Skip to main content
Glama
aidemd-mcp

aidemd-mcp/server

by aidemd-mcp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

aide_upgrade

Compare AIDE methodology artifacts with canonical versions, report drift by category, then apply confirmed category updates to sync commands, agents, skills, MCP, IDE, and brain config.

Instructions

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, the summary reports missingSections, outdated section text as staleSections and a legacy brain launcher as legacyLauncher (its reasons), each named separately. The brain category then works through three calls, each one decision at a time: a. category: "brain" (after the user's yes) inserts every missing section from the latest bundled template — byte-identical, in the file's line endings — only when the config launches the template's own brain server. It returns { outcome: "inserted", inserted } (markers only; empty when nothing is missing) or { outcome: "adapt", adapt, instructions } naming the sections the user must write for their backend. b. category: "brain" with brainChange: <marker | "launcher"> returns one { outcome: "change", target, before, after, beforeHash } diff to show the user. It is read-only. For a non-template config it returns missing with the template's version of an absent section instead. c. The same call plus that beforeHash, only on the user's yes to that one diff, returns applied, or a refused re-fetch instruction when the bytes changed since the preview. Never batch changes under one yes. Every refusal's instructions names the next step.

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

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

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

  • AIDE pointer stub in the agent config file

  • Canonical methodology docs under .aide/docs/

  • versions.json metadata under .aide/docs/

  • Slash commands for all pipeline phases

  • Pipeline agent files, skill templates

  • MCP server entry in the project's MCP config

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

  • The user-owned brain config, only through the brain category: missing sections and confirmed migrations, one consented change at a time

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

MCP step: only AIDE's own launch forms for the aide entry are judged, and a prescription never switches the mode. An npx entry matches only when it is npx -y pinned to this server's version, so a differs there is how the pin moves forward deliberately. An aidemd-mcp entry matches as the bare command or an absolute-path shim of it; a path-launched one may carry tip, an informational remark to mention once — never drift, never a merge question. Any other (custom) command under the aide key is left alone and reports matches. The brain entry is not part of the mcp step; a legacy brain launcher is changed only through the brain category's brainChange: "launcher" preview and apply, on the user's yes.

Input Schema

NameRequiredDescriptionDefault
pathNoCustom project root path (defaults to server working directory)
categoryNoWhen provided, applies that category. For package-owned categories the call writes all differs/missing files to disk and returns a manifest (no canonicalContent). For `brain` it inserts missing sections (no `brainChange`), previews one change (`brainChange` alone), or applies it (`brainChange` + `beforeHash`); it never rewrites an existing section outside an applied change. When omitted, return all categories as metadata-only summaries (no canonicalContent fields).
frameworkNoForce a specific framework instead of auto-detecting. Auto-detection checks for framework-specific files/directories and defaults to Claude Code.
beforeHashNoThe `beforeHash` a `brainChange` preview returned. Turns the call into the guarded apply: the change is written only if the current bytes still hash to this value.
brainChangeNoBrain-category-only selector for one stale section (its marker) or the legacy launcher (`launcher`). Without `beforeHash` the call previews that one change read-only; with `beforeHash` it applies it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.11.1
    • addedInput schema / properties / beforeHash
      Added value: +{
+  "description": "The `beforeHash` a `brainChange` preview returned. Turns the call into the guarded apply: the change is written only if the current bytes still hash to this value.",
+  "type": "string"
+}
    • addedInput schema / properties / brainChange
      Added value: +{
+  "description": "Brain-category-only selector for one stale section (its marker) or the legacy launcher (`launcher`). Without `beforeHash` the call previews that one change read-only; with `beforeHash` it applies it.",
+  "enum": [
+    "orientation",
+    "config",
+    "playbook-index",
+    "study-playbook",
+    "update-playbook",
+    "research-index",
+    "kanban-index",
+    "kanban-create",
+    "kanban-work",
+    "kanban-manage",
+    "kanban-move",
+    "kanban-complete",
+    "kanban-stash",
+    "kanban-review",
+    "launcher"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / category / description
      Previous value: -"Write 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."New value: +"When provided, applies that category. For package-owned categories the call writes all differs/missing files to disk and returns a manifest (no canonicalContent). For `brain` it inserts missing sections (no `brainChange`), previews one change (`brainChange` alone), or applies it (`brainChange` + `beforeHash`); it never rewrites an existing section outside an applied change. When omitted, return all categories as metadata-only summaries (no canonicalContent fields)."
  2. Changed1 schema field changedv0.6.1
    • 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"
+]
  3. First observedv0.3.15

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the entire burden and does so: it discloses that the tool writes files to disk itself, that no canonicalContent is ever returned, the exact outcome shapes for the brain category, the beforeHash guard and refusal behavior on changed bytes, that user code and specs are never touched, and the MCP matching rules. This is unusually rich behavioral disclosure.

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?

Purpose and usage are front-loaded in the first two paragraphs, and given the tool's branching brain/mcp behavior, most sentences carry operational weight. It is nevertheless very long and includes recursive prose (the nested brain steps) that partly duplicates the schema's own descriptions, costing some crispness.

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 and no annotations, the description must cover returns and it does: manifests, statuses, outcome values, refusal instructions, and the mcp prescription/tip semantics. Combined with 100% parameter coverage, an agent has everything needed to call this correctly across all five parameters.

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%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains that omitting category yields metadata-only summaries, that the second call is what performs writes, and that brainChange alone previews while brainChange + beforeHash applies. The only shortfall is that it reads more as workflow narration than as per-parameter discrimination.

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?

States a specific verb and resource: compare AIDE methodology artifacts against canonical versions and return grouped JSON. It scopes the tool precisely, both positively (methodology infrastructure) and negatively (NOT user .aide specs), which cleanly separates it from sibling tools like aide_init, aide_cleanup, and aide_brain.

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?

Explicit triggers are listed (update AIDE, sync AIDE, refresh AIDE, check for updates), an exclusion is stated, and the full agent workflow — call without category, ask per category, repeat with category — is spelled out. The one-at-a-time wizard pattern with AskUserQuestion leaves no ambiguity about when and how to sequence calls.

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

Deploy Server

Other Tools