Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 31 additions & 30 deletions docs/readme/README.zh-cn.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
![Release status](https://github.202132.xyzmodelcontextprotocol/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实现。

## 使用

Expand All @@ -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;
Expand All @@ -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) 轻松构建服务
Expand All @@ -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};

Expand Down Expand Up @@ -137,28 +133,33 @@ impl ServerHandler for Calculator {
}

```
你要做的唯一事情就是保证函数的返回类型实现了 `IntoCallToolResult`.
你要做的唯一事情就是确保函数的返回类型实现了 `IntoCallToolResult`

你可以为返回类型实现 `IntoContents`, 那么返回内容会被自动标记为成功
你可以为返回类型实现 `IntoContents`,那么返回值将自动标记为成功

如果返回类型是 `Result<T, E>` ,其中 `T` 与 `E` 都实现了 `IntoContents`, 那就会自动标记成功或者失败
如果返回类型是 `Result<T, E>`,其中 `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)
Loading