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
- π Full Protocol Support: Complete implementation of MCP specification
- π Multiple Transports: stdio, HTTP/SSE, and WebSocket with auto-reconnection
- π‘οΈ Type Safety: Compile-time protocol validation
- β‘ Zero-Copy Parsing: Efficient message handling
- π Built-in Auth: OAuth 2.0 and bearer token support
- π€ LLM Sampling: Native support for model sampling operations
- π Middleware System: Request/response interceptors for custom logic
- π Retry Logic: Built-in exponential backoff for resilient connections
- π¦ Message Batching: Efficient notification grouping and debouncing
- π¬ Resource Subscriptions: Real-time resource change notifications
- β Request Cancellation: Full async cancellation support with CancellationToken
- π WebSocket Server: Complete server-side WebSocket transport implementation
- π Roots Management: Directory/URI registration and management
- π Comprehensive Testing: Property tests with 100% invariant coverage
- ποΈ Quality First: Zero technical debt, no unwraps in production code
Add to your Cargo.toml
:
[dependencies]
pmcp = "0.3.1"
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
# Message batching and debouncing
cargo run --example 16_batching
See the examples directory for detailed documentation.
Full WebSocket support with automatic reconnection, exponential backoff, and keepalive ping/pong.
HTTP transport with Server-Sent Events for real-time notifications and long-polling 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?;
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())));
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()
});
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(())
}
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(())
}
let transport = StdioTransport::new();
use pmcp::{HttpTransport, HttpConfig};
let config = HttpConfig {
base_url: "http://localhost:8080".parse()?,
sse_endpoint: Some("/events".to_string()),
..Default::default()
};
let transport = HttpTransport::new(config);
use pmcp::{WebSocketTransport, WebSocketConfig};
let config = WebSocketConfig {
url: "ws://localhost:8080".parse()?,
auto_reconnect: true,
..Default::default()
};
let transport = WebSocketTransport::new(config);
- Rust 1.80.0 or later
- Git
# 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
This project maintains pmat-level quality standards:
- Zero Technical Debt: No TODO/FIXME comments
- No
unwrap()
: All errors handled explicitly - 100% Documentation: Every public API documented
- Property Testing: Comprehensive invariant testing
- Benchmarks: Performance regression prevention
# 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
- 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
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
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 | β | β |
Benchmarks show 10x improvement over TypeScript SDK:
- Message parsing: < 1ΞΌs
- Round-trip latency: < 100ΞΌs (stdio)
- Memory usage: < 10MB baseline
Run benchmarks:
make bench
This project is licensed under the MIT License - see the LICENSE file for details.
- Model Context Protocol specification
- TypeScript SDK for reference implementation
- PAIML MCP Agent Toolkit for quality standards