Hugging Face's logo

Spaces:
Chunte
/
Thumbnail-Crafter.mini.mcp_experiment
Running

App Files Community
Thumbnail-Crafter.mini.mcp_experiment / SMART_COLLABORATION_GUIDE.md
ChunDe's picture
ChunDe
feat: Add MCP compatibility with smart collaboration thumbnails
65493c3
preview code
|
raw
history blame contribute delete
11 kB

Smart Collaboration Thumbnail Generator 🤖🎨

What Is This?

Your Thumbnail Crafter Space now has AI-powered logo fetching! When you ask HuggingChat to create a collaboration thumbnail, it will:

  1. Search the web for the partner company's logo
  2. Download and process the logo automatically
  3. Load your Space with the appropriate layout
  4. Inject the logo into the placeholder
  5. Export the final thumbnail and return it

Example Use Cases

In HuggingChat 

You: "Create a collaboration thumbnail for Hugging Face and Nvidia
      using the Serious Collab layout with a white background"

HuggingChat calls your Space →
  📡 Searches web for "Nvidia logo PNG"
  ⬇️  Downloads the logo
  🎨 Loads Serious Collab layout
  🖼️  Replaces placeholder with Nvidia logo
  📤 Returns completed thumbnail

You receive: A professional thumbnail ready to use!

More Examples 

"Generate a Fun Collab thumbnail for Hugging Face and OpenAI"

"Create an Academia Hub collab thumbnail for Hugging Face and Stanford"

"Make a collaboration thumbnail for Hugging Face and Google
 with a light blue background"

How It Works

The Complete Workflow 

┌─────────────────────────────────────────────────┐
│ 1. HuggingChat                                  │
│    User asks for collaboration thumbnail        │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 2. Your MCP Server (Python)                     │
│    • Parses request                             │
│    • Searches DuckDuckGo for company logo       │
│    • Downloads and processes logo image         │
│    • Resizes, adds transparency                 │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 3. Playwright Browser Automation                │
│    • Launches headless Chrome                   │
│    • Opens your React app                       │
│    • Waits for window.thumbnailAPI              │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 4. Your React App (window.thumbnailAPI)        │
│    • thumbnailAPI.loadLayout('seriousCollab')  │
│    • thumbnailAPI.setBgColor('#ffffff')         │
│    • thumbnailAPI.replaceLogoPlaceholder(...)  │
│    • thumbnailAPI.exportCanvas()                │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│ 5. Return to HuggingChat                        │
│    Base64-encoded PNG thumbnail                 │
└─────────────────────────────────────────────────┘

Available Tools

1. generate_collab_thumbnail

Generate a collaboration thumbnail with automatic logo fetching.

Parameters:

  • partner_name (required): Company name (e.g., "Nvidia", "Google", "Microsoft")
  • layout (optional): Layout ID - "seriousCollab" (default), "funCollab", "academiaHub", "sandwich", "impactTitle"
  • partner_logo_url (optional): Direct logo URL if you have one
  • title (optional): Custom title text
  • bg_color (optional): Background color hex (default: "#ffffff")
  • canvas_size (optional): "default" (1200x675), "linkedin" (1200x627), "hf" (1160x580)

Example Request:

{
  "name": "generate_collab_thumbnail",
  "arguments": {
    "partner_name": "Nvidia",
    "layout": "seriousCollab",
    "bg_color": "#f0f0f0"
  }
}

Returns:

{
  "success": true,
  "image": "data:image/png;base64,...",
  "width": 1200,
  "height": 675,
  "partner_name": "Nvidia",
  "layout_used": "seriousCollab",
  "logo_fetched": true
}

2. search_logo

Just search for a logo without generating a thumbnail.

Parameters:

  • company_name (required): Company to search for

Example:

{
  "name": "search_logo",
  "arguments": {
    "company_name": "OpenAI"
  }
}

3. get_available_layouts

List all available collaboration layouts.

window.thumbnailAPI Reference

Your React app now exposes a programmatic API for browser automation:

window.thumbnailAPI = {
  // Load a layout by ID
  loadLayout(layoutId: string): boolean

  // Set background color
  setBgColor(color: string): boolean

  // Replace logo placeholder with new image
  replaceLogoPlaceholder(imageDataUri: string): boolean

  // Add image at specific position
  addImage(dataUri: string, x: number, y: number, w?: number, h?: number): boolean

  // Update text content
  updateText(identifier: string, newText: string): boolean

  // Set canvas size
  setCanvasSize(size: 'default' | 'linkedin' | 'hf'): boolean

  // Export canvas as data URL
  exportCanvas(): Promise<string>

  // Get current state
  getInfo(): object
}

You can also use this API manually in the browser console for testing:

// Open your Space in browser
// Open DevTools Console (F12)

// Load a layout
window.thumbnailAPI.loadLayout('seriousCollab')

// Set background
window.thumbnailAPI.setBgColor('#e3f2fd')

// Replace logo with any data URI
window.thumbnailAPI.replaceLogoPlaceholder('data:image/png;base64,...')

// Export
const dataUrl = await window.thumbnailAPI.exportCanvas()

Deployment Steps

1. Build Your React App 

npm run build

This creates the dist/ folder with your production frontend.

2. Choose Which MCP Server to Use

Option A: Smart Server (Recommended)

# Rename to use the smart server
mv mcp_server_smart.py main.py

Option B: Keep Both Keep both files and update Dockerfile to use mcp_server_smart.py

3. Update Dockerfile 

# Copy the smart MCP server
COPY mcp_server_smart.py main.py
# OR
COPY mcp_server_smart.py .

# Update CMD
CMD ["uvicorn", "mcp_server_smart:app", "--host", "0.0.0.0", "--port", "7860"]

4. Install Playwright Browsers in Dockerfile

Add to your Dockerfile:

# After installing Python packages
RUN playwright install chromium
RUN playwright install-deps chromium

5. Deploy to Hugging Face 

git add -A
git commit -m "feat: Add smart collaboration thumbnail generation with logo fetching"
git push

6. Wait for Build

Hugging Face will build your Docker container (~10-15 minutes).

7. Test the Endpoint 

curl -X POST https://huggingface.co/spaces/YOUR-USERNAME/Thumbnail-Crafter.mini/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "generate_collab_thumbnail",
    "arguments": {
      "partner_name": "Nvidia",
      "layout": "seriousCollab"
    }
  }'

8. Register in HuggingChat

  1. Go to HuggingChat → Settings → MCP Servers
  2. Add your Space URL
  3. Enable it

9. Use It! 

User in HuggingChat:
"Create a collab thumbnail for Hugging Face and Nvidia"

HuggingChat:
*generates thumbnail automatically*
Here's your collaboration thumbnail! [shows image]

Local Testing

Test the Smart Server Locally 

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install chromium

# Start your React app (in one terminal)
npm run dev

# Start the MCP server (in another terminal)
python mcp_server_smart.py

Test Logo Fetching 

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

Test Full Workflow 

curl -X POST http://localhost:7860/tools \
  -H "Content-Type: application/json" \
  -d '{
    "name": "generate_collab_thumbnail",
    "arguments": {
      "partner_name": "Microsoft",
      "layout": "seriousCollab",
      "bg_color": "#ffffff"
    }
  }'

Troubleshooting

Logo Not Found

Problem: Can't find logo for company X

Solutions:

  1. Try a more specific name: "Microsoft Corporation" instead of "MS"
  2. Provide direct logo URL: partner_logo_url: "https://..."
  3. Use a well-known variant: "Meta" instead of "Facebook"

Logo Not Replacing Placeholder

Problem: Logo fetched but not showing in thumbnail

Solutions:

  1. Check layout has a logo placeholder: seriousCollab, funCollab, academiaHub do
  2. Check browser console logs for errors
  3. Verify window.thumbnailAPI is loaded

Browser Automation Fails

Problem: Playwright can't open the app

Solutions:

  1. Ensure React app is running at APP_URL
  2. Check Playwright is installed: playwright install chromium
  3. Check firewall/network issues
  4. Try increasing timeouts in Python code

Image Quality Issues

Problem: Logo looks pixelated or wrong size

Solutions:

  1. Adjust target_size in process_logo_image()
  2. Search for higher resolution: add "high resolution" to search query
  3. Provide direct URL to vector/high-res logo

Performance Considerations

  • Logo Fetching: 2-5 seconds
  • Browser Launch: 1-3 seconds
  • Layout Rendering: 1-2 seconds
  • Export: 0.5-1 second

Total Time: ~5-10 seconds per thumbnail

To improve:

  • Keep browser instance warm (already implemented)
  • Cache fetched logos (TODO)
  • Pre-download common logos (TODO)

Security & Privacy

  • Logos are fetched from public web sources (DuckDuckGo Images)
  • No API keys required for image search
  • All processing happens server-side
  • No user data is stored
  • Respects robots.txt and rate limits

Future Enhancements

  • Cache frequently used logos
  • Support for multiple logos (three-way collabs)
  • Custom logo positioning
  • Batch generation
  • Video thumbnail generation
  • Real-time preview in HuggingChat

Built with Claude Code 🤖

Questions? Check the main MCP_DEPLOYMENT_GUIDE.md