# cloudflare/mcp-server-cloudflare architecture

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

- Interactive diagram: https://gitdiagram.com/cloudflare/mcp-server-cloudflare
- Repository: https://github.com/cloudflare/mcp-server-cloudflare

## Overview

##### Main Components
- Server Entry Points & Core Application Logic:
- Main TypeScript files in the src directory (index.ts, init.ts, main.ts) which essentially kick off and configure the MCP server.
- Tools Modules:
- “src/tools” directory as a separate module layer. Each file (e.g., analytics.ts, bindings.ts, cron.ts, d1.ts, durable-objects.ts, kv.ts, queues.ts, workers.ts, workflows.ts, etc.) corresponds to specific Cloudflare API functionalities.
- Utility Functions:
- A shared utility layer (src/utils) where cross-cutting helper functions, type definitions, and additional logic are defined.
- Test Suite:
- “tests” directory (including mocks, setups, and specific tool tests) as a testing layer that validates the functionality of each module.
- External Cloudflare Services:
- External services (Cloudflare API endpoints for Workers, KV, R2, D1, Durable Objects, etc.) that the MCP Server calls to carry out its operations.
- Authentication & CLI/Client Integration:
- Since the server uses “wrangler login” for authentication and integration with MCP Clients like Claude Desktop, indicate the authentication flow and client interaction points.

##### Relationships & Interactions
- The Startup & Initialization Flow:
- Tools as the Functional Interface:
- External API Integration:
- Utility Layer Integration:
- That each tool module relies on shared helper functions and types from the utils layer.
- Testing & Mocks:

##### Architectural Patterns & Design Principles
- Modular Design:
- The clear separation of tool modules and utility functions indicates a modular architecture, so separate each tool as its own component while showing shared dependencies.
- Layered Architecture:
- Differentiate the core business logic (server entry and tools) from peripheral layers (utils, configuration, and tests). This can be represented in horizontal layers.
- Dependency Injection / Loose Coupling:
- Optionally mention how commands are handled in a loosely coupled manner—each tool can be executed independently by the core dispatching logic.

##### Relevant Technologies and Frameworks
- TypeScript for language
- Use of Vitest as the testing framework and MSW for API mocking
- Wrangler CLI for Cloudflare authentication and deployment
- Cloudflare API endpoints representing external services

##### Putting It All Together
- Branch out to the “Tools Module” grouping that encapsulates different Cloudflare API functionalities.
- A side layer for “Utilities” that service each module.
- On the external side, group the various Cloudflare services which the tools will interact with.
- Optionally, add a testing block that verifies command and tool communication.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Server Core: Entry Points & Core Application Logic
    subgraph "Server Core"
        server_index["index.ts"]:::core
        server_init["init.ts"]:::core
        server_main["main.ts"]:::core
    end

    %% Tools Modules: Cloudflare API functionalities
    subgraph "Tools Modules"
        tools_dispatcher["Tools Dispatcher"]:::tools
        tools_analytics["analytics.ts"]:::tools
        tools_bindings["bindings.ts"]:::tools
        tools_cron["cron.ts"]:::tools
        tools_d1["d1.ts"]:::tools
        tools_durable["durable-objects.ts"]:::tools
        tools_kv["kv.ts"]:::tools
        tools_queues["queues.ts"]:::tools
        tools_r2["r2.ts"]:::tools
        tools_routing["routing.ts"]:::tools
        tools_secrets["secrets.ts"]:::tools
        tools_templates["templates.ts"]:::tools
        tools_versions["versions.ts"]:::tools
        tools_workers_ai["workers-ai.ts"]:::tools
        tools_workers_for_platforms["workers-for-platforms.ts"]:::tools
        tools_workers["workers.ts"]:::tools
        tools_workflows["workflows.ts"]:::tools
        tools_wrangler["wrangler.ts"]:::tools
        tools_zones["zones.ts"]:::tools
    end

    %% Utility Functions: Shared helpers & types
    subgraph "Utility Functions"
        utils_c3["c3.ts"]:::utils
        utils_helpers["helpers.ts"]:::utils
        utils_types["types.ts"]:::utils
        utils_wrangler["wrangler.ts"]:::utils
    end

    %% External Cloudflare Services
    subgraph "External Cloudflare Services"
        external_workers["Cloudflare Workers API"]:::external
        external_kv["Cloudflare KV API"]:::external
        external_r2["Cloudflare R2 API"]:::external
        external_d1["Cloudflare D1 API"]:::external
        external_durable["Cloudflare Durable Objects API"]:::external
        external_zones["Cloudflare Zones API"]:::external
        external_analytics["Cloudflare Analytics API"]:::external
    end

    %% Test Suite: Mocks, Setup & Integration Tests
    subgraph "Test Suite"
        test_setup["tests/setup.ts"]:::test
        test_setup_nomws["tests/setup-no-msw.ts"]:::test
        test_mocks["tests/mocks"]:::test
        test_tools["tests/tools"]:::test
        test_utils["tests/utils"]:::test
    end

    %% Relationships: Server Initialization Flow
    server_index -->|"initializes"| server_init
    server_init -->|"configures"| server_main
    server_main -->|"dispatches"| tools_dispatcher

    %% Tools Dispatcher executing individual tools
    tools_dispatcher -->|"executes"| tools_analytics
    tools_dispatcher -->|"executes"| tools_bindings
    tools_dispatcher -->|"executes"| tools_cron
    tools_dispatcher -->|"executes"| tools_d1
    tools_dispatcher -->|"executes"| tools_durable
    tools_dispatcher -->|"executes"| tools_kv
    tools_dispatcher -->|"executes"| tools_queues
    tools_dispatcher -->|"executes"| tools_r2
    tools_dispatcher -->|"executes"| tools_routing
    tools_dispatcher -->|"executes"| tools_secrets
    tools_dispatcher -->|"executes"| tools_templates
    tools_dispatcher -->|"executes"| tools_versions
    tools_dispatcher -->|"executes"| tools_workers_ai
    tools_dispatcher -->|"executes"| tools_workers_for_platforms
    tools_dispatcher -->|"executes"| tools_workers
    tools_dispatcher -->|"executes"| tools_workflows
    tools_dispatcher -->|"executes"| tools_wrangler
    tools_dispatcher -->|"executes"| tools_zones

    %% Tools Modules calling External Cloudflare APIs
    tools_analytics -->|"calls"| external_analytics
    tools_kv -->|"calls"| external_kv
    tools_r2 -->|"calls"| external_r2
    tools_d1 -->|"calls"| external_d1
    tools_durable -->|"calls"| external_durable
    tools_workers_ai -->|"calls"| external_workers
    tools_workers_for_platforms -->|"calls"| external_workers
    tools_workers -->|"calls"| external_workers
    tools_zones -->|"calls"| external_zones

    %% Tools Modules utilizing Utility Functions
    tools_dispatcher -->|"utilizes"| utils_helpers

    %% Test Suite integration and mocks
    test_setup -->|"integrates"| server_main
    test_mocks -->|"mocks"| tools_dispatcher

    %% Click Events for Core Files
    click server_index "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/index.ts"
    click server_init "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/init.ts"
    click server_main "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/main.ts"

    %% Click Events for Tools Modules
    click tools_analytics "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/analytics.ts"
    click tools_bindings "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/bindings.ts"
    click tools_cron "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/cron.ts"
    click tools_d1 "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/d1.ts"
    click tools_durable "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/durable-objects.ts"
    click tools_kv "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/kv.ts"
    click tools_queues "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/queues.ts"
    click tools_r2 "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/r2.ts"
    click tools_routing "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/routing.ts"
    click tools_secrets "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/secrets.ts"
    click tools_templates "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/templates.ts"
    click tools_versions "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/versions.ts"
    click tools_workers_ai "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/workers-ai.ts"
    click tools_workers_for_platforms "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/workers-for-platforms.ts"
    click tools_workers "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/workers.ts"
    click tools_workflows "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/workflows.ts"
    click tools_wrangler "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/wrangler.ts"
    click tools_zones "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/tools/zones.ts"

    %% Click Events for Utility Functions
    click utils_c3 "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/utils/c3.ts"
    click utils_helpers "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/utils/helpers.ts"
    click utils_types "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/utils/types.ts"
    click utils_wrangler "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/src/utils/wrangler.ts"

    %% Click Events for Test Suite
    click test_setup "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/tests/setup.ts"
    click test_setup_nomws "https://github.com/cloudflare/mcp-server-cloudflare/blob/main/tests/setup-no-msw.ts"
    click test_mocks "https://github.com/cloudflare/mcp-server-cloudflare/tree/main/tests/mocks"
    click test_tools "https://github.com/cloudflare/mcp-server-cloudflare/tree/main/tests/tools"
    click test_utils "https://github.com/cloudflare/mcp-server-cloudflare/tree/main/tests/utils"

    %% Styles
    classDef core fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef tools fill:#a6cee3,stroke:#333,stroke-width:2px;
    classDef utils fill:#b2df8a,stroke:#333,stroke-width:2px;
    classDef external fill:#fb9a99,stroke:#333,stroke-width:2px;
    classDef test fill:#cab2d6,stroke:#333,stroke-width:2px;
```
