MCP_DEPLOYMENT_GUIDE.md

# MCP Deployment Guide for Hugging Face Spaces

## What We Built

Your Thumbnail Crafter Space is now MCP-compatible! It can be called as a tool by AI assistants like HuggingChat.

### Files Created

1. **`main.py`** - FastAPI server with MCP `/tools` endpoint
2. **`tools.json`** - Tool schema for HuggingChat discovery
3. **`requirements.txt`** - Python dependencies
4. **`Dockerfile`** - Container configuration for Hugging Face Spaces
5. **`README.md`** - Updated documentation

## Deployment Steps

### 1. Push to Hugging Face

```bash
# Make sure you're in your project directory
cd "C:\HuggingFace\Huggy thumbnail crafter"

# Add all new files
git add main.py tools.json requirements.txt Dockerfile README.md

# Commit the changes
git commit -m "feat: Add MCP compatibility for HuggingChat integration

- Add FastAPI backend with /tools endpoint
- Implement generate_thumbnail and get_available_layouts tools
- Add Docker support for hybrid React + Python deployment
- Update README with MCP usage instructions"

# Push to Hugging Face
git push
```

### 2. Wait for Space to Rebuild

Once you push, Hugging Face will automatically:
1. Detect the `Dockerfile`
2. Build the Docker image
3. Deploy your Space with both React frontend + Python backend

This may take 5-10 minutes.

### 3. Test the MCP Endpoint

Once deployed, test that the MCP endpoint works:

```bash
# Replace with your Space URL
curl -X POST https://huggingface.co/spaces/Chunte/Thumbnail-Crafter.mini/tools \\
  -H "Content-Type: application/json" \\
  -d '{"name":"get_available_layouts","arguments":{}}'
```

You should see a streaming JSON response:
```json
{"output": true, "data": {"success": true, "layouts": [...]}}
{"output": false}
```

### 4. Register in HuggingChat

#### Option A: Automatic Discovery (if supported)
HuggingChat should automatically discover your Space's `tools.json` file.

#### Option B: Manual Registration
1. Go to [HuggingChat](https://huggingface.co/chat/)
2. Click Settings → MCP Servers
3. Click "Add Server"
4. Enter your Space URL: `https://huggingface.co/spaces/Chunte/Thumbnail-Crafter.mini`
5. Enable the server

### 5. Use in HuggingChat

Once registered, you can ask HuggingChat:

```
Generate a thumbnail for my new model "BERT-FineTuned"
with a red background and white text
```

HuggingChat will:
1. Recognize it needs to generate a thumbnail
2. Call your Space's `generate_thumbnail` tool
3. Return the generated image

## Available Tools

### 1. generate_thumbnail

Generates a custom thumbnail image.

**Parameters:**
- `title` (string, required): Main text to display
- `layout` (string): Layout type - "impactTitle", "hfLogo", or "custom" (default: "impactTitle")
- `bg_color` (string): Background color hex (default: "#1a1a1a")
- `text_color` (string): Text color hex (default: "#ffffff")
- `width` (integer): Canvas width (default: 1280)
- `height` (integer): Canvas height (default: 720)

**Returns:**
- Base64-encoded PNG image
- Metadata (width, height, size, etc.)

**Example:**
```json
{
  "name": "generate_thumbnail",
  "arguments": {
    "title": "My AI Model",
    "layout": "impactTitle",
    "bg_color": "#FF6B6B",
    "text_color": "#FFFFFF"
  }
}
```

### 2. get_available_layouts

Returns list of available layout templates.

**Parameters:** None

**Returns:**
- Array of layout objects with id, name, and description

## Local Testing

### Start the Server Locally

```bash
# Install dependencies
pip install -r requirements.txt

# Run the server
python main.py
```

Server will run at `http://localhost:7860`

### Test with Python

```python
import requests
import json

response = requests.post(
    "http://localhost:7860/tools",
    json={
        "name": "get_available_layouts",
        "arguments": {}
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        print(json.loads(line.decode('utf-8')))
```

### Test with curl

```bash
curl -X POST http://localhost:7860/tools \\
  -H "Content-Type: application/json" \\
  -d '{"name":"get_available_layouts","arguments":{}}'
```

## Endpoints

- **`/`** - React frontend (when deployed)
- **`/tools`** - MCP endpoint for HuggingChat
- **`/tools.json`** - Tool schema definition
- **`/api/info`** - API information
- **`/health`** - Health check

## Troubleshooting

### Space Build Fails

**Check Docker logs** in your Space's "Build" tab

Common issues:
- Missing files in git (make sure all files are pushed)
- Invalid Dockerfile syntax
- Missing Python dependencies

### MCP Endpoint Returns Error

1. Check `/health` endpoint is responding
2. Verify `tools.json` is accessible
3. Check server logs in Space settings

### HuggingChat Can't Find Tools

1. Verify `tools.json` is in the root directory
2. Check that `/tools` endpoint returns `200 OK`
3. Try manual registration in HuggingChat settings

### Image Generation Fails

**Font not found:** The server tries multiple font paths. If all fail, it uses a default font.

To add custom fonts, modify the Dockerfile:
```dockerfile
RUN apt-get install -y fonts-liberation
COPY path/to/your/font.ttf /usr/share/fonts/truetype/
```

## Architecture

```
┌─────────────────────────────────────┐
│ Hugging Face Space                  │
│                                     │
│  ┌─────────────────────────────┐   │
│  │ FastAPI Backend (port 7860) │   │
│  │                             │   │
│  │  • /tools (MCP endpoint)    │   │
│  │  • /api/info                │   │
│  │  • / (serves React app)     │   │
│  └─────────────────────────────┘   │
│                                     │
│  ┌─────────────────────────────┐   │
│  │ React Frontend (static)     │   │
│  │ Built files in /static      │   │
│  └─────────────────────────────┘   │
└─────────────────────────────────────┘
           ↑
           │ HTTP/HTTPS
           │
    ┌──────┴──────┐
    │ HuggingChat │
    │ (AI Client) │
    └─────────────┘
```

## Next Steps

1. **Deploy to Hugging Face** - Push your changes
2. **Test the endpoint** - Verify `/tools` works
3. **Register in HuggingChat** - Add your Space as an MCP server
4. **Try it out** - Ask HuggingChat to generate thumbnails!

## Support

- [Model Context Protocol Docs](https://modelcontextprotocol.io/)
- [Hugging Face Spaces Docs](https://huggingface.co/docs/hub/spaces)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)

---

**Built with Claude Code** 🤖