DEPLOYMENT.md

Deployment Guide for Hugging Face Spaces

Overview

This guide explains how to deploy the Basicsearch MCP server to Hugging Face Spaces using Docker.

Prerequisites

1. A Hugging Face account
2. A YouTube Data API v3 key from Google Cloud Console

Deployment Steps

1. Create a New Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Choose a name for your space
4. Select "Docker" as the SDK
5. Click "Create Space"

2. Upload Your Code

You can either:

Option A: Use Git (Recommended)

# Clone your space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy files from this directory
cp /path/to/basicsearch/* .

# Commit and push
git add .
git commit -m "Initial deployment"
git push

Option B: Upload via Web Interface

• Upload the following files:
  • Dockerfile
  • app.py
  • server.py
  • pyproject.toml
  • uv.lock
  • README.md

3. Configure Environment Variables

1. Go to your Space settings
2. Navigate to "Repository secrets"
3. Add a new secret:
   • Name: YOUTUBE_API_KEY
   • Value: Your YouTube API key

4. Wait for Build

• Hugging Face will automatically detect the Dockerfile and build your container
• This may take a few minutes
• You can monitor the build logs in the "Settings" → "Logs" section

Testing Your Deployment

Once deployed, your Space will be available at:

https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

Available Endpoints

1. Health Check

   curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health
   

2. Service Info

   curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/
   

3. List Tools

   curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/tools
   

4. Search YouTube Videos

   curl -X POST https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/search \
     -H "Content-Type: application/json" \
     -d '{"query": "Python tutorial", "max_results": 5}'
   

Architecture

Components

1. server.py: Core MCP server with YouTube search functionality
2. app.py: FastAPI HTTP wrapper for web deployment
3. Dockerfile: Container definition for deployment

Port Configuration

• The server runs on port 7860 (Hugging Face Spaces default)
• This is configured via the PORT environment variable

Troubleshooting

Build Fails

• Check the build logs in Settings → Logs
• Ensure all files are uploaded correctly
• Verify the Dockerfile syntax

API Key Issues

• Ensure YOUTUBE_API_KEY is set in Repository secrets
• The key must have YouTube Data API v3 enabled
• Check quota limits in Google Cloud Console

Connection Issues

• Spaces may take a few minutes to start after deployment
• Check if the Space is in "Running" state
• Review application logs for errors

Local Testing

Before deploying, test locally:

# Build the Docker image
docker build -t basicsearch-mcp .

# Run the container
docker run -p 7860:7860 -e YOUTUBE_API_KEY=your_key_here basicsearch-mcp

# Test the endpoint
curl http://localhost:7860/health

Monitoring

Health Checks

The Docker container includes automatic health checks that run every 30 seconds.

Logs

View logs in your Space's Settings → Logs section to monitor:

• API requests
• Error messages
• Performance metrics

Updating Your Deployment

To update your Space:

# Make your changes locally
# Commit and push
git add .
git commit -m "Update description"
git push

Hugging Face will automatically rebuild and redeploy your Space.

Cost Considerations

• Hugging Face Spaces offers free tier for public spaces
• YouTube Data API has daily quota limits (10,000 units/day by default)
• Each search request costs approximately 100 units

Security Best Practices

1. Never commit API keys to your repository
2. Use Hugging Face Repository secrets for sensitive data
3. Consider implementing rate limiting in production
4. Monitor API usage in Google Cloud Console

Additional Resources

• Hugging Face Spaces Documentation
• Docker Documentation
• YouTube Data API Documentation
• FastMCP Documentation