proceed-mcp

proceed-mcp

一个 MCP 服务，会向私密 Telegram 聊天发送审批请求，并通过正在等待的 MCP 调用返回配对人类的决定。人类可以在 Telegram 中选择批准、拒绝或回复。proceed-mcp 会记录结果，但不会执行所请求的操作。

预览状态：@meshimize/[email protected] 已发布到 npm。尚未验证实际使用。 源码已在 Windows 和 Node 24.22.2 环境下通过离线测试。该版本在变更合并前通过手动步骤发布。由于 npm 以 HTTP 400 拒绝了移除 latest 的请求，preview 和 latest dist-tag 目前都指向此版本。请固定到确切版本，不要依赖这两个标签中的任一个。此预览尚未验证真实的 Telegram 配对、问题送达、人类决策、OpenCode V2 主机运行或干净的公开 npm 安装。

已实现的范围包括：回环代理、私密 Telegram 配对与问题显示、批准／拒绝／回复、过期、取消、经能力授权的检索，以及确认。此预览尚未实现 MCP Events、超时后自动继续、doctor 和 retry。

分发

@meshimize/proceed-mcp 是此产品的 npm 包。它会安装 proceed-mcp 命令及其运行时源码。它不是托管的 MCP 端点，也没有云端代理。MCP 适配器和代理都在你的机器上运行。代理仅监听 127.0.0.1，并会调用 https://api.telegram.org 与 Telegram 通信。

已发布的 npm 包是公开预览版 @meshimize/proceed-mcp，版本为 0.1.0-preview.1。它以 preview dist-tag 发布，latest 标签也指向此版本：npm 以 HTTP 400 拒绝了移除 latest 的请求。请固定到确切版本，不要依赖这两个标签中的任一个。这是变更合并前手动执行的发布，并非发布工作流的结果。计划通过发布自动化进行受保护的发布，但尚未实现，也没有运行任何自动发布。

官方 MCP Registry 列表是此预览已获批准的交付任务，与 npm 包发布分开跟踪和报告。列表仅提供发现元数据：它会指向 npm 包，不会托管或运行代理。计划在 npm 预览版发布且确切版本的安装检查通过后再提交列表。选定的列表名称是 io.github.renl/proceed-mcp，对应仓库 https://github.com/renl/proceed-mcp。此选择要求确认 Registry 命名空间和 Registry 发布权限，但这些事项仍未解决，且不代表已通过 Registry 身份验证或架构验证。尚未发布任何列表，也未验证任何 Registry 交付。列表受阻或待处理，不会改变或隐藏 npm 发布结果。

要求

• Node.js 24 或更高版本。package.json 声明要求 >=24。此预览仅在 Windows 和 Node 24.22.2 环境下测试过。其他操作系统和 Node 版本均未测试。
• 一个专用 Telegram 机器人，以及与该机器人的一个私密聊天。请勿与其他轮询器或 webhook 共用此机器人。
• 代理和 MCP 适配器必须在同一台机器上运行。人类可以位于远程位置。
• 在 Windows 上，必须提供 powershell.exe 和 icacls，以进行仅限所有者的 ACL 检查。在 POSIX 系统上，状态目录必须支持仅限所有者的权限位。
• 无需构建工具、原生扩展或 postinstall 脚本。

安装

全局安装此预览的确切版本：

npm install --global @meshimize/[email protected]
proceed-mcp --help

或者无需全局安装即可运行：

npx --yes --package @meshimize/[email protected] -- proceed-mcp --help

此作用域包会安装相同的 proceed-mcp 命令。版本 0.1.0-preview.1 以 preview 标签发布，latest 标签也指向此版本，因此请固定到确切版本，不要依赖这两个标签中的任一个。安装成功只是第一项发布检查，并不能证明实际审批流程可正常运行；干净的公开安装也尚未验证。

设置代理和 Telegram

1. 创建受保护的状态

选择一个绝对路径，指向空目录或尚不存在的目录。将其放在仓库之外。

proceed-mcp init --state-dir <absolute-state-dir>

init 会创建受保护的 config.json、本地控制凭据和空日志。它不会覆盖现有状态。它会打印状态路径，但绝不打印凭据值。

2. 添加一位所有者

所有者是 MCP 适配器使用的传输主体。

proceed-mcp owner add <owner-id> --label "<display-label>" --state-dir <absolute-state-dir>

<owner-id> 必须符合 [a-z0-9_-]{1,64}。标签仅用于显示，并会显示在 Telegram 中。请在首次运行 serve 前执行此操作，因为存在代理所有权记录时，owner add 会拒绝执行。所有者记录和凭据均不可更改。

3. 创建专用的 Telegram 机器人

使用 @BotFather 创建新机器人，并妥善保管其令牌。此机器人仅供此代理使用。不要为其配置 webhook，也不要让其他轮询器使用它。proceed-mcp 绝不会删除 webhook，也不会回退或丢弃待处理的更新。如果 Telegram 报告存在冲突的消费者，Telegram 处理将停止并显示诊断信息，此时必须修复机器人并重启 serve。

4. 在前台启动代理

仅将令牌放入代理自身进程的环境中。

PowerShell：

$env:PROCEED_TELEGRAM_BOT_TOKEN = '<bot-token>'
proceed-mcp serve --state-dir 'C:\absolute\path\to\proceed-state'

POSIX：

export PROCEED_TELEGRAM_BOT_TOKEN='<bot-token>'
proceed-mcp serve --state-dir /absolute/path/to/proceed-state

等待出现 proceed-mcp: broker ready on http://127.0.0.1:43189 和状态目录所在行。保持此终端处于打开状态。

令牌只会从代理进程的环境中读取。它绝不会存储在状态目录、日志、Telegram 或请求历史记录中。本产品不会读取 .env 文件。绝不要将令牌放入 MCP 适配器的环境或 MCP 客户端配置中。

如果令牌缺失或为空，代理仍会在本地启动并打印警告。必须先有人工用户完成配对，才能创建请求，因此请先完成 Telegram 设置再进行测试。如果令牌被拒绝，或机器人由其他消费者占用，Telegram 处理将停止并显示诊断信息，但本地代理会继续运行。请修复机器人并重启 serve。

5. 配对私聊

在第二个终端中：

proceed-mcp pair --state-dir <absolute-state-dir>

命令会打印 Pairing code: 和 Expires at:。在与机器人的私聊中发送 /start，然后在有效期内准确发送 /pair <code>。不接受群聊。单独发送 /start 不会授予任何权限。带机器人后缀或格式错误的命令不会完成配对。配对码只能使用一次，有效期为五分钟，且不会以明文存储。

只有首次配对会成功。无法在聊天中重新配对或更改身份。

6. 连接 MCP 客户端

OpenCode V2

在 opencode.jsonc 的 mcp.servers 下添加本地服务。此配置格式遵循 OpenCode V2 MCP 文档。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "proceed": {
        "type": "local",
        "command": [
          "npx",
          "--yes",
          "--package",
          "@meshimize/[email protected]",
          "--",
          "proceed-mcp",
          "mcp",
          "--owner",
          "<owner-id>",
          "--state-dir",
          "/absolute/path/to/proceed-state",
        ],
        "codemode": false,
      },
    },
  },
}

替换 <owner-id> 和状态路径。在 Windows 上，请在 JSON 字符串中转义反斜杠，或改用正斜杠。codemode: false 会直接公开这些工具。保存后，OpenCode 会重新加载 MCP 配置。运行 opencode mcp list 检查连接。

--package 参数用于选择带作用域的 npm 包，-- 后的参数则是该包中的 proceed-mcp 命令。如果你已全局安装该包，请将 command 数组的开头改为 proceed-mcp，并保留相同的 mcp --owner ... --state-dir ... 参数。

使用此服务名称时，OpenCode 会将工具公开为 proceed_prepare_approval、proceed_request_approval、proceed_get_approval、proceed_cancel_approval 和 proceed_acknowledge_approval。如果不关闭 Code Mode，OpenCode 会将它们归在 tools.proceed 下。

不要将 PROCEED_TELEGRAM_BOT_TOKEN 添加到 environment 中。适配器不需要此令牌，也不得接收它。

其他 stdio MCP 客户端

在任何能够启动本地 stdio 服务的客户端中使用此命令：

proceed-mcp mcp --owner <owner-id> --state-dir <absolute-state-dir>

无需全局安装即可运行已发布的版本：

npx --yes --package @meshimize/[email protected] -- proceed-mcp mcp --owner <owner-id> --state-dir <absolute-state-dir>

此适配器不需要 OpenCode API、密码、提供商凭据或专有会话元数据。 它只连接本地代理。请保持 serve 运行。

此服务公布 MCP 协议 2025-11-25，并提供五个工具：prepare_approval、 request_approval、get_approval、cancel_approval 和 acknowledge_approval。

MCP 工具

工具	参数	效果
prepare_approval	可选的 session_label	预留一个持久化的请求标识和一个私有请求凭据。不会发送 Telegram 问题。
request_approval	request_handle、request_capability、client_request_id、action、context、可选的 expires_in_seconds	创建或重放唯一请求，然后等待其解决、过期或取消。若重放的请求已处于终态，则立即返回。
get_approval	request_id、request_capability	读取经授权的请求，并首先应用过期规则。不会产生投递副作用，也不会唤醒 Agent。
cancel_approval	request_id、request_capability	取消该待处理请求。若结果已处于终态，则原样返回。
acknowledge_approval	request_id、request_capability、decision_id	记录已收到相应的终态决定。此操作幂等，且不会创建第二个决定。

action 接受 1-1000 个 Unicode 标量值，context 接受 0-1000 个，session_label 接受 1-128 个。 client_request_id 必须匹配 [A-Za-z0-9_-]{1,128}。expires_in_seconds 是 60 到 86400 之间的整数，默认值为 3600。

request_approval 是等待调用。它返回实际结果，而非创建回执。 单独调用 prepare_approval 不会发送 Telegram 问题，也不会创建可执行的请求。

典型的 Agent 流程如下：

1. 调用 prepare_approval，并将返回的 request_handle、request_id 和 request_capability 保存在一起。
2. 使用该句柄和凭据，提供唯一的 client_request_id、准确的操作，以及足够让人类区分该请求的上下文，调用 request_approval。
3. 使用返回的 resolution 和 delivery_state。此调用会直接返回人类的处理结果。
4. 如果结果包含 decision_id，则使用 acknowledge_approval 确认该确切决定。
5. 只有当结果为 approved 时，才执行操作，并且只能在你自身的权限规则范围内执行。

请求凭据与其所属主体共同授权后续的 get_approval、 cancel_approval 和 acknowledge_approval 调用。切勿将其放入 Telegram、助手消息、 日志、session_label、action 或 context 中。这些文本字段会显示在 Telegram 问题中。标签是调用方提供的显示上下文，不是经过身份验证的身份。

与同一主体下的其他上下文共享凭据，会授予该上下文访问这一个请求的权限。这不会重定向原始等待调用，也不会授权其他主体。

决策与交付

结果	含义
approved	配对的人类明确批准了此请求。
rejected	配对的人类拒绝了此请求。这不授权执行该操作。
responded	配对的人类提供了指示。这不构成批准。
expired	截止时间已过，仍未作出决定。这不构成批准。
cancelled	获授权的调用方取消了待处理请求。这不构成批准。

只有明确选择“Approve”才会授予批准。“Reject”会记录拒绝。只有收到有效关联的文本后，“Respond”才会记录针对该请求的指示。要发送指示，请按下“Respond”并回复其提示，或准确发送 /respond <request_id> <text>。“Respond”文本中类似批准的字词绝不会授予批准。“Respond”文本会原样存储和返回，包括空白字符。

每个请求最多只能有一个处理结果。重复更新和相互冲突的选择不会替换该结果。采取行动前，请根据 (request_id, decision_id) 去重。

客户端或传输超时不会取消或使请求过期。等待中的调用丢失也不会取消请求。请保留请求标识和能力，并在之后的轮次中使用 get_approval 读取未变更的结果。检索不会唤醒 Agent，也不会启动新的助手轮次。

此预览版不支持 MCP Events。超时后不会自动恢复，也不会自动重新附加会话。批准会记录一个结果，但不会执行该操作。

delivery_state 描述的是结果报告状态，而非决策：

• not_applicable：尚无终结决策。
• pending：已记录决策，但尚未确认交付。
• returned：适配器报告已将结果写入原始调用。尚未确认是否收到。
• confirmed：请求能力持有者已确认该决策。
• unavailable：无法自动交付。请使用保留的能力检索结果。
• blocked：交付受阻。请检查 proceed-mcp status。

首次手动测试

使用无害操作。产品不会执行该操作。

1. 保持 serve 运行，并让 MCP 客户端保持连接。
2. 在新的 Agent 会话中，先请求 prepare_approval，再请求 request_approval，其中 client_request_id 为 manual-approve-1，操作为 Report the text PROCEED TEST，上下文为 Harmless first-use check. Do not modify files.，且 expires_in_seconds 为 300。
3. 在第二次调用仍处于等待状态时，在 Telegram 中按下 Approve。
4. 预期这次等待中的调用返回 resolution: approved，且 request_id 相同。使用 acknowledge_approval 确认返回的 decision_id。无需执行任何文件或命令操作。
5. 在下一轮助手对话中，检查后续确认。它必须指出相同的 request_id 和已记录的结果 approved。它不得重复 request_capability，也不得执行该操作。这是必须进行的手动检查，并非已验证的预览结果。
6. 使用新准备的句柄和 client_request_id manual-reject-1 重复上述步骤，然后按下 Reject。 调用应返回 rejected，而不是执行该操作的授权。以相同方式检查下一轮 助手对话：request_id 和结果 rejected 匹配，不回显能力，也不执行操作。
7. 使用 manual-respond-1 重复上述步骤。按下 Respond，使用提示词回复确切文本 Read only. Do not modify files.，并确认调用返回 responded，且文本保持不变。该文本中类似批准的词语仍是指令。检查下一轮助手对话中的 request_id 和结果 responded 是否匹配；这表示记录的是指令，而非批准，且不回显能力，也不执行操作。

如果等待中的调用在你选择之前超时，请求会一直处于待处理状态，直到期限届满。在之后的轮次中，使用保留的 request_id 和 request_capability 调用 get_approval。检索操作不会唤醒 Agent。

最后，在代理终端中按一次 Ctrl+C，并等待 proceed-mcp: broker stopped。

命令

命令	用途
init --state-dir <dir>	创建受保护的空状态。拒绝覆盖现有状态。
owner add <id> --label <label> --state-dir <dir>	添加不可变所有者及其凭据。要求代理已停止。
serve --state-dir <dir>	运行前台代理。从代理环境中读取 Telegram 令牌。
pair --state-dir <dir>	向运行中的代理请求一次性、五分钟有效的配对码。
mcp --owner <id> --state-dir <dir>	为一个所有者运行 stdio MCP 适配器。
status --state-dir <dir> [--request <id>] [--json]	显示请求、处理结果、Telegram 和投递状态，以及下一步操作。
retry <request_id> --state-dir <dir>	报告此预览中无法重试该请求。

尚未实现 doctor，因此会作为未知命令失败。帮助输出中的旧版 origin add 命令属于已弃用的基于 origin 的配置，不适用于此状态。请使用 owner 模式。

退出代码：完成时为 0，参数或配置无效时为 2，必需条件不可用时为 3，存储或完整性故障时为 4。诊断信息写入 stderr。MCP stdout 仅承载协议帧。

状态、隐私和关闭

路径	内容
config.json	架构版本 2：Telegram 令牌变量名、代理端口、所有者记录。
credentials/control.token	用于配对、状态查询及其他控制操作的本地控制凭据。
credentials/owner.<owner-id>.token	用于 MCP 请求路由的各所有者凭据。
journal.log	仅追加的事务日志。唯一可变的产品状态。
broker.lock	由运行中的代理写入、正常停止时移除的所有权记录。

状态目录及其中的文件仅限当前 OS 账户访问。init、owner add 和 serve 会验证这一保护措施；如果无法确保保护，则会失败而不会继续。Windows 检查通过 PowerShell 和 icacls 使用仅限所有者的 ACL。POSIX 使用仅限所有者的权限位。

日志会存储请求文本、响应文本、配对标识符、决定、时间戳和交付状态。请将状态目录视为敏感的本地数据。请备份已停止的代理的整个状态目录。此预览版不支持删除历史记录或压缩日志。

请求能力仅以 SHA-256 验证值的形式存储。明文能力会出现在工具结果中，并由你负责保管。命令绝不会打印凭据和令牌值。

代理仅绑定到 127.0.0.1，每个路由都需要凭据，并且会拒绝浏览器源。没有公共代理侦听器，也不提供远程代理托管。

使用 Ctrl+C 停止代理，并等待 proceed-mcp: broker stopped。正常停止会释放所有权记录。如果关闭失败或进程被终止，broker.lock 可能会残留，导致下次运行 serve 时拒绝启动。请保留受保护的状态目录，不要删除锁文件或日志。此预览版不会自动恢复过期锁。

常见故障

• BROKER_UNAVAILABLE：启动 serve，或检查适配器和代理是否使用相同的 --state-dir。
• NOT_PAIRED：先完成 /pair，再创建请求。
• NOT_FOUND：所有者或状态目录错误、句柄未使用，或请求能力不匹配。
• DECISION_MISMATCH：请求尚未进入终止状态，或 decision_id 不匹配。
• Telegram 处理已停止：检查机器人令牌，并确认没有 Webhook 或第二个轮询器正在控制该机器人。修复后重新启动 serve。

限制

• 每个代理只能配对一名真人和一个机器人令牌。只有首次配对会成功。无法在聊天中更改身份或重新配对。
• 每个状态目录只能运行一个代理。单独的所有者代表独立的传输主体，而非另一名真人或另一个机器人。
• 不提供托管服务，也不提供远程代理。代理仅限本地回环连接。
• 不支持 MCP Events。工具超时后不会自动继续，超时也不会取消请求。
• 检索不会唤醒 Agent，也不会创建新的决定。
• 产品不会执行操作，也不会强制执行 OpenCode 的权限规则。审批依赖各方配合。
• 无法恢复已退出的 MCP 客户端或框架进程，也不会自动重新连接会话。
• OpenCode V2 是首个验证框架。未测试其他框架。虽然提供通用的 stdio 命令，但不保证兼容多个框架。
• 清单要求 Node.js 24 或更高版本。离线测试证据仅适用于 Windows 和 Node 24.22.2。请勿假设支持其他操作系统或 Node 版本。
• 尚未实现 doctor。retry 会报告不可用。
• npm 预览版已发布。尚未验证全新公开安装，也未验证 Telegram 或 OpenCode 的实时结果。

许可证

MIT，版权归 Ng Cheng Leong 所有，2026 年。发布包必须在根目录中包含标准的 MIT LICENSE 文件。