CLAUDE.md

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

# 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

# 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