Aidemd MCP MCP

@aidemd-mcp/server

MCP server that brings intent-driven development to any AI-powered IDE. Manage .aide spec files that live next to your code — the domain context that architects plan from, implementors build from, and QA validates against.

Learn more at aidemd.dev.

Features

• Project-wide spec discovery with a progressive disclosure tree that surfaces intent, research, and QA specs at every level of your codebase
• One-command project bootstrap via aide_init — wires methodology docs, pipeline commands, and this MCP server into your project in a single guided flow
• Automatic naming convention enforcement — aide_scaffold handles the .aide / intent.aide rename rules so you never create conflicting specs
• Guarded pipeline cleanup via aide_cleanup — removes a closed module's plan, todo and brief only when every checkbox is checked, and refuses with the exact open items otherwise
• Health-check validation via aide_validate — detects orphaned specs, missing descriptions, broken links, and naming conflicts before they cause drift
• Code introspection via aide_inspect — returns JSDoc, signatures, and kind for named symbols without opening files, giving agents Tier 2 progressive disclosure for code
• Upgrade drift detection via aide_upgrade — compares your project's AIDE methodology artifacts against canonical versions and writes updates per-category
• Runtime brain entry-point via aide_brain — on-demand tool that returns ready-to-execute prose telling the agent which MCP tools to call and how to reach whatever brain backend is wired, without the agent knowing which backend it is

Installation

Quick Start (Claude Code)

Run the installer from your project's root:

npx -y @aidemd-mcp/server@0.15.0 init

This command:

• Installs the AIDE MCP server globally (npm i -g @aidemd-mcp/server); if the install fails, it says so and writes nothing
• Merges the AIDE MCP server entry into .mcp.json, launched by its global command aidemd-mcp
• Writes the bundled brain config template to .aide/config/brain.aide (the brain location stays unset until /aide:brain config fills it and writes the brain MCP entry)
• Writes every pipeline slash command to .claude/commands/aide/
• Installs 11 canonical agents to .claude/agents/aide/ (the pipeline agents plus aide-upgrader, which /aide:upgrade runs to migrate the project's own files) and the kanban-maintainer board agent to .claude/agents/kanban/
• Installs skills (study-playbook, brain, aide, aide-handoff, kanban, aide-brain-author) to .claude/skills/
• Installs the methodology docs hub to .aide/docs/
• Writes the aide-tree launcher to .aide/bin/aide-tree.mjs
• Adds an AIDE badge to README.md (appends if not present)

All operations are additive — files that already exist are never overwritten. Safe to re-run at any time.

init asks for no brain location, path or token, and rejects backend flags such as --vault-path. --brain picks the bundled template (today only obsidian, the default).

After running, open Claude Code and run /aide. On the first run it routes to /aide:brain config, which fills the brain location in .aide/config/brain.aide, writes the brain MCP entry through sync, and seeds the brain. Anything else init could not finish is named in its closing follow-up list.

Syncing brain.aide to .mcp.json

Run this after editing .aide/config/brain.aide — for example, when you update the brain path argument in mcpServerConfig.args or rename the brain in the name field:

aidemd-mcp sync

sync reads .aide/config/brain.aide, copies mcpServerConfig verbatim into .mcp.json under the fixed brain key, and writes the name field as the server label. Every other key in mcpServers (including your aide entry and any personal MCP integrations) is left byte-identical. If a legacy obsidian key is present it is removed in the same write. The command is idempotent — running it twice produces the same .mcp.json bytes, and the second invocation prints already in sync without touching the file. Exit code is 0 on success (including the no-change case), 1 on a missing or malformed brain.aide or invalid .mcp.json, and 2 on --help.

Example output after updating the brain path in mcpServerConfig.args:

Read .aide/config/brain.aide

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

Manual Configuration

If you use a client other than Claude Code, or prefer to configure manually, add the server entry to your client's MCP config file.

Claude Code

Install once, then register:

npm i -g @aidemd-mcp/server

claude mcp add aide -- aidemd-mcp

Or add to your project's .mcp.json:

{

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

[!NOTE]

The Quick Start command above handles this automatically for Claude Code users.

Claude Desktop

Config file locations:

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

After npm i -g @aidemd-mcp/server:

{

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

[!NOTE]

Claude Desktop does not inherit the terminal PATH. If you use nvm or Homebrew to manage Node, aidemd-mcp may not be found. Run which aidemd-mcp in your terminal to get the absolute path and use it as the command in the config above.

Claude Desktop requires a full quit-and-reopen after any config change.

Cursor

Add to ~/.cursor/mcp.json:

After npm i -g @aidemd-mcp/server:

{

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

VS Code / Copilot

Add to .vscode/mcp.json:

After npm i -g @aidemd-mcp/server:

{

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

[!NOTE]

VS Code / Copilot uses "servers" as the root key, not "mcpServers". Using the wrong root key causes the server to silently fail to load.

Windsurf

Add to ~/.windsurf/mcp.json:

After npm i -g @aidemd-mcp/server:

{

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

Tools

aide_discover

Scan the project for .aide spec files and return a progressive disclosure tree map showing each spec's type, location, and summary. A plan or todo list carries its status inline, e.g. [plan: approved], and a reviewed spec its alignment.

Inputs:

• path (string, optional): Subdirectory to drill into. When provided, the response opens with the ancestor chain — the cascading intent lineage from root to target, each ancestor showing its description and alignment status — followed by the detailed subtree with summaries and warnings. When omitted, returns a shallow project-wide map (locations and types only).

aide_read

Read an .aide spec file with full context, returning the file content, its classified type (intent/research/plan/todo), related specs in the same directory, and links found in the content.

Inputs:

• path (string, required): Path to the .aide file to read.

aide_scaffold

Create new .aide spec files with automatic naming convention enforcement. Handles the rename rules: intent specs are .aide by default but become intent.aide when research.aide exists in the same folder; creating a research.aide auto-renames any existing .aide to intent.aide.

Inputs:

• directory (string, required): Directory where the .aide file(s) will be created.
• type (string, required): Type of file to create. One of: intent, research, both, todo, plan, session. session always writes the project's session record at .aide/session.aide, whatever directory says.

It never overwrites: a file that already exists is skipped and reported. New intent specs start alignment: unreviewed; new plans and todo lists start status: proposed.

aide_cleanup

Remove a closed module's pipeline ephemerals — brief.aide, todo.aide and plan.aide — and nothing else. The preconditions are enforced in code. Each file it would remove must record a closed status: completed (and every checkbox really checked) or abandoned; a file from before statuses existed passes when every checkbox is checked. Anything still proposed or approved is refused. A brief.aide is removed only together with its plan, and an abandoned plan takes its brief with it. Where there is no plan.aide, a closed todo.aide is removed on its own. A refusal removes nothing and names each unchecked item with its file and line. It never touches intent specs, code or .aide/session.aide, and it refuses paths outside the project. Cross-platform with no shell, so cleanup needs no rm permission — allow the tool by name.

Inputs:

• path (string, required): Module folder that holds the ephemerals, relative to the project root.
• dryRun (boolean, optional): Report what would be removed, or what blocks removal, without removing anything. For inspection only — the real call is already safe.

aide_frontmatter

Read or change one governed frontmatter value of an AIDE file, leaving every other byte as it was. Intent specs carry alignment (unreviewed, aligned, misaligned). Plans, briefs and todo lists carry status, moving proposed → approved → completed, or to abandoned; completed and abandoned are final, completed needs every item checked, and a revised approved file drops back to proposed. The tool enforces the allowed moves and refuses the session record, research specs, non-AIDE files and paths outside the project. It never decides when a value changes — the aligner, QA, the user's approval or a discard do.

Inputs:

• path (string, required): The AIDE file, relative to the project root.
• field (string, optional): alignment or status. Omit with value to read.
• value (string, optional): The new value.

aide_inspect

Return the JSDoc block, signature, and kind for a named function, method, class, interface, or type alias in the workspace — Tier 2 progressive disclosure for code. Agents can understand a symbol's contract without opening the file.

Inputs:

• name (string, required): Symbol name to look up.
• file (string, optional): Restrict search to a single file (relative to project root).

aide_validate

Run a health check on .aide spec files in the project. Detects orphaned specs, missing specs, naming conflicts (.aide and intent.aide in the same folder), broken links, orphaned research files, missing frontmatter descriptions, unparsable frontmatter, and intent specs whose alignment is missing or not a known value.

Inputs:

• path (string, optional): Subdirectory to validate. Defaults to the entire pro