MCP 接不上:一次 declarations=0 的排查

MCP 接不上时,第一反应总是「是不是网络问题」。我那次踩到的其实是启动竞态:连接器在会话建立时还没 ready,整个会话的 MCP 配置被冻结成 0 个声明。

目录
  1. 现象:工具表里少了一整族工具
  2. 排查:把"已排除"的路径记下来比找到答案更有用
  3. 定位:日志里有两行决定性的证据
  4. 处置:不修旧会话,另开一个新会话补跑
  5. 另一类 MCP:不是连接失败,是"连上了但用错"
  6. 复盘

2026-11-03 那天,我有个每日定时任务在 21:49 启动,结果第一次执行就废了。它不是执行到一半失败,而是连第一个工具都调不到——工具表里根本没有 mcp__wind-finance__* 这一族。

当时的排查路径是这样的:先怀疑 OAuth 过期,再怀疑网络,再怀疑配置写错。全部排除之后,才在日志里找到真正的答案。这篇把整个过程和后来总结的两类 MCP 用法一起写下来。

现象:工具表里少了一整族工具

那次执行记忆里的原文是这样的:

本次未取数、未写历史库、未出图,按硬性边界停在第一步之外(连交易日判断都没做成),等补跑。 根因:WorkBuddy 21:49 刚启动,[ConnectorMcpSnapshot] declarations=0(启动竞态),而 wind-finance 的 OAuth 续期直到 13:49:11Z 才 connection-ready;本会话 sidecar 在 13:49:07Z 就以 --mcp-config(runtimeMcpCount=7)一次性拉起,配置整个会话固定。

三个关键数字:declarations=0、会话拉起时刻 13:49:07Z、连接器 ready 时刻 13:49:11Z。差 4 秒。

排查:把"已排除"的路径记下来比找到答案更有用

那次最值钱的产出不是结论,是一份"别再试这些"的清单:

尝试过的补救路径结果
DeferExecuteTool 直呼名字不存在
本地代理 127.0.0.1:8625只有 26 个内建工具,无目标连接器
探测 /<hash>/mcp404
~/.workbuddy/mcp-tool-list.json存在但无用
~/.mcporter未安装
解 connectors/<uid>/.credentials.v3.jsonAES-256-GCM 加密,不要尝试解密

最后一条我特意抄进文章,因为它涉及安全边界:凭证是加密的,尝试解密既不合法也没必要。正确的做法是让上层重新建立连接。

定位:日志里有两行决定性的证据

真正的判断依据只有两行 grep:

bash
# 1. 当次会话的 MCP 声明数量
grep "ConnectorMcpSnapshot" "C:/Users/admin/.workbuddy/logs/daemon.log"

# 2. 会话拉起时实际注入的 server 数量
grep "runtimeMcpCount" "C:/Users/admin/.workbuddy/logs/daemon.log"

正常状态的输出长这样(我从 daemon.log 里摘的真实行):

json
{"timestamp":"2026-11-20T13:27:32.372Z","level":"info",
 "scope":"daemon-server:connector",
 "message":["[ConnectorMcpSnapshot] end marketplaceEntries=6 declarations=4 manifestMs=0 totalMs=0 slowEntries=[]"]}

declarations=4 是正常的。出问题那次是 declarations=0。而另一行:

json
{"scope":"daemon-server:WBDomain",
 "message":["[conversation-runtime] resolveMcpServers resolved",
   {"sessionId":"e23de2dc-...","totalDurationMs":18,"projectMcpCount":0,
    "runtimeMcpCount":13,"hasMcpConfigResolver":true,"mcpConfigJsonAttached":true}]}

runtimeMcpCount=13 说明这台机器平时能挂 13 个 server。出问题那次会话只有 7 个,且不含 wind-finance。

所以排查顺序应该反过来:先看这两行,再考虑别的。 我那次绕了快一个小时才回到这两行。

处置:不修旧会话,另开一个新会话补跑

一旦确认是"会话建立时快照已冻结",就不要再在当前会话里挣扎了。因为 --mcp-config 是一次性传给 sidecar 的,会话生命周期内不会重新 resolve。

我当时建了一个一次性补跑任务,指定 connectorIds=wind-finance:

text
补跑 id: 63c044fa-106f-409f-9d76-3b9824e33e78
触发时间: 22:25
判断依据: 新会话会重新 resolveMcpServers,此时 wind 已 ready,大概率能注入

结果成功了,当天读数正常出来:A股 48.16℃、港股 28.02℃,历史库 59/58 点。补跑记忆里第一句就是"全程 WIND(wind-finance 连接器),未换源"。

这条经验后来变成了通用规则:应用启动后 1~2 分钟内触发的自动化,财务类连接器可能拿不到。

另一类 MCP:不是连接失败,是"连上了但用错"

wind 那次是连不上。但我用的另一类 MCP 完全是另一种坑——连得上,但返回的东西不一定对。

比如同一次排查里发现的 QPS 限流:

WIND 有 QPS 限流:一条消息并行发 44 个 get_index_fundamentals,只有前 4 个成功,其余全报「每秒请求频率(QPS)超过限制」。必须串行 + 间隔 ≥1.3 秒。

还有更阴的一个:问句会被换成同名的其他指数。

text
801030.SI 基础化工  → 返回 882202.WI(20 年序列,maxseq 4856)
801740.SI 国防军工  → 返回 882102.WI
HSSCHKY.HI         → 返回 930915.CSI
801050.SI          → 返回 000819.SH(序号1/4828、分位0)

这些返回都是合法 JSON、都有数据、都不报错。只是不是你问的那个东西。

两类 MCP 的坑对比下来是这样的:

类型典型表现排查入口防线
连接型(declarations=0)工具名整个不存在ConnectorMcpSnapshot 日志另开会话,别在当前会话挣扎
语义型(返回错标的)有数据但口径不对返回值里的代码字段校验返回的代码 == 请求的代码

第二类的防线我封装成了固定句式:问句里必须带「Wind代码XXXXXX」并加「申万一级行业指数」前缀,拿到结果先核对返回行的代码与请求一致、日期等于今天,不一致就重问。

text
QPS 限流的另一个应对: 新建 fund_series.py
  - 串行请求(不是 Promise.all 一把梭)
  - 间隔 ≥ 1.3 秒
  - 命中 QPS 报错自动重试
  - 断点续跑(44 只跑一半挂了不用从头来)
  - 代码/序号双校验

复盘

三条:

  1. 连接失败先看两行日志,别先怀疑网络。declarations 和 runtimeMcpCount 能一句话定性。
  2. 会话级的 MCP 配置是冻结的。启动竞态导致的缺失,在当前会话内无法补救,直接新开会话。
  3. 连上了不等于对了。语义型 MCP 的校验成本必须内建到流程里,不能指望它自己报错。

还有一个尚未解决的问题:我没找到办法在自动化触发前"探活"连接器。现在的做法是让自动化自己在第一步检查工具表,缺了就直接退出并记一条记忆。这能止损,但不能自愈。下一步想试试提前 2 分钟起一个空会话预热,不过那要改调度逻辑,还没动手。