ADR 0015: Add graphify to the MCP Catalog (opt-in, security-sensitive)

Field Value
Status Accepted (implemented in commit cab08b3, v1.0-rc2)
Date 2026-05-23
Deciders Project maintainers
Supersedes —
Superseded by —
Related ADRs 0007 (MCP catalog shape), 0008 (Prereq install policy), 0005 (Adapter contract)

Summary

Add graphify (PyPI graphifyy) to the @aidokit/mcp-catalog as the 8th catalog entry, filling the v4 kit's cgb (code-graph-builder) MCP slot referenced by the researcher.md agent. The entry is marked securitySensitive: true and trigger: 'never' — it is opt-in only, never auto-suggested by stack-pack or detector triggers, and never auto-installed. Python remains a project-level prerequisite for any user who opts in; aidokit does not add Python to its own prereq list, and ADR-0008's no-auto-install policy applies unchanged.

Context

The v4 kit's researcher agent declares a cgb MCP for dependency-topology and impact analysis (kit Part 3 §47). The v0.5 MCP catalog has no entry that fills this slot, leaving researcher flows without code-graph capability out of the box.

graphify is a candidate: it turns a repository into a queryable knowledge graph and ships an MCP server plus a /graphify skill. It runs inside the user's AI CLI, not from aidokit itself, so it does not affect aidokit's zero-LLM-calls rule.

Three properties make it non-trivial to add:

  1. Python dependency. graphify is distributed on PyPI as graphifyy. The current prereq model (ADR-0008, Node + Git + AI CLI
  2. Beads) is Node-only.
  3. Security surface. graphify reads the whole project tree and sends docs/images to an external model for graph construction. This is a meaningful expansion of capability versus the existing catalog entries.
  4. Researcher-specific. Only the researcher role uses the cgb slot. Most users running aidokit init will never invoke it.

The question is whether to add it at all, and if so under what constraints.

Decision

1. Add graphify as MCP catalog entry #8

A one-file MCPDef add per ADR-0007. The entry sits alongside the existing seven (Context7, Beads MCP, Playwright, GitHub, Chrome DevTools, Postgres, Filesystem).

{
  id: 'graphify',
  name: 'graphify',
  description:
    'Code-graph / knowledge-graph MCP. Turns a repo into a queryable graph for dependency and impact analysis. Fills the v4 researcher agent cgb slot.',
  securitySensitive: true,
  trigger: 'never',
  install: {
    'claude-code': {
      command: 'claude mcp add graphify -- uvx graphifyy mcp',
    },
    // codex: TBD when codex adapter lands
  },
  prereqs: ['python>=3.10', 'uv or pipx'],
  docs: 'https://pypi.org/project/graphifyy/',
}

2. Opt-in only — never auto-suggested

trigger: 'never' is mandatory. No stack-pack suggestMCPs(ctx) returns 'graphify' from a detector signal. Users surface it explicitly via aidokit mcp add graphify or by selecting it in the init MCP picker. This matches the security-sensitive policy already applied to Postgres and Filesystem.

3. Python is NOT promoted to an aidokit prereq

ADR-0008 stands unchanged. The prereq list remains Node + Git + AI CLI + Beads. graphify's Python requirement is surfaced as a per-MCP prereq string in its MCPDef and printed when the user opts in, with the install hint (pipx install graphifyy or uv tool install graphifyy). aidokit detects but does not install.

4. No auto-install — ADR-0008 applies

Selecting graphify in init runs the per-adapter installMCP recipe (e.g. claude mcp add graphify -- …). It does not run pipx install or uv tool install. If Python or uvx is missing, the MCP install fails with a clean MCP_INSTALL_FAILED envelope and the printed prereq hint.

5. Documentation surfaces the trust boundary

The catalog description and the aidokit mcp add graphify confirmation prompt both state that graphify reads the project tree and sends content to an external model. Consent is per-invocation; --yes does not bypass the security-sensitive prompt for MCP entries flagged securitySensitive: true.

Consequences

Positive

Negative

Neutral

Alternatives considered

Alternative 1: Do not add graphify

Leave the cgb slot empty; users who need it install graphify manually and configure it themselves.

Pros

Cons

Reason rejected: the catalog exists to make MCP discovery and install one step. Refusing to list a clearly relevant MCP because it has a Python prereq punishes users for a problem they can solve.

Alternative 2: Add graphify and auto-suggest it for any project

trigger: 'always' or a detect.hasMultipleLanguages-style trigger that surfaces graphify by default.

Pros

Cons

Reason rejected: violates the existing policy for security-sensitive entries (Postgres, Filesystem). No catalog entry that sends user content off-host should auto-suggest.

Alternative 3: Promote Python to an aidokit prereq

Add Python ≥ 3.10 to @aidokit/prereq-check as an optional prereq so graphify (and any future Python MCP) detects cleanly.

Pros

Cons

Reason rejected: premature. If a second Python MCP lands, revisit in a new ADR. For one entry, per-MCP prereqs: string[] is enough.

Alternative 4: Bundle a different code-graph MCP

Pick a Node-native code-graph MCP (e.g. one based on ts-morph or tree-sitter) to avoid the Python dependency.

Pros

Cons

Reason rejected: the better option may exist later; not today.

Implementation notes

Validation

This decision is validated when:

References

Internal

External