Shelly 如何隔离 MCP 审批与只读请求
Shelly 允许桌面客户端通过同一网络上的 MCP 服务访问手机端工具,并用令牌认证、默认关闭的服务开关和应用内审批来控制访问。文章还复盘了写入或命令执行等待审批时阻塞其他请求的问题。
AI 深度解读
桌面上的 Claude Code 可以通过 MCP 读取手机上 Shelly 的终端输出和 Git 状态,也可以在用户批准后执行命令或写文件。Shelly 给入口加了 Bearer token 和手机端审批,真机联调却发现,一条等待审批的写请求能让后面的只读请求一起卡住。
这次故障把三个问题摆到了一起:客户端能否接入、某次操作能否执行、等待审批期间其他请求能否继续。Shelly 的版本记录讲清了前两道边界,也给出了一个很具体的排查线索:先看分发器把 await 放在了哪儿。
连上 MCP 后,桌面 AI 能做什么?
Shelly 的这轮改动跨越 2026 年 9 月的 v8.0.1 和 10 月的 v8.0.2。2026-09-16,提交 e578d7f77 增加了本地 MCP Server,settings.mcpServerEnabled 默认关闭。开启后,同一网络内的 Claude Code、Claude Desktop 可以使用 4 个只读工具,分别查看终端输出、Git 状态、已注册的 Agent 和已配置的仓库。开发调试时,桌面客户端可以直接拿到这些信息,省去通过 adb 或 uiautomator 获取的步骤。
原有的 capability broker 管的是 Shelly 向外发出的请求。桌面 AI 调用手机上的工具,方向反过来了。2026-09-17,提交 d0590ece6 给入站调用加了审批。run_command 和 write_file 受 mcpExecEnabled 控制,这个开关默认关闭,只有 MCP Server 已开启时才生效。每次执行或写入都要等 components/McpApprovalModal.tsx 返回决定。弹窗在 Shelly 处于前台时显示,90 秒未处理就自动拒绝。
用户点了同意,工具仍要检查自己的边界。run_command 会硬拒绝 lib/command-safety.ts 判为 CRITICAL 的命令。write_file 只能写入主目录或 Sidebar 配置的仓库路径,沿用了 git_status 的路径范围。HTTP 鉴权负责决定请求能否进门,应用内审批负责当前这次操作,命令和路径规则则决定即使获批也能做多大的事。
为什么点一下手机,积压的响应就一起回来了?
作者记录,他们用真实的 Claude Code 和 Codex 客户端做端到端测试时,在 2026-09-17 发现了这个问题,随后用提交 e2a8b39b6 修复。表面症状挺容易带偏:触碰屏幕后,几个积压的响应会一并返回,看起来像 Android 限制了 JavaScript 定时器。记录下来的原因是请求串行处理。
Shelly 当时轮询请求文件,分发器在 drainOnce() 里等待执行或写入请求的审批。队头那条请求一挂起,后面的请求就没有机会被分发。用户只是想看一眼 Git 状态,也得陪前面的写入请求等决定。这类故障叫队头阻塞。原文给出了故障位置和修复提交,但没展开补丁怎样调度请求,也没有给修复前后的耗时对照。
MCP 对请求之间的并发语义通常不作保证,例如对端会先观察到某条通知还是另一条请求。原文提到 Go SDK 会异步处理多个 tools/call,描述的是 SDK 的行为。Shelly 这里出故障的是自己的请求文件轮询层。排查时要顺着实际入口走一遍,因为外层能同时收请求,内层也可能在一个循环里挨个等结果。
无状态 MCP 改了什么,鉴权还要检查什么?
MCP 2026-07-28 引入了自描述请求。原先的 initialize / initialized 交换和 Mcp-Session-Id 请求头被移除,每次请求带齐必要信息,可以被路由到不同的服务实例。Go SDK 对这个版本及之后的请求要求在 _meta 里提供 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities。io.modelcontextprotocol/clientInfo 可选,但规范建议客户端每次都带上身份。服务端收到第一条请求就处理并校验元数据。客户端可以选择先调 server/discover,实现该版本的服务端必须提供它。
网关可用 Mcp-Method 和 Mcp-Name 识别方法和工具,Go SDK 还用 Mcp-Protocol-Version 镜像请求体里的版本。镜像头与 JSON-RPC 请求体不一致时会报 CodeHeaderMismatch (-32020)。Go SDK 的 Streamable HTTP handler 还需要设置 StreamableHTTPOptions.Stateless = true 才会接受该版本的请求。
无状态模式下,工具仍可返回显式句柄,供客户端在下一次调用时作为参数传回。响应流断开后,在途请求会丢失,客户端得用新 ID 重发。Go SDK 保留 EventStore 和 Last-Event-ID 路径,用于兼容 2025-11-25 及更早版本。无状态临时会话也无法向客户端发起请求,因为客户端的响应找不到原会话。工具中途需要确认或补参数时,协议提供 Multi Round-Trip Requests(MRTR)。工具先返回 resultType: "input_required",客户端再带着 inputResponses 重试。这套机制接替了曾经需要保持流打开的 elicitation/create、sampling/createMessage 和 roots/list。原文把 MRTR 列为另一种做法,没有说 Shelly 的手机弹窗已经改用它。
传输鉴权仍逐条生效。MCP 实现可选是否支持授权,支持 HTTP 授权时应遵循规范。受保护的 MCP Server 是 OAuth 2.1 资源服务器,MCP 客户端代表资源所有者发起请求,授权服务器负责发令牌和必要的用户交互。每条受保护的 HTTP 请求都要带 Authorization: Bearer <access-token>,令牌禁止放进 URI 查询参数。客户端应以 WWW-Authenticate 挑战给出的 scope 为当前操作的依据,首次授权优先用挑战中给出的 scope,之后再按需追加权限。STDIO 实现则应从环境读取凭证。
原文还用 Go SDK 说明鉴权责任怎么分。RequireBearerToken 要包住所有需要校验的 HTTP handler,例如 NewStreamableHTTPHandler。TokenVerifier 负责解析、验证令牌并确认它是发给当前服务的,中间件检查有效期和配置的 scope。设了 RequireBearerTokenOptions.ResourceMetadataURL 时,验证失败会设置 WWW-Authenticate 响应头。这是 SDK 的用法,原文没交代 Shelly 是否直接采用了这套实现。
我的判断
这篇最扎实的部分是真实客户端复现了读请求被挂起,并把故障定位到 drainOnce()。对于前端和 Node 开发者,这比单看协议更有参考价值。即使服务端能同时收下多条 HTTP 请求,自己写的轮询器或任务队列也可能把它们重新串起来。至于修复提升了多少吞吐、并发写入怎么排序,文章没给对照数据,能确认的只有作者记录的故障及修复。
手机弹窗适合同网调试,操作者通常就在手机旁边,也能看到自己批准了什么。后台使用时,前台显示和 90 秒超时会直接影响完成率。MRTR 可以把补充输入的过程交给客户端,适合客户端能够呈现交互并发起重试的场景。两种方式怎么选,要看确认应当在哪个设备上发生。作者没有给两者的对照测试,原文也披露了内容由 AI 工具研究、写作和审阅,且可能在作者阅读前自动发布。
能拿来做什么
- 给 Claude Code 接自建 MCP 工具时,可以先开放状态查询,再给命令执行和文件写入单独加开关。测试时分别覆盖开关关闭、用户拒绝、审批超时,以及用户批准后仍被命令或路径规则拒绝的情况。
- 排查 Node 分发器卡顿时,先发一条会等待审批的写请求,再发一条只读请求。观察后者能否独立返回,并检查轮询循环或队列消费者有没有直接
await整个审批过程。 - 对接
2026-07-28的 Streamable HTTP 服务时,用测试覆盖首条请求的元数据、镜像头不一致和响应流断开。对有副作用的操作,先明确如何识别重复执行,再决定断流后是否自动重发。