Model Context Protocol (MCP) Schema for Rust

Rust 版 Model Context Protocol（MCP）Schema

官方 Model Context Protocol（MCP）Schema 的类型安全 Rust 实现，支持所有官方 MCP 协议版本：

• 2026-07-28（默认）
• 2025-11-25
• 2025-06-18
• 2025-03-26
• 2024-11-05
• draft

此仓库中的 MCP Schema 由官方 Model Context Protocol 自动生成，确保始终保持最新，并与最新官方规范一致。

---

注意： 此 crate 仅提供 MCP Schema 的实现。

如果你正在寻找用于构建 MCP 服务和客户端的高性能异步工具包，请查看 rust-mcp-sdk。 专注于应用逻辑，其余工作交给 rust-mcp-sdk！

---

目录：

• 功能

• 如何使用此 crate？

• Schema 版本

  • 如何切换不同的 Schema 版本？
  • 如何生成 Schema？

• 什么是 schema_utils？

• schema_utils 有什么作用？

• 使用示例

  • 在 MCP 服务上检测 CallToolRequest 消息
  • 在 MCP 服务上创建 CallToolResult 响应
  • 在 MCP 客户端中检测 CallToolResult 响应消息

• 使用示例（不使用 schema_utils）

  • 在 MCP 服务上检测 CallToolRequest 消息（不使用 schema_utils）

• 贡献

功能

• 🧩 MCP 协议规范的类型安全实现。
• 💎 自动生成的 Schema 始终与官方 Schema 规范保持同步。
• 📜 包含所有正式发布的版本：2026-07-28、2025-11-25、2025-06-18、2025-03-26、2024-11-05，以及用于早期采用的 draft 版本。
• 🛠 附带 Schema 实用工具模块（schema_utils），提升效率并确保开发过程的健全性。

如何使用这个 crate？

这个 Crate 提供了官方 Model Context Protocol（MCP）Schema 的 Rust 实现。

Model Context Protocol（MCP）是一种开放协议，可实现大模型应用与外部数据源和工具之间的无缝集成。无论你是在构建 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都提供了一种标准化方式，将大模型与其所需的上下文连接起来。

这个 crate 包含 Schema，并通过 serde_json 提供 serialization / deserialization 支持，同时为结构体和枚举提供必要特征的最小实现。这有助于创建和使用各种 MCP 消息，例如请求、响应、通知和错误。

这个 crate 可用于在 Rust 中开发 MCP 服务 或 MCP 客户端。 有关 MCP 架构的更多信息，请参阅官方文档。

---

了解一下 rust-mcp-sdk，这是一个基于 rust-mcp-schema、用于构建 MCP 服务和客户端的高性能异步工具包。专注于应用逻辑，rust-mcp-sdk 会处理其余工作！

---

Schema 版本

此仓库提供所有正式发布的 Schema 版本，包括草案版本，让你能够提前准备和调整应用，以适配即将发布的官方 Schema 版本。

• 2026-07-28（默认）
• 2025-11-25
• 2025-06-18
• 2025-03-26
• 2024-11-05
• 草案

如何在不同的 Schema 版本之间切换？

默认情况下，启用的是最新版本的 MCP 协议 Schema。

每个 Schema 版本都对应一个 Cargo 特性，可在项目的 Cargo.toml 中启用。

如果需要，可以同时启用多个 Schema 版本。非默认版本可通过显式命名的模块访问，例如：

• rust_mcp_schema::mcp_2025_06_18
• rust_mcp_schema::mcp_2025_11_25

📌 注意：最近的三个 Schema（2026_07_28、2025_11_25 和 draft）也会重新导出到 crate 根目录，因此彼此互斥——一次最多启用其中一个。较早的版本（2025_06_18、2025_03_26、2024_11_05）仅能通过模块访问，可与上述任意一个版本组合使用。

示例：启用 2025-06-18 版本的 Schema：

# Cargo.toml
rust-mcp-schema = { version: 2.0.0 , default-features = false, features=["2025_06_18"] }

示例：启用 `draft`` 版本的 Schema：

#Cargo.toml
rust-mcp-schema = { version: 2.0.0 , default-features = false, features=["draft"] }

如何生成 Schema？

Schema 根据原始 Model Context Protocol（MCP）仓库中的官方 schema.ts 和 schema.json 文件生成。

通过使用定制版本的 typify，以及额外的预处理和后处理步骤，Schema 规范会被转换为 Rust 代码。

📌 注意

用于根据 schema.ts 和 schema.json 生成 Schema 的代码未包含在此仓库中。不过，我正在考虑未来将其作为 CLI 工具提供，让开发者能够生成可直接集成到项目中的 Rust 版 MCP Schema。

什么是 schema_utils？

此 crate 中 MCP 架构的 Rust 实现会根据官方 MCP GitHub 仓库自动生成。

mcp_schema.rs 提供所有核心结构体和枚举，并支持序列化和反序列化，你可以按需使用并扩展其功能。

为了简化开发、改善编译时类型检查并减少潜在错误，我们实现了实用类型和函数，提供类型更强的对象和实现，同时不修改原始生成的架构。

有关详情，请参阅 schema_utils.rs。

📌 注意

schema_utils 是可选的。默认情况下，它通过 schema_utils Cargo 功能启用，可从 rust_mcp_schema::schema_utils 使用。

如果你不想使用 schema_utils，可以直接使用 mcp_schema.rs 中提供的枚举和结构体，根据需要进行调整，并围绕它们创建自己的实用类型和函数。

请访问用法示例（不使用 schema_utils），查看另一种实现方式。

schema_utils 有什么作用？

官方架构定义了统一的 JsonrpcMessage 类型，涵盖 MCP 协议中的所有消息和通知。

为提升类型安全性和易用性，schema_utils 将 JsonrpcMessage 分为两类：ClientMessage 和 ServerMessage。每类都包含标准消息和自定义消息对应的类型。

有关详情，请参阅 schema_utils.rs 和用法示例部分。

用法示例

:point_right: 以下示例仅介绍架构消息的序列化和反序列化，并假设应用已将 JSON-RPC 消息作为字符串接收。

在 MCP 服务上检测 CallToolRequest 消息

以下代码片段演示如何将以 JSON 字符串表示的 MCP 消息反序列化为 ClientMessage，以及如何识别其是否为 CallToolRequest 消息。

注意：ClientMessage 表示从 MCP 客户端发送的 MCP 消息。以下代码演示 MCP 服务如何反序列化从 MCP 客户端接收的消息。

pub fn handle_message(message_payload: &str) -> std::result::Result<(), RpcError> {
    // Deserialize message into ClientMessage.
    let message = ClientMessage::from_str(message_payload)?;

    // Check if the message is a Request
    if let ClientMessage::Request(client_request) = message {
        // Requests delegate to the schema-generated `ClientRequest` enum via `ClientJsonrpcRequest::Known`
        if let ClientJsonrpcRequest::Known(ClientRequest::CallToolRequest(call_tool_request)) = client_request {
            // Process the CallToolRequest (and eventually send a CallToolResult back to the client)
            handle_call_tool_request(call_tool_request);
        }
    }
    Ok(())
}

请参阅 examples/mcp_server_handle_message.rs，了解处理所有可能 ClientMessage 变体的完整 match 实现。

在 MCP 服务上创建 CallToolResult 响应。

收到 CallToolRequest 后，MCP 服务应返回 CallToolResult 消息。

此代码片段演示如何创建 CallToolResult、将其序列化为字符串，并通过传输层发送回客户端。

    // create a CallToolResult object (the builder sets `resultType: "complete"`)
    let tool_result = CallToolResult::text_content(vec![TextContent::new(
        "Sunny, 22°C in Paris.".to_string(),
        None,
        None,
    )]);

    // wrap it in a JSON-RPC response envelope addressed to the request's `id`
    let message = ServerJsonrpcResponse::new(RequestId::Integer(0), tool_result.into());

    // Serialize the MCP message into a valid JSON string for sending to the client
    let json_payload = serde_json::to_string(&message).unwrap();

    println!("{}", json_payload);

输出：

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
    "content": [{ "type": "text", "text": "Sunny, 22°C in Paris." }],
    "resultType": "complete"
  }
}

在 MCP 客户端中检测 CallToolResult 响应消息：

fn handle_message(message_payload: &str) -> std::result::Result<(), AppError> {
    // Deserialize message into ServerMessage.
    // ServerMessage represents a message sent by an MCP Server and received by an MCP Client.
    let mcp_message = ServerMessage::from_str(message_payload)?;

    // Check if the message is a Response type of message
    if let ServerMessage::Response(server_response) = mcp_message {
        // Check if it's a CallToolResult response
        if let ServerResult::CallToolResult(call_tool_result) = &server_response.result {
            // Process the CallToolResult
            handle_call_tool_result(call_tool_result);
        }
    }
    Ok(())
}

请参阅 mcp_client_handle_message.rs，了解处理所有可能 ServerMessage 变体的完整 match 实现。

用法示例（不使用 schema_utils）

如果你不想使用 schema_utils，可以直接在应用中使用生成的类型，或围绕它们构建自定义实用工具。

在 MCP 服务上检测 CallToolRequest 消息（不使用 schema_utils）

以下代码示例演示如何在 MCP 服务上检测 CallToolRequest 消息：

fn handle_message(message_payload: &str) -> std::result::Result<(), AppError> {
    // Deserialize the JSON-RPC payload directly into ClientRequest.
    // Its `Deserialize` impl dispatches on the `method` field.
    let client_request: ClientRequest = serde_json::from_str(message_payload).unwrap();

    // Check it's a "tools/call" request
    if let ClientRequest::CallToolRequest(call_tool_request) = client_request {
        // Now that we can handle the message, we simply print out the details.
        println!("CallTool request received!");

        println!("Tool name : {:?} ", call_tool_request.params.name);
        println!("Arguments : {:?} ", call_tool_request.params.arguments);
    }

    Ok(())
}

参与贡献

欢迎所有希望参与贡献的人！更多详情请参阅贡献指南。

所有贡献，包括问题和拉取请求，都必须遵守 Rust 行为准则。

除非另有明确说明，您提交以纳入 rust-mcp-schema 的任何贡献均依据 MIT License 的条款提供，不附带任何额外条件或限制。