diff --git a/docs/readme/README.zh-cn.md b/docs/readme/README.zh-cn.md index 0f94b8fa..60613856 100644 --- a/docs/readme/README.zh-cn.md +++ b/docs/readme/README.zh-cn.md @@ -3,7 +3,7 @@ ![Release status](https://github.commodelcontextprotocol/rust-sdk/actions/workflows/release.yml/badge.svg) [![docs.rs](https://img.shields.io/docsrs/rmcp)](https://docs.rs/rmcp/latest/rmcp) -一个干净且完整的 MCP SDK +一个基于tokio异步运行时的官方Model Context Protocol SDK实现。 ## 使用 @@ -15,7 +15,7 @@ rmcp = { git = "https://github.com/modelcontextprotocol/rust-sdk", branch = "mai ``` ### 快速上手 -你可以用一行代码,启动一个SSE客户端 +一行代码启动客户端: ```rust use rmcp::{ServiceExt, transport::TokioChildProcess}; use tokio::process::Command; @@ -32,19 +32,19 @@ use tokio::io::{stdin, stdout}; let transport = (stdin(), stdout()); ``` -传输层类型只需要实现 [`IntoTransport`](crate::transport::IntoTransport) trait, 这个特性允许你创建一个Sink和一个Stream +传输层类型必须实现 [`IntoTransport`](crate::transport::IntoTransport) trait, 这个特性允许分割成一个sink和一个stream。 对于客户端, Sink 的 Item 是 [`ClientJsonRpcMessage`](crate::model::ClientJsonRpcMessage), Stream 的 Item 是 [`ServerJsonRpcMessage`](crate::model::ServerJsonRpcMessage) 对于服务端, Sink 的 Item 是 [`ServerJsonRpcMessage`](crate::model::ServerJsonRpcMessage), Stream 的 Item 是 [`ClientJsonRpcMessage`](crate::model::ClientJsonRpcMessage) ##### 这些类型自动实现了 [`IntoTransport`](crate::transport::IntoTransport) trait -1. 兼具 [`Sink`](futures::Sink) 与 [`Stream`](futures::Stream) 的 -2. 一对 Sink `Tx` Stream `Rx`, 类型 `(Tx, Rx)` 自动实现 [`IntoTransport`](crate::transport::IntoTransport) -3. 兼具 [`tokio::io::AsyncRead`] 与 [`tokio::io::AsyncWrite`] 的 -4. 一对 Sink [`tokio::io::AsyncRead`] `R ` [`tokio::io::AsyncWrite`] `W`, 类型 `(R, W)`自动实现 [`IntoTransport`](crate::transport::IntoTransport) +1. 已经同时实现了 [`Sink`](futures::Sink) 和 [`Stream`](futures::Stream) trait的类型。 +2. 由sink `Tx` 和 stream `Rx`组成的元组: `(Tx, Rx)`。 +3. 同时实现了 [`tokio::io::AsyncRead`] 和 [`tokio::io::AsyncWrite`] trait的类型。 +4. 由 [`tokio::io::AsyncRead`] `R `和 [`tokio::io::AsyncWrite`] `W` 组成的元组: `(R, W)`。 -示例,你可以轻松创建一个TCP流来作为传输层. [examples](examples/README.md) +例如,你可以看到我们如何轻松地通过TCP流或http升级构建传输层。 [examples](examples/README.md) #### 2. 构建服务 你可以通过 [`ServerHandler`](crates/rmcp/src/handler/server.rs) 或 [`ClientHandler`](crates/rmcp/src/handler/client.rs) 轻松构建服务 @@ -53,38 +53,34 @@ let transport = (stdin(), stdout()); let service = common::counter::Counter::new(); ``` -如果你想用 `tower`, 你也可以使用 [`TowerHandler`] 来作为tower服务的适配器. - -请参考 [服务用例](examples/servers/src/common/counter.rs). - #### 3. 把他们组装到一起 ```rust, ignore // 这里会自动完成初始化流程 let server = service.serve(transport).await?; ``` -#### 4. 与服务端/客户端交互 -一旦你完成初始化,你可以发送请求或者发送通知 +#### 4. 与服务交互 +一旦服务初始化完成,你可以发送请求或通知: ```rust, ignore -// request +// 请求 let roots = server.list_roots().await?; -// or send notification +// 或发送通知 server.notify_cancelled(...).await?; ``` -#### 5. 等待服务结束 +#### 5. 等待服务关闭 ```rust, ignore let quit_reason = server.waiting().await?; -// or cancel it +// 或取消它 let quit_reason = server.cancel().await?; ``` -### 使用宏来定义工具 -使用 `tool` 宏来快速创建工具 +### 使用宏来声明工具 +使用 `toolbox` 和 `tool` 宏来快速创建工具。 -请看这个[文件](examples/servers/src/common/calculator.rs). +请看这个[文件](examples/servers/src/common/calculator.rs)。 ```rust, ignore use rmcp::{ServerHandler, model::ServerInfo, schemars, tool}; @@ -137,28 +133,33 @@ impl ServerHandler for Calculator { } ``` -你要做的唯一事情就是保证函数的返回类型实现了 `IntoCallToolResult`. +你要做的唯一事情就是确保函数的返回类型实现了 `IntoCallToolResult`。 -你可以为返回类型实现 `IntoContents`, 那么返回内容会被自动标记为成功。 +你可以为返回类型实现 `IntoContents`,那么返回值将自动标记为成功。 -如果返回类型是 `Result` ,其中 `T` 与 `E` 都实现了 `IntoContents`, 那就会自动标记成功或者失败。 +如果返回类型是 `Result`,其中 `T` 与 `E` 都实现了 `IntoContents`,那也是可以的。 ### 管理多个服务 -在很多情况下你需要把不同类型的服务管理在一个集合当中,你可以调用 `into_dyn` 来把他们都转化成动态类型。 +在很多情况下你需要在一个集合中管理多个服务,你可以调用 `into_dyn` 来将服务转换为相同类型。 ```rust, ignore let service = service.into_dyn(); ``` -### 用例 -查看 [用例文件夹](examples/README.md) +### 示例 +查看 [examples](examples/README.md) -### Features +### 功能特性 - `client`: 使用客户端sdk - `server`: 使用服务端sdk - +- `macros`: 宏默认 +#### 传输层 +- `transport-io`: 服务端标准输入输出传输 +- `transport-sse-server`: 服务端SSE传输 +- `transport-child-process`: 客户端标准输入输出传输 +- `transport-sse`: 客户端SSE传输 ## 相关资源 - [MCP Specification](https://spec.modelcontextprotocol.io/specification/2024-11-05/) -- [Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.ts) +- [Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.ts) \ No newline at end of file