pmcp 1.2.2

# PMCP - Pragmatic Model Context Protocol
<!-- QUALITY BADGES START -->
[![Quality Gate](https://img.shields.io/badge/Quality%20Gate-failing-red)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-badges.yml)
[![TDG Score](https://img.shields.io/badge/TDG%20Score-0.00-brightgreen)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-badges.yml)
[![Complexity](https://img.shields.io/badge/Complexity-clean-brightgreen)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-badges.yml)
[![Technical Debt](https://img.shields.io/badge/Tech%20Debt-0h-brightgreen)](https://github.com/paiml/rust-mcp-sdk/actions/workflows/quality-badges.yml)
<!-- QUALITY BADGES END -->

[![CI](https://github.com/paiml/pmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/paiml/pmcp/actions/workflows/ci.yml)
[![Quality Gate](https://img.shields.io/badge/Quality%20Gate-passing-brightgreen)](https://github.com/paiml/pmcp/actions/workflows/quality-badges.yml)
[![TDG Score](https://img.shields.io/badge/TDG%20Score-0.76-green)](https://github.com/paiml/pmcp/actions/workflows/quality-badges.yml)
[![Complexity](https://img.shields.io/badge/Complexity-clean-brightgreen)](https://github.com/paiml/pmcp/actions/workflows/quality-badges.yml)
[![Technical Debt](https://img.shields.io/badge/Tech%20Debt-436h-yellow)](https://github.com/paiml/pmcp/actions/workflows/quality-badges.yml)
[![Coverage](https://img.shields.io/badge/coverage-52%25-yellow.svg)](https://github.com/paiml/pmcp)
[![Crates.io](https://img.shields.io/crates/v/pmcp.svg)](https://crates.io/crates/pmcp)
[![Documentation](https://docs.rs/pmcp/badge.svg)](https://docs.rs/pmcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust 1.82+](https://img.shields.io/badge/rust-1.82+-orange.svg)](https://www.rust-lang.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-v1.17.2%2B-blue.svg)](https://modelcontextprotocol.io)

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

Code Name: *Angel Rust*

## 🎉 Version 1.2.1 - Toyota Way Quality Excellence & PMAT Integration!

- 🏭 **Toyota Way Implementation**: Zero-defect development with Jidoka, Genchi Genbutsu, and Kaizen principles
- 📊 **PMAT Quality Analysis**: Comprehensive code quality metrics with TDG scoring (0.76)
- 🎯 **Quality Gates**: Automated quality enforcement with pre-commit hooks and CI integration
- 📈 **Quality Badges**: Real-time quality metrics with GitHub Actions badges
- 🛡️ **SIMD Refactoring**: Reduced complexity while maintaining 10-50x performance improvements
- 🔒 **Security Documentation**: Enhanced PKCE and OAuth security with comprehensive docs
- ✅ **Full TypeScript SDK v1.17.2+ Compatibility**: 100% protocol compatibility verified
- 🎯 **Procedural Macros**: Simplified tool/prompt/resource definitions with `#[tool]` macro
- 🌍 **WASM/Browser Support**: Run MCP clients directly in web browsers
- 🔍 **Fuzzing Infrastructure**: Comprehensive fuzz testing for protocol robustness
- 🚀 **Performance**: 16x faster than TypeScript SDK, 50x lower memory usage

## Core Features

- 🚀 **Full Protocol Support**: Complete implementation of MCP specification v1.0
- 🔄 **Multiple Transports**: stdio, HTTP/SSE, and WebSocket with auto-reconnection
- 💾 **Event Store**: Connection resumability and event persistence for recovery
- 📡 **SSE Parser**: Full Server-Sent Events support for streaming responses
- 🔗 **URI Templates**: Complete RFC 6570 implementation for dynamic URIs
- 🛡️ **Type Safety**: Compile-time protocol validation
- ⚡ **Zero-Copy Parsing**: Efficient message handling with SIMD acceleration
- 🔐 **Built-in Auth**: OAuth 2.0, OIDC discovery, 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, fuzzing, and integration tests
- 🏗️ **Quality First**: Zero technical debt, no unwraps in production code

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
pmcp = "1.2"
```

## Examples

The SDK includes comprehensive examples for all major features:

```bash
# 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
```

See the [examples directory](examples/) for detailed documentation.

## 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 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:
```rust
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:
```rust
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:
```rust
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

```rust
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

```rust
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)
```rust
let transport = StdioTransport::new();
```

### Streamable HTTP (Stateful)
```rust
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)
```rust
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  
```rust
use pmcp::{WebSocketTransport, WebSocketConfig};

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

### WASM (Browser)
```rust
// 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

```bash
# 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

```bash
# 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:
```bash
make bench
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) specification
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) for reference implementation
- [PAIML MCP Agent Toolkit](https://github.com/paiml/paiml-mcp-agent-toolkit) for quality standards
- [Alternative implementation - official rust sdk](https://github.com/modelcontextprotocol/rust-sdk/) - created before I knew this existed.