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

## 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

```bash
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:

```bash
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

| Tool | Answers |
|---|---|
| `list_architecture_decisions` | What ADRs exist? |
| `get_architecture_decision` | Full text of one ADR by id |
| `get_project_conventions` | All golden rules + per-domain surface conventions |
| `get_component_usage` | Real scanned usage stats + examples for one component, optionally scoped to a domain |
| `get_usage_guidance` | **The main one.** Synthesizes relevant ADRs + golden rules + surface convention + real examples for one component in one domain — "why/when/where" in a single call |
| `search_context` | Full-text search across ADRs and golden rules |

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.