runtime-mcp

runtime-mcp

Drop-in MCP server that lets Claude inspect, debug, and hot-fix your running Bun process through conversation.

One line of code. Claude can now see inside your running Bun server — memory, queries, traffic, errors, everything.

import { attachMCP } from 'runtime-mcp';
attachMCP({ port: 3100 }); // that's it

Your Bun process now speaks MCP. Connect Claude Desktop, Cursor, or any MCP client and start asking questions about your live app.

Why

Debugging a running app today means adding logging, restarting, and hoping you guessed the right thing to log. LLMs can read your source code, but they can't see your runtime state — the variable values, the open connections, the slow queries, the memory growth.

runtime-mcp fixes that. It exposes your process internals as MCP resources and tools, so the LLM examines the live patient instead of guessing from the chart.

Quick Start

1. Install

bun add runtime-mcp

2. Attach to your server

import { serve } from 'bun';
import { attachMCP } from 'runtime-mcp';

const server = serve({
  port: 3000,
  fetch: () => new Response('Hello'),
});

attachMCP({
  port: 3100,
  bind: { server },
});

3. Connect Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:3100/sse"
    }
  }
}

Restart Claude Desktop. Ask: "What is this process doing?"

What Claude Can See

Resources (read-only, always available)

| Resource | URI | Description | |----------|-----|-------------| | Process info | runtime://process/info | PID, uptime, Bun version, entrypoint, env vars | | Memory | runtime://process/memory | RSS, heap used/total, external, array buffers | | Event loop | runtime://process/event-loop | Pending timers, active handles, loop lag | | HTTP routes | runtime://server/routes | All registered routes, active connections, req/min | | Request log | runtime://server/requests | Recent HTTP requests with status, duration, bodies | | Errors | runtime://errors/recent | Uncaught exceptions and unhandled rejections (deduplicated) | | DB connections | runtime://db/connections | Pool state, recent queries, slow queries | | Module graph | runtime://modules/graph | Full dependency tree from entrypoint | | WebSockets | runtime://websockets | Active connections, message counts | | Variables | runtime://variables/{path} | Inspect any bound variable by dot-path |

Tools (actions Claude can take)

| Tool | Description | |------|-------------| | inspect | Deep-inspect any reachable object by expression | | eval | Execute JavaScript in the process context | | get_source | Read source files from the running process | | intercept_requests | Capture HTTP traffic matching a glob pattern | | intercept_sql | Capture SQL queries matching a substring | | subscribe_events | Stream real-time events (requests, errors, queries) | | heap_snapshot | Take a V8 heap snapshot, diff against previous | | profile | CPU profile for N milliseconds | | set_breakpoint | Conditional breakpoints with state capture | | hot_patch | Replace a module's code at runtime without restart | | shell | Run read-only shell commands in the process cwd |

\Requires node:inspector — not yet available in Bun (tracking issue).*

Prompts (guided debugging workflows)

| Prompt | Description | |--------|-------------| | debug-endpoint | Systematically debug a specific HTTP endpoint | | find-memory-leak | Snapshot, wait, diff, identify growing allocations | | explain-process | Full overview of what the process is doing right now | | generate-tests | Watch live traffic and generate test cases from it | | optimize-query | Find slow queries, explain plans, suggest fixes |

Configuration

attachMCP({
  // Transport
  port: 3100,              // MCP server port (default: 3100)
  host: 'localhost',       // Bind address (default: 'localhost')

  // What to expose
  bind: {                  // Objects the LLM can inspect/eval against
    server,
    db,
    config,
  },

  // Access control
  readOnly: false,         // Disable eval, hot_patch, shell (default: true in production)
  allowedTools: undefined, // Whitelist specific tools
  blockedTools: undefined, // Blacklist specific tools

  // Observation tuning
  requestLog: {
    maxSize: 1000,         // Ring buffer size
    includeBodies: true,   // Capture req/res bodies (default: false in production)
  },
  sqlLog: {
    maxSize: 500,
    includeParams: true,   // Capture query params (default: false in production)
    slowThreshold: 500,    // Slow query threshold in ms
  },

  // Remote access (requires auth)
  auth: 'your-secret-token', // Required when host !== localhost
});

Production Defaults

When NODE_ENV=production, runtime-mcp automatically:

• Sets readOnly: true — disables eval, hot_patch, shell
• Hides request/response bodies
• Hides SQL query parameters
• All read-only inspection tools remain available

Binding Objects

Pass objects to bind to make them accessible to Claude:

import { serve } from 'bun';
import { SQL } from 'bun';
import { attachMCP } from 'runtime-mcp';

const db = new SQL('postgres://localhost/myapp');
const server = serve({ port: 3000, fetch: handleRequest });
const config = { featureFlags: { newCheckout: true }, rateLimit: 100 };

attachMCP({
  port: 3100,
  bind: { server, db, config },
});

runtime-mcp auto-detects:

• Bun.serve() servers — wraps the fetch handler to intercept HTTP traffic
• Bun.sql instances — wraps queries to capture SQL traffic
• WebSocket handlers — tracks connections and messages

Everything else is available through inspect and eval by name.

Security

• Binds to localhost only by default
• Non-localhost binding requires the auth option (Bearer token)
• Production mode disables code execution tools
• Shell tool blocks destructive commands (rm, kill, shutdown, etc.)
• Sensitive env vars are filtered from process info

This is a development tool. Treat the MCP port like a debugger port — don't expose it to the internet.

Requirements

• Bun >= 1.0.0
• An MCP client (Claude Desktop, Cursor, or any MCP-compatible tool)

How It Was Built

This project was built in a single session using Ralph, an autonomous AI agent loop. A PRD was written, converted to a task list, and Ralph implemented all 22 user stories sequentially — each one adding a resource, tool, or interceptor layer.

License

MIT