runtime-mcp

El estado de ejecución en vivo de tu app — logs, esquema de BD, configuración, feature flags — como herramientas MCP para agentes de código.

Ponlo en tu app. Tu agente deja de adivinar.

Cuando opencode, Claude Code o Cursor depuran tu app hoy, trabajan a ciegas: suposiciones obsoletas sobre tu esquema, fragmentos de logs pegados, valores de configuración inventados.

runtime-mcp cierra esa brecha. Con dos líneas de configuración, cualquier agente que hable MCP puede consultar lo que tu proceso en ejecución ve realmente:

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

Inicio rápido

0 — Instala:

npm install runtime-mcp runtime-mcp-integrations

1 — Instrumenta tu app (un import):

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

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

2 — Registra el shim en el .mcp.json de tu proyecto:

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

3 — Inicia tu app. Eso es todo. El agente se conecta automáticamente y ve el estado en vivo a partir de entonces.

Lo que obtienen los agentes

Herramientas

Recursos

Arquitectura

┌──────────────────────────────┐          ┌─────────────────────────────┐
│         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)             │
└──────────────────────────────┘          └─────────────────────────────┘

¿Por qué dos piezas? Los agentes lanzan sus propios procesos — no pueden acceder a tu app. El archivo de descubrimiento los une: la librería lo escribe al arrancar, el shim lo lee en cada llamada. ¿App reiniciada con un puerto o token nuevo? El shim se reconecta automáticamente. Nunca hay que reconfigurar nada.

Adaptadores

npm install runtime-mcp runtime-mcp-integrations

Ejemplo de registro estructurado:

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

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

¿Sin logger configurado? La captura de consola está activada por defecto — console.error y similares fluyen al mismo búfer.

Modelo de seguridad

Diseñado para desarrollo local y puesta en escena. Defensa en profundidad por defecto:

Añade .runtime-mcp.json a tu .gitignore.

Por qué ahora

Todas las plataformas están construyendo hacia adentro. Nadie lo ha construido de forma genérica. Esto es eso.

Demo

packages/demo-app es una tienda Express + SQLite con dos errores plantados: una consulta N+1 en /orders y una variable de entorno mal escrita DEMO_TAX_RATE que pone a cero los impuestos del carrito. Apunta a tu agente y pregúntale "¿por qué los totales del carrito son incorrectos?"

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

Paquetes

Todos los paquetes están publicados en npm (v0.1.0):

Requiere Node ≥ 20. ESM.

Desarrollo

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

• Seguimiento de logs en vivo mediante suscripciones de recursos MCP

• Adaptadores Fastify / Hono

• Adaptadores de introspección MySQL / Drizzle

• Paridad del SDK de Python (FastAPI / Django)

• Espacios de trabajo multiproyecto en el shim de conexión

Licencia

MIT