rucora_mcp/lib.rs
1//! rucora-mcp - MCP（Model Context Protocol）集成
2//!
3//! # 概述
4//!
5//! 本模块提供 MCP（Model Context Protocol）集成支持，用于：
6//! - 连接 MCP 服务器
7//! - 将 MCP 工具转换为 rucora 的 Tool trait
8//! - 统一 MCP 工具调用接口
9//!
10//! # 什么是 MCP
11//!
12//! MCP（Model Context Protocol）是一个开放协议，用于：
13//! - 标准化 AI 模型与外部工具的交互
14//! - 提供工具发现、调用、结果返回的统一格式
15//! - 支持多种传输层（stdio、HTTP、WebSocket 等）
16//!
17//! # 核心组件
18//!
19//! ## 传输层（Transport）
20//!
21//! 支持多种 MCP 传输方式：
22//!
23//! - [`StdioTransport`][]: 标准输入输出（用于本地进程）
24//! - [`StreamableHttpTransport`][]: HTTP 流式传输
25//!
26//! ## 协议层（Protocol）
27//!
28//! MCP 协议定义的消息类型：
29//!
30//! - 工具列表请求/响应
31//! - 工具调用请求/响应
32//! - 错误处理
33//!
34//! ## 工具适配（Tool Adapter）
35//!
36//! [`McpToolAdapter`] 将远程 MCP 工具包装为 [`rucora_core::tool::Tool`]：
37//!
38//! ```rust
39//! use rucora::mcp::McpToolAdapter;
40//! use rucora_core::tool::Tool;
41//!
42//! // MCP 工具可以直接作为 rucora 的 Tool 使用
43//! let adapter: McpToolAdapter = ...;
44//! let result = adapter.call(input).await?;
45//! ```
46//!
47//! # 使用示例
48//!
49//! ## 连接 MCP 服务器
50//!
51//! ```rust,no_run
52//! use rucora::mcp::{McpClient, StdioTransport};
53//!
54//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
55//! // 创建传输层
56//! let transport = StdioTransport::new("mcp-server");
57//!
58//! // 创建客户端
59//! let client = McpClient::connect(transport).await?;
60//!
61//! // 列出可用工具
62//! let tools = client.list_tools().await?;
63//!
64//! for tool in tools {
65//! println!("工具：{}", tool.name);
66//! }
67//! # Ok(())
68//! # }
69//! ```
70//!
71//! ## 调用 MCP 工具
72//!
73//! ```rust,no_run
74//! use rucora::mcp::{McpClient, StdioTransport};
75//! use serde_json::json;
76//!
77//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
78//! let transport = StdioTransport::new("mcp-server");
79//! let client = McpClient::connect(transport).await?;
80//!
81//! // 调用工具
82//! let result = client.call_tool(
83//! "my_tool",
84//! json!({"param": "value"})
85//! ).await?;
86//!
87//! println!("结果：{}", result);
88//! # Ok(())
89//! # }
90//! ```
91//!
92//! ## 将 MCP 工具转换为 rucora Tool
93//!
94//! ```rust,no_run
95//! use rucora::mcp::{McpClient, McpToolAdapter, StdioTransport};
96//! use rucora_core::tool::Tool;
97//! use std::sync::Arc;
98//!
99//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
100//! let transport = StdioTransport::new("mcp-server");
101//! let client = McpClient::connect(transport).await?;
102//!
103//! // 获取 MCP 工具定义
104//! let tools = client.list_tools().await?;
105//! let mcp_tool = tools.into_iter().next().unwrap();
106//!
107//! // 创建适配器
108//! let adapter = McpToolAdapter::new(client.clone(), mcp_tool);
109//!
110//! // 现在可以作为 rucora Tool 使用
111//! let result = adapter.call(serde_json::json!({})).await?;
112//! # Ok(())
113//! # }
114//! ```
115//!
116//! # 子模块
117//!
118//! - [`protocol`][]: MCP 协议模型类型
119//! - [`tool`][]: MCP 工具适配器
120//! - [`transport`][]: MCP 传输层
121//!
122//! # 依赖
123//!
124//! 本模块基于 [`rmcp`](https://crates.io/crates/rmcp) 库构建。
125//!
126//! # Feature 标志
127//!
128//! - `client`: 启用 MCP 客户端支持
129//! - `server`: 启用 MCP 服务器支持
130//! - `transport-streamable-http-client`: HTTP 流式传输客户端
131
132/// MCP 协议模型
133pub mod protocol;
134
135/// MCP 工具适配器
136pub mod tool;
137
138/// MCP 传输层
139pub mod transport;
140
141/// `rmcp` 服务扩展 trait（直接转导出）
142pub use rmcp::ServiceExt;
143
144/// MCP 协议模型类型（从 `rmcp::model` 转导出）
145pub use protocol::*;
146
147/// MCP 工具适配（将远端 MCP 工具包装为 `rucora-core` 的 Tool）
148pub use tool::*;
149
150/// MCP 传输层（从 `rmcp::transport` 转导出）
151pub use transport::*;