diff --git a/README.md b/README.md index e682c725..99c12a95 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ # 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) @@ -12,6 +13,7 @@ An official rust Model Context Protocol SDK implementation with tokio async runt ## Usage ### Import + ```toml rmcp = { version = "0.1", features = ["server"] } ## or dev channel @@ -19,7 +21,9 @@ rmcp = { git = "https://github.com/modelcontextprotocol/rust-sdk", branch = "mai ``` ### Quick start + Start a client in one line: + ```rust use rmcp::{ServiceExt, transport::TokioChildProcess}; use tokio::process::Command; @@ -47,14 +51,16 @@ 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 @@ -62,16 +68,18 @@ 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 @@ -79,6 +87,7 @@ server.notify_cancelled(...).await?; ``` #### 5. Waiting for service shutdown + ```rust, ignore let quit_reason = server.waiting().await?; // or cancel it @@ -86,9 +95,11 @@ 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}; @@ -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` 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) diff --git a/examples/README.md b/examples/README.md index 8a812f83..2f234611 100644 --- a/examples/README.md +++ b/examples/README.md @@ -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 @@ -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 ``` diff --git a/examples/wasi/README.md b/examples/wasi/README.md index 5dd9e97e..ca5e661d 100644 --- a/examples/wasi/README.md +++ b/examples/wasi/README.md @@ -1,4 +1,4 @@ ```sh cargo build -p wasi --target wasm32-wasip2 - npx @modelcontextprotocol/inspector wasmtime target/wasm32-wasip2/debug/wasi.wasm -``` \ No newline at end of file +npx @modelcontextprotocol/inspector wasmtime target/wasm32-wasip2/debug/wasi.wasm +```