MCP 生态这一年爆发式增长身边把 Claude Code、Cursor、Codex CLI 接到本机 MCP 服务上干活的人越来越多。察元的 MCP 目录一共 46 个文档工具工具一多报错种类看着就吓人但我维护部门这半年的经验是真正高频的错误码只有六个。把它们整理成一张表贴在工位上日常九成的求助都能自己消化。先上表错误码一句话含义第一反应动作WPS_AGENT_OFFLINEWPS 或加载项没连上 sidecar先打开 WPS随便开份文档DOCUMENT_TOO_LARGE文本超过约 80k 阈值改用 document_chunks 分块读LOCATE_MISMATCH / LOCATE_NOT_FOUND锚点校验失败或未找到重新 document_locate 拿新锚点LICENSE_REQUIRED免费额度用尽不弹购买窗可配自有模型MODEL_NOT_CONFIGURED校对模型未配置配好 OpenAI 兼容端点再跑CONFIRMATION_REQUIRED写操作缺 confirmed:true补参数重发这不是故障六个码按三类记背六个码有窍门按性质分三类。环境类两个WPS_AGENT_OFFLINE 和 MODEL_NOT_CONFIGURED都是上下文没就绪把 WPS 打开、把模型配好就消失。行为类两个CONFIRMATION_REQUIRED 和 LOCATE 系兄弟前者是确认机制拦你后者是锚点校验拦你同属设计如此的防御。额度与体量类两个LICENSE_REQUIRED 和 DOCUMENT_TOO_LARGE一个管配额一个管上下文长度。分类记住报错一眼就知道该动配置、补参数还是换读法。逐个展开WPS_AGENT_OFFLINE 出现频率最高。察元的架构是 MCP 服务常驻本机但真正操作文档的桥接要靠 WPS 加载项WPS 没开、或者加载项没被加载46 个文档工具就集体失联。处置顺序是先把 WPS 打开不行就检查加载项是否落在 jsaddons 目录、publish.xml 注册是否正常再不行让外部 Agent 调 wps_launch 冷启动。4.1.2 之后 sidecar 全面隐藏启动且 Spike 掉线自愈这类报错肉眼可见地少了。DOCUMENT_TOO_LARGE 是长文档必经之路。document_get_text 对超过约 80k 字符的文档会拒绝整篇返回这是对模型上下文的保护。正确做法是换 document_chunks 带 cursor 和 limit 分页读必要时也可以 force:true 强制整篇但一般不建议Token 花得肉疼还容易把关键内容稀释在长上下文里。LOCATE_MISMATCH 和 LOCATE_NOT_FOUND 是写回环节的守门员。文档是有生命的你在读和写之间正文可能已经变了锚点对不上时工具宁可报错也不乱写。遇到就重新 document_locate 定位拿最新锚点再执行写回。这个较真的设计救过我好几回尤其是批注钉错字这种要求位置精确的场景。LICENSE_REQUIRED 最容易引起误会免费额度用尽时报它而且不弹购买窗进程安静地失败日志里才看得到。处置要么等额度恢复要么在配置里接自己的模型Ollama、LM Studio、Xinference、OneAPI 这些 OpenAI 兼容端点都行内网部署也顺。MODEL_NOT_CONFIGURED 顾名思义校对类工具依赖校对模型模型没配就先去配配完再跑 proofread_run。这个码友好在它把你还没配模型和模型配错了区分开了照着提示走就行。CONFIRMATION_REQUIRED 严格说不算错误是确认策略。document_add_comment、proofread_apply_comments、declassify_apply 这些写操作必须显式传 confirmed:true 才落盘第一次调用返回这个码是设计使然补参数重发即可。document_replace、document_insert、document_apply_ops 未带确认时则返回 preview 不写盘一个道理。排错三板斧第一斧打健康检查浏览器或终端访问http://127.0.0.1:62588/healthz返回 online 说明服务活着问题在下游。第二斧让 Agent 调 wps_status它是分层健康检查服务、加载项、桥接逐层看比瞎猜快得多。第三斧用 MCP Inspector 直连验证npx modelcontextprotocol/inspector选 Streamable HTTP 填地址点 Connect工具列表能枚举出来就说明链路通问题在提示词或参数。校对这类长任务还有异步路线proofread_run 发出去之后用 proofread_job_poll 轮询结果批量处理成套文档时不用干等一个会话编排起来顺手得多。顺手一条好习惯排错之外日常用建议养成先预览后写回的习惯直接把这句丢给 Agent先跑一遍校对dryRun汇总问题列表不要先改正文我确认后再写成批注dryRun 默认只返回问题清单你过目之后才让 proofread_apply_comments 落成批注既避开误写也少踩 CONFIRMATION_REQUIRED 的来回。这张速查适合三类人刚把 Claude Code 或 Cursor 接上察元的新手、替同事装机后负责答疑的接口人、以及想在内网挂一页排错 FAQ 的信息科同事。最后照例说边界校对结果是辅助参考最终改不改、怎么改仍以人工定稿为准。这张表建议收藏下次报错先对表再决定要不要喊人。