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:
[]
= "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
# Deploy SDK-based Worker
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
# Other book commands
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
# Basic server with tools
# Client tool usage
# Server with resources
# Client resource access
# Server with prompts
# Client prompts usage
# Logging
# Authentication (OAuth, Bearer tokens)
# Progress notifications
# Request cancellation
# Error handling patterns
# WebSocket transport
# LLM sampling operations
# Middleware and interceptors
# OAuth server with authentication
# Completable prompts
# Resource watching with file system monitoring
# Input elicitation
# OIDC discovery and authentication
# Procedural macros for tools
# Streamable HTTP server (stateful with sessions)
# Streamable HTTP server (stateless for serverless)
# Streamable HTTP client
# WASM client (browser-based) - see examples/wasm-client/README.md
&&
# WebSocket server implementation with connection management
# MCP server tester - comprehensive testing tool for MCP servers
# HTTP/SSE transport optimizations with connection pooling
# Connection pooling and load balancing demonstration
# Advanced middleware system with circuit breakers and rate limiting
# Advanced error recovery with adaptive retry and health monitoring
# Complete advanced error recovery example with cascade detection
# SIMD parsing performance demonstration with benchmarks
# NEW in v1.4.1 - Enhanced Examples with TypeScript SDK Parity
# Multiple parallel clients with concurrent operations and error handling
# Structured output schemas with advanced data validation
# Tool with LLM sampling integration for text processing
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:
# Binary will be at target/release/mcp-tester
Usage
# Test an MCP server
# Test with tools validation
# Protocol compliance check
# Connection diagnostics
# Compare two servers
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:
ToolResulttype 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_usagedemonstrating 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.await?;
๐ Middleware System
Powerful middleware chain for request/response processing:
use ;
let mut chain = new;
chain.add;
chain.add;
๐ Message Batching & Debouncing
Optimize notification delivery with batching and debouncing:
use ;
let batcher = new;
Quick Start
Client Example
use ;
async
Server Example
use ;
use async_trait;
use Value;
;
async
Transport Options
stdio (Default)
let transport = new;
Streamable HTTP (Stateful)
use ;
let config = StreamableHttpTransportConfig ;
let transport = new;
Streamable HTTP (Stateless/Serverless)
use ;
let config = StreamableHttpTransportConfig ;
let transport = new;
WebSocket
use ;
let config = WebSocketConfig ;
let transport = new;
WASM (Browser)
// For WebSocket in browser
use ;
let transport = connect.await?;
// For HTTP in browser
use ;
let config = WasmHttpConfig ;
let transport = new;
Development
Prerequisites
- Rust 1.80.0 or later
- Git
Setup
# Clone the repository
# Install development tools
# Run quality checks
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
# Run property tests (slower, more thorough)
# Generate coverage report
# Run mutation tests
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Ensure all quality checks pass (
make quality-gate) - Commit your changes (following conventional commits)
- Push to the branch (
git push origin feature/amazing-feature) - 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:
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.