suspec-mcp

一个轻量的 MCP stdio 适配器，用于在不经过 shell 的情况下访问 Suspec 的确定性检查器。轻量正是它的特点。

它要求 checks 契约 0.26.0，校验每个 CLI JSON 载荷，并保留有序的报告和退出状态。

工具

suspec_check

将一个有序且非空的绝对制品路径数组交给一个 CLI 进程执行。frontmatter 中的 type: 决定行为。

spec、task、change-plan 和 campaign 输入会接受其 CLI 检查。inventory、audit、research 和 panel 返回 checked: false。缺失和未知的类型会被拒绝。

单次调用会保留 C002 等跨文件检查。任务路径共享同一个 specPath；每个任务都必须指定该 spec。无效的伴生配对会让 CLI 返回结构化拒绝结果，其中 ok: false。

每个制品结果都会标明其类型。只有可选的最终 (file set) 报告没有类型。

suspec_get_checks

以 concise 模式返回契约版本，以及每个核心检查项的 ID 和严重级别。需要名称时使用 responseFormat: "detailed"。同一契约也可通过 suspec://checks 获取。

启动和资源读取要求契约严格为 0.26.0，且退出码为 0。资源失败会直接抛出异常，而不是把错误文档作为资源内容返回。

Related MCP server: governed-mcp

信封

适配器每次成功调用都会返回：

• ok：CLI 是否运行并产生了有效载荷，而不是诊断是否干净；

• source：确切的命令和退出码；

• data：通过校验的详细输出或简洁投影；

• 可选的 note；

• responseFormat。

ok 表示适配器工作正常，而不是制品质量良好。带有阻塞诊断的检查仍为 ok: true；请查看 data.level、诊断信息以及 source.exitCode。

CLI 的退出码 0、1、2 属于契约范围。任何其他退出码都表示适配器启动失败。JSON 形状的 stdout 不会协商新的契约。结构化 CLI 错误仅在退出码为 2 时被接受。

安装

需要 Node.js 22.6 或更高版本，以及一个 suspec CLI。这两个包均未发布。

git clone https://github.com/jcosta33/suspec-mcp
cd suspec-mcp
corepack enable
pnpm install --frozen-lockfile

配置绝对入口点，使 GUI 客户端不依赖 shell 的 PATH：

{
  "mcpServers": {
    "suspec": {
      "command": "/absolute/path/to/suspec-mcp/bin/suspec-mcp.js",
      "args": ["--suspec-bin", "/absolute/path/to/suspec-cli/bin/suspec.js"]
    }
  }
}

CLI 优先级：

每次工具调用都会提供完整的制品路径。服务器不绑定任何仓库、工作区、配置或存储。它是适配器，而不是第二个产品大脑。

~/.agents/artifacts/<workspace>/ 没有特殊的运行时含义。用户级策略安装是 CLI 的职责：直接运行 suspec setup。MCP 不暴露任何 setup、storage、promotion、lifecycle 或 orchestration 接口。

安全

• 主路径和伴生路径必须是绝对路径，且不得包含控制字符、格式字符或行分隔字符。

• 适配器传递固定的参数数组，不经过 shell。

• 只有 check 和受支持的伴生或契约参数会到达 CLI。setup 会在子进程启动前被拒绝。

• CLI 的检查面是只读的。

服务器可以读取其进程可访问的任何路径。文件系统权限就是安全边界，而不是一句建议。请将进程权限与客户端的信任边界对应起来，或使用操作系统级沙箱。

开发

Fixture 漂移以真实 CLI 为准。手写约定证明不了任何东西。将 SUSPEC_BIN 设置为 CLI 的绝对路径；否则，一个名为 suspec-cli 的同级包可能会被发现。生成过程会拒绝其他包。

export SUSPEC_BIN=/absolute/path/to/suspec-cli/bin/suspec.js
pnpm install
pnpm test:run
pnpm gate
pnpm fixtures

test/fixtures/provenance.json 记录 CLI 的 git HEAD、完整的 dirty-worktree 哈希以及二进制哈希。scripts/generate-fixtures.mjs 捕获输出；测试通过 src/suspec/contract.ts 解析每个 fixture。Fixtures 由生成而来，绝不手工修改。

许可证

MIT