Moderator MCP Server

本地运行的 MCP Server，让用户在一个 Claude Code 会话中同时管理多个远程 AI 编码 Agent。

核心理念：讨论自由，执行受控。

Agent 之间可以自由讨论技术方案，但执行任何实际操作前必须经主持人（用户）批准。

详见 REQUIREMENT.txt。

它做什么

主持人（即用户本人）通过本地 Claude Code 的 6 个 MCP 工具管理远端 Agent：

完整的工具语义见 docs/glossary.md 和 docs/adr/。

Related MCP server: Agent Communication MCP Server

协作模型（速览）

主持人 = 用户本人，本地 Claude Code 会话中通过工具调用管理 Agent。拥有最终决策权。

Agent = 远程机器上独立运行的进程；通过四种结构化标记（marker）与系统交互。

四种 marker

详细协议见 ADR-0006（marker 协议）和 ADR-0007（写回协议）。

讨论 vs 执行

• 讨论（自由）：读文件、grep / cat / ls / git log / 只读 API。Agent 自由进行。

• 执行（需审批）：写文件、删文件、shell 命令、test / build / install、git commit、副作用 API 调用。Agent 必须发 【申请执行】 等批准。

边界原则：是否留下持久状态变更或对外部系统产生副作用。

Non-Claude Agents（软契约）

Moderator MCP Server 协议本身不依赖 Claude Code 的特定行为。任何满足以下最低要求的进程都可作为 Agent 接入：

1. 能读 stdin：服务器通过 stdin 发送 <moderator-…> 写回 tag。

2. 能写 stdout：Agent 通过 stdout 输出 marker。

3. 能保持长会话：进程不主动退出，除非收到停止信号。

4. 尊重 marker 语法：完整闭合 【…】…【/…】；嵌套 / 畸形时协议容错（详见 ADR-0010）。

5. 解析 writeback tag：能从 stdin 文本中提取 <moderator-approve> / <moderator-reject> / <moderator-cue> / <moderator-info> 并按 kind 分发。

v1 不做

• 不做 schema 强制：Agent 端解析由 Agent 自己负责，moderator 不验证。

• 不做适配器：Hermes / Gemini CLI / 自定义 Agent 脚本需自己解析 tag。docs/adr/0007-moderator-writeback-protocol.md 提供完整语法。

• 不做发现机制：Agent 启动需要 moderator 显式 start_session(name, host, ...) 拉起。

v2 候选

• mini-DSL for marker 协议：如果用户频繁接入新 Agent 类型，考虑提供 SDK。

• plugin 系统：把 marker / writeback 写成可注册的 schema。复杂度高，仅在明确需求时再做。

推荐的非 Claude 接入示例

任何能在 tmux 会话里跑的脚本都可以。例如：

# 简单 shell Agent：echo marker，read stdin
#!/bin/bash
while read -r line; do
  case "$line" in
    "<moderator-approve"*) echo "【进度汇报】收到批准，开始执行【/进度汇报】" ;;
    "<moderator-cue"*) echo "【进度汇报】收到 cue【/进度汇报】" ;;
  esac
done

更严肃的 Agent（Hermes / Aider / 自定义脚本）应按 ADR-0007 的语法解析。

安全声明

⚠️ state 文件和 role_prompt 是明文存储。可能包含 secret（API key、密码、个人信息）。

• state 文件：~/.moderator/moderator_state.json（用户可覆盖）。请按 secret-grade 资源保护（chmod 600 / Windows ACL）。

• role_prompt 路径：远端主机的 /tmp/moderator/role-<name>.txt，通常全局可读。

• 不适用于多用户机器：假设 moderator 是机器唯一用户。

• v1 不做加密：密钥管理是开放问题。详见 ADR-0012。

架构与设计文档

• 术语表：docs/glossary.md —— 系统的通用语言（角色、marker、审批、生命周期、横切关注点）。

• 架构决策记录：docs/adr/ —— 所有 ADR 按数字排列。每项决策的 Context / Decision / Consequences / Alternatives 都已记录。

必读 ADR

新贡献者建议按以下顺序阅读：

1. ADR-0001 —— 我们用 ADR（元模板）

2. ADR-0002 —— MCP 传输用 stdio

3. ADR-0003 —— 远端 Agent 机制

4. ADR-0004 —— 持久化

5. ADR-0005 —— 路由白名单 + 同名拒绝

6. ADR-0006 —— Marker 协议

7. ADR-0007 —— 写回协议

8. ADR-0008 —— Agent 生命周期

9. ADR-0009 —— 审批语义

10. ADR-0010 —— Marker 边界条件

11. ADR-0014 —— State schema v1 对账

12. ADR-0015 —— SSH 指纹 TOFU

13. ADR-0016 —— Schema 版本迁移

安装与启动

占位。v1 实施推进中。

# 占位
git clone <repo>
cd multi-agent-moderator-mcp
pip install -e .

启动后 moderator 在 Claude Code 会话里会看到 6 个工具可用：start_session / check / approve / reject / cue / stop_session。

状态文件

默认路径：~/.moderator/moderator_state.json（可通过环境变量覆盖）。

JSON 形态，包含 5 个顶层集合（agents / actions / chat / progress / help_requests），外加辅助字段（action_seq 计数器、seen_marker_hashes FIFO、schema_version）。详细 schema 见 ADR-0014（待写）。

审计导出

moderator state-inspect --format jsonl [--agent=<name>] [--since=<ts>]

详见 ADR-0013。

已知软肋（v1 显式不解决的）

开发

• M1–M8 实施：见主计划 ~/.claude/plans/requirement-txt-atomic-canyon.md。

• 设计文档同步：本 README 跟 docs/ 一起维护；改协议时先写 ADR 再改代码。

许可

待定。