https://docs.rs/pmcp

PMCP - Pragmatic Model Context Protocol

A high-quality Rust implementation of the Model Context Protocol (MCP) SDK, maintaining full compatibility with the TypeScript SDK while leveraging Rust's performance and safety guarantees.

Code Name: Angel Rust

🎉 Claude Code Compatible! Version 1.4.0+ includes full JSON-RPC 2.0 compatibility, enabling seamless integration with Claude Code and all standard MCP clients. If you're experiencing connection issues, please upgrade to v1.4.1+.

🎉 Version 1.4.2 - MCP Server Tester & Enhanced Compatibility!

🧪 NEW: MCP Server Tester Tool

• 🔍 Protocol Compliance: Validates JSON-RPC 2.0 and MCP protocol compliance
• 🌐 Multi-Transport Support: Tests HTTP, HTTPS, WebSocket, and stdio transports
• 📊 Comprehensive Diagnostics: Layer-by-layer connection troubleshooting
• 🎯 CI/CD Ready: JSON output for automated testing pipelines

🎉 Version 1.4.1 - Enhanced Developer Experience & TypeScript Parity!

🔧 NEW: Enhanced Type Ergonomics

• ✨ ToolResult Type Alias: Improved developer experience with use pmcp::ToolResult
• 📚 Comprehensive Documentation: Enhanced API docs with 4 complete usage examples
• 🧪 100% Test Coverage: Property tests, unit tests, and doctests for reliability
• 💯 Backward Compatible: Zero breaking changes, seamless upgrade experience

📖 NEW: Complete Example Library

• 🤖 Tool-with-Sampling Server: Demonstrates LLM sampling integration for text processing
• 🔀 Multiple Parallel Clients: Shows concurrent client operations and error handling
• 🏗️ Structured Output Schemas: Advanced data validation and structured responses
• 📝 TDD Methodology: All examples developed using Test-Driven Development

🏭 Quality Excellence (v1.4.1)

• 📊 72% Line Coverage: Comprehensive test coverage with 100% function coverage
• 🎯 Zero Defects: All quality gates passing (lint + coverage)
• 🔍 Toyota Way Standards: Jidoka principles with zero tolerance for defects
• ✅ Full TypeScript SDK Compatibility: Complete feature parity verified

---

🎉 Version 1.4.0 - High-Performance Enterprise Features!

🚀 WebSocket Server & Advanced Transports

• 🌐 Complete WebSocket Server: Production-ready server implementation with connection management
• ⚡ HTTP/SSE Optimizations: 10x faster Server-Sent Events processing with connection pooling
• 🔗 Connection Pooling: Smart load balancing across multiple transport connections
• 🛡️ Advanced Middleware: Circuit breakers, rate limiting, compression, and metrics collection

🔧 Advanced Error Recovery

• 🔄 Adaptive Retry: Intelligent retry strategies with jitter and exponential backoff
• 🏥 Health Monitoring: Automatic cascade failure detection and prevention
• 📊 Recovery Metrics: Comprehensive error recovery analytics and monitoring
• ⏱️ Deadline Management: Timeout-aware operations with deadline propagation

⚡ SIMD Parsing Acceleration

• 🔥 10.3x SSE Parsing Speedup: Vectorized Server-Sent Events processing
• 💻 CPU Feature Detection: Runtime AVX2/SSE4.2 optimization
• 📦 Batch Processing: Parallel JSON-RPC parsing with 119% efficiency gains
• 🧠 Smart Fallbacks: Automatic scalar fallback when SIMD unavailable

🏭 Toyota Way Quality Excellence

• 📊 PMAT Quality Analysis: Comprehensive code quality metrics with TDG scoring (0.76)
• 🎯 Quality Gates: Zero-tolerance defect policy with automated enforcement
• 🔍 Fuzzing Infrastructure: Comprehensive fuzz testing for protocol robustness
• ✅ Full TypeScript SDK v1.17.5+ Compatibility: 100% protocol compatibility verified
• 🚀 Performance: 16x faster than TypeScript SDK, 50x lower memory usage

Core Features

🚀 Transport Layer

• 🔄 Multiple Transports: stdio, HTTP/SSE, and WebSocket with auto-reconnection
• 🌐 WebSocket Server: Complete server-side WebSocket transport implementation
• 🔗 Connection Pooling: Smart load balancing with health monitoring
• ⚡ HTTP/SSE Optimizations: High-performance streaming with connection pooling
• 💾 Event Store: Connection resumability and event persistence for recovery

🛡️ Advanced Middleware & Recovery

• 🔌 Middleware System: Circuit breakers, rate limiting, compression, metrics
• 🔄 Adaptive Retry: Intelligent retry strategies with jitter and exponential backoff
• 🏥 Health Monitoring: Automatic cascade failure detection and prevention
• ⏱️ Deadline Management: Timeout-aware operations with deadline propagation
• 📊 Recovery Metrics: Comprehensive error analytics and monitoring

⚡ High-Performance Parsing

• 🔥 SIMD Acceleration: 10.3x SSE parsing speedup with AVX2/SSE4.2 optimization
• 📦 Batch Processing: Parallel JSON-RPC parsing with 119% efficiency gains
• 🧠 Smart CPU Detection: Runtime feature detection with automatic fallbacks
• 💻 Zero-Copy Parsing: Efficient message handling with vectorized operations

🔐 Security & Protocol

• 🚀 Full Protocol Support: Complete implementation of MCP specification v1.0
• 🛡️ Type Safety: Compile-time protocol validation
• 🔐 Built-in Auth: OAuth 2.0, OIDC discovery, and bearer token support
• 🔗 URI Templates: Complete RFC 6570 implementation for dynamic URIs
• 📡 SSE Parser: Full Server-Sent Events support for streaming responses

🤖 Developer Experience

• 🤖 LLM Sampling: Native support for model sampling operations
• 📦 Message Batching: Efficient notification grouping and debouncing
• 📬 Resource Subscriptions: Real-time resource change notifications
• ❌ Request Cancellation: Full async cancellation support with CancellationToken
• 📁 Roots Management: Directory/URI registration and management
• 📊 Comprehensive Testing: Property tests, fuzzing, and integration tests
• 🏗️ Quality First: Zero technical debt, no unwraps in production code

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
pmcp = "1.4"

⚠️ Important for Claude Code users: Version 1.4.0+ is required for Claude Code compatibility. Earlier versions use a different message format that is incompatible with standard MCP clients. See the Migration Guide if upgrading from < 1.4.0.

🌐 WebAssembly Support

The SDK fully supports WebAssembly compilation for deployment to:

• Cloudflare Workers (wasm32-unknown-unknown)
• WASI Runtimes (wasm32-wasi)
• Browser Environments via wasm-bindgen

WASM Quick Start

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

# Deploy SDK-based Worker
make cloudflare-sdk-deploy

WASM Documentation

• WASM Target Guide - Detailed guide for different WASM targets
• WASM MCP Server Example - Write once, deploy everywhere (Cloudflare & Fermyon)
• WASM API Reference - WasmServerCore documentation

📚 Documentation

Complete PMCP Guide

The comprehensive PMCP Guide provides detailed documentation with interactive examples:

📖 Read Online - Live documentation updated automatically

# Local development
make book-serve    # Serve at http://localhost:3000

# Other book commands  
make book          # Build the book
make book-open     # Build and open in browser
make book-clean    # Clean build artifacts

The guide covers everything from basic concepts to advanced patterns:

• Getting Started - Installation, first server/client
• Core Concepts - Tools, resources, prompts, error handling
• Advanced Features - Auth, transports, middleware, performance
• Real-World Examples - Production patterns and best practices
• TypeScript Migration - Complete compatibility guide

Examples

The SDK includes comprehensive examples for all major features:

# Client initialization and connection
cargo run --example 01_client_initialize

# Basic server with tools
cargo run --example 02_server_basic

# Client tool usage
cargo run --example 03_client_tools

# Server with resources
cargo run --example 04_server_resources

# Client resource access
cargo run --example 05_client_resources

# Server with prompts
cargo run --example 06_server_prompts

# Client prompts usage
cargo run --example 07_client_prompts

# Logging
cargo run --example 08_logging

# Authentication (OAuth, Bearer tokens)
cargo run --example 09_authentication

# Progress notifications
cargo run --example 10_progress_notifications

# Request cancellation
cargo run --example 11_request_cancellation

# Error handling patterns
cargo run --example 12_error_handling

# WebSocket transport
cargo run --example 13_websocket_transport

# LLM sampling operations
cargo run --example 14_sampling_llm

# Middleware and interceptors
cargo run --example 15_middleware

# OAuth server with authentication
cargo run --example 16_oauth_server

# Completable prompts
cargo run --example 17_completable_prompts

# Resource watching with file system monitoring
cargo run --example 18_resource_watcher

# Input elicitation
cargo run --example 19_elicit_input

# OIDC discovery and authentication
cargo run --example 20_oidc_discovery

# Procedural macros for tools
cargo run --example 21_macro_tools --features macros

# Streamable HTTP server (stateful with sessions)
cargo run --example 22_streamable_http_server_stateful --features streamable-http

# Streamable HTTP server (stateless for serverless)
cargo run --example 23_streamable_http_server_stateless --features streamable-http

# Streamable HTTP client
cargo run --example 24_streamable_http_client --features streamable-http

# WASM client (browser-based) - see examples/wasm-client/README.md
cd examples/wasm-client && bash build.sh

# WebSocket server implementation with connection management
cargo run --example 25_websocket_server --features full

# MCP server tester - comprehensive testing tool for MCP servers
cargo run --example 26-server-tester -- test http://localhost:8080

# HTTP/SSE transport optimizations with connection pooling
cargo run --example 26_http_sse_optimizations --features full

# Connection pooling and load balancing demonstration
cargo run --example 27_connection_pooling --features full

# Advanced middleware system with circuit breakers and rate limiting
cargo run --example 28_advanced_middleware --features full

# Advanced error recovery with adaptive retry and health monitoring
cargo run --example 29_advanced_error_recovery --features full

# Complete advanced error recovery example with cascade detection
cargo run --example 31_advanced_error_recovery --features full

# SIMD parsing performance demonstration with benchmarks
cargo run --example 32_simd_parsing_performance --features full

# NEW in v1.4.1 - Enhanced Examples with TypeScript SDK Parity

# Multiple parallel clients with concurrent operations and error handling
cargo run --example 47_multiple_clients_parallel --features full

# Structured output schemas with advanced data validation
cargo run --example 48_structured_output_schema --features full

# Tool with LLM sampling integration for text processing
cargo run --example 49_tool_with_sampling_server --features full

MCP Server Tester

The SDK includes a comprehensive testing tool for validating MCP server implementations. The tester ensures protocol compliance, validates capabilities, and provides detailed diagnostics.

Features

• Protocol Compliance: Validates JSON-RPC 2.0 and MCP protocol compliance
• Multi-Transport Support: Tests HTTP, HTTPS, WebSocket, and stdio transports
• Comprehensive Diagnostics: Layer-by-layer connection troubleshooting
• Tool Testing: Discover and test individual tools with custom arguments
• CI/CD Ready: JSON output for automated testing pipelines

Installation

Pre-built binaries are available from releases:

• mcp-tester-linux-x86_64 (Linux)
• mcp-tester-macos-x86_64 (macOS Intel/Apple Silicon via Rosetta)
• mcp-tester-windows-x86_64.exe (Windows)

Or build from source:

cargo build --release --package mcp-server-tester
# Binary will be at target/release/mcp-tester

Usage

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

# Test with tools validation
mcp-tester test http://localhost:8080 --with-tools

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

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

# Compare two servers
mcp-tester compare http://server1:8080 http://server2:8080

For detailed usage, see examples/26-server-tester/README.md.

See the examples directory for detailed documentation.

🤖 Background Agents

PMCP serves as the foundation for building background agents that provide continuous AI assistance. See our Background Agents Guide for examples including:

• PMAT - Continuous code quality monitoring with Toyota Way compliance
• Ruchy - Language server agent for the Ruchy programming language
• Build your own background agent using PMCP as the transport layer

What's New in v1.4.1 - Developer Experience Improvements

🔧 ToolResult Type Alias (GitHub Issue #37)

• New: ToolResult type alias now available from crate root: use pmcp::ToolResult;
• Compatibility: Fully compatible with existing CallToolResult - they are the same type
• Documentation: Comprehensive documentation with examples and usage patterns
• Testing: Full test coverage including unit tests, property tests, and doctests
• Examples: New cargo run --example toolresult_usage demonstrating all features

What's New in v1.4.0 - Enterprise Performance Edition

🌐 Production WebSocket Server (PMCP-4001)

• Complete server-side WebSocket implementation with connection lifecycle management
• Automatic ping/pong keepalive and graceful connection handling
• WebSocket-specific middleware integration and error recovery
• Production-ready with comprehensive connection monitoring

⚡ HTTP/SSE Transport Optimizations (PMCP-4002)

• 10x performance improvement in Server-Sent Events processing
• Connection pooling with intelligent load balancing strategies
• Optimized SSE parser with reduced memory allocations
• Enhanced streaming performance for real-time applications

🔗 Advanced Connection Management (PMCP-4003)

• Smart connection pooling with health monitoring and failover
• Load balancing strategies: round-robin, least-connections, weighted
• Automatic unhealthy connection detection and replacement
• Connection pool metrics and monitoring integration

🛡️ Enterprise Middleware System (PMCP-4004)

• Advanced middleware chain with circuit breakers and rate limiting
• Compression middleware with configurable algorithms
• Metrics collection middleware with performance monitoring
• Priority-based middleware execution with dependency management

🔧 Advanced Error Recovery (PMCP-4005)

• Adaptive retry strategies with configurable jitter patterns
• Deadline-aware recovery with timeout propagation
• Bulk operation recovery with partial failure handling
• Health monitoring with cascade failure detection and prevention
• Recovery coordination with event-driven architecture

⚡ SIMD Parsing Acceleration (PMCP-4006)

• 10.3x SSE parsing speedup using AVX2/SSE4.2 vectorization
• Runtime CPU feature detection with automatic fallbacks
• Parallel JSON-RPC batch processing with 119% efficiency gains
• Memory-efficient SIMD operations with comprehensive metrics

What's New in v1.0 (In Development)

🎯 Procedural Macros

• #[tool] attribute for automatic tool handler generation
• #[tool_router] for collecting tools from impl blocks
• Automatic JSON schema generation from Rust types
• 70% reduction in boilerplate code

🌍 Enhanced WASM Support

• Full WebAssembly support for browser environments
• Dual transport support: WebSocket and HTTP
• HTTP transport for stateless/serverless MCP servers (AWS Lambda, Vercel, etc.)
• Cross-platform runtime abstraction
• Interactive browser example with modern UI
• CORS-enabled streamable HTTP servers
• TypeScript definitions for seamless integration

🔄 Streamable HTTP Transport

• Stateful mode with session management for traditional deployments
• Stateless mode optimized for serverless (AWS Lambda, Vercel Functions)
• Server-Sent Events (SSE) support for real-time streaming
• Automatic protocol version negotiation
• Built-in CORS support for browser clients
• Examples for both client and server implementations

🚀 Enhanced Developer Experience

• Type-safe parameter handling with compile-time validation
• Automatic error conversion and handling
• Improved documentation with 200+ examples
• Property-based testing for all new features

What's New in v0.6.6

🔐 OIDC Discovery Support

• Full OpenID Connect discovery implementation
• Automatic retry on CORS/network errors
• Token exchange with explicit JSON accept headers
• Comprehensive auth client module

🔒 Transport Response Isolation

• Unique transport IDs prevent cross-transport response routing
• Enhanced protocol safety for multiple concurrent connections
• Request-response correlation per transport instance

📚 Enhanced Documentation

• 135+ doctests with real-world examples
• Complete property test coverage
• New OIDC discovery example (example 20)

What's New in v0.2.0

🆕 WebSocket Transport with Auto-Reconnection

Full WebSocket support with automatic reconnection, exponential backoff, and keep-alive ping/pong.

🆕 HTTP/SSE Transport

HTTP transport with Server-Sent Events for real-time notifications and long-polling support.

🆕 LLM Sampling Support

Native support for model sampling operations with the createMessage API:

let result = client.create_message(CreateMessageRequest {
    messages: vec![SamplingMessage {
        role: Role::User,
        content: Content::Text { text: "Hello!".to_string() },
    }],
    ..Default::default()
}).await?;

🆕 Middleware System

Powerful middleware chain for request/response processing:

use pmcp::{MiddlewareChain, LoggingMiddleware, AuthMiddleware};

let mut chain = MiddlewareChain::new();
chain.add(Arc::new(LoggingMiddleware::default()));
chain.add(Arc::new(AuthMiddleware::new("token".to_string())));

🆕 Message Batching & Debouncing

Optimize notification delivery with batching and debouncing:

use pmcp::{MessageBatcher, BatchingConfig};

let batcher = MessageBatcher::new(BatchingConfig {
    max_batch_size: 10,
    max_wait_time: Duration::from_millis(100),
    ..Default::default()
});

Quick Start

Client Example

use pmcp::{Client, StdioTransport, ClientCapabilities};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client with stdio transport
    let transport = StdioTransport::new();
    let mut client = Client::new(transport);
    
    // Initialize connection
    let server_info = client.initialize(ClientCapabilities::default()).await?;
    println!("Connected to: {}", server_info.server_info.name);
    
    // List available tools
    let tools = client.list_tools(None).await?;
    for tool in tools.tools {
        println!("Tool: {} - {:?}", tool.name, tool.description);
    }
    
    // Call a tool
    let result = client.call_tool("get-weather", serde_json::json!({
        "location": "San Francisco"
    })).await?;
    
    Ok(())
}

Server Example

use pmcp::{Server, ServerCapabilities, ToolHandler};
use async_trait::async_trait;
use serde_json::Value;

struct WeatherTool;

#[async_trait]
impl ToolHandler for WeatherTool {
    async fn handle(&self, args: Value) -> pmcp::Result<Value> {
        let location = args["location"].as_str()
            .ok_or_else(|| pmcp::Error::validation("location required"))?;
        
        // Implement weather fetching logic
        Ok(serde_json::json!({
            "temperature": 72,
            "condition": "sunny",
            "location": location
        }))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = Server::builder()
        .name("weather-server")
        .version("1.0.0")
        .capabilities(ServerCapabilities::tools_only())
        .tool("get-weather", WeatherTool)
        .build()?;
    
    // Run with stdio transport
    server.run_stdio().await?;
    Ok(())
}

Transport Options

stdio (Default)

let transport = StdioTransport::new();

Streamable HTTP (Stateful)

use pmcp::{StreamableHttpTransport, StreamableHttpTransportConfig};

let config = StreamableHttpTransportConfig {
    url: "http://localhost:3000".parse()?,
    enable_sse: true,  // Use SSE for real-time updates
    session_id: Some("my-session".to_string()),
    ..Default::default()
};
let transport = StreamableHttpTransport::new(config);

Streamable HTTP (Stateless/Serverless)

use pmcp::{StreamableHttpTransport, StreamableHttpTransportConfig};

let config = StreamableHttpTransportConfig {
    url: "http://localhost:8081".parse()?,
    enable_sse: false,  // Simple request/response
    session_id: None,   // No session management
    ..Default::default()
};
let transport = StreamableHttpTransport::new(config);

WebSocket

use pmcp::{WebSocketTransport, WebSocketConfig};

let config = WebSocketConfig {
    url: "ws://localhost:8080".parse()?,
    auto_reconnect: true,
    ..Default::default()
};
let transport = WebSocketTransport::new(config);

WASM (Browser)

// For WebSocket in browser
use pmcp::{WasmWebSocketTransport};
let transport = WasmWebSocketTransport::connect("ws://localhost:8080").await?;

// For HTTP in browser
use pmcp::{WasmHttpTransport, WasmHttpConfig};
let config = WasmHttpConfig {
    url: "https://api.example.com/mcp".to_string(),
    extra_headers: vec![],
};
let transport = WasmHttpTransport::new(config);

Development

Prerequisites

• Rust 1.80.0 or later
• Git

Setup

# Clone the repository
git clone https://github.com/paiml/rust-pmcp
cd rust-pmcp

# Install development tools
make setup

# Run quality checks
make quality-gate

Quality Standards

This project maintains Toyota Way and PMAT-level quality standards:

• Zero Technical Debt: TDG score 0.76, production-ready with minimal technical debt
• Toyota Way Principles: Jidoka (stop the line), Genchi Genbutsu (go and see), Kaizen (continuous improvement)
• Quality Gates: PMAT quality gates enforce complexity limits and detect SATD
• No unwrap(): All errors handled explicitly with comprehensive error types
• 100% Documentation: Every public API documented with examples
• Property Testing: Comprehensive invariant testing with quickcheck
• Benchmarks: Performance regression prevention with criterion
• SIMD Optimizations: High-performance parsing with reduced complexity

Testing

# Run all tests
make test-all

# Run property tests (slower, more thorough)
make test-property

# Generate coverage report
make coverage

# Run mutation tests
make mutants

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Ensure all quality checks pass (make quality-gate)
4. Commit your changes (following conventional commits)
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Architecture

pmcp/
├── src/
│   ├── client/          # Client implementation
│   ├── server/          # Server implementation
│   ├── shared/          # Shared transport/protocol code
│   ├── types/           # Protocol type definitions
│   └── utils/           # Utility functions
├── tests/
│   ├── integration/     # Integration tests
│   └── property/        # Property-based tests
├── benches/             # Performance benchmarks
└── examples/            # Example implementations

Compatibility

Feature	TypeScript SDK	Rust SDK
Protocol Versions	2024-10-07+	2024-10-07+
Transports	stdio, SSE, WebSocket	stdio, SSE, WebSocket
Authentication	OAuth 2.0, Bearer	OAuth 2.0, Bearer
Tools	✓	✓
Prompts	✓	✓
Resources	✓	✓
Sampling	✓	✓

Performance

SIMD-Accelerated Parsing Performance (v1.4.0)

• SSE parsing: 10.3x speedup (336,921 vs 32,691 events/sec)
• JSON-RPC parsing: 195,181 docs/sec with 100% SIMD utilization
• Batch processing: 119.3% parallel efficiency with vectorized operations
• Memory efficiency: 580 bytes per document with optimized allocations

General Performance vs TypeScript SDK

• Overall performance: 16x faster than TypeScript SDK
• Message parsing: < 1μs (sub-microsecond with SIMD)
• Round-trip latency: < 100μs (stdio)
• Memory usage: 50x lower baseline (< 10MB)
• Base64 operations: 252+ MB/s throughput

Run benchmarks:

make bench                                    # General benchmarks
cargo run --example 32_simd_parsing_performance  # SIMD-specific benchmarks

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Model Context Protocol specification
• TypeScript SDK for reference implementation
• PAIML MCP Agent Toolkit for quality standards
• Alternative implementation - official rust sdk - created before I knew this existed.