Maple

@maple-kit/mcp

Model Context Protocol 服务，会将 Maple 在预览部署中收集的评审评论交给编码 Agent。

预发布版本。 这里的每个软件包都是 0.x 版本，不承诺兼容性。

Agent 等待评论，读取评论及其上下文——标注者提供的 file:line、视口、截图，以及编写评论时所依据的模拟图——然后进行修改，并将评论关联到修复该问题的提交以解决它。评审者负责添加覆盖层；双方在存储中会合。

安装

npm install @maple-kit/mcp

随附两个二进制文件：服务 maple-mcp，以及用于阻止 Agent 在评论仍未解决时自称已完成的 maple-stop-hook。

连接 Agent

客户端不带参数启动服务，因此通过环境变量进行配置。在 Claude Code 的 .mcp.json 中：

{
  "mcpServers": {
    "maple": {
      "command": "npx",
      "args": ["-y", "-p", "@maple-kit/mcp", "maple-mcp"],
      "env": { "MAPLE_GITHUB_OWNER": "acme", "MAPLE_GITHUB_REPO": "web" }
    }
  }
}

并通过 op run --env-file 运行客户端，以确保 GITHUB_TOKEN 不会落入文件。缺少所需值时，服务会在启动时失败，而不是等到首次调用工具时才失败。

名称	是否为密钥	说明
GITHUB_TOKEN	是	可读取和写入拉取请求评论的令牌。github 存储所必需。
MAPLE_GITHUB_OWNER	否	仓库所有者。github 存储所必需。
MAPLE_GITHUB_REPO	否	仓库。github 存储所必需。
MAPLE_GITHUB_API	否	API 根地址，用于 Enterprise Server。
MAPLE_STORE	否	github：配置了代码托管平台时的默认值；或 file：未配置时的默认值，即 .maple/ 下的评论。
MAPLE_BRANCH	否	Stop hook 检查的分支，否则检查当前检出的分支。服务会忽略此变量。
MAPLE_URL	否	已部署路由的挂载 URL。解决评论时会请求它重新发布门禁。
MAPLE_GATE_TOKEN	是	仅用于 CI：门禁 App 的安装令牌。不可与 MAPLE_URL 同时使用。
MAPLE_GATE_APP_ID	否	门禁 App 的 ID，使其更新自己的检查运行，而非其他 App 的检查运行。
MAPLE_REQUIRE_APPROVAL	否	设为 true 时，门禁会保持等待，直到有人批准，与路由和 CI 的行为一致。

未配置代码托管平台

不设置 GITHUB_TOKEN、MAPLE_GITHUB_OWNER 和 MAPLE_GITHUB_REPO 时，服务会读取和写入工作目录所在仓库中 .maple/ 下由 fileStore() 保存的评论，因此即使没有拉取请求，也能在笔记本电脑上完成整个流程。显式设置 MAPLE_STORE=file 也能指定此行为。这是笔记本电脑的存储，不是预览 Pod 的存储：相关说明见 docs/connectors.md。Stop hook 会读取会话工作目录中当前检出分支对应的同一文件夹；如果没有 .maple/ 文件夹、该分支没有评论或当前目录不属于仓库，它就不会输出任何内容。

工具

工具	读取	功能
list_comments(branch, statuses?)	✓	返回分支上的评审评论，按时间从新到旧排列。
wait_for_comments(branch, cursor?, timeoutMs?)	✓	阻塞，直到收到新评论或等待时间结束。如果没有新评论，则返回状态 "timeout"，而不会报错。
resolve_comment(id, sha, note?)		将评论标记为已解决，并记录处理该评论的提交。
get_comment_context(id, branch)	✓	返回处理单条评论所需的所有信息：锚点、视口、周边标记，以及任何回放链接。在 Maple Mock 下撰写的评论会附带 mock.recipe 和 mock.replay，后者是指向该状态下页面的链接。
start_solo(previewUrl)		在 localhost 上启动桥接服务，并返回将已部署预览与其配对的链接。评审者在浏览器中打开该链接后，他们在那里撰写的评论会写入 .maple/，供 list_comments 和 wait_for_comments 读取。这些评论不会计入合并门槛。

wait_for_comments 的等待时间上限为 55 秒，因为每个编码客户端都会在 60 秒时终止工具调用；它每 15 秒发送一次 notifications/progress。超时是一种结果：如果 Agent 把超时视为错误，那么第一次没人查看时，它就会停止循环。它的游标是时间戳；首次调用时省略游标，即可读取所有已经等待处理的评论。

停止钩子

MCP 无法让服务中断客户端，因此循环需要从另一端闭合。当 Agent 认为自己已完成时，Claude Code 的 Stop 钩子会运行，而 Maple 会用仍未关闭的评论作出回应：

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "npx -y -p @maple-kit/mcp maple-stop-hook" }] }
    ]
  }
}

Maple Claude Code 插件会为你注册此钩子。当评论处于 open 或 needs_reverify 状态时，它会阻塞；每个会话最多连续阻塞八次。第九次时，它会让会话结束，并说明仍有哪些评论未关闭；这比 Agent 为了脱身而解决评论要好。计数按 session_id 保存在系统临时目录中，未被阻塞的停止操作会重新开始计数。

钩子无法看到 .mcp.json 中的 env。 该配置块只会传递给 MCP 服务；钩子运行在客户端自己的环境中。因此，MAPLE_GITHUB_OWNER、MAPLE_GITHUB_REPO 和 GITHUB_TOKEN 必须在客户端自身启动的位置设置——使用同一个 op run --env-file——否则钩子会指出缺少的变量并失败。如果前两个变量都未设置，它会改为读取当前分支下 .maple/ 中的评论；如果没有评论，则允许所有停止操作通过。MAPLE_BRANCH 默认为会话工作目录中检出的分支。

问题解决后，合并门禁解除

设置 MAPLE_URL 为已部署路由的挂载 URL，例如 https://web-482.preview.acme.dev/api/maple，resolve_comment 会请求该路由 重新发布 maple/visual-review，因此，即使 Agent 解决了最后一条评论后没有待推送的内容， 检查也不会一直停留在已完成的工作上。 请求会携带分支和 GITHUB_TOKEN，后者必须具有向仓库推送的权限。 路由会判定结果，并使用门禁 App 自身的凭据发布结果，这些凭据绝不会离开路由。 刷新失败时会记录到标准错误输出，但仍会记录问题已解决。

MAPLE_GATE_TOKEN 是供 CI 使用的另一种方式：直接用于发布的门禁 App 安装令牌。 该令牌自生成后一小时过期，因此适用于作业，而非会话。启动时同时设置两者会失败。

文档

• Agent 工作循环
• 合并门禁
• maple-review 技能可将拉取请求中的 ```maple 评论转换为工作清单，无需服务器。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。