mcpward Vibe 项目

项目简介

mcpward 是一款针对 MCP（Model Context Protocol）服务器的黑盒合同与安全测试 CLI，专为 CI 环境设计。它把"对 MCP 服务器的依赖"当作普通 npm 依赖来对待：先用一个 lockfile 把服务器的工具清单、参数 schema、输出形状、描述文本完整快照下来，之后每次服务器升级都在 CI 中比对 diff，发现 schema 漂移、沉默的描述篡改、协议违规、错误合同失误、Tool 毒化模式等问题就立刻中断构建并产出 JUnit / SARIF 报告。与同类工具 mcp-scan 专注"本地安装的 MCP 服务器是否被入侵"不同，mcpward 专注回答另一个问题——"这个 MCP 服务器的合同是否在两次发布之间发生了变更"，运行完全离线、不需要账户、不调用远程 API、不上传遥测数据。

核心功能

1. 合同快照与 lockfile 固定：运行 mcpward baseline 连接目标 MCP 服务器，捕获全部工具的描述、输入输出形状，保存到 mcpward.lock.json，把它当作普通依赖 lockfile 提交进版本控制。
2. schema 漂移检测：能识别新增必填参数、删除字段、类型变窄、enum 收紧、maxLength 缩小、新增 pattern 等任意深度的破坏性 schema 变更。
3. 沉默篡改检测：工具描述变化（哪怕只多一个零宽字符）也会被抓出，因为 Tool 描述会被 Agent 当成自然语言指令阅读，是潜在的 prompt injection 载体。
4. 权限边界翻转检测：readOnlyHint 从 true 翻到 false、destructiveHint 从 false 翻到 true 都会被识别为高风险，因为它们影响 Agent 自动授权决策。
5. 双层错误合同校验：检查错误返回的格式、错误信息是否包含必要上下文、错误是否会被下游静默吞掉。
6. 输出形状黑盒推断：对未声明 outputSchema 的服务器，mcpward 会基于真实调用推断输出结构（只对比字段 / 类型 / 嵌套，不读取值），把输出形状漂移也纳入 diff。
7. 行为测试套件：可以在 lockfile 中录制多次实际调用并比对结果，让"工具是否仍然按原意工作"成为可重复的回归项。
8. JUnit / SARIF 报告：输出可直接接入主流 CI 平台，把漂移抓取挂到 PR 检查、Merge 卡口、定时构建中。

技术实现

项目采用 Node.js ≥20 实现，封装为 npm 包，对 MCP 服务器以 stdio 或 Streamable HTTP 协议启动会话；通过官方 MCP SDK 拉取工具列表与 schema，对每个工具进行结构化 diff。严重程度分类器采用纯函数 + 穷尽性化 fixture 测试驱动，变更被分为四档（high / medium / low / 报告级），不同档位对应不同 fail 策略。输出形状检查采用"只读不取"设计，从不读不取值（仅推断字段 / 类型 / 嵌套），从不发送远程调用，从不把数据上传到外部。本地优先 / 零遥测 / 零账户的设计原则贯穿整套实现，工具名 / 描述 / 调用结构全部留在本机。

快速上手

1. 初始化配置：在项目根目录运行 npx mcpward init，生成默认 mcpward.yml 配置文件。
2. 捕获基线：执行 npx mcpward baseline，连接目标 MCP 服务器，生成 mcpward.lock.json 并提交进版本控制。
3. 运行检查：执行 npx mcpward run，扫描当前连接的 MCP 服务器并产出完整 diff 报告。
4. 持续 diff：服务器升级后执行 npx mcpward diff，自动读取 lockfile 并比对，输出差异表。
5. 接入 CI：在 GitHub Actions / GitLab CI 中作为 step 执行 npx mcpward diff，设置退出码 1 即中断构建。
6. 输出 CI 报告：以 --format junit 或 --format sarif 输出，可直接被主流 CI 平台解析可视化。
7. 调整 fail 策略：在配置文件中设置 fail_on: high（仅中断高危变更）、medium（中断高危 + schema 破坏）、low（中断所有变更），或显式列出关心的变更类目。
8. 开启输出形状推断：设置 output.enabled: true 后只对 readOnlyHint 为 true 且无需参数的调用自动推断输出；其他工具需手动 allowlist 才会被采样。

适用人群

• 把第三方 MCP 服务器作为生产依赖集成进产品的应用开发者，需要 CI 把合同变更挡在合并前；
• 平台安全团队 / SRE 团队，希望把 MCP 依赖治理纳入既有依赖供应链验证流程；
• MCP 服务器作者本人，可以用 mcpward 作为面向依赖者的质量背书；
• 重视本地优先 / 不上传 / 不需要账户的依赖治理拥护者。