What is Mcprotocol Rs

mcprotocol-rs is a Rust implementation of the Model Context Protocol (MCP). It provides a complete framework for implementing MCP clients and servers.

Use cases

Use cases for mcprotocol-rs include building high-performance servers for real-time data streaming, managing client connections in a scalable manner, and implementing custom transport layers for specific application needs.

How to use

To use mcprotocol-rs, you need to include it in your Rust project by adding it to your Cargo.toml file. You can then create MCP clients and servers using the provided APIs, following the documentation for guidance on setup and usage.

Key features

Key features of mcprotocol-rs include a complete implementation of the MCP 2024-11-05 specification, support for multiple transport layers (HTTP/SSE and standard I/O), asynchronous API design based on tokio, complete type safety, built-in error handling, and an extensible architecture with modular transport layer design.

Where to use

mcprotocol-rs can be used in various fields where real-time communication and data exchange are required, such as web applications, IoT systems, and any software that needs to implement the Model Context Protocol.

mcprotocol-rs

⚠️ 开发状态: 本项目目前处于积极开发中，API 可能会发生变化。

⚠️ Development Status: This project is under active development and the API may change.

mcprotocol-rs 是 Model Context Protocol (MCP) 的 Rust 实现。它提供了一个完整的框架来实现 MCP 客户端和服务器。

mcprotocol-rs is a Rust implementation of the Model Context Protocol (MCP). It provides a complete framework for implementing MCP clients and servers.

特性 | Features

• 完整实现 MCP 2024-11-05 规范

• 支持多种传输层

  • HTTP/SSE 传输
    • 基于 axum 的高性能服务器实现
    • 支持 SSE 实时消息推送
    • 内置认证支持
    • 自动管理客户端连接生命周期
    • 精确的消息路由机制
  • 标准输入/输出传输
    • 符合 MCP 规范的子进程管理
    • 支持服务器日志捕获
    • 自动处理进程生命周期

• 异步 API 设计

  • 基于 tokio 的异步运行时
  • 完整的 Stream 支持
  • 非阻塞 I/O 操作

• 完整的类型安全

• 内置错误处理

• 可扩展的架构

  • 模块化的传输层设计
  • 支持自定义传输实现
  • 工厂模式创建实例

• Complete implementation of MCP 2024-11-05 specification

• Multiple transport layer support

  • HTTP/SSE transport
    • High-performance server implementation based on axum
    • SSE real-time message push support
    • Built-in authentication support
    • Automatic client connection lifecycle management
    • Precise message routing mechanism
  • Standard input/output transport
    • MCP-compliant subprocess management
    • Server log capture support
    • Automatic process lifecycle handling

• Asynchronous API design

  • Based on tokio runtime
  • Complete Stream support
  • Non-blocking I/O operations

• Complete type safety

• Built-in error handling

• Extensible architecture

  • Modular transport layer design
  • Custom transport implementation support
  • Factory pattern for instance creation

安装 | Installation

将以下内容添加到你的 Cargo.toml：
Add this to your Cargo.toml:

[dependencies]
mcprotocol-rs = "0.1.5"

快速开始 | Quick Start

HTTP/SSE 服务器示例 | HTTP/SSE Server Example

use mcprotocol_rs::{
    transport::{
        ServerTransportFactory,
        TransportConfig,
        TransportType,
    },
    Result,
};
use std::net::SocketAddr;

#[tokio::main]
async fn main() -> Result<()> {
    // 配置 HTTP 服务器
    // Configure HTTP server
    let addr = "127.0.0.1:3000".parse::<SocketAddr>().unwrap();
    let config = TransportConfig {
        transport_type: TransportType::Http {
            base_url: addr.to_string(),
            auth_token: Some("your-auth-token".to_string()),
        },
        parameters: None,
    };

    // 使用工厂创建服务器
    // Create server using factory
    let factory = ServerTransportFactory;
    let mut server = factory.create(config)?;
    
    // 初始化并启动服务器
    // Initialize and start server
    server.initialize().await?;
    println!("Server started on {}", addr);

    // 保持服务器运行
    // Keep server running
    tokio::signal::ctrl_c().await?;
    Ok(())
}

HTTP/SSE 客户端示例 | HTTP/SSE Client Example

use mcprotocol_rs::{
    transport::{ClientTransportFactory, TransportConfig, TransportType},
    protocol::{Message, Method, Request, RequestId},
    Result,
};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    // 配置 HTTP 客户端
    // Configure HTTP client
    let config = TransportConfig {
        transport_type: TransportType::Http {
            base_url: "http://127.0.0.1:3000".to_string(),
            auth_token: Some("your-auth-token".to_string()),
        },
        parameters: None,
    };

    // 创建客户端实例
    // Create client instance
    let factory = ClientTransportFactory;
    let mut client = factory.create(config)?;

    // 初始化客户端
    // Initialize client
    client.initialize().await?;
    println!("Client connected to server");

    // 创建并发送请求
    // Create and send request
    let request = Request::new(
        Method::Ping,
        None,
        RequestId::String("ping-1".to_string()),
    );
    client.send(Message::Request(request)).await?;

    // 接收响应
    // Receive response
    let response = client.receive().await?;
    println!("Received response: {:?}", response);

    // 关闭客户端
    // Close client
    client.close().await?;
    Ok(())
}

Stdio 传输示例 | Stdio Transport Example

查看完整示例代码
See full example code

生命周期示例 | Lifecycle Example

查看完整示例代码
See full example code

HTTP/SSE 传输特性 | HTTP/SSE Transport Features

客户端管理 | Client Management

• 基于 SSE 的客户端连接管理

• 自动清理断开的连接

• 保持连接活跃检测

• 支持客户端重连机制

• SSE-based client connection management

• Automatic cleanup of disconnected clients

• Keep-alive connection detection

• Support for client reconnection

消息路由 | Message Routing

• 基于请求 ID 的消息路由

• 支持请求-响应模式

• 支持通知消息

• 自动清理断开的连接

• Request ID based message routing

• Support for request-response pattern

• Support for notification messages

• Automatic cleanup of disconnected connections

安全性 | Security

• 支持 Bearer Token 认证

• 安全的消息传输

• 连接状态监控

• Bearer Token authentication support

• Secure message transmission

• Connection state monitoring

自定义传输实现 | Custom Transport Implementation

你可以通过实现 Transport trait 来创建自己的传输层：
You can create your own transport layer by implementing the Transport trait:

use mcprotocol_rs::{
    transport::Transport,
    protocol::Message,
    Result,
};
use async_trait::async_trait;

#[derive(Clone)]
struct MyTransport {
    // 你的传输层字段
    // Your transport fields
}

#[async_trait]
impl Transport for MyTransport {
    async fn initialize(&mut self) -> Result<()> {
        // 实现初始化逻辑
        // Implement initialization logic
    }

    async fn send(&self, message: Message) -> Result<()> {
        // 实现发送逻辑
        // Implement send logic
    }

    async fn receive(&self) -> Result<Message> {
        // 实现接收逻辑
        // Implement receive logic
    }

    async fn close(&mut self) -> Result<()> {
        // 实现关闭逻辑
        // Implement close logic
    }
}

项目结构 | Project Structure

src/
├── protocol/         # MCP 协议实现 | MCP protocol implementation
├── transport/        # 传输层实现 | Transport layer implementation
│   ├── http/        # HTTP/SSE 传输 | HTTP/SSE transport
│   │   ├── client.rs # HTTP 客户端 | HTTP client
│   │   └── server.rs # HTTP 服务器 | HTTP server
│   └── stdio/       # 标准输入/输出传输 | Stdio transport
│       ├── client.rs # Stdio 客户端 | Stdio client
│       └── server.rs # Stdio 服务器 | Stdio server
├── client_features/ # 客户端特性实现 | Client features implementation
├── server_features/ # 服务器特性实现 | Server features implementation
├── error.rs        # 错误类型定义 | Error type definitions
└── lib.rs          # 库入口和导出 | Library entry and exports

examples/
├── ping_example.rs      # Ping/Pong 示例 | Ping/Pong example
├── lifecycle_client.rs  # 生命周期客户端示例 | Lifecycle client example
├── lifecycle_server.rs  # 生命周期服务器示例 | Lifecycle server example
├── stdio_client.rs      # 标准输入/输出客户端示例 | Stdio client example
└── stdio_server.rs      # 标准输入/输出服务器示例 | Stdio server example

贡献 | Contributing

欢迎提交 Pull Requests！对于重大更改，请先开 issue 讨论您想要更改的内容。

Pull Requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

许可证 | License

本项目采用 MIT 许可证 - 详见 LICENSE 文件

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