Teaches AI agents the AIDE methodology through progressive disclosure and manages intent-driven development specification files.
Also known as aidemd-mcp/server, @aidemd-mcp/server
- Stars
- 4
- Tools
- 11
- Downloads, 30 days
- 2,125
- Latest version
- 0.15.0
- Last commit
- Oct 28, 2026
- License
- MIT
What is AIDE MCP?
AIDE teaches AI agents the AIDE methodology through progressive disclosure and manages intent-driven development specification files. It exposes 11 tools, such as aide_discover, aide_read, aide_scaffold.
Summary generated from the project's README
About AIDE MCP server
Developers using AI-powered IDEs can implement intent-driven development by managing specialized specification files through this server. It facilitates the AIDE methodology by providing tools to discover, create, and maintain .aide files that serve as domain context for architects, implementors, and QA testers. The server works locally within environments like Claude Code, Cursor, Windsurf, or Claude Desktop by managing a directory of spec files alongside your codebase.
Users can bootstrap entire projects with a single command to install methodology documentation, pipeline commands, and specialized agents. The server includes specific tools for maintaining project health, such as aide_validate for detecting naming conflicts or broken links, and aide_cleanup to safely remove completed module plans only when all checkboxes are checked. It also offers aide_inspect to provide code introspection, allowing agents to see JSDoc and signatures without opening full files. This approach ensures that AI agents follow a structured development lifecycle guided by progressive disclosure of intent and research.
What you can do with it
- 1Bootstrap a new projectInitialize a project with all necessary methodology docs, pipeline commands, and specialized agents in one step.
- 2Enforce naming conventionsCreate new specification files while automatically handling complex renaming rules for intent and research files.
- 3Perform code introspectionAllow an AI agent to understand a symbol's contract and signature without needing to read the entire file.
- 4Validate specification healthCheck the codebase for orphaned specs, missing descriptions, or naming conflicts that cause documentation drift.
Written from the project's README. Every use case is checked against a quote from it.
How to install AIDE MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AIDE MCP in Claude Code
$ claude mcp add server -- npx -y @aidemd-mcp/serverInstall AIDE MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"server": {
"command": "npx",
"args": [
"-y",
"@aidemd-mcp/server"
]
}
}
}Install AIDE MCP in VS Code
.vscode/mcp.json
{
"servers": {
"server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@aidemd-mcp/server"
]
}
}
}Install AIDE MCP in VS Code CLI
$ code --add-mcp '{"name":"server","type":"stdio","command":"npx","args":["-y","@aidemd-mcp/server"]}'Install AIDE MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"server": {
"command": "npx",
"args": [
"-y",
"@aidemd-mcp/server"
]
}
}
}Install AIDE MCP in Codex
$ codex mcp add server -- npx -y @aidemd-mcp/serverInstall AIDE MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.server] command = "npx" args = ["-y", "@aidemd-mcp/server"]
Install AIDE MCP in Gemini CLI
$ gemini mcp add -s user server npx -- -y @aidemd-mcp/serverInstall AIDE MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"server": {
"command": "npx",
"args": [
"-y",
"@aidemd-mcp/server"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @aidemd-mcp/server 0.15.0 in an isolated container with no network and no keys. It answered and listed 11 tools.
AIDE MCP tools 11
Read from the server with tools/listaide_discoverScan 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, type tags and each spec's one-line description; a plan or todo tag carries its status, e.g. [plan: approved]. Only the head of each file is read. 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.
aide_readRead 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, inline references, URLs). Use this after aide_discover to drill into a specific spec.
aide_scaffoldCreate a new AIDE working file from its blank template, under its canonical name. It never overwrites: a request for a file that already exists, filled or empty, is a no-op reported as a skip line — remove a file first with aide_cleanup to replace it. New files start with their starting value: an intent spec alignment: unreviewed, a plan or todo list status: proposed. Handles the naming rules, so never pick a name yourself: in a module folder, 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. The project root intent spec always lands at .aide/intent.aide: pass directory ".aide" or "." (both mean the project's .aide folder for intent, research and both). A bare .aide/.aide left by an older project, with no intent.aide beside it, is renamed to .aide/intent.aide with its content kept; if .aide/intent.aide exists, nothing changes. Folders are never treated as spec files. A plan needs an intent spec beside it: scaffolding a plan in a folder with no intent spec (.aide or intent.aide; a research.aide alone does not count) is refused and creates nothing — write the folder's intent spec first. For a root-level plan, pass directory ".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; refused unless the folder already holds an intent spec - session — The project's session record, always at .aide/session.aide whatever directory you pass: the empty placeholder with every section heading. Its single source; never write the placeholder by hand.
aide_cleanupRemove a module's pipeline ephemerals (plan.aide, todo.aide, brief.aide) once that module's cycle has closed, leaving the code and the intent specs as the durable record. It never removes, rewrites or reads anything else: intent specs, research specs, code, and .aide/session.aide are all out of reach. Each file it would remove must record a closed status: completed (re-checked — every checkbox really checked) or abandoned. A file from before statuses existed, with no status but every checkbox checked, also passes. It refuses anything still proposed or approved, a completed file with an open item, a brief.aide with no plan.aide beside it, and a folder with no ephemerals. An abandoned plan takes its brief with it, and where there is no plan.aide a closed todo.aide is removed on its own. A refusal names each open file or item with its file and line, and nothing is removed. Record a closing status with aide_frontmatter first; this tool never sets or infers one. Call it directly, because the real call is already safe. dryRun is an optional preview for inspection only and is never a required step before the real call. This is the cross-platform replacement for a shell delete, so it can be permitted by name.
aide_frontmatterRead or change one governed frontmatter value of an AIDE file, leaving every other byte untouched. Intent specs carry alignment (unreviewed, aligned, misaligned). plan.aide, brief.aide and todo.aide carry one status lifecycle: proposed, approved, completed, abandoned. Only allowed moves are accepted, completed is refused while any item is unchecked or, for a brief, until its plan is completed, and a refusal names the allowed next values. Call with path alone to read a file's governed value without changing it. The session record, research specs and brain.aide carry no governed values. The tool never chooses a value; the caller decides.
aide_validateHealth check for .aide spec files in the project. Detects orphaned specs (a spec whose folder, subfolders included, holds no code — only AIDE files, Markdown and dot-files; the project root intent spec in .aide/ is never orphaned, and a plan's presence never decides it), plans with no intent spec beside them (plan-without-spec — write the folder's spec, never delete the plan), 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), missing descriptions (specs with no description field in frontmatter), files whose frontmatter cannot be parsed, and intent specs whose alignment is missing (missing-alignment) or not one of unreviewed, aligned, misaligned (invalid-alignment).
aide_upgradeCompare 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 `"unchanged"`), 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, a result that carries `prescription` is merged into the existing MCP config by you (read → merge → write). A result that carries `pinMove` or `globalSwitch` is never merged by hand: the tool writes it (see the MCP step). 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. 6. For `brain`, the summary reports `missingSections`, outdated section text as `staleSections` and a legacy brain launcher as `legacyLauncher` (its reasons), each named separately. The brain category then works through three calls, each one decision at a time: a. `category: "brain"` (after the user's yes) inserts every missing section from the latest bundled template — byte-identical, in the file's line endings — only when the config launches the template's own brain server. It returns `{ outcome: "inserted", inserted }` (markers only; empty when nothing is missing) or `{ outcome: "adapt", adapt, instructions }` naming the sections the user must write for their backend. b. `category: "brain"` with `brainChange: <marker | "launcher">` returns one `{ outcome: "change", target, before, after, beforeHash }` diff to show the user. It is read-only. For a non-template config it returns `missing` with the template's version of an absent section instead. c. The same call plus that `beforeHash`, only on the user's yes to that one diff, returns `applied`, or a `refused` re-fetch instruction when the bytes changed since the preview. Never batch changes under one yes. Every refusal's `instructions` names the next step. **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, brain. 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) - The user-owned brain config, only through the brain category: missing sections and confirmed migrations, one consented change at a time Supports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects the framework or accepts an override. **MCP step:** the canonical aide entry runs the global command `aidemd-mcp`. The entry is read under the `aide` key, or under `aidemd-mcp` when there is no `aide` key; the key is never renamed. Without `targetVersion`, an entry that launches through npx reports `differs` with `globalSwitch: { key, name, installed, installCommand }` and no prescription. Tell the user npx launches time out at session start and ask; on yes, run `installCommand` via Bash first unless `installed` is true (a failed install: say so and stop). Then `category: "mcp"` makes the tool rewrite only that entry's command and args to the global command, every other byte unchanged; it re-checks the global install and, while the package is missing, keeps `differs` and returns `instructions` naming the install command — install, then call again. A missing aide entry returns the global `prescription` plus `globalPackage`; when the package is not installed it also carries `instructions` — act on them: install first, then merge, and never merge after a failed install. An older server cannot switch itself, so a pinned project first moves its pin to a newer version with `targetVersion` (only under the `aide` key; an npx entry under `aidemd-mcp` gets `instructions` to call without `targetVersion` and switch instead) — an exact published `x.y.z`, normally `aide_info`'s `behind.latest`, valid only with no category or with `category: "mcp"`. With it, a local (npx) aide entry is judged by its version pin alone: an older, missing or non-exact pin reports `differs` with `pinMove: { from, to }` (`from` is null when unpinned) and no prescription; a pin at or ahead of the target `matches` and is never moved back. Install the target first (`npx -y @aidemd-mcp/server@{to} sync --help` prints help starting `Usage:` and exits 2 by design; anything else means the install failed — then stop and move nothing). Then `category: "mcp"` with the same `targetVersion` makes the tool write the move itself, changing only the version inside the package argument — the command form, `cmd /c`, `-y`, other servers, formatting and line endings stay byte-identical — and returns `status: "updated"` with `pinMove`. A result that keeps `status: "differs"` with `instructions` means nothing was written (the pin changed since it was checked, the config cannot be edited byte-safely, or the entry is not a locatable `@aidemd-mcp/server` spec): relay the instructions. A global entry is never moved; the target is ignored for it. A moved pin takes effect only in a new session — tell the user to start one. An `aidemd-mcp` entry matches as the bare command or an absolute-path shim of it; a path-launched one may carry `tip`, an informational remark to mention once — never drift, never a merge question. Any other (custom) command under the `aide` key is left alone and reports `matches`. The brain entry is not part of the `mcp` step; a legacy brain launcher is changed only through the brain category's `brainChange: "launcher"` preview and apply, on the user's yes.
aide_infoBoot-time reporter called by the orchestrator at startup. Returns independent top-level fields that the orchestrator must branch on separately: **`outdated` (array of stale artifact keys) — soft notification.** Compares the host's `.aide/versions.json` against the canonical manifest shipped with this running server — never against the latest published version, so files that match the version the project runs are current even when a newer release exists. Each element names an artifact key that is behind. An empty array means everything is current. A missing `.aide/versions.json` (old install predating version tracking) silently collapses to `[]`. Staleness is informational — the orchestrator continues with a heads-up to the user. **`behind` (`{ installed, latest, launch, versionsBehind, highlights }` or null) — soft notification.** Non-null when the running server is older than the latest published version, whatever launch the project's `aide` entry uses — a global install or npx, pinned or not. `installed` is the running server's version. `launch` (`global` or `local`) picks the remedy: `global` → `npm i -g @aidemd-mcp/server@{latest}`; `local` → first install `latest` into the npx cache, then move the project's aide pin to it with `aide_upgrade({ category: "mcp", targetVersion: latest })`, never a hand edit of `.mcp.json`; if the install fails, switch nothing; once the newer server runs, `/aide:upgrade` offers to switch the entry to the global command. `versionsBehind` (1 or more) counts the published releases after `installed` up to `latest`; `highlights` holds 0–3 one-line notes of what they added or fixed (empty when the release notes were unavailable). Show the count and highlights briefly, never the changelog. Either upgrade takes effect only in a new session. It never gates the pipeline. Null when there is no `aide` entry, the running version is unknown, the server is current, or the version check could not run (offline checks pass silently). **`brainMigration` (`{ staleSections, legacyLauncher }` or null) — soft notification.** Non-null when the brain config has sections whose text matches an earlier template version, or a legacy brain launcher (`legacyLauncher` lists the reasons: npx-launch, unpinned, unversioned, older-pin, missing-auto-confirm). Mention it once and suggest `/aide:brain config`; it never gates the pipeline and never changes `brain.status`. **`brain` (precondition state) — hard gate.** Reports whether the host's brain MCP entry is wired and consistent. Shape: `{ status, name?, fault?, hints }` — `name` is absent on `no-brain-aide` and `brain-aide-invalid`; `fault` is present only on `brain-aide-invalid`. The orchestrator must halt and direct the user to resolve the issue before continuing if `status` is not `'ok'`. No path validation is performed — the package never stats any directory on disk; state derives entirely from comparing `.aide/config/brain.aide` against `.mcp.json`. The five `brain.status` values: - `ok` — `.aide/config/brain.aide` exists, satisfies the required-section contract, and the host's `.mcp.json` `brain` entry matches the parsed `mcpServerConfig`. `name` is the user-declared descriptive label from brain.aide. The pipeline may proceed. - `no-brain-aide` — `.aide/config/brain.aide` is absent. No `name` field. Remediation: run `/aide:brain config`, which creates the config. - `brain-aide-invalid` — the file exists but falls short. `fault.kind` is `missing-sections` (with `fault.sections` naming each missing required section) or `malformed` (with `fault.reason`). No `name` field. Remediation: run `/aide:brain config`. - `no-mcp-entry` — brain.aide parsed successfully but the host's `.mcp.json` is absent, malformed, or has no `mcpServers.brain` key. `name` is present. Remediation: run sync with the same launcher the project's `aide` MCP entry uses — `aidemd-mcp sync` when the project's `aide` MCP entry runs the globally installed `aidemd-mcp`, or `npx -y @aidemd-mcp/server@<version> sync` with the version that entry pins when it runs through npx. - `mcp-drift` — brain.aide and `.mcp.json` both exist but their `brain` entries disagree on `command` or `args`. `name` is present. Remediation: run sync with the same launcher the project's `aide` MCP entry uses — `aidemd-mcp sync` when the project's `aide` MCP entry runs the globally installed `aidemd-mcp`, or `npx -y @aidemd-mcp/server@<version> sync` with the version that entry pins when it runs through npx. `hints` is always present on every status — an array of candidate brain root paths the orchestrator can surface during recovery. No parameters needed — uses the server's working directory.
aide_brainOn-demand brain entry-point tool. Call this when you need to reach the brain mid-task — do NOT call it on every /aide boot. Boot-time brain precondition state is already reported by aide_info.brain.status; firing aide_brain at boot duplicates that work unnecessarily. It is also how a brain config is set up, repaired or written for any backend, one decision at a time. Every mode is read-only: no call writes to disk. **Optional `source` parameter** — which read runs. Omitted means `"host"`. - `"host"` — one section of the host's `.aide/config/brain.aide`, described below. - `"template"` — `{ template, purpose }`: one section of the bundled template (or its launcher, with `kind: "launcher"`) as verbatim bytes, and that section's one-line purpose from the published contract. The answer is the same whatever state the host's config is in. Use it as a worked example when writing that section for another backend. - `"contract"` — `{ sections }`: every contract section in order, each with `marker`, `role` (`live` or `seed`) and `purpose`, and no section text. - `"draft"` — a structural check of the draft config at `path`, with the same rules and fault vocabulary as the host config check, so a draft that passes is ready to swap in. Returns `{ outcome, instructions }`: `valid`; `invalid` with `fault` (`missing-sections` and its `sections`, or `malformed` and its `reason`); `absent` when no file is at `path`; `refused` when `path` is outside the project, and nothing is read. It checks structure, never content. **Optional `kind` parameter** — host and template reads only: any section marker of the published brain contract (see the enum), live or seed; `"launcher"` only with `source: "template"`. Omitting it means `"orientation"`, the runtime briefing for reaching the brain mid-task. `"config"` is the integration's wiring flow that `/aide:brain config` runs. Seed sections are fetched one per call while seeding. `path` is required with `source: "draft"` and accepted nowhere else; any other combination is rejected before the tool runs. **Host read response shape: exactly `{ status, instructions, found, purpose? }`.** No `backend`, no `connector`, no `name`, no `kind`. - `found: true` — `instructions` is that section's verbatim bytes from the host's `.aide/config/brain.aide`: no trimming, no normalization, no `${...}` substitution. `purpose` is that section's one-line purpose from the published contract; use it when adapting the section for another backend. - `found: false` — `instructions` is remediation, and `purpose` is absent. An absent file → run `/aide:brain config`. A requested section missing from the file → with the user's consent, call `aide_upgrade` with `category: "brain"`. A malformed or unreadable file → the exact fault, a hand fix with the user, then re-check with `aide_info`. Do not proceed as if the section were available. The section is returned on every status where the config exists and is well-formed, including `brain-aide-invalid` with missing sections, `no-mcp-entry` and `mcp-drift`. `status` mirrors the `BrainState` tagged union from `buildBrainState`, with five values: `ok`, `no-brain-aide`, `brain-aide-invalid`, `no-mcp-entry`, `mcp-drift`. Branch on `found` for "did I get the section" and on `status` for "is the brain healthy".
aide_initBootstrap 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-overwrite/would-skip/exists), `category`, and `filePath`, but NO `content` fields. Also returns `brainHints` (brain root candidates) and detected `framework`. Use this to understand what needs to be done and which categories require user prompts. **Second call (with `category` param):** The tool writes all `would-create` AND approved `would-overwrite` files directly to disk itself and returns a manifest — steps with `filePath`, `status` (`created`, `overwritten`, or `exists`), and `name`, but NO `content`. `would-skip` steps stay `would-skip` in the manifest (tool writes nothing for them). 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:** The `Brain config (brain.aide)` step carries `brainSummary` on every call, including the summary: `sections` (each section's `marker`, `role`, `seedPath` for seeds, and `templateBytes`), `missingSections`, `staleSections`, `legacyLauncher` reasons and `templateIntegration`. It never carries section text, purposes, repair blocks or before/after bodies. Missing sections are inserted with `aide_upgrade` `category: "brain"`, seeds are read one at a time with `aide_brain`, and migrations are previewed and applied one at a time through `aide_upgrade`. Sections the user edited and custom launchers are never offered. The tool creates `.aide/config/brain.aide` when it is absent and never overwrites an existing one. **Exception — session record:** The `Session record (session.aide)` step never carries content and the tool never writes it. When it is `would-create`, its `instructions` tell you to call `aide_scaffold` with directory "." and type "session" — do that, unprompted. When `.aide/session.aide` exists it is `exists` and is never overwritten. **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. **Agent branch logic — silent-on-create, prompt-on-overwrite:** After the first call, walk the categories using this rule: - **Pure-create category** (all steps are `would-create`, `would-skip`, or `exists`): apply silently by calling with `category=X` immediately — no AskUserQuestion. A category with nothing on disk to overwrite has no decision the user can inform. - **Overwrite-bearing category** (any step is `would-overwrite`): pause and use AskUserQuestion with structured options. Name the files that would be overwritten. If the user approves, call with `category=X` — the tool overwrites and returns `overwritten` in the manifest. If the user declines an overwrite but wants the new files, call with `category=X` — the tool writes only `would-create` steps; the `would-overwrite` step stays `would-overwrite` in the manifest. - **Inherent-decision categories** (framework, brain root path, MCP config merge, IDE choice): always use AskUserQuestion regardless of disk state. These are not file-write decisions — filesystem contents cannot resolve them. **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. 1. Call without `category` first to get the metadata 2. Present ONLY the detected framework — use AskUserQuestion with Yes/{alternatives} options. STOP. 3. Walk categories in order: methodology, commands, agents, skills, mcp, brain, ide, readme. For each: - Pure-create: apply silently (call with `category=X`), report results, move to next. - Overwrite-bearing: use AskUserQuestion naming the would-overwrite files. STOP. Wait for selection, then call with `category=X`. Report manifest (created N, overwrote M). Move to next. - Inherent decision: always use AskUserQuestion. STOP. 4. For brain: read `brainSummary` from the step, then direct the user to `/aide:brain config`. Call with `category=brain` only to receive the manifest; the tool creates `.aide/config/brain.aide` only when absent and never overwrites an existing one. 5. For MCP: when the aide step is would-create, its `globalPackage` names the aide server's global package. If `installed` is false, the step also carries `instructions`: act on them before merging — run its `installCommand` via Bash first — running AIDE's setup is the consent. If the install fails, tell the user plainly and stop: never merge an entry whose command is not installed. Then use AskUserQuestion with Merge/Skip and merge the `prescription` entry (the global `aidemd-mcp` command) into the existing config yourself (read → merge → write). Never replace an existing aide entry. STOP. 6. For IDE: use AskUserQuestion with multiSelect for Zed/VS Code/Neither. STOP. Each pause point is ONE AskUserQuestion → wait for selection → then proceed. Never show multiple categories at once. Never ask open-ended conversational questions.
aide_inspectReturn JSDoc, signature, and kind for a named symbol without opening the full file — Tier 2 progressive disclosure for code. When an agent knows a function name from an import list or orchestrator file, call inspect to learn what the symbol does, what it accepts, and what it returns, based on its contract alone. Searches across TypeScript and JavaScript source files (ts, tsx, js, jsx, mjs, cjs). Use the optional `file` parameter to narrow the search to a single file when the location is already known.
| aide_discover | 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, type tags and each spec's one-line description; a plan or todo tag carries its status, e.g. [plan: approved]. Only the head of each file is read. 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. | |
| aide_read | 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, inline references, URLs). Use this after aide_discover to drill into a specific spec. | |
| aide_scaffold | Create a new AIDE working file from its blank template, under its canonical name. It never overwrites: a request for a file that already exists, filled or empty, is a no-op reported as a skip line — remove a file first with aide_cleanup to replace it. New files start with their starting value: an intent spec alignment: unreviewed, a plan or todo list status: proposed. Handles the naming rules, so never pick a name yourself: in a module folder, 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. The project root intent spec always lands at .aide/intent.aide: pass directory ".aide" or "." (both mean the project's .aide folder for intent, research and both). A bare .aide/.aide left by an older project, with no intent.aide beside it, is renamed to .aide/intent.aide with its content kept; if .aide/intent.aide exists, nothing changes. Folders are never treated as spec files. A plan needs an intent spec beside it: scaffolding a plan in a folder with no intent spec (.aide or intent.aide; a research.aide alone does not count) is refused and creates nothing — write the folder's intent spec first. For a root-level plan, pass directory ".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; refused unless the folder already holds an intent spec - session — The project's session record, always at .aide/session.aide whatever directory you pass: the empty placeholder with every section heading. Its single source; never write the placeholder by hand. | |
| aide_cleanup | Remove a module's pipeline ephemerals (plan.aide, todo.aide, brief.aide) once that module's cycle has closed, leaving the code and the intent specs as the durable record. It never removes, rewrites or reads anything else: intent specs, research specs, code, and .aide/session.aide are all out of reach. Each file it would remove must record a closed status: completed (re-checked — every checkbox really checked) or abandoned. A file from before statuses existed, with no status but every checkbox checked, also passes. It refuses anything still proposed or approved, a completed file with an open item, a brief.aide with no plan.aide beside it, and a folder with no ephemerals. An abandoned plan takes its brief with it, and where there is no plan.aide a closed todo.aide is removed on its own. A refusal names each open file or item with its file and line, and nothing is removed. Record a closing status with aide_frontmatter first; this tool never sets or infers one. Call it directly, because the real call is already safe. dryRun is an optional preview for inspection only and is never a required step before the real call. This is the cross-platform replacement for a shell delete, so it can be permitted by name. | |
| aide_frontmatter | Read or change one governed frontmatter value of an AIDE file, leaving every other byte untouched. Intent specs carry alignment (unreviewed, aligned, misaligned). plan.aide, brief.aide and todo.aide carry one status lifecycle: proposed, approved, completed, abandoned. Only allowed moves are accepted, completed is refused while any item is unchecked or, for a brief, until its plan is completed, and a refusal names the allowed next values. Call with path alone to read a file's governed value without changing it. The session record, research specs and brain.aide carry no governed values. The tool never chooses a value; the caller decides. | |
| aide_validate | Health check for .aide spec files in the project. Detects orphaned specs (a spec whose folder, subfolders included, holds no code — only AIDE files, Markdown and dot-files; the project root intent spec in .aide/ is never orphaned, and a plan's presence never decides it), plans with no intent spec beside them (plan-without-spec — write the folder's spec, never delete the plan), 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), missing descriptions (specs with no description field in frontmatter), files whose frontmatter cannot be parsed, and intent specs whose alignment is missing (missing-alignment) or not one of unreviewed, aligned, misaligned (invalid-alignment). | |
| aide_upgrade | 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 `"unchanged"`), 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, a result that carries `prescription` is merged into the existing MCP config by you (read → merge → write). A result that carries `pinMove` or `globalSwitch` is never merged by hand: the tool writes it (see the MCP step). 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. 6. For `brain`, the summary reports `missingSections`, outdated section text as `staleSections` and a legacy brain launcher as `legacyLauncher` (its reasons), each named separately. The brain category then works through three calls, each one decision at a time: a. `category: "brain"` (after the user's yes) inserts every missing section from the latest bundled template — byte-identical, in the file's line endings — only when the config launches the template's own brain server. It returns `{ outcome: "inserted", inserted }` (markers only; empty when nothing is missing) or `{ outcome: "adapt", adapt, instructions }` naming the sections the user must write for their backend. b. `category: "brain"` with `brainChange: <marker | "launcher">` returns one `{ outcome: "change", target, before, after, beforeHash }` diff to show the user. It is read-only. For a non-template config it returns `missing` with the template's version of an absent section instead. c. The same call plus that `beforeHash`, only on the user's yes to that one diff, returns `applied`, or a `refused` re-fetch instruction when the bytes changed since the preview. Never batch changes under one yes. Every refusal's `instructions` names the next step. **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, brain. 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) - The user-owned brain config, only through the brain category: missing sections and confirmed migrations, one consented change at a time Supports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects the framework or accepts an override. **MCP step:** the canonical aide entry runs the global command `aidemd-mcp`. The entry is read under the `aide` key, or under `aidemd-mcp` when there is no `aide` key; the key is never renamed. Without `targetVersion`, an entry that launches through npx reports `differs` with `globalSwitch: { key, name, installed, installCommand }` and no prescription. Tell the user npx launches time out at session start and ask; on yes, run `installCommand` via Bash first unless `installed` is true (a failed install: say so and stop). Then `category: "mcp"` makes the tool rewrite only that entry's command and args to the global command, every other byte unchanged; it re-checks the global install and, while the package is missing, keeps `differs` and returns `instructions` naming the install command — install, then call again. A missing aide entry returns the global `prescription` plus `globalPackage`; when the package is not installed it also carries `instructions` — act on them: install first, then merge, and never merge after a failed install. An older server cannot switch itself, so a pinned project first moves its pin to a newer version with `targetVersion` (only under the `aide` key; an npx entry under `aidemd-mcp` gets `instructions` to call without `targetVersion` and switch instead) — an exact published `x.y.z`, normally `aide_info`'s `behind.latest`, valid only with no category or with `category: "mcp"`. With it, a local (npx) aide entry is judged by its version pin alone: an older, missing or non-exact pin reports `differs` with `pinMove: { from, to }` (`from` is null when unpinned) and no prescription; a pin at or ahead of the target `matches` and is never moved back. Install the target first (`npx -y @aidemd-mcp/server@{to} sync --help` prints help starting `Usage:` and exits 2 by design; anything else means the install failed — then stop and move nothing). Then `category: "mcp"` with the same `targetVersion` makes the tool write the move itself, changing only the version inside the package argument — the command form, `cmd /c`, `-y`, other servers, formatting and line endings stay byte-identical — and returns `status: "updated"` with `pinMove`. A result that keeps `status: "differs"` with `instructions` means nothing was written (the pin changed since it was checked, the config cannot be edited byte-safely, or the entry is not a locatable `@aidemd-mcp/server` spec): relay the instructions. A global entry is never moved; the target is ignored for it. A moved pin takes effect only in a new session — tell the user to start one. An `aidemd-mcp` entry matches as the bare command or an absolute-path shim of it; a path-launched one may carry `tip`, an informational remark to mention once — never drift, never a merge question. Any other (custom) command under the `aide` key is left alone and reports `matches`. The brain entry is not part of the `mcp` step; a legacy brain launcher is changed only through the brain category's `brainChange: "launcher"` preview and apply, on the user's yes. | |
| aide_info | Boot-time reporter called by the orchestrator at startup. Returns independent top-level fields that the orchestrator must branch on separately: **`outdated` (array of stale artifact keys) — soft notification.** Compares the host's `.aide/versions.json` against the canonical manifest shipped with this running server — never against the latest published version, so files that match the version the project runs are current even when a newer release exists. Each element names an artifact key that is behind. An empty array means everything is current. A missing `.aide/versions.json` (old install predating version tracking) silently collapses to `[]`. Staleness is informational — the orchestrator continues with a heads-up to the user. **`behind` (`{ installed, latest, launch, versionsBehind, highlights }` or null) — soft notification.** Non-null when the running server is older than the latest published version, whatever launch the project's `aide` entry uses — a global install or npx, pinned or not. `installed` is the running server's version. `launch` (`global` or `local`) picks the remedy: `global` → `npm i -g @aidemd-mcp/server@{latest}`; `local` → first install `latest` into the npx cache, then move the project's aide pin to it with `aide_upgrade({ category: "mcp", targetVersion: latest })`, never a hand edit of `.mcp.json`; if the install fails, switch nothing; once the newer server runs, `/aide:upgrade` offers to switch the entry to the global command. `versionsBehind` (1 or more) counts the published releases after `installed` up to `latest`; `highlights` holds 0–3 one-line notes of what they added or fixed (empty when the release notes were unavailable). Show the count and highlights briefly, never the changelog. Either upgrade takes effect only in a new session. It never gates the pipeline. Null when there is no `aide` entry, the running version is unknown, the server is current, or the version check could not run (offline checks pass silently). **`brainMigration` (`{ staleSections, legacyLauncher }` or null) — soft notification.** Non-null when the brain config has sections whose text matches an earlier template version, or a legacy brain launcher (`legacyLauncher` lists the reasons: npx-launch, unpinned, unversioned, older-pin, missing-auto-confirm). Mention it once and suggest `/aide:brain config`; it never gates the pipeline and never changes `brain.status`. **`brain` (precondition state) — hard gate.** Reports whether the host's brain MCP entry is wired and consistent. Shape: `{ status, name?, fault?, hints }` — `name` is absent on `no-brain-aide` and `brain-aide-invalid`; `fault` is present only on `brain-aide-invalid`. The orchestrator must halt and direct the user to resolve the issue before continuing if `status` is not `'ok'`. No path validation is performed — the package never stats any directory on disk; state derives entirely from comparing `.aide/config/brain.aide` against `.mcp.json`. The five `brain.status` values: - `ok` — `.aide/config/brain.aide` exists, satisfies the required-section contract, and the host's `.mcp.json` `brain` entry matches the parsed `mcpServerConfig`. `name` is the user-declared descriptive label from brain.aide. The pipeline may proceed. - `no-brain-aide` — `.aide/config/brain.aide` is absent. No `name` field. Remediation: run `/aide:brain config`, which creates the config. - `brain-aide-invalid` — the file exists but falls short. `fault.kind` is `missing-sections` (with `fault.sections` naming each missing required section) or `malformed` (with `fault.reason`). No `name` field. Remediation: run `/aide:brain config`. - `no-mcp-entry` — brain.aide parsed successfully but the host's `.mcp.json` is absent, malformed, or has no `mcpServers.brain` key. `name` is present. Remediation: run sync with the same launcher the project's `aide` MCP entry uses — `aidemd-mcp sync` when the project's `aide` MCP entry runs the globally installed `aidemd-mcp`, or `npx -y @aidemd-mcp/server@<version> sync` with the version that entry pins when it runs through npx. - `mcp-drift` — brain.aide and `.mcp.json` both exist but their `brain` entries disagree on `command` or `args`. `name` is present. Remediation: run sync with the same launcher the project's `aide` MCP entry uses — `aidemd-mcp sync` when the project's `aide` MCP entry runs the globally installed `aidemd-mcp`, or `npx -y @aidemd-mcp/server@<version> sync` with the version that entry pins when it runs through npx. `hints` is always present on every status — an array of candidate brain root paths the orchestrator can surface during recovery. No parameters needed — uses the server's working directory. | |
| aide_brain | On-demand brain entry-point tool. Call this when you need to reach the brain mid-task — do NOT call it on every /aide boot. Boot-time brain precondition state is already reported by aide_info.brain.status; firing aide_brain at boot duplicates that work unnecessarily. It is also how a brain config is set up, repaired or written for any backend, one decision at a time. Every mode is read-only: no call writes to disk. **Optional `source` parameter** — which read runs. Omitted means `"host"`. - `"host"` — one section of the host's `.aide/config/brain.aide`, described below. - `"template"` — `{ template, purpose }`: one section of the bundled template (or its launcher, with `kind: "launcher"`) as verbatim bytes, and that section's one-line purpose from the published contract. The answer is the same whatever state the host's config is in. Use it as a worked example when writing that section for another backend. - `"contract"` — `{ sections }`: every contract section in order, each with `marker`, `role` (`live` or `seed`) and `purpose`, and no section text. - `"draft"` — a structural check of the draft config at `path`, with the same rules and fault vocabulary as the host config check, so a draft that passes is ready to swap in. Returns `{ outcome, instructions }`: `valid`; `invalid` with `fault` (`missing-sections` and its `sections`, or `malformed` and its `reason`); `absent` when no file is at `path`; `refused` when `path` is outside the project, and nothing is read. It checks structure, never content. **Optional `kind` parameter** — host and template reads only: any section marker of the published brain contract (see the enum), live or seed; `"launcher"` only with `source: "template"`. Omitting it means `"orientation"`, the runtime briefing for reaching the brain mid-task. `"config"` is the integration's wiring flow that `/aide:brain config` runs. Seed sections are fetched one per call while seeding. `path` is required with `source: "draft"` and accepted nowhere else; any other combination is rejected before the tool runs. **Host read response shape: exactly `{ status, instructions, found, purpose? }`.** No `backend`, no `connector`, no `name`, no `kind`. - `found: true` — `instructions` is that section's verbatim bytes from the host's `.aide/config/brain.aide`: no trimming, no normalization, no `${...}` substitution. `purpose` is that section's one-line purpose from the published contract; use it when adapting the section for another backend. - `found: false` — `instructions` is remediation, and `purpose` is absent. An absent file → run `/aide:brain config`. A requested section missing from the file → with the user's consent, call `aide_upgrade` with `category: "brain"`. A malformed or unreadable file → the exact fault, a hand fix with the user, then re-check with `aide_info`. Do not proceed as if the section were available. The section is returned on every status where the config exists and is well-formed, including `brain-aide-invalid` with missing sections, `no-mcp-entry` and `mcp-drift`. `status` mirrors the `BrainState` tagged union from `buildBrainState`, with five values: `ok`, `no-brain-aide`, `brain-aide-invalid`, `no-mcp-entry`, `mcp-drift`. Branch on `found` for "did I get the section" and on `status` for "is the brain healthy". | |
| aide_init | 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-overwrite/would-skip/exists), `category`, and `filePath`, but NO `content` fields. Also returns `brainHints` (brain root candidates) and detected `framework`. Use this to understand what needs to be done and which categories require user prompts. **Second call (with `category` param):** The tool writes all `would-create` AND approved `would-overwrite` files directly to disk itself and returns a manifest — steps with `filePath`, `status` (`created`, `overwritten`, or `exists`), and `name`, but NO `content`. `would-skip` steps stay `would-skip` in the manifest (tool writes nothing for them). 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:** The `Brain config (brain.aide)` step carries `brainSummary` on every call, including the summary: `sections` (each section's `marker`, `role`, `seedPath` for seeds, and `templateBytes`), `missingSections`, `staleSections`, `legacyLauncher` reasons and `templateIntegration`. It never carries section text, purposes, repair blocks or before/after bodies. Missing sections are inserted with `aide_upgrade` `category: "brain"`, seeds are read one at a time with `aide_brain`, and migrations are previewed and applied one at a time through `aide_upgrade`. Sections the user edited and custom launchers are never offered. The tool creates `.aide/config/brain.aide` when it is absent and never overwrites an existing one. **Exception — session record:** The `Session record (session.aide)` step never carries content and the tool never writes it. When it is `would-create`, its `instructions` tell you to call `aide_scaffold` with directory "." and type "session" — do that, unprompted. When `.aide/session.aide` exists it is `exists` and is never overwritten. **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. **Agent branch logic — silent-on-create, prompt-on-overwrite:** After the first call, walk the categories using this rule: - **Pure-create category** (all steps are `would-create`, `would-skip`, or `exists`): apply silently by calling with `category=X` immediately — no AskUserQuestion. A category with nothing on disk to overwrite has no decision the user can inform. - **Overwrite-bearing category** (any step is `would-overwrite`): pause and use AskUserQuestion with structured options. Name the files that would be overwritten. If the user approves, call with `category=X` — the tool overwrites and returns `overwritten` in the manifest. If the user declines an overwrite but wants the new files, call with `category=X` — the tool writes only `would-create` steps; the `would-overwrite` step stays `would-overwrite` in the manifest. - **Inherent-decision categories** (framework, brain root path, MCP config merge, IDE choice): always use AskUserQuestion regardless of disk state. These are not file-write decisions — filesystem contents cannot resolve them. **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. 1. Call without `category` first to get the metadata 2. Present ONLY the detected framework — use AskUserQuestion with Yes/{alternatives} options. STOP. 3. Walk categories in order: methodology, commands, agents, skills, mcp, brain, ide, readme. For each: - Pure-create: apply silently (call with `category=X`), report results, move to next. - Overwrite-bearing: use AskUserQuestion naming the would-overwrite files. STOP. Wait for selection, then call with `category=X`. Report manifest (created N, overwrote M). Move to next. - Inherent decision: always use AskUserQuestion. STOP. 4. For brain: read `brainSummary` from the step, then direct the user to `/aide:brain config`. Call with `category=brain` only to receive the manifest; the tool creates `.aide/config/brain.aide` only when absent and never overwrites an existing one. 5. For MCP: when the aide step is would-create, its `globalPackage` names the aide server's global package. If `installed` is false, the step also carries `instructions`: act on them before merging — run its `installCommand` via Bash first — running AIDE's setup is the consent. If the install fails, tell the user plainly and stop: never merge an entry whose command is not installed. Then use AskUserQuestion with Merge/Skip and merge the `prescription` entry (the global `aidemd-mcp` command) into the existing config yourself (read → merge → write). Never replace an existing aide entry. STOP. 6. For IDE: use AskUserQuestion with multiSelect for Zed/VS Code/Neither. STOP. Each pause point is ONE AskUserQuestion → wait for selection → then proceed. Never show multiple categories at once. Never ask open-ended conversational questions. | |
| aide_inspect | Return JSDoc, signature, and kind for a named symbol without opening the full file — Tier 2 progressive disclosure for code. When an agent knows a function name from an import list or orchestrator file, call inspect to learn what the symbol does, what it accepts, and what it returns, based on its contract alone. Searches across TypeScript and JavaScript source files (ts, tsx, js, jsx, mjs, cjs). Use the optional `file` parameter to narrow the search to a single file when the location is already known. |
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableaidemd-mcp/server is public and reachablegithub.com/aidemd-mcp/server ↗Pass
- Package names this repository as its source@aidemd-mcp/server names aidemd-mcp/server as sourcenpmjs.com/package/@aidemd-mcp/server ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @aidemd-mcp/servernpmjs.com/package/@aidemd-mcp/server/v/0.15.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/aidemd-mcp/server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @aidemd-mcp/serverPass
- No critical advisory in the package or its dependencies141 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model11 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@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_scaffoldhandles the.aide/intent.aiderename 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 commandaidemd-mcp - Writes the bundled brain config template to
.aide/config/brain.aide(the brain location stays unset until/aide:brain configfills 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 plusaide-upgrader, which/aide:upgraderuns to migrate the project's own files) and thekanban-maintainerboard 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-treelauncher 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 <integration> 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-mcpmay not be found. Runwhich aidemd-mcpin 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.aidefile 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.aidefile(s) will be created.type(string, required): Type of file to create. One of:intent,research,both,todo,plan,session.sessionalways writes the project's session record at.aide/session.aide, whateverdirectorysays.
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):alignmentorstatus. Omit withvalueto 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 project when omitted.
aide_info
Boot-time precondition reporter. Returns two independent fields the orchestrator branches on separately: outdated (an array of stale AIDE artifact keys, comparing the project's versions.json against the shipped manifest), and brain (a { status, name?, hints } object reporting whether the project's brain.aide config is wired into .mcp.json). brain.status is a closed five-status union: ok | no-brain-aide | brain-aide-invalid | no-mcp-entry | mcp-drift, derived by comparing .aide/config/brain.aide against .mcp.json — no disk path validation. brain-aide-invalid means the file is present but unusable and carries a fault: either missing-sections (naming the required sections that are absent) or malformed (with a reason, which also covers a file that cannot be read). name is the user-declared label from brain.aide; it is absent on no-brain-aide and brain-aide-invalid. /aide:brain config is the recovery for both no-brain-aide and brain-aide-invalid. hints is an array of candidate vault locations the orchestrator can surface during recovery.
Inputs:
(none)
aide_brain
On-demand brain entry-point tool. Call this when you need to reach the brain mid-task — do NOT call it on every /aide boot. Boot-time brain precondition state is already reported by aide_info.brain.status; firing aide_brain at boot duplicates that work unnecessarily.
Returns { status, instructions } — exactly two fields. No backend, no connector, no name. status mirrors aide_info.brain.status (ok | no-brain-aide | brain-aide-invalid | no-mcp-entry | mcp-drift). instructions is always non-empty: on ok it is the verbatim body of the selected section (orientation or config, per the optional kind input) from the user's .aide/config/brain.aide (no server substitution); on the failure states it carries remediation prose. no-brain-aide and brain-aide-invalid both route to /aide:brain config; brain-aide-invalid is composed from the detector's fault — either the missing required sections, named, or the malformed reason (including a file that is present but unreadable, which is never reported as absent). no-mcp-entry and mcp-drift tell the user to run sync with the launcher their aide entry uses (aidemd-mcp sync or npx -y @aidemd-mcp/server@<version> sync).
Inputs:
(none)
aide_init
Bootstrap the AIDE development environment into a project using a guided one-at-a-time wizard. On the first call (no category), returns a summary of every step with status and detected framework. On subsequent calls (with category), writes all pending files for that category to disk and returns a manifest.
Inputs:
framework(string, optional): Force a specific framework instead of auto-detecting. One of:claude,cursor,windsurf,copilot.path(string, optional): Custom project root path. Defaults to the server working directory.category(string, optional): Write allwould-createfiles for this category and return a manifest. One of:framework,methodology,commands,agents,skills,mcp,brain,ide,readme. Omit on the first call to get a metadata-only summary.
The aide MCP entry always launches the global command aidemd-mcp. A would-create aide entry carries globalPackage; when it is not installed, the agent runs its installCommand before merging the entry.
aide_upgrade
Compare the AIDE methodology artifacts in this project against canonical versions and return a structured diff grouped by category. On the first call (no category), returns a lightweight summary of every category with drift status. On subsequent calls (with category), writes all diffed or missing files for that category to disk and returns a manifest.
Inputs:
framework(string, optional): Force a specific framework instead of auto-detecting. One of:claude,cursor,windsurf,copilot.path(string, optional): Custom project root path. Defaults to the server working directory.category(string, optional): Write all drifted or missing files for this category and return a manifest. One of:pointer-stub,methodology-docs,version-metadata,commands,agents,skills,mcp,ide,readme. Omit on the first call to get a metadata-only summary.
Getting Started
After adding the server to your MCP client, ask your agent to run aide_init to bootstrap the AIDE methodology into your project. This installs the methodology docs, scaffolds pipeline commands, and wires everything up.
Then try: "Scaffold an intent spec for my authentication module" — the agent will use aide_discover to map your project and aide_scaffold to create the spec in the right place with the right naming conventions.
Development
npm install
npm run build
npm test
License
AIDE MCP questions
How do I add AIDE MCP to Claude Code?
Run claude mcp add server -- npx -y @aidemd-mcp/server in your terminal. Add --scope user to make it available in every project.
How do I add AIDE MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does AIDE MCP provide?
It exposes 11 tools, including aide_discover, aide_read, aide_scaffold, aide_cleanup, aide_frontmatter.
Can I use this with Claude Desktop?
Yes, after installing the package globally, you can add the server entry to your Claude Desktop configuration file using the aidemd-mcp command.