{
  "markdown": "[![AIDE](https://img.shields.io/badge/AIDE-intent--driven-0D9488?style=flat&logo=markdown&logoColor=white)](https://github.com/aidemd-mcp/server)\n[![CI](https://github.com/aidemd-mcp/server/actions/workflows/ci.yml/badge.svg)](https://github.com/aidemd-mcp/server/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@aidemd-mcp/server.svg)](https://www.npmjs.com/package/@aidemd-mcp/server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![server MCP server](https://glama.ai/mcp/servers/aidemd-mcp/server/badges/score.svg)](https://glama.ai/mcp/servers/aidemd-mcp/server)\n[![npm downloads](https://img.shields.io/npm/dm/@aidemd-mcp/server.svg)](https://www.npmjs.com/package/@aidemd-mcp/server)\n[![TypeScript](https://img.shields.io/badge/TypeScript-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![Discord](https://img.shields.io/discord/1496212051377262692?label=Discord&logo=discord)](https://discord.gg/N4NqMXuvTR)\n\n# @aidemd-mcp/server\n\nMCP server that brings intent-driven development to any AI-powered IDE.\nManage `.aide` spec files that live next to your code — the domain context\nthat architects plan from, implementors build from, and QA validates against.\n\nLearn more at [aidemd.dev](https://aidemd.dev).\n\n## Features\n\n- **Project-wide spec discovery** with a progressive disclosure tree that surfaces intent, research, and QA specs at every level of your codebase\n- **One-command project bootstrap** via `aide_init` — wires methodology docs, pipeline commands, and this MCP server into your project in a single guided flow\n- **Automatic naming convention enforcement** — `aide_scaffold` handles the `.aide` / `intent.aide` rename rules so you never create conflicting specs\n- **Health-check validation** via `aide_validate` — detects orphaned specs, missing descriptions, broken links, and naming conflicts before they cause drift\n- **Code introspection** via `aide_inspect` — returns JSDoc, signatures, and kind for named symbols without opening files, giving agents Tier 2 progressive disclosure for code\n- **Upgrade drift detection** via `aide_upgrade` — compares your project's AIDE methodology artifacts against canonical versions and writes updates per-category\n- **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\n\n## Installation\n\n### Quick Start (Claude Code)\n\nThe fastest path is a single npx command that wires everything up automatically:\n\n```bash\nnpx @aidemd-mcp/server@latest init\n```\n\nThis command:\n\n- Merges the AIDE MCP server entry into `.mcp.json`\n- Merges a placeholder brain MCP entry into `.mcp.json` (vault path filled in by `/aide`)\n- Writes every pipeline slash command to `.claude/commands/aide/`\n- Installs 9 canonical pipeline agents to `.claude/agents/aide/`\n- Installs skills (`study-playbook`, `brain`) to `.claude/skills/`\n- Installs the methodology docs hub to `.aide/docs/`\n- Writes the `aide-tree` launcher to `.aide/bin/aide-tree.mjs`\n- Adds an AIDE badge to `README.md` (appends if not present)\n\nAll operations are additive — files that already exist are never overwritten. Safe to re-run at any time.\n\nPass `--vault-path <path>` to record your brain vault location at install time, skipping the vault-path prompt when `/aide` first runs.\n\nAfter 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).\n\n### Syncing brain.aide to .mcp.json\n\nRun 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:\n\n```bash\nnpx @aidemd-mcp/server@latest sync\n```\n\n`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`.\n\nExample output after updating the vault path in `mcpServerConfig.args`:\n\n```\nRead .aide/brain.aide\nWrote brain MCP entry into .mcp.json\n  command: npx\n  args: [-y, obsidian-mcp, D:/notes/new-vault]\nDone.\n```\n\n### Manual Configuration\n\nIf you use a client other than Claude Code, or prefer to configure manually, add the server entry to your client's MCP config file.\n\n#### Claude Code\n\n```bash\nclaude mcp add aide npx -- -y @aidemd-mcp/server@latest\n```\n\nOr add to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"aide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aidemd-mcp/server@latest\"]\n    }\n  }\n}\n```\n\n> [!NOTE]\n> The Quick Start command above handles this automatically for Claude Code users.\n\n#### Claude Desktop\n\nConfig file locations:\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"aide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aidemd-mcp/server@latest\"]\n    }\n  }\n}\n```\n\n> [!NOTE]\n> 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.\n\nClaude Desktop requires a full quit-and-reopen after any config change.\n\n#### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"aide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aidemd-mcp/server@latest\"]\n    }\n  }\n}\n```\n\n#### VS Code / Copilot\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"aide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aidemd-mcp/server@latest\"]\n    }\n  }\n}\n```\n\n> [!NOTE]\n> VS Code / Copilot uses `\"servers\"` as the root key, not `\"mcpServers\"`. Using the wrong root key causes the server to silently fail to load.\n\n#### Windsurf\n\nAdd to `~/.windsurf/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"aide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aidemd-mcp/server@latest\"]\n    }\n  }\n}\n```\n\n## Tools\n\n### aide_discover\n\nScan the project for `.aide` spec files and return a progressive disclosure tree map showing each spec's type, location, and summary.\n\n**Inputs:**\n\n- `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).\n\n### aide_read\n\nRead 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.\n\n**Inputs:**\n\n- `path` (string, required): Path to the `.aide` file to read.\n\n### aide_scaffold\n\nCreate 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`.\n\n**Inputs:**\n\n- `directory` (string, required): Directory where the `.aide` file(s) will be created.\n- `type` (string, required): Type of `.aide` file to create. One of: `intent`, `research`, `both`, `todo`, `plan`.\n\n### aide_inspect\n\nReturn 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.\n\n**Inputs:**\n\n- `name` (string, required): Symbol name to look up.\n- `file` (string, optional): Restrict search to a single file (relative to project root).\n\n### aide_validate\n\nRun 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.\n\n**Inputs:**\n\n- `path` (string, optional): Subdirectory to validate. Defaults to the entire project when omitted.\n\n### aide_info\n\nBoot-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.\n\n**Inputs:**\n\n(none)\n\n### aide_brain\n\nOn-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.\n\nReturns `{ 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`).\n\n**Inputs:**\n\n(none)\n\n### aide_init\n\nBootstrap 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.\n\n**Inputs:**\n\n- `framework` (string, optional): Force a specific framework instead of auto-detecting. One of: `claude`, `cursor`, `windsurf`, `copilot`.\n- `path` (string, optional): Custom project root path. Defaults to the server working directory.\n- `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.\n- `brainPath` (string, optional): Resolved brain vault path. Required when `category=brain`.\n\n### aide_upgrade\n\nCompare 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.\n\n**Inputs:**\n\n- `framework` (string, optional): Force a specific framework instead of auto-detecting. One of: `claude`, `cursor`, `windsurf`, `copilot`.\n- `path` (string, optional): Custom project root path. Defaults to the server working directory.\n- `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.\n\n## Getting Started\n\nAfter 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.\n\nThen 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.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\n## License\n\n[MIT](https://github.com/aidemd-mcp/server/blob/main/LICENSE)\n",
  "bytes": 12834,
  "sha": "f65d304ebce0f61a8010532bed81ba880f610703ad6c870117b6b7125477b620",
  "repo_slug": "aidemd-mcp/server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aidemd_mcp_server_61c8cebb/readme"
}