How rust-mcp-stack/rust-mcp-schema works
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.