技术文档摘要

kuri (栗或くり)

kuri 是一个用于构建 模型上下文协议 (MCP) 服务器的框架，专注于开发者体验和清晰度。

MCP 允许大型语言模型执行预定义的功能（称为“工具”），这些工具允许它获取数据并产生副作用（即：与外部世界交互）。大型语言模型只需提供函数的输入参数，然后执行该函数并将响应返回给模型。这些工具由“MCP 服务器”提供，可以本地运行，并且单个服务器可以提供多个工具。

设计理念

Rust 是一种编写可靠的 MCP 服务器的优秀语言，具有强大的类型系统和正确性保证。kuri 的目标是使在 Rust 中编写 MCP 服务器编程变得极其愉快，以促进使用 Rust 构建 MCP 服务器。我们的设计目标包括：

• 舒适的开发者体验：MCP 服务器编程应感觉像正常的 Rust 编程。工具和提示只是普通的异步 Rust 函数。
• 最小的宏使用（#[tool]，#[prompt]）：仅用于附加工具和参数描述，而不是复杂的代码生成。
• 最小的样板代码：专注于您的应用程序逻辑，而不是序列化或 MCP 协议路由。
• 利用 tower 生态系统的中间件、服务和实用程序。免费获得超时、跟踪、异常处理等功能，并重用来自 axum、tonic 和 hyper 的组件。

以上是我们与其他 MCP 服务器库不同的部分。我们专注于做好一件事，并且做得非常好。没有复杂的魔法宏，您的应用程序代码保持自解释性，kuri 的内部结构清晰易读。kuri 还基于 tower，允许您重用丰富的中间件和层生态系统。

示例

use kuri::{MCPServiceBuilder, ServiceExt, ToolError, prompt, serve, tool, transport::StdioTransport};
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub enum Operation {
    Add,
    Subtract,
    Multiply,
    Divide,
}

// 一个纯函数，接受三个输入并返回一个整数。工具及其参数的描述帮助模型决定使用哪个工具，并正确提供工具的参数。
#[tool(
    description = "执行基本算术运算",
    params(
        x = "计算中的第一个数字",
        y = "计算中的第二个数字",
        operation = "要执行的操作（加法、减法、乘法、除法）"
    )
)]
async fn calculator(x: i32, y: i32, operation: Operation) -> Result<i32, ToolError> {
    match operation {
        Operation::Add => Ok(x + y),
        Operation::Subtract => Ok(x - y),
        Operation::Multiply => Ok(x * y),
        Operation::Divide => {
            if y ==  0 {
                Err(ToolError::ExecutionError("除以零".to_string()))
            } else {
                Ok(x / y)
            }
        }
    }
}

// 创建一个用于文本总结的提示模板。应用程序提供要总结的文本，以及可选的格式参数（使用 Rust 的 `Option` 类型表示）。`kuri` 告诉模型 `format` 可能被省略。
#[prompt(
    description = "生成用于总结文本的提示",
    params(
        text = "要总结的文本",
        format = "总结的可选格式（例如：'项目符号'或'Shakespeare'）"
    )
)]
async fn summarise_text(text: String, format: Option<String>) -> String {
    let format_instruction = match format {
        Some(f) => format!("以 {} 格式", f),
        None => String::new(),
    };

    format!(
        "请总结以下文本{}：\n\n{}",
        format_instruction, text
    )
}

#[tokio::main]
async fn main() -> Result<(), TransportError> {
    // 使用服务器名称创建 MCP 服务
    let service = MCPServiceBuilder::new("kuri 的测试服务器".to_string())
        // 注册工具和提示
        .with_tool(Calculator)
        .with_prompt(SummariseText)
        .build();

    // 通过标准输入输出传输进行服务
    serve(service.into_request_service(), StdioTransport::new()).await
}

更多示例参见 示例

开始使用，请在您的 Cargo.toml 中添加 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"] }

MCP 规范支持

• 核心生命周期：连接初始化、能力协商和会话控制
• 工具：功能齐全并经过测试
• 提示：大部分完成并经过测试
• 资源
• 传输
  • 标准输入输出
  • 流式 HTTP (2025-03-26 协议)
• 额外（可选）功能
  • 补全
  • 分页

我们当前的重点是增加 HTTP 传输支持，稳定 API，并确保核心规范的全面支持。

贡献

本项目的目的是构建一个舒适、符合人体工程学、符合 Rust 习惯的 MCP 服务器库。目前处于早期阶段，因此结构仍可能发生变化。如果您喜欢 Rust、MCP、构建 crate 或网络协议（也许您对 protohackers 感兴趣！），我们非常欢迎您加入！参与仓库，或者如果您想讨论，请通过电子邮件 联系！

如果您已经使用了这个框架来构建您的项目：感谢您尝试！我非常希望听到您的使用体验！