Skip to content
Merged
Show file tree
Hide file tree
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
27 changes: 22 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
</div>

# RMCP

[![Crates.io Version](https://img.shields.io/crates/v/rmcp)](https://crates.io/crates/rmcp)
![Release status](https://github.com/modelcontextprotocol/rust-sdk/actions/workflows/release.yml/badge.svg)
[![docs.rs](https://img.shields.io/docsrs/rmcp)](https://docs.rs/rmcp/latest/rmcp)
Expand All @@ -12,14 +13,17 @@ An official rust Model Context Protocol SDK implementation with tokio async runt
## Usage

### Import

```toml
rmcp = { version = "0.1", features = ["server"] }
## or dev channel
rmcp = { git = "https://github.com/modelcontextprotocol/rust-sdk", branch = "main" }
```

### Quick start

Start a client in one line:

```rust
use rmcp::{ServiceExt, transport::TokioChildProcess};
use tokio::process::Command;
Expand Down Expand Up @@ -47,48 +51,55 @@ For client, the sink item is [`ClientJsonRpcMessage`](crate::model::ClientJsonRp
For server, the sink item is [`ServerJsonRpcMessage`](crate::model::ServerJsonRpcMessage) and stream item is [`ClientJsonRpcMessage`](crate::model::ClientJsonRpcMessage)

##### These types is automatically implemented [`IntoTransport`](crate::transport::IntoTransport) trait

1. The types that already implement both [`Sink`](futures::Sink) and [`Stream`](futures::Stream) trait.
2. A tuple of sink `Tx` and stream `Rx`: `(Tx, Rx)`.
3. The type that implement both [`tokio::io::AsyncRead`] and [`tokio::io::AsyncWrite`] trait.
4. A tuple of [`tokio::io::AsyncRead`] `R `and [`tokio::io::AsyncWrite`] `W`: `(R, W)`.
4. A tuple of [`tokio::io::AsyncRead`] `R `and [`tokio::io::AsyncWrite`] `W`: `(R, W)`.

For example, you can see how we build a transport through TCP stream or http upgrade so easily. [examples](examples/README.md)

#### 2. Build a service

You can easily build a service by using [`ServerHandler`](crates/rmcp/src/handler/server.rs) or [`ClientHandler`](crates/rmcp/src/handler/client.rs).

```rust, ignore
let service = common::counter::Counter::new();
```

#### 3. Serve them together

```rust, ignore
// this call will finish the initialization process
let server = service.serve(transport).await?;
```

#### 4. Interact with the server

Once the server is initialized, you can send requests or notifications:

```rust, ignore
// request
// request
let roots = server.list_roots().await?;

// or send notification
server.notify_cancelled(...).await?;
```

#### 5. Waiting for service shutdown

```rust, ignore
let quit_reason = server.waiting().await?;
// or cancel it
let quit_reason = server.cancel().await?;
```

### Use marcos to declaring tool

Use `toolbox` and `tool` macros to create tool quickly.

Check this [file](examples/servers/src/common/calculator.rs).

```rust, ignore
use rmcp::{ServerHandler, model::ServerInfo, schemars, tool};

Expand Down Expand Up @@ -141,33 +152,39 @@ impl ServerHandler for Calculator {
}

```

The only thing you should do is to make the function's return type implement `IntoCallToolResult`.

And you can just implement `IntoContents`, and the return value will be marked as success automatically.
And you can just implement `IntoContents`, and the return value will be marked as success automatically.

If you return a type of `Result<T, E>` where `T` and `E` both implemented `IntoContents`, it's also OK.

### Manage Multi Services

For many cases you need to manage several service in a collection, you can call `into_dyn` to convert services into the same type.

```rust, ignore
let service = service.into_dyn();
```


### Examples

See [examples](examples/README.md)

### Features

- `client`: use client side sdk
- `server`: use server side sdk
- `macros`: macros default

#### Transports

- `transport-io`: Server stdio transport
- `transport-sse-server`: Server SSE transport
- `transport-child-process`: Client stdio transport
- `transport-sse`: Client sse transport

## Related Resources
- [MCP Specification](https://spec.modelcontextprotocol.io/specification/2024-11-05/)

- [MCP Specification](https://spec.modelcontextprotocol.io/specification/2024-11-05/)
- [Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.ts)
9 changes: 5 additions & 4 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,8 @@

# Server Examples

- [Server SSE](servers/src/axum.rs), using axum as web server.
- [Server stdio](servers/src/std_io.rs), using tokio async io.

- [Server SSE](servers/src/axum.rs), using axum as web server.
- [Server stdio](servers/src/std_io.rs), using tokio async io.

# Transport Examples

Expand All @@ -18,14 +17,16 @@
- [Unix Socket](transport/src/unix_socket.rs)
- [Websocket](transport/src/websocket.rs)

# Integration

# Intergration
- [Rig](examples/rig-integration) A stream chatbot with rig

# WASI

- [WASI-P2 runtime](examples/wasi) How it works with wasip2

## Use Mcp Inspector

```sh
npx @modelcontextprotocol/inspector
```
4 changes: 2 additions & 2 deletions examples/wasi/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
```sh
cargo build -p wasi --target wasm32-wasip2
npx @modelcontextprotocol/inspector wasmtime target/wasm32-wasip2/debug/wasi.wasm
```
npx @modelcontextprotocol/inspector wasmtime target/wasm32-wasip2/debug/wasi.wasm
```
Loading