# nspady/google-calendar-mcp architecture

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

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

## Overview

##### Project Type and Purpose
- This is a **backend MCP (Model Context Protocol) server** that exposes a standardized API for LLMs (e.g., Claude Desktop) to interact with Google Calendar.
- Purpose: handle OAuth, translate MCP commands into calls to the Google Calendar API, and return structured results.

##### File Structure
- Top‐Level Files & Configs
– Dockerfile, .dockerignore → containerization
– github/workflows/ci.yml → CI pipeline
– package.json, tsconfig.json, bun.lockb → Node.js/TypeScript project
- src/auth‐server.ts & src/auth/
– Implements local OAuth server to obtain/refresh tokens
- src/index.ts
– Entry point: bootstraps authentication check, starts MCP HTTP/CLI server
- src/handlers/
– callTool.ts: dispatches incoming MCP commands
– core/*.ts: per‐command handlers (ListEvents, CreateEvent, etc.)
- src/schemas/
– Types & validation for incoming/outgoing messages
- scripts/build.js
– Custom build steps, e.g., bundling or assets

##### Extract Key Insights from README
- **External Dependencies**: Google Calendar API, OAuth 2.0
- **Runtime Flow**:
1. Server startup → check tokens → if missing, spin up a temporary OAuth HTTP server (ports 3000–3004)
2. Browser consent → tokens saved to `.gcp-saved-tokens.json`
3. Server initializes MCP endpoints
- **Integration Point**: LLMs invoke the MCP server via CLI or HTTP (defined in Claude Desktop config)

##### Main Architectural Components
a. **OAuth Module**
- Subcomponents:
- Credentials Loader (reads `gcp-oauth.keys.json`)
- Token Storage (.gcp-saved-tokens.json)
- Local HTTP Auth Server (`src/auth-server.ts` + `src/auth/server.ts`)
b. **MCP Core Server**
- Entry (src/index.ts)
- Router / Dispatcher (callTool.ts)
- Handler Layer (each core/* Handler)
c. **Schema & Validation**
- Types (types.ts)
- Validators (validators.ts)
d. **External Systems**
- Google Calendar REST API
- External Client (LLM or CLI)
- (Optional) Docker container or hosting environment
e. **CI/CD & Deployment**
- GitHub Actions CI (ci.yml)
- Dockerfile for container image

##### Relationships & Data Flows
- **Startup** (arrowed flow):
1. MCP Server boot → check token store →
2. If needed, spawn OAuth HTTP Server → User’s browser → Google Auth → Redirect to local callback → token written
3. MCP Server ready
- **Request Handling**:
- External Client → MCP Server (callTool endpoint) → Dispatcher
- Dispatcher → Appropriate Handler → uses Token Manager to call Google Calendar API
- Handler receives Google API response → applies schema/validation → returns response to client

##### Architectural Patterns & Principles
- **Modular Handler Pattern**: one handler per calendar operation
- **Single Responsibility**: separate modules for auth, dispatch, handlers, schemas
- **Configurable OAuth Flow**: ports range, token persistence
- **Testability**: mocks for Google API and filesystem in Vitest tests

- Component labels: “OAuth Server”, “Token Manager”, “MCP Dispatcher”, “Calendar Handlers”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        Client["External Client (LLM/CLI)"]:::external
        Browser["User Browser"]:::external
        GoogleAPI["Google Calendar API"]:::external
    end

    %% MCP Server
    subgraph "MCP Server"
        direction TB
        %% OAuth Module
        subgraph "OAuth Module"
            direction TB
            CredLoader["Credentials Loader"]:::internal
            TokenManager["Token Manager"]:::internal
            AuthServerEntry["Auth Server Entry"]:::internal
            AuthServerImpl["Auth Server Implementation"]:::internal
            AuthUtils["Auth Utility Helpers"]:::internal
            TokenStore[(.gcp-saved-tokens.json)]:::datastore
        end

        %% Schema & Validation
        SchemaSub["Schema & Validation"]:::internal
        Types["Type Definitions"]:::internal
        Validators["Validators"]:::internal

        %% Core Server
        subgraph "MCP Core Server"
            direction TB
            EntryPoint["Entry Point & Bootstrap"]:::internal
            Dispatcher["Dispatcher / Router"]:::internal
        end

        %% Handler Layer
        subgraph "Handler Layer"
            direction TB
            BaseHandler["BaseToolHandler"]:::internal
            CreateHandler["CreateEventHandler"]:::internal
            DeleteHandler["DeleteEventHandler"]:::internal
            FreeBusyHandler["FreeBusyEventHandler"]:::internal
            ListCalendarsHandler["ListCalendarsHandler"]:::internal
            ListColorsHandler["ListColorsHandler"]:::internal
            ListEventsHandler["ListEventsHandler"]:::internal
            SearchEventsHandler["SearchEventsHandler"]:::internal
            UpdateHandler["UpdateEventHandler"]:::internal
        end
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        CI["GitHub Actions Workflow"]:::infra
        Docker["Docker Containerization"]:::infra
        BuildScript["Build Scripts & Tools"]:::infra
    end

    %% Startup Flow
    EntryPoint -->|"check tokens"| TokenManager
    TokenManager -->|"token missing?"| AuthServerEntry
    AuthServerEntry --> AuthServerImpl
    AuthServerImpl -->|"open consent"| Browser
    Browser -->|"grant auth"| GoogleAPI
    GoogleAPI -->|"callback"| AuthServerImpl
    AuthServerImpl -->|write tokens| TokenStore
    TokenStore --> TokenManager
    TokenManager --> EntryPoint

    %% Request Flow
    Client -->|"MCP request"| EntryPoint
    EntryPoint --> Dispatcher
    Dispatcher --> BaseHandler
    Dispatcher --> CreateHandler
    Dispatcher --> DeleteHandler
    Dispatcher --> FreeBusyHandler
    Dispatcher --> ListCalendarsHandler
    Dispatcher --> ListColorsHandler
    Dispatcher --> ListEventsHandler
    Dispatcher --> SearchEventsHandler
    Dispatcher --> UpdateHandler
    CreateHandler -->|"API call"| GoogleAPI
    DeleteHandler -->|"API call"| GoogleAPI
    FreeBusyHandler -->|"API call"| GoogleAPI
    ListCalendarsHandler -->|"API call"| GoogleAPI
    ListColorsHandler -->|"API call"| GoogleAPI
    ListEventsHandler -->|"API call"| GoogleAPI
    SearchEventsHandler -->|"API call"| GoogleAPI
    UpdateHandler -->|"API call"| GoogleAPI
    GoogleAPI -->|"response"| Dispatcher
    Dispatcher --> Client

    %% Schema usage
    Dispatcher --> Types
    Dispatcher --> Validators
    BaseHandler --> Types
    BaseHandler --> Validators

    %% CI/CD flows
    CI --> Docker
    CI --> BuildScript

    %% Click Events
    click CredLoader "https://github.com/nspady/google-calendar-mcp/blob/main/src/auth/client.ts"
    click TokenManager "https://github.com/nspady/google-calendar-mcp/blob/main/src/auth/tokenManager.ts"
    click AuthServerEntry "https://github.com/nspady/google-calendar-mcp/blob/main/src/auth-server.ts"
    click AuthServerImpl "https://github.com/nspady/google-calendar-mcp/blob/main/src/auth/server.ts"
    click AuthUtils "https://github.com/nspady/google-calendar-mcp/blob/main/src/auth/utils.ts"
    click EntryPoint "https://github.com/nspady/google-calendar-mcp/blob/main/src/index.ts"
    click Dispatcher "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/callTool.ts"
    click BaseHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/BaseToolHandler.ts"
    click CreateHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/CreateEventHandler.ts"
    click DeleteHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/DeleteEventHandler.ts"
    click FreeBusyHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/FreeBusyEventHandler.ts"
    click ListCalendarsHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/ListCalendarsHandler.ts"
    click ListColorsHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/ListColorsHandler.ts"
    click ListEventsHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/ListEventsHandler.ts"
    click SearchEventsHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/SearchEventsHandler.ts"
    click UpdateHandler "https://github.com/nspady/google-calendar-mcp/blob/main/src/handlers/core/UpdateEventHandler.ts"
    click Types "https://github.com/nspady/google-calendar-mcp/blob/main/src/schemas/types.ts"
    click Validators "https://github.com/nspady/google-calendar-mcp/blob/main/src/schemas/validators.ts"
    click BuildScript "https://github.com/nspady/google-calendar-mcp/blob/main/scripts/build.js"
    click CI "https://github.com/nspady/google-calendar-mcp/blob/main/.github/workflows/ci.yml"
    click Docker "https://github.com/nspady/google-calendar-mcp/tree/main/Dockerfile"

    %% Styles
    classDef internal fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef external fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef infra fill:#e0e0e0,stroke:#616161,color:#212121
    classDef datastore fill:#ffe082,stroke:#f9a825,color:#5d4037
```
