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