MCP Log Analyzer

# MCP AI Agent Architecture Documentation ## Table of Contents 1. [Overview](#overview) 2. [System Architecture](#system-architecture) 3. [Component Design](#component-design) 4. [Data Flow](#data-flow) 5. [Communication Protocols](#communication-protocols) 6. [Security Architecture](#security-architecture) 7. [Deployment Architecture](#deployment-architecture) 8. [Performance Considerations](#performance-considerations) 9. [Extensibility](#extensibility) ## Overview The MCP AI Agent is a command-line application that acts as an intelligent interface between users and MCP (Model Context Protocol) servers. It combines natural language processing capabilities with MCP server functionality to provide an enhanced conversational experience. ### Key Objectives - **Seamless Integration**: Connect to any MCP-compliant server - **Intelligent Processing**: Use AI to determine when and how to use MCP tools - **User-Friendly Interface**: Provide an intuitive CLI experience - **Extensible Design**: Support plugins and custom extensions - **Production-Ready**: Include monitoring, logging, and error handling ## System Architecture ### High-Level Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ User Interface │ │ (CLI with Rich/Click) │ └───────────────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────────────▼─────────────────────────────────┐ │ AI Agent Core │ │ ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ Message Handler │ │ Context Mgmt │ │ Tool Selector │ │ │ └─────────────────┘ └──────────────┘ └─────────────────┘ │ └───────────────────────────────┬─────────────────────────────────┘ │ ┌───────────────────────────────▼─────────────────────────────────┐ │ MCP Client Layer │ │ ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ Connection Mgr │ │ Protocol Impl│ │ Request Queue │ │ │ └─────────────────┘ └──────────────┘ └─────────────────┘ │ └───────────────────────────────┬─────────────────────────────────┘ │ ▼ ┌────────────────────┐ │ MCP Server │ │ (External) │ └────────────────────┘ ``` ### Component Relationships ``` ┌──────────────┐ uses ┌──────────────┐ │ main.py ├──────────────►│ cli.py │ └──────────────┘ └───────┬──────┘ │ creates ▼ ┌──────────────┐ uses ┌──────────────┐ │ config.py ├──────────────►│ ai_agent.py │ └──────────────┘ └───────┬──────┘ │ uses ▼ ┌──────────────┐ │mcp_client.py │ └──────────────┘ ``` ## Component Design ### 1. Configuration Management (`config.py`) **Purpose**: Centralized configuration management using environment variables **Key Features**: - Pydantic-based settings validation - Environment variable loading - Type safety and validation - Default values with overrides **Configuration Schema**: ```python class Settings(BaseSettings): mcp_server_url: HttpUrl mcp_server_port: int = Field(ge=1, le=65535) mcp_api_key: Optional[str] = None ai_model: str = "gpt-4" log_level: str = "INFO" connection_timeout: int = 30 retry_attempts: int = 3 ``` ### 2. MCP Client (`mcp_client.py`) **Purpose**: Handle all communication with the MCP server **Key Components**: - **Connection Manager**: Handles WebSocket/HTTP connections - **Protocol Handler**: Implements MCP protocol specification - **Request Queue**: Manages concurrent requests - **Response Parser**: Validates and parses server responses **Class Structure**: ```python class MCPClient: async def connect() -> None async def disconnect() -> None async def send_request(request: Request) -> Response async def list_tools() -> List[Tool] async def execute_tool(tool_name: str, params: Dict) -> Any ``` **Connection Strategy**: - Primary: WebSocket for real-time bidirectional communication - Fallback: HTTP for request-response patterns - Automatic reconnection with exponential backoff ### 3. AI Agent (`ai_agent.py`) **Purpose**: Core intelligence layer that processes user inputs **Key Responsibilities**: - Message understanding and intent detection - Tool selection based on user queries - Context management across conversations - Response generation and formatting **Decision Flow**: ``` User Input → Intent Analysis → Tool Selection → MCP Execution → Response Generation ``` **Context Management**: - Maintains conversation history - Tracks tool usage and results - Manages token limits - Implements sliding window for long conversations ### 4. CLI Interface (`cli.py`) **Purpose**: User interaction layer with rich terminal UI **Features**: - Interactive chat mode with syntax highlighting - Command palette for quick actions - Progress indicators for long operations - Session management and history **Command Structure**: ``` mcp-agent ├── start # Start interactive session ├── list-tools # Display available MCP tools ├── config # Show current configuration └── test-connection # Verify MCP server connectivity ``` ## Data Flow ### 1. User Query Processing ``` User Input │ ▼ CLI Parsing & Validation │ ▼ AI Agent Processing ├─► Intent Detection ├─► Context Retrieval └─► Tool Selection │ ▼ MCP Tool Execution │ ▼ Response Formatting │ ▼ CLI Display ``` ### 2. MCP Communication Flow ``` AI Agent Request │ ▼ Request Serialization (JSON-RPC 2.0) │ ▼ Connection Manager ├─► WebSocket Send (Primary) └─► HTTP POST (Fallback) │ ▼ MCP Server Processing │ ▼ Response Deserialization │ ▼ Validation & Error Handling │ ▼ AI Agent Response Processing ``` ## Communication Protocols ### MCP Protocol Implementation **Message Format** (JSON-RPC 2.0): ```json { "jsonrpc": "2.0", "method": "tool.execute", "params": { "name": "search", "arguments": { "query": "user search term" } }, "id": "unique-request-id" } ``` **Response Format**: ```json { "jsonrpc": "2.0", "result": { "output": "tool execution result", "metadata": {} }, "id": "unique-request-id" } ``` ### WebSocket Protocol **Connection Lifecycle**: 1. Initial handshake with authentication 2. Bidirectional message exchange 3. Heartbeat/ping mechanism 4. Graceful disconnection **Error Handling**: - Automatic reconnection on disconnect - Message queuing during connection loss - Duplicate detection using message IDs ## Security Architecture ### Authentication & Authorization ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │────►│ MCP │────►│ Auth │ │ (API Key) │ │ Server │ │ Provider │ └─────────────┘ └─────────────┘ └─────────────┘ ``` **Security Measures**: 1. **API Key Management**: Stored in environment variables, never in code 2. **TLS/SSL**: All communications encrypted in transit 3. **Input Sanitization**: Prevent injection attacks 4. **Rate Limiting**: Protect against abuse 5. **Audit Logging**: Track all tool executions ### Data Protection - **Sensitive Data**: Never logged or stored in plain text - **Conversation Privacy**: Optional encryption for stored sessions - **Token Management**: Secure storage of AI model tokens ## Deployment Architecture ### Local Development ``` Developer Machine ├── Python Virtual Environment ├── Local MCP Server (Testing) └── Environment Configuration ``` ### Production Deployment ``` ┌─────────────────────┐ │ Load Balancer │ └──────────┬──────────┘ │ ┌──────────▼──────────┐ ┌─────────────────┐ │ Agent Instance 1 │────►│ MCP Server │ ├─────────────────────┤ │ Cluster │ │ Agent Instance 2 │────►│ │ ├─────────────────────┤ └─────────────────┘ │ Agent Instance N │ └─────────────────────┘ ``` ### Container Architecture ```dockerfile # Multi-stage build FROM python:3.11-slim as builder # Build dependencies FROM python:3.11-slim # Runtime with minimal footprint ``` ## Performance Considerations ### Optimization Strategies 1. **Connection Pooling**: - Reuse MCP connections - Limit maximum concurrent connections - Implement connection health checks 2. **Caching**: - Cache tool listings - Store frequent query results - Implement TTL-based invalidation 3. **Async Operations**: - Non-blocking I/O for all network operations - Concurrent request processing - Event-driven architecture ### Performance Metrics ``` ┌─────────────────────────────────────┐ │ Metrics Collected │ ├─────────────────────────────────────┤ │ • Response Time (P50, P95, P99) │ │ • Throughput (requests/second) │ │ • Error Rate (% failed requests) │ │ • Resource Usage (CPU, Memory) │ │ • Connection Pool Utilization │ │ • Cache Hit Rate │ └─────────────────────────────────────┘ ``` ### Scalability Patterns 1. **Horizontal Scaling**: Multiple agent instances 2. **Vertical Scaling**: Resource allocation per instance 3. **Circuit Breaker**: Prevent cascade failures 4. **Bulkhead**: Isolate critical resources ## Extensibility ### Plugin Architecture ``` plugins/ ├── __init__.py ├── base.py # Plugin interface definition ├── loader.py # Dynamic plugin loading └── examples/ ├── custom_formatter.py ├── analytics.py └── export_handler.py ``` **Plugin Interface**: ```python class Plugin(ABC): @abstractmethod def initialize(self, agent: AIAgent) -> None: """Initialize plugin with agent instance""" @abstractmethod def process_message(self, message: Message) -> Optional[Message]: """Process or modify messages""" @abstractmethod def cleanup(self) -> None: """Cleanup resources""" ``` ### Extension Points 1. **Message Processors**: Transform or enrich messages 2. **Output Formatters**: Custom display formats 3. **Tool Providers**: Add custom tools 4. **Storage Backends**: Alternative session storage 5. **Authentication Methods**: Custom auth providers ### Integration Patterns **Event-Driven Extensions**: ```python @agent.on("message_received") def custom_handler(message): # Custom processing pass @agent.on("tool_executed") def log_execution(tool, result): # Custom logging pass ``` ## Monitoring & Observability ### Logging Architecture ``` Application Logs │ ├─► Structured Logging (JSON) ├─► Log Levels (DEBUG, INFO, WARN, ERROR) └─► Contextual Information ├─► Request IDs ├─► User Sessions └─► Tool Executions ``` ### Health Checks ``` /health ├── /ready # Application ready to serve ├── /live # Application is running └── /metrics # Prometheus metrics ``` ### Distributed Tracing ``` User Request → Agent → MCP Client → MCP Server └─────────── Trace ID ────────────┘ ``` ## Error Handling Strategy ### Error Categories 1. **Connection Errors**: Network timeouts, server unavailable 2. **Protocol Errors**: Invalid messages, unsupported operations 3. **Tool Errors**: Tool execution failures 4. **AI Errors**: Model unavailable, token limits 5. **User Errors**: Invalid input, unauthorized access ### Recovery Mechanisms ``` Error Detection │ ├─► Retry (with backoff) ├─► Fallback (alternative method) ├─► Circuit Break (prevent cascading) └─► Graceful Degradation └─► User Notification ``` ## Future Enhancements 1. **Multi-Model Support**: Switch between different AI models 2. **Federation**: Connect to multiple MCP servers 3. **Web UI**: Browser-based interface option 4. **Mobile Support**: iOS/Android clients 5. **Voice Interface**: Speech-to-text integration 6. **Batch Processing**: Handle multiple queries efficiently 7. **Advanced Analytics**: Usage patterns and insights ## Conclusion This architecture provides a robust, scalable, and extensible foundation for the MCP AI Agent. The modular design allows for easy maintenance and enhancement while the comprehensive error handling and monitoring ensure production readiness.