# rust-mcp-stack/rust-mcp-schema architecture

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

- Interactive diagram: https://gitdiagram.com/rust-mcp-stack/rust-mcp-schema
- Repository: https://github.com/rust-mcp-stack/rust-mcp-schema

## Overview

##### Project type and purpose
- This is an open-source Rust library crate (“rust-mcp-schema”) that provides a type-safe implementation of the Model Context Protocol (MCP) schema.
- It auto-generates Rust code from the official MCP JSON/TypeScript schema, offers utility wrappers (`schema_utils`), and includes examples, tests, and CI/CD workflows.

##### File structure
- Top-level directories:
- src/ – core code; houses `rust-mcp-schema.rs` and `generated_schema/` (per-version MCP schemas plus `schema_utils`)
- examples/ – sample apps showing how to use the crate
- tests/ – unit/integration tests validating serialization/deserialization
- scripts/ – helper scripts (`run_clippy.sh`, `run_test.sh`) for local development
- .github/workflows/ – CI pipelines (lint, test, publish, release)
- .cargo/config.toml, Cargo.toml, Cargo.lock – Rust/Cargo build configuration
- Patterns/Choices:
- Code-generation pipeline feeding into `src/generated_schema`
- Feature flags in Cargo.toml to switch schema versions
- Separation of auto-generated code (mcp_schema.rs) vs. handwritten utilities (schema_utils.rs)

##### Key README insights
- The crate only contains schema definitions; actual protocol clients/servers are in a separate “rust-mcp-sdk” crate.
- Schemas for versions `2024_11_05`, `2025_03_26`, and `draft` are generated from upstream spec via a customized `typify` workflow.
- Utility functions in `schema_utils` boost type safety by splitting messages into `ClientMessage` and `ServerMessage`.

##### Main components
a. External Specification Source
– Official MCP repo (JSON/TS schema files).
b. Code-Generation Pipeline
– Pre-processing scripts (not in repo), `typify` tool, post-processing.
– Input: schema.ts/json → Output: Rust modules under `src/generated_schema/{version}/mcp_schema.rs` & `schema_utils.rs`.
c. Generated Code Modules
– Versioned schema modules (2024_11_05, 2025_03_26, draft).
– `schema_utils` wrappers.
d. Library API
– Exposed in `src/rust-mcp-schema.rs`, re-exporting generated types and features.
e. Examples & Tests
– examples/*.rs demonstrate client/server message handling.
– tests/ validate serialization, version switching, edge cases.
f. CI/CD & Release
– GitHub Actions workflows (.github/workflows/ci.yml, lint-pr.yml, publish.yml, release-pr.yml).
– scripts/run_clippy.sh, run_test.sh for local invocation.
g. Downstream Consumers
– rust-mcp-sdk, end-user applications relying on the crate.

##### Relationships and data flow
- Pipeline → Generated Code Modules
- Generated Code Modules → Library API
- Library API → Examples & Tests (they import and use API)
- CI/CD orchestrates Pipeline, Tests, Lint, Publish
- End-User Apps ↔ Library API (via Cargo)
- Feature flags (2024_11_05, 2025_03_26, draft) depicted as toggle inputs into Library API.

##### Architectural patterns & design principles
- Single-source code generation: upstream spec drives all versions.
- Separation of concerns: auto-generated code vs. handwritten utilities vs. examples/tests.
- Feature-flagged versioning: enables multiple schema versions within one crate.
- CI/CD as code: automated generation, quality checks, and releases.

##### Technologies, frameworks, and libraries
- Rust & Cargo (crate management, feature flags)
- typify (code generation from JSON/TS)
- serde_json (serialization/deserialization)
- GitHub Actions (CI/CD workflows)
- shell scripts for local lint/test

##### Essential detail & component separation
- Schema version as its own node.
- Feature-flag toggles feeding into the build.
- How shell scripts and workflows trigger generation and testing.
- Downstream SDK and end-user applications as distinct consumers.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Resources
    SpecRepo[(Official MCP Schema Repo)]:::external

    %% Code Generation Pipeline
    subgraph "Code Generation Pipeline"
        CGP[/"Typify & Processing"/]:::process
        CL["run_clippy.sh"]:::process
        RT["run_test.sh"]:::process
    end

    %% CI/CD Workflows
    subgraph "CI/CD Workflows"
        CI["ci.yml"]:::process
        LINT["lint-pr.yml"]:::process
        PUB["publish.yml"]:::process
        REL["release-pr.yml"]:::process
    end

    %% Generated Schema Modules
    subgraph "Generated Schema"
        subgraph "v2024_11_05"
            V1M["mcp_schema.rs"]:::code
            V1U["schema_utils.rs"]:::code
        end
        subgraph "v2025_03_26"
            V2M["mcp_schema.rs"]:::code
            V2U["schema_utils.rs"]:::code
        end
        subgraph "draft"
            DM["mcp_schema.rs"]:::code
            DU["schema_utils.rs"]:::code
        end
        AGG["generated_schema.rs"]:::code
    end

    %% Library API & Config
    subgraph "Library API"
        API["rust-mcp-schema.rs"]:::code
        CF["Cargo.toml"]:::code
    end

    %% Examples
    subgraph "Examples"
        EXC["mcp_client_handle_message.rs"]:::example
        EXS["mcp_server_handle_message.rs"]:::example
    end

    %% Tests
    subgraph "Tests"
        T1["2024_11_05_exclusive.rs"]:::example
        T2["miscellaneous.rs"]:::example
        T3["test_deserialize.rs"]:::example
        T4["test_serialize.rs"]:::example
        TC["common/common.rs"]:::example
        TJ["common/sample_mcp_messages.json"]:::example
    end

    %% Downstream Consumers
    subgraph "Consumers"
        SDK["rust-mcp-sdk"]:::consumer
        APP["End-User Apps"]:::consumer
    end

    %% Relationships
    SpecRepo -->|"schemas"| CGP
    CGP --> CL
    CGP --> RT
    CGP --> V1M
    CGP --> V1U
    CGP --> V2M
    CGP --> V2U
    CGP --> DM
    CGP --> DU

    V1M --> AGG
    V1U --> AGG
    V2M --> AGG
    V2U --> AGG
    DM --> AGG
    DU --> AGG

    AGG --> API
    CF --> API

    API --> EXC
    API --> EXS
    API --> T1
    API --> T2
    API --> T3
    API --> T4

    CI --> CGP
    CI --> EXC
    CI --> T1
    CI --> T2
    CI --> T3
    CI --> T4
    CI --> PUB
    CI --> REL

    API --> SDK
    API --> APP

    %% Click Events
    click CL "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/scripts/run_clippy.sh"
    click RT "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/scripts/run_test.sh"
    click CI "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/.github/workflows/ci.yml"
    click LINT "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/.github/workflows/lint-pr.yml"
    click PUB "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/.github/workflows/publish.yml"
    click REL "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/.github/workflows/release-pr.yml"
    click V1M "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/generated_schema/2024_11_05/mcp_schema.rs"
    click V1U "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/generated_schema/2024_11_05/schema_utils.rs"
    click V2M "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/generated_schema/2025_03_26/mcp_schema.rs"
    click V2U "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/generated_schema/2025_03_26/schema_utils.rs"
    click DM "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/generated_schema/draft/mcp_schema.rs"
    click DU "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/generated_schema/draft/schema_utils.rs"
    click AGG "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/generated_schema.rs"
    click API "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/src/rust-mcp-schema.rs"
    click CF "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/Cargo.toml"
    click EXC "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/examples/mcp_client_handle_message.rs"
    click EXS "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/examples/mcp_server_handle_message.rs"
    click T1 "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/tests/2024_11_05_exclusive.rs"
    click T2 "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/tests/miscellaneous.rs"
    click T3 "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/tests/test_deserialize.rs"
    click T4 "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/tests/test_serialize.rs"
    click TC "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/tests/common/common.rs"
    click TJ "https://github.com/rust-mcp-stack/rust-mcp-schema/blob/main/tests/common/sample_mcp_messages.json"

    %% Styles
    classDef external fill:#ccffcc,stroke:#006600;
    classDef process fill:#ffcc99,stroke:#993300;
    classDef code fill:#cce5ff,stroke:#004085;
    classDef example fill:#e2d7f5,stroke:#4b0082;
    classDef consumer fill:#f0f0f0,stroke:#333333;
```
