{
  "markdown": "# PMCP - Pragmatic Model Context Protocol\n<!-- QUALITY BADGES START -->\n[![Quality Gate](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-gate.yml/badge.svg?branch=main)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-gate.yml)\n[![TDG Score](https://img.shields.io/badge/TDG%20Score-0.00-brightgreen)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-badges.yml)\n[![Complexity](https://img.shields.io/badge/Complexity-clean-brightgreen)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-badges.yml)\n[![Technical Debt](https://img.shields.io/badge/Tech%20Debt-0h-brightgreen)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-badges.yml)\n<!-- QUALITY BADGES END -->\n\n[![CI](https://github.com/paiml/rust-mcp-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/badge/coverage-52%25-yellow.svg)](https://github.com/paiml/rust-mcp-sdk)\n[![Crates.io](https://img.shields.io/crates/v/pmcp.svg)](https://crates.io/crates/pmcp)\n[![Documentation](https://docs.rs/pmcp/badge.svg)](https://docs.rs/pmcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Rust 1.83+](https://img.shields.io/badge/rust-1.83+-orange.svg)](https://www.rust-lang.org)\n[![MCP Compatible](https://img.shields.io/badge/MCP-v2025--11--25-blue.svg)](https://modelcontextprotocol.io)\n\n> **Production-grade Rust implementation of the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) - 16x faster than TypeScript, built with Toyota Way quality principles**\n\n## Overview\n\nPMCP is a complete MCP ecosystem for Rust, providing everything you need to build, test, and deploy production-grade MCP servers — in Rust, **or from configuration alone**:\n\n- **🧩 Config-Driven Servers** - Build SQL & OpenAPI/HTTP MCP servers from a `config.toml`, or serve a governed Excel workbook from a compiled bundle — all **no Rust required** (`pmcp-server-toolkit`, `pmcp-sql-server`, `pmcp-openapi-server`, `pmcp-workbook-server`)\n- **🤝 Agents & Teams** - Build deploy-anywhere agents and small teams: the agent loop (`pmcp-agent`), four reference team servers (`pmcp-team-servers`), and a portable AI-Package format (`pmcp-package`) — driven from the `cargo pmcp agent`/`team`/`package` verbs\n- **🦀 pmcp SDK** - High-performance Rust crate with full MCP protocol support\n- **⚡ cargo-pmcp** - CLI toolkit for scaffolding, testing, and development\n- **📚 pmcp-book** - Comprehensive reference guide with 27 chapters\n- **🎓 pmcp-course** - Hands-on course with quizzes and exercises\n- **🤖 AI Agents** - Kiro and Claude Code configurations for AI-assisted development\n\n**Why PMCP?**\n- **Performance**: 16x faster than TypeScript SDK, 50x lower memory\n- **Safety**: Rust's type system + zero `unwrap()` in production code\n- **Quality**: Toyota Way principles - zero technical debt tolerance\n- **Complete**: SDK, tooling, documentation, and AI assistance in one ecosystem\n\n## Quick Start\n\nChoose your path based on experience and preference:\n\n### 🧩 Path 1: Config-Only Servers — No Rust Required (SQL & OpenAPI)\n\n**New in v2.9 — this removes the biggest blocker to putting organizational data behind MCP: you no longer need a Rust programmer.** Describe a production MCP server over a **SQL database** or any **OpenAPI / HTTP backend** in a `config.toml` — declare the backend, a handful of curated tools, and a Code Mode policy — and a prebuilt binary serves it. No Rust, no recompiling. Curated tools cover the common ~20%; **Code Mode** handles the long-tail ~80% by generating queries against your schema/spec under a static, default-deny policy. A business analyst curates the API slice in config; the toolkit does the rest.\n\n**SQL — SQLite / Postgres / MySQL / Athena** (runnable from a checkout of this repo):\n```bash\ncargo install pmcp-sql-server\n\n# Seed a tiny demo DB, then serve it from config alone — two curated tools\n# (list_books, books_by_author) + Code Mode for the long tail.\nsqlite3 /tmp/pmcp-sqlite-explorer.db < crates/pmcp-sql-server/examples/sqlite-explorer.sql\npmcp-sql-server \\\n  --config crates/pmcp-sql-server/examples/sqlite-explorer.toml \\\n  --schema crates/pmcp-sql-server/examples/sqlite-explorer.sql\n```\n\n**OpenAPI / HTTP — any REST backend**, with six outgoing-auth models including OAuth **passthrough** (the server holds no standing credential and forwards the caller's own token, so it can only act as the signed-in user):\n```bash\ncargo install pmcp-openapi-server\n\n# Curated configs ship with the crate — e.g. a London Tube (api_key) showcase and\n# a Microsoft-Graph / Excel \"Contoso\" (oauth_passthrough) example. These talk to a\n# live backend, so supply any required credential per the example's comments.\n#\n# `base_url` is a SLOT, not a baked literal, so the endpoint comes from the\n# environment too — the same package moves between environments unchanged.\nTFL_BASE_URL=https://api.tfl.gov.uk TFL_APP_KEY=<your-key> \\\n  pmcp-openapi-server --config crates/pmcp-openapi-server/examples/london-tube.toml\n```\n\n**Excel workbook — a governed spreadsheet, served as one MCP tool per output table** (no `config.toml`, no schema; the single input is a compiled `bundle@version` directory). Author inputs and outputs as named Excel **Tables** and each output table becomes its own well-named, well-typed MCP tool with a DAG-derived input schema:\n```bash\ncargo install pmcp-workbook-server\n\n# Preview the exact tool surface an AI will see — BEFORE you compile or deploy:\ncargo pmcp workbook explain pricing.xlsx          # e.g. calculate_tax, estimate_refund\n\n# Compile a governed workbook to a deterministic bundle (ingest → lint → compile →\n# reconcile → fail-closed gate → write), then serve one calculation tool per output\n# table — plus explain / get_manifest / diff_version / render_workbook — from the bundle alone.\ncargo pmcp workbook compile pricing.xlsx --workflow quote --approver alice\npmcp-workbook-server --bundle-dir bundles/quote@1.0.0\n```\n\n**Want to extend and deploy it?** `cargo pmcp new my-server --kind sql-server` (or `--kind openapi-server` / `--kind workbook-server`) scaffolds the same config-driven server as a small crate, ready for `cargo pmcp deploy` to AWS Lambda / Google Cloud Run / Cloudflare / pmcp.run.\n\n**Learn more**: the *Config-Driven SQL Servers*, *OpenAPI*, and *Config-Driven Workbook Servers* chapters in the [pmcp-book](https://paiml.github.io/rust-mcp-sdk/book/) · [`pmcp-sql-server`](crates/pmcp-sql-server/README.md) · [`pmcp-openapi-server`](crates/pmcp-openapi-server/README.md) · [`pmcp-workbook-server`](crates/pmcp-workbook-server/README.md) · [`pmcp-server-toolkit`](crates/pmcp-server-toolkit/README.md)\n\n---\n\n### 🚀 Path 2: AI-Assisted (Recommended for Rapid Prototyping)\n\nBuild production-ready MCP servers with AI assistance in minutes:\n\n**Prerequisites:**\n```bash\n# Install Rust\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nrustup update\n\n# Install cargo-pmcp\ncargo install cargo-pmcp\n```\n\n**Install Claude Code AI Agent:**\n```bash\n# Install the mcp-developer subagent (user-level - works across all projects)\ncurl -fsSL https://raw.githubusercontent.com/paiml/rust-mcp-sdk/main/ai-agents/claude-code/mcp-developer.md \\\n  -o ~/.claude/agents/mcp-developer.md\n\n# Restart Claude Code\n```\n\n**Build your server:**\n```\nYou: \"Create a weather forecast MCP server with tools for getting current conditions and 5-day forecasts\"\n\nClaude Code: [Invokes mcp-developer subagent]\n\nI'll create a production-ready weather MCP server using cargo-pmcp.\n\n$ cargo pmcp new weather-mcp-workspace\n$ cd weather-mcp-workspace\n$ cargo pmcp add server weather --template minimal\n\n[Implements type-safe tools with validation]\n[Adds comprehensive tests and observability]\n[Validates quality gates]\n\n✅ Production-ready server complete with 85% test coverage!\n```\n\n**What you get**: Production-ready code following Toyota Way principles, with comprehensive tests, structured logging, metrics collection, and zero clippy warnings.\n\n**Learn more**: [AI-Assisted Development Course](https://paiml.github.io/rust-mcp-sdk/course/part6-ai-dev/ch15-ai-assisted.html) | [AI Agents README](ai-agents/README.md)\n\n---\n\n### ⚡ Path 3: cargo-pmcp Toolkit (Recommended for Manual Development)\n\nScaffold and build servers using the cargo-pmcp CLI:\n\n**Installation:**\n```bash\n# Install Rust\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nrustup update\n\n# Install cargo-pmcp\ncargo install cargo-pmcp\n```\n\n**Create a server:**\n```bash\n# Create workspace\ncargo pmcp new my-mcp-workspace\ncd my-mcp-workspace\n\n# Add a server using a template\ncargo pmcp add server myserver --template minimal\n\n# Start development server with hot-reload\ncargo pmcp dev --server myserver\n\n# Generate and run tests\ncargo pmcp test --server myserver --generate-scenarios\ncargo pmcp test --server myserver\n\n# Build for production\ncargo build --release\n```\n\n**Available templates** (`cargo pmcp add server <name> --template <t>`):\n- `minimal` - Empty structure for custom servers\n- `calculator` - Arithmetic operations (learning)\n- `complete_calculator` - Full-featured reference implementation\n- `sqlite_explorer` - Hand-coded Rust database browser (escape hatch)\n\n**Config-driven kinds** (`cargo pmcp new <name> --kind <k>` — TOML-driven, no per-tool Rust):\n- `sql-server` - SQL MCP server over SQLite / Postgres / MySQL / Athena from `config.toml`\n- `openapi-server` - MCP server over any OpenAPI / HTTP backend from `config.toml`\n- `workbook-server` - MCP server over a governed Excel workbook, served from a compiled `bundle@version` directory\n\n**Learn more**: [cargo-pmcp Guide](cargo-pmcp/README.md)\n\n---\n\n### 🦀 Path 4: pmcp SDK Directly (For Fine-Grained Control)\n\nUse the pmcp crate directly for maximum control:\n\n**Installation:**\n```toml\n[dependencies]\npmcp = \"2.0\"\ntokio = { version = \"1\", features = [\"full\"] }\nserde = { version = \"1\", features = [\"derive\"] }\nschemars = \"0.8\"  # For type-safe tools\n```\n\n**Type-safe server example:**\n```rust\nuse pmcp::{ServerBuilder, TypedTool, RequestHandlerExtra, Error};\nuse schemars::JsonSchema;\nuse serde::{Deserialize, Serialize};\n\n#[derive(Debug, Deserialize, Serialize, JsonSchema)]\n#[schemars(deny_unknown_fields)]\nstruct WeatherArgs {\n    #[schemars(description = \"City name\")]\n    city: String,\n\n    #[schemars(description = \"Number of days (1-5)\")]\n    days: Option<u8>,\n}\n\n#[derive(Debug, Serialize, JsonSchema)]\nstruct WeatherOutput {\n    temperature: f64,\n    conditions: String,\n}\n\nasync fn get_weather(args: WeatherArgs, _extra: RequestHandlerExtra) -> pmcp::Result<WeatherOutput> {\n    // Validate\n    if args.city.is_empty() {\n        return Err(Error::validation(\"City cannot be empty\"));\n    }\n\n    let days = args.days.unwrap_or(1);\n    if !(1..=5).contains(&days) {\n        return Err(Error::validation(\"Days must be 1-5\"));\n    }\n\n    // Call weather API...\n    Ok(WeatherOutput {\n        temperature: 72.0,\n        conditions: \"Sunny\".to_string(),\n    })\n}\n\n#[tokio::main]\nasync fn main() -> pmcp::Result<()> {\n    let server = ServerBuilder::new()\n        .name(\"weather-server\")\n        .version(\"1.0.0\")\n        .tool(\"get-weather\", TypedTool::new(\"get-weather\", |args, extra| {\n            Box::pin(get_weather(args, extra))\n        }).with_description(\"Get weather forecast for a city\"))\n        .build()?;\n\n    server.run_stdio().await?;\n    Ok(())\n}\n```\n\n**Learn more**: [pmcp-book](https://paiml.github.io/rust-mcp-sdk/book/) | [pmcp-course](https://paiml.github.io/rust-mcp-sdk/course/) | [API Documentation](https://docs.rs/pmcp)\n\n---\n\n## PMCP Ecosystem Components\n\n### 🦀 pmcp SDK (The Crate)\n\nHigh-performance Rust implementation of the MCP protocol.\n\n**Key Features:**\n- **Type-Safe Tools**: Automatic JSON schema generation from Rust types\n- **Multiple Transports**: stdio, HTTP/SSE, WebSocket, WASM\n- **OAuth Support**: Full auth context pass-through\n- **Workflows**: Multi-step orchestration with array indexing support\n- **MCP Apps**: Rich HTML UI widgets with live preview and browser DevTools\n- **MCP Tasks**: Shared client/server state with task lifecycle management — see the [*Task-Augmented Tool Results (SEP-1686)*](https://paiml.github.io/rust-mcp-sdk/book/task-augmented-results.html) chapter for returning a `CallToolResult` that points at a related task\n- **Agent Skills (SEP-2640)**: Register an Agent Skill in ~5 lines and serve it on BOTH a SEP-2640 skill surface AND a parallel MCP prompt fallback — byte-equal by construction (`skills` feature, opt-in)\n- **Tower Middleware**: DNS rebinding protection, CORS, security headers\n- **Typed Client Helpers**: `call_tool_typed`, `get_prompt_typed`, and auto-paginating `list_all_*` with bounded safety cap\n- **Performance**: 16x faster than TypeScript, SIMD-accelerated parsing\n- **Quality**: Zero `unwrap()`, comprehensive error handling\n\n**Latest Version:** `pmcp = \"2.9\"`\n\n**Documentation:**\n- [API Reference](https://docs.rs/pmcp)\n- [pmcp-book](https://paiml.github.io/rust-mcp-sdk/)\n- [Examples](examples/)\n\n---\n\n### ⚡ cargo-pmcp (CLI Toolkit)\n\nFull-lifecycle development toolkit — from scaffolding to production deployment.\n\n```bash\ncargo install cargo-pmcp\n```\n\n```bash\ncargo pmcp new my-workspace             # Scaffold a new workspace\ncargo pmcp add server my-server         # Add a server with best-practice template\ncargo pmcp dev --server my-server       # Dev server with hot-reload\ncargo pmcp test --server my-server      # Auto-generated scenario tests\ncargo pmcp loadtest run                 # Load test with latency percentiles\ncargo pmcp pentest run                  # Security audit (32 checks, SARIF output)\ncargo pmcp preview --open               # Browser-based widget preview\ncargo pmcp workbook explain wb.xlsx     # Preview an Excel workbook's MCP tool surface\ncargo pmcp deploy --target aws-lambda   # Deploy to AWS Lambda, GCR, or Cloudflare\ncargo pmcp deploy logs --tail           # Stream production logs\n```\n\nCovers the full development lifecycle: scaffolding, dev mode, testing, load testing, security pentesting, MCP Apps preview, schema management, multi-target deployment, secrets, and OAuth setup.\n\n**Full command reference**: [cargo-pmcp Guide](cargo-pmcp/README.md)\n\n---\n\n### 🧩 Config-Driven Servers (No Rust)\n\nBuild production MCP servers over SQL and HTTP backends from a `config.toml` alone — the toolkit synthesizes curated tools + a Code Mode long tail, so exposing organizational data over MCP no longer needs a Rust programmer.\n\n| Crate | What it is |\n| ----- | ---------- |\n| [`pmcp-server-toolkit`](crates/pmcp-server-toolkit) | The backend-agnostic library: config types, the `[[tools]]` synthesizer, Code Mode wiring, and the connector/auth seams that the binaries below build on. |\n| [`pmcp-sql-server`](crates/pmcp-sql-server) | Shape-A binary serving a SQL database (SQLite / Postgres / MySQL / Athena) from `config.toml` + a schema file. Ships a runnable [`sqlite-explorer`](crates/pmcp-sql-server/examples/sqlite-explorer.toml) example. |\n| [`pmcp-openapi-server`](crates/pmcp-openapi-server) | Shape-A binary serving any OpenAPI / HTTP backend, with six outgoing-auth models (incl. OAuth passthrough). Ships [`london-tube`](crates/pmcp-openapi-server/examples/london-tube.toml) (api_key) and [`contoso-m365`](crates/pmcp-openapi-server/examples/contoso-m365.toml) (oauth_passthrough, Microsoft Graph + Excel) examples. |\n| [`pmcp-workbook-server`](crates/pmcp-workbook-server) | Shape-A binary serving a governed Excel workbook as one named MCP tool per output table (e.g. `calculate_tax`, `estimate_refund`) plus infrastructure tools (`explain` / `get_manifest` / `diff_version` / `render_workbook`) from a compiled `bundle@version` directory alone — no `config.toml`, no schema. The Excel reader and JS code-mode are compile-time only and absent from the served binary (purity gate). |\n| [`pmcp-toolkit-postgres`](crates/pmcp-toolkit-postgres) / [`-mysql`](crates/pmcp-toolkit-mysql) / [`-athena`](crates/pmcp-toolkit-athena) | Per-backend SQL connectors for the toolkit. |\n\nThese binaries have `cargo pmcp new --kind {sql-server,openapi-server,workbook-server}` scaffold siblings that generate the same config-driven server as a small, deployable crate. See **Path 1** above and the *Config-Driven SQL Servers* / *OpenAPI* / *Config-Driven Workbook Servers* chapters in the [pmcp-book](https://paiml.github.io/rust-mcp-sdk/book/).\n\n---\n\n### 📚 pmcp-book (Reference Guide)\n\n27-chapter comprehensive reference guide to building MCP servers with pmcp.\n\n**📖 [Read Online](https://paiml.github.io/rust-mcp-sdk/book/)**\n\n**Coverage:**\n- **Getting Started**: Installation, first server, quick start tutorial\n- **Core Concepts**: Tools, resources, prompts, error handling\n- **Advanced Features**: Auth, transports, middleware, progress tracking\n- **Real-World**: Production servers, testing, deployment, performance\n- **Examples & Patterns**: Complete examples and design patterns\n- **TypeScript Migration**: Complete compatibility guide\n- **Advanced Topics**: Custom transports, AI-assisted development\n\n**Local development:**\n```bash\nmake book-serve    # Serve at http://localhost:3000\nmake book-open     # Build and open in browser\n```\n\n---\n\n### 🎓 pmcp-course (Hands-On Learning)\n\nInteractive course with quizzes, exercises, and real-world projects for mastering MCP development.\n\n**🎓 [Start the Course](https://paiml.github.io/rust-mcp-sdk/course/)**\n\n**Course Structure:**\n- **Part I: Foundations** - MCP concepts, first server, typed tools\n- **Part II: Core Concepts** - Tools, resources, prompts, validation\n- **Part III: Deployment** - AWS Lambda, Cloudflare Workers, Google Cloud Run\n- **Part IV: Testing** - Local testing, CI/CD, regression testing\n- **Part V: Security** - OAuth 2.0, identity providers, multi-tenant\n- **Part VI: AI-Assisted Dev** - Claude Code, feedback loops, collaboration\n- **Part VII: Observability** - Middleware, logging, metrics\n- **Part VIII: Advanced** - Server composition, MCP Apps (experimental)\n\n**Features:**\n- Interactive quizzes after each chapter\n- Hands-on exercises with solutions\n- Real-world project examples\n- Best practices from production servers\n\n**Local development:**\n```bash\ncd pmcp-course && mdbook serve    # Serve at http://localhost:3000\n```\n\n---\n\n### 🤖 ai-agents (AI-Assisted Development)\n\nAI agent configurations that teach Kiro and Claude Code how to build MCP servers.\n\n**Supported AI Assistants:**\n\n**Kiro (Steering Files)** - 10,876 lines of persistent MCP expertise\n- Always-active knowledge in every conversation\n- Comprehensive testing and observability guidance\n- [Installation Guide](ai-agents/kiro/mcp-developer-power/)\n\n**Claude Code (Subagent)** - ~750 lines of focused MCP knowledge\n- On-demand invocation for MCP tasks\n- Quick scaffolding and implementation\n- [Installation Guide](ai-agents/claude-code/)\n\n**What AI agents know:**\n- MCP protocol concepts and patterns\n- cargo-pmcp workflow (never creates files manually)\n- Type-safe tool implementation\n- Testing strategies (unit, integration, property, fuzz)\n- Production observability (logging, metrics)\n- Toyota Way quality standards\n\n**Community implementations welcome:**\n- GitHub Copilot, Cursor, Cline, and others\n- [Contribution Guide](ai-agents/README.md)\n\n**Learn more**: [AI-Assisted Development Course](https://paiml.github.io/rust-mcp-sdk/course/part6-ai-dev/ch15-ai-assisted.html) | [ai-agents/](ai-agents/)\n\n---\n\n### 🎨 MCP Apps (Rich UI Widgets)\n\nBuild rich HTML UI widgets served from MCP servers — works with ChatGPT, Claude, and other MCP clients.\n\n**What it does:**\n- **Preview**: Live widget preview with dual proxy/WASM bridge modes\n- **Author**: File-based widgets in `widgets/` directory with hot-reload\n- **Scaffold**: `cargo pmcp app new` generates a complete MCP Apps project\n- **Publish**: ChatGPT-compatible manifest and standalone demo landing pages\n- **Test**: 20 E2E browser tests via chromiumoxide CDP\n\n**Quick start:**\n```bash\n# Scaffold a new MCP Apps project\ncargo pmcp app new my-widget-app\ncd my-widget-app\n\n# Run the server\ncargo run\n\n# Preview in browser (separate terminal)\ncargo pmcp preview --url http://localhost:3000 --open\n\n# Generate deployment artifacts\ncargo pmcp app build --url https://my-server.example.com\n```\n\n**Examples:**\n- [Chess App](examples/mcp-apps-chess/) — Interactive chess board with move validation\n- [Map App](examples/mcp-apps-map/) — Leaflet.js geospatial city explorer\n- [Data Viz App](examples/mcp-apps-dataviz/) — Chart.js dashboard with SQL queries\n\n**Learn more**: [Widget Runtime](packages/widget-runtime/) | [Preview Server](crates/mcp-preview/) | [E2E Tests](crates/mcp-e2e-tests/)\n\n---\n\n## Agents & Teams\n\nEverything so far builds MCP **servers** — things that wait to be called. An agent is\nthe other side: it owns a decision loop, so it *is* an MCP client. PMCP ships that loop\nas a crate and scaffolds it from the CLI, so you can watch an agent make decisions\nbefore writing any Rust.\n\n```bash\n# Scaffold a runnable agent package (AgentPackage manifest + crate)\ncargo pmcp agent new research-agent\ncd research-agent\n\n# Run the loop offline first — no network, no API key\ncargo pmcp agent dev --source fixed\n\n# Then against a local model (defaults to Ollama at http://localhost:11434/v1)\ncargo pmcp agent dev --source openai-compat --model llama3.2\n\n# Run a two-member reference team in one process\ncargo pmcp team dev\n```\n\nThe agent's identity — instructions, model slot, token and iteration limits — lives in\nan `agent.package.json` manifest, not in code, so the same package moves from your\nlaptop to a deployment unedited. Only `--source` changes when you swap where completions\ncome from; the loop does not.\n\n**The crates behind it:**\n- **🤖 `pmcp-agent`** - The `AgentEngine` loop over three seams (completion source, tool invoker, store), plus `AgentServer` for exposing an agent as an MCP tool that is sampled by its caller\n- **👥 `pmcp-team-servers`** - Four reference team servers and the in-process composition runtime `cargo pmcp team dev` drives\n- **📦 `pmcp-package`** - The portable AI-Package format (`AgentPackage`, `TeamPackage`) that makes an agent a description rather than a binary\n\n```bash\n# One AgentEngine, run twice: standalone, then hosted-sampled — no network, no key\ncargo run -p pmcp-agent --example s50_standalone_vs_sampled\n```\n\n**Learn more**: [Chapter 12.15: Agents as MCP Clients](https://paiml.github.io/rust-mcp-sdk/book/ch12-15-agents-as-mcp-clients.html) | [`pmcp-agent`](crates/pmcp-agent/) | [`pmcp-team-servers`](crates/pmcp-team-servers/)\n\n---\n\n## Protocol Versions\n\nPMCP speaks **two MCP protocol eras out of one binary**: **v1** (`2025-11-25`) and **v2**\n(`2026-07-28`). The era is negotiated **per request**, not per process — the same server answers a\nv1 client with sessions and a v2 client without them, concurrently, on the same port. You do not\nrun two fleets, and you do not choose an era at build time.\n\nThroughout this project an era is written `v1`/`v2` with its date string, while the crate is always\nwritten with its name attached — \"pmcp 2.18\". A bare version number never means a protocol era.\n\n**Opting in, by role:**\n\n- **Servers** — one explicit call, `ServerBuilder::with_supported_protocol_versions(...)`, listing your v1 version *alongside* `PROTOCOL_VERSION_2026_07_28`. The default accept-list is v1-only by design, so upgrading the crate alone leaves a server answering v1 only. See `examples/s47_v2_stateless_mrtr.rs`.\n- **Clients** — one explicit call, `ClientBuilder::with_protocol_version(...)`. Without it a client stays on v1, exactly as before.\n- **Agents** — already done for you. `pmcp-agent`'s invoker prefers v2 and falls back to v1, so an agent scaffolded with `cargo pmcp agent new` speaks v2 wherever the server supports it.\n\nThere is also a server-side lever in the *opposite* direction — opting **out** of v1:\n\n```bash\ncargo build -p pmcp --no-default-features --features full-v2\n```\n\n`--no-default-features` on its own proves nothing (it also strips the HTTP transport, so v1 would\nappear severed only because nothing was compiled). `full-v2` is the positive feature list: exactly\nwhat `full` carries, minus `v1-compat`.\n\n**Learn more**: [Chapter 12.17: Migrating to MCP 2026-07-28 (v2)](https://paiml.github.io/rust-mcp-sdk/book/ch12-17-migrating-to-mcp-2026-07-28.html) | [v1 sunset policy](docs/v1-sunset-policy.md)\n\n---\n\n## Latest Release: pmcp 2.18.0\n\n**Published 2026-08-16.** The in-flight line is **pmcp 2.19.0**, still unreleased — its entry at the\ntop of the changelog is the authoritative list of what is landing next.\n\n- **Two protocol eras, one binary**: pmcp serves both MCP `2025-11-25` (v1) and `2026-07-28` (v2), negotiated per request — see [Protocol Versions](#protocol-versions) above\n- **Credential storage (2.18.0)**: one machine, one credential store — `pmcp::shared::credential_store` addressed by `(issuer, account, server)`, with an on-disk `FileCredentialStore` that `cargo pmcp auth` writes through\n- **Agents & Teams**: the `pmcp-agent` loop, four reference team servers, and the portable AI-Package format — see [Agents & Teams](#agents--teams) above\n- **MCP Apps**: Rich interactive HTML UI widgets served from MCP servers — works with ChatGPT, Claude Desktop, and other MCP clients. Live preview with browser-style DevTools (resizable panel, network/events/protocol/bridge tabs)\n- **MCP Tasks**: Shared client/server task lifecycle with pluggable stores (in-memory and DynamoDB) and task variables — the v2 shape is an extension and is still provisional\n- **Conformance Test Suite**: 19-scenario conformance engine across 5 domains with `cargo pmcp test conformance` and `mcp-tester conformance` CLI integration\n- **Tower Middleware**: DNS rebinding protection, CORS with origin-locked headers, configurable security headers — production-ready HTTP stack\n- **PMCP Server**: MCP server exposing SDK developer tools (test, scaffold, schema export) via Streamable HTTP, deployed on AWS Lambda\n- **Uniform Constructor DX**: Default impls, builders, and constructors for all protocol types — dramatically improved ergonomics\n- **85 examples in [`examples/`](examples/)**: runnable coverage of the SDK surface (119 example targets across the whole workspace)\n\n**Full changelog**: [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## Core Features\n\n### 🚀 **Transport Layer**\n- **stdio**: Standard input/output for CLI integration\n- **HTTP/SSE**: Streamable HTTP with Server-Sent Events\n- **WebSocket**: Full-duplex with auto-reconnection\n- **WASM**: Browser and Cloudflare Workers support\n\n### 🛠️ **Type-Safe Development**\n- **Automatic Schema Generation**: From Rust types using `schemars`\n- **Compile-Time Validation**: Type-checked tool arguments\n- **Runtime Validation**: Against generated JSON schemas\n- **Zero Unwraps**: Explicit error handling throughout\n\n### 🔐 **Security & Auth**\n- **OAuth 2.0**: Full auth context pass-through\n- **OIDC Discovery**: Automatic provider configuration\n- **Bearer Tokens**: Standard authentication\n- **Path Validation**: Secure file system access\n\n### 🧪 **Testing & Quality**\n- **mcp-tester**: Comprehensive server testing tool\n- **Scenario Generation**: Auto-generate test cases\n- **Property Testing**: Invariant validation\n- **Quality Gates**: fmt, clippy, coverage enforcement\n\n### ⚡ **Performance**\n- **16x faster** than TypeScript SDK\n- **50x lower memory** usage\n- **SIMD Parsing**: 10.3x SSE speedup with AVX2/SSE4.2\n- **Connection Pooling**: Smart load balancing\n\n### 🏭 **Toyota Way Quality**\n- **Zero Technical Debt**: TDG score 0.76\n- **Jidoka**: Stop the line on defects\n- **Genchi Genbutsu**: Go and see (evidence-based)\n- **Kaizen**: Continuous improvement\n- **No Unwraps**: Explicit error handling only\n\n---\n\n## Documentation\n\n### 📖 Primary Resources\n\n- **[PMCP Documentation Portal](https://paiml.github.io/rust-mcp-sdk/)** - Landing page for all documentation\n- **[pmcp-book](https://paiml.github.io/rust-mcp-sdk/book/)** - Comprehensive reference guide (27 chapters)\n- **[pmcp-course](https://paiml.github.io/rust-mcp-sdk/course/)** - Hands-on course with quizzes and exercises\n- **[API Reference](https://docs.rs/pmcp)** - Complete API documentation\n- **[cargo-pmcp Guide](cargo-pmcp/README.md)** - CLI toolkit documentation\n\n### 📚 Additional Resources\n\n- **[Examples](examples/)** - 85 working examples in `examples/` (119 example targets workspace-wide)\n- **[CHANGELOG](CHANGELOG.md)** - Version history\n- **[Migration Guides](docs/)** - Upgrade instructions\n- **[Contributing](CONTRIBUTING.md)** - How to contribute\n\n### 🎯 Quick Links\n\n- [Quick Start Tutorial](https://paiml.github.io/rust-mcp-sdk/book/ch01_5-quick-start-tutorial.html)\n- [Your First Server](https://paiml.github.io/rust-mcp-sdk/book/ch02-first-server.html)\n- [Course: Getting Started](https://paiml.github.io/rust-mcp-sdk/course/part1-foundations/ch01-enterprise-case.html)\n- [Testing Guide](https://paiml.github.io/rust-mcp-sdk/course/part4-testing/ch11-local-testing.html)\n- [Production Deployment](https://paiml.github.io/rust-mcp-sdk/course/part3-deployment/ch07-deployment.html)\n\n---\n\n## Examples\n\nThe SDK ships **85 runnable examples** in [`examples/`](examples/) — 119 example targets across the\nwhole workspace — covering the full SDK surface:\n\n```bash\n# Basic examples\ncargo run --example c01_client_initialize   # Client setup\ncargo run --example s01_basic_server        # Basic server\ncargo run --example c02_client_tools        # Tool usage\n\n# Type-safe tools (v1.6.0+)\ncargo run --example s16_typed_tools --features schema-generation\ncargo run --example s17_advanced_typed_tools --features schema-generation\n\n# Advanced features\ncargo run --example s28_authentication      # OAuth/Bearer\ncargo run --example t01_websocket_transport # WebSocket\ncargo run --example m01_basic_middleware    # Middleware chain\n\n# Agent Skills (SEP-2640) — dual-surface skill + prompt\ncargo run --example s44_server_skills --features skills,full\ncargo run --example c10_client_skills --features skills,full\n\n# Agents & Teams — an agent loop, and four reference servers cooperating\ncargo run --example s49_sampling_host\ncargo run -p pmcp-agent --example s50_standalone_vs_sampled\ncargo run -p pmcp-team-servers --example doc_review_team --features runtime\n\n# MCP 2026-07-28 (v2) — start the SERVER first, in its own terminal; each client\n# takes the server address as its argument and defaults to where the server binds\ncargo run --example s47_v2_stateless_mrtr --features full   # serves on 127.0.0.1:8147\ncargo run --example s48_v2_mrtr_client --features full      # then, in another terminal\ncargo run --example s53_v2_agent_client --features full     # the pmcp-agent connector, v2 with v1 fallback\n\n# MCP 2026-07-28 (v2) Tasks — same rule: server first, then the agent\ncargo run --example s50_v2_tasks_server --features full     # serves on 127.0.0.1:8150\ncargo run --example s51_v2_tasks_agent --features full\n\n# Testing (mcp-tester is a standalone Cargo project in examples/26-server-tester)\ncargo install mcp-tester && mcp-tester test http://localhost:8080\n\n# AI-assisted development\n# See ai-agents/README.md for Kiro and Claude Code setup\n```\n\nSee [examples/README.md](examples/README.md) for complete list.\n\n---\n\n## MCP Server Tester\n\nComprehensive testing tool for validating MCP server implementations.\n\n**Features:**\n- Protocol compliance validation (JSON-RPC 2.0, MCP spec)\n- Multi-transport support (HTTP, HTTPS, WebSocket, stdio)\n- Tool discovery and testing\n- CI/CD ready with JSON output\n\n**Installation:**\n```bash\ncargo install mcp-server-tester\n\n# Or download pre-built binaries from releases\n```\n\n**Usage:**\n```bash\n# Test a server\nmcp-tester test http://localhost:8080\n\n# Protocol compliance check\nmcp-tester compliance http://localhost:8080 --strict\n\n# Connection diagnostics\nmcp-tester diagnose http://localhost:8080\n```\n\n**Learn more**: [examples/26-server-tester/README.md](examples/26-server-tester/README.md)\n\n---\n\n## Quality & Performance\n\n### Toyota Way Principles\n\nPMCP is built following Toyota Production System principles:\n\n- **Jidoka (自働化)**: Automation with human touch\n  - Quality gates stop builds on defects\n  - Zero tolerance for `unwrap()` in production\n  - Comprehensive error handling with context\n\n- **Genchi Genbutsu (現地現物)**: Go and see\n  - Evidence-based decisions with metrics\n  - PMAT quality analysis (TDG score 0.76)\n  - Comprehensive testing (unit, property, fuzz)\n\n- **Kaizen (改善)**: Continuous improvement\n  - Regular benchmarking and optimization\n  - Performance regression prevention\n  - Community-driven enhancements\n\n### Quality Metrics\n\n- **TDG Score**: 0.76 (production-ready)\n- **Technical Debt**: Minimal (436h across entire codebase)\n- **Complexity**: All functions ≤25 complexity\n- **Coverage**: 52% line coverage, 100% function coverage\n- **Linting**: Zero clippy warnings in production code\n\n### Performance Benchmarks\n\n```\nMetric                  PMCP (Rust)     TypeScript SDK    Improvement\n────────────────────────────────────────────────────────────────────\nOverall Speed           16x             1x                16x faster\nMemory Usage            <10 MB          ~500 MB           50x lower\nSSE Parsing             336,921 ev/s    32,691 ev/s       10.3x faster\nJSON-RPC Parsing        195,181 docs/s  N/A               SIMD-optimized\nRound-trip Latency      <100 μs         ~1-2 ms           10-20x faster\nBase64 Operations       252+ MB/s       N/A               Optimized\n```\n\n**Run benchmarks:**\n```bash\nmake bench                           # General benchmarks\ncargo run --example t08_simd_parsing_performance  # SIMD-specific\n```\n\n---\n\n## WebAssembly Support\n\nFull WASM support for browser and edge deployment:\n\n**Targets:**\n- **Cloudflare Workers** (wasm32-unknown-unknown)\n- **WASI Runtimes** (wasm32-wasi)\n- **Browser** (wasm-bindgen)\n\n**Quick start:**\n```bash\n# Build for Cloudflare Workers\ncargo build --target wasm32-unknown-unknown --no-default-features --features wasm\n\n# Deploy\nmake cloudflare-sdk-deploy\n```\n\n**Learn more**: [WASM Guide](docs/WASM_TARGETS.md) | [WASM Example](examples/wasm-mcp-server/)\n\n---\n\n## Development\n\n### Prerequisites\n- Rust 1.83.0 or later\n- Git\n\n### Setup\n```bash\ngit clone https://github.com/paiml/rust-mcp-sdk\ncd rust-mcp-sdk\n\n# Install development tools\nmake setup\n\n# Run quality checks\nmake quality-gate\n```\n\n### Testing\n```bash\nmake test-all           # All tests\nmake test-property      # Property tests\nmake coverage           # Coverage report\nmake mutants            # Mutation tests\n```\n\n### Contributing\n\nWe welcome contributions! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Ensure quality gates pass (`make quality-gate`)\n4. Commit with conventional commits\n5. Push and open a Pull Request\n\n**See**: [CONTRIBUTING.md](CONTRIBUTING.md)\n\n---\n\n## Compatibility\n\n| Feature | TypeScript SDK v2.0 | PMCP v2.0 (Rust) |\n|---------|---------------------|------------------|\n| Protocol Version | 2025-11-25 | 2025-11-25 (+ 2024-11-05 compat) |\n| Transports | stdio, SSE, WebSocket | stdio, SSE, WebSocket, WASM |\n| Authentication | OAuth 2.0, Bearer | OAuth 2.0, Bearer, OIDC |\n| Tools | ✓ | ✓ (Type-safe + outputSchema) |\n| Prompts | ✓ | ✓ (Workflows) |\n| Resources | ✓ | ✓ (Subscriptions) |\n| Sampling | ✓ | ✓ |\n| MCP Apps | ✓ | ✓ (Preview + DevTools) |\n| Agent Skills (SEP-2640) | ✓ | ✓ (dual-surface skill + prompt, byte-equal) |\n| Tower Middleware | N/A | ✓ (DNS rebinding, CORS, security headers) |\n| Performance | 1x | 16x faster |\n| Memory | Baseline | 50x lower |\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Acknowledgments\n\n- [Model Context Protocol](https://modelcontextprotocol.io) specification\n- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for reference implementation\n- [PAIML MCP Agent Toolkit](https://github.com/paiml/paiml-mcp-agent-toolkit) for quality standards\n- Community contributors and early adopters\n\n---\n\n## Links\n\n- **Documentation Portal**: https://paiml.github.io/rust-mcp-sdk/\n- **Reference Guide**: https://paiml.github.io/rust-mcp-sdk/book/\n- **Course**: https://paiml.github.io/rust-mcp-sdk/course/\n- **Crates.io**: https://crates.io/crates/pmcp\n- **API Docs**: https://docs.rs/pmcp\n- **Issues**: https://github.com/paiml/rust-mcp-sdk/issues\n- **Discussions**: https://github.com/paiml/rust-mcp-sdk/discussions\n\n---\n\n**Built with 🦀 Rust and ❤️ following Toyota Way principles**\n",
  "bytes": 36567,
  "sha": "50a27b0d86c9f2fec8241405662a5a7c35c630ff95695383aca0034e5fa3a3eb",
  "repo_slug": "paiml/rust-mcp-sdk",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_paiml_pmcp_6f116ada/readme"
}