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. The TS port of swift-kernelee's KernelIntrospect / KernelIntrospectMCP.

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.

The tools

Tool	Args	Answers
arch_overview	—	The map: ring × device symbol counts, every endpoint headline, state / shared-stage / part lists. Start here.
arch_endpoint	key	One endpoint in full: the stage tree (kinds, flows, notes, fork branches), its binding, and who drives / diverts-to / reads / writes around it.
arch_state	state	One buffer state: declaration, named mutations, writers, and readers split into circuit vs. presentation.
arch_trace	from, edges?, depth?	A typed-edge BFS neighborhood (drivenBy, divertsTo, callsSymbol, reads, writes, usesSharedStage) around any node.
arch_refresh	—	Runs the consumer's refresh command, then reloads the index.

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