# modelcontextprotocol/modelcontextprotocol architecture

> Architecture diagram of the GitHub repository modelcontextprotocol/modelcontextprotocol, 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/modelcontextprotocol/modelcontextprotocol
- Repository: https://github.com/modelcontextprotocol/modelcontextprotocol

## Overview

##### Project type and purpose
- This repo is an open-source specification and documentation project. It defines the “Model Context Protocol” (MCP) schema in TypeScript and publishes it as JSON Schema, and it hosts extensive MDX-based docs powered by a static site generator (Mintlify).

##### File structure
- Top-level:
- schema/ – TypeScript + JSON Schema definitions, versioned by spec date (e.g., 2024-11-05, 2025-03-26, draft)
- docs/ – MDX files organizing guides, tutorials, concepts, specification chapters, images, code snippets
- .github/workflows/ – CI workflows for formatting and build
- package.json, tsconfig.json – Node/TypeScript project config
- Key patterns:
- Versioned spec directories under both docs/specification and schema
- docs/docs holds conceptual overviews, docs/quickstart holds usage examples, docs/sdk holds client/server SDK guides
- CI pipelines run lint/format on docs and schemas, likely build/publish website

##### README for additional insights
- Confirms: TypeScript schema → JSON Schema
- Docs are published at modelcontextprotocol.io using Mintlify
- Focus is on specification maintenance and docs generation

##### Main components
a. Schema Module
- TypeScript sources (schema/**/*.ts)
- JSON Schema outputs (schema/**/*.json)
b. Documentation Module
- MDX source files (docs/**/*.mdx)
- Static Site Generator (Mintlify CLI)
c. CI/CD
- GitHub Actions workflows: lint/format checks, site build, deploy
d. Hosting / CDN
- modelcontextprotocol.io
e. Consumers
- Developers pulling JSON Schema for validation
- Doc readers visiting website
f. Versioning
- Release branches or version tags mapping to schema/2025-03-26, 2024-11-05, draft

##### Architectural patterns and principles
- “Source of truth” separation: schema code vs. docs content
- Versioned directories ensure backward-compatible spec releases
- CI as single orchestration for code quality, build, and deployment
- Static site generation for performance and security

##### Relevant technologies / frameworks
- Node.js, TypeScript
- JSON Schema
- MDX (Markdown + JSX)
- Mintlify (SSG / documentation platform)
- GitHub Actions

## Diagram (Mermaid)

```mermaid
graph TD
    %% Schema Module
    subgraph "Schema Module"
        subgraph "Versioned Specs"
            ST1["2024-11-05/schema.ts"]:::code
            SJ1["2024-11-05/schema.json"]:::artifact
            ST2["2025-03-26/schema.ts"]:::code
            SJ2["2025-03-26/schema.json"]:::artifact
            ST3["draft/schema.ts"]:::code
            SJ3["draft/schema.json"]:::artifact
        end
    end

    ST1 -->|"compile"| SJ1
    ST2 -->|"compile"| SJ2
    ST3 -->|"compile"| SJ3

    click ST1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2024-11-05/schema.ts"
    click SJ1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2024-11-05/schema.json"
    click ST2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.ts"
    click SJ2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-03-26/schema.json"
    click ST3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/draft/schema.ts"
    click SJ3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/draft/schema.json"

    %% Documentation Module
    subgraph "Documentation Module"
        subgraph "MDX Sources"
            DM1["clients.mdx"]:::code
            DM2["introduction.mdx"]:::code
            DM3["faqs.mdx"]:::code
            DM4["examples.mdx"]:::code
            DM5["style.css"]:::code
            subgraph "Development"
                DD1["contributing.mdx"]:::code
                DD2["roadmap.mdx"]:::code
                DD3["updates.mdx"]:::code
            end
            subgraph "Quickstart"
                DQ1["client.mdx"]:::code
                DQ2["server.mdx"]:::code
                DQ3["user.mdx"]:::code
            end
            subgraph "SDK/Java"
                DS1["mcp-client.mdx"]:::code
                DS2["mcp-overview.mdx"]:::code
                DS3["mcp-server.mdx"]:::code
            end
            DG1["concepts/*.mdx"]:::code
            DG2["tools/*.mdx"]:::code
            DG3["tutorials/*.mdx"]:::code
            subgraph "Specification Versions"
                DSV1["2024-11-05/**/*.mdx"]:::code
                DSV2["2025-03-26/**/*.mdx"]:::code
                DSV3["draft/**/*.mdx"]:::code
                DSV4["contributing.mdx"]:::code
                DSV5["versioning.mdx"]:::code
            end
        end
    end

    click DM1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/clients.mdx"
    click DM2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/introduction.mdx"
    click DM3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/faqs.mdx"
    click DM4 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/examples.mdx"
    click DM5 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/style.css"
    click DD1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/development/contributing.mdx"
    click DD2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/development/roadmap.mdx"
    click DD3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/development/updates.mdx"
    click DQ1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/quickstart/client.mdx"
    click DQ2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/quickstart/server.mdx"
    click DQ3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/quickstart/user.mdx"
    click DS1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/sdk/java/mcp-client.mdx"
    click DS2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/sdk/java/mcp-overview.mdx"
    click DS3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/sdk/java/mcp-server.mdx"
    click DG1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/docs/concepts/*.mdx"
    click DG2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/docs/tools/*.mdx"
    click DG3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/tutorials/*.mdx"
    click DSV1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2024-11-05/**/*.mdx"
    click DSV2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-03-26/**/*.mdx"
    click DSV3 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/draft/**/*.mdx"
    click DSV4 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/contributing.mdx"
    click DSV5 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/versioning.mdx"

    %% Aggregators for build
    JSON_OUT["JSON Schema Outputs"]:::artifact
    MDX_SRC["MDX Sources Aggregate"]:::code

    SJ1 --> JSON_OUT
    SJ2 --> JSON_OUT
    SJ3 --> JSON_OUT
    DM1 --> MDX_SRC
    DM2 --> MDX_SRC
    DM3 --> MDX_SRC
    DM4 --> MDX_SRC
    DM5 --> MDX_SRC
    DD1 --> MDX_SRC
    DD2 --> MDX_SRC
    DD3 --> MDX_SRC
    DQ1 --> MDX_SRC
    DQ2 --> MDX_SRC
    DQ3 --> MDX_SRC
    DS1 --> MDX_SRC
    DS2 --> MDX_SRC
    DS3 --> MDX_SRC
    DG1 --> MDX_SRC
    DG2 --> MDX_SRC
    DG3 --> MDX_SRC
    DSV1 --> MDX_SRC
    DSV2 --> MDX_SRC
    DSV3 --> MDX_SRC
    DSV4 --> MDX_SRC
    DSV5 --> MDX_SRC

    %% Site Build
    subgraph "Site Build"
        Pkg["package.json"]:::config
        TSC["tsconfig.json"]:::config
        Meta["docs/docs.json"]:::config
        SSG["Static Site Generator\n(Mintlify CLI)"]:::process
    end

    click Pkg "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/package.json"
    click TSC "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/tsconfig.json"
    click Meta "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/docs.json"

    JSON_OUT --> SSG
    MDX_SRC --> SSG
    Pkg --> SSG
    TSC --> SSG
    Meta --> SSG

    %% CI/CD
    GIT["Git Push"]:::external
    CI1["GitHub Actions\n(main.yml)"]:::ci
    CI2["GitHub Actions\n(markdown-format.yml)"]:::ci

    click CI1 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/.github/workflows/main.yml"
    click CI2 "https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/.github/workflows/markdown-format.yml"

    GIT --> CI1
    GIT --> CI2
    CI1 --> SSG
    CI1 --> Hosting

    %% Hosting
    Hosting["modelcontextprotocol.io\n(CDN/Hosting)"]:::cloud
    SSG --> Hosting

    %% Consumers
    subgraph "Consumers"
        Dev["Developers\n(JSON Schema)"]:::user
        Readers["Doc Readers\n(Website)"]:::user
    end

    JSON_OUT --> Dev
    Hosting --> Readers

    %% Styles
    classDef code fill:#D0E8FF,stroke:#0055AA,color:#003366
    classDef artifact fill:#DFFFE0,stroke:#228822,color:#115511
    classDef process fill:#FFF0C0,stroke:#CC9900,color:#995500
    classDef config fill:#E8E8E8,stroke:#555555,color:#333333
    classDef ci fill:#FFD9B3,stroke:#FF6600,color:#993300
    classDef cloud fill:#E0F0FF,stroke:#7777CC,color:#334477
    classDef external fill:#F0F0F0,stroke:#AAAAAA,color:#666666
    classDef user fill:#F5E6FF,stroke:#AA33AA,color:#660066
```
