# takumi0706/google-calendar-mcp architecture

> Architecture diagram of the GitHub repository takumi0706/google-calendar-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/takumi0706/google-calendar-mcp
- Repository: https://github.com/takumi0706/google-calendar-mcp

## Overview

##### Project type and purpose
- This is a backend “tool‐style” microservice: a Model Context Protocol (MCP) server that runs over STDIO, plugs into Claude Desktop, and exposes Google Calendar operations as “tools.”
- Its purpose is to mediate between Claude Desktop and the Google Calendar API, handling OAuth2, schema validation, event CRUD, and token security.

##### High-level file‐structure analysis
- Top level: configuration files, CI/CD workflows, test config (jest.config.js), TS config.
- src/ directory is organized into feature-driven subdirectories:
- auth/ – OAuth handlers, token manager
- calendar/ – calendar-specific API wrappers and types
- config/ – environment-based config loader
- mcp/ – MCP server core (transport, tool registration, JSON‐RPC handling)
- utils/ – logging, error handling, HTML sanitization, JSON parsing
- __tests__/ – unit tests mirroring each feature directory
- Key external configs: .env.example (dotenv), qodana.yaml (code quality), GitHub Actions YAMLs (CI/CD pipelines).

##### Architecture insights from README
- Core components outlined: MCP Server, Google Calendar Tools, Auth Handler, Schema Validation, Token Manager
- Tech stack: TypeScript, @modelcontextprotocol/sdk, googleapis, Zod, Helmet.js, AES-256-GCM, Jest, GitHub Actions
- Communication: STDIO transport for MCP JSON‐RPC messages

##### Diagramming the system – main components and interactions
1. CLAUDE DESKTOP (External System)
- Initiates STDIO connection, sends MCP JSON‐RPC requests
2. STDIO TRANSPORT LAYER (src/mcp/server.ts)
- Reads/writes to process.stdin/stdout
- Invokes MCP SDK message parsing
3. MCP SERVER CORE (@modelcontextprotocol/sdk)
- Registers tools, dispatches incoming tool calls based on Model Context Protocol
4. TOOL IMPLEMENTATIONS
– Google Calendar Tools (src/calendar/calendar-api.ts)
– CRUD functions: getEvents, createEvent, updateEvent, deleteEvent, authenticate
5. AUTHENTICATION SUBSYSTEM
- oauth-handler.ts: spins up local HTTP server for OAuth code exchange
- token-manager.ts: encrypts/decrypts tokens in memory using AES-256-GCM
6. SCHEMA VALIDATION (src/mcp/schemas.ts, zod)
- Validates incoming parameters and outgoing responses
7. CONFIGURATION (src/config/config.ts, dotenv)
- Loads env vars: client ID/secret, ports, encryption key, manual auth flag
8. UTILITIES
- Logger, error-handler, html-sanitizer, json-parser
9. GOOGLE CALENDAR API (External Service)
- Receives authenticated HTTP requests from calendar-api.ts

- Claude Desktop → STDIO Transport → MCP SDK → Tool Dispatcher
- Tool Dispatcher → Schema Validation → Appropriate Tool Function
- Tool Function → (if auth needed) → Token Manager & OAuth Handler → Google API
- Tool Function → Google API → returns data → Schema Validation → MCP SDK → STDIO → Claude Desktop
- Config module is imported by all internal modules (auth, mcp, calendar, utils)
- Utils are imported wherever logging, error handling, or parsing is needed

c. Architectural patterns & design principles
- Layered structure: transport → protocol core → business logic → external API
- Separation of concerns: auth, validation, tools, config, utils
- Dependency injection via configuration module
- Secure-by-design: in‐memory tokens, AES-256-GCM encryption, Helmet.js headers, Zod validation

d. Key technologies, frameworks, libraries
- TypeScript (static typing)
- @modelcontextprotocol/sdk (MCP server core)
- googleapis (Google Calendar integration)
- Zod (schema validation)
- dotenv (config)
- AES-256-GCM (crypto)
- Helmet.js (security headers)
- Jest (unit testing)
- GitHub Actions (CI/CD)

##### Detailed capturing of architectural elements
- Sequence for a typical tool call (e.g., createEvent): STDIO → MCP → validate → auth (if needed) → calendar-api → Google API → back through validation and STDIO

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Systems
    ClaudeDesktop["Claude Desktop"]:::external
    GoogleAPI["Google Calendar API"]:::external

    %% Transport & Protocol Layer
    subgraph "Transport & Protocol" 
        EntryPoint["Service Entry Point"]:::transport
        STDIO["STDIO Transport Layer"]:::transport
        MCPCore["MCP Server Core<br/>(Tool Registration & Dispatch)"]:::transport
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        CalendarAPI["Google Calendar API Wrapper"]:::business
        OAuthHelper["OAuth Helper<br/>(Auth flows)"]:::business
        OAuthHandler["OAuth Authentication Handler"]:::business
        TokenManager["Token Manager"]:::business
    end

    %% Utilities & Config
    subgraph "Utilities & Config"
        Schema["Schema Validation"]:::util
        Config["Configuration Loader"]:::util
        Logger["Logger Utility"]:::util
        ErrorHandler["Error Handling Utility"]:::util
        HTMLSanitizer["HTML Sanitization Utility"]:::util
        JSONParser["JSON Parsing Utility"]:::util
        CalendarTypes["Calendar Types"]:::util
    end

    %% Data Flows
    ClaudeDesktop -->|"STDIO"| STDIO
    STDIO --> EntryPoint
    EntryPoint --> MCPCore
    MCPCore -->|"validate request"| Schema
    Schema --> MCPCore
    MCPCore -->|"dispatch tool call"| CalendarAPI
    CalendarAPI -->|"validate params"| Schema
    CalendarAPI --> CalendarTypes
    CalendarAPI --> TokenManager
    CalendarAPI --> OAuthHelper
    OAuthHelper --> OAuthHandler
    OAuthHandler -->|"OAuth callback HTTP"| GoogleAPI
    TokenManager -.->|"encrypt/decrypt tokens"| CalendarAPI
    CalendarAPI -->|"HTTP request"| GoogleAPI
    GoogleAPI -->|"API response"| CalendarAPI
    CalendarAPI -->|"validate response"| Schema
    Schema --> MCPCore
    MCPCore --> STDIO
    STDIO --> ClaudeDesktop

    %% Dependencies from Config & Utils
    Config --> STDIO
    Config --> MCPCore
    Config --> CalendarAPI
    Config --> OAuthHelper
    Config --> OAuthHandler
    Config --> TokenManager
    Config --> Schema
    Logger --> MCPCore
    Logger --> CalendarAPI
    Logger --> OAuthHandler
    ErrorHandler --> MCPCore
    ErrorHandler --> CalendarAPI
    ErrorHandler --> OAuthHandler
    HTMLSanitizer --> CalendarAPI
    JSONParser --> STDIO

    %% Click Events
    click STDIO "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/mcp/server.ts"
    click MCPCore "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/mcp/tools.ts"
    click Schema "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/mcp/schemas.ts"
    click CalendarAPI "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/calendar/calendar-api.ts"
    click CalendarTypes "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/calendar/types.ts"
    click OAuthHandler "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/auth/oauth-handler.ts"
    click OAuthHelper "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/auth/oauth-auth.ts"
    click TokenManager "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/auth/token-manager.ts"
    click Config "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/config/config.ts"
    click Logger "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/utils/logger.ts"
    click ErrorHandler "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/utils/error-handler.ts"
    click HTMLSanitizer "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/utils/html-sanitizer.ts"
    click JSONParser "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/utils/json-parser.ts"
    click EntryPoint "https://github.com/takumi0706/google-calendar-mcp/blob/main/src/index.ts"

    %% Style Definitions
    classDef external fill:#b3d4fc,stroke:#1f78b4,color:#0c2d48
    classDef transport fill:#c7e9c0,stroke:#31a354,color:#0c2d48
    classDef business fill:#fdcc8a,stroke:#e34a33,color:#0c2d48
    classDef util fill:#eeeeee,stroke:#888888,color:#333333
```
