aidemd-mcp/server

Scan for .aide spec files in this project. Returns a tree map of where specs live, following progressive disclosure.

Without a path: returns a lightweight project-wide map — file locations and types only, no content. Use this once to understand the project's spec architecture.

With a path: the response opens with the ancestor chain — the cascading intent lineage from project root down to the target directory, with each ancestor showing its description and alignment status (aligned/misaligned when set). The ancestor chain gives you the full inherited context before you read a single spec body. After the ancestor chain comes the detailed subtree of the target directory — summaries extracted from file content and anomaly warnings. Use this to drill into the area you're working on.

.aide files are progressive disclosure specs that live next to orchestrator code — they contain intent (strategy, implementation contracts, anti-patterns), research (sources, data, patterns), or QA checklists (todo). Read .aide files BEFORE reading code — they are the context layer between folder structure and implementation details.

File types (.aide, intent.aide, research.aide, plan.aide, todo.aide):

• .aide — Intent spec (default). Strategy, contracts, anti-patterns.

• intent.aide — Same as .aide, used only when research.aide exists in the same folder.

• research.aide — Raw research. Sources, data points, pattern synthesis.

• plan.aide -- Architect's implementation plan. Checkboxed steps for the implementor.

• todo.aide — QA re-alignment document. Captures where implementation drifted from intent.

Never have both .aide and intent.aide in the same folder.

Read an .aide spec file with full context. Returns the file content, its classified type (intent/research/plan/todo), related specs in the same directory, and links found in the content (relative paths, wikilinks, URLs). Use this after aide_discover to drill into a specific spec.

Create new .aide spec files with automatic naming convention enforcement. Handles the naming 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.

Types:

• intent — Strategy, contracts, anti-patterns

• research — Sources, data, patterns (triggers rename of existing .aide)

• both — Creates research.aide + intent.aide pair

• todo — QA re-alignment document for QA agents

• plan -- Architect's implementation plan (no naming interaction with intent/research)

Health check for .aide spec files in the project. Detects orphaned specs (in folders with no orchestrator), missing specs (orchestrators with 3+ helper imports but no .aide), naming conflicts (.aide + intent.aide in same folder), broken links, orphaned research (research.aide without intent spec), and missing descriptions (specs with no description field in frontmatter).

Compare the AIDE methodology artifacts in this project against the canonical versions and return structured JSON results grouped by category. Use this when the user asks to update AIDE, sync AIDE, refresh AIDE, check for AIDE updates, or bring AIDE up to date. This is NOT for editing user .aide specs — it inspects methodology infrastructure only.

The tool uses a two-call pattern for progressive disclosure:

First call (no category param): Returns a lightweight summary — every category with file names, statuses, and counts, but NO file content. Use this to understand what has drifted and present a summary to the user. Ask which categories they want to apply.

Second call (with category param): The tool writes all differs/missing files directly to disk itself and returns a manifest — file results with filePath, status ("updated", "created", or "matches"), and name, but NO canonicalContent. The agent never sees file content and never uses the Write tool for methodology files.

Repeat the second call for each category the user confirms.

As the calling agent, you must:

1. Call without category first to get the summary

2. Present each drifted category (differs/missing) and ask the user which to apply

3. For each confirmed category, call again with category=X — the tool writes the files and returns a manifest. Report what was updated/created to the user.

4. For the mcp category, the manifest still includes prescription data — merge the entry into the existing MCP config yourself (read → merge → write). If malformed, tell the user — do not overwrite.

5. For ide, the manifest may include instructions for VS Code extension install — execute that command for the user. Zed config is written directly by the tool.

IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion: Do NOT present all categories at once. Walk the user through ONE category at a time using AskUserQuestion with Yes/Skip options. Stop after each question and wait for confirmation before calling with that category.

Categories: pointer-stub, methodology-docs, version-metadata, commands, agents, skills, mcp, ide, readme.

Upgrade surface (user code and user .aide specs are never touched):

• AIDE pointer stub in the agent config file

• Canonical methodology docs under .aide/docs/

• versions.json metadata under .aide/docs/

• Slash commands for all pipeline phases

• Pipeline agent files, skill templates

• MCP server entry in the project's MCP config

• IDE file association config (Zed settings, VS Code extension)

Supports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects the framework or accepts an override.

Check whether the host project's AIDE artifacts are up to date. Reads the local .aide/versions.json, compares against the canonical manifest shipped with the server, and returns which artifacts are outdated plus the server version. No parameters needed — uses the server's working directory. Called by the orchestrator at boot.

Bootstrap the AIDE development environment into a project. Returns structured JSON for agent consumption — not prose.

The tool uses a two-call pattern for progressive disclosure:

First call (no category param): Returns a lightweight summary — every step with name, status (would-create/would-skip/exists), category, and filePath, but NO content fields. Also returns brainHints (vault candidates) and detected framework. Use this to understand what needs to be done.

Second call (with category param): The tool writes all would-create files directly to disk itself and returns a manifest — steps with filePath, status (created or exists), and name, but NO content. The agent never sees file content and never uses the Write tool for new files.

Exception — MCP steps: For MCP steps, the manifest includes prescription data (key name and entry object) so the agent can read the existing config, merge, and write. The tool never touches MCP config directly.

Exception — brain category: When calling with category=brain, also pass brainPath with the user-confirmed vault path. The tool creates the vault scaffold directories directly.

Exception — IDE VS Code steps: IDE steps that need external tooling (VS Code CLI) return instructions for the agent to execute, since those aren't simple file writes.

IMPORTANT — one-at-a-time wizard pattern using AskUserQuestion: Do NOT present a summary table of all categories. Do NOT offer "all" as an option. Do NOT ask conversational questions — use the AskUserQuestion tool with structured options at every pause point. Walk the user through ONE category at a time:

1. Call without category first to get the metadata

2. Present ONLY the detected framework — use AskUserQuestion with Yes/{alternatives} options. STOP.

3. Present ONLY the first category with would-create steps — use AskUserQuestion with Yes/Skip options. STOP.

4. If confirmed, call again with category=X (and brainPath when category is brain). The tool writes files and returns a manifest. Report what was created, then present the NEXT category with AskUserQuestion. STOP.

5. Repeat step 4 for each remaining category in order: methodology, commands, agents, skills, mcp, brain, ide, readme

6. For brain: use AskUserQuestion with brainHints as labeled options (user can pick Other for custom path). STOP.

7. For MCP: use AskUserQuestion with Merge/Skip options. Merge the prescription entry into the existing config yourself (read → merge → write). STOP.

8. For IDE: use AskUserQuestion with multiSelect for Zed/VS Code/Neither. STOP.

Each step is ONE AskUserQuestion → wait for selection → then proceed. Never show multiple categories at once. Never ask open-ended conversational questions.

Do NOT auto-apply steps without user confirmation.