pmcp

PMCP - 实用的模型上下文协议

采用 Toyota Way 质量原则构建的生产级 Rust 模型上下文协议（MCP）实现——速度比 TypeScript 快 16 倍

概述

PMCP 是面向 Rust 的完整 MCP 生态系统，提供构建、测试和部署生产级 MCP 服务所需的一切——使用 Rust，或仅通过配置即可完成：

• 🧩 配置驱动的服务 - 通过 config.toml 构建 SQL 和 OpenAPI/HTTP MCP 服务，或从已编译的捆绑包中提供受治理的 Excel 工作簿——无需 Rust（pmcp-server-toolkit、pmcp-sql-server、pmcp-openapi-server、pmcp-workbook-server）
• 🤝 Agent 与团队 - 构建可部署到任何地方的 Agent 和小型团队：Agent 循环（pmcp-agent）、四个参考团队服务（pmcp-team-servers）和可移植的 AI-Package 格式（pmcp-package）——通过 cargo pmcp agent/team/package 子命令驱动
• 🦀 pmcp SDK - 高性能 Rust crate，全面支持 MCP 协议
• ⚡ cargo-pmcp - 用于脚手架搭建、测试和开发的 CLI 工具包
• 📚 pmcp-book - 包含 27 章的综合参考指南
• 🎓 pmcp-course - 包含测验和练习的实践课程
• 🤖 AI Agent - 用于 AI 辅助开发的 Kiro 和 Claude Code 配置

为什么选择 PMCP？

• 性能：速度比 TypeScript SDK 快 16 倍，内存占用低 50 倍
• 安全性：Rust 的类型系统 + 生产代码中不使用 unwrap()
• 质量：Toyota Way 原则——零容忍技术债务
• 全面性：SDK、工具、文档和 AI 辅助，尽在一个生态系统中

快速开始

根据经验和偏好选择适合你的路径：

🧩 路径 1：仅配置的服务 — 无需 Rust（SQL 和 OpenAPI）

v2.9 新增 — 这消除了将组织数据置于 MCP 之后的最大障碍：你不再需要 Rust 程序员。 在 config.toml 中描述一个基于 SQL 数据库 或任意 OpenAPI / HTTP 后端 的生产级 MCP 服务——声明后端、少量精选工具和 Code Mode 策略——预构建的二进制文件即可提供服务。无需 Rust，无需重新编译。精选工具覆盖常见的约 20%；Code Mode 会在静态、默认拒绝的策略下，根据你的架构或规范生成查询，处理剩余约 80% 的长尾需求。业务分析师在配置中精选 API 范围；其余工作由工具包完成。

SQL — SQLite / Postgres / MySQL / Athena（可从本仓库的检出版本运行）：

cargo install pmcp-sql-server

# Seed a tiny demo DB, then serve it from config alone — two curated tools
# (list_books, books_by_author) + Code Mode for the long tail.
sqlite3 /tmp/pmcp-sqlite-explorer.db < crates/pmcp-sql-server/examples/sqlite-explorer.sql
pmcp-sql-server \
  --config crates/pmcp-sql-server/examples/sqlite-explorer.toml \
  --schema crates/pmcp-sql-server/examples/sqlite-explorer.sql

OpenAPI / HTTP — 任意 REST 后端，支持六种出站身份验证模式，包括 OAuth 透传（服务不持有长期凭据，而是转发调用者自己的令牌，因此只能以已登录用户的身份执行操作）：

cargo install pmcp-openapi-server

# Curated configs ship with the crate — e.g. a London Tube (api_key) showcase and
# a Microsoft-Graph / Excel "Contoso" (oauth_passthrough) example. These talk to a
# live backend, so supply any required credential per the example's comments.
#
# `base_url` is a SLOT, not a baked literal, so the endpoint comes from the
# environment too — the same package moves between environments unchanged.
TFL_BASE_URL=https://api.tfl.gov.uk TFL_APP_KEY=<your-key> \
  pmcp-openapi-server --config crates/pmcp-openapi-server/examples/london-tube.toml

Excel 工作簿 — 受管控的电子表格，每个输出表格作为一个 MCP 工具提供（无需 config.toml，无需架构；唯一输入是已编译的 bundle@version 目录）。将输入和输出定义为命名的 Excel 表格，每个输出表格都会成为一个命名清晰、类型明确的 MCP 工具，其输入架构由 DAG 推导而来：

cargo install pmcp-workbook-server

# Preview the exact tool surface an AI will see — BEFORE you compile or deploy:
cargo pmcp workbook explain pricing.xlsx          # e.g. calculate_tax, estimate_refund

# Compile a governed workbook to a deterministic bundle (ingest → lint → compile →
# reconcile → fail-closed gate → write), then serve one calculation tool per output
# table — plus explain / get_manifest / diff_version / render_workbook — from the bundle alone.
cargo pmcp workbook compile pricing.xlsx --workflow quote --approver alice
pmcp-workbook-server --bundle-dir bundles/[email protected]

想要扩展并部署？ cargo pmcp new my-server --kind sql-server（或 --kind openapi-server / --kind workbook-server）会将同一配置驱动的服务生成脚手架为一个小型 crate，可直接使用 cargo pmcp deploy 部署到 AWS Lambda / Google Cloud Run / Cloudflare / pmcp.run。

了解更多：pmcp-book 中的 Config-Driven SQL Servers、OpenAPI 和 Config-Driven Workbook Servers 章节 · pmcp-sql-server · pmcp-openapi-server · pmcp-workbook-server · pmcp-server-toolkit

---

🚀 路径 2：AI 辅助（推荐用于快速原型开发）

借助 AI，在几分钟内构建可用于生产环境的 MCP 服务：

前提条件：

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update

# Install cargo-pmcp
cargo install cargo-pmcp

安装 Claude Code AI Agent：

# Install the mcp-developer subagent (user-level - works across all projects)
curl -fsSL https://raw.githubusercontent.com/paiml/rust-mcp-sdk/main/ai-agents/claude-code/mcp-developer.md \
  -o ~/.claude/agents/mcp-developer.md

# Restart Claude Code

构建你的服务：

You: "Create a weather forecast MCP server with tools for getting current conditions and 5-day forecasts"

Claude Code: [Invokes mcp-developer subagent]

I'll create a production-ready weather MCP server using cargo-pmcp.

$ cargo pmcp new weather-mcp-workspace
$ cd weather-mcp-workspace
$ cargo pmcp add server weather --template minimal

[Implements type-safe tools with validation]
[Adds comprehensive tests and observability]
[Validates quality gates]

✅ Production-ready server complete with 85% test coverage!

你将获得：遵循 Toyota Way 原则的生产就绪代码，包含全面的测试、结构化日志记录、指标收集，且没有任何 clippy 警告。

了解更多：AI 辅助开发课程 | AI Agents README

---

⚡ 路径 3：cargo-pmcp 工具包（推荐用于手动开发）

使用 cargo-pmcp CLI 生成脚手架并构建服务：

安装：

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update

# Install cargo-pmcp
cargo install cargo-pmcp

创建服务：

# Create workspace
cargo pmcp new my-mcp-workspace
cd my-mcp-workspace

# Add a server using a template
cargo pmcp add server myserver --template minimal

# Start development server with hot-reload
cargo pmcp dev --server myserver

# Generate and run tests
cargo pmcp test --server myserver --generate-scenarios
cargo pmcp test --server myserver

# Build for production
cargo build --release

可用模板（cargo pmcp add server <name> --template <t>）：

• minimal - 用于自定义服务的空结构
• calculator - 算术运算（用于学习）
• complete_calculator - 功能齐全的参考实现
• sqlite_explorer - 手写的 Rust 数据库浏览器（备用方案）

配置驱动的类型（cargo pmcp new <name> --kind <k> — 由 TOML 驱动，每个工具无需编写 Rust）：

• sql-server - 从 config.toml 为 SQLite / Postgres / MySQL / Athena 提供 SQL MCP 服务
• openapi-server - 从 config.toml 为任意 OpenAPI / HTTP 后端提供 MCP 服务
• workbook-server - 为受管控的 Excel 工作簿提供 MCP 服务，通过已编译的 bundle@version 目录提供

了解更多：cargo-pmcp 指南

---

🦀 路径 4：直接使用 pmcp SDK（用于精细控制）

直接使用 pmcp crate，实现最大程度的控制：

安装：

[dependencies]
pmcp = "2.0"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
schemars = "0.8"  # For type-safe tools

类型安全的服务示例：

use pmcp::{ServerBuilder, TypedTool, RequestHandlerExtra, Error};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
#[schemars(deny_unknown_fields)]
struct WeatherArgs {
    #[schemars(description = "City name")]
    city: String,

    #[schemars(description = "Number of days (1-5)")]
    days: Option<u8>,
}

#[derive(Debug, Serialize, JsonSchema)]
struct WeatherOutput {
    temperature: f64,
    conditions: String,
}

async fn get_weather(args: WeatherArgs, _extra: RequestHandlerExtra) -> pmcp::Result<WeatherOutput> {
    // Validate
    if args.city.is_empty() {
        return Err(Error::validation("City cannot be empty"));
    }

    let days = args.days.unwrap_or(1);
    if !(1..=5).contains(&days) {
        return Err(Error::validation("Days must be 1-5"));
    }

    // Call weather API...
    Ok(WeatherOutput {
        temperature: 72.0,
        conditions: "Sunny".to_string(),
    })
}

#[tokio::main]
async fn main() -> pmcp::Result<()> {
    let server = ServerBuilder::new()
        .name("weather-server")
        .version("1.0.0")
        .tool("get-weather", TypedTool::new("get-weather", |args, extra| {
            Box::pin(get_weather(args, extra))
        }).with_description("Get weather forecast for a city"))
        .build()?;

    server.run_stdio().await?;
    Ok(())
}

了解更多：pmcp-book | pmcp-course | API 文档

---

PMCP 生态系统组件

🦀 pmcp SDK（Crate）

MCP 协议的高性能 Rust 实现。

主要功能：

• 类型安全的工具：根据 Rust 类型自动生成 JSON Schema
• 多种传输方式：stdio、HTTP/SSE、WebSocket、WASM
• OAuth 支持：完整传递身份验证上下文
• 工作流：支持数组索引的多步骤编排
• MCP Apps：丰富的 HTML UI 小组件，支持实时预览和浏览器 DevTools
• MCP Tasks：共享客户端/服务端状态，并管理任务生命周期 — 有关如何返回指向关联任务的 CallToolResult，请参阅 任务增强型工具结果（SEP-1686） 章节
• Agent Skills（SEP-2640）：只需约 5 行代码即可注册 Agent Skill，并同时在 SEP-2640 技能界面和并行的 MCP 提示词回退界面上提供服务 — 设计上确保两者逐字节相同（需选择启用 skills 功能）
• Tower 中间件：DNS 重绑定防护、CORS、安全标头
• 类型化客户端辅助工具：call_tool_typed、get_prompt_typed，以及带有有界安全上限的自动分页 list_all_*
• 性能：速度比 TypeScript 快 16 倍，支持 SIMD 加速解析
• 质量：不使用 unwrap()，并提供全面的错误处理

最新版本： pmcp = "2.9"

文档：

• API 参考
• pmcp-book
• 示例

---

⚡ cargo-pmcp（CLI 工具包）

覆盖完整开发生命周期的工具包 — 从项目脚手架到生产环境部署。

cargo install cargo-pmcp

cargo pmcp new my-workspace             # Scaffold a new workspace
cargo pmcp add server my-server         # Add a server with best-practice template
cargo pmcp dev --server my-server       # Dev server with hot-reload
cargo pmcp test --server my-server      # Auto-generated scenario tests
cargo pmcp loadtest run                 # Load test with latency percentiles
cargo pmcp pentest run                  # Security audit (32 checks, SARIF output)
cargo pmcp preview --open               # Browser-based widget preview
cargo pmcp workbook explain wb.xlsx     # Preview an Excel workbook's MCP tool surface
cargo pmcp deploy --target aws-lambda   # Deploy to AWS Lambda, GCR, or Cloudflare
cargo pmcp deploy logs --tail           # Stream production logs

覆盖完整开发生命周期：项目脚手架、开发模式、测试、负载测试、安全渗透测试、MCP Apps 预览、架构管理、多目标部署、密钥和 OAuth 设置。

完整命令参考：cargo-pmcp 指南

---

🧩 配置驱动的服务（无需 Rust）

仅凭 config.toml，即可基于 SQL 和 HTTP 后端构建生产级 MCP 服务——该工具包会合成精选工具和 Code Mode 长尾工具，因此通过 MCP 暴露组织数据不再需要 Rust 程序员。

Crate	说明
pmcp-server-toolkit	与后端无关的库：配置类型、[[tools]] 合成器、Code Mode 接线，以及下方二进制程序所依赖的连接器和身份验证接口。
pmcp-sql-server	Shape-A 二进制程序，可通过 config.toml 和架构文件提供 SQL 数据库（SQLite / Postgres / MySQL / Athena）服务。附带可运行的 sqlite-explorer 示例。
pmcp-openapi-server	Shape-A 二进制程序，可为任何 OpenAPI / HTTP 后端提供服务，支持六种出站身份验证模式（包括 OAuth 透传）。附带 london-tube（api_key）和 contoso-m365（oauth_passthrough、Microsoft Graph + Excel）示例。
pmcp-workbook-server	Shape-A 二进制程序，仅需一个已编译的 bundle@version 目录，即可将受治理的 Excel 工作簿作为 MCP 服务提供：每个输出表对应一个具名 MCP 工具（例如 calculate_tax、estimate_refund），另有基础设施工具（explain / get_manifest / diff_version / render_workbook）——无需 config.toml，也无需架构。Excel 读取器和 JS code-mode 仅在编译时使用，不会包含在所提供服务的二进制程序中（纯净性门禁）。
pmcp-toolkit-postgres / -mysql / -athena	该工具包针对各后端的 SQL 连接器。

这些二进制程序均有对应的 cargo pmcp new --kind {sql-server,openapi-server,workbook-server} 脚手架，可生成相同的配置驱动服务，并作为小型、可部署的 crate。请参阅上文的 路径 1，以及 pmcp-book 中的 配置驱动 SQL 服务 / OpenAPI / 配置驱动工作簿服务 章节。

---

📚 pmcp-book（参考指南）

这份全面的参考指南共 27 章，介绍如何使用 pmcp 构建 MCP 服务。

📖 在线阅读

内容涵盖：

• 入门：安装、首个服务、快速入门教程
• 核心概念：工具、资源、提示词、错误处理
• 高级功能：身份验证、传输、中间件、进度跟踪
• 实际应用：生产级服务、测试、部署、性能
• 示例与模式：完整示例和设计模式
• TypeScript 迁移：完整兼容性指南
• 高级主题：自定义传输、AI 辅助开发

本地开发：

make book-serve    # Serve at http://localhost:3000
make book-open     # Build and open in browser

---

🎓 pmcp-course（实践学习）

交互式课程，包含测验、练习和真实项目，帮助掌握 MCP 开发。

🎓 开始课程

课程结构：

• 第一部分：基础知识 - MCP 概念、首个服务、类型化工具
• 第二部分：核心概念 - 工具、资源、提示词、验证
• 第三部分：部署 - AWS Lambda、Cloudflare Workers、Google Cloud Run
• 第四部分：测试 - 本地测试、CI/CD、回归测试
• 第五部分：安全 - OAuth 2.0、身份提供商、多租户
• 第六部分：AI 辅助开发 - Claude Code、反馈循环、协作
• 第七部分：可观测性 - 中间件、日志记录、指标
• 第八部分：高级主题 - 服务组合、MCP Apps（实验性）

功能：

• 每章结束后提供交互式测验
• 提供附有解答的实践练习
• 真实项目示例
• 来自生产级服务的最佳实践

本地开发：

cd pmcp-course && mdbook serve    # Serve at http://localhost:3000

---

🤖 ai-agents（AI 辅助开发）

AI Agent 配置，用于指导 Kiro 和 Claude Code 如何构建 MCP 服务。

支持的 AI 助手：

Kiro（Steering 文件） - 10,876 行持久的 MCP 专业知识

• 在每次对话中始终生效的知识
• 全面的测试和可观测性指南
• 安装指南

Claude Code（子 Agent） - 约 750 行专注于 MCP 的知识

• 按需调用，处理 MCP 任务
• 快速搭建框架并实现
• 安装指南

AI Agent 掌握的内容：

• MCP 协议概念和模式
• cargo-pmcp 工作流（绝不手动创建文件）
• 类型安全的工具实现
• 测试策略（单元、集成、属性、模糊测试）
• 生产环境可观测性（日志、指标）
• 丰田之道质量标准

欢迎社区贡献实现：

• GitHub Copilot、Cursor、Cline 等
• 贡献指南

了解更多：AI 辅助开发课程 | ai-agents/

---

🎨 MCP Apps（富 UI 小组件）

构建由 MCP 服务提供的富 HTML UI 小组件，可与 ChatGPT、Claude 和其他 MCP 客户端配合使用。

功能介绍：

• 预览：通过双代理/WASM 桥接模式实时预览小组件
• 编写：在 widgets/ 目录中创建基于文件的小组件，并支持热重载
• 搭建：cargo pmcp app new 可生成完整的 MCP Apps 项目
• 发布：ChatGPT 兼容的清单和独立演示落地页
• 测试：通过 chromiumoxide CDP 运行 20 项端到端浏览器测试

快速开始：

# Scaffold a new MCP Apps project
cargo pmcp app new my-widget-app
cd my-widget-app

# Run the server
cargo run

# Preview in browser (separate terminal)
cargo pmcp preview --url http://localhost:3000 --open

# Generate deployment artifacts
cargo pmcp app build --url https://my-server.example.com

示例：

• Chess App — 带走棋验证功能的交互式棋盘
• Map App — 基于 Leaflet.js 的地理空间城市探索工具
• Data Viz App — 带 SQL 查询的 Chart.js 仪表板

了解更多：小组件运行时 | 预览服务 | 端到端测试

---

Agent 与团队

到目前为止，所有内容都在构建 MCP 服务——等待被调用的程序。Agent 则是另一端：它拥有一个决策循环，因此本身就是 MCP 客户端。PMCP 将这个循环作为一个 crate 提供，并通过 CLI 为其搭建脚手架，因此你可以在编写任何 Rust 代码之前，先观察 Agent 如何做出决策。

# Scaffold a runnable agent package (AgentPackage manifest + crate)
cargo pmcp agent new research-agent
cd research-agent

# Run the loop offline first — no network, no API key
cargo pmcp agent dev --source fixed

# Then against a local model (defaults to Ollama at http://localhost:11434/v1)
cargo pmcp agent dev --source openai-compat --model llama3.2

# Run a two-member reference team in one process
cargo pmcp team dev

Agent 的身份信息——指令、模型槽位、令牌和迭代限制——保存在 agent.package.json 清单中，而不是代码里，因此同一个包可以未经修改地从你的笔记本电脑迁移到部署环境。切换补全内容的来源时，只需更改 --source；循环本身无需改动。

背后的 crate：

• 🤖 pmcp-agent - AgentEngine 循环，由三个接口（补全来源、工具调用器、存储）组成；还提供 AgentServer，用于将 Agent 暴露为由调用方采样的 MCP 工具
• 👥 pmcp-team-servers - 四个参考团队服务，以及由 cargo pmcp team dev 驱动的进程内组合运行时
• 📦 pmcp-package - 可移植的 AI-Package 格式（AgentPackage、TeamPackage），使 Agent 成为一种描述，而非二进制文件

# One AgentEngine, run twice: standalone, then hosted-sampled — no network, no key
cargo run -p pmcp-agent --example s50_standalone_vs_sampled

了解更多：第 12.15 章：作为 MCP 客户端的 Agent | pmcp-agent | pmcp-team-servers

---

协议版本

PMCP 用一个二进制文件支持两个 MCP 协议时代：v1（2025-11-25）和 v2 （2026-07-28）。协议时代按请求协商，而非按进程协商——同一服务可在同一端口上同时为 v1 客户端提供会话，为 v2 客户端提供无会话服务。你无需运行两套服务，也无需在构建时选择协议时代。

在本项目中，协议时代始终写作带日期字符串的 v1/v2，而 crate 始终与名称一起写作——“pmcp 2.18”。单独的版本号绝不表示协议时代。

按角色选择启用方式：

• 服务端——显式调用一次 ServerBuilder::with_supported_protocol_versions(...)，将你的 v1 版本与 PROTOCOL_VERSION_2026_07_28 一起列出。默认接受列表设计为仅支持 v1，因此仅升级 crate 后，服务仍只会响应 v1。参见 examples/s47_v2_stateless_mrtr.rs。
• 客户端——显式调用一次 ClientBuilder::with_protocol_version(...)。如果不调用，客户端将继续使用 v1，与之前完全相同。
• Agent——已为你处理好。pmcp-agent 的调用器优先使用 v2，并回退到 v1，因此通过 cargo pmcp agent new 搭建的 Agent 会在服务支持 v2 时使用 v2。

此外，服务端还可以通过一个相反方向的选项来选择退出 v1：

cargo build -p pmcp --no-default-features --features full-v2

单独使用 --no-default-features 不能证明任何事情（它还会移除 HTTP 传输，因此 v1 看起来像是被切断，只是因为没有编译任何内容）。full-v2 是正向的功能列表：它包含 full 中的所有内容，仅不包含 v1-compat。

了解更多：第 12.17 章：迁移到 MCP 2026-07-28（v2） | v1 退役政策

---

最新版本：pmcp 2.18.0

发布于 2026-08-16。 当前开发版本为 pmcp 2.19.0，尚未发布——变更日志顶部的条目是下一版本将包含内容的权威列表。

• 两个协议时代，一个二进制文件：pmcp 同时支持 MCP 2025-11-25（v1）和 2026-07-28（v2），并按请求协商——参见上文协议版本
• 凭据存储（2.18.0）：一台机器，一个凭据存储——pmcp::shared::credential_store 通过 (issuer, account, server) 寻址，并提供由 cargo pmcp auth 写入的磁盘文件 FileCredentialStore
• Agents 与 Teams：pmcp-agent 循环、四个参考团队服务，以及可移植的 AI-Package 格式——参见上文Agents 与 Teams
• MCP Apps：由 MCP 服务提供的丰富交互式 HTML UI 小组件——支持 ChatGPT、Claude Desktop 和其他 MCP 客户端。提供实时预览，并配有类浏览器的 DevTools（可调整大小的面板，以及网络／事件／协议／桥接标签页）
• MCP Tasks：共享的客户端／服务端任务生命周期，支持可插拔存储（内存和 DynamoDB）及任务变量——v2 形式属于扩展，目前仍为暂定方案
• 一致性测试套件：跨 5 个领域的 19 场景一致性引擎，集成 cargo pmcp test conformance 和 mcp-tester conformance CLI
• Tower 中间件：DNS 重绑定防护、带来源锁定标头的 CORS、可配置的安全标头——适用于生产环境的 HTTP 技术栈
• PMCP 服务：通过 Streamable HTTP 提供 SDK 开发者工具（测试、脚手架、架构导出）的 MCP 服务，部署于 AWS Lambda
• 统一构造器体验：为所有协议类型提供默认实现、构建器和构造函数——大幅提升易用性
• examples/ 中的 85 个示例：可运行的 SDK 功能覆盖（整个工作区共有 119 个示例目标）

完整变更日志：CHANGELOG.md

---

核心功能

🚀 传输层

• stdio：用于 CLI 集成的标准输入／输出
• HTTP/SSE：支持服务器发送事件的 Streamable HTTP
• WebSocket：支持自动重连的全双工通信
• WASM：支持浏览器和 Cloudflare Workers

🛠️ 类型安全开发

• 自动生成 Schema：使用 schemars 从 Rust 类型生成
• 编译时验证：对工具参数进行类型检查
• 运行时验证：根据生成的 JSON Schema 进行验证
• 零 Unwrap：始终显式处理错误

🔐 安全与认证

• OAuth 2.0：完整透传认证上下文
• OIDC 发现：自动配置提供方
• Bearer 令牌：标准认证方式
• 路径验证：安全访问文件系统

🧪 测试与质量

• mcp-tester：全面的服务测试工具
• 场景生成：自动生成测试用例
• 属性测试：验证不变量
• 质量门禁：强制执行 fmt、clippy 和覆盖率要求

⚡ 性能

• 速度比 TypeScript SDK 快 16 倍
• 内存占用低 50 倍
• SIMD 解析：使用 AVX2/SSE4.2 时，SSE 快 10.3 倍
• 连接池：智能负载均衡

🏭 丰田之道质量

• 零技术债务：TDG 得分为 0.76
• Jidoka：发现缺陷时停止生产线
• Genchi Genbutsu：亲临现场（以证据为依据）
• Kaizen：持续改进
• 无 Unwrap：仅显式处理错误

---

文档

📖 主要资源

• PMCP 文档门户 - 所有文档的入口页
• pmcp-book - 全面的参考指南（27 章）
• pmcp-course - 包含测验和练习的实战课程
• API 参考 - 完整的 API 文档
• cargo-pmcp 指南 - CLI 工具包文档

📚 更多资源

• 示例 - examples/ 中有 85 个可运行示例（整个工作区共有 119 个示例目标）
• 更新日志 - 版本历史
• 迁移指南 - 升级说明
• 参与贡献 - 如何参与贡献

🎯 快速链接

• 快速入门教程
• 你的第一个服务
• 课程：入门
• 测试指南
• 生产环境部署

---

示例

SDK 在 examples/ 中提供 85 个可运行示例，整个工作区共有 119 个示例目标，涵盖 SDK 的全部功能：

# Basic examples
cargo run --example c01_client_initialize   # Client setup
cargo run --example s01_basic_server        # Basic server
cargo run --example c02_client_tools        # Tool usage

# Type-safe tools (v1.6.0+)
cargo run --example s16_typed_tools --features schema-generation
cargo run --example s17_advanced_typed_tools --features schema-generation

# Advanced features
cargo run --example s28_authentication      # OAuth/Bearer
cargo run --example t01_websocket_transport # WebSocket
cargo run --example m01_basic_middleware    # Middleware chain

# Agent Skills (SEP-2640) — dual-surface skill + prompt
cargo run --example s44_server_skills --features skills,full
cargo run --example c10_client_skills --features skills,full

# Agents & Teams — an agent loop, and four reference servers cooperating
cargo run --example s49_sampling_host
cargo run -p pmcp-agent --example s50_standalone_vs_sampled
cargo run -p pmcp-team-servers --example doc_review_team --features runtime

# MCP 2026-07-28 (v2) — start the SERVER first, in its own terminal; each client
# takes the server address as its argument and defaults to where the server binds
cargo run --example s47_v2_stateless_mrtr --features full   # serves on 127.0.0.1:8147
cargo run --example s48_v2_mrtr_client --features full      # then, in another terminal
cargo run --example s53_v2_agent_client --features full     # the pmcp-agent connector, v2 with v1 fallback

# MCP 2026-07-28 (v2) Tasks — same rule: server first, then the agent
cargo run --example s50_v2_tasks_server --features full     # serves on 127.0.0.1:8150
cargo run --example s51_v2_tasks_agent --features full

# Testing (mcp-tester is a standalone Cargo project in examples/26-server-tester)
cargo install mcp-tester && mcp-tester test http://localhost:8080

# AI-assisted development
# See ai-agents/README.md for Kiro and Claude Code setup

完整列表请参阅 examples/README.md。

---

MCP 服务测试工具

用于验证 MCP 服务实现的综合测试工具。

功能：

• 协议合规性验证（JSON-RPC 2.0、MCP 规范）
• 支持多种传输方式（HTTP、HTTPS、WebSocket、stdio）
• 工具发现与测试
• 可用于 CI/CD，并支持 JSON 输出

安装：

cargo install mcp-server-tester

# Or download pre-built binaries from releases

用法：

# Test a server
mcp-tester test http://localhost:8080

# Protocol compliance check
mcp-tester compliance http://localhost:8080 --strict

# Connection diagnostics
mcp-tester diagnose http://localhost:8080

了解更多：examples/26-server-tester/README.md

---

质量与性能

丰田之道原则

PMCP 遵循丰田生产方式原则构建：

• Jidoka（自働化）：兼顾人工判断的自动化

  • 质量门禁会在发现缺陷时停止构建
  • 生产环境中绝不容忍 unwrap()
  • 全面处理错误并提供上下文

• Genchi Genbutsu（現地現物）：亲临现场

  • 基于指标和证据做出决策
  • PMAT 质量分析（TDG 得分为 0.76）
  • 全面测试（单元测试、属性测试、模糊测试）

• Kaizen（改善）：持续改进

  • 定期进行基准测试和优化
  • 防止性能回归
  • 由社区推动改进

质量指标

• TDG 评分：0.76（可用于生产）
• 技术债务：极少（整个代码库共 436 小时）
• 复杂度：所有函数的复杂度均 ≤25
• 覆盖率：52% 行覆盖率，100% 函数覆盖率
• Lint 检查：生产代码中没有 clippy 警告

性能基准测试

Metric                  PMCP (Rust)     TypeScript SDK    Improvement
────────────────────────────────────────────────────────────────────
Overall Speed           16x             1x                16x faster
Memory Usage            <10 MB          ~500 MB           50x lower
SSE Parsing             336,921 ev/s    32,691 ev/s       10.3x faster
JSON-RPC Parsing        195,181 docs/s  N/A               SIMD-optimized
Round-trip Latency      <100 μs         ~1-2 ms           10-20x faster
Base64 Operations       252+ MB/s       N/A               Optimized

运行基准测试：

make bench                           # General benchmarks
cargo run --example t08_simd_parsing_performance  # SIMD-specific

---

WebAssembly 支持

全面支持 WASM，可用于浏览器和边缘部署：

目标平台：

• Cloudflare Workers（wasm32-unknown-unknown）
• WASI 运行时（wasm32-wasi）
• 浏览器（wasm-bindgen）

快速开始：

# Build for Cloudflare Workers
cargo build --target wasm32-unknown-unknown --no-default-features --features wasm

# Deploy
make cloudflare-sdk-deploy

了解更多：WASM 指南 | WASM 示例

---

开发

前置条件

• Rust 1.83.0 或更高版本
• Git

设置

git clone https://github.com/paiml/rust-mcp-sdk
cd rust-mcp-sdk

# Install development tools
make setup

# Run quality checks
make quality-gate

测试

make test-all           # All tests
make test-property      # Property tests
make coverage           # Coverage report
make mutants            # Mutation tests

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 确保通过质量门禁（make quality-gate）
4. 使用 Conventional Commits 规范提交
5. 推送并创建 Pull Request

参见：CONTRIBUTING.md

---

兼容性

功能	TypeScript SDK v2.0	PMCP v2.0（Rust）
协议版本	2025-11-25	2025-11-25（兼容 2024-11-05）
传输方式	stdio、SSE、WebSocket	stdio、SSE、WebSocket、WASM
身份验证	OAuth 2.0、Bearer	OAuth 2.0、Bearer、OIDC
工具	✓	✓（类型安全 + outputSchema）
提示词	✓	✓（工作流）
资源	✓	✓（订阅）
采样	✓	✓
MCP Apps	✓	✓（预览版 + DevTools）
Agent Skills（SEP-2640）	✓	✓（双界面技能 + 提示词，字节完全一致）
Tower 中间件	不适用	✓（DNS 重绑定、CORS、安全标头）
性能	1 倍	快 16 倍
内存	基准值	低 50 倍

---

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

---

致谢

• Model Context Protocol 规范
• TypeScript SDK 参考实现
• PAIML MCP Agent Toolkit 质量标准
• 社区贡献者和早期采用者

---

链接

• 文档门户：https://paiml.github.io/rust-mcp-sdk/
• 参考指南：https://paiml.github.io/rust-mcp-sdk/book/
• 课程：https://paiml.github.io/rust-mcp-sdk/course/
• Crates.io：https://crates.io/crates/pmcp
• API 文档：https://docs.rs/pmcp
• 问题反馈：https://github.com/paiml/rust-mcp-sdk/issues
• 讨论：https://github.com/paiml/rust-mcp-sdk/discussions

---

以 🦀 Rust 构建，秉承丰田之道原则，满怀 ❤️