ADR 0030: Code-understanding companions — catalog graphify, document Understand-Anything

Summary

Two open-source "turn your repo into a queryable knowledge graph" tools fill the v4 researcher agent's cgb (code-graph-builder) slot: graphify (safishamsi/graphify, PyPI graphifyy) and Understand-Anything (Lum1104/Understand-Anything). Both are MIT-licensed, run inside the user's AI CLI, and are usable with or without aidokit.

This ADR draws the boundary: the MCP catalog lists MCP servers installed via a shell claude mcp add recipe; it does not list AI-CLI plugins. graphify is a real MCP server and stays catalogued (ADR-0015). Understand-Anything is a Claude Code / Copilot plugin installed via /plugin marketplace add + /plugin install (and platform installer scripts) — it has no claude mcp add shell recipe, so it does not fit MCPDef and is documented in the wiki as a recommended optional companion instead of being forced into the catalog.

It also corrects two accuracy issues found while evaluating graphify (see Decision §3).

Context

A user asked whether graphify and Understand-Anything are usable without aidokit and, if so, whether aidokit should integrate them. Findings:

• graphify — distributed on PyPI as graphifyy (CLI graphify). Parses code locally with tree-sitter (no API calls for code); only non-code content (docs, PDFs, images, video transcripts) goes through the user's configured AI model. Ships an MCP server. Already catalog entry #11 (ADR-0015).
• Understand-Anything — a multi-agent plugin that builds a knowledge graph and an interactive dashboard, exposing slash commands (/understand, /understand-chat, /understand-diff, …). Installed as a plugin:
• Claude Code: /plugin marketplace add Lum1104/Understand-Anything → /plugin install understand-anything
• Copilot CLI: copilot plugin install Lum1104/Understand-Anything:understand-anything-plugin
• Cursor / VS Code: auto-discovery; macOS/Linux/Windows installer scripts.
• No claude mcp add understand-anything -- … shell recipe is published.

aidokit's MCPDef (ADR-0007) models an MCP server by a per-adapter shell install.command. Understand-Anything's install is an in-session plugin command, not a shell MCP registration. Cataloguing it would require either faking a shell recipe that does not exist, or expanding the contract to model AI-CLI plugins — a new abstraction with its own lifecycle (/plugin vs claude mcp add), out of scope here and not requested.

The catalog already distinguishes its members from non-members: the --custom-url escape hatch and the "bring your own" wiki scenario exist precisely for tools that live outside the curated catalog. Understand-Anything belongs in that documented-but-not-catalogued space.

Decision

1. The MCP catalog is MCP-servers-only

An entry qualifies for @aidokit/mcp-catalog only if it is an MCP server installable by a deterministic per-adapter shell recipe (claude mcp add … -- …, a codex configBlock, etc.). AI-CLI plugins, marketplace extensions, and IDE add-ons that install via in-session commands (/plugin install) or bespoke installer scripts are not catalog members. They are documented in the wiki.

2. Understand-Anything is documented, not catalogued

A new wiki page (wiki/how-to-guides/code-understanding-graph.md) presents both options for the code-understanding / cgb slot:

• graphify — the catalogued MCP server (aidokit mcp add graphify), opt-in, security-sensitive.
• Understand-Anything — the recommended optional plugin, with the exact per-platform install commands and a clear note that it installs through the user's AI CLI plugin system, not through aidokit.

The page states plainly that aidokit makes zero LLM calls and does not install, run, or proxy either tool — both run inside the user's own CLI with the user's own credentials.

3. Correct two graphify accuracy issues

• Privacy framing. ADR-0015 and the catalog comment said graphify "sends content to an external model." More precisely: code is parsed locally (tree-sitter, no API); only non-code content uses the user's AI model. securitySensitive: true still holds (it reads the whole tree and sends non-code content off-host), but the description is corrected to avoid overstating the code-exfiltration risk. The catalog JSDoc is updated; this ADR is the authoritative correction to ADR-0015's framing (ADR-0015 content is preserved per the no-edit-history rule).
• Install command caveat. Upstream documents the MCP server as python -m graphify.serve graphify-out/graph.json (after uv tool install "graphifyy[mcp]"), i.e. it serves a pre-built graph. The catalog's zero-argument uvx graphifyy mcp was flagged for an upstream smoke-test rather than silently rewritten (a wrong guess is worse than a flagged one).

RESOLVED (smoke-tested 2026-06-09, Python 3.12 + uv 0.10.3): uvx graphifyy mcp was wrong on three counts — graphifyy is not an executable (the package exposes graphify / graphify-mcp), there is no mcp subcommand, and the server lives in the optional [mcp] extra. The correct, verified command is claude mcp add graphify -- uvx --from "graphifyy[mcp]" graphify-mcp. It serves over stdio and defaults graph_path to graphify-out/graph.json, so no path argument is needed — but it serves a pre-built graph, so the user must build one first (graphify's /graphify skill or graphify .) or the server exits with "Graph file not found". The catalog, spec §11.11, the reference table, and the wiki how-to are all updated to the verified command + the build-first runtime prerequisite.

4. No contract change, no new prereq

MCPDef is unchanged. ADR-0008 (no auto-install) and the Python-is-per-MCP decision (ADR-0015 §3) stand. Documenting a plugin adds no runtime surface.

Consequences

Positive

• Honest catalog boundary. A clear, reusable rule for what is and isn't a catalog entry; future plugin-shaped tools route to docs, not the catalog.
• Users get both tools. graphify via one command; Understand-Anything via documented per-platform install — neither requires aidokit.
• graphify framing is accurate. Code-local vs non-code-external is stated correctly; users can make an informed opt-in choice.

Negative

• Two tools, one slot, some choice burden. Users must pick. Mitigated by the wiki page giving a one-line "use graphify if you want a catalogued MCP; use Understand-Anything if you want the dashboard/plugin UX" steer.
• Understand-Anything isn't aidokit doctor-visible. Because it's not catalogued, doctor can't report it. Accepted: it's a plugin with its own lifecycle; aidokit shouldn't pretend to own it.
• graphify command remains unverified. Flagged, not fixed. Mitigated by the smoke-test note; a follow-up should verify against upstream and correct.

Neutral

• If a future tool ships both a plugin and a claude mcp add MCP server, only the server half qualifies for the catalog; the plugin half stays documented.

Alternatives considered

Alternative 1: Add Understand-Anything to the MCP catalog anyway

Write an MCPDef with a faked or plugin-ish install command.

Cons: there is no claude mcp add recipe; the install.command would be a lie or a non-MCP /plugin string that the per-adapter installer can't execute. Breaks the contract's meaning.

Reason rejected: the catalog's value is that every entry installs by a real deterministic recipe. A fake entry erodes that guarantee.

Alternative 2: Expand the contract to model AI-CLI plugins

Add a kind: 'mcp-server' | 'plugin' discriminator and a plugin install shape.

Pros: first-class plugin support; doctor visibility.

Cons: a new abstraction with its own lifecycle, per-adapter plugin-install semantics, and security model — speculative and unrequested. CLAUDE.md §8 warns against speculative contract expansion.

Reason rejected: premature. If demand for cataloguing plugins emerges, revisit with a dedicated ADR. One documented plugin does not justify a new contract.

Alternative 3: Document neither / catalog both

Either ignore both (loses real value) or catalog both (same contract violation as Alt 1 for Understand-Anything).

Reason rejected: the split (catalog the server, document the plugin) is the only option that respects the contract and still delivers both tools to users.

Validation

This decision is validated when:

• [x] wiki/how-to-guides/code-understanding-graph.md exists and lists graphify (catalogued) and Understand-Anything (plugin) with exact install commands.
• [x] The graphify catalog JSDoc states code-local / non-code-external. (Update: the MCP command was smoke-tested 2026-06-09 and corrected — see §3 RESOLVED.)
• [x] wiki/reference/mcp-catalog-reference.md and wiki/scenarios/bring-your-own.md link the new page.
• [x] No MCPDef for Understand-Anything is added (it is not an MCP server).
• [x] graphify's claude mcp add command smoke-tested and corrected to uvx --from "graphifyy[mcp]" graphify-mcp across catalog, spec, reference, wiki.

References

Internal

• ADR-0007 — MCP catalog shape (MCPDef, per-adapter shell install).
• ADR-0015 — graphify catalog entry (this ADR corrects its privacy framing).
• ADR-0008 — no auto-install of prereqs.
• packages/mcp-catalog/src/catalog.ts — the GRAPHIFY entry.
• wiki/scenarios/bring-your-own.md — the documented-but-not-catalogued space.

External

• graphify — https://github.com/safishamsi/graphify · https://pypi.org/project/graphifyy/
• Understand-Anything — https://github.com/Lum1104/Understand-Anything (MIT).