MCP API Server

# Design Document ## Overview The MCP API Server is a TypeScript-based Model Context Protocol server that provides HTTP API calling capabilities. It implements the MCP specification to expose tools for making GET, POST, PUT, and DELETE requests to external APIs. The server handles authentication, request/response processing, and error management while maintaining compatibility with the MCP protocol. ## Architecture The server follows a modular architecture with clear separation of concerns: ``` ┌─────────────────┐ │ MCP Client │ └─────────┬───────┘ │ MCP Protocol ┌─────────▼───────┐ │ MCP Server │ │ - Tool Registry│ │ - Request │ │ Handler │ └─────────┬───────┘ │ HTTP Requests ┌─────────▼───────┐ │ External APIs │ └─────────────────┘ ``` The server acts as a bridge between MCP clients and external HTTP APIs, translating MCP tool calls into HTTP requests and returning structured responses. ## Components and Interfaces ### Core Components 1. **MCPServer**: Main server class that implements the MCP protocol 2. **APIClient**: HTTP client wrapper for making external API calls 3. **ToolRegistry**: Manages available tools and their schemas 4. **RequestValidator**: Validates incoming tool call parameters 5. **ResponseFormatter**: Formats API responses for MCP clients ### Tool Definitions The server exposes the following tools: #### `api_get` - **Purpose**: Make HTTP GET requests - **Parameters**: - `url` (string, required): Target URL - `headers` (object, optional): Custom headers #### `api_post` - **Purpose**: Make HTTP POST requests - **Parameters**: - `url` (string, required): Target URL - `body` (string/object, optional): Request body - `headers` (object, optional): Custom headers #### `api_put` - **Purpose**: Make HTTP PUT requests - **Parameters**: - `url` (string, required): Target URL - `body` (string/object, optional): Request body - `headers` (object, optional): Custom headers #### `api_delete` - **Purpose**: Make HTTP DELETE requests - **Parameters**: - `url` (string, required): Target URL - `headers` (object, optional): Custom headers ### Interface Definitions ```typescript interface APIRequest { url: string; method: 'GET' | 'POST' | 'PUT' | 'DELETE'; headers?: Record<string, string>; body?: string | object; } interface APIResponse { status: number; statusText: string; headers: Record<string, string>; data: any; } interface ToolCallParams { url: string; headers?: Record<string, string>; body?: string | object; } ``` ## Data Models ### Request Model - URL validation (must be valid HTTP/HTTPS URL) - Method validation (must be supported HTTP method) - Headers validation (must be key-value pairs) - Body validation (must be valid JSON for POST/PUT when object) ### Response Model - Status code (HTTP status code) - Status text (HTTP status message) - Headers (response headers as key-value pairs) - Data (parsed response body - JSON object or raw text) ### Error Model - Error type (network, validation, HTTP error) - Error message (human-readable description) - Status code (when applicable) - Original error details (for debugging) ## Error Handling ### Error Categories 1. **Validation Errors** - Invalid URL format - Missing required parameters - Invalid JSON in request body - Unsupported HTTP method 2. **Network Errors** - Connection timeout - DNS resolution failure - Network unreachable - SSL/TLS errors 3. **HTTP Errors** - 4xx client errors (400, 401, 403, 404, etc.) - 5xx server errors (500, 502, 503, etc.) - Response parsing errors ### Error Response Format ```typescript interface ErrorResponse { error: { type: 'validation' | 'network' | 'http' | 'parsing'; message: string; statusCode?: number; details?: any; }; } ``` ## Testing Strategy Since testing is not required for this implementation, the design focuses on: 1. **Input Validation**: Robust parameter validation to prevent runtime errors 2. **Error Handling**: Comprehensive error catching and meaningful error messages 3. **Logging**: Detailed logging for debugging and monitoring 4. **Type Safety**: Strong TypeScript typing to catch errors at compile time ## Implementation Details ### Dependencies - `@modelcontextprotocol/sdk`: MCP SDK for TypeScript - `axios`: HTTP client library - `zod`: Runtime type validation - Standard Node.js modules (url, util, etc.) ### Configuration - Configurable timeout settings - Optional request/response logging - Customizable user agent string - Support for proxy configuration ### Security Considerations - URL validation to prevent SSRF attacks - Header sanitization - Request size limits - Timeout enforcement to prevent hanging requests