内容
suspec-mcp
一个 [MCP](https://modelcontextprotocol.io) 的_stdio_服务器，提供 [Suspec](https://github.com/jcosta33/suspec) 的规范/评审规则，使代理人可以直接访问 — 因此，代理人在任务中可以询问 Suspec _"我的范围是什么？"_、_"缺少什么证据？"_、_"评审人不应该错过什么？"_ — 并 **被告知事实和人工关注列表，而不是可以直接转换为绿色勾选的通过/失败结果**。
## 为什么它存在（不可绕过的价值）
这里有两件事是无法通过给代理人一个 shell 实现的：
1.裁决信封是一种保证，而不仅仅是一种便利。** 每次对读取结果都带有 `noVerdictIssued: true` 和一个派生的、结构化的人工关注列表 — 覆盖口、超出范围的更改、空证据通过行、自报告不都表示为 `{category, severity, message, ref}`。suspec-mcp 提供 **事实**；人类或独立评审者拥有通过/失败/未验证/阻止空或弱证据单元格读取未验证，无论对账是否干净。代理人 **无法** 使此服务器声明其自身工作完成 — 这目的。
2. **没有 shell 的客户端提供服务。** Claude Desktop、Cursor 和终端客户端无法自行运行 `json`。对于MCP 资源（棋盘、检查合约、解析的任务/评审/发现）和提示（实施者/评审者立场）是唯一一种将 Suspec 的上下文带入对话的方式 — 应用程序驱动的上下文 + 程序化提示，而不是 CLI 包装。
对于人，_工具_ 层很大程度上是一种输入的、便捷方式，优于相同的 `--json`；上述持久价值 shell 无法提供的。
## 它做什么 — 以及它不做什么使用固定的 argv（从不使用 shell 字符串，从不使用客户端注入的标志）启动 `suspec <cmd> --json`，并将输出重塑为 MCP 工具、资源和提示。它 **不** 导入 suspec-cli 的内部函数、运行模型循环、写入棋盘、写入评审结果或发出裁决。
- **仅对账，无裁决 — 包括安全写入层。** 安全写入工具（`scaffold_spec` / `split_task` / `scaffold_finding`）是无裁决的 _准备操作_： CLI 的 `new spec` / `new task --from` / `promote` 搭建新的工件，不写入棋盘、不写入评审结果、不覆盖任何内容（不带 `--write`/`--force`/`--agent` 标志）。
- **根目录限制。** 它只在配置的工作区根目录内读取/搭建；每个客户端提供的输入在子进程运行前都会验证。文件路径是 realpath 限制的（无 `..`，无绝对路径转义，无符号链接转义）；id/slug/stem 必须是一个安全的段；git 基础必须是无标志的引用；动词 _ 标志在单个子进程边缘进行允许列表检查。
- **一种弯曲的 typed ，只有在应该的地方才弯** CLI `--json` 形状被镜像为一个漂器（一个重命名的/删除的字段，适配器 _读取_ 失败一个测试，而不是静默错误输出），但一个的枚举（CLI 咨询代码，适配器仅中继 `z.string()` —性的附加 CLI 枚举 suspec-mcp 的中断。固定装置 **生成** 自二进制文件（`pnpm fixtures`），并且测试重新运行生成器，因此它们不会过时 **许多库，而不是框架。** 它通过公共 `--json` 接口与 suspec-cli 耦合，因此 suspec-cli 保持其最小的占用空间，每个部分都保持的实用性。
## 运行它
```jsonc Claude Desktop / Cursor MCP 配置
{
"mcpServers "suspec": {
"command": "suspec-m "args": ["--workspace", "/path/to/your/suspec-workspace"],
},
},
}
```
配置：`--workspace <path>` / `SUSPEC_WORKSPACE`（工作区根目录）；`--suspec-bin <path>` / `SUSPEC_BIN`（`suspec` 二进制文件，默认为 PATH 上的 `suspec`）。需要安装 [`suspec` CLI](https://github.com/jc/suspec-cli)。
上面的 `suspec-mcp` 命令解析为此二进制文件。要从源代码发布版本可用：
```git clone https://github.com/jcosta33/suspec-mcp && cd suspec-mcp
pnpm install && npm link # 将 `suspec-mcp` 暴露在 PATH 上（通过类型剥离运行 TypeScript 源代码）
```
节点：启动器在 `src/index.ts` 存在时从源代码运行（源代码检出 — 即使在 `pnpm build` 之后），它在运行时剥离类型，需要 22.6发布/文件修剪的安装且没有 `src/` 的情况下，才会运行的 `dist/`，需要 Node ≥ 18.18。
## 表面
-工具（8）。** 都声明一个 `output，并接受一个 `: concise|detailed 简洁返回相关约 ⅓ 个标记），按需返回原始有效载荷。
- `suspec_get_status` — 派生的工作区棋盘（规范、任务、评审状态、分类列表）。
- `suspec_list` — 为没有 id 的代理人枚举规范/任务。
- `suspec_check_workspace` — 每个规范 + 更改计划的检查合约。
- `suspec_check_file` — 一个文件的检查路径（规范、更改计划或评审数据包）。
- `suspec_get_task` — 解析的任务数据包（范围、区域、声称的更改、嵌入的规范部分）。
- `suspec_get_spec` — 解析的规范（前置信息、需求、`## Execution` 运行记录）。
- `suspec_get_review` — 解析的评审数据包（状态、覆盖率行、验证块、身份）。
- `suspec_get_checks` — 检查合约（版本 + 核心检查）。
- **对账工具（1）。** `suspec_reconcile` — 将 `task`（或 `spec`，对于 1:1 评审到规范的情况）与规范和工作树差异对账。无论是否存在评审数据包，都有一个引擎（报告带有 `hasReviewPacket`；没有单独的扫描工具）。实施者与评审者的立场分离存在于提示中，而不是在两个工具中。
- **安全写入工具（3）— 无裁决的准备操作。** `suspec_scaffold_spec` (`new spec`)，`suspec_split_task` (`new task --from`，复制范围而不是发明），`suspec_scaffold_finding` (`promote`)。都搭建一个新工写入棋盘/结果，不发出裁决。
- **资源（7）。** 固定资源：`suspec://workspace`，`suspec://status`，`suspec://checks`。模板资源：`suspec://tasks/{id}`，`suspec://specs/{id}`，`suspec://reviews/{id}`，`suspec://findings/{id}`。
- **提示（5）。** `suspec_task_briefing`，`suspec_before_done`（实施者 — _不能批准自己的工作_），`suspec_review_assistant`（独立评审者 — _伪造，不要信任_），`suspec_evidence_rule`，`suspec_finding_candidate`（由 `suspec_scaffold_finding` 支持）。 before-done / review-assistant 的不对称性是故意的：没有提示授予裁决权。
## 开发
```sh
pnpm install
pnpm gate # 类型检查 + lint +
