kernelee-mcp-tools

Architecture-index MCP tools for kernelee apps — a ts-morph static scan and the kernel's own runtime wiring projection, assembled into one JSON index and served to coding agents over the Model Context Protocol.

A kernelee app's control flow is data (symbols, pipes, buffer states), so it can be indexed and queried instead of grepped: "who drives this endpoint?", "who writes this state?", "what is one hop downstream of this symbol?".

What it does

Three cooperating pieces:

• Foundation (kernelee-mcp-tools) — builds an IndexDocument from: the runtime wiring projection (projectWiringGraph over the app's live pipe catalog), a ts-morph static scan of the app's tsconfig program (input types, readsState / writesState, drive sites — dispatch/call/run and React useDispatch — per-stage flows, fork branch selectors, declaration/implementation addresses), and a git stamp. Written atomically to index.json.

• MCP server (kernelee-mcp-tools/server) — runKernelIntrospectMCPServer(configuration): a stdio MCP server that re-reads index.json per query and prepends a staleness verdict (fresh / stale / unknown vs. the current working tree) to every answer.

• CLI (kernelee-introspect) — kernelee-introspect <config-module> regenerates the index from a consumer-supplied config and prints a one-line summary. Wire it into the app's build so the index can never silently rot.

Contract: introspection output artifacts — outputPath and KERNEL_INTROSPECT_TRACE_PATH, if set — must live outside the repository, or be gitignored. Staleness works by comparing a content hash of the whole non-ignored working tree; if the index (or a trace dump) itself falls inside that domain, writing it changes the very tree the hash just described, and staleness can never converge on fresh — every arch_refresh reports stale again, forever. The CLI enforces this with a hard error before writing anything (see docs/mcp-server-gotchas.md #10); the server appends a diagnostic note to a stale hint (including arch_refresh's own success response) whenever it can tell this is the cause. A path inside a git repo nested under the repo root is a known, conservative false positive — gitignoring it there is harmless.

Related MCP server: Graft

The tools

Misses come back with nearest-key suggestions rather than bare errors.

Consumer integration

The package hardcodes nothing about your app — everything arrives by injection. A consumer supplies two small pieces:

1. An IntrospectConfig module for the CLI — repo root, tsconfig path, catalog file/function, state files, output path, and optional CI gates (failOnWiringIssues, failOnOffBufferControlValues, each with an allowlist):

   // package.json
   "scripts": {
     "introspect": "tsx node_modules/.bin/kernelee-introspect scripts/introspect.config.ts",
     "build": "npm run introspect && vite build"
   }

2. A thin MCP launcher that bakes its defaults and starts the server — registered in the MCP client (e.g. Claude Code's .mcp.json) as a stdio server:

   // scripts/introspect-mcp-server.mjs
   import { runKernelIntrospectMCPServer, configurationFromEnvironmentOverridingDefaults }
     from '@s-age/kernelee-mcp-tools/server';
   
   await runKernelIntrospectMCPServer(configurationFromEnvironmentOverridingDefaults({
     indexPath: '.claude/introspect/index.json',
     repoRoot: process.cwd(),
     refreshCommand: 'npm run introspect',
     refreshTimeoutSeconds: 300,
   }));

   Every default can be overridden via KERNEL_INTROSPECT_INDEX_PATH, KERNEL_INTROSPECT_REPO_ROOT, KERNEL_INTROSPECT_REFRESH_COMMAND, KERNEL_INTROSPECT_REFRESH_TIMEOUT_SECONDS.

The reference consumer is kernelee-lifegame — see its scripts/introspect.config.ts, scripts/introspect-mcp-server.mjs, and docs/kernel-introspect-mcp.md (an end-user guide with example outputs and client-registration recipes).

Development

npm run build      # tsc → dist/ (the bin needs this before first use)
npm test           # vitest run — unit + MCP end-to-end integration tests
npm run typecheck  # tsc --noEmit

Dependencies: @modelcontextprotocol/sdk, ts-morph, zod; kernelee is a peer dependency. fixtures/authoringShapes/ is a minimal kernelee app the scan tests run against; docs/ holds implementation gotcha notes.

License

MIT © s-age