aidokitwiki
User Docs Wiki

MCP Catalog

Audience-Contributor Status-Shipped v0.5 Spec-MCP Catalog ADR-0007

Purpose #

Explain what the MCP catalog is, what it deliberately is not, and how the trigger / role-scoping / security-sensitive rules combine.

Big Picture #

The MCP catalog is the curated list of MCP (Model Context Protocol) servers aidokit knows about. It ships as a TypeScript const array in @aidokit/mcp-catalog. Adding an entry is a single-file PR.

It is not:

Source of truth: .docs/docs/specs/mcp-catalog.md and ADR-0007.

How It Works #

The shape of an entry #

{
  id: 'context7',                              // kebab-case, permanent
  name: 'Context7',
  purpose: 'Up-to-date library documentation lookup for agents.',
  suggestedFor: ['researcher', 'architect'],   // default role-scoping
  triggers: ['always'],                        // see "Trigger grammar" below
  securitySensitive: false,
  install: {
    'claude-code': { command: 'claude mcp add context7 -- npx -y @upstash/context7-mcp', requiresNetwork: true, minCliVersion: '2.1.32' },
    'codex':       { configBlock: { target: '~/.codex/config.toml', content: '...', mode: 'merge' }, requiresNetwork: true },
  },
  // optional: deprecated, replacedBy, homepage, tags, prereqs
}

Trigger grammar (restricted) #

OR-only, no negation, no boolean operators. Full list at .docs/docs/specs/mcp-catalog.md §7:

Trigger Evaluates true when
always every project
never never auto-suggest; explicit add only
beadsEnabled ctx.beadsEnabled === true
brownfield ctx.brownfield === true
stack.has(<id>) pack id present in ctx.selectedStackPacks
stack.hasFrontend any selected pack is in the frontend set
stack.hasBackend any selected pack is in the backend set
stack.hasDatabase any selected pack declares a DB in extras
stack.language(<lang>) language present in manifest.languages
detect.githubRemote git remote -v shows github.com
detect.gitlabRemote same for gitlab.com
detect.bitbucketRemote same for bitbucket.org
os.darwin / linux / win32 host OS match
conformance.<level> project conformance match

If a more complex condition is needed, split the entry, do not extend the grammar.

Role scoping #

suggestedFor is the default role set the CLI scopes the MCP to on install. Users may override via aidokit mcp add <id> --roles <list>. The CLI MUST NOT default-scope to all roles (.docs/docs/specs/mcp-catalog.md §9.4).

securitySensitive: true #

A hard, non-bypassable gate:

No removal — deprecation only #

Entries are never removed. To retire, set deprecated: true and (if a successor exists) replacedBy: '<new-id>'. The CLI excludes deprecated entries from suggestion; aidokit doctor warns projects still referencing them.

Example: the v1.0 catalog #

Eight entries as of [Unreleased] + ADR-0015:

ID Triggers Sensitive Default scope
context7 always ❌ researcher, architect
beads-mcp beadsEnabled ❌ planner, maintainer
playwright stack.hasFrontend ❌ tester-reviewer, frontend-browser-tester
github detect.githubRemote ❌ researcher, planner
chrome-devtools stack.hasFrontend ❌ frontend-browser-tester
postgres (per spec) ❌ (per spec)
filesystem never ✅ (empty — manual scoping)
graphify never ✅ (empty — opt-in, fills v4 cgb slot)

See reference/mcp-catalog-reference.md for the full table with install commands.

Diagram #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart TD
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;

  init["aidokit init"]:::cli --> trig{evaluate triggers}:::stop
  trig -->|matches| auto["auto-suggest in picker"]:::cli
  trig -->|securitySensitive| skip["never auto-suggest"]:::stop
  add["aidokit mcp add "]:::cli --> sens{securitySensitive?}:::stop
  sens -->|yes| confirm["explicit confirm (unbypassable)"]:::stop
  sens -->|no| roles["scope to suggestedFor or --roles"]:::cli
  confirm --> install["adapter.installMCP → ShellCommand[]"]:::adapter
  roles --> install
  install --> exec["CLI executes commands"]:::external
  exec --> state[".aido/state.json audit record"]:::artifact

Common Mistakes #

Checklist for adding an entry #

From .docs/docs/specs/mcp-catalog.md Appendix B: