Covenant

属于 StudioMeyer MCP Stack — 在马略卡岛打造 🌴 · 如果你在使用，欢迎 ⭐

mcp-covenant

用于 Model Context Protocol 服务的契约与破坏性变更检测 — 为你的 MCP 接口提供语义化版本管理。

发布类型化库时，你拥有公共 API，也有工具会在你破坏它时发出警告。MCP 服务两者都没有：它们只会返回 当前 的 tools/list 结果。重命名工具、添加必需参数、缩小枚举范围——所有基于你服务构建的 Agent 都会因此失效，而你的流水线却毫无察觉。

mcp-covenant 是一个静态二进制文件，可将服务接口快照保存到已提交的锁文件中，并且在变更会破坏现有客户端时让 CI 失败 — 按照人类的判断分类为：破坏性变更 / 次要变更 / 补丁变更。

$ mcp-covenant check --baseline mcp-covenant.lock -- node dist/server.js
mcp-covenant: 3 change(s) — required version bump: MAJOR

  BREAKING (2)
    x tool:legacy — tool was removed  [tool.removed]
    x tool:search → inputSchema.properties.limit — new required property  [schema.property.required.added]
  MINOR (1)
    + tool:newtool — new tool  [tool.added]
# exit code 1 → the job fails

---

为什么选择 Rust

这个想法并不新鲜——目前已有多种用于 MCP 的架构漂移 / 契约工具，都基于 Node、Python 或 JVM。mcp-covenant 的特点是单个静态二进制文件：无需 npm install，无需 Python venv，CI 镜像中也不需要 JVM。将它放进任何流水线即可——Go 团队、Rust 团队，或精简的 Alpine 容器——它都能通过 stdio 或 Streamable HTTP 与 MCP 通信。

它还能识别变更方向，而这正是大多数漂移工具容易出错的地方（见下文）。

与 mcp-armor（运行时防护） 以及 mcp-gauntlet（部署前模糊测试 + 负载测试）配套。mcp-covenant 负责接口稳定性；mcp-herald（规范迁移）和 mcp-passport（注册表发布门禁）则完善了整个工具栈。

---

安装

cargo install mcp-covenant

或从源代码构建：

git clone https://github.com/studiomeyer-io/mcp-covenant
cd mcp-covenant && cargo build --release
# binary at ./target/release/mcp-covenant

更精简的仅支持 stdio 的构建版本（不包含 HTTP 传输，依赖更少）：

cargo install mcp-covenant --no-default-features

---

三条命令即可使用

1. 创建快照，将当前接口保存为基线并提交到 git：

mcp-covenant snapshot -o mcp-covenant.lock -- node dist/server.js
# or against a running HTTP server:
mcp-covenant snapshot -o mcp-covenant.lock --http https://my-server.example/mcp

2. 在 CI 中检查 — 发生破坏性变更时返回非零退出码：

mcp-covenant check --fail-on breaking -- node dist/server.js

3. 检查接口规范，确保架构整洁（排查那些会悄然影响工具选择的问题）：

$ mcp-covenant lint -- node dist/server.js
mcp-covenant lint: 2 finding(s) (0 error, 1 warning, 1 info)

  WARNING (1)
    tool:newtool — tool has no description; the model cannot tell when to call it  [tool.missing_description]
  INFO (1)
    tool:search → limit — parameter has no description  [tool.param.missing_description]

所有操作也都能针对两个锁文件完全离线运行 — 无需服务：

mcp-covenant check --baseline v1.lock --against v2.lock
mcp-covenant lint   --from v1.lock

---

它如何对变更分类

有趣之处在于：工具的 inputSchema 是调用方发送的内容；其 outputSchema 是调用方接收的内容。同一种结构性变更会因方向不同而产生相反的影响范围， 而 mcp-covenant 会同时对两者进行建模。

变更	输入（调用方发送）	输出（调用方接收）
移除工具／资源／提示词	破坏性变更	—
新增工具／资源／提示词	次要变更	—
新增必需字段	破坏性变更	次要变更（保证更强）
新增可选字段	次要变更	次要变更
移除字段	若为必需字段则为破坏性变更，否则为次要变更	破坏性变更（字段已不存在）
可选 → 必需	破坏性变更	次要变更
必需 → 可选	次要变更	破坏性变更（字段现在可能缺失）
类型收窄（例如 ["string","number"] → string）	破坏性变更	次要变更
新增枚举值	次要变更（接受更多值）	破坏性变更（出现未知值）
移除枚举值	破坏性变更（拒绝该值）	次要变更
数组新增 items 架构	破坏性变更（元素现在受到约束）	次要变更
数组移除 items 架构	次要变更	破坏性变更（元素现在不受约束）
additionalProperties: true → false	破坏性变更	—
描述／标题变更	补丁级变更	补丁级变更

嵌套对象属性和数组 items 会递归比较差异。一侧缺失的关键字会按空值比较：没有 properties 的架构表示未声明任何字段，而 required 即使包含架构从未声明的字段也会 计入。最终结果取发现的最严重变更，这决定了你需要为用户升级的 semver 级别。

---

CI

GitHub Action

# .github/workflows/mcp-contract.yml
name: MCP contract
on: [pull_request]
jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: studiomeyer-io/[email protected]
        with:
          command: "node dist/server.js"   # or: http: https://my-server/mcp
          baseline: mcp-covenant.lock
          fail-on: breaking

原始用法，适用于任意 CI

mcp-covenant check --fail-on breaking -- node dist/server.js

SARIF → GitHub 代码扫描

mcp-covenant check --format sarif -- node dist/server.js > covenant.sarif
# then upload with github/codeql-action/upload-sarif

发现结果会以内联方式显示在 PR 中，并定位到你的 mcp-covenant.lock。

---

锁文件

mcp-covenant.lock 是纯文本、格式美观且顺序确定的 JSON——请将其提交，并像审查其他 锁文件一样进行审查。若接口没有变更，重新生成的文件会逐字节一致，因此，嘈杂的差异 正是变更信号。

{
  "covenant_version": "0.1.1",
  "captured_at_unix": 1750000000,
  "server": { "name": "demo", "version": "1.0.0", "protocolVersion": "2025-11-25" },
  "surface": {
    "tools": [ { "name": "search", "description": "Search the catalog.", "inputSchema": { … } } ],
    "resources": [],
    "prompts": []
  }
}

---

范围

mcp-covenant 为只读：它会执行 initialize 握手并调用 tools/list、 resources/list、prompts/list——但绝不会调用工具。它对 MCP 工具实际使用的那部分 JSON Schema 进行建模（type、enum、properties、required、items、additionalProperties）， 而非整个规范。分类规则以及如何添加分类规则，请参阅 CONTRIBUTING.md。

许可证

MIT © StudioMeyer