# io.github.aidemd-mcp/server (npm · @aidemd-mcp/server)

MCP server that teaches any AI agent the AIDE methodology via progressive disclosure

- Trust score: 65/100 (medium)
- Change this week: +60
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-07

## Components

- npm · `@aidemd-mcp/server`: 65/100 (this document), [markdown](https://verifymcp.io/servers/aidemd-mcp-server/aidemd-mcp-server.md), [page](https://verifymcp.io/servers/aidemd-mcp-server/aidemd-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `@aidemd-mcp/server`
- Version: `0.9.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-07.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 44 of 136 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 76 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 56/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 3798 tokens (~422/item across 9 items; 9 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add aidemd-mcp-server -- npx -y @aidemd-mcp/server
```

### Codex

```bash
codex mcp add aidemd-mcp-server -- npx -y @aidemd-mcp/server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "aidemd-mcp-server": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@aidemd-mcp/server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add aidemd-mcp-server --command npx --arg -y --arg @aidemd-mcp/server
```

### Hermes

```yaml
mcp_servers:
  aidemd-mcp-server:
    command: "npx"
    args: ["-y", "@aidemd-mcp/server"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-07 (score 65, +3)

- [security improvement] Known CVEs: partial → pass
- [functional regression] Security disclosure: fail → unverified
- [functional] Dependency health: partial → 0.85

### 2026-08-05 (score 62, +26)

- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Schema quality: excellent
- [functional] First check of Schema quality: fail
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: fail

### 2026-08-04 (score 36, +1)

No change was recorded against any check on this day. Supply Chain Security went from 88 to 89.

### 2026-08-02 (score 35, +15)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Security disclosure: fail → unverified
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional] Capabilities: Protocol version not yet verified: we do not have a sandbox capture of the MCP handshake this version of the package performs yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Licence: MIT

### 2026-08-01 (score 20, +15)

- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: our sandbox run of this package did not complete, so we have no schema to compare.
- [functional] Schema quality: Schema quality not yet verified: our sandbox run of this package did not complete, so we have no schema to assess.
- [functional] Tool coverage: Tool coverage not yet verified: our sandbox run of this package did not complete, so we have no tool definitions to assess.
- [functional] Capabilities: Protocol version not yet verified: our sandbox run of this package did not complete, so we never saw its MCP handshake.

### 2026-07-31 (score 5, −1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 6, −18)

- [security regression] Malware scan: pass → unverified
- [functional] Tool coverage: Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- [functional] Schema quality: Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.

### 2026-07-27 (score 24)

First indexed and scored.

## MCP tools (9)

### `aide_discover` (~417 tokens)

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.

Input parameters:

- `path` (string): 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 —…

### `aide_read` (~87 tokens)

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.

Input parameters:

- `path` (string, required): Path to the .aide file to read

### `aide_scaffold` (~175 tokens)

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)

Input parameters:

- `directory` (string, required): Directory where the .aide file(s) will be created
- `type` (string, required): Type of .aide file to create

### `aide_validate` (~108 tokens)

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

Input parameters:

- `path` (string): Subdirectory to validate (defaults to entire project)

### `aide_upgrade` (~732 tokens)

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 —…

Input parameters:

- `category` (string): 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.
- `framework` (string): Force a specific framework instead of auto-detecting. Auto-detection checks for framework-specific files/directories and defaults to Claude Code.
- `path` (string): Custom project root path (defaults to server working directory)

### `aide_info` (~497 tokens)

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 work…

### `aide_brain` (~584 tokens)

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…

Input parameters:

- `kind` (string): Which 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_init` (~1046 tokens)

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…

Input parameters:

- `brainPath` (string): Resolved brain root path. Required when category=brain. The agent provides this after interviewing the user.
- `category` (string): 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 fi…
- `framework` (string): Force a specific framework instead of auto-detecting. Use this when re-calling after the user confirms or overrides detection.
- `path` (string): Custom project root path (defaults to server working directory)

### `aide_inspect` (~152 tokens)

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.

Input parameters:

- `file` (string): Optional file path to narrow search to a single file
- `name` (string, required): Symbol name to look up

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/aidemd-mcp-server/aidemd-mcp-server#diagnostics

## Score history

- 2026-08-07: 65
- 2026-08-06: 62
- 2026-08-05: 62
- 2026-08-04: 36
- 2026-08-03: 35
- 2026-08-02: 35
- 2026-08-01: 20
- 2026-07-31: 5
- 2026-07-30: 6
- 2026-07-28: 24
- 2026-07-27: 24

## Links

- npm package: https://www.npmjs.com/package/@aidemd-mcp/server
- Socket report: https://socket.dev/npm/package/@aidemd-mcp/server
- Repository: https://github.com/aidemd-mcp/server
- Changelog RSS feed: https://verifymcp.io/servers/aidemd-mcp-server/aidemd-mcp-server.xml
- Changelog JSON feed: https://verifymcp.io/servers/aidemd-mcp-server/aidemd-mcp-server.json
- HTML version of this page: https://verifymcp.io/servers/aidemd-mcp-server/aidemd-mcp-server