@aidemd-mcp/server 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.aide/plan.aide +89 -160
  2. package/.aide/readme.aide +338 -0
  3. package/.aide/todo.aide +24 -35
  4. package/README.md +142 -31
  5. package/package.json +1 -1
package/.aide/plan.aide CHANGED
@@ -1,169 +1,98 @@
1
1
  ---
2
2
  intent: >
3
- Bring the aidemd-mcp codebase into alignment with the canonical docs updated
4
- in c32e887: five file types (adding plan), seven phase commands (adding
5
- synthesize) plus the /aide orchestrator, seven canonical docs plus index
6
- (adding plan-aide.md and todo-aide.md), todo.aide redefined as a QA
7
- re-alignment document, and discover tags including [plan].
3
+ Rewrite README.md to match the readme.aide spec — quick-install via
4
+ npx @aidemd-mcp/server init as recommended primary path, per-client manual
5
+ config blocks as fallback, full tool parameter documentation, badges,
6
+ features list, post-install block, and npm-safe rendering throughout.
8
7
  ---
9
8
 
10
9
  ## Plan
11
10
 
12
- - [x] **Step 1 — src/types/index.ts line 2: expand AideFileType union.**
13
- Change `"intent" | "research" | "todo"` to `"intent" | "research" | "todo" | "plan"`.
14
- Update the JSDoc comment on line 1 from "The three spec types plus QA checklist"
15
- to "The four spec types plus QA re-alignment document" (or equivalent wording
16
- that reflects five file types total with plan included). No other changes in
17
- this file.
18
-
19
- - [x] **Step 2 — src/util/classify/index.ts line 12-17: add plan.aide classification branch.**
20
- Add a branch `if (base === "plan.aide") return "plan";` before the final
21
- `return "intent"` fallback. Update the JSDoc on the function (lines 7-11) to
22
- list all five patterns: `.aide` or `intent.aide` -> "intent", `research.aide` ->
23
- "research", `todo.aide` -> "todo", `plan.aide` -> "plan". Order the branches
24
- so the specific named files are checked before the catch-all intent return:
25
- research, todo, plan, then fallback to intent.
26
-
27
- - [x] **Step 3 — src/tools/discover/buildTree/index.ts line 5: add plan to TYPE_ORDER.**
28
- Change `{ intent: 0, research: 1, todo: 2 }` to
29
- `{ intent: 0, research: 1, plan: 2, todo: 3 }`. Plan sorts after research
30
- (it is the architect's artifact derived from the intent) and before todo
31
- (which is the QA artifact). Update the JSDoc on line 4 to read:
32
- "Sort priority for file types: intent first, then research, plan, then todo."
33
- Also update the tree-rendering JSDoc on buildTree (line 34) to include `[plan]`
34
- in the tag list: `[intent]`, `[research]`, `[plan]`, `[todo]`.
35
-
36
- - [x] **Step 4 — src/tools/scaffold/index.ts: add plan type and template.**
37
- 4a. Line 8: change the Zod enum from `["intent", "research", "both", "todo"]` to
38
- `["intent", "research", "both", "todo", "plan"]`. Update the `.describe()` text
39
- to mention plan.
40
- 4b. Add a `PLAN_TEMPLATE` constant after the existing `TODO_TEMPLATE` (after
41
- line 43). Content should match the plan.aide spec format from
42
- `.aide/docs/plan-aide.md` — a minimal scaffold with frontmatter `intent` field
43
- and `## Plan` / `## Decisions` body sections:
44
- ```
45
- ---
46
- intent: >
47
-
48
- ---
49
-
50
- ## Plan
51
-
52
- - [ ]
53
-
54
- ## Decisions
55
-
56
- ```
57
- 4c. Line 67: change the `type` parameter signature from
58
- `"intent" | "research" | "both" | "todo"` to
59
- `"intent" | "research" | "both" | "todo" | "plan"`.
60
- 4d. Add a `plan` branch in the `if/else` chain (after the `todo` branch,
61
- before `intent`). It should mirror the todo branch exactly in structure:
62
- create `plan.aide` in the target directory using `PLAN_TEMPLATE`, push
63
- action "Created plan.aide". Plan is orthogonal to intent/research naming
64
- — no rename logic needed.
65
- 4e. Update the function-level JSDoc (lines 56-63) to document the new
66
- `type=plan` branch: "type=plan -> creates plan.aide".
67
-
68
- - [x] **Step 5 — src/tools/init/initContent/index.ts: add plan-aide, todo-aide docs
69
- and synthesize + aide orchestrator command entries.**
70
- 5a. DOC_PATHS (lines 34-47): add two methodology doc entries:
71
- `"plan-aide": ".aide/docs/plan-aide.md"` and
72
- `"todo-aide": ".aide/docs/todo-aide.md"`.
73
- Add two command entries:
74
- `"commands/aide/synthesize": ".claude/commands/aide/synthesize.md"` and
75
- `"commands/aide/aide": ".claude/commands/aide.md"` (the orchestrator lives
76
- at the commands root as `aide.md`, not inside the `aide/` subfolder — check
77
- that the path `.claude/commands/aide.md` resolves correctly relative to
78
- REPO_ROOT).
79
- Note: the orchestrator canonical template is at `.claude/commands/aide.md`
80
- which is a peer of the `aide/` folder, not inside it.
81
- 5b. METHODOLOGY_DOCS (lines 71-78): append two entries to the array:
82
- `{ canonical: "plan-aide", hostFilename: "plan-aide.md" }` and
83
- `{ canonical: "todo-aide", hostFilename: "todo-aide.md" }`.
84
- These go after the existing `automated-qa` entry and before the closing
85
- bracket. Keep insertion order matching the hub index reading order.
86
-
87
- - [x] **Step 6 — src/tools/init/scaffoldCommands/index.ts: add synthesize command
88
- and /aide orchestrator.**
89
- 6a. COMMANDS array (lines 30-37): add the synthesize phase command entry:
90
- `{ canonical: "commands/aide/synthesize", hostPath: "aide/synthesize.md", displayName: "aide:synthesize" }`.
91
- Insert it between the `spec` entry and the `plan` entry to match pipeline
92
- order: research, spec, synthesize, plan, build, qa, fix.
93
- 6b. Add the `/aide` orchestrator command entry:
94
- `{ canonical: "commands/aide/aide", hostPath: "aide.md", displayName: "aide" }`.
95
- **Important**: the orchestrator's `hostPath` is `"aide.md"` (at the command
96
- directory root), NOT `"aide/aide.md"` (inside the subfolder). It is a peer
97
- of the `aide/` subfolder. Place it as the first entry in the COMMANDS array
98
- so it is installed and reported before the seven phase commands.
99
- 6c. Update the JSDoc comment on lines 9-25: change "six AIDE pipeline slash
100
- commands" to "seven AIDE pipeline phase commands plus the /aide orchestrator
101
- entry point". Explain that the orchestrator is installed as `aide.md` at
102
- the command directory root (a peer of `aide/`), while phase commands go
103
- inside `aide/`. Update any references to "six" or "six-phase cap" to
104
- reflect the new count.
105
-
106
- - [x] **Step 7 — src/index.ts: update stale tool description strings.**
107
- 7a. `aide_discover` description (lines 34-35): where it lists file types,
108
- add the plan.aide type. The current text lists four types (.aide, intent.aide,
109
- research.aide, todo.aide). Add between research.aide and todo.aide:
110
- `- plan.aide -- Architect's implementation plan. Checkboxed steps for the implementor.`
111
- Also update the count text from "File types:" (which implies four) to
112
- explicitly name all five. Update the description of todo.aide from
113
- "QA checklist. Issues found by audit agents." to
114
- "QA re-alignment document. Captures where implementation drifted from intent."
115
- 7b. `aide_read` description (line 50): change the parenthetical
116
- `(intent/research/todo)` to `(intent/research/plan/todo)`.
117
- 7c. `aide_scaffold` description (lines 64-65): add `plan` to the Types list.
118
- Add a line: `- plan -- Architect's implementation plan (no naming interaction
119
- with intent/research)`. Also update the todo description from
120
- "QA checklist for audit agents" to
121
- "QA re-alignment document for QA agents".
122
- Update the Zod enum in the inputSchema (line 75) from
123
- `["intent", "research", "both", "todo"]` to
124
- `["intent", "research", "both", "todo", "plan"]`.
125
- 7d. `aide_init` description (lines 98-99): update the text that says
126
- "scaffolds slash commands for every pipeline phase (research, spec, plan,
127
- build, QA, fix)" to include synthesize:
128
- "scaffolds slash commands for every pipeline phase (research, spec,
129
- synthesize, plan, build, QA, fix) plus the /aide orchestrator entry point".
130
- Also ensure the methodology doc hub description mentions "seven canonical
131
- methodology docs" (not five or six). Update "six pipeline slash commands"
132
- references to "seven pipeline phase commands plus the /aide orchestrator".
11
+ ### 1. Write the complete README.md
12
+
13
+ Read: `coding-playbook/foundations/conventions`
14
+
15
+ This is a single-file documentation rewrite. The entire README is one cohesive
16
+ document where every section references and flows into the next. It cannot be
17
+ split across agents — section order, cross-references, and consistent voice
18
+ require a single pass. The implementor writes the full file using the structure
19
+ below, sourced entirely from the spec and the tool definitions in source.
20
+
21
+ **Read before writing:**
22
+ - The full spec at `.aide/readme.aide` (strategy, good/bad examples, all conventions)
23
+ - The tool definitions in `src/index.ts` lines 46-167 (exact parameter names, types, required/optional, enum values, descriptions)
24
+ - The current `README.md` (to understand what exists and what must change)
25
+
26
+ **Section order** (canonical MCP README order per spec):
27
+
28
+ - [x] 1a. **H1 + badges + description.** H1 is `# @aidemd-mcp/server`. Badges on the next line: npm version badge linking to npmjs.com/package/@aidemd-mcp/server, MIT license badge linking to opensource.org/licenses/MIT. Use shields.io badge URLs from the spec's good example. Description paragraph below badges — names the value (intent-driven specs next to code), not the mechanism (teaching). Must work as npm subtitle.
29
+
30
+ - [x] 1b. **Features bullet list.** H2 `## Features`. Three to five bullets naming capabilities from the user's perspective. No "What is AIDE?" explainer, no file-type table. Capabilities to highlight: project-wide spec discovery with progressive disclosure tree, one-command project bootstrap (`aide_init`), automatic naming convention enforcement, health-check validation for spec hygiene, upgrade drift detection for methodology artifacts. Keep each bullet to one line.
31
+
32
+ - [x] 1c. **Installation section with quick-install primary path and per-client manual fallback.** H2 `## Installation`.
33
+
34
+ **Quick Start (recommended) — lead the section with this.** Open with an H3 `### Quick Start (Claude Code)`. One sentence explaining this is the fastest path: a single npx command that wires everything up. Show the command in a bash code block:
35
+
36
+ ```
37
+ npx @aidemd-mcp/server init
38
+ ```
39
+
40
+ Below the code block, add a brief explanation of what the command does (three bullet points):
41
+ - Merges the AIDE MCP server entry into `.mcp.json` (creates or skips if already present)
42
+ - Writes the `/aide:init` slash command to `.claude/commands/aide/init.md` (skips if exists)
43
+ - Writes the `aide-tree` launcher to `.aide/bin/aide-tree.mjs` (skips if exists)
44
+
45
+ End with a one-liner: "All operations are idempotent — safe to re-run at any time." Then a transition sentence: "After running, open Claude Code and run `/aide:init` to complete setup."
46
+
47
+ **Manual Configuration (other clients or manual setup) — follows the quick-start.** Add an H3 `### Manual Configuration`. Open with a one-sentence intro: "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." Then one H4 per client, each with a copy-pasteable config block. Every block uses `npx -y @aidemd-mcp/server@latest`. Clients to cover in this order:
48
+
49
+ - **Claude Code** (H4) — CLI command (`claude mcp add aide npx -- -y @aidemd-mcp/server@latest`) plus `.mcp.json` JSON block with `"mcpServers"` root key. Note that the Quick Start command above handles this automatically.
50
+ - **Claude Desktop** (H4) — JSON block with `"mcpServers"` root key. Show both macOS (`~/Library/Application Support/Claude/claude_desktop_config.json`) and Windows (`%APPDATA%\Claude\claude_desktop_config.json`) config file paths above the block. Add a `> [!NOTE]` callout about PATH: Claude Desktop does not inherit the terminal PATH, so nvm/Homebrew users must use `which npx` to find the absolute path and replace `"npx"` with it. Add a one-line note that Claude Desktop requires a full quit-and-reopen after config changes.
51
+ - **Cursor** (H4) — JSON block with `"mcpServers"` root key. Note config file path (`~/.cursor/mcp.json`).
52
+ - **VS Code / Copilot** (H4) — JSON block with `"servers"` root key (NOT `"mcpServers"`). Note config file path (`.vscode/mcp.json`).
53
+ - **Windsurf** (H4) — JSON block with `"mcpServers"` root key. Note config file path (`~/.windsurf/mcp.json`).
54
+
55
+ All JSON blocks show the same server entry structure: `"command": "npx"`, `"args": ["-y", "@aidemd-mcp/server@latest"]`.
56
+
57
+ - [x] 1d. **Tools section with full parameter documentation.** H2 `## Tools`. One H3 per tool in lifecycle order: `aide_discover`, `aide_read`, `aide_scaffold`, `aide_validate`, `aide_init`, `aide_upgrade`. Each tool gets:
58
+ - Imperative one-sentence description (condensed from the tool `description` in `src/index.ts`)
59
+ - `**Inputs:**` bulleted list with backtick param name, (type), optional/required marker, and description
60
+ - Source all parameter details exactly from `inputSchema` in `src/index.ts` — do not invent parameters or omit any
61
+
62
+ Tool parameters to document (extracted from `src/index.ts`):
63
+ - `aide_discover`: `path` (string, optional) — subdirectory to drill into
64
+ - `aide_read`: `path` (string, required) — path to the .aide file
65
+ - `aide_scaffold`: `directory` (string, required), `type` (string, required — enum: intent, research, both, todo, plan)
66
+ - `aide_validate`: `path` (string, optional) — subdirectory to validate
67
+ - `aide_init`: `framework` (string, optional — enum: claude, cursor, windsurf, copilot), `path` (string, optional), `category` (string, optional — enum: framework, methodology, commands, agents, skills, mcp, brain, ide), `brainPath` (string, optional)
68
+ - `aide_upgrade`: `framework` (string, optional — enum: claude, cursor, windsurf, copilot), `path` (string, optional), `category` (string, optional — enum: pointer-stub, methodology-docs, version-metadata, commands, agents, skills, mcp, ide)
69
+
70
+ - [x] 1e. **Getting Started (post-install) block.** H2 `## Getting Started`. Short block telling the developer to run `aide_init` after adding the server, then try a concrete action. Use the spec's good example as the baseline.
71
+
72
+ - [x] 1f. **Development section.** H2 `## Development`. Three commands in a single code block: `npm install`, `npm run build`, `npm test`. Nothing else.
73
+
74
+ - [x] 1g. **License line.** H2 `## License`. One line: `MIT` — linked to the LICENSE file using an absolute GitHub URL (`https://github.com/aidemd-mcp/server/blob/main/LICENSE`).
75
+
76
+ **Rendering rules** (apply throughout all sections):
77
+ - No `<details>`/`<summary>` tags anywhere
78
+ - All cross-repo links use absolute GitHub URLs (base: `https://github.com/aidemd-mcp/server`)
79
+ - `> [!NOTE]` callouts are acceptable (degrade to blockquotes on npm)
80
+ - No relative links to files within the repo
133
81
 
134
82
  ## Decisions
135
83
 
136
- **plan sorts between research and todo in TYPE_ORDER.** Plan is the architect's
137
- artifact that follows research synthesis and precedes implementation + QA. This
138
- matches the pipeline ordering: research -> synthesize -> plan -> build -> qa.
139
- Todo is the QA output that comes last in the lifecycle.
140
-
141
- **The orchestrator /aide is a COMMANDS entry, not a separate mechanism.** The
142
- scaffoldCommands helper already handles idempotent command installation. The
143
- orchestrator is just another command file with a different hostPath (command
144
- directory root instead of aide/ subfolder). Adding it to the same COMMANDS array
145
- avoids a second installation path and keeps reporting consistent.
146
-
147
- **The orchestrator entry goes first in the COMMANDS array.** Pipeline reporting
148
- order should show the entry point before the phases it routes to. This matches
149
- the init spec's good-example output where `aide:` appears before `aide/research:`.
150
-
151
- **PLAN_TEMPLATE follows the plan.aide spec format, not the intent template format.**
152
- The plan.aide canonical spec defines frontmatter with `intent` only, plus
153
- `## Plan` and `## Decisions` body sections. The scaffold template mirrors this
154
- structure with empty placeholders, same as the TODO_TEMPLATE mirrors the todo
155
- format.
156
-
157
- **No changes to aide_validate or aide_read.** Both tools work off the
158
- AideFileType union and classifyFile, which are being updated in steps 1-2.
159
- They will automatically handle plan.aide files once the type system includes
160
- "plan". No tool-specific changes needed.
161
-
162
- **The "commands/aide/aide" canonical name uses `aide` as both namespace and
163
- basename.** This looks redundant but is mechanically correct: the canonical
164
- name prefix `commands/aide/` means "lives under .claude/commands/aide/" in
165
- the repo, and `aide` is the bare filename. The hostPath `aide.md` (without
166
- the `aide/` prefix) is what places it at the command directory root on the
167
- host side. The asymmetry between canonical path and host path is intentional
168
- — the canonical source lives inside the aide/ folder in the repo, but the
169
- host install places it as a peer of that folder.
84
+ 1. **Single step with lettered sub-steps.** The README is one file where every section depends on the overall structure, voice, and cross-references. Splitting into multiple agents would create inconsistency in tone, duplicate header work, or miss section flow. Lettered sub-steps let one agent write top-to-bottom while the plan still specifies each section's requirements independently.
85
+
86
+ 2. **No deep playbook dive for documentation.** The coding playbook governs code conventions, not prose documentation. The `foundations/conventions` note is included in the Read list for general naming/style awareness, but the spec itself (`readme.aide`) is the authoritative source for every README decision — section order, badge selection, config block format, tool documentation format, rendering constraints. The spec's strategy section is unusually detailed and research-backed; the plan defers to it entirely.
87
+
88
+ 3. **Parameters sourced from `src/index.ts`, not current README.** The current README has incomplete and outdated parameter lists (missing `plan` type in scaffold enum, missing `aide_upgrade` tool entirely, missing `category`/`brainPath` params on `aide_init`). The plan instructs the implementor to source all parameters from the `inputSchema` definitions in `src/index.ts` lines 46-167, which are the canonical source of truth.
89
+
90
+ 4. **VS Code uses `"servers"` root key.** Per the spec's research, VS Code/Copilot uses `"servers"` not `"mcpServers"`. This is the number one silent failure mode for cross-client config blocks. The plan calls this out explicitly.
91
+
92
+ 5. **`@latest` pinning in all config blocks.** Bare package names serve stale cached versions. Every config block uses `@aidemd-mcp/server@latest` with the `-y` flag to prevent npx from hanging in non-interactive contexts like Claude Desktop's process spawner.
93
+
94
+ 6. **PATH callout as `> [!NOTE]`, not `<details>`.** The spec requires the PATH troubleshooting to be visible on both GitHub and npm. GitHub `> [!NOTE]` renders as a styled callout and degrades to a plain blockquote on npm — both are readable. `<details>` would hide it on npm.
95
+
96
+ 7. **Quick-install command leads the Installation section.** `npx @aidemd-mcp/server init` is the recommended primary path because it eliminates three manual steps (MCP config, slash command, aide-tree) with a single idempotent command. It is scoped to Claude Code users — the primary audience per the spec's v1 scope note. The per-client manual config blocks move under a "Manual Configuration" H3 as the fallback for non-Claude-Code clients or users who prefer manual setup. This preserves all existing installation guidance while reducing time-to-value for the majority audience.
97
+
98
+ 8. **H3/H4 nesting for Installation.** Quick Start and Manual Configuration are H3s under the Installation H2. Individual clients under Manual Configuration are H4s. This keeps the Installation section scannable — a user on Claude Code sees the quick-start immediately and never needs to scroll past five client blocks. A user on Cursor jumps to Manual Configuration and finds their H4.
package/.aide/readme.aide ADDED
@@ -0,0 +1,338 @@
1
+ ---
2
+ scope: README.md
3
+ description: >
4
+ Spec for the @aidemd-mcp/server README — the primary conversion surface
5
+ on GitHub and npm that must turn visitors into installed users.
6
+ intent: >
7
+ The README is the single document that serves both GitHub repository
8
+ visitors and npm package page visitors. Its job is to convert a developer
9
+ who has heard of AIDE or stumbled on the package into an active user who
10
+ has the MCP server running in their IDE within five minutes. It must
11
+ communicate what the server does, how to install it in every supported
12
+ client, and what tools it provides — in that order, with no friction
13
+ that sends the visitor elsewhere for answers. The README is not a
14
+ methodology tutorial or a marketing page; it is a self-contained
15
+ installation guide with enough context to justify the install.
16
+ outcomes:
17
+ desired:
18
+ - A developer on any supported MCP client (Claude Code, Claude Desktop,
19
+ Cursor, VS Code / Copilot, Windsurf) finds a copy-pasteable config
20
+ block for their specific client, with the correct JSON root key, the
21
+ correct config file path, and @latest version pinning — no translation
22
+ from another client's example required.
23
+ - The tools section documents every tool with full parameter lists in
24
+ the canonical MCP README format (H3 per tool, imperative description,
25
+ bulleted Inputs with name/type/optional markers), so a developer
26
+ evaluating the server knows exactly what capabilities they get before
27
+ installing.
28
+ - A developer who has never heard of AIDE understands what the server
29
+ does and why it matters within the first two sentences — the title
30
+ line and description paragraph carry the pitch, not a separate
31
+ "What is AIDE?" explainer section.
32
+ - The README renders correctly on both GitHub and the npm package page,
33
+ avoiding constructs that break on npm (details/summary for critical
34
+ content, relative links, hover-only interactions).
35
+ - A post-install "what happens next" block gives the developer a
36
+ concrete first action to take inside their agent, closing the gap
37
+ between install and first value.
38
+ undesired:
39
+ - A config block that shows one client's format and expects users of
40
+ other clients to translate — the #1 documented friction source in
41
+ MCP server READMEs (mcp-readme-conventions research).
42
+ - A tool list without parameter documentation, forcing the developer
43
+ to install the server just to discover what inputs each tool accepts.
44
+ - A README that teaches the full AIDE methodology instead of focusing
45
+ on what the MCP server does and how to install it. The methodology
46
+ docs are delivered by aide_init; the README's job is to get the user
47
+ to that point, not to replace it.
48
+ - Content hidden inside details/summary tags that renders on GitHub
49
+ but is invisible or broken on the npm package page.
50
+ - A config block using a bare package name without @latest, which
51
+ silently serves a stale cached version to users who have previously
52
+ installed any version.
53
+ - A PATH-troubleshooting gap: omitting the nvm/Homebrew PATH failure
54
+ mode for Claude Desktop, which is the single most common MCP install
55
+ failure and silently loses users who blame themselves and give up.
56
+ ---
57
+
58
+ ## Context
59
+
60
+ The README serves two overlapping audiences arriving from two surfaces.
61
+ GitHub visitors are evaluating whether to adopt the tool — they scan the
62
+ repo, read the README top-to-bottom, and decide. npm visitors land on the
63
+ package page after finding `@aidemd-mcp/server` in search results or a
64
+ link — they see the README rendered by npm's markdown engine, which
65
+ supports less than GitHub (no collapsible details for critical content, no
66
+ relative links, degraded callout styling). Both audiences need the same
67
+ core information: what the server does, how to install it in their specific
68
+ client, and what tools it provides. Neither audience wants a methodology
69
+ tutorial — that is what `aide_init` delivers after the install.
70
+
71
+ The MCP ecosystem has a specific install friction profile. Each client
72
+ stores its config in a different file at a different path, and VS Code
73
+ uses a different JSON root key (`"servers"`) than every other client
74
+ (`"mcpServers"`). Users who copy a config block for the wrong client get
75
+ a silent failure. Claude Desktop has an additional failure mode: it does
76
+ not inherit the terminal's PATH, so users with nvm or Homebrew Node
77
+ installations get "command not found" errors that are never explained in
78
+ most MCP server READMEs. These are the documented friction points the
79
+ README must address head-on.
80
+
81
+ The server currently ships six tools (`aide_discover`, `aide_read`,
82
+ `aide_scaffold`, `aide_validate`, `aide_init`, `aide_upgrade`) plus a
83
+ `plan.aide` file type. With six tools, full parameter documentation is
84
+ feasible and preferred over a summary list — the tool count is small
85
+ enough that every parameter can be documented without the README becoming
86
+ unwieldy. This is the recommendation from the tool documentation research
87
+ for servers with ten or fewer tools.
88
+
89
+ ## Strategy
90
+
91
+ **Lead with a one-line description that names the value, not the
92
+ mechanism.** The H1 title is the package name; the line immediately below
93
+ it says what the server does for the developer, not how it works
94
+ internally. The current README opens with "MCP server that teaches any
95
+ agent the AIDE methodology" — this is close but should be tightened to
96
+ name the outcome (intent-driven specs next to code) rather than the
97
+ mechanism (teaching). The description must work as the npm package
98
+ subtitle, which is the only text a developer sees in search results
99
+ before clicking through (npm badge research).
100
+
101
+ **Badges signal legitimacy and version currency.** Place npm version and
102
+ MIT license badges immediately below the H1, before the description. Add
103
+ npm weekly downloads once the package has meaningful traction. Skip CI/build
104
+ badges — no MCP server README in the research corpus uses them, and the
105
+ audience does not expect them. A Smithery registry badge is worth adding
106
+ once the package is listed there, as it is a recognized quality signal in
107
+ the MCP ecosystem (mcp-readme-npm-badges research).
108
+
109
+ **Use a brief features bullet list, not a "What is AIDE?" section.** The
110
+ current README has a "What is AIDE?" section with a file-type table that
111
+ front-loads methodology detail before the install instructions. This
112
+ violates the canonical MCP README section order, which puts features
113
+ (brief) before installation (detailed). Replace the explainer with a
114
+ three-to-five-bullet feature list that names capabilities from the user's
115
+ perspective: project-wide spec discovery, one-command bootstrap, naming
116
+ convention enforcement, health-check validation, upgrade drift detection.
117
+ The file-type table belongs in the methodology docs that `aide_init`
118
+ installs, not in the README (mcp-readme-conventions research, section
119
+ order finding).
120
+
121
+ **Show a separate config block per client, not one block with a
122
+ footnote.** Use Pattern A from the conventions research: one H3 per
123
+ client under the Installation H2, each with its own copy-pasteable JSON
124
+ block showing the correct root key, the correct config file path, and
125
+ `@latest` version pinning. The clients to cover are Claude Code (CLI
126
+ command and .mcp.json), Claude Desktop (Mac and Windows paths), Cursor,
127
+ VS Code / Copilot (noting the `"servers"` root key difference), and
128
+ Windsurf. This is the largest section of the README and the most visited
129
+ — every character must be copy-pasteable without modification
130
+ (mcp-readme-config-blocks research, multi-client presentation finding).
131
+
132
+ **Pin to `@latest` in all config blocks.** Use `npx -y
133
+ @aidemd-mcp/server@latest` rather than a bare package name. The bare name
134
+ uses a locally cached version if one exists; `@latest` forces a fresh
135
+ resolution. This is the convention in community MCP servers and
136
+ communicates intent explicitly. Users who want reproducibility can pin in
137
+ their own config (mcp-readme-config-blocks research, version pinning
138
+ finding).
139
+
140
+ **Include the `-y` flag in npx args.** All official MCP server READMEs
141
+ use `npx -y` to auto-confirm the package install prompt. Omitting `-y`
142
+ causes npx to hang waiting for confirmation in non-interactive contexts
143
+ like Claude Desktop's process spawner, which is a silent install failure
144
+ (mcp-readme-conventions research).
145
+
146
+ **Add a PATH troubleshooting callout in the Claude Desktop section.**
147
+ Claude Desktop does not inherit the terminal PATH — users with
148
+ nvm/Homebrew Node hit "command not found: npx" and silently churn. A
149
+ blockquote callout (which degrades to a plain blockquote on npm — acceptable)
150
+ naming the problem and the fix (use `which npx` to find the absolute path)
151
+ addresses the single most common MCP install failure
152
+ (mcp-readme-config-blocks research, PATH problem finding; install-cta-mechanics
153
+ research, friction map finding).
154
+
155
+ **Note the Claude Desktop restart requirement.** Claude Desktop requires
156
+ a full quit-and-reopen for config changes to take effect. This is the #2
157
+ documented failure mode. A one-line note in the Claude Desktop section
158
+ prevents it (mcp-readme-config-blocks research, reload requirement finding).
159
+
160
+ **Document every tool with full parameters in the canonical format.** Use
161
+ H3 per tool inside a Tools H2. Each tool gets an imperative one-sentence
162
+ description and an Inputs bullet list with backtick name, (type, optional)
163
+ markers, and a description. Six tools is well within the feasibility
164
+ threshold for full documentation. Group by lifecycle phase if it helps
165
+ scanning: discover and read (navigation), scaffold and validate
166
+ (authoring), init and upgrade (project setup). Include the `plan.aide`
167
+ file type in the tool documentation for `aide_scaffold` since it was added
168
+ after the current README was written (mcp-readme-tool-documentation
169
+ research, canonical format finding).
170
+
171
+ **Add a post-install "try it" block.** After the Tools section, include a
172
+ short block that tells the developer what to do after installing: "Run
173
+ `aide_init` in your agent to bootstrap the AIDE methodology into your
174
+ project, then try `/aide` to start the pipeline." This closes the
175
+ install-to-value gap that silently loses users in dev-tool landings
176
+ (install-cta-mechanics research, post-install hand-off finding).
177
+
178
+ **Keep the Development section minimal.** Three commands (install, build,
179
+ test) in a code block. No contributing guide, no changelog — those belong
180
+ in separate files if needed. The README is for users, not contributors
181
+ (mcp-readme-conventions research, building section finding).
182
+
183
+ **Use absolute URLs for any cross-repo links.** Relative links work on
184
+ GitHub but break on the npm package page. Any link to files within the
185
+ repo (LICENSE, methodology docs) must use the full GitHub URL
186
+ (mcp-readme-npm-badges research, npm rendering finding).
187
+
188
+ **Avoid details/summary tags for any content a visitor needs to see.**
189
+ They are broken on npm. Use flat sections instead. The `> [!NOTE]`
190
+ callout syntax is acceptable — it renders as a styled callout on GitHub
191
+ and degrades to a readable blockquote on npm (mcp-readme-npm-badges
192
+ research, npm rendering finding).
193
+
194
+ ## Good examples
195
+
196
+ A strong opening that names the value:
197
+
198
+ > # @aidemd-mcp/server
199
+ >
200
+ > [![npm version](https://img.shields.io/npm/v/@aidemd-mcp/server.svg)](https://www.npmjs.com/package/@aidemd-mcp/server)
201
+ > [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
202
+ >
203
+ > MCP server that brings intent-driven development to any AI-powered IDE.
204
+ > Manage `.aide` spec files that live next to your code — the domain context
205
+ > that architects plan from, implementors build from, and QA validates against.
206
+
207
+ A per-client config block that eliminates translation friction:
208
+
209
+ > ### Claude Code
210
+ >
211
+ > ```bash
212
+ > claude mcp add aide npx -- -y @aidemd-mcp/server@latest
213
+ > ```
214
+ >
215
+ > Or add to your project's `.mcp.json`:
216
+ >
217
+ > ```json
218
+ > {
219
+ > "mcpServers": {
220
+ > "aide": {
221
+ > "command": "npx",
222
+ > "args": ["-y", "@aidemd-mcp/server@latest"]
223
+ > }
224
+ > }
225
+ > }
226
+ > ```
227
+ >
228
+ > ### VS Code / Copilot
229
+ >
230
+ > Add to `.vscode/mcp.json`:
231
+ >
232
+ > ```json
233
+ > {
234
+ > "servers": {
235
+ > "aide": {
236
+ > "command": "npx",
237
+ > "args": ["-y", "@aidemd-mcp/server@latest"]
238
+ > }
239
+ > }
240
+ > }
241
+ > ```
242
+
243
+ A tool documented in the canonical format:
244
+
245
+ > ### aide_discover
246
+ >
247
+ > Scan the project for `.aide` spec files and return a progressive disclosure
248
+ > tree map showing each spec's type, location, and summary.
249
+ >
250
+ > **Inputs:**
251
+ > - `path` (string, optional): Subdirectory to drill into. When provided,
252
+ > opens with the ancestor chain — the cascading intent lineage from root
253
+ > to target — followed by the detailed subtree. When omitted, returns a
254
+ > project-wide map.
255
+
256
+ A post-install block that bridges install to first value:
257
+
258
+ > ## Getting Started
259
+ >
260
+ > After adding the server to your MCP client, ask your agent to run
261
+ > `aide_init` to bootstrap the AIDE methodology into your project. This
262
+ > installs the methodology docs, scaffolds pipeline commands, and wires
263
+ > everything up.
264
+ >
265
+ > Then try: "Scaffold an intent spec for my authentication module" — the
266
+ > agent will use `aide_discover` to map your project and `aide_scaffold`
267
+ > to create the spec in the right place with the right naming conventions.
268
+
269
+ ## Bad examples
270
+
271
+ A README that opens with a methodology explainer before the install block:
272
+
273
+ > ## What is AIDE?
274
+ >
275
+ > AIDE (Autonomous Intent-Driven Engineering) is a methodology that puts
276
+ > intent at the center of everything. It uses a three-layer model...
277
+ > [300 words of methodology detail]
278
+ >
279
+ > ## Installation
280
+ > ...
281
+
282
+ The visitor wanted to install, not to study. The methodology detail
283
+ belongs in the docs that `aide_init` delivers, not in the README that
284
+ must convince the visitor to install. By the time they reach the config
285
+ block, they have either scrolled past or left.
286
+
287
+ A single config block labeled "Add to your MCP client config" with the
288
+ `mcpServers` root key and no per-client guidance:
289
+
290
+ > ```json
291
+ > {
292
+ > "mcpServers": {
293
+ > "aide": {
294
+ > "command": "npx",
295
+ > "args": ["@aidemd-mcp/server"]
296
+ > }
297
+ > }
298
+ > }
299
+ > ```
300
+
301
+ A VS Code user pastes this into `.vscode/mcp.json`, where the root key
302
+ should be `"servers"`, not `"mcpServers"`. The server silently fails to
303
+ load. The user assumes the package is broken and moves on. Meanwhile, the
304
+ `-y` flag is missing, so Claude Desktop users get a hung npx prompt they
305
+ never see. Two silent failures from one config block.
306
+
307
+ A tool list without parameters:
308
+
309
+ > - **aide_discover** — Scans for .aide files
310
+ > - **aide_scaffold** — Creates new .aide files
311
+ > - **aide_validate** — Validates .aide files
312
+
313
+ The developer evaluating this server cannot tell what inputs each tool
314
+ accepts, whether paths are required or optional, or what the `type`
315
+ enum values are for scaffold. They must install the server and call the
316
+ tools to find out. A developer comparing this against another MCP server
317
+ that documents its parameters fully will choose the documented one.
318
+
319
+ A README that uses `<details>` tags to collapse the per-client config
320
+ blocks:
321
+
322
+ > <details>
323
+ > <summary>Claude Desktop</summary>
324
+ > [config block]
325
+ > </details>
326
+
327
+ On the npm package page, the details/summary tags are broken — the
328
+ content is either always expanded or invisible depending on npm's
329
+ renderer version. The most-visited section of the README is now
330
+ inaccessible on one of the two primary surfaces the README serves.
331
+
332
+ ## References
333
+
334
+ - `research/mcp-readme/mcp-readme-conventions` -- Canonical section order (title, badges, features, install, tools, dev, license) and the Pattern A multi-client presentation finding that drives the per-client config block strategy.
335
+ - `research/mcp-readme/mcp-readme-config-blocks` -- The `mcpServers` vs `"servers"` root key difference, `@latest` version pinning recommendation, PATH troubleshooting requirement for Claude Desktop, and the restart-after-config-change requirement.
336
+ - `research/mcp-readme/mcp-readme-tool-documentation` -- The canonical tool documentation format (H3 per tool, imperative description, bulleted Inputs), the full-documentation recommendation for servers with fewer than 10 tools, and the tool annotations pattern.
337
+ - `research/mcp-readme/mcp-readme-npm-badges` -- Badge placement convention (below H1, before description), recommended badge stack (version + license minimum), npm rendering constraints (no details/summary, absolute URLs required, callout degradation acceptable).
338
+ - `research/aidemd-dev/install-cta-mechanics` -- The MCP install friction map (config location confusion, reload requirement, PATH inheritance failure, cross-client ambiguity), the post-install "try it" block pattern from Stripe/shadcn precedent, and the v1 scope note confirming Claude Code as primary target.
package/.aide/todo.aide CHANGED
@@ -1,47 +1,36 @@
1
1
  ---
2
2
  intent: >
3
- Canonical docs updated in c32e887 (orchestrator, synthesize phase, plan.aide
4
- spec, todo.aide spec, expanded file-type table, seven-doc hub) but downstream
5
- .aide intent specs still reference the pre-commit state: four file types
6
- instead of five, six pipeline commands instead of seven-plus, five canonical
7
- docs instead of seven, and todo.aide described as a "QA queue" instead of a
8
- re-alignment document. The specs no longer faithfully reflect the methodology
9
- they are supposed to deliver.
3
+ README.md rewrite against readme.aide spec. One outcome violated: the Quick
4
+ Start block omits @latest from the npx command, which can serve a stale
5
+ cached version of the CLI init subcommand to users who have previously
6
+ installed any version of the package.
10
7
  misalignment:
11
- - implementation-drift
8
+ - plan-gap
12
9
  ---
13
10
 
14
11
  ## Issues
15
12
 
16
- - [x] **src/.aide:21** — Teaches "the four file types" in tool descriptions; canonical `aide-spec.md` now defines five file types (`.aide`, `intent.aide`, `research.aide`, `plan.aide`, `todo.aide`).
17
- Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
18
-
19
- - [x] **src/.aide:149-152** — Good example describes `todo.aide` as "a QA queue". Canonical docs redefine it as a "QA re-alignment document" with misalignment tags and a `## Retro` section.
20
- Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
21
-
22
- - [x] **src/tools/init/.aide:33-34** — References "six pipeline slash commands (research, spec, plan, build, qa, fix)". Canonical pipeline now includes a synthesize phase (`/aide:synthesize`) and an orchestrator entry point (`/aide`).
23
- Traces to: `outcomes.desired[3]` | Misalignment: `implementation-drift`
24
-
25
- - [x] **src/tools/init/.aide:194-209** — Good examples list exactly six scaffolded commands and six "already present" lines. Missing synthesize phase; summary shape no longer matches what init actually produces after the doc update.
26
- Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
27
-
28
- - [x] **src/tools/init/scaffoldCommands/.aide:1-4** — Intent says "six AIDE pipeline slash commands (research, spec, plan, build, qa, fix)" and enforces a six-cap throughout. The canonical pipeline now has seven phase commands (adding synthesize). The "six-cap" language on lines 20, 81, 114, 116 is all stale.
29
- Traces to: `outcomes.desired[3]` | Misalignment: `implementation-drift`
30
-
31
- - [x] **src/tools/init/installMethodologyDocs/.aide:101** — Context says "five canonical files under `docs/`". The hub index now lists seven docs (added `plan-aide.md` and `todo-aide.md`). The number "five" also appears in the bad-examples section (line 255) and good-examples section (line 198).
32
- Traces to: `outcomes.desired[1]` | Misalignment: `implementation-drift`
33
-
34
- - [x] **src/tools/discover/.aide:23** — Type tags listed as `[intent]`, `[research]`, `[todo]`. Missing `[plan]` tag for the new `plan.aide` file type.
35
- Traces to: `outcomes.desired[2]` | Misalignment: `implementation-drift`
36
-
37
- - [x] **src/tools/scaffold/.aide:1-28** — Supports types: intent, research, both, todo. Does not support `type=plan` for creating `plan.aide` files. The canonical `aide-spec.md` file-type table now includes `plan.aide` as a first-class file type that scaffold should know how to create.
38
- Traces to: `outcomes.desired[1]` | Misalignment: `implementation-drift`
13
+ - [ ] **README.md:25** — Quick Start block uses `npx @aidemd-mcp/server init` without `@latest`. The spec requires `@latest` on all npx invocations ("use `npx -y @aidemd-mcp/server@latest` rather than a bare package name. The bare name uses a locally cached version if one exists"). The plan carried this omission forward (plan.aide line 34 shows `npx @aidemd-mcp/server init` without `@latest`), meaning the gap originated at planning, not implementation.
14
+ Traces to: `outcomes.undesired[4]` ("A config block using a bare package name without @latest, which silently serves a stale cached version to users who have previously installed any version") | Misalignment: `plan-gap`
39
15
 
40
16
  ## Retro
41
17
 
42
- Every issue traces to a single cause: the canonical docs were updated in one commit but the downstream `.aide` specs that encode the same facts were not updated in the same commit. The commit changed the source of truth; the renderers of that truth were left behind.
18
+ The spec's `@latest` requirement was written with config blocks in mind and the
19
+ strategy section explicitly mentions "config blocks" as the scope ("all config
20
+ blocks"). The plan correctly applied `@latest` to every JSON config block under
21
+ Manual Configuration, but silently dropped it from the Quick Start CLI command,
22
+ treating the CLI invocation as exempt from the rule.
23
+
24
+ The gap is plan-level: the planner read the `@latest` requirement as scoped
25
+ only to JSON config blocks and did not apply it to the `npx @aidemd-mcp/server
26
+ init` CLI command. The spec's good examples show `npx -y
27
+ @aidemd-mcp/server@latest` consistently, including for CLI invocations, but
28
+ the spec's strategy text says "config blocks" — the ambiguity created a
29
+ loophole that the plan exploited.
43
30
 
44
31
  What would have caught this earlier:
45
- - A pre-commit check (or a QA pass scoped to `.aide` files) that runs `aide_validate` and flags specs whose file-type counts, command counts, or doc counts disagree with the canonical docs.
46
- - A convention that any commit touching `.aide/docs/` also touches every downstream `.aide` that references the changed facts — enforced by review checklist, not tooling, until tooling can do it.
47
- - The orchestrator `/aide` could have been used to drive the doc change itself, which would have surfaced the propagation gap at the plan stage before code was written.
32
+ - The plan step for the Quick Start block should have explicitly cross-checked
33
+ the `@latest` and `-y` conventions from the spec's strategy section and
34
+ applied them to the CLI command, not just to the JSON blocks.
35
+ - A QA checklist item "verify every `npx` invocation in the README (not just
36
+ JSON blocks) uses `@latest`" would have caught this mechanically.
package/README.md CHANGED
@@ -1,41 +1,130 @@
1
1
  # @aidemd-mcp/server
2
2
 
3
- MCP server that teaches any agent the AIDE (Autonomous Intel-Driven Engineering) methodology. When an agent connects, the tool descriptions themselves teach the convention — no config or documentation injection needed.
3
+ [![npm version](https://img.shields.io/npm/v/@aidemd-mcp/server.svg)](https://www.npmjs.com/package/@aidemd-mcp/server)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4
5
 
5
- ## What is AIDE?
6
+ MCP server that brings intent-driven development to any AI-powered IDE.
7
+ Manage `.aide` spec files that live next to your code — the domain context
8
+ that architects plan from, implementors build from, and QA validates against.
6
9
 
7
- AIDE specs are `.aide` files that live next to orchestrator code as progressive disclosure specs. They capture the domain context that code alone doesn't — strategy, research, implementation contracts, and anti-patterns.
10
+ ## Features
8
11
 
9
- | File | Purpose |
10
- |------|---------|
11
- | `.aide` | Intent spec (default). Strategy, contracts, anti-patterns. |
12
- | `intent.aide` | Same as `.aide` — used only when `research.aide` exists in the same folder. |
13
- | `research.aide` | Raw research. Sources, data points, pattern synthesis. |
14
- | `todo.aide` | QA checklist. Issues found by audit agents. |
12
+ - **Project-wide spec discovery** with a progressive disclosure tree that surfaces intent, research, and QA specs at every level of your codebase
13
+ - **One-command project bootstrap** via `aide_init` — wires methodology docs, pipeline commands, and this MCP server into your project in a single guided flow
14
+ - **Automatic naming convention enforcement** — `aide_scaffold` handles the `.aide` / `intent.aide` rename rules so you never create conflicting specs
15
+ - **Health-check validation** via `aide_validate` — detects orphaned specs, missing descriptions, broken links, and naming conflicts before they cause drift
16
+ - **Upgrade drift detection** via `aide_upgrade` — compares your project's AIDE methodology artifacts against canonical versions and writes updates per-category
15
17
 
16
18
  ## Installation
17
19
 
18
- Add to your MCP client config:
20
+ ### Quick Start (Claude Code)
21
+
22
+ The fastest path is a single npx command that wires everything up automatically:
23
+
24
+ ```bash
25
+ npx @aidemd-mcp/server@latest init
26
+ ```
27
+
28
+ This command:
29
+ - Merges the AIDE MCP server entry into `.mcp.json` (creates the file or skips the entry if already present)
30
+ - Writes the `/aide:init` slash command to `.claude/commands/aide/init.md` (skips if exists)
31
+ - Writes the `aide-tree` launcher to `.aide/bin/aide-tree.mjs` (skips if exists)
32
+
33
+ All operations are idempotent — safe to re-run at any time.
34
+
35
+ After running, open Claude Code and run `/aide:init` to complete setup.
36
+
37
+ ### Manual Configuration
38
+
39
+ 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.
40
+
41
+ #### Claude Code
42
+
43
+ ```bash
44
+ claude mcp add aide npx -- -y @aidemd-mcp/server@latest
45
+ ```
46
+
47
+ Or add to your project's `.mcp.json`:
48
+
49
+ ```json
50
+ {
51
+ "mcpServers": {
52
+ "aide": {
53
+ "command": "npx",
54
+ "args": ["-y", "@aidemd-mcp/server@latest"]
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ > [!NOTE]
61
+ > The Quick Start command above handles this automatically for Claude Code users.
62
+
63
+ #### Claude Desktop
64
+
65
+ Config file locations:
66
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
67
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
19
68
 
20
69
  ```json
21
70
  {
22
71
  "mcpServers": {
23
72
  "aide": {
24
73
  "command": "npx",
25
- "args": ["@aidemd-mcp/server"]
74
+ "args": ["-y", "@aidemd-mcp/server@latest"]
26
75
  }
27
76
  }
28
77
  }
29
78
  ```
30
79
 
31
- Or with a custom project root:
80
+ > [!NOTE]
81
+ > 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.
82
+
83
+ Claude Desktop requires a full quit-and-reopen after any config change.
84
+
85
+ #### Cursor
86
+
87
+ Add to `~/.cursor/mcp.json`:
32
88
 
33
89
  ```json
34
90
  {
35
91
  "mcpServers": {
36
92
  "aide": {
37
93
  "command": "npx",
38
- "args": ["@aidemd-mcp/server", "--root", "/path/to/project"]
94
+ "args": ["-y", "@aidemd-mcp/server@latest"]
95
+ }
96
+ }
97
+ }
98
+ ```
99
+
100
+ #### VS Code / Copilot
101
+
102
+ Add to `.vscode/mcp.json`:
103
+
104
+ ```json
105
+ {
106
+ "servers": {
107
+ "aide": {
108
+ "command": "npx",
109
+ "args": ["-y", "@aidemd-mcp/server@latest"]
110
+ }
111
+ }
112
+ }
113
+ ```
114
+
115
+ > [!NOTE]
116
+ > VS Code / Copilot uses `"servers"` as the root key, not `"mcpServers"`. Using the wrong root key causes the server to silently fail to load.
117
+
118
+ #### Windsurf
119
+
120
+ Add to `~/.windsurf/mcp.json`:
121
+
122
+ ```json
123
+ {
124
+ "mcpServers": {
125
+ "aide": {
126
+ "command": "npx",
127
+ "args": ["-y", "@aidemd-mcp/server@latest"]
39
128
  }
40
129
  }
41
130
  }
@@ -43,41 +132,59 @@ Or with a custom project root:
43
132
 
44
133
  ## Tools
45
134
 
46
- ### `aide_discover`
135
+ ### aide_discover
136
+
137
+ Scan the project for `.aide` spec files and return a progressive disclosure tree map showing each spec's type, location, and summary.
138
+
139
+ **Inputs:**
140
+ - `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).
47
141
 
48
- Scans the project for all `.aide` files and returns a progressive disclosure tree map. This is the flagship tool — it teaches the agent the entire module architecture at a glance.
142
+ ### aide_read
49
143
 
50
- **Input:** optional `path` (subdirectory to scan)
144
+ 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.
51
145
 
52
- **Output:** Tree showing each spec's type, location, and summary.
146
+ **Inputs:**
147
+ - `path` (string, required): Path to the `.aide` file to read.
53
148
 
54
- ### `aide_read`
149
+ ### aide_scaffold
55
150
 
56
- Reads an `.aide` file with context awareness. Returns the file content, classified type, sibling specs in the same directory, and links found in the content (wikilinks, relative paths, URLs).
151
+ 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`.
57
152
 
58
- **Input:** `path` (required)
153
+ **Inputs:**
154
+ - `directory` (string, required): Directory where the `.aide` file(s) will be created.
155
+ - `type` (string, required): Type of `.aide` file to create. One of: `intent`, `research`, `both`, `todo`, `plan`.
59
156
 
60
- ### `aide_scaffold`
157
+ ### aide_validate
61
158
 
62
- Creates new `.aide` files with automatic naming convention enforcement. Handles auto-rename logic — creating a `research.aide` will rename an existing `.aide` to `intent.aide`.
159
+ 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.
63
160
 
64
- **Input:** `directory` (required), `type` (required: `intent` | `research` | `both` | `todo`)
161
+ **Inputs:**
162
+ - `path` (string, optional): Subdirectory to validate. Defaults to the entire project when omitted.
65
163
 
66
- ### `aide_validate`
164
+ ### aide_init
67
165
 
68
- Health check for `.aide` spec files. Detects orphaned specs, missing specs, naming conflicts, broken links, and orphaned research files.
166
+ 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.
69
167
 
70
- **Input:** optional `path` (subdirectory to validate)
168
+ **Inputs:**
169
+ - `framework` (string, optional): Force a specific framework instead of auto-detecting. One of: `claude`, `cursor`, `windsurf`, `copilot`.
170
+ - `path` (string, optional): Custom project root path. Defaults to the server working directory.
171
+ - `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`. Omit on the first call to get a metadata-only summary.
172
+ - `brainPath` (string, optional): Resolved brain vault path. Required when `category=brain`.
71
173
 
72
- ### `aide_init`
174
+ ### aide_upgrade
73
175
 
74
- Bootstrap the AIDE development environment into a project with one command. Detects the agent framework, writes the AIDE methodology into the agent's config file, scaffolds slash commands for every pipeline phase (`/aide-research`, `/aide-spec`, `/aide-synthesize`, `/aide-plan`, `/aide-build`, `/aide-qa`, `/aide-fix`, `/aide-refactor`), and wires this MCP server into the project's MCP config.
176
+ 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.
75
177
 
76
- Supports Claude Code, Cursor, Windsurf, and Copilot. Auto-detects from marker files or accepts an override.
178
+ **Inputs:**
179
+ - `framework` (string, optional): Force a specific framework instead of auto-detecting. One of: `claude`, `cursor`, `windsurf`, `copilot`.
180
+ - `path` (string, optional): Custom project root path. Defaults to the server working directory.
181
+ - `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`. Omit on the first call to get a metadata-only summary.
77
182
 
78
- **Input:** optional `framework` (`claude` | `cursor` | `windsurf` | `copilot`), optional `path` (project root)
183
+ ## Getting Started
79
184
 
80
- Each step is idempotent — running on an already-initialized project reports what's present without overwriting.
185
+ 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.
186
+
187
+ 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.
81
188
 
82
189
  ## Development
83
190
 
@@ -86,3 +193,7 @@ npm install
86
193
  npm run build
87
194
  npm test
88
195
  ```
196
+
197
+ ## License
198
+
199
+ [MIT](https://github.com/aidemd-mcp/server/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aidemd-mcp/server",
3
- "version": "0.2.3",
3
+ "version": "0.2.4",
4
4
  "description": "MCP server that teaches any agent the AIDE methodology through tool descriptions and progressive disclosure tooling",
5
5
  "type": "module",
6
6
  "bin": {