simple-mcp-server

# Simple MCP Server A simple Model Context Protocol (MCP) server built with FastMCP, featuring three utility tools. ## Tools 1. **generate_uuid** - Generates a random UUID (version 4 or 1) 2. **convert_temperature** - Converts temperature between Celsius and Fahrenheit 3. **text_statistics** - Calculates basic text statistics (characters, words, lines) ## Installation Install dependencies using uv: ```bash uv sync ``` ## Usage ### Running the Server Start the MCP server with HTTP transport: ```bash uv run server.py ``` The server will start on `http://localhost:8000/mcp` by default. ### Testing with FastMCP Client Run the FastMCP-based client: ```bash uv run client_fastmcp.py ``` ### Testing with httpx Client Run the pure httpx client (no MCP libraries required): ```bash uv run client_httpx.py ``` ### Testing with curl Client Run the bash script using only curl and jq: ```bash ./client_curl.sh ``` **Requirements for curl client:** - `curl` (for HTTP requests) - `jq` (for JSON parsing) - Standard Unix tools (`grep`, `sed`, `awk`, `tr`) ## Project Structure - `server.py` - MCP server with three utility tools - `client_fastmcp.py` - Client using FastMCP library - `client_httpx.py` - Client using only httpx for direct HTTP requests - `client_curl.sh` - Bash script client using curl and jq - `main.py` - Original template file (not used) ## Example Output All three clients will: 1. Connect to the server 2. List available tools 3. Test generate_uuid (generates a UUID v4) 4. Test convert_temperature (converts 0°C to Fahrenheit → 32.0°F) 5. Test text_statistics (counts characters, words, and lines in sample text) Example: ``` Test 1: Generate UUID Result: 98f99e94-7357-4dd4-85eb-76819fad3ada Test 2: Convert temperature (0°C to Fahrenheit) Result: 32.0 Test 3: Text statistics Result: {"characters":47,"words":9,"lines":3} ``` ## Technical Details - **Transport**: Streamable HTTP (MCP protocol over HTTP) - **Endpoint**: `/mcp` - **Response Format**: Server-Sent Events (SSE) - **Session Management**: Server assigns session ID via `Mcp-Session-Id` header ### Client Implementations 1. **FastMCP Client** (`client_fastmcp.py`): - Uses official MCP Python SDK - Handles SSE automatically - Full protocol support 2. **httpx Client** (`client_httpx.py`): - Pure Python with only httpx dependency - Manual JSON-RPC implementation - Custom SSE parsing 3. **curl Client** (`client_curl.sh`): - Bash script using curl and jq - Demonstrates raw HTTP requests - No Python dependencies required ## Requirements - Python 3.13+ - fastmcp - httpx (included as fastmcp dependency)