Spaces:
Sleeping
Sleeping
| # CLAUDE.md | |
| This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. | |
| ## Project Overview | |
| This is a Docker-based Model Context Protocol (MCP) server designed for deployment on Hugging Face Spaces. The project implements a custom MCP server with HTTP wrapper functionality and includes both FastAPI applications and MCP protocol handlers. | |
| ## Architecture | |
| ### Core Components | |
| - **mcp_server.py**: Core MCP server implementation with JSON-RPC 2.0 protocol handling | |
| - Implements MCP protocol methods (initialize, tools/list, tools/call, resources/list, resources/read) | |
| - Includes sample tools (echo, current_time, calculate, word_count, reverse_text) | |
| - Contains decorator-based tool and resource registration system | |
| - **http_wrapper.py**: FastAPI HTTP wrapper that exposes MCP server over HTTP (main entry point) | |
| - Converts HTTP requests to MCP protocol calls | |
| - Provides web interface and API documentation | |
| - Health check endpoint at `/health` | |
| - **proxy_script.py**: Local proxy for connecting Claude Desktop to remote HTTP MCP server | |
| - Bridges stdio-based MCP protocol to HTTP endpoints | |
| - Configured for Hugging Face Spaces deployment | |
| - **app.py**: Alternative FastAPI app with HuggingFace transformers integration (T5 model) | |
| - **main.py**: Simple hello world script | |
| ## Development Commands | |
| ### Running Locally | |
| ```bash | |
| # Install dependencies | |
| pip install -r requirements.txt | |
| # Run the main HTTP server (recommended) | |
| python3 http_wrapper.py | |
| # Run MCP server in stdio mode | |
| python3 mcp_server.py | |
| # Run alternative app with transformers | |
| python3 app.py | |
| ``` | |
| ### Docker Deployment | |
| ```bash | |
| # Build container | |
| docker build -t mcp-server . | |
| # Run container | |
| docker run -p 7860:7860 mcp-server | |
| ``` | |
| ### Testing | |
| - Health check: `curl http://localhost:7860/health` | |
| - List tools: `curl http://localhost:7860/tools` | |
| - API docs available at: `http://localhost:7860/docs` | |
| ## Key Technical Details | |
| ### MCP Protocol Implementation | |
| - Uses JSON-RPC 2.0 for all communications | |
| - Protocol version: 2024-11-05 | |
| - Supports both stdio and HTTP transport modes | |
| ### Tool Registration | |
| Tools are registered using the `@server.tool()` decorator with: | |
| - Name and description | |
| - Parameter schema definitions | |
| - Async function implementations | |
| ### Resource System | |
| Resources use the `@server.resource()` decorator for URI-based content access. | |
| ### Deployment Environment | |
| - Designed for Hugging Face Spaces with Docker SDK | |
| - Default port: 7860 | |
| - Health checks configured for container orchestration | |
| - Non-root user execution for security | |
| ## Container Configuration | |
| - Base image: python:3.11-slim | |
| - Exposed port: 7860 | |
| - Entry point: `http_wrapper.py` | |
| - Health check endpoint: `/health` | |
| - Working directory: `/app` |