runtime-mcp

Der Live-Zustand deiner App — Logs, DB-Schema, Config, Feature-Flags — als MCP-Tools für Coding-Agenten.

Wirf es in deine App. Dein Agent hört auf zu raten.

Wenn opencode, Claude Code oder Cursor deine App debuggen, arbeiten sie blind: veraltete Annahmen über dein Schema, kopierte Log-Fragmente, erfundene Config-Werte.

runtime-mcp schließt diese Lücke. Zwei Zeilen Setup und jeder MCP-fähige Agent kann sehen, was dein laufender Prozess tatsächlich sieht:

Agent: "why is checkout failing?"
  ├─ get_errors   → TypeError at checkout.ts:42, full stack trace
  ├─ db_query     → orders table has no `coupon_id` column
  ├─ config://    → STRIPE_KEY: [REDACTED], TAX_RATE: 0  ← there it is
  └─ "Found it — you renamed the env var."

Schnellstart

0 — Installieren:

npm install runtime-mcp runtime-mcp-integrations

1 — Deine App instrumentieren (ein Import):

import { runtimeMcp } from 'runtime-mcp';
import { pgAdapter } from 'runtime-mcp-integrations/pg';

await runtimeMcp({
  db: pgAdapter(pool),
  config: process.env,
  flags: myFlagRegistry,
});

2 — Den Shim registrieren in deiner .mcp.json:

{
  "mcpServers": {
    "runtime": { "command": "npx", "args": ["-y", "runtime-mcp-connect"] }
  }
}

3 — Deine App starten. Fertig. Der Agent verbindet sich automatisch und sieht von da an den Live-Zustand.

Was Agenten bekommen

Tools

Ressourcen

Architektur

┌──────────────────────────────┐          ┌─────────────────────────────┐
│         Your App             │          │   Agent (opencode/Claude)   │
│                              │          │                             │
│  runtimeMcp({ db, config })  │          │  .mcp.json                  │
│   ├─ log ring buffer         │          │    └─ runtime-mcp-connect   │
│   ├─ schema introspection    │          │          │ stdio            │
│   ├─ config + redaction      │◄─────────┼──────────┘                  │
│   └─ feature flags           │  loopback│                             │
│                              │   HTTP   │                             │
│  127.0.0.1:<port>/mcp        │          │                             │
│  .runtime-mcp.json ──────────┼─ pid·url·token·(chmod 600)             │
└──────────────────────────────┘          └─────────────────────────────┘

Warum zwei Komponenten? Agenten starten eigene Prozesse — sie können nicht direkt in deine App hineinschauen. Die Discovery-Datei überbrückt das: Die Library schreibt sie beim Boot, der Shim liest sie bei jedem Aufruf. App mit neuem Port oder Token neu gestartet? Der Shim verbindet sich automatisch neu. Nichts muss neu konfiguriert werden. Nie.

Adapter

npm install runtime-mcp runtime-mcp-integrations

Strukturiertes Logging-Beispiel:

import pino from 'pino';
import { createRuntimeMcpPinoDestination } from 'runtime-mcp-integrations/pino';

const logger = pino(pino.multistream([
  pino.destination(1),
  createRuntimeMcpPinoDestination(),
]));

Kein Logger eingebunden? Console-Capture ist standardmäßig aktiv — console.error und Co. fließen in denselben Puffer.

Sicherheitsmodell

Gedacht für lokale Entwicklung und Staging. Defense in Depth standardmäßig:

.runtime-mcp.json in die .gitignore aufnehmen.

Warum jetzt

Jede Plattform baut das nach innen. Niemand hat es generisch gebaut. Das hier ist generisch.

Demo

pnpm install && pnpm -r build
pnpm --filter @runtime-mcp/demo-app dev

packages/demo-app ist ein Express + SQLite Store mit zwei absichtlich eingebauten Bugs — ein N+1-Query auf /orders und eine falsch benannte DEMO_TAX_RATE-Env-Var, die die Mehrwertsteuer beim Checkout stillschweigend auf null setzt. Zeig deinen Agenten darauf und frag: "Warum stimmen die Warenkorb-Summen nicht?"

Pakete

Alle Pakete sind auf npm veröffentlicht (v0.1.0):

Erfordert Node ≥ 20. ESM.

Entwicklung

pnpm install
pnpm -r build
pnpm test    # unit + end-to-end over real HTTP and stdio transports

• Live-Log-Tailing über MCP-Ressourcen-Abos

• Fastify-/Hono-Adapter

• MySQL-/Drizzle-Introspection-Adapter

• Python-SDK-Parität (FastAPI / Django)

• Multi-Projekt-Workspaces im Connect-Shim

Lizenz

MIT