Skip to main content
Glama
deeneskoruzh
aidemd-mcp

aidemd-mcp/server

by aidemd-mcp
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

AIDE CI npm version License: MIT server MCP server npm downloads TypeScript Discord

@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

  • 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

Related MCP server: Foundry MCP

Installation

Quick Start (Claude Code)

The fastest path is a single npx command that wires everything up automatically:

npx @aidemd-mcp/server@latest init

This command:

  • Merges the AIDE MCP server entry into .mcp.json

  • Merges a placeholder brain MCP entry into .mcp.json (vault path filled in by /aide)

  • Writes every pipeline slash command to .claude/commands/aide/

  • Installs 9 canonical pipeline agents to .claude/agents/aide/

  • Installs skills (study-playbook, brain) 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.

Pass --vault-path <path> to record your brain vault location at install time, skipping the vault-path prompt when /aide first runs.

After running, open Claude Code and run /aide — the orchestrator will prompt for any setup the cli could not finish (IDE choice, vault path if not supplied).

Syncing brain.aide to .mcp.json

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

npx @aidemd-mcp/server@latest 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 vault path in mcpServerConfig.args:

Read .aide/brain.aide
Wrote brain MCP entry into .mcp.json
  command: npx
  args: [-y, obsidian-mcp, D:/notes/new-vault]
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

claude mcp add aide npx -- -y @aidemd-mcp/server@latest

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

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}
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

{
  "mcpServers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}
NOTE

Claude Desktop does not inherit the terminal PATH. If you use nvm or Homebrew to manage Node,npx may not be found. Run which npx in your terminal to get the absolute path and replace "npx" with it in the config above.

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

Cursor

Add to ~/.cursor/mcp.json:

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

VS Code / Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "aide": {
      "command": "npx",
      "args": ["-y", "@aidemd-mcp/server@latest"]
    }
  }
}
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:

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

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.

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 .aide file to create. One of: intent, research, both, todo, plan.

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, and missing frontmatter descriptions.

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 the four-state union ok | no-brain-aide | no-mcp-entry | mcp-drift, derived by comparing .aide/config/brain.aide against .mcp.json — no disk path validation. name is the user-declared label from brain.aide (only present on non-no-brain-aide states). 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 | no-mcp-entry | mcp-drift). instructions is always non-empty: on ok it is the verbatim ## Prose body from the user's .aide/config/brain.aide (no server substitution); on the failure states it carries fixed remediation prose naming the right CLI recovery command (npx @aidemd-mcp/server@latest init for no-brain-aide, npx @aidemd-mcp/server@latest sync for no-mcp-entry and mcp-drift).

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 all would-create files 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.

  • brainPath (string, optional): Resolved brain vault path. Required when category=brain.

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

MIT

Available Tools

9 tools
aide_brainA

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.

Optional kind parameter — closed two-value vocabulary: "orientation" (default) or "config".

  • "orientation" — returns the orientation section: a runtime briefing delivered when an agent reaches for the brain mid-task. Omitting kind is equivalent to passing "orientation".

  • "config" — returns the integration-specific wiring flow, used by /aide:brain config to walk through brain setup.

Install-time seed sections (playbookIndex, studyPlaybook, updatePlaybook, researchIndex) are NOT surfaced via this tool — agents reach those via the brain's read tool against the on-disk seed files.

Response shape: { status, instructions } — exactly two fields. No backend, no connector, no name, no kind.

status — mirrors the BrainState tagged union from buildBrainState. The four-state vocabulary: ok, no-brain-aide, no-mcp-entry, mcp-drift. Branch on status alone — no other discriminant is present.

instructions — always non-empty on every branch. Act on this field directly:

  • On ok: the verbatim bytes of the selected section from the host's .aide/config/brain.aide, byte-identical to what the user wrote between that section's markers. No trimming, no normalization, no ${...} substitution. The selected section takes over from here — the tool has no further role.

  • On no-brain-aide: fixed remediation prose directing the user to run npx @aidemd-mcp/server@latest init. Do not proceed as if the brain were available.

  • On no-mcp-entry: fixed remediation prose directing the user to run npx @aidemd-mcp/server@latest sync and restart Claude Code. Do not proceed as if the brain were available.

  • On mcp-drift: fixed remediation prose directing the user to run npx @aidemd-mcp/server@latest sync and restart Claude Code, explicitly forbidding the agent from patching .mcp.json itself.

Non-ok remediation prose is identical regardless of kind — the file is broken for both sections in the same way.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNoWhich section of brain.aide to return. `"orientation"` (default when omitted) returns the runtime briefing for mid-task brain access. `"config"` returns the integration-specific wiring flow used by `/aide:brain config`.

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It thoroughly details the response shape, four status states, instructions for each, and data integrity guarantees (no trimming, no substitution). Also notes that non-ok remediation is identical regardless of kind.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with headings and bullet points. Every sentence adds value, and the main purpose is front-loaded. No wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has 1 optional param, no output schema, no annotations. Description fully covers purpose, usage, response, edge cases, and remediation. Nothing missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds significant context: explains the two enum values, default behavior, and what each returns. Also details the response shape and status behavior beyond parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it is an on-demand brain entry-point tool for mid-task use, and distinguishes from sibling tools like aide_info by warning not to call at boot. It specifies the two optional kinds and their purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (mid-task) and when not to (boot), with an alternative given (aide_info.brain.status). Also explains the kind parameter choices and defaults.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_discoverA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoSubdirectory 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).

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: different responses based on path, ancestor chain with alignment status, summaries and warnings, and explains .aide file types. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer but well-structured with clear sections. Front-loaded main purpose. Could be slightly more concise, but every sentence adds value for this complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the description thoroughly explains the output structure (ancestor chain, subtree) and file types. Covers both modes comprehensively given the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single parameter 'path'. The description adds significant context beyond schema: different outcomes, ancestor chain structure, and usage scenarios, enhancing agent understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Scan' and the resource '.aide spec files', returning a 'tree map'. It distinguishes between two modes (with/without path), which differentiates it from siblings like aide_read and aide_inspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use without path (project-wide overview) and with path (drill into area). Does not explicitly state when not to use, but the progressive disclosure concept and file type explanations provide clear context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_infoA

Boot-time reporter called by the orchestrator at startup. Returns two 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 npm package. 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.

brain (precondition state) — hard gate. Reports whether the host's brain MCP entry is wired and consistent. Shape: { status, name?, hints }. 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 four brain.status values:

  • ok — .aide/config/brain.aide exists 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 missing or unparseable. No name field. Remediation: run /aide and complete the brain wiring interview.

  • 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 npx @aidemd-mcp/server@latest sync.

  • mcp-drift — brain.aide and .mcp.json both exist but their brain entries disagree on command or args. name is present. Remediation: run npx @aidemd-mcp/server@latest sync.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It thoroughly discloses all behaviors: no file system stats, silent collapse of missing files, remediation steps for each brain status, and the imperative to halt on non-ok status. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose but well-structured with headings and bullet points. It is front-loaded with purpose and then details. Some redundancy exists, but the organization aids readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations or output schema, the description comprehensively covers all aspects: return fields, status meanings, remediation, and constraints. An agent can fully understand tool behavior and context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters and full schema coverage, the description adds meaning by detailing the output fields and their semantics. It explains the two top-level fields and the four brain statuses, which is essential given no output schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the tool as a boot-time reporter returning two specific fields: outdated (stale artifact keys) and brain (precondition state). It differentiates itself from sibling tools like aide_brain or aide_discover by focusing on startup reporting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states it is called by the orchestrator at startup and provides branching logic for the two fields. While it doesn't mention when not to use it, the context is clear and no alternatives are suggested, which is acceptable for a unique boot-time reporter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_initA

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: When calling with category=brain, also pass brainPath with the user-confirmed brain root path. The tool creates the brain root 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.

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: use AskUserQuestion with brainHints as labeled options (user can pick Other for custom path). STOP. Then call with category=brain and brainPath.

  5. For MCP: use AskUserQuestion with Merge/Skip options. Merge the prescription entry into the existing config yourself (read → merge → write). 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoCustom project root path (defaults to server working directory)
categoryNoWrite all would-create and approved would-overwrite files for this category to disk and return a manifest (status: created/overwritten/exists; would-skip steps pass through unchanged). Omit on the first call to get a metadata-only summary of all steps.
brainPathNoResolved brain root path. Required when category=brain. The agent provides this after interviewing the user.
frameworkNoForce a specific framework instead of auto-detecting. Use this when re-calling after the user confirms or overrides detection.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations were provided, so the description carries full burden. It fully discloses that the tool writes files itself, returns structured JSON (not prose), uses progressive disclosure, handles overwrites and skips, and never touches MCP config directly. It also explains the exceptions for brain, IDE, and MCP steps. There is no contradiction with structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with bullet points and numbered steps. It front-loads the main purpose. While every sentence adds value, some sections (e.g., the detailed wizard pattern) could be slightly more compact without losing clarity. However, given the tool's complexity, this level of detail is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description comprehensively explains the return format (lightweight summary vs manifest), the two-call pattern, exceptions, and branch logic. It covers all four parameters and provides a step-by-step agent workflow. This is extremely complete for a tool with 4 parameters and no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds critical context beyond the schema: the purpose of the category parameter (first call omit, second call with category), the brainPath parameter (required when category=brain), and the framework parameter (force detection). It explains default behavior for path (server working directory) and clarifies the two-call pattern, which is not captured in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Bootstrap the AIDE development environment into a project.' This is a specific verb-resource combination that distinguishes it from sibling tools (e.g., aide_brain, aide_scaffold) by emphasizing the multi-step wizard pattern and progressive disclosure.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use and when-not-to-use guidance, including the two-call pattern, branch logic for categories (pure-create vs overwrite-bearing vs inherent-decision), and instructions to avoid summary tables or asking multiple questions at once. It also names alternative tools indirectly by specifying when the agent should use AskUserQuestion versus calling the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_inspectA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
fileNoOptional file path to narrow search to a single file
nameYesSymbol name to look up

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool operates without opening the full file (lightweight), and searches across multiple file extensions (ts, tsx, js, jsx, mjs, cjs). It could mention return format or performance constraints, but overall it is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences plus one additional sentence on file types) and front-loaded with the core functionality. Every sentence adds value, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the input and what is returned (JSDoc, signature, kind) adequately for a simple lookup tool. No output schema is needed; the description covers the return values. It fits well within the sibling tools context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters described. The description adds context beyond schema: it explains how to use the optional file parameter to narrow the search when location is known. This provides meaningful guidance beyond the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns JSDoc, signature, and kind for a named symbol without opening the full file, distinguishing it from siblings like aide_read which opens the full file. The verb 'inspect' and resource 'symbol' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises when to use this tool: when an agent knows a function name from an import list or orchestrator file. It also explains the optional file parameter for narrowing search. However, it does not explicitly state when not to use it or mention alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_readA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesPath to the .aide file to read

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It details the output structure (content, type, related specs, links), which goes beyond a minimal description. However, it does not mention error handling or read-only status, though that is implied.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: first defines functionality, second gives usage guidance. No unnecessary words, front-loaded with key details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (1 param, no output schema). The description fully explains the return value and usage context, making it complete for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning for the 'path' parameter beyond the schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'read', the resource '.aide spec file', and details the returned information (file content, type, related specs, links). It also explicitly distinguishes from sibling tool aide_discover.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to use this tool after aide_discover, providing clear context on when to use it versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_scaffoldA

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)

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYesType of .aide file to create
directoryYesDirectory where the .aide file(s) will be created

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses key behaviors: naming rules, auto-renaming of existing .aide files when creating research.aide, and the specific purpose of each type. It could mention potential side effects like overwriting, but the information is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a clear main sentence followed by bullet points for types. Every sentence contributes meaning without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema, no annotations), the description covers all necessary aspects: purpose, naming conventions, type meanings, and usage context. An agent can correctly select and invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds significant value beyond the schema by detailing each type's purpose and naming interactions, which helps the agent decide values for the 'type' parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates .aide spec files and enforces naming conventions. It explains the types and interactions, distinguishing it from sibling tools like aide_read or aide_validate, which are for different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for each type (intent, research, etc.) and when to use them, but does not explicitly state when not to use this tool or suggest alternatives. The sibling tools cover other operations, making usage relatively clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_upgradeA

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, 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.

  6. For brain, category=brain never writes; the manifest entry carries an instructions field directing the agent to invoke /aide:brain config, which is the single canonical home for brain.aide creation.

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)

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

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoCustom project root path (defaults to server working directory)
categoryNoWrite all differs/missing files for this category to disk and return a manifest. Omit on the first call to get a metadata-only summary of all categories.
frameworkNoForce a specific framework instead of auto-detecting. Auto-detection checks for framework-specific files/directories and defaults to Claude Code.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and excels. It discloses the two-call progressive disclosure pattern, that the tool writes files on second call, that the agent never sees file content, and detailed per-category behavior (e.g., brain never writes, mcp needs merge, ide may need VS Code command). It also covers auto-detection and framework support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but well-structured with clear sections (first call, second call, categories, upgrade surface). It front-loads the main purpose and then provides procedural details. While every sentence is useful, it could be slightly shorter without losing clarity. Still, it's appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (two-call pattern, multiple categories, special cases for brain/mcp/ide, framework detection), the description is remarkably complete. It covers usage pattern, constraints (no editing user specs), return format for each call, and agent responsibilities. No output schema, but the description compensates by detailing the manifest structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds significant context beyond the schema. It explains the meaning of omitting category (summary mode), how framework override works, and the two-call usage pattern. This justifies a score above baseline 3, though the schema already describes the parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: comparing AIDE methodology artifacts against canonical versions and returning structured JSON. It specifies what it is NOT for (editing user .aide specs), and outlines the two-call pattern with detailed steps. The verb 'upgrade' and resource 'AIDE methodology artifacts' are well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use triggers (user asks to update/sync/refresh AIDE) and when-not-to-use (not for editing user specs). It gives a step-by-step wizard pattern with AskUserQuestion, one-at-a-time categories, and special handling for mcp/ide/brain categories. This clearly distinguishes from sibling tools like aide_init or aide_scaffold.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

aide_validateB

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoSubdirectory to validate (defaults to entire project)

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior. It lists the specific checks performed, which is good, but it omits details about the output format, side effects, or whether any changes are made. The description is somewhat transparent but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence but front-loaded with the main purpose. It lists multiple items clearly separated by commas. Could be improved with bullet points, but it's reasonably concise and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (multiple checks) and the absence of an output schema, the description covers the input and the nature of the checks. However, it fails to describe what the tool produces (e.g., a report, exit code), which is important for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameter 'path' is documented in the schema. The description adds that it defaults to the entire project, which is a slight extension. This meets the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'health check' and resource '.aide spec files', and lists distinct detections like orphaned specs, missing specs, naming conflicts, etc. This clearly differentiates it from sibling tools like aide_init or aide_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or when not to use it. It simply states what it does.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.6.1
    • Addedaide_brain
    • Changedaide_init2 fields changed
      • changedInput schema / properties / brainPath / description
        Previous value: -"Resolved brain vault path. Required when category=brain. The agent provides this after interviewing the user."New value: +"Resolved brain root path. Required when category=brain. The agent provides this after interviewing the user."
      • changedInput schema / properties / category / description
        Previous value: -"Write all would-create files for this category to disk and return a manifest. Omit on the first call to get a metadata-only summary of all steps."New value: +"Write all would-create and approved would-overwrite files for this category to disk and return a manifest (status: created/overwritten/exists; would-skip steps pass through unchanged). Omit on the first call to get a metadata-only summary of all steps."
    • Addedaide_inspect
    • Changedaide_upgrade1 field changed
      • changedInput schema / properties / category / enum
        Previous value: -[
-  "pointer-stub",
-  "methodology-docs",
-  "version-metadata",
-  "commands",
-  "agents",
-  "skills",
-  "mcp",
-  "ide",
-  "readme"
-]New value: +[
+  "pointer-stub",
+  "methodology-docs",
+  "version-metadata",
+  "commands",
+  "agents",
+  "skills",
+  "mcp",
+  "ide",
+  "readme",
+  "brain"
+]
  2. 7 tool updatesv0.3.15
    • First observedaide_discover
    • First observedaide_info
    • First observedaide_init
    • First observedaide_read
    • First observedaide_scaffold
    • First observedaide_upgrade
    • First observedaide_validate
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation4/5

Each tool has a distinct purpose: brain (brain state), discover (overview), info (boot-time), init (environment bootstrap), inspect (code symbol), read (spec content), scaffold (create spec), upgrade (update methodology), validate (health check). Some overlap between read/discover and init/scaffold, but descriptions clarify their different roles.

Naming Consistency5/5

All tools follow a consistent 'aide_verb' pattern (aide_brain, aide_discover, aide_info, etc.). The verbs are descriptive and the naming is predictable, making it easy for an agent to infer tool purpose from the name alone.

Tool Count5/5

9 tools is well-scoped for a server focused on AIDE methodology management. Each tool fills a specific role without redundancy, covering discovery, reading, creation, validation, upgrade, and boot-time reporting.

Completeness4/5

The tool surface covers the main lifecycle of AIDE methodology files: discover, read, create (init & scaffold), update (upgrade), and validate. Missing functionality includes deletion of specs or artifacts, and there is no tool to modify existing user specs beyond the upgrade tool. Minor gaps but core workflows are supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Obsidian

    clavia-labs
    A
    license
    Not graded
    quality
    Not graded
    maintenance
    This is a connector to allow Claude Desktop (or any MCP client) to read and search any directory containing Markdown notes (such as an Obsidian vault).
    1,444
    1,352
    AGPL 3.0

  • Foundry MCP

    foundry-works
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables spec-driven development workflows with AI assistants, providing tools for managing specification lifecycles, task dependencies, code navigation, testing, and automated reviews through a unified CLI and MCP interface.
    4
    MIT

  • arch-viewer

    axumquant
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides AI-powered architecture analysis and visualization of codebases, exposing 17 MCP tools for querying components, dependencies, and generating interactive diagrams.
    1
    MIT
  • NEAT MCP Server by NEAT-Technologies

    NEAT MCP Serverofficial

    NEAT-Technologies
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides AI agents with a live architecture model of a codebase, enabling queries for root cause analysis, blast radius, and dependency traversal through MCP tools.
    238
    18
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aidemd-mcp/server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server