MCP API Server

# Design Document ## Overview The MCP Test Frontend is a single-page HTML application that provides a comprehensive testing interface for Model Context Protocol (MCP) servers. The frontend will simulate MCP client behavior, allowing developers to connect to their local MCP servers, explore available tools, execute tool calls, and monitor the complete JSON-RPC communication flow. The application will be built as a self-contained HTML file with embedded CSS and JavaScript, requiring no external dependencies or build process. This ensures maximum portability and ease of use in development environments. ## Architecture ### Client-Side Architecture The frontend follows a modular JavaScript architecture with clear separation of concerns: ``` ┌─────────────────────────────────────────────────────────────┐ │ HTML Interface │ ├─────────────────────────────────────────────────────────────┤ │ Connection Panel │ Tools Panel │ Execution Panel │ History │ ├─────────────────────────────────────────────────────────────┤ │ JavaScript Modules │ ├─────────────────────────────────────────────────────────────┤ │ MCPClient │ UIManager │ HistoryManager │ ValidationUtils │ ├─────────────────────────────────────────────────────────────┤ │ MCP Protocol Layer │ ├─────────────────────────────────────────────────────────────┤ │ JSON-RPC over HTTP/WebSocket │ └─────────────────────────────────────────────────────────────┘ ``` ### Communication Flow Since MCP servers typically use stdio transport, the frontend will need to communicate through a bridge or proxy. The design supports two connection modes: 1. **HTTP Bridge Mode**: Connect to an HTTP wrapper around the MCP server 2. **WebSocket Mode**: Connect to a WebSocket bridge that translates to stdio ## Components and Interfaces ### 1. MCPClient Module Handles all MCP protocol communication and maintains connection state. ```javascript class MCPClient { constructor(config) async connect(serverUrl) async disconnect() async listTools() async callTool(name, arguments) getConnectionStatus() onMessage(callback) onError(callback) } ``` **Key Responsibilities:** - Manage connection lifecycle - Implement JSON-RPC message formatting - Handle protocol handshake and initialization - Provide event-driven communication interface - Maintain message ID tracking for request/response correlation ### 2. UIManager Module Manages all user interface interactions and state updates. ```javascript class UIManager { constructor(mcpClient, historyManager) renderConnectionPanel() renderToolsPanel(tools) renderExecutionPanel(selectedTool) renderHistoryPanel(history) showError(message) showSuccess(message) updateConnectionStatus(status) } ``` **Key Responsibilities:** - Render dynamic UI components - Handle form validation and submission - Manage UI state transitions - Display notifications and error messages - Coordinate between different UI panels ### 3. HistoryManager Module Tracks and manages the history of MCP interactions. ```javascript class HistoryManager { constructor() addInteraction(request, response, timestamp) getHistory() clearHistory() exportHistory() filterHistory(criteria) } ``` **Key Responsibilities:** - Store request/response pairs with metadata - Provide history filtering and search - Support history export functionality - Maintain interaction timestamps and status ### 4. ValidationUtils Module Provides client-side validation for tool parameters and requests. ```javascript class ValidationUtils { static validateURL(url) static validateToolParameters(toolSchema, parameters) static validateHeaders(headers) static formatValidationErrors(errors) } ``` **Key Responsibilities:** - Validate user input before sending requests - Provide real-time validation feedback - Format validation error messages - Support JSON schema validation for tool parameters ## Data Models ### Connection State ```javascript interface ConnectionState { status: 'disconnected' | 'connecting' | 'connected' | 'error'; serverUrl: string | null; serverInfo: { name: string; version: string; capabilities: object; } | null; error: string | null; } ``` ### Tool Definition ```javascript interface ToolDefinition { name: string; description: string; inputSchema: { type: 'object'; properties: Record<string, any>; required?: string[]; }; } ``` ### Interaction History ```javascript interface InteractionRecord { id: string; timestamp: Date; type: 'tools/list' | 'tools/call' | 'initialize'; request: { method: string; params: any; id: string | number; }; response: { result?: any; error?: any; id: string | number; }; duration: number; status: 'success' | 'error'; } ``` ### UI State ```javascript interface UIState { selectedTool: string | null; toolParameters: Record<string, any>; showHistory: boolean; historyFilter: string; notifications: Array<{ id: string; type: 'success' | 'error' | 'info'; message: string; timestamp: Date; }>; } ``` ## Error Handling ### Connection Errors - **Network Errors**: Display user-friendly messages for connection failures - **Protocol Errors**: Show detailed JSON-RPC error information - **Timeout Errors**: Provide retry mechanisms with exponential backoff ### Validation Errors - **Parameter Validation**: Real-time validation with inline error messages - **Schema Validation**: JSON schema validation for tool parameters - **URL Validation**: Validate server URLs before connection attempts ### Runtime Errors - **JavaScript Errors**: Global error handler with user notification - **Response Parsing**: Handle malformed JSON responses gracefully - **Tool Execution**: Display tool-specific error messages clearly ## Testing Strategy ### Manual Testing Approach Since this is a testing tool itself, the testing strategy focuses on manual validation: 1. **Connection Testing** - Test connection to various MCP server implementations - Validate error handling for invalid server URLs - Verify reconnection behavior 2. **Tool Interaction Testing** - Test all supported HTTP methods (GET, POST, PUT, DELETE) - Validate parameter validation for different tool schemas - Test error scenarios and edge cases 3. **UI/UX Testing** - Test responsive design on different screen sizes - Validate accessibility features - Test keyboard navigation and shortcuts 4. **Protocol Compliance Testing** - Verify JSON-RPC message formatting - Test message ID correlation - Validate error response handling ### Browser Compatibility - **Modern Browsers**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+ - **JavaScript Features**: ES6+ features with fallbacks where needed - **CSS Features**: Flexbox and Grid with fallbacks - **No External Dependencies**: Pure HTML/CSS/JavaScript implementation ## Implementation Considerations ### Performance - **Lazy Loading**: Load UI components on demand - **Message Batching**: Batch multiple rapid requests when possible - **Memory Management**: Limit history size with configurable retention - **DOM Optimization**: Minimize DOM manipulations and reflows ### Security - **Input Sanitization**: Sanitize all user inputs before display - **XSS Prevention**: Use textContent instead of innerHTML where possible - **CORS Handling**: Provide clear error messages for CORS issues - **URL Validation**: Strict validation of server URLs ### Accessibility - **Keyboard Navigation**: Full keyboard accessibility - **Screen Reader Support**: Proper ARIA labels and roles - **High Contrast**: Support for high contrast mode - **Focus Management**: Clear focus indicators and logical tab order ### Responsive Design - **Mobile First**: Design for mobile devices first - **Flexible Layouts**: Use CSS Grid and Flexbox for responsive layouts - **Touch Friendly**: Appropriate touch targets for mobile devices - **Print Styles**: Optimized styles for printing interaction history