noyalib-mcp

noyalib-mcp

用于无损检查、编辑和验证 YAML 的 Model Context Protocol 服务。

---

目录

开始使用

• 安装 — Cargo、npm 包装器和容器
• 要求 — 工具链最低版本、平台
• 快速开始 — 通过 stdio 或 HTTP 启动服务

noyalib-mcp 生态系统

• noyalib-mcp 生态系统 — 协议与库之间的关系

库参考

• 功能一览 — 按主题划分的当前功能范围
• 生态系统比较 — 简要矩阵；完整表格见 docs/COMPARISON.md
• 基准测试 — 测试框架覆盖范围；完整方法见 docs/BENCHMARKS.md
• 功能 — MCP 工具和资源
• 配置 — 传输方式和端点
• 示例 — 可运行的客户端

运维

• 何时不应使用 noyalib-mcp — 局限性
• 开发 — make 目标、模糊测试、CI
• 安全 — 保障和合规性
• 文档 — 所有参考文档
• 稳定性保障 — 协议、SemVer 和工具链规范
• 许可证

---

安装

作为 Rust 库

[dependencies]
noyalib-mcp = "0.0.58"

通过适合宿主环境的方式安装或运行服务：

cargo install noyalib-mcp --locked
docker run --rm -i ghcr.io/sebastienrousseau/noyalib-mcp:latest

npm 包装器（npx @sebastienrousseau/noyalib-mcp）仅当其软件包包含适用于你平台的 SHA-256 时才会运行二进制文件。目前，各平台的发布包尚未提供，因此它会拒绝运行，并提示使用上面的两条命令。

要求

• 从源代码构建时需要 Rust 1.89.0 或更高版本。
• CI 会在 Linux、macOS 和 Windows 上进行测试。
• 根据锁步契约，该 crate 将 noyalib 固定为精确版本 =0.0.58。
• 需要 MCP 客户端来驱动此服务。

范围	最低工具链	强制执行方式
服务和库	Rust 1.89.0	清单和 MSRV CI
完整测试范围	Rust 1.89.0	全目标 CI

快速入门

使用 stdio 集成子进程：

noyalib-mcp

stdio 客户端在发送 initialized 通知或列出工具之前，会先发送 MCP 初始化请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "example",
      "version": "0.0.1"
    }
  }
}

在 /mcp 提供可流式 HTTP 服务，或在 /sse 和 /messages/ 提供旧版 HTTP+SSE 桥接：

noyalib-mcp --transport streamable-http --host 127.0.0.1 --port 8000
noyalib-mcp --transport sse --host 127.0.0.1 --port 8001

服务端会在 initialize 期间协商支持的 MCP 版本；客户端应先完成该握手，再发送原始工具调用。

noyalib-mcp 生态系统

组件	作用
noyalib-mcp	MCP 服务、传输、工具、提示词和资源
noyalib	YAML 解析器、CST 编辑器和架构验证器
noya-cli	面向用户的格式化和验证命令
rmcp	用于协议处理的官方 Rust MCP SDK

功能一览

类别	功能	状态
传输	stdio、可流式 HTTP 和 HTTP+SSE	支持
协议	从 2024-11-05 到 2026-07-28 的版本	已协商
结果	文本及类型化 structuredContent	支持
YAML	解析、获取、设置、多文档设置、编辑和验证	支持
元数据	工具架构、注释、示例、提示词和资源	已发布

生态系统对比

交付方式	无损 YAML 编辑	远程传输	类型化工具结果
noyalib-mcp	是	HTTP 和 SSE	是
noya-cli	是	否	不适用
noyalib	是	否	Rust 原生类型

有关范围和依据，请参阅 docs/COMPARISON.md。

基准测试

仓库中提供的 mcp_tools Criterion 测试框架用于测量工具分发和 YAML 操作，不会将受噪声影响的计时值作为正确性门槛。

cargo bench --bench mcp_tools

有关方法，请参阅 docs/BENCHMARKS.md。

功能

• 提供六种用于 YAML 读取、编辑、解析和验证的类型化工具。
• 声明 outputSchema、structuredContent、注释和示例。
• 支持 stdio、可流式 HTTP 和旧版 HTTP+SSE 传输。
• 提供用于 Agent 集成的提示词和资源。
• 支持协议版本协商和会话感知路由。

配置

选项	效果
--transport stdio	使用进程标准输入和标准输出；这是默认设置
--transport streamable-http	在 /mcp 提供 MCP 服务
--transport sse	提供 /sse 和 /messages/
--host ADDRESS	将 HTTP 传输绑定到指定地址
--port PORT	选择 HTTP 监听端口
--root DIR	将文件工具的访问限制在 DIR 内（默认：工作目录，该目录可能不是 / 或主目录）
--profile strict|standard	规定每种工具解析时使用的规则，包括文件工具和 noyalib_edit：noyalib 的严格 YAML 1.2 配置（默认设置：重复键和异常缩进会报错，限制更严格），或库的默认规则
--max-sessions N	HTTP 传输同时持有的会话数（默认 64）

请谨慎绑定远程传输。默认的环回主机可避免服务暴露给本机以外的设备。文件工具（noyalib_get、noyalib_set、noyalib_set_multidoc）会拒绝任何解析后位于根目录之外的路径，包括符号链接；请使用 --root 启动服务，并将其指向客户端可访问的目录。HTTP 传输会拒绝外部的 Host 或 Origin，且不进行身份验证。完整的信任模型请参阅 SECURITY.md。

示例

• mcp_session.rs：由 SDK 支持的内存会话。
• handshake.sh：初始化并列出工具。
• set-then-get.sh：无损修改并读取结果。

客户端配置示例请参阅 docs/agent-integration.md。

何时不应使用 noyalib-mcp

• 在不需要 MCP 的 Rust 应用程序中直接使用 noyalib。
• 使用 noya-cli 执行 Shell 管道和全仓库验证。
• 请勿在未通过身份验证和授权层保护的情况下，将 HTTP 传输暴露给不可信网络。
• 服务不会获取远程架构；调用方必须提供可信的架构内容。

详细 README 参考保留了客户端设置、工具详情、验证步骤和一致性讨论。

开发

make
make test
make clippy
make fmt
cargo fuzz run fuzz_tool_call

CI 会检查 Rust 格式、Lint、测试、文档、依赖策略、模糊测试回归、协议行为和共享 YAML 测试套件。请参阅 DEVELOPMENT.md。

安全

请通过 SECURITY.md 报告漏洞。此 crate 禁止使用 unsafe 代码、审计依赖项、使用有界的 noyalib 操作，并生成发布证明和 SBOM。请将文件内容、YAML、架构和 MCP 元数据视为不可信输入。

文档

• 用户手册
• API 参考
• 开发者文档
• Agent 集成
• 工具参考
• 架构
• 工程策略
• 合规等级
• 详细 README 参考

稳定性保证

• 在 0.0.x 阶段，补丁版本号是破坏性变更的版本轴。
• 工具名称、参数架构、输出架构和传输路由构成公开兼容性接口。
• 协议修订通过协商确定，而非推断得出。
• MSRV 只能在破坏性变更版本轴上提高，并须在变更日志中说明原因。

许可证

可根据您的选择，采用 Apache License, Version 2.0 或 MIT License 双重授权。