MCP 服务器

ADHDev 提供了一个 MCP stdio 服务器，让外部 MCP 客户端可以把 ADHDev 会话当作工具使用。该服务器以 @adhdev/mcp-server 发布，也被主云 CLI 包装为 adhdev mcp。

当你想让诸如 Claude Desktop 之类的 MCP 客户端列出活动的 ADHDev 会话、读取聊天历史、发送消息或批准一个等待中的提示时，请使用它。在 mesh 模式下，它会成为完整的 Repo Mesh 协调者工具界面。

模式

模式	MCP 服务器使用的传输	工具
本地 standalone	http://localhost:3847 standalone API	基础 15 个工具 + screenshot + 3 个 mesh 引导工具（共 19 个）
IPC	localhost:19222 处的云守护进程本地 IPC	相同的基础 15 个工具 + 3 个 mesh 引导工具，不含 screenshot（共 18 个）
Mesh	本地或 IPC + --repo-mesh <id>	协调者范围的工具集 — 见下方 Mesh 工具
Worker	本地或 IPC + --worker	极简的被委派工作者工具集：report_completion、progress_update、peer_context_pull、git_status、git_log、git_diff（共 6 个工具）

本地模式是 OSS/自托管界面的一部分。有关 standalone 设置和认证详情，请使用 OSS 文档：

• Self-hosted Setup
• Self-hosted Local API

启动服务器

# 本地模式：需要一个正在运行的 standalone 守护进程
adhdev mcp
adhdev mcp --port 4000
adhdev mcp --password my-standalone-password

你也可以直接运行 OSS 包：

npx @adhdev/mcp-server
npx @adhdev/mcp-server --mode ipc --repo-mesh mesh_abc123

也支持环境变量：

ADHDEV_PASSWORD=my-standalone-password adhdev mcp
ADHDEV_MESH_ID=mesh_abc123 adhdev mcp

Claude Desktop 配置

{
  "mcpServers": {
    "adhdev": {
      "command": "adhdev",
      "args": ["mcp"]
    }
  }
}

Mesh 模式（协调者范围工具）：

{
  "mcpServers": {
    "adhdev-mesh": {
      "command": "adhdev",
      "args": ["mcp", "--mode", "ipc", "--repo-mesh", "mesh_abc123"]
    }
  }
}

标准模式工具

标准模式（不带 --repo-mesh）在直接会话控制界面之外，还额外暴露三个 mesh 引导工具，让纯 MCP 代理能够在 mesh 尚不存在时先创建一个。

会话与守护进程

• list_daemons —— 报告已连接守护进程的身份。
• list_sessions —— 发现某个守护进程上可用的会话。
• launch_session / stop_session —— 管理 CLI/IDE 代理生命周期。
• check_pending —— 列出等待批准的会话。

聊天与批准

• read_chat —— 读取所选会话的最近聊天。
• read_chat_debug —— 所选会话聊天状态的有界调试包。
• spec_debug —— 供应商 spec 解析调试辅助工具。
• send_chat —— 向所选会话发送消息。
• approve —— 批准或拒绝一个批准提示。

Git

• git_status、git_diff、git_log、git_checkpoint、git_push —— 管理工作区 git 操作。

仅限本地

• screenshot —— 通过守护进程捕获当前 IDE 窗口。需要 P2P/本地守护进程访问，因此只在本地模式下可用，IPC 模式不可用。

Mesh 引导（本地和 IPC 标准模式下均可用 —— 这是尚无 mesh 时的路径）

• mesh_create —— 创建一个新 mesh，可选地将当前工作区注册为其第一个节点。以 mode: "plan" 调用时，它是只读 dry-run：仅提议创建/加入 mesh 会做什么，不写入任何内容——请先运行它。
• mesh_add_node —— 将一个已存在的工作区注册为某个已存在 mesh 的节点。

一旦 mesh 存在，用 --repo-mesh <mesh_id> 重新注册 MCP 服务器即可切换到 mesh 模式，解锁下方完整的协调者工具集 —— mesh 模式是完全替换工具界面，而不是在其基础上追加。

Mesh 工具

Mesh 工具仅在 mesh 模式（--repo-mesh）中可用。它们用一套协调者范围的工具集替换标准工具。

名称与数量的权威来源

本页按工具族分组介绍，用于导览。准确的名称、当前数量及完整的输入 schema 的权威列表，是 oss/packages/mcp-server/src/tools/mesh-tool-schemas.ts 中的 ALL_MESH_TOOLS。如果下方列表与代码有出入，以代码为准 —— 这份列表过去曾经过时。

状态与检查

• mesh_status —— 聚合快照：所有节点的健康状况、git 状态、活动会话、恢复提示，以及按守护进程的构建/陈旧信息。
• mesh_list_nodes —— 基于 mesh 配置的轻量节点清单：每个节点的工作区路径、机器身份、节点策略和能力（不含实时 git 或会话——那些看 mesh_status）。
• mesh_read_chat —— 读取某个被委派代理的聊天历史。
• mesh_read_debug —— 某个被委派会话的有界调试包。
• mesh_read_terminal —— 读取某个被委派会话当前的原始 PTY 视口（人类此刻在屏幕上会看到的内容）。
• mesh_git_status —— 获取某个节点工作区的 git 状态。
• mesh_read_node_logs —— 对某个节点的守护进程日志文件做 grep（整个文件，而非仅末尾）。
• mesh_task_history —— mesh 账本：任务、完成、失败、检查点、节点与任务组生命周期；可按 kind（单个或逗号分隔列表）、since 和 node 过滤，返回最新的 tail 条。
• mesh_ledger_query —— mesh_task_history 的已弃用别名（见已弃用别名）。
• mesh_review_inbox —— 等待协调者的待审查/待批准项。
• mesh_list_pending_approvals —— 整个 mesh 中当前等待批准决定的所有会话列表。
• mesh_route_preview —— 基于当前内存中的 mesh/队列/配额事实快照，只读且不发起任何请求地预览一个假设任务会被路由到哪里、为什么（容量优先顺序、难度下限、适配度组成部分、配额加成、门控结果）。不会入队、写入、探测 CLI 或刷新配额。

分派、会话与控制

• mesh_send_task —— 直接向某个被委派代理会话发送自然语言任务。
• mesh_launch_session —— 在某个 mesh 节点上启动新的代理会话。
• mesh_send_keys —— 向某个被委派的工作者会话注入结构化的按键序列。
• mesh_restart_daemon —— 重启某个 mesh 节点的守护进程。
• mesh_approve —— 批准/拒绝某个被委派代理上的待处理操作。
• mesh_answer_question —— 回答某个被委派会话正在等待的多选问题（AskUserQuestion）。
• mesh_checkpoint —— 在某个节点工作区上创建 git 检查点。
• mesh_cleanup_sessions —— 停止/清理某个节点上陈旧或孤立的被委派会话；mode: "prune_stale_direct" 则改为清理整个 mesh 中陈旧的直接分派记录（除非 execute: true，否则为 dry-run）。

工作队列与任务群

• mesh_enqueue_task —— 把一个由空闲节点自主认领的任务入队（支持 target_node_id / prefer_worktree 路由、task_mode、mission_id、depends_on，以及一个可选的 owned_paths 声明，使 mesh 中其他地方与之重叠的 code_change 任务在认领时被拒绝，而不是与之竞争）。用 depends_on 把新任务串接到已有任务上，是构建多步骤计划的默认方式 —— 每当发现新的工作，计划就会一次增加一条链接。带有 depends_on 的任务会自动收到一份 "Upstream results" 附录，总结其前置任务完成时报告的内容。
• mesh_enqueue_batch —— 在一次调用中原子性地把多个任务（及其 depends_on 关系）入队，只要其中任意一项无效，整个批次都会回滚。它是为步骤已经确认好的计划提供的便利工具 —— 不是串接任务的默认方式（参见上方的 mesh_enqueue_task）。
• mesh_view_queue —— 当前活动工作的权威来源（pending/assigned/terminal）。
• mesh_queue_cancel / mesh_queue_requeue —— 取消或重新入队一个已排队的任务。
• mesh_mission_upsert —— 创建/更新一个任务群（目标分组 + 生命周期状态）。
• mesh_mission_list —— 列出任务群及其目标、状态和实时任务进度（总数/待处理/已分配/已完成/失败）。
• mesh_reconcile_ledger —— 根据对等方的有界切片对齐本地账本。
• mesh_note —— action: "record" / "forget"：记录或撤回一条未来协调者会继承的持久运营笔记。

引导与配置（mesh 模式；与上方标准模式的两件套引导工具不同）

• mesh_init —— 面向已有 git 项目的一键引导：检测已安装的 CLI 供应商，并提议仓库的三类 .adhdev/* 配置（Refinery、worktree bootstrap、change-impact）。默认是预览；write: true 时才会应用。 mode: "reinit" 是面向已初始化仓库的同一操作，overwrite 默认为 true，并返回当前值与建议值的 diff。
• mesh_config —— 按 kind 选择的仓库配置辅助工具。kind: "refine" 和 kind: "change_impact" 是只读辅助，用 mode（schema / validate / suggest）选择操作；kind: "mesh_json" 根据本机的 mesh 条目写入提交到仓库的 .adhdev/mesh.json（除非 write: true，否则为 dry-run）。见下方已退役的工具名。

节点

• mesh_clone_node —— 把一个节点克隆为一个隔离的 git 工作树节点。
• mesh_remove_node —— 移除一个（工作树）节点，可选地清理会话。
• mesh_cleanup_worktree_nodes —— 对已证明分支已合并/已推送、且通过所有安全排除条件的、已收敛的本地工作树节点，规划（默认 dry-run）或执行安全移除。
• mesh_fast_forward_node —— 默认安全地 dry-run，或显式执行一次明确的干净 fast-forward，而不启动代理会话；仅使用 fetch/recheck、merge --ff-only、可选的子模块更新和后续状态验证。

Refinery（工作树 → 基线收敛）

• mesh_refine_node / mesh_refine_batch —— 把一个或多个工作树分支收敛回基础分支（验证 → 合并 → 推送 → 清理）。两者默认只预览计划，直到传入 execute: true 才会执行。

节点槽位（供应商/模型/思考级别路由）

• mesh_node_slots —— 按 action 操作节点的槽位列表（把供应商/模型/思考级别绑定到难度类别）：list 列出当前槽位；set 提议（dry-run）或应用槽位列表；propose 是只读的自动检测，探测节点上已安装的 CLI 智能体并据此起草能力槽位配置（"直接允许、由它自己算出槽位"的路径）。propose 绝不会写入——审核后用 mesh_node_slots({ action: "set", node_id, slots: proposedSlots, write: true }) 应用草案，因为槽位写入是整体替换，可能丢弃手动调整过的槽位。

Worker 模式

adhdev mcp --mode ipc --worker 启动的是 Repo Mesh 工作者会话所使用的极简被委派工作者工具集（mesh 协调者把任务分派给其他代理会话，这些会话充当工作者）。这种模式通常由守护进程自身在启动一个工作者会话时自动启动，而不是你手动运行的东西 —— 工作者进程需要守护进程提供的会话绑定（ADHDEV_WORKER_SESSION_BIND）或任务令牌（ADHDEV_WORKER_TASK_TOKEN）。--worker 会覆盖 --repo-mesh：工作者会话永远不会获得协调者工具集。

工作者工具：report_completion、progress_update、peer_context_pull、git_status、git_log、git_diff。

已退役的工具名

2026-09-26，把作用于同一对象的多个工具合并为一个、通过 action / kind / mode 参数选择的工具，mesh 工具从 60 个整合为 48 个。所有功能仍然可用。旧名称不再由 tools/list 列出，且不会被转发：调用旧名称会返回一个错误，指明替代工具和需要添加的参数，因此使用旧提示词的智能体在下一次调用时就能恢复。

旧名称	改为调用
mesh_node_slots_list	mesh_node_slots + action: "list"
mesh_node_slots_propose	mesh_node_slots + action: "propose"
mesh_node_slots_set	mesh_node_slots + action: "set"
mesh_record_note	mesh_note + action: "record"
mesh_forget_note	mesh_note + action: "forget"
mesh_reinit	mesh_init + mode: "reinit"
mesh_refine_config	mesh_config + kind: "refine"
mesh_change_impact_config	mesh_config + kind: "change_impact"
mesh_write_mesh_json_config	mesh_config + kind: "mesh_json"
mesh_plan_onboarding	mesh_create + mode: "plan"
mesh_prune_stale_direct	mesh_cleanup_sessions + mode: "prune_stale_direct"

图编排工具（mesh_graph_view、mesh_graph_gate、mesh_graph_node_patch）已于 2026-09-30 移除，没有替代工具；请改用 depends_on 串接任务。

MAGI 工具（mesh_magi_review、mesh_magi_collect、mesh_magi_kind_panel）已于 2026-09-30 移除。调用它们会返回一条说明替代做法的错误：用 mesh_send_task 把同一个只读问题发给 2–3 个不同提供方的工作者，等待它们的 report_completion，然后自己综合答案。

mesh_refine_plan 已于 2026-10-08 移除：它是 mesh_refine_node 默认试运行的别名。调用它会返回一条指向 mesh_refine_node 的错误；mesh_refine_node 会在不执行任何操作的情况下返回同样的计划。

mesh_coordinator_prompt_append（包括已退役的 _get / _set 名称）已于 2026-10-08 与按机器存储的 ~/.adhdev/coordinator-prompts/ 文件一起移除，守护进程不再读取这些文件。调用它会返回一条说明替代做法的错误：要给某个项目的协调者长期附加的指示，请写入仓库 .adhdev/mesh.json 的 coordinator.systemPromptAppend（mesh_config，kind: "mesh_json"），经验教训则用 mesh_note 记录。

已弃用别名

mesh_refine_config_schema、mesh_suggest_refine_config、mesh_validate_refine_config，以及它们对应的 change-impact 版本（mesh_change_impact_config_schema、mesh_suggest_change_impact_config、mesh_validate_change_impact_config）早于上述整合。它们不由 tools/list 列出，但服务器仍作为兼容层继续派发它们，以对应的 kind 和 mode 转发到 mesh_config。新的调用方应直接使用 mesh_config。

mesh_ledger_query 是 mesh_task_history 的已弃用别名，mesh_task_history 已于 2026-10-08 接管了它的 kind / since / node 过滤器。它在一个版本内仍会列出并可用（完整负载，tail 默认 50），之后将被移除。新的调用方应使用 mesh_task_history；需要完整负载时传入 verbose: true。

相关参考

• CLI 命令
• API 密钥
• REST API