Crate airsprotocols_mcp

Expand description

AIRS MCP - Model Context Protocol Implementation

This crate provides a complete implementation of the Model Context Protocol (MCP) built on a solid JSON-RPC 2.0 foundation with trait-based message abstractions.

§Architecture

The AIRS MCP implementation is organized in layers:

Protocol Layer (protocol): Unified JSON-RPC 2.0 + MCP protocol implementation
Transport Layer (transport): Communication transport abstractions and implementations
Integration Layer (integration): High-level MCP client and server interfaces
Providers Layer (providers): Production-ready MCP provider implementations
Shared Layer (shared): Additional MCP message structures and content types

§Core Features

§JSON-RPC 2.0 Foundation

Complete JSON-RPC 2.0 specification compliance with:

Type-safe message structures (JsonRpcRequest, JsonRpcResponse, JsonRpcNotification)
Flexible request ID support (string and numeric variants)
Trait-based serialization with consistent behavior across all message types
Comprehensive validation and error handling

§Quick Start

use airsprotocols_mcp::{JsonRpcRequest, JsonRpcMessageTrait, RequestId};
use serde_json::json;

// Create a JSON-RPC request
let request = JsonRpcRequest::new(
    "ping",
    Some(json!({"message": "hello world"})),
    RequestId::new_string("req-001")
);

// Serialize using trait method
let json = request.to_json().unwrap();
println!("Request: {}", json);

// Deserialize back to typed structure
let parsed = JsonRpcRequest::from_json(&json).unwrap();
assert_eq!(request, parsed);

§Message Types

§JsonRpcRequest

Represents a request to invoke a method on the remote peer:

use airsprotocols_mcp::{JsonRpcRequest, RequestId};
use serde_json::json;

let request = JsonRpcRequest::new(
    "calculate",
    Some(json!({"operation": "add", "values": [1, 2, 3]})),
    RequestId::new_number(42)
);

§JsonRpcResponse

Represents a response to a JSON-RPC request (success or error):

use airsprotocols_mcp::{JsonRpcResponse, RequestId};
use serde_json::json;

// Success response
let success = JsonRpcResponse::success(
    json!({"result": "calculation complete", "value": 6}),
    RequestId::new_number(42)
);

// Error response
let error = JsonRpcResponse::error(
    json!({"code": -32602, "message": "Invalid params"}),
    Some(RequestId::new_number(42))
);

§JsonRpcNotification

Represents a notification (one-way message without response):

use airsprotocols_mcp::JsonRpcNotification;
use serde_json::json;

let notification = JsonRpcNotification::new(
    "user_logged_in",
    Some(json!({"user_id": 12345, "timestamp": "2025-07-28T10:30:00Z"}))
);

§JsonRpcMessage Trait

All message types implement the JsonRpcMessage trait for consistent serialization:

use airsprotocols_mcp::{JsonRpcMessageTrait, JsonRpcNotification};

let notification = JsonRpcNotification::new("heartbeat", None);

// Standard JSON serialization
let json = notification.to_json().unwrap();

// Pretty-printed JSON for debugging
let pretty = notification.to_json_pretty().unwrap();

// Deserialize from JSON string
let parsed = JsonRpcNotification::from_json(&json).unwrap();

§Request ID Flexibility

Request IDs support both string and numeric formats per JSON-RPC 2.0 specification:

use airsprotocols_mcp::RequestId;

// String-based IDs (UUIDs, custom formats, etc.)
let string_id = RequestId::new_string("req-12345-abcdef");

// Numeric IDs (counters, timestamps, etc.)
let numeric_id = RequestId::new_number(1234567890);

// Display formatting works for both
println!("String ID: {}", string_id);   // "req-12345-abcdef"
println!("Numeric ID: {}", numeric_id); // "1234567890"

§Error Handling

All serialization operations return Result types with serde_json::Error:

use airsprotocols_mcp::{JsonRpcRequest, JsonRpcMessageTrait, RequestId};

let request = JsonRpcRequest::new("test", None, RequestId::new_number(1));

match request.to_json() {
    Ok(json) => println!("Serialized: {}", json),
    Err(e) => eprintln!("Serialization failed: {}", e),
}

§JSON-RPC 2.0 Specification Compliance

This implementation strictly adheres to the JSON-RPC 2.0 specification:

All messages include "jsonrpc": "2.0" field
Requests have method, optional params, and id fields
Responses have either result or error (mutual exclusion), and id fields
Notifications have method and optional params (no id field)
Request IDs support string, number, and null values
Parameters must be structured (Object) or ordered (Array) values

§Future Features

Planned extensions include:

MCP protocol layer implementation
Transport abstractions (STDIO)
Request correlation and bidirectional communication
High-level client and server interfaces
Performance optimizations and zero-copy processing

§Performance Characteristics

The current implementation prioritizes correctness and maintainability:

Message serialization: Sub-millisecond for typical message sizes
Memory usage: Minimal allocations with efficient serde integration
Trait-based abstractions: Zero runtime cost through compile-time optimization

For high-throughput scenarios, future versions will include zero-copy optimizations and buffer pooling strategies.

Re-exports§

pub use protocol::Base64Data;
pub use protocol::ClientInfo;
pub use protocol::JsonRpcError;
pub use protocol::JsonRpcMessage;
pub use protocol::JsonRpcMessageTrait;
pub use protocol::JsonRpcNotification;
pub use protocol::JsonRpcRequest;
pub use protocol::JsonRpcResponse;
pub use protocol::MessageContext;
pub use protocol::MessageHandler;
pub use protocol::MimeType;
pub use protocol::ProtocolError;
pub use protocol::ProtocolResult;
pub use protocol::ProtocolVersion;
pub use protocol::RequestId;
pub use protocol::ServerConfig;
pub use protocol::ServerInfo;
pub use protocol::Transport as ProtocolTransport;
pub use protocol::TransportError as ProtocolTransportError;
pub use protocol::Uri;
pub use integration::IntegrationError;
pub use integration::IntegrationResult;
pub use integration::McpClient;
pub use integration::McpClientBuilder;
pub use integration::McpClientConfig;
pub use integration::McpError;
pub use integration::McpResult;
pub use integration::McpServer;
pub use integration::McpSessionState;
pub use transport::adapters::StdioTransport;
pub use transport::TransportError;

Modules§

authentication: Multi-Method Authentication for MCP Protocol
authorization: Zero-Cost Generic Authorization Framework
integration: Integration Layer - High-level MCP (Model Context Protocol) implementations
oauth2: OAuth 2.1 Authentication for MCP Protocol
protocol: Protocol Layer - Unified JSON-RPC 2.0 and MCP Implementation
providers: Production-ready MCP Provider Implementations
transport: Transport Abstraction Layer

Macros§

require_auth: Helper macros for working with authentication context
require_scope

Constants§

VERSION

Functions§

version: Get the crate version as a string