Skip to main content

MCP 服务器

梳理 MoAI-ADK 自带的 moai mcp-server(stdio 本地 MCP 服务器)的配置、工具目录、认证和延迟加载策略。

更新 2026-10-29 16 分钟阅读 在 GitHub 上编辑 ↗

MCP 服务器

MoAI-ADK 在 Claude Code 的 MCP 生态之上,又叠加了一个自有的 MCP 服务器。一个二进制文件(moai mcp-server)以 stdio 本地服务器的方式运行,向 Claude Code 运行时暴露 MoAI-ADK 独有的工具——SPEC 生命周期审计、验证快照、目标引擎、跨模型审计、codex·GLM 委托等。

两份 MCP 文档的关系

Claude Code 通用 MCP 讲的是平台自身的 MCP(Model Context Protocol)集成——USB 端口比喻、服务器注册、传输类型、/mcp 命令、OAuth 认证、延迟加载原理。

本文档讲的是叠加在其上的 MoAI 自有 MCP 服务器。两个表面共享相同的核心规则,但所讨论的主体不同。

同一个核心,两个表面

Claude Code 的 MCP 生态与 MoAI 的自有 MCP 服务器是各自独立的服务器,但都建立在相同的运用原则之上。它们共享三条核心规则。

核心规则含义
MCP-over-CLI同一功能同时以 CLI 和 MCP 工具暴露,但当智能体的 tools: 列表中存在 MCP 工具时优先使用 MCP。优势在于结构化输出、规避 shell-quoting、在子智能体中低延迟。
延迟加载MCP 工具定义默认延迟加载。平时只将简短的元数据留在上下文中,实际调用时再用 ToolSearch 加载 schema。
权限门MCP 工具与 Claude 的通用工具一样需通过相同的权限门。首次调用时审批提示出现在主会话,放行后同一工具不再询问。
flowchart TD
    CC["Claude Code 运行时
(工具权限 · 延迟加载 · 审批)"] CMCP["通用 MCP 服务器
(context7, chrome-devtools, …)"] MMCP["moai mcp-server
(MoAI 自有工具)"] CC --> CMCP CC --> MMCP MMCP --> TOOLS["SPEC lifecycle · 验证 · 目标 · 审计 · codex/GLM 委托"] CMCP --> EXT["外部工具 (库文档 · 浏览器自动化 · …)"]

关键在于,“MoAI 不配置 MCP"是一个半真半假的说法。不默认配置外部 MCP 服务器(context7、playwright 等)是对的。但 MoAI 自有的那个服务器在 moai init 时就会以 default-on 装上。这个服务器正是 MoAI 的工具目录触达 Claude Code 的通道。

.mcp.json 配置

moai init 在项目根目录创建 .mcp.json(project scope),在里面建立恰好一个活跃条目——自有的 moai 本地 stdio 服务器。

json
{
  "mcpServers": {
    "moai": {
      "command": "moai",
      "args": ["mcp-server"]
    }
  },
  "staggeredStartup": {
    "enabled": true,
    "delayMs": 500,
    "connectionTimeout": 15000
  }
}

staggeredStartup 是 Claude Code 运行时字段,用来调节服务器顺序启动。当服务器有多个时,它能防止同时启动的竞争(race)。

五个 documented-but-disabled 条目

部署默认值只有 moai 一个服务器处于活跃状态。五个外部服务器已写入文档但处于禁用状态,用 moai mcp add <名称> 命令来开启。

服务器用途激活方式
context7查询最新库的官方文档(resolve-library-id, get-library-docs)moai mcp add context7
chrome-devtools无头浏览器自动化moai mcp add chrome-devtools
playwright浏览器自动化 + E2E 测试moai mcp add playwright
ast-grep结构化代码搜索和重构moai mcp add ast-grep
aside在已登录浏览器中工作的可选浏览器代理(exec, repl)moai mcp add aside --command aside --args mcp --scope user

aside 是可选项。它不在默认配置里,任何工作流也不以它为前提。要为所有项目注册,运行 moai mcp add aside --command aside --args mcp --scope user;只想注册到当前项目,就去掉 --scope user。aside mcp 提供两个工具:exec 在已登录的网站上运行浏览器代理,repl 对已打开的页面执行 Playwright 风格的 JavaScript。由于它在操作者自己已登录的浏览器里工作,MoAI 默认只读使用,且不使用 --permission full-access。aside repl 没有权限标志,所以 REPL 的只读使用是一条操作规则,而不是工具本身强制执行的限制。任何会改变状态的步骤都需要操作者明确确认,而这一确认只由 MoAI 编排器(绝不是子智能体)发起并执行。MoAI 不会安装 Aside;如需添加 Aside 自带的浏览器技能,由操作者自己运行 aside skills install。在 E2E 工作流中,只有明确传入 /moai e2e --tool aside 时才会用到 Aside(CI=true 时不可用),Aside 不存在时,工作流会不作任何提示地继续使用平台默认工具链。

中立性契约

.mcp.json 是 git-tracked 文件。因此"搭载秘密的条目、需要凭证的条目、未通过中立性检查的条目"是禁止的。所有环境变量的值都以 ${VAR} 字面量写入——Claude Code 运行时扩展实际值,被解释的秘密不会被序列化到 git-tracked 的 .mcp.json 中。

json
{
  "remote-needs-auth": {
    "type": "http",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "Authorization": "Bearer ${MY_API_KEY}"
    }
  }
}

${MY_API_KEY} 由运行时从环境变量中填充。文件本身只保留字面量字符串,所以秘密不会暴露到存储库中。

atomic-RWM 管理

用户不直接手编 .mcp.json。moai mcp add|remove|list CLI 管理该文件,且此 CLI 通过 atomic-RWM seam(flock 文件锁 + compare-retry + 备份后写入 + idempotent-skip)运作。即使两个会话同时编辑,也不会让一边的变更覆盖另一边。

project_root 输入——由调用方指名自己的树

33 个工具接受可选的字符串 project_root:spec_progress、spec_audit、spec_drift、verify_snapshot、verify_trend、codex_audit、codex_review、glm_audit、glm_review、claude_audit、audit_multi、graph_file_api、graph_find_code、graph_shortest_path、graph_trace_calls、factory_decide、todo_add、todo_list、factory_next、factory_stage、factory_complete、factory_renew、audit_cache、glm_job_cancel、glm_job_result、glm_job_status、glm_task、goal_arm、goal_status、jev_ask、fetch_web、session_list、todo_claim。它指明这次调用应当作用的树,要传的值就是调用方自己的 git rev-parse --show-toplevel。不过在 factory_next、factory_stage、factory_complete、factory_renew 上它不是可选而是必填——不传自己的 toplevel 调用就会被拒绝,也不会默认到任何树。

在 worktree 里工作的智能体必须传它。这不是图方便的功能。服务器没有办法自行推出答案:它是一个长寿的子进程,工作目录跟不上 worktree 的切换,而它退而依赖的环境变量指向的是项目根目录——也就是 primary 检出——即便会话正在 worktree 中工作也是如此。在 worktree 里省掉它,调用就会作用到 primary 检出上,于是只存在于卡片分支上的 SPEC 不会进入审计者读取的目录。它也不会被报告为缺失。它只是不存在。

握有答案的只有调用方。这正是它作为输入、而非由服务器推断的原因。

情形传什么结果
worktree 中的会话project_root: <git rev-parse --show-toplevel>调用作用于该树
primary 检出中的会话不传与以往完全一致地解析
不用 git 跟踪 .moai 的仓库的链接 worktree(worktree 自身没有 .moai)project_root: <git rev-parse --show-toplevel>若 git 将其登记为某个带 .moai 的 primary 检出的 worktree,则予以接受,调用作用于该 worktree
并非 MoAI 项目根的路径—调用被拒绝,错误信息中写明该路径

拒绝是刻意的设计,而不是毛边。若悄悄回退到默认值,就会把打错自己 worktree 路径的调用方送回去审计 primary 检出,还告诉它成功了——正是这个参数要防止的那种失败。

如果仓库把 .moai 放在 git 之外,链接 worktree 里就没有 .moai,但仍会被接受。条件有两个:路径必须是 git worktree list 中登记的 worktree 的顶层目录,且仓库的 primary 检出中有 .moai。子目录、未登记或可清理(prunable)的 worktree、独立 git 目录这类结构不明确的布局,以及无法使用 git 的环境,都会被拒绝。这类 worktree 若没有自己的 workflow 配置,显式审计关卡(workflow.audit.gates)从 primary 检出读取;无法确定 primary 时,关卡按 required 处理,也就是说缺少判定时结果是失败而不是通过。SPEC 目录(spec_progress、spec_drift、spec_audit)基于 worktree 与 primary 检出两边 .moai/specs 的并集作答,每条记录和发现项都标明来源(worktree 或 primary);同一 SPEC ID 两边都有时,只按 worktree 那份计一次,并在响应中指出被遮蔽的 primary 副本。审计回执、审计者启动标记与拒绝记录、audit_multi 收敛判定、verify_snapshot 快照等状态保存在 primary 检出的 .moai/state 中,并附上 worktree 自己的树标识,因此多棵树共用一个存储也不会互相覆盖记录;实际读取了哪些来源,由 _root.worktree_warning 和 _root.sources 说明。无法确定 primary 检出时,状态写入不会改写到别处,而是直接报错(尽力而为的写入会被跳过,并以通知说明);目录只读取 worktree,并在 _root 中写明未读取 primary 的原因。此时审计关卡按 required 处理,所以即使仓库从未启用该关卡,从这个 worktree 发起的阶段入口派生也会被拒绝;要解除,可让 primary 变得可识别,或在 worktree 中放置它自己的 .moai/config/sections/workflow.yaml。

在 audit_multi 中,根会到达 fan-out 的两个后端:codex 把它作为执行审查的工作目录,GLM 路径则用它从那棵树上取出要发往 z.ai 的 diff。传这个值,才能让两份第二意见针对同一棵树——不传,它们可能看的是不同的树。

版本提醒:已经在运行的服务器,即使替换了其下的二进制,在重启前仍保持旧行为——子进程不会自行重新加载。调用方可以检查的是 ListTools 的响应中是否出现 project_root。

工具目录

下面按类别整理 moai mcp-server 暴露的工具。调用时都带 mcp__moai__ 前缀。本页不写工具数量。工具数量与列表以已安装二进制通过 tools/list 返回的列表为准,整理该列表的文档是 .claude/rules/moai/core/moai-mcp-tools.md;二者与本页不一致时,以它们为准。

SPEC 生命周期

工具目的消费智能体CLI 等价物
mcp__moai__spec_progressSPEC 文档列表 + frontmatter 查询manager-spec, manager-docs—
mcp__moai__spec_auditSPEC 生命周期审计(时代分类 + 漂移)manager-spec, manager-docs, plan-auditor, super-advisormoai spec audit
mcp__moai__spec_drift现代时代 V3R6 漂移发现manager-spec, plan-auditormoai spec audit (drift 视图)

用于 plan-phase(manager-spec 编写新 SPEC 时确认时代分类和漂移)与 sync-phase(manager-docs 验证生命周期终结)。plan-auditor 用 spec_audit / spec_drift 执行 plan-phase 的怀疑式审查。

验证快照

工具目的消费智能体CLI 等价物
mcp__moai__verify_snapshot按键读取/记录验证快照manager-developmoai verify check
mcp__moai__verify_trend按键验证历史趋势manager-develop, sync-auditor, super-advisormoai verify check

manager-develop 在 run-phase 自验证(接缝 §E)中使用,sync-auditor 和 super-advisor 用于审查趋势。verify_snapshot 读取或记录以 HEAD 摘要为键的快照,verify_trend 展示用于判断收敛的历史。

目标 + 会话(自治循环)

工具目的消费智能体CLI 等价物
mcp__moai__goal_arm条件声明目标武装编排器主会话专用(未连线到任何智能体)moai goal arm / /moai goal
mcp__moai__goal_status读取已武装的目标状态manager-develop, manager-leadmoai goal status
mcp__moai__session_list活跃 moai 会话列表manager-leadmoai session list

goal_arm 是编排器专用的——自治循环武装是编排器关注的事,所以不在智能体内调用。这是为了保留平面层级武装表面而做的设计。goal_status 是 manager-develop / manager-lead 读取已武装条件进度的通道,session_list 是 manager-lead 在 fan-out 前检测同一检出上并发会话的竞争缓解手段。

跨模型审计(第二意见)

工具目的消费智能体CLI 等价物
mcp__moai__audit_multi多审计者收敛(claude + codex + glm)plan-auditor, sync-auditor—(MCP 专用收敛入口)
mcp__moai__claude_auditClaude 订阅后端单独审计(claude -p,只读隔离,结构化输出)plan-auditor, sync-auditor;在 GPT/GLM 会话中由 audit_multi 自动调用—
mcp__moai__codex_auditcodex 后端单一审计(原生/对抗式)plan-auditor, sync-auditor—
mcp__moai__glm_auditGLM (z.ai) 后端单一审计plan-auditor, sync-auditor—
mcp__moai__audit_cacheplan-audit PASS 缓存(compute_hash / lookup / store,进程间共享)sync-auditor—

单一后端审计模式由项目的 audit_model 设置决定:codex+glm(默认值,通过 audit_multi 收敛)| glm | codex | none(Claude 独自,无后端调用)。所有后端都是 fail-open——不可用的后端返回 inconclusive,而非 Go error。

按需自我评审(仅供参考)

工具目的消费智能体CLI 等价物
mcp__moai__codex_review让 codex 评审调用方自己的改动——scope: card(卡片 diff)或 scope: uncommitted主会话,以及在自己的 tools: 列表中列出该工具的智能体moai verify codex-review(仅 codex 一侧)
mcp__moai__glm_review把调用方自己的改动整理成 diff,请 GLM (z.ai) 评审主会话,以及在自己的 tools: 列表中列出该工具的智能体—

这两个工具都不是审计工具。结果仅供参考,不具约束力:advisory 恒为 true,既不生成也不读取审计回执,也不会被 workflow.audit.gates.* 的 required 转换改写(评审方缺席时得到的是 inconclusive,而不是 fail)。审计模型的固定设置同样不适用,所以 model 要么是调用方传入的值,要么是后端的默认值。scope 必填,没有默认值。card 通过与回合结束评审门相同的范围解析器确定卡片 diff,每次调用都会重新计算合并基线;不是卡片工作树的树会直接返回 inconclusive,不会评审任何内容。uncommitted 评审指定树中尚未提交的改动;在 primary 检出中,对象是整个共享工作树,且不支持按路径限定。每个结果都带有 scope、base(card 时为合并基线的 SHA,其余情况为空字符串)、backend 和 tree(实际评审的规范化根目录)。

GLM 没有文件系统,所以请求中携带的是排除了运行时管理路径的 diff。未被跟踪的文件无法放进 diff,会列在 excluded_untracked 中;diff 在大小上限处被截断时会置位 truncated;diff 为空时两个后端都不会被调用。调用是同步的,在评审预算之内结束,也不发送进度通知。在这些工具出现之前启动的服务器进程看不到它们,请重新连接服务器。在此期间,codex 一侧可以改用 moai verify codex-review --project-root <树>,GLM 一侧没有替代办法。

codex 委托(后台任务)

工具目的消费智能体CLI 等价物
mcp__moai__codex_setup探测本地 codex 安装(LookPath + 版本 + 认证)super-advisor—

通用 codex 委托工具族(codex_task、codex_job_status / codex_job_result / codex_job_cancel)已移除;codex_setup 作为审计面的安装探针保留,连线到按需高推理咨询智能体 super-advisor。codex 是可选的(optional)——缺失或不可用时返回 fail-open 的 inconclusive,而非 hard error。

codex 只读角色

工具用途使用方CLI 等价
mcp__moai__codex_role_audit以顶层 codex exec 进程启动一个只读角色(只读沙箱,禁用全部 MCP 服务器),立即返回任务 IDCodex 会话—
mcp__moai__codex_role_audit_status读取角色任务的状态与时间戳Codex 会话—
mcp__moai__codex_role_audit_result读取已结束角色任务的退出码、返回文本或判定书路径,以及启动记录路径Codex 会话—

Codex 会话通过这组工具而不是 spawn_agent 启动 plan-auditor、sync-auditor 等只读角色。Codex 会话的 shell 中嵌套的 codex exec 无法访问模型,因此没有 CLI 等价物。任务存在于服务器进程中,随进程结束而结束。

GLM 委托(后台任务)

工具目的消费智能体CLI 等价物
mcp__moai__glm_task把任务(任意提示词)委托给 GLM(z.ai)(同步或后台)manager-develop, super-advisor—(无对应 CLI)
mcp__moai__glm_job_status读取后台 GLM 任务的状态/记录manager-develop, super-advisor—
mcp__moai__glm_job_result读取后台 GLM 任务的输出manager-develop, super-advisor—
mcp__moai__glm_job_cancel中断正在运行的后台 GLM 任务manager-develop, super-advisor—

GLM 委托工具族与 codex 委托同形,连线到 super-advisor 和 manager-develop。manager-develop 持有整个工具族,仅在 run 工作流的 External Model Delegation 一节所允许的范围内,才用 glm_task 委托范围有限的机械性子任务;GLM 任务会把提示词发送给外部提供方。glm_task 在 background 为假时直接返回完成的文本,为真时立即返回任务 ID(此后用 glm_job_status·glm_job_result·glm_job_cancel 观察·中断)。响应 token 上限可用 max_tokens 覆盖,默认上限值定在服务器一侧。后台任务活在服务器进程里,进程结束它也一并结束。GLM 同样是可选的——密钥缺失或连不上 z.ai 时,只返回结构化的 fail-open 结果,而不是工具错误。

代码查询

工具用途使用方CLI 等价
mcp__moai__graph_file_api列出单个源文件的导出声明及其签名(不含函数体)所有代理—
mcp__moai__graph_find_code在由代码生成的边层中查找符号的调用点与调用者(每条边附带解析置信度)所有代理—
mcp__moai__graph_trace_calls从某个符号出发,沿调用者与被调用者方向追踪调用边,直到指定深度所有代理—
mcp__moai__graph_shortest_path两个符号之间的最短调用路径(最多 8 跳,每跳附带行号与置信度)所有代理—

每个回答都注明计算所依据的树根与提交。边层即 moai graph build 生成的 edges.jsonl。

判断(受门控,仅供展示)

工具用途使用方CLI 等价
mcp__moai__jev_ask针对给定的一个状态提出类型化问题,得到带概率的回答发布默认值(workflow.jev.enabled: false)下不可用—(仅 MCP)

该工具始终注册,但门控关闭时既不构造请求,也不发起网络调用。回答是供人阅读的参考信号,其本身不会成为完成判定、合并批准或队列变更。即使被自动使用,也只作为信号 — 例如 moai todo --auto 查看待办卡片的顺序,或只能确认或移交给人的可选启动交叉验证。

MCP-over-CLI 规则

当智能体的 tools: 列表中存在 MCP 工具时优先走 MCP 路径而非 CLI。两条路径在后台跑的是同一套实现。MCP 路径的优势有三:

  • 返回结构化输出(无需解析)
  • 避开 shell-quoting 风险
  • 在 Bash 可能受限的子智能体环境中以低延迟运作

CLI 仅在 MCP 工具不在 tools: 列表中,或在主会话中 CLI 形态更自然时使用。

认证

GLM (z.ai)

在 GLM 会话(moai glm)中运行时,网络搜索和网络查询会路由到 z.ai MCP 工具,而非内置的 WebSearch / WebFetch。认证从 ~/.moai/.env.glm 读取。

z.ai MCP 服务器(zai-mcp-server、web_search_prime、web_reader)默认禁用,在 GLM 会话中用 moai glm tools enable 开启。GLM 会话中的路由规则请参考多 LLM 后端。

codex

codex 审计/委托工具(codex_audit、codex_task 等)从 ~/.codex/auth.json 读取认证凭证。codex 是可选的——认证文件不存在或 codex 未安装时,相关工具返回 inconclusive 并继续。这是智能体工作不依赖于 codex 可用性的设计。

所有后端都 fail-open

GLM、codex、Claude——三个后端都遵循 fail-open 原则。不可用的后端只会返回 inconclusive,不会引发 Go error。即使一个后端缺失,其余后端也能让审计收敛;如果所有后端都不可用,则以 Claude 独自运作(audit_model: none)。

后台任务进度跟踪

codex·GLM 委托工具中的 codex_task 和 glm_task 可以用 background: true 启动后台任务。此时不等待任务结束就立即返回任务 ID。

进度通过两个工具来轮询(下面以 codex 为例——GLM 由 glm_job_* 扮演同样角色):

text
codex_task(background=true) ──▶ 返回任务 ID
       │
       ├── codex_job_status(任务 ID) ──▶ 运行中 / 完成 / 失败
       │
       └── codex_job_result(任务 ID) ──▶ 完成时读取输出

需要时 codex_job_cancel(任务 ID) ──▶ 中断

可以在 MCP 控制台(Web 控制台)中查看各工具的设置和认证状态。控制台的详细功能请参考 Web 控制台。

延迟加载与 ToolSearch

MoAI 自有 MCP 服务器也和 Claude Code 通用 MCP 一样遵循延迟加载原则。如果把工具定义全部常驻加载到上下文中,上下文窗口会很快填满,因此平时只放简短的元数据,在实际调用时才加载 schema。

要调用延迟工具,必须先用 ToolSearch 将 schema 加载到活动上下文中。

text
需要工具了 ──▶ {schema 在上下文中吗?}
                   │
            ┌──────┴──────┐
            否              是
            │               │
    先用 ToolSearch         调用工具
    加载 schema
            │
            └──▶ 调用工具

跳过此步骤,工具调用会因验证错误而被拒绝。延迟加载原理的背景说明请参考 Claude Code 通用 MCP 文档的"延迟加载与 Tool Search"一节。

相关文档

  • Claude Code 通用 MCP — 平台自身的 MCP 集成(USB 端口比喻、服务器注册、传输类型、/mcp 命令)
  • 多 LLM 后端 — Claude × GLM 多后端运用 · GLM 会话中网络搜索/查询路由到 z.ai MCP 工具的规则
  • 跨模型审计 — 多审计者收敛机制
  • Web 控制台 — MCP 工具设置与认证表面