mcp context engine

Upstream Project Knowledge Engine. Gives an AI agent deep codebase memory, architectural guidelines, and project intent, so it knows why, when, and where to use your design system's components — not just what props they take.

How this differs from a component registry

In the context of a design system it can tell an agent that variant="danger" should basically only ever appear in an account-deletion flow, that auth screens all share one specific layout for a documented reason, or that dashboard tiles get a primary button because it competes with the page's real primary action.

This engine answers the next layer of questions:

• Why does this pattern exist? (architecture decision records)

• When/where should I use X vs Y? (project conventions — golden rules, scoped per product surface)

• How has the team actually used this, in practice? (a real index of every usage in the codebase, scanned with an AST parser — not guessed)

Use both together: fetch the prop schema from the component registry, fetch usage guidance from this engine, then generate.

Related MCP server: mcpsystem.design MCP Server

Architecture

[ ADRs (why) ] ─┐
                 ├─→ [ context-index/*.json ] ─→ [ MCP server ] ─→ agent
[ Conventions   ] ┤       (merged knowledge)         (6 tools)
 (when/where)   ─┘
                 
[ Real codebase ] ─→ [ AST-based indexer ] ─→ [ usage-index.json ] ─┘
   (.tsx files)      (@babel/parser +               (how, in practice)
                       @babel/traverse)

Two of the three knowledge sources are authored by humans (ADRs, conventions) because that's where actual judgment lives — this tool doesn't try to infer why a decision was made from code alone. The third (usage) is scanned, because "how has this actually been used" should reflect reality, not memory of intent that's since drifted.

What's in here

mcp-context-engine/
├── adrs/                          # Architecture Decision Records (markdown + frontmatter)
│   ├── 0001-component-driven-ui.md
│   ├── 0002-json-tree-not-jsx.md
│   └── 0003-auth-credential-card-pattern.md
├── conventions/
│   └── project-intent.json        # golden rules + per-surface (domain) conventions
├── sample-project/                # a small demo codebase the indexer scans
│   └── src/{auth,settings,dashboard}/*.tsx
├── scripts/
│   ├── index-codebase.js          # AST scan: finds every real component usage
│   └── build-context-index.js     # merges ADRs + conventions + usage into one index
├── context-index/                 # generated output (gitignore this in a real repo,
│   │                                 or commit it — either works; regenerate on demand)
│   ├── usage-index.json
│   ├── adrs-full.json
│   ├── conventions-full.json
│   └── context-index.json
├── mcp-server/
│   ├── index.js                   # exposes it all as 6 MCP tools
│   └── package.json
└── package.json

Running it

npm install
npm run build              # indexes sample-project/ + merges ADRs/conventions
cd mcp-server && npm install && npm start

To point the indexer at your real project instead of the sample one:

node scripts/index-codebase.js /path/to/your/project
npm run build-context

The indexer currently tracks Button, Card, Input (see TRACKED_COMPONENTS in scripts/index-codebase.js) — in a real setup, read this list from your component registry's metadata/index.json instead of hardcoding it, so newly added components are picked up automatically.

The tools this exposes

Verified against real JSON-RPC calls (not just described): asking get_usage_guidance("Card", "auth") correctly returns ADR-0001 and ADR-0003 (matched by content, not a hardcoded mapping), the "reuse the credential-card pattern" golden rule, the auth surface's bordered convention, and two real file/line examples — one of which is LoginPage.tsx, whose own source comment independently references ADR-0003. Nothing here is fabricated context; it's assembled from what's actually in adrs/, conventions/, and the scanned source files.

Extending

• Track more components: edit TRACKED_COMPONENTS in scripts/index-codebase.js.

• Add an ADR: drop a new NNNN-title.md file in adrs/ with the same frontmatter shape (id, title, status, date, tags), run npm run build-context.

• Add a convention: edit conventions/project-intent.json — either a new golden rule or a new/updated surfaces.<domain> entry.

• Re-index after code changes: run npm run build again. Nothing here is incremental yet; for a large real codebase, consider running the indexer in CI on merge to main rather than on every request.