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

# 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:

# 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:

{"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
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:

{
  "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

# Install dependencies
pip install -r requirements.txt

# Run the server
python main.py

Server will run at http://localhost:7860

Test with 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

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:

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
• Hugging Face Spaces Docs
• FastAPI Documentation

---

Built with Claude Code 🤖