Aidemd

@aidemd-mcp/server

为任何 AI 驱动的 IDE 带来意图驱动开发的 MCP 服务。 管理与代码并存的 .aide 规范文件——架构师据此规划、实现者据此构建、QA 据此验证的领域上下文。

了解详情，请访问 aidemd.dev。

功能

• 全项目规范发现，通过渐进式披露树在代码库的各个层级呈现意图、研究和 QA 规范
• 一条命令初始化项目，通过 aide_init 在单个引导流程中将方法论文档、流水线命令和此 MCP 服务接入项目
• 自动执行命名约定——aide_scaffold 负责处理 .aide / intent.aide 重命名规则，避免创建冲突的规范
• 受控的流水线清理，通过 aide_cleanup，仅当所有复选框都已勾选时才移除已关闭模块的计划、待办事项和简报；否则会拒绝操作并准确列出未完成项
• 健康检查验证，通过 aide_validate，在问题导致偏差前检测孤立规范、缺失的描述、失效链接和命名冲突
• 代码内省，通过 aide_inspect，无需打开文件即可返回指定符号的 JSDoc、签名和类型，为 Agent 提供代码的第 2 层渐进式披露
• 升级偏差检测，通过 aide_upgrade，将项目的 AIDE 方法论产物与规范版本进行比较，并按类别写入更新
• 运行时大脑入口，通过 aide_brain，按需提供工具，返回可直接执行的说明，告知 Agent 应调用哪些 MCP 工具以及如何访问已接入的大脑后端，而无需让 Agent 知道具体使用的是哪个后端

安装

快速开始（Claude Code）

选择启动模式——init 会询问并推荐全局模式，且不会切换现有条目。

全局——个人设备推荐选择此模式：启动可靠，并保持使用已安装的版本。

npm i -g @aidemd-mcp/server
aidemd-mcp init

本地——共享仓库和云端/CI 环境推荐选择此模式：固定为一个确切版本，由 /aide:upgrade 推进版本。

npx -y @aidemd-mcp/[email protected] init

--mode global|local 可跳过提问（非交互式运行默认使用本地模式）。

此命令会：

• 将 AIDE MCP 服务条目合并到 .mcp.json
• 将捆绑的 brain 配置模板写入 .aide/config/brain.aide（在 /aide:brain config 填入 brain 位置并写入 brain MCP 条目之前，brain 位置会保持未设置状态）
• 将所有流水线斜杠命令写入 .claude/commands/aide/
• 将 11 个规范 Agent 安装到 .claude/agents/aide/（包括流水线 Agent，以及由 /aide:upgrade 运行、用于迁移项目自身文件的 aide-upgrader），并将看板 Agent kanban-maintainer 安装到 .claude/agents/kanban/
• 将技能（study-playbook、brain、aide、aide-handoff、kanban、aide-brain-author）安装到 .claude/skills/
• 将方法论文档中心安装到 .aide/docs/
• 将 aide-tree 启动器写入 .aide/bin/aide-tree.mjs
• 向 README.md 添加 AIDE 徽章（如果尚不存在，则追加到文件末尾）

所有操作均为增量操作——绝不会覆盖已存在的文件。可随时安全地重新运行。

init 不会询问 brain 位置、路径或令牌，并会拒绝 --vault-path 等后端标志。--brain <integration> 用于选择捆绑模板（目前仅有 obsidian，也是默认值）。

运行后，打开 Claude Code 并运行 /aide。首次运行时会跳转到 /aide:brain config，该命令会在 .aide/config/brain.aide 中填入 brain 位置，通过 sync 写入 brain MCP 条目，并初始化 brain。init 未能完成的其他事项会列在结束时的后续操作清单中。

将 brain.aide 同步到 .mcp.json

编辑 .aide/config/brain.aide 后运行此命令，例如更新 mcpServerConfig.args 中的 brain 路径参数，或重命名 name 字段中的 brain 名称时：

全局：

aidemd-mcp sync

本地（使用你的 aide 条目固定的版本）：

npx -y @aidemd-mcp/[email protected] sync

sync 会读取 .aide/config/brain.aide，将 mcpServerConfig 原样复制到 .mcp.json 中固定的 brain 键下，并将 name 字段写为服务标签。mcpServers 中的所有其他键（包括你的 aide 条目和任何个人 MCP 集成）都会保持字节级不变。如果存在旧版 obsidian 键，则会在同一次写入中将其移除。此命令具有幂等性——运行两次会生成完全相同的 .mcp.json 字节；第二次调用会打印 already in sync，且不会改动文件。成功时（包括无需更改的情况）退出代码为 0；缺少或格式错误的 brain.aide，或无效的 .mcp.json，退出代码为 1；使用 --help 时退出代码为 2。

更新 mcpServerConfig.args 中的 brain 路径后，输出示例如下：

Read .aide/config/brain.aide
Wrote brain MCP entry into .mcp.json
  command: mcpvault
  args: [D:/notes/new-brain]
Done.

手动配置

如果你使用 Claude Code 以外的客户端，或更倾向于手动配置，请将服务条目添加到客户端的 MCP 配置文件中。

Claude Code

全局——推荐在自己的设备上使用。安装一次，然后注册：

npm i -g @aidemd-mcp/server
claude mcp add aide -- aidemd-mcp

或者添加到项目的 .mcp.json：

{
  "mcpServers": {
    "aide": {
      "command": "aidemd-mcp"
    }
  }
}

本地、固定版本——适用于共享仓库和云端/CI 环境：

claude mcp add aide -- npx -y @aidemd-mcp/[email protected]

或者添加到项目的 .mcp.json：

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/[email protected]"]
    }
  }
}

说明

上方的快速开始命令会为 Claude Code 用户自动完成此操作。

Claude Desktop

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

全局 — 推荐在自己的计算机上使用（安装 npm i -g @aidemd-mcp/server 后）：

{
  "mcpServers": {
    "aide": {
      "command": "aidemd-mcp"
    }
  }
}

本地固定版本 — 适用于共享仓库和云端/CI：

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/[email protected]"]
    }
  }
}

说明

Claude Desktop 不会继承终端的 PATH。如果你使用 nvm 或 Homebrew 管理 Node，可能无法找到 npx。在终端运行 which npx 获取绝对路径，并在上方配置中用该路径替换 "npx"。

修改配置后，Claude Desktop 必须完全退出并重新打开。

Cursor

添加到 ~/.cursor/mcp.json：

全局 — 推荐在自己的计算机上使用（安装 npm i -g @aidemd-mcp/server 后）：

{
  "mcpServers": {
    "aide": {
      "command": "aidemd-mcp"
    }
  }
}

本地固定版本 — 适用于共享仓库和云端/CI：

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/[email protected]"]
    }
  }
}

VS Code / Copilot

添加到 .vscode/mcp.json：

全局 — 推荐在自己的计算机上使用（安装 npm i -g @aidemd-mcp/server 后）：

{
  "servers": {
    "aide": {
      "command": "aidemd-mcp"
    }
  }
}

本地固定版本 — 适用于共享仓库和云端/CI：

{
  "servers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/[email protected]"]
    }
  }
}

说明

VS Code / Copilot 使用 "servers" 作为根键，而不是 "mcpServers"。使用错误的根键会导致服务无法加载，且不会显示任何错误。

Windsurf

添加到 ~/.windsurf/mcp.json：

全局 — 推荐在自己的计算机上使用（安装 npm i -g @aidemd-mcp/server 后）：

{
  "mcpServers": {
    "aide": {
      "command": "aidemd-mcp"
    }
  }
}

本地固定版本 — 适用于共享仓库和云端/CI：

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/[email protected]"]
    }
  }
}

工具

aide_discover

扫描项目中的 .aide 规范文件，并返回渐进式披露树状图，展示每份规范的类型、位置和摘要。计划或待办列表会内嵌其状态，例如 [plan: approved]；已审阅的规范则会显示其一致性状态。

输入：

• path（字符串，可选）：要深入查看的子目录。提供该参数时，响应会先显示祖先链——从根目录到目标目录的级联意图脉络，其中每个祖先都会显示其描述和一致性状态——然后显示包含摘要和警告的详细子树。不提供时，则返回浅层的全项目地图（仅显示位置和类型）。

aide_read

读取 .aide 规范文件及其完整上下文，返回文件内容、分类后的类型（intent/research/plan/todo）、同一目录中的相关规范，以及内容中找到的链接。

输入：

• path（字符串，必填）：要读取的 .aide 文件路径。

aide_scaffold

创建新的 .aide 规范文件，并自动强制执行命名约定。处理重命名规则：默认情况下，intent 规范使用 .aide；若同一文件夹中存在 research.aide，则改用 intent.aide；创建 research.aide 时，会自动将已有的 .aide 重命名为 intent.aide。

输入：

• directory（字符串，必填）：创建 .aide 文件的目录。
• type（字符串，必填）：要创建的文件类型。可选值：intent、research、both、todo、plan、session。无论 directory 指定什么，session 始终会将项目的会话记录写入 .aide/session.aide。

该工具绝不会覆盖文件：如果文件已存在，则跳过并报告。新建的 intent 规范初始状态为 alignment: unreviewed；新建的计划和待办列表初始状态为 status: proposed。

aide_cleanup

移除已关闭模块的流水线临时文件——brief.aide、todo.aide 和 plan.aide，除此之外不做任何更改。代码会强制检查前置条件。每个待移除文件都必须记录已关闭状态：completed（且每个复选框都确实已勾选）或 abandoned；对于状态机制引入前的文件，只要所有复选框都已勾选即可通过。任何仍处于 proposed 或 approved 状态的文件都会被拒绝。只有与计划一同移除时，才会移除 brief.aide；若计划已放弃，也会一并移除其 brief。若不存在 plan.aide，则单独移除已关闭的 todo.aide。拒绝操作不会移除任何内容，并会列出每个未勾选项及其文件和行号。绝不会触及意图规范、代码或 .aide/session.aide，并且会拒绝项目目录之外的路径。支持跨平台且无需 shell，因此清理不需要 rm 权限——按名称允许此工具即可。

输入：

• path（字符串，必填）：存放临时文件的模块文件夹，相对于项目根目录。
• dryRun（布尔值，可选）：报告将要移除的内容或阻止移除的原因，但不实际移除。仅用于检查——实际调用本身已是安全的。

aide_frontmatter

读取或更改 AIDE 文件中一个受管控的 frontmatter 值，同时保持其他每个字节不变。意图规范包含 alignment（unreviewed、aligned、misaligned）。计划、brief 和 todo 列表包含 status，状态可从 proposed → approved → completed，或变为 abandoned；completed 和 abandoned 是最终状态，设为 completed 要求每个项目都已勾选，修订后的 approved 文件会退回 proposed。此工具会强制执行允许的状态变更，并拒绝会话记录、研究规范、非 AIDE 文件以及项目目录之外的路径。它不会决定何时更改值——这由对齐器、QA、用户批准或丢弃操作决定。

输入：

• path（字符串，必填）：AIDE 文件，相对于项目根目录。
• field（字符串，可选）：alignment 或 status。与 value 一同省略时表示读取。
• value（字符串，可选）：新值。

aide_inspect

在工作区中查找指定函数、方法、类、接口或类型别名，并返回其 JSDoc 块、签名和种类——这是代码的第 2 层渐进式披露。Agent 无需打开文件即可了解符号的契约。

输入：

• name（字符串，必填）：要查找的符号名称。
• file（字符串，可选）：将搜索范围限制为单个文件（相对于项目根目录）。

aide_validate

对项目中的 .aide 规范文件运行健康检查。检测孤立规范、缺失规范、命名冲突（同一文件夹中同时存在 .aide 和 intent.aide）、失效链接、孤立研究文件、缺失的 frontmatter 描述、无法解析的 frontmatter，以及缺少 alignment 或其值不受支持的意图规范。

输入：

• path（字符串，可选）：要验证的子目录。省略时默认为整个项目。

aide_info

启动时前置条件报告器。返回两个供编排器分别分支处理的独立字段：outdated（过时 AIDE 产物键的数组，用于比较项目的 versions.json 与随附清单），以及 brain（一个 { status, name?, hints } 对象，用于报告项目的 brain.aide 配置是否已接入 .mcp.json）。brain.status 是一个仅包含五种状态的联合类型：ok | no-brain-aide | brain-aide-invalid | no-mcp-entry | mcp-drift，通过比较 .aide/config/brain.aide 与 .mcp.json 得出——不验证磁盘路径。brain-aide-invalid 表示文件存在但不可用，并带有一个 fault：可以是 missing-sections（指出缺少哪些必需部分），也可以是 malformed（附带原因，也包括文件无法读取的情况）。name 是用户在 brain.aide 中声明的标签；在 no-brain-aide 和 brain-aide-invalid 状态下不存在。对于 no-brain-aide 和 brain-aide-invalid，可通过 /aide:brain config 恢复。hints 是候选知识库位置数组，编排器可在恢复时显示这些位置。

输入：

（无）

aide_brain

按需调用的 brain 入口工具。当你需要在任务中途访问 brain 时调用此工具——不要在每次 /aide 启动时都调用。启动时的 brain 前置条件状态已由 aide_info.brain.status 报告；在启动时调用 aide_brain 会不必要地重复这项工作。

返回 { status, instructions }——恰好两个字段。不包含 backend、connector 或 name。status 与 aide_info.brain.status 相同（ok | no-brain-aide | brain-aide-invalid | no-mcp-entry | mcp-drift）。instructions 始终非空：状态为 ok 时，它是从用户的 .aide/config/brain.aide 中选定部分（根据可选的 kind 输入选择 orientation 或 config）原样返回的正文（不会替换服务端内容）；处于失败状态时，它包含修复说明。no-brain-aide 和 brain-aide-invalid 都会跳转至 /aide:brain config；brain-aide-invalid 的内容根据检测器的 fault 生成——可能是列出的缺失必需部分，也可能是格式错误原因（包括文件存在但无法读取的情况，绝不会报告为文件不存在）。no-mcp-entry 和 mcp-drift 会提示用户使用其 aide 条目所用的启动器运行同步命令（aidemd-mcp sync 或 npx -y @aidemd-mcp/server@<version> sync）。

输入：

（无）

aide_init

通过逐项引导向导，将 AIDE 开发环境引导至项目中。首次调用时（不传入 category），返回包含每个步骤状态及检测到的框架的摘要。后续调用时（传入 category），将该类别的所有待创建文件写入磁盘，并返回清单。

输入：

• framework（字符串，可选）：强制指定框架，而非自动检测。可选值：claude、cursor、windsurf、copilot。
• path（字符串，可选）：自定义项目根路径。默认为服务端工作目录。
• category（字符串，可选）：为此类别写入所有 would-create 文件并返回清单。可选值：framework、methodology、commands、agents、skills、mcp、brain、ide、readme。首次调用时省略此项，以获取仅包含元数据的摘要。
• aideMode（字符串，可选）：aide MCP 条目的启动模式，global（推荐）或 local。与 category=mcp 一起传入。
• brainMode（字符串，可选）：brain 模板启动器的启动模式，global 或 local。与 category=brain 一起传入。

aide_upgrade

将此项目中的 AIDE 方法论制品与规范版本进行比较，并按类别分组返回结构化差异。首次调用（不提供 category）时，返回每个类别的轻量摘要及其偏差状态。后续调用（提供 category）时，将该类别中所有存在差异或缺失的文件写入磁盘，并返回清单。

输入：

• framework（字符串，可选）：强制使用指定框架，而非自动检测。可选值：claude、cursor、windsurf、copilot。
• path（字符串，可选）：自定义项目根路径。默认为服务工作目录。
• category（字符串，可选）：将该类别中所有存在差异或缺失的文件写入磁盘，并返回清单。可选值：pointer-stub、methodology-docs、version-metadata、commands、agents、skills、mcp、ide、readme。首次调用时省略此参数，以获取仅包含元数据的摘要。

入门

将服务添加到 MCP 客户端后，让你的 Agent 运行 aide_init，将 AIDE 方法论引导至项目中。此操作会安装方法论文档、搭建流水线命令，并完成所有配置。

然后尝试：“为我的身份验证模块搭建意图规范”——Agent 将使用 aide_discover 梳理项目，并使用 aide_scaffold 按照正确的命名约定在合适的位置创建规范。

开发

npm install
npm run build
npm test

许可证

MIT