Hugging Face's logo

Spaces:
LeoWalker
/
foodwise-remote-mcp
Running

App Files Community
foodwise-remote-mcp / planning /archive /remote_mcp.md
LeoWalker's picture
LeoWalker
chore(project): clean up project files and organize planning docs
8d62a8a
preview code
|
raw
history blame contribute delete
14.2 kB

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:

# ✅ Already on remote-mcp branch
# ✅ Using Python 3.12.8 with uv
# ✅ Project structure ready

Implementation Tasks:

  • Create Dockerfile for HuggingFace Spaces (Python 3.12 + uv)
  • Create main.py entry point (HTTP MCP on 7860)
  • Create HuggingFace Space with Docker SDK
  • Configure environment variables (NOTION_SECRET, NOTION_INVENTORY_DB_ID, optional NOTION_SHOPPING_DB_ID)
  • Remote health and CORS validation for https://claude.ai
  • 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) 

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

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 

# 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 

# .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) 

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

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

# 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 

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