Math Operations MCP Server

# Math Operations - Architecture Diagram ## Overall System Architecture ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ CLIENT APPLICATIONS │ └─────────────────────────────────────────────────────────────────────────┘ │ ┌───────────────┴───────────────┐ │ │ ▼ ▼ ┌───────────────────────┐ ┌──────────────────────┐ │ HTTP REST Client │ │ AI Applications │ │ (curl, browser, │ │ - Claude Desktop │ │ Postman, etc.) │ │ - Cline/VSCode │ └───────────┬───────────┘ │ - Continue.dev │ │ │ - Custom AI Apps │ │ └──────────┬───────────┘ │ │ │ HTTP/JSON │ stdio/JSON-RPC │ │ ┌───────────▼───────────┐ ┌──────────▼───────────┐ │ │ │ │ │ FastAPI Server │ │ MCP Server │ │ (Port 8000) │ │ (stdio transport) │ │ │ │ │ └───────────────────────┘ └──────────────────────┘ ``` --- ## FastAPI Server Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ main.py │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ FastAPI Application │ │ │ │ - Title: "Math Operations API" │ │ │ │ - Version: "1.0.0" │ │ │ │ - Root endpoint: GET / │ │ │ └──────────────┬────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────┴──────────┐ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────┐ ┌─────────┐ │ │ │ Router │ │ Router │ │ │ │ Prefix: │ │ Prefix: │ │ │ │ /api │ │ /api │ │ │ └────┬────┘ └────┬────┘ │ └───────┼──────────────────┼───────────────────────────────────┘ │ │ │ │ ┌───────▼──────────┐ ┌────▼─────────────┐ │ api/add.py │ │ api/subtract.py │ │ │ │ │ │ POST /api/add │ │ POST /api/subtract│ │ │ │ │ │ ┌──────────────┐ │ │ ┌──────────────┐ │ │ │AddRequest │ │ │ │SubtractRequest│ │ │ │- a: float │ │ │ │- a: float │ │ │ │- b: float │ │ │ │- b: float │ │ │ └──────────────┘ │ │ └──────────────┘ │ │ │ │ │ │ │ │ ▼ │ │ ▼ │ │ ┌──────────────┐ │ │ ┌──────────────┐ │ │ │add_numbers() │ │ │ │subtract_ │ │ │ │ │ │ │ │numbers() │ │ │ │result = a+b │ │ │ │result = a-b │ │ │ └──────────────┘ │ │ └──────────────┘ │ │ │ │ │ │ │ │ ▼ │ │ ▼ │ │ ┌──────────────┐ │ │ ┌──────────────┐ │ │ │AddResponse │ │ │ │SubtractResp. │ │ │ │- result │ │ │ │- result │ │ │ │- operation │ │ │ │- operation │ │ │ │- inputs │ │ │ │- inputs │ │ │ └──────────────┘ │ │ └──────────────┘ │ └──────────────────┘ └──────────────────┘ ``` --- ## MCP Server Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ mcp_server.py │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ MCP Server("math-operations-mcp") │ │ │ │ │ │ │ │ Transport: stdio (Standard Input/Output) │ │ │ │ Protocol: JSON-RPC 2.0 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌───────────────┴───────────────┐ │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ @app.list_tools() │ │ @app.call_tool() │ │ │ │ │ │ │ │ │ │ Returns: │ │ Parameters: │ │ │ │ - Tool: "add" │ │ - name: str │ │ │ │ - Tool: "subtract" │ │ - arguments: dict │ │ │ └─────────────────────┘ └──────────┬──────────┘ │ │ │ │ │ ┌──────────────┴──────────────┐ │ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ name == "add" │ │name == "subtract"│ │ │ │ │ │ │ │ a = args["a"] │ │ a = args["a"] │ │ │ b = args["b"] │ │ b = args["b"] │ │ │ │ │ │ │ │ result = a + b │ │ result = a - b │ │ │ │ │ │ │ │ Return: │ │ Return: │ │ │ TextContent │ │ TextContent │ │ └──────────────────┘ └──────────────────┘ │ │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## MCP Tools Schema ``` ┌────────────────────────────────────────┐ │ Tool: "add" │ ├────────────────────────────────────────┤ │ Description: │ │ "Add two numbers together. │ │ Returns the sum of a and b." │ ├────────────────────────────────────────┤ │ Input Schema: │ │ { │ │ "type": "object", │ │ "properties": { │ │ "a": { │ │ "type": "number", │ │ "description": "First number" │ │ }, │ │ "b": { │ │ "type": "number", │ │ "description": "Second number" │ │ } │ │ }, │ │ "required": ["a", "b"] │ │ } │ └────────────────────────────────────────┘ ┌────────────────────────────────────────┐ │ Tool: "subtract" │ ├────────────────────────────────────────┤ │ Description: │ │ "Subtract b from a. │ │ Returns the difference (a - b)." │ ├────────────────────────────────────────┤ │ Input Schema: │ │ { │ │ "type": "object", │ │ "properties": { │ │ "a": { │ │ "type": "number", │ │ "description": "Subtract from" │ │ }, │ │ "b": { │ │ "type": "number", │ │ "description": "To subtract" │ │ } │ │ }, │ │ "required": ["a", "b"] │ │ } │ └────────────────────────────────────────┘ ``` --- ## Communication Flow - FastAPI ``` ┌──────────┐ ┌────────────┐ │ Client │ │ FastAPI │ │ (HTTP) │ │ Server │ └────┬─────┘ └─────┬──────┘ │ │ │ 1. POST /api/add │ │ Content-Type: application/json │ │ {"a": 10.5, "b": 5.5} │ ├────────────────────────────────────────────────────────>│ │ │ │ 2. Parse JSON │ │ 3. Validate │ │ 4. Execute │ │ result=a+b │ │ │ │ 5. HTTP 200 OK │ │ Content-Type: application/json │ │ { │ │ "result": 16.0, │ │ "operation": "addition", │ │ "inputs": {"a": 10.5, "b": 5.5} │ │ } │ │<────────────────────────────────────────────────────────┤ │ │ ``` --- ## Communication Flow - MCP Server ``` ┌────────────┐ ┌────────────┐ │ AI │ │ MCP │ │Application │ │ Server │ │ (Claude) │ │ (stdio) │ └─────┬──────┘ └─────┬──────┘ │ │ │ 1. Initialize Session │ │ JSON-RPC: initialize │ ├──────────────────────────────────────────────────>│ │ │ │ 2. Response: capabilities │ │<───────────────────────────────────────────────────┤ │ │ │ 3. Request: tools/list │ ├──────────────────────────────────────────────────>│ │ │ │ 4. Response: [add, subtract] │ │ with schemas │ │<───────────────────────────────────────────────────┤ │ │ │ 5. Request: tools/call │ │ { │ │ "name": "add", │ │ "arguments": {"a": 10, "b": 5} │ │ } │ ├──────────────────────────────────────────────────>│ │ 6. Execute │ │ result=15│ │ │ │ 7. Response: TextContent │ │ "Result: 15.0 │ │ Operation: addition │ │ Inputs: a=10, b=5" │ │<───────────────────────────────────────────────────┤ │ │ ``` --- ## Testing Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Testing Methods │ └─────────────────────────────────────────────────────────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ▼ ▼ ▼ ┌───────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ test_mcp.py │ │ MCP Inspector │ │ Manual Test │ │ │ │ │ │ │ │ - Automated │ │ - Visual UI │ │ - Direct stdio │ │ - Python │ │ - Interactive │ │ - JSON-RPC │ │ - 6 test cases│ │ - Browser-based │ │ - Command line │ └───────┬───────┘ └────────┬────────┘ └────────┬────────┘ │ │ │ │ │ │ └───────────────────┼────────────────────┘ │ ▼ ┌───────────────────────┐ │ mcp_server.py │ │ │ │ - Receives requests │ │ - Executes tools │ │ - Returns results │ └───────────────────────┘ Test Results: ┌─────────────────────────────────────────┐ │ ✓ List tools │ │ ✓ Add positive numbers (15.5 + 24.5) │ │ ✓ Subtract numbers (100 - 42) │ │ ✓ Add negative numbers (-10 + -5) │ │ ✓ Decimal precision (0.1 + 0.2) │ │ ✓ Error handling (unknown tool) │ └─────────────────────────────────────────┘ ``` --- ## Project File Structure ``` d:\Projects\MCP\ │ ├── main.py ← FastAPI application entry point │ └── Includes routers from api/ │ ├── mcp_server.py ← MCP server (stdio transport) │ ├── @app.list_tools() ← Tool definitions │ └── @app.call_tool() ← Tool execution logic │ ├── test_mcp.py ← Automated test script │ └── Uses MCP ClientSession │ ├── mcp.json ← Config example for AI apps │ └── Claude Desktop, Cline, Continue.dev │ ├── requirements.txt ← Python dependencies │ ├── fastapi==0.115.0 │ ├── uvicorn==0.32.0 │ ├── pydantic==2.9.2 │ └── mcp>=1.0.0 │ ├── README.md ← Documentation │ └── api/ ← API modules ├── __init__.py ├── add.py ← Addition endpoint │ ├── POST /api/add │ ├── AddRequest (a, b) │ └── AddResponse (result, operation, inputs) │ └── subtract.py ← Subtraction endpoint ├── POST /api/subtract ├── SubtractRequest (a, b) └── SubtractResponse (result, operation, inputs) ``` --- ## Data Flow - Complete Example ``` User Request: "Add 10 and 20" │ ├─────────────────────────────┬──────────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ FastAPI │ │ MCP │ │ Testing │ │ Path │ │ Path │ │ Path │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ ▼ ▼ ▼ POST /api/add tools/call "add" session.call_tool() {"a":10,"b":20} {"a":10,"b":20} ("add",{a:10,b:20}) │ │ │ ▼ ▼ ▼ api/add.py mcp_server.py mcp_server.py add_numbers() call_tool() call_tool() │ │ │ ▼ ▼ ▼ result = 10+20 result = 10+20 result = 10+20 result = 30 result = 30 result = 30 │ │ │ ▼ ▼ ▼ AddResponse TextContent TextContent { "Result: 30.0 "Result: 30.0 "result": 30, Operation: addition Operation: addition "operation": "addition", Inputs: a=10, b=20" Inputs: a=10, b=20" "inputs": {a:10,b:20} } │ │ │ ▼ ▼ ▼ HTTP 200 Response JSON-RPC Response Test Assertion JSON body stdio output assert == 30 ✓ ``` --- ## Key Technologies ``` ┌─────────────────────────────────────────────────────────────┐ │ Technology Stack │ └─────────────────────────────────────────────────────────────┘ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ FastAPI │ │ Pydantic │ │ MCP SDK │ │ │ │ │ │ │ │ - REST API │ │ - Validation │ │ - stdio │ │ - OpenAPI │ │ - Schemas │ │ - JSON-RPC │ │ - Async │ │ - Type hints │ │ - Tools │ └──────────────┘ └──────────────┘ └──────────────┘ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Uvicorn │ │ Python │ │ uv │ │ │ │ │ │ │ │ - ASGI │ │ - 3.10+ │ │ - Package │ │ - Server │ │ - Async/Await│ │ - Manager │ └──────────────┘ └──────────────┘ └──────────────┘ ``` --- ## Integration Points ``` ┌─────────────────────────────────────────────────────────────┐ │ How AI Applications Connect │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────┐ ┌──────────────────┐ │ Claude Desktop │ │ Cline │ │ │ │ (VSCode) │ │ Config file: │ │ │ │ claude_desktop_ │ │ Config file: │ │ config.json │ │ .vscode/ │ │ │ │ settings.json │ │ "mcpServers": { │ │ │ │ "math-ops": { │ │ "cline.mcp │ │ "command": │ │ Servers": {...} │ │ "uv", │ │ │ │ "args": [ │ │ │ │ "run", │ │ │ │ "mcp_ │ │ │ │ server.py"│ │ │ │ ] │ │ │ │ } │ │ │ │ } │ │ │ └────────┬────────┘ └────────┬─────────┘ │ │ └──────────┬─────────────────┘ │ ▼ ┌────────────────────┐ │ mcp_server.py │ │ (stdio process) │ └────────────────────┘ ```