planning/archive/remote_mcp.md

# Remote MCP Server Implementation Plan 🌐

## 🎯 Project Overview

Transform FoodWise from a local MCP server into a cloud-hosted, accessible-anywhere inventory management system using HuggingFace Spaces. This approach focuses on simplicity and educational value for developers learning MCP patterns.

**Key Benefits (current):**
- Remote access to inventory management from anywhere
- Free hosting with Docker support
- Keep existing Python FastMCP code
- Educational example for the MCP community

## 🏗️ Architecture Vision

### Current State (Local MCP)
```
Claude Desktop ↔ Local FastMCP Server ↔ Notion API
```

### Target State (HuggingFace Spaces)
```
Claude Desktop (via supergateway) / Any configurable MCP client ↔ HF Spaces (HTTP MCP) ↔ Notion API
                                                              ↗ Environment Variables
```

**Why This Is Better:**
- ✅ **Simple**: No complex gateway or infrastructure
- ✅ **Educational**: Clear, single-container deployment
- ✅ **Free**: HuggingFace Spaces hosting
- ✅ **Proven**: FastAPI + Docker examples exist

## 🔧 Technical Components

### 1. HuggingFace Spaces Docker Container
- **Existing FastMCP Server**: Keep all your current Python code
- **Docker Deployment**: Simple `Dockerfile` + `pyproject.toml` (uv)
- **Port 7860**: HuggingFace Spaces standard port
- **Environment Variables**: Secrets management for `NOTION_SECRET`, `NOTION_INVENTORY_DB_ID`, optional `NOTION_SHOPPING_DB_ID`

### 2. Access Model
- Current: OAuth disabled (`hf_oauth: false`) to allow public Streamable HTTP MCP at `/mcp/`
- Optional later: Enable OAuth if you need gated access

### 3. Deployment Simplicity
- **Single Platform**: Only HuggingFace Spaces (no multiple options)
- **Git-based**: Push to deploy, just like local development
- **Free Hosting**: Perfect for educational and personal use
- **Community Visibility**: Others can see and learn from your MCP server

### 4. Educational Value
- **Clear Example**: Simple Docker + FastMCP pattern
- **Minimal Complexity**: Focus on MCP concepts, not infrastructure
- **Open Source**: Visible implementation for community learning
- **Reproducible**: Easy for others to fork and adapt

## 📋 Implementation Phases

### Phase 1: HuggingFace Spaces Deployment (MVP)
**Goal (done)**: Deploy existing FastMCP server to HuggingFace Spaces with public HTTP MCP

**Branch Workflow:**
```bash
# ✅ Already on remote-mcp branch
# ✅ Using Python 3.12.8 with uv
# ✅ Project structure ready
```

**Implementation Tasks:**
- [x] Create Dockerfile for HuggingFace Spaces (Python 3.12 + uv)
- [x] Create `main.py` entry point (HTTP MCP on 7860)
- [x] Create HuggingFace Space with Docker SDK
- [x] Configure environment variables (`NOTION_SECRET`, `NOTION_INVENTORY_DB_ID`, optional `NOTION_SHOPPING_DB_ID`)
- [x] Remote health and CORS validation for `https://claude.ai`
- [x] Test with MCP Inspector (remote)
- [ ] Add `.env.example` to Space repo
- [ ] Add simple smoke test instructions for Space logs

**Success Criteria:**
- ✅ HuggingFace Space builds and runs successfully
- ✅ MCP Inspector works against `/mcp/`
- ✅ Claude Desktop connects via Streamable HTTP using `supergateway`
- ⚠️ Note: Claude Web does not currently allow user-defined connectors; use Desktop or other configurable MCP clients
- ✅ All inventory + shopping tools function remotely

**Educational Value:**
- Simple Docker + FastMCP deployment pattern
- Clear authentication flow with built-in OAuth
- Minimal infrastructure complexity
- Open source example for community

### Phase 2: Community & Polish (Optional)
**Goal**: Make the MCP server a great learning resource

**Tasks:**
- [ ] Add comprehensive README with setup instructions
- [ ] Document the MCP tool implementations
- [ ] Create video tutorial for deployment process
- [ ] Write blog post about remote MCP patterns
- [ ] Add monitoring and health checks

**Success Criteria:**
- ✅ Other developers can easily replicate the setup
- ✅ Clear documentation of MCP patterns used
- ✅ Stable, production-ready deployment
- ✅ Community adoption and contributions

## 🛠️ Development Setup

### HuggingFace Space Configuration (current)
```yaml
# README.md metadata
---
title: FoodWise Remote MCP
emoji: 🥗
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
hf_oauth: false
---
```

### Recommended Project Structure
```
foodwise-remote-mcp/
├── .env.example          # Template for environment variables (commit)
├── .env                  # Local development environment (gitignore)
├── .gitignore           # Include .env, exclude .env.example
├── pyproject.toml       # Dependencies and project config
├── uv.lock             # Locked dependency versions
├── README.md           # HuggingFace Space configuration
├── Dockerfile          # Container setup using uv
├── main.py             # FastMCP server entry point
└── src/
    └── foodwise/
        └── mcp_server/  # Your existing FastMCP code
```

### Sample Dockerfile (Educational Example)
```dockerfile
FROM python:3.12

# Install uv for fast Python package management
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/

# HuggingFace Spaces requires user with ID 1000
RUN useradd -m -u 1000 user
USER user

# Environment setup
ENV HOME=/home/user \
    PATH=/home/user/.local/bin:$PATH \
    PYTHONPATH=/home/user/app

WORKDIR $HOME/app

# Copy Python project configuration
COPY --chown=user pyproject.toml uv.lock* ./

# Install dependencies using uv (much faster than pip)
RUN uv sync --frozen --no-cache

# Copy FastMCP server code and environment config
COPY --chown=user . .

# Expose HuggingFace Spaces port
EXPOSE 7860

# Start FastMCP server using uv run
CMD ["uv", "run", "python", "main.py"]
```

### Local Development & Testing
```bash
# Set up development environment with uv
uv sync

# Create .env file for local development
cp .env.example .env
# Edit .env with your NOTION_SECRET / IDs and other variables

# Run locally for development (HTTP MCP on port 7860)
uv run python main.py

# Test Docker container locally with .env file
docker build -t foodwise-mcp-test .
docker run -p 7860:7860 --env-file .env foodwise-mcp-test

# Test MCP connection (option A): MCP Inspector against HTTP endpoint
mcp-inspector http://localhost:7860/mcp/

# Test MCP connection (option B): Bridge Claude Desktop via supergateway
npx supergateway --streamableHttp "http://localhost:7860/mcp/" --logLevel debug
```

### Environment Configuration
```bash
# .env.example (commit to repo)
NOTION_SECRET=your_notion_integration_token_here
NOTION_INVENTORY_DB_ID=...
# Optional if using shopping features
NOTION_SHOPPING_DB_ID=...
ENVIRONMENT=development
LOG_LEVEL=DEBUG

# .env (local only, add to .gitignore)
NOTION_SECRET=sk-actual-token-here
NOTION_INVENTORY_DB_ID=...
NOTION_SHOPPING_DB_ID=...
ENVIRONMENT=development
LOG_LEVEL=DEBUG
```

## 🔐 Security Considerations

### Access Summary (current)
1. Public Streamable HTTP MCP endpoint at `/mcp/`
2. Environment secrets: `NOTION_SECRET` and database IDs set in Space settings
3. Optional: enable OAuth later if gated access is needed

### Built-in Security Benefits
- **HTTPS by Default**: HuggingFace Spaces use HTTPS automatically
- **No Custom Auth**: Leverage HF's proven authentication system
- **Environment Variables**: Secure secret management via HF Spaces settings
- **Container Isolation**: Docker provides process isolation

### Development Security Practices
- **Local Development**: Use `.env` files (never commit actual secrets)
- **Production**: Store secrets in HuggingFace Spaces environment variables
- **Dependency Management**: Keep `uv.lock` updated for reproducible builds  
- **Environment Separation**: Use different `.env` files for dev/staging/production
- **Monitor Access**: Review Space logs for unusual activity

### Token Proxy Mode
- When `MCP_AUTH_TOKEN` is set:
  - MCP upstream runs on `127.0.0.1:7870`
  - Proxy serves `/mcp/` on public `PORT` (7860)
- Prefer header auth; `?key=` is available for Desktop bridge compatibility

## 📊 Simple Monitoring

### HuggingFace Spaces Built-in Features
- **Container Logs**: Available in Space settings
- **Build Logs**: Visible during deployment
- **Usage Stats**: Basic metrics provided by HF
- **Health Status**: Automatic container health monitoring

### Optional Enhancements
- Add simple health check endpoint (`/health`)
- Log MCP tool usage for debugging
- Monitor Notion API rate limits
- Add basic error handling and logging

## 🚀 Simple Deployment Strategy

### Git-Based Deployment (HuggingFace Spaces)
1. **Create Space**: Docker-based HuggingFace Space
2. **Environment Setup**: Configure secrets in Space settings
3. **Push Code**: Git push to Space repo triggers build and deploy
4. **Test & Iterate**: Validate via MCP Inspector and Claude

### Deployment Steps (keeping Space as separate repo or pushing from main)
```bash
# Option A) Push directly from the main repo (recommended)
# In /Users/leowalker/Documents/Projects/FoodWise
git remote add hf https://huggingface.co/spaces/LeoWalker/foodwise-remote-mcp
git push hf main:main

# Option B) (Deprecated) Using a separate Space clone directory
# If you previously used a dedicated clone, you can now push directly from the main repo.
git add . && git commit -m "Sync with main"
git push origin main

# 2. Set up project structure
uv init --no-readme  # If starting fresh, or use existing project
uv add fastapi uvicorn python-dotenv mcp
uv add your-existing-dependencies

# 3) Configure environment (Space settings → Secrets)
# - NOTION_SECRET: your_actual_token
# - NOTION_INVENTORY_DB_ID: your_inventory_db
# - (optional) NOTION_SHOPPING_DB_ID: your_shopping_db

# 4) Restart Space after pushing to trigger rebuild

# 5. Monitor deployment
# Check Space logs for build status and container health
```

### Simple Rollback
- **Git Revert**: Revert the last push to the Space repo
- **Space Restart**: Use the Space restart/factory reset if needed
- **Environment Rollback**: Revert environment variable changes in Space settings

## Connector References

### Claude Desktop (local bridge)
```json
{
  "mcpServers": {
    "foodwise-remote": {
      "command": "npx",
      "args": ["supergateway", "--streamableHttp", "https://leowalker-foodwise-remote-mcp.hf.space/mcp/?key=$MCP_AUTH_TOKEN"]
    }
  }
}
```

### Claude Web
- Not currently user-configurable for custom MCP connectors. Use Claude Desktop with `supergateway` or other MCP clients that allow configuring an HTTP endpoint.

## 💡 Potential Future Enhancements

### Educational Extensions
- **Multiple MCP Tools**: Add more inventory management tools
- **Error Handling**: Demonstrate robust error handling patterns
- **Caching**: Show how to cache Notion API responses
- **Testing**: Add comprehensive test suite for MCP tools
- **Documentation**: Create detailed MCP development guides

### Community Features
- **Fork-Friendly**: Make it easy for others to customize
- **Tutorial Series**: Step-by-step guides for each component
- **Video Walkthroughs**: Screen recordings of the deployment process
- **Discussion Forum**: HuggingFace Community tab for questions
- **Templates**: Reusable templates for other MCP servers

### Advanced MCP Patterns (Optional)
- **Resource Streaming**: Demonstrate MCP resource capabilities
- **Prompt Templates**: Show MCP prompt management
- **Tool Composition**: Chain multiple MCP tools together
- **State Management**: Handle stateful MCP interactions

## 📝 Educational Success Metrics

### Learning & Community Impact
- **Community Adoption**: Others fork and adapt the example
- **Documentation Quality**: Clear, comprehensive setup guides
- **Tutorial Engagement**: High completion rates for tutorials
- **Support Quality**: Helpful responses in community discussions

### Technical Excellence
- **Reliability**: Consistent uptime for demonstration purposes
- **Simplicity**: Easy to understand and replicate
- **Best Practices**: Demonstrates MCP development patterns
- **Performance**: Responsive for typical demo usage

## 🎉 Getting Started

Ready to begin? Here's the simplified path:

### Quick Start Checklist

#### Pre-Development Setup ✅
1. **✅ Branch**: Already on `remote-mcp` branch
2. **✅ Python**: Using Python 3.12.8 with uv
3. **✅ Project Structure**: Existing FastMCP server ready

#### Implementation Steps  
1. **🔧 Prepare Files**: Create .env.example, Dockerfile, main.py
2. **🧪 Test Locally**: Claude Desktop + MCP Inspector validation
3. **🚀 Deploy**: Create HuggingFace Space with OAuth  
4. **✅ Validate**: Test remote deployment end-to-end

#### Testing Workflow
```bash
# Phase 1: Local testing (before any commits)
uv run python main.py  # Start local server
# Test Claude Desktop connection → localhost:7860
# Test MCP Inspector → localhost:7860

# Phase 2: Commit and deploy  
git add . && git commit -m "Add HuggingFace Spaces deployment"

# Phase 3: Remote testing (after deployment)
# Test Claude Desktop → https://your-space.hf.space  
# Test MCP Inspector → https://your-space.hf.space
```

### Next Steps (Ready to Execute!)
- **Phase 1**: Create deployment files and test locally
- **Phase 2**: Deploy to HuggingFace Spaces 
- **Phase 3**: Validate with Claude Desktop and MCP Inspector
- **Phase 4**: Document and share as educational example

### MCP Inspector Integration
```bash
# Install MCP Inspector (if not already installed)
npm install -g @mcp/inspector

# Test local server
mcp-inspector http://localhost:7860

# Test remote server after deployment  
mcp-inspector https://your-space.hf.space
```

**MCP Inspector Benefits:**
- Interactive tool testing without Claude Desktop
- Debug tool parameters and responses
- Validate all MCP tools work correctly  
- Great for development and troubleshooting

*This plan is now ready for execution with proper branch workflow and comprehensive testing!*

---

*This simplified plan transforms FoodWise into an accessible, educational example of remote MCP server deployment using HuggingFace Spaces. Perfect for developers learning MCP patterns!*