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](https://console.cloud.google.com/)

## Deployment Steps

### 1. Create a New Space
1. Go to [Hugging Face Spaces](https://huggingface.co/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)**
```bash
# 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**
   ```bash
   curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health
   ```

2. **Service Info**
   ```bash
   curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/
   ```

3. **List Tools**
   ```bash
   curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/tools
   ```

4. **Search YouTube Videos**
   ```bash
   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:

```bash
# 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:
```bash
# 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](https://huggingface.co/docs/hub/spaces)
- [Docker Documentation](https://docs.docker.com/)
- [YouTube Data API Documentation](https://developers.google.com/youtube/v3)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)