Enhanced MCP Server

# System Architecture ## Complete System Architecture ```mermaid graph TB subgraph "Client Layer" CD[Claude Desktop] end subgraph "MCP Server Layer" MCP[MCP Server<br/>mcp_server.py] TR[Tool Registry<br/>30+ Tools] end subgraph "Service Layer" EA[Email Adapter] CA[Calendar Adapter] DA[Drive Adapter] SA[Sheets Adapter] KA[Keep Adapter] end subgraph "LLM Layer" LLM[LLM Manager] CB[Circuit Breaker] RL[Rate Limiter] subgraph "LLM Providers" EURI[Euri API] DS[Deepseek API] GM[Gemini API] CL[Claude API] end end subgraph "Workflow Layer" WF1[Email Processing<br/>Workflow] WF2[Calendar Management<br/>Workflow] WF3[Job Tracking<br/>Workflow] WF4[Notification<br/>Workflow] end subgraph "Scheduler Layer" SCH1[Email Scheduler<br/>Every 4 hours] SCH2[Calendar Scheduler<br/>Daily summaries] SCH3[Notification Scheduler<br/>Smart reminders] end subgraph "Data Layer" DB[(SQLite Database)] CACHE[Redis Cache<br/>Optional] end subgraph "External APIs" GMAIL[Gmail API] GCAL[Calendar API] GDRV[Drive API] GSHT[Sheets API] end subgraph "Configuration" ENV[.env<br/>Environment Variables] CFG[config.yaml<br/>Application Config] TOKEN[tokens.json<br/>OAuth Tokens] end CD -->|JSON-RPC stdio| MCP MCP --> TR TR --> EA TR --> CA TR --> DA TR --> SA TR --> KA EA --> LLM CA --> LLM DA --> LLM SA --> LLM KA --> LLM LLM --> CB LLM --> RL CB --> EURI CB --> DS CB --> GM CB --> CL EA --> GMAIL CA --> GCAL DA --> GDRV SA --> GSHT EA --> WF1 CA --> WF2 EA --> WF3 CA --> WF4 WF1 --> SCH1 WF2 --> SCH2 WF4 --> SCH3 EA --> DB CA --> DB DA --> CACHE SA --> DB ENV -.->|Load| MCP CFG -.->|Load| MCP TOKEN -.->|OAuth| EA TOKEN -.->|OAuth| CA TOKEN -.->|OAuth| DA TOKEN -.->|OAuth| SA style CD fill:#667eea,stroke:#333,stroke-width:2px,color:#fff style MCP fill:#764ba2,stroke:#333,stroke-width:2px,color:#fff style LLM fill:#f59e0b,stroke:#333,stroke-width:2px,color:#fff style DB fill:#10b981,stroke:#333,stroke-width:2px,color:#fff ``` ## High-Level Component Diagram ```mermaid C4Context title System Context Diagram - Enhanced MCP Server Person(user, "User", "Claude Desktop User") System(mcp, "Enhanced MCP Server", "Google Services Integration with LLM Fallback") System_Ext(google, "Google APIs", "Gmail, Calendar, Drive, Sheets") System_Ext(llm1, "Euri API", "Primary LLM") System_Ext(llm2, "Deepseek API", "Fallback LLM") System_Ext(llm3, "Gemini API", "Fallback LLM") System_Ext(llm4, "Claude API", "Final Fallback") Rel(user, mcp, "Uses", "JSON-RPC") Rel(mcp, google, "Calls", "REST API") Rel(mcp, llm1, "Calls", "REST API") Rel(mcp, llm2, "Falls back to", "REST API") Rel(mcp, llm3, "Falls back to", "REST API") Rel(mcp, llm4, "Falls back to", "REST API") ``` ## Layer Architecture ```mermaid graph LR subgraph "Presentation" A[Claude Desktop UI] end subgraph "Application" B[MCP Protocol Handler] C[Tool Orchestrator] D[Request Router] end subgraph "Business Logic" E[Email Service] F[Calendar Service] G[Job Tracking Service] H[Notification Service] end subgraph "Integration" I[Google API Adapters] J[LLM Manager] K[Workflow Engine] end subgraph "Infrastructure" L[Database] M[Cache] N[Logger] O[Config Manager] end A --> B B --> C C --> D D --> E D --> F D --> G D --> H E --> I E --> J F --> I F --> J G --> J H --> K I --> L J --> L K --> M L --> N M --> O style A fill:#667eea,color:#fff style B fill:#764ba2,color:#fff style I fill:#10b981,color:#fff style J fill:#f59e0b,color:#fff ``` ## Data Flow Architecture ```mermaid flowchart TD Start([User Request in Claude Desktop]) --> Parse[Parse Request] Parse --> Route{Route to Tool} Route -->|Email| EmailTool[Email Tool Handler] Route -->|Calendar| CalTool[Calendar Tool Handler] Route -->|Job| JobTool[Job Tracking Tool] Route -->|Drive| DriveTool[Drive Tool] EmailTool --> EmailAdapter[Gmail Adapter] CalTool --> CalAdapter[Calendar Adapter] JobTool --> JobAdapter[Job Tracking Service] DriveTool --> DriveAdapter[Drive Adapter] EmailAdapter --> NeedsLLM{Needs LLM?} CalAdapter --> NeedsLLM JobAdapter --> NeedsLLM DriveAdapter --> NeedsLLM NeedsLLM -->|Yes| LLMManager[LLM Manager] NeedsLLM -->|No| CallAPI[Call Google API] LLMManager --> TryEuri{Try Euri} TryEuri -->|Success| ProcessResponse TryEuri -->|Fail| TryDeepseek{Try Deepseek} TryDeepseek -->|Success| ProcessResponse TryDeepseek -->|Fail| TryGemini{Try Gemini} TryGemini -->|Success| ProcessResponse TryGemini -->|Fail| TryClaude{Try Claude} TryClaude -->|Success| ProcessResponse TryClaude -->|Fail| Error[All Providers Failed] ProcessResponse --> CallAPI CallAPI --> CheckSchedule{Schedule Task?} CheckSchedule -->|Yes| AddToScheduler[Add to Scheduler] CheckSchedule -->|No| SaveToDB[Save to Database] AddToScheduler --> SaveToDB SaveToDB --> FormatResponse[Format Response] FormatResponse --> Return([Return to Claude Desktop]) Error --> Return style Start fill:#667eea,color:#fff style LLMManager fill:#f59e0b,color:#fff style SaveToDB fill:#10b981,color:#fff style Return fill:#667eea,color:#fff ``` ## Component Interaction Diagram ```mermaid sequenceDiagram participant User as Claude Desktop participant MCP as MCP Server participant Tool as Tool Handler participant Adapter as Google Adapter participant LLM as LLM Manager participant CB as Circuit Breaker participant API as Google API participant DB as Database User->>MCP: Request (e.g., "Summarize my emails") MCP->>Tool: Route to Email Tool Tool->>Adapter: Call Gmail Adapter Adapter->>DB: Check Cache alt Cache Miss Adapter->>API: Fetch Emails API-->>Adapter: Email Data end Adapter->>LLM: Request Summarization LLM->>CB: Check Euri Circuit alt Circuit Closed CB->>LLM: Proceed LLM->>API: Call Euri API API-->>LLM: Response else Circuit Open CB->>LLM: Try Next Provider LLM->>API: Call Deepseek API API-->>LLM: Response end LLM-->>Adapter: Processed Result Adapter->>DB: Save Result Adapter-->>Tool: Return Data Tool-->>MCP: Format Response MCP-->>User: Display Result ``` ## Deployment Architecture ```mermaid graph TB subgraph "User Machine" subgraph "Claude Desktop" UI[Claude UI] end subgraph "MCP Server Process" Server[MCP Server<br/>Python Process] Config[Configuration Files] end subgraph "Local Storage" DB[(SQLite Database)] Tokens[OAuth Tokens] Logs[Log Files] end end subgraph "Google Cloud" Gmail[Gmail API] Calendar[Calendar API] Drive[Drive API] Sheets[Sheets API] end subgraph "LLM Providers" Euri[Euri API] Deepseek[Deepseek API] Gemini[Gemini API] Claude[Claude API] end UI <-->|stdio| Server Server --> Config Server --> DB Server --> Tokens Server --> Logs Server -->|HTTPS| Gmail Server -->|HTTPS| Calendar Server -->|HTTPS| Drive Server -->|HTTPS| Sheets Server -->|HTTPS| Euri Server -->|HTTPS| Deepseek Server -->|HTTPS| Gemini Server -->|HTTPS| Claude style UI fill:#667eea,color:#fff style Server fill:#764ba2,color:#fff style DB fill:#10b981,color:#fff ``` ## Technology Stack ```mermaid graph LR subgraph "Frontend" A[Claude Desktop] end subgraph "Protocol" B[MCP<br/>Model Context Protocol] C[JSON-RPC 2.0] end subgraph "Backend Framework" D[Python 3.8+] E[AsyncIO] F[Pydantic] end subgraph "Integration" G[Google API Client] H[LangChain] I[LangGraph] end subgraph "LLM Providers" J[OpenAI SDK<br/>Euri, Deepseek] K[Anthropic SDK<br/>Claude] L[Google Gen AI<br/>Gemini] end subgraph "Scheduling" M[APScheduler] end subgraph "Data" N[SQLAlchemy] O[SQLite] P[Aiosqlite] end subgraph "Utilities" Q[Structlog<br/>Logging] R[Tenacity<br/>Retry Logic] S[HTTPX<br/>HTTP Client] end A --> B B --> C C --> D D --> E D --> F D --> G D --> H D --> I H --> J H --> K H --> L D --> M D --> N N --> O N --> P D --> Q D --> R D --> S style A fill:#667eea,color:#fff style D fill:#764ba2,color:#fff style N fill:#10b981,color:#fff ``` --- ## Architecture Principles ### 1. **Modularity** - Each adapter is independent - Tools are organized by domain - Clear separation of concerns ### 2. **Reliability** - Circuit breaker pattern prevents cascading failures - Rate limiting protects against overuse - Comprehensive error handling - Automatic retry with exponential backoff ### 3. **Scalability** - Async/await throughout - Connection pooling - Batch operations - Caching strategy ### 4. **Maintainability** - Type-safe with Pydantic models - Comprehensive logging - Clear naming conventions - Extensive documentation ### 5. **Security** - OAuth 2.0 authentication - Token encryption - Environment-based secrets - API key rotation support ### 6. **Observability** - Structured logging (JSON) - Metrics collection - Health checks - Cost tracking --- ## Key Design Decisions | Decision | Rationale | |----------|-----------| | **Stdio Protocol** | Required by Claude Desktop MCP integration | | **Async/Await** | Handles concurrent requests efficiently | | **Pydantic Models** | Type safety and validation | | **Circuit Breaker** | Prevents cascading LLM provider failures | | **Rate Limiting** | Protects against API rate limits | | **SQLite Database** | Simple, local, zero-config persistence | | **LangGraph Workflows** | Complex multi-step orchestration | | **APScheduler** | Reliable scheduled task execution | | **Structured Logging** | Easy parsing and analysis | --- ## Performance Characteristics - **Startup Time**: < 2 seconds - **Average Tool Response**: 500ms - 2s (excluding LLM calls) - **LLM Response**: 1-5s (depending on provider) - **Concurrent Requests**: Up to 10 simultaneous - **Database Queries**: < 50ms average - **Memory Footprint**: ~100-200MB - **CPU Usage**: Low (mostly I/O bound) --- ## Scalability Considerations ### Current Limitations - Single-user deployment (one Claude Desktop instance) - Local SQLite database - In-memory rate limiting ### Future Enhancements - Multi-user support with user authentication - PostgreSQL for multi-user scenarios - Redis for distributed rate limiting - Horizontal scaling with load balancer - Cloud deployment (AWS, GCP, Azure) --- **Status**: ✅ Production Ready