Rust MCP Core

防锈mcp芯

    

基于官方Rust SDK构建的配置驱动MCP服务器核心(rmcp).在YAML或JSON配置中定义工具、身份验证、提示、资源和HTTP行为——该库使用最少的Rust代码处理执行、验证和协议合规性。

全面实施 模型上下文协议规范（2025-11-25）.

经过测试的AI CLI兼容性

此库已通过以下方式进行了测试和验证：

• 克劳德代码
• Codex 命令行界面
• 双子星命令行工具

这是干什么用的

• 减少样板。 通过编写配置而不是协议管道来建立一个符合规范的MCP服务器。一个使用HTTP工具的工作服务器只需要一个YAML文件和几行Rust。
• 内置HTTP API工具。 完全在配置中定义出站HTTP工具调用，包括URL模板、标头注入、查询参数和结构化响应映射。
• 开箱即用的身份验证。 支持入站承载令牌、JWT/JWKS验证和OAuth令牌自检，并具有作用域强制和 WWW-Authenticate 挑战。还支持HTTP工具的出站上游身份验证(none, bearer, basic, oauth2)包括OAuth2客户端凭据/刷新令牌授予，在令牌端点处具有可选的mTLS。
• 可扩展插件系统。 当配置驱动的行为不够时，注册自定义工具逻辑、身份验证、提示/资源提供程序、完成提供程序和HTTP路由器扩展的插件。
• 两种运输方式。 适用于stdio和流式HTTP传输。
• 使用官方SDK。 这个图书馆建立在 rmcp 并使用其传输运行时间， ServerHandler 直接定义特征和MCP类型——无需重新实现。

这不是什么

• 不是工具箱。 此库不包括文件服务器、数据库连接器或shell执行器等内置工具。唯一内置的执行类型是出站HTTP调用。任何其他工具行为都必须通过工具插件提供。

这如何补充rmcp SDK

这 rmcp SDK 提供低级MCP协议原语：传输、消息帧、 ServerHandler 特征和类型定义。rust-mcp核心在此基础上构建，提供配置驱动的服务器框架。

SDK提供了什么（直接使用，不重新实现）：

• 传输运行时（stdio+流式HTTP）
• ServerHandler 特征与JSON-RPC调度
• 所有MCP型号(Tool, Prompt, Resource, Task等等）
• 默认处理程序实现（例如。， ping)

rust-mcp核心添加了什么：

• 配置加载 ${env:ENV} 扩展和JSON模式验证
• 工具执行引擎（带模板的HTTP工具+插件工具）
• 输出模式验证和结构化内容呈现
• 插件注册表（工具、身份验证、提示、资源、完成、HTTP路由器）
• 配置驱动的提示、资源和完成提供者
• 认证中间件（承载、JWT/JWKS、自省、作用域执行）
• 具有对等隔离、TTL、协作取消和状态通知的任务存储

与auth的互补关系最为明显。SDK提供 客户端 OAuth（PKCE流、令牌获取、凭证存储、自动刷新）。铁锈mcp核心提供 服务器端 auth（令牌验证、作用域强制执行）， WWW-Authenticate 挑战和受保护的资源元数据端点）。rmcp客户端获取令牌并发送；rust-mcp核心服务器接收并验证它。

MCP规范合规性

此库实现了以下功能 MCP 2025-11-25规范:

服务器能力

服务器启动的客户端功能

这些需要一个注册的插件才能调用。该框架处理配置验证和客户端能力协商；插件代码通过以下方式调用助手 params.ctx (params: PluginCallParams).

协议基础

• 能力谈判期间 initialize 握手
• 乒乓球用于连接健康
• 功能门强制：禁用功能返回 method-not-found 并且从能力广告中省略

编译时功能

默认情况下，所有功能都已启用。禁用 default-features = false 并选择性地启用。

最小构建（仅限stdio+插件工具）：

cargo build --no-default-features

如果配置引用了禁用的功能，启动将失败，并显示明确的错误消息。

安装

自 克拉特斯.io:

[dependencies]
rust-mcp-core = "0.1"

来自GitHub：

[dependencies]
rust-mcp-core = { git = "https://github.com/nullablevariant/rust-mcp-core" }

快速开始

配置

创建一个YAML配置文件。此示例定义了一个HTTP工具和一个通过流式HTTP传输的内联提示。设置还支持Stdio传输 transport.mode: stdio. 如果你想要一个包含所有支持字段的完整复制/粘贴启动器，请使用 mcp_config.template.yml.

version: 1
server:
  host: 0.0.0.0
  port: 3000
  endpoint_path: /mcp
  logging:
    level: info
  transport:
    mode: streamable_http  # also supports: stdio
  auth:
    enabled: false

client_logging:
  level: info

upstreams:
  api:
    base_url: ${env:API_BASE_URL}

tools:
  items:
    - name: api.list_items
      description: List items from the API
      input_schema:
        type: object
        properties:
          query:
            type: string
      execute:
        type: http
        upstream: api
        method: GET
        path: /items
        query:
          q: "${query}"
      response:
        type: structured
        template:
          items: "${$.items}"
        fallback: text

用法

use std::path::PathBuf;
use rust_mcp_core::{load_mcp_config_from_path, runtime, PluginRegistry};
use rust_mcp_core::McpError;

#[tokio::main]
async fn main() -> Result {
    let config = load_mcp_config_from_path(PathBuf::from("config/mcp_config.yml"))?;
    let plugins = PluginRegistry::new();
    runtime::run_from_config(config, plugins).await
}

使用自定义工具插件：

use rust_mcp_core::{load_mcp_config_from_path, runtime, McpError, PluginRegistry};

#[tokio::main]
async fn main() -> Result {
    let config = load_mcp_config_from_path("config/mcp_config.yml".into())?;
    let plugins = PluginRegistry::new()
        .register_tool(MyToolPlugin)?;
    runtime::run_from_config(config, plugins).await
}

配置引用的任何插件（例如通过 tools.items[].execute.plugin 或提供者插件字段）必须在配置中声明 plugins[] 并注册于 PluginRegistry。未声明的额外注册插件将被忽略并发出警告。看 插件指南 对于完整的插件合同。

配置重新加载（消费者管理）

runtime::run_from_config(...) 是一个方便的入口点 不 暴露重载控制。

如果需要重新加载配置：

• 使用 runtime::build_runtime(...),
• 保持返回 runtime 手柄，
• 自己加载更新的配置输入，
• 呼叫 runtime.reload_config(new_config).await.

rust-mcp-core 不会自动监视配置文件或触发重新加载。

use std::path::PathBuf;
use rust_mcp_core::{load_mcp_config_from_path, runtime, McpError, PluginRegistry};

#[tokio::main]
async fn main() -> Result {
    let initial = load_mcp_config_from_path(PathBuf::from("config/mcp_config.yml"))?;
    let runtime = runtime::build_runtime(initial, PluginRegistry::new()).await?;

    // Consumer-owned trigger (file watcher, signal, admin endpoint, etc.)
    let updated = load_mcp_config_from_path(PathBuf::from("config/mcp_config.reload.yml"))?;
    runtime.reload_config(updated).await?;

    runtime.run().await
}

HTTP工具的上游身份验证

upstreams..auth 控制出站身份验证 tools.items[].execute.type=http:

• type: none ->没有注入auth标头。
• type: bearer ->注射 Authorization: Bearer .
• type: basic ->注入HTTP基本身份验证。
• type: oauth2 ->通过以下方式获取/缓存访问令牌 client_credentials 或 refresh_token 授予、注入承载令牌，并可以重试一次 401 强制刷新后。

令牌端点机密支持 inline, env，以及 path 来源。可选令牌端点mTLS通过以下方式配置 auth.mtls (client_cert, client_key，可选 ca_cert).看 认证 和 配置架构 有关完整字段级别的详细信息。

可流式HTTP请求流（手动客户端）

当 server.transport.mode=streamable_http，手动客户端（例如 curl)应遵循以下流程：

• 发送 initialize 首先，捕获 MCP-Session-Id 启用会话时从响应标头中提取。
• 发送 notifications/initialized 在具有相同会话头的同一端点上。
• 包含 Accept: application/json, text/event-stream POST请求。
• 如果客户端发送 MCP-Protocol-Version 关于HTTP请求：

- 默认 server.transport.streamable_http.protocol_version_negotiation.mode: strict 保留标题；不支持的值返回HTTP 400. - mode: negotiate 保留已知的RMCP版本，并在RMCP验证之前删除未知版本。

• 重复使用 MCP-Session-Id 在会话模式下需要它的后续请求的标头。
• 预计流式HTTP响应将采用SSE框架。

为什么存在：

• rust-mcp-core 与RMCP的已知协议版本集耦合。
• 一些AI客户端发送一个新的日期戳 MCP-Protocol-Version 与捆绑的RMCP支持的标头相比。
• 在 strict 此模式很快就会失败 400 （显式不匹配）。
• 在 negotiate 模式未知的标头值被删除，因此请求可以继续，而无需强制反向代理/标头重写层。
• 这是一个仅适用于HTTP标头的兼容层；MCP能力/版本协商仍正常进行 initialize 流动。

对于特定于客户端的互操作性约束（例如模式子集 限制， structuredContent 形状期望、协议报头规范化， 和 Accept 要求），请参见 AI客户端兼容性.

可流化HTTP强化(http_hardening)

随着 http_hardening 启用后，核心可以强制执行：

• 入站请求正文上限(max_request_bytes，HTTP 413 超过），
• 一般入境费率限制(rate_limit，HTTP 429 超过），
• 会话滥用控制(max_sessions, idle_ttl_secs, max_lifetime_secs, creation_rate),
• panic-to-500和灵敏的收割台运输防护装置。

看 运输 和 配置架构 用于字段级行为和验证规则。

插件日志记录助手

工具插件可以发出服务器日志和/或MCP客户端通知：

let ctx = params.ctx;
ctx.log_event(rust_mcp_core::LogEventParams {
    level: rust_mcp_core::mcp::LoggingLevel::Info,
    message: "synced records".to_owned(),
    data: Some(serde_json::json!({"count": 42})),
    channels: &[rust_mcp_core::LogChannel::Server, rust_mcp_core::LogChannel::Client],
}).await?;

• LogChannel::Server 写入服务器的跟踪输出（由控制 server.logging.level).
• LogChannel::Client 发送MCP notifications/message 给客户（由 client_logging.level 和 logging/setLevel).
• logging/setLevel 做 不 更改服务器跟踪冗长程度。它仅更新客户端通知过滤。
• 在配置重新加载时， server.logging.level 当rust-mcp核心拥有全局跟踪订阅者时，将应用更新。如果主机应用程序已经设置了全局订阅者，rust-mcp核心会记录一个警告，并且无法覆盖它。

插件出站OAuth2帮助程序(http_tools)

当 http_tools 启用，上游使用 auth.type: oauth2，插件可以通过以下方式重用本机令牌获取 PluginContext:

let token = params.ctx.upstream_access_token("partner_api", false).await?;
let (name, value) = params
    .ctx
    .upstream_bearer_header("partner_api", false)
    .await?;

upstream_bearer_header 回报 ("Authorization", "Bearer "). force_refresh=true 强制通过HTTP工具使用的同一出站OAuth2令牌管理器进行一次刷新尝试。

对于向配置的上游发出的出站请求，插件可以使用内置的辅助路径：

let response = params.ctx.send(
    "partner_api",
    rust_mcp_core::OutboundHttpRequest {
        method: "GET".to_owned(),
        url: "/partners".to_owned(),
        ..rust_mcp_core::OutboundHttpRequest::default()
    },
).await?;

此路径应用与内置HTTP工具相同的出站默认解析行为。 使用 send_with(...) 用于每次调用的身份验证覆盖和 send_raw(...) 当您有意绕过上游/默认/重试策略时。 send_with(...) 支持 PluginSendAuthMode::{Inherit, None, Explicit}.

看 examples/plugins-tool-oauth-helper/README.md 以实现完整的可运行流。

文档

例子

下面是可运行的示例 examples/ 根据示例配置 examples//config/mcp_config.yml.

• 浏览所有示例： 示例/README.md
• 最小核心： examples/core minimur/README.md
• 身份验证流程： 认证持有者, auth-oauth-jwt, auth-oauth自省, 全身份验证模式
• HTTP工具： 工具网络搜索, 工具crud http, 工具http post, 工具模板, 工具输出模式, 上游身份验证工具, 工具内容丰富
• 插件接线： 插件工具自定义, 插件工具文件系统, 插件身份验证自定义, 插件路由器http, 插件简单出站http
• 提示/资源/任务/客户端功能： 提示内联插件, 资源内联插件, 资源订阅已更新, 公用事业任务, 公用事业任务高级, 插件工具客户端功能, 插件工具客户端功能高级
• 效用行为： 公用设施测井, 公用事业进展, 公用事业取消, 公用设施竣工, 实用程序分页, 实用程序列表已更改

配置架构

请参阅中的完整架构和验证规则 CONFIG_SCHEMA.md.