Skip to content

paiml/pmcp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

22 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

PMCP - Pragmatic Model Context Protocol

CI Quality Gate Coverage Crates.io Documentation License: MIT Rust 1.80+

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

Features

  • πŸš€ 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

Installation

Add to your Cargo.toml:

[dependencies]
pmcp = "0.3.1"

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

# Message batching and debouncing
cargo run --example 16_batching

See the examples directory for detailed documentation.

What's New in v0.2.0

πŸ†• WebSocket Transport with Auto-Reconnection

Full WebSocket support with automatic reconnection, exponential backoff, and keepalive 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();

HTTP/SSE

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);

WebSocket

use pmcp::{WebSocketTransport, WebSocketConfig};

let config = WebSocketConfig {
    url: "ws://localhost:8080".parse()?,
    auto_reconnect: true,
    ..Default::default()
};
let transport = WebSocketTransport::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 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

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

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

License

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

Acknowledgments

About

Pragmatic AI Labs MCP SDK

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 3

  •  
  •  
  •