使用说明

项目简介

Kuri 是一个使用 Rust 语言开发的框架，旨在帮助开发者轻松构建 Model Context Protocol (MCP) 服务器。它提供了定义和管理工具 (Tools) 和 Prompt 模板 (Prompts) 的能力，并支持通过 Stdio 进行 JSON-RPC 通信。Kuri 框架的设计目标是开发者友好和代码清晰，使得用 Rust 构建 MCP 服务器变得简单高效。

主要功能点

工具 (Tools) 管理: 允许注册和执行由 LLM 客户端调用的外部功能，例如计算器、数据查询等。工具以 Rust 函数的形式定义，并通过装饰器 '#[tool]' 声明，方便快捷。
Prompt 模板 (Prompts) 管理: 支持定义和渲染 Prompt 模板，允许 LLM 客户端获取预定义的 Prompt 文本，以定制 LLM 的交互行为。Prompt 模板也以 Rust 异步函数的形式定义，通过 '#[prompt]' 装饰器声明。
基于 JSON-RPC 协议: 使用标准的 JSON-RPC 协议与 MCP 客户端进行通信，确保了良好的互操作性。
Stdio 传输: 支持标准的 Stdio (标准输入/输出) 作为传输协议，易于部署和测试。
能力声明: 服务器能够声明自身提供的工具和 Prompt 能力，方便客户端了解服务器的功能。
会话管理: 服务器端负责管理会话，虽然文档中没有明确强调会话管理的细节，但作为 MCP 服务器实现的基础功能，框架应已包含或易于扩展实现会话管理。
易于扩展: 基于 Tower 生态系统构建，可以方便地利用 Tower 中间件进行功能扩展，例如添加超时处理、追踪、panic 处理等。

安装步骤

安装 Rust 环境: 如果尚未安装 Rust，请访问 https://www.rust-lang.org/tools/install 按照官方指南安装 Rust 工具链。
创建 Cargo 项目: 打开终端，使用 Cargo 创建一个新的 Rust 项目（如果已有项目则跳过此步骤）：
```
cargo new my_mcp_server
cd my_mcp_server
```

添加依赖: 编辑 'Cargo.toml' 文件，在 '[dependencies]' 部分添加 'kuri' 及其它必要的依赖：

[dependencies]
kuri = "0.1"
async-trait = "0.1"
schemars = "0.8"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio = { version = "1", features = ["full"] }
tracing-subscriber = "0.3" # 可选，用于日志
anyhow = "1.0" # 可选，用于错误处理

编写服务器代码: 根据 'kuri' 提供的示例，在 'src/main.rs' 文件中编写 MCP 服务器代码。例如，可以参考 'examples' 目录下的示例代码，如 '01_simple_calculator_tool_server.rs' 或 '03_prompt_server.rs'，根据需要添加或修改工具和 Prompt 的定义。

一个简单的 'src/main.rs' 示例 (基于 '01_simple_calculator_tool_server.rs')：

use anyhow::Result;
use kuri::{MCPServiceBuilder, ToolError, serve, tool, transport::StdioTransport};

#[tool(
    description = "执行基本的算术运算",
    params(
        x = "计算中的第一个数字",
        y = "计算中的第二个数字",
        operation = "要执行的操作 (add, subtract, multiply, divide)"
    )
)]
async fn calculator(x: i32, y: i32, operation: String) -> Result<i32, ToolError> {
    match operation.as_str() {
        "add" => Ok(x + y),
        "subtract" => Ok(x - y),
        "multiply" => Ok(x * y),
        "divide" => {
            if y == 0 {
                Err(ToolError::ExecutionError("除零错误".to_string()))
            } else {
                Ok(x / y)
            }
        }
        _ => Err(ToolError::InvalidParameters(format!(
            "未知操作: {}",
            operation
        ))),
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    let service = MCPServiceBuilder::new(
        "Calculator Server".to_string(),
        "提供一个计算器工具的 MCP 服务器".to_string(),
    )
    .with_tool(Calculator)
    .build();

    serve(service, StdioTransport::new()).await?;
    Ok(())
}

编译项目: 在终端中，使用 Cargo 编译项目：
```
cargo build --release
```
可执行文件将位于 'target/release/my_mcp_server' (或 'target/debug/my_mcp_server' for debug build)。

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数才能连接。以下是一个 JSON 格式的配置示例，用于连接上面 'src/main.rs' 中定义的计算器服务器。

{
  "serverName": "Calculator Server",  //  MCP 服务器名称，与代码中 MCPServiceBuilder::new() 中定义的名称一致
  "command": "target/release/my_mcp_server", // MCP 服务器可执行文件的路径，根据实际编译结果调整
  "args": [], //  启动参数，对于 Stdio 传输通常为空数组
  "transport": "stdio" //  传输协议，stdio 表示标准输入输出
}

配置参数说明:

'serverName': MCP 服务器的名称，用于客户端识别和显示。
'command': 启动 MCP 服务器进程的命令，通常是编译后的可执行文件路径。
'args': 传递给服务器进程的命令行参数，本例中使用 Stdio 传输，无需额外参数。
'transport': 指定传输协议，这里使用 'stdio' 表示通过标准输入输出进行通信。

基本使用方法

启动 MCP 服务器: 在终端中，导航到项目根目录，并运行编译后的可执行文件（或直接使用 'cargo run --example 01_simple_calculator_tool_server' 运行示例）。服务器将通过 Stdio 监听 MCP 客户端的请求。
配置 MCP 客户端: 在 MCP 客户端应用中，根据上述 “服务器配置” 章节的说明，配置连接到 Kuri MCP 服务器。确保客户端配置的 'command' 指向正确的可执行文件路径。
客户端发起请求: 客户端启动后，应能自动与 Kuri MCP 服务器建立连接，并可以发现服务器提供的工具和 Prompt。客户端可以调用 'tools/list' 和 'prompts/list' 方法获取工具和 Prompt 列表，然后使用 'tools/call' 调用工具，或使用 'prompts/get' 获取 Prompt 内容。
查看日志 (可选): 如果代码中配置了日志功能 (例如使用了 'tracing-subscriber' 示例)，可以在指定的日志文件 (如 'server.log') 中查看服务器运行日志，帮助调试和监控。

注意:

本使用说明基于 Stdio 传输，Kuri 框架未来可能会支持更多传输协议 (如 HTTP)，届时配置和使用方法可能会有所不同。
示例代码和配置仅供参考，实际使用时请根据具体需求进行调整和扩展。

关键词