sednalabs/mcp-toolkit-rs
GitHub: sednalabs/mcp-toolkit-rs
mcp-toolkit-rs：模型上下文协议（MCP）Rust构建块工具包
Stars: 0 | Forks: 0
# mcp-rs 工具包
用于模型上下文协议（MCP）服务器和客户端的可重用Rust构建块。
`mcp-rs-toolkit` 是一个早期公开的工作空间，用于保持 Rust MCP 服务一致的共享基础：认证发现、HTTP/会话支持、策略原语、工具清单助手、可观察性、进程实用工具和测试框架。它目前处于预1.0版本，crates 还未发布到 crates.io，因此采用者现在应从 Git 中获取。
## 包含内容
| Crate | 目的 |
| --- | --- |
| `mcp-toolkit` | 包含可选功能组的伞形 crate。 |
| `mcp-toolkit-core` | 面向协议的助手、通知和工具清单类型。 |
| `mcp-toolkit-auth` | 带令牌认证、令牌验证、重放保护和认证表面助手。 |
| `mcp-toolkit-http` | OAuth/PRM元数据助手以及可选的流式 HTTP 会话支持。 |
| `mcp-toolkit-observability` | 删除、清理、跟踪桥接、度量外观和可选 OTel 助手。 |
| `mcp-toolkit-policy-core` | 纯策略决策、声明助手、路由/范围检查和 SQL 只读分类。 |
| `mcp-toolkit-policy-runtime` | 运行时策略权限适配器和能力守护助手。 |
| `mcp-toolkit-policy-conformance` | 策略向量和模式的可重用一致性框架。 |
| `mcp-toolkit-policy-ffi` | 可选的动态策略运行时加载器。 |
| `mcp-toolkit-policy-kernel-adapters` | 精确外部策略内核兼容性适配器。 |
| `mcp-toolkit-postgres` | PostgreSQL 连接和 TLS 助手。 |
| `mcp-toolkit-process` | 进程和信号助手。 |
| `mcp-toolkit-server` | 可选的 stdio 和托管 HTTP 服务器组合助手。 |
| `mcp-toolkit-testing` | 工具模式和认证表面合同测试助手。 |
| `mcp-toolkit-docs` | 文档和工具元数据助手。 |
| `mcp-toolkit-gemini` | 可选的基于进程的 Gemini CLI 集成助手。 |
`mcp-toolkit-gemini` 故意只使用 API 密钥。它需要 `GEMINI_API_KEY`，在启动 Gemini CLI 之前清除继承的进程环境状态，并且不支持基于浏览器、账户或主目录的 Gemini CLI 认证。
## 快速入门
对于完整的服务器创建、验证、审查和发布流程，从 `docs/golden-path.md` 开始。对于将此流程转换为可重复实施通道的可复制清单，请使用 `docs/new-server-delivery-lane.md`。
从 Git 中添加您需要的特定 crates：
```
[dependencies]
mcp-toolkit-core = { git = "https://github.com/sednalabs/mcp-rs-toolkit" }
mcp-toolkit-http = { git = "https://github.com/sednalabs/mcp-rs-toolkit", features = ["session"] }
mcp-toolkit-testing = { git = "https://github.com/sednalabs/mcp-rs-toolkit" }
```
或者当您需要一个具有显式功能选择的依赖项时，使用伞形 crate：
```
[dependencies]
mcp-toolkit = {
git = "https://github.com/sednalabs/mcp-rs-toolkit",
features = ["auth", "http", "policy", "process", "server"]
}
```
从存储库根目录运行基线检查：
```
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
```
## 最小采用路径
对于新的 Rust MCP 服务器，从提供稳定公共表面的最小部分开始：
1. 使用 `mcp-toolkit-core::tool_inventory` 注册您的服务器可以公开的工具。
2. 使用 `mcp-toolkit-testing::assert_tool_schema_snapshot` 锁定导出的 `tools/list` 合同。
3. 当通过 OAuth 发现和受保护资源元数据在 HTTP 上提供 MCP 时，使用 `mcp-toolkit-http::oauth` 和 `mcp-toolkit-auth::surface`。
4. 当您希望工具集组装 stdio 启动、本地可流式 HTTP 运行时组件、托管保护、认证表面层和默认 MCP 路由包时，使用 `mcp-toolkit-server`。
5. 使用 `mcp-toolkit-observability` 助手进行清理日志、有界标签和可选跟踪/度量集成。
6. 仅当服务具有需要可重用强制执行的授权、SQL 只读或能力守护边界时，才添加策略 crates。
7. 对于可复制起点，请参阅 `templates/curated-stdio-intent-server` 以获取 stdio 意图工具，以及 `templates/hosted-http-auth-server` 以获取具有 OAuth 受保护资源元数据、带令牌挑战、主机保护、模式快照和合同测试的托管 HTTP。
8. 对于现有服务的采用，一次迁移一个运行时接口，并通过 GitHub 托管验证证明前后合同。`docs/golden-path.md` 中的清单定义了预期的移交、审查门和发布证据。
## 示例：锁定工具模式
```
use mcp_toolkit_testing::assert_tool_schema_snapshot;
use serde_json::json;
#[test]
fn tool_schema_snapshot_matches_exported_tools() {
let tools = vec![
json!({
"name": "example.search",
"description": "Search the configured source index",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string" }
},
"required": ["query"]
}
}),
];
assert_tool_schema_snapshot("spec/tool_schema_snapshot.v1.json", &tools);
}
```
默认情况下以严格模式运行此测试。要故意重新基准测试快照，请设置 `MCP_TOOLKIT_UPDATE_TOOL_SNAPSHOTS=1` 以进行测试运行，并在合并之前审查 JSON 差异。
## 安全性和发布状态
此存储库面向公众，并使用保守的 GitHub Actions 状态：
- 工作流程令牌默认为只读；
- 外部分叉拉取请求在运行工作流程之前需要维护者批准；
- 工作流程避免 `pull_request_target`；
- 第三方 Actions 锁定到不可变提交；
- CodeQL 分析 GitHub Actions 工作流程策略。
依赖项策略在 `docs/dependency-governance.md` 中记录。
## 文档
- `docs/auth-surface.md` 解释了 OAuth、受保护资源元数据和带令牌强制执行的合同。
- `docs/contract-testing.md` 涵盖了用于 stdio、认证元数据、带令牌挑战、主机守护和快照的可重用硬路径测试助手。
- `docs/deferred-loading-and-tool-search.md` 涵盖了轻量级工具发现和延迟加载。
- `docs/dependency-governance.md` 定义了依赖项选择和更新门。
- `docs/ecosystem-map.md` 解释了工具集、参考架构和服务特定代码应居住的位置。
- `docs/golden-path.md` 是创建、验证、审查、发布和采用工具集构建的 MCP 服务器的端到端路径。
- `docs/new-server-delivery-lane.md` 定义了从工具集模板通过经过验证的提升快速、可审查的 MCP 服务器创建的七门通道。
- `docs/observability-evolution.md` 和 `docs/observability-rollout.md` 涵盖了可观察性适配器和采用。
- `docs/security-profiles.md` 描述了认证配置文件选择。
- `docs/server-composition-layer.md` 描述了可选的 stdio 和 HTTP 服务器组合层。
- `docs/starter-templates.md` 解释了维护的服务器启动模板及其验证合同。
- `docs/sql-policy-kernel-conformance.md` 记录了 SQL 策略向量一致性。
- `docs/tool-inventory-migration.md` 和 `docs/tool-schema-snapshots.md` 涵盖了导出的工具表面管理。
- `docs/toolkit-boundary.md` 定义了属于此公共工具集的内容。
## 状态
此工作空间现在很有用，但它仍然是预 1.0 版本。随着公共表面的稳定，预计 API 将变得更加严格。crates 标记为 `publish = false`，直到 crate 级别的发布流程准备就绪。
## 许可证
根据 Apache License，版本 2.0 许可。请参阅 `LICENSE`。
标签：CLI, DNS解析, Gemini, MCP, Model Context Protocol, pocsuite3, Rust, Rust 库, WiFi技术, 会话, 内核驱动, 协议, 可观察性, 可视化界面, 安全协议, 客户端, 工具, 开源项目, 技术教程, 数据传输, 数据管道, 文档, 服务器, 测试框架, 策略, 系统架构, 网络协议, 网络流量审计, 软件可定制性, 软件可扩展性, 软件可测试性, 软件可理解性, 软件可移植性, 软件可维护性, 软件可访问性, 软件可追踪性, 软件可配置性, 软件可重用性, 软件可集成性, 软件工具, 软件工程, 软件库, 软件开发, 软件性能, 软件构建块, 软件架构, 软件框架, 软件测试, 软件组件, 软件维护, 软件设计, 软件部署, 过程工具, 通知系统