runtime-mcp: Instructions file for Codex

AGENTS.md — runtime-mcp

Project

Drop-in MCP library exposing a running Node app's live state (logs, DB schema, config, feature flags) to coding agents. Monorepo of 4 packages.

Layout

packages/
├── core/           # runtime-mcp: registry, endpoint, discovery, redaction, SQL guard
├── connect/        # runtime-mcp-connect: stdio shim agents register in .mcp.json
├── integrations/   # adapters: express/pino/winston/pg/prisma/node-sqlite (subpath exports)
└── demo-app/       # Express + node:sqlite demo with planted bugs

Session-start workflow

Before deep work, regenerate AI indexes if stale:

npx repomix . --output repomix-output.xml
graphify update . --no-cluster

Use repomix-output.xml and graphify query instead of reading files one-by-one.

Commands

pnpm install          # after changing deps
pnpm -r build         # tsup builds all packages (core must build before connect/integrations typecheck)
npx vitest run        # full suite from repo root (39 tests)
cd packages/demo-app && npx tsc --noEmit   # demo has noEmit tsconfig

Per-package typecheck: cd packages/<name> && npx tsc --noEmit.

Conventions

• TypeScript strict + noUncheckedIndexedAccess + verbatimModuleSyntax — use import type, watch for possibly-undefined index access.
• ESM everywhere; relative imports need .js extensions in TS source.
• No comments in code; no console.log in library code (console hook is the product).
• Immutable patterns; no mutation of shared state objects.
• SDK is MCP TypeScript SDK v2: McpServer.registerTool(name, config, cb), registerResource(name, uriOrTemplate, config, cb), templates via new ResourceTemplate(uri, { list }) (list key REQUIRED, may be undefined). Transports: NodeStreamableHTTPServerTransport (enableJsonResponse: true for deterministic responses), client via @modelcontextprotocol/client (Client, StreamableHTTPClientTransport, authProvider { token: async () => token }).
• Per-session hosting pattern: create transport → server.connect(transport) → transport.handleRequest(req,res,body); session map keyed by mcp-session-id.