🔌 runtime-mcp: Live Runtime MCP Bridge for AI Agents

Eliminate environment and runtime hallucinations.
runtime-mcp bridges the gap between static code analysis and live application runtime. It transparently inspects live SQLite schemas, intercepts live HTTP errors (4xx/5xx) through an async local reverse proxy, extracts log stack traces, and serves an instant, compact state snapshot to Antigravity, Claude Code, and Cursor via the Model Context Protocol (MCP).

🛑 The Problem

Modern AI coding agents (Claude, Cursor, Antigravity) are exceptional at reading static code, but they are completely blind to your application's actual runtime state:

1. Database Hallucinations: Because migrations are often complex or out-of-sync, agents frequently invent non-existent database columns, missing types, or incorrect foreign keys.

2. Copy-Paste Friction: When an API returns a 500 Internal Server Error, you have to manually copy payloads, headers, and terminal stack traces back into chat.

3. Stale Context: Agents suggest code changes based on assumptions rather than verified ground-truth runtime state.

Related MCP server: Alma Atlas

⚡ The Solution

runtime-mcp acts as a zero-overhead live telemetry sidecar for your local development stack:

┌──────────────────────┐         ┌──────────────────────────────┐
│  Browser / Frontend  │ ──────> │  runtime-mcp tap (:8090)     │ ─────> ┌────────────────────┐
└──────────────────────┘         │  (Captures 4xx/5xx failures) │        │ Local App (:3000)  │
                                 └──────────────┬───────────────┘        └────────────────────┘
                                                │
                                    .runtime_state.json
                                                │
┌──────────────────────┐         ┌──────────────┴───────────────┐
│ AI Assistant         │ <====== │   runtime-mcp serve (MCP)    │
│ (Antigravity/Claude) │  stdio  │  - get_live_db_schema()      │ <───── SQLite DB (?mode=ro)
└──────────────────────┘         │  - get_recent_http_errors()  │
                                 │  - get_runtime_snapshot()    │ <───── App Logs (*.log)
                                 └──────────────────────────────┘

• DatabaseSchemaTap: Connects to your local SQLite database in read-only URI mode (?mode=ro). Extracts real tables, column types, primary/foreign keys, indexes, and row counts into an ultra-compact, hallucination-resistant Markdown schema.

• HttpTap: An asynchronous local reverse proxy (asyncio + httpx) listening on :8090 (or custom port) and forwarding to your backend (:3000, :8000, etc.). Automatically captures requests and deep response bodies for 4xx/5xx failures into a thread-safe ring buffer.

• LogTailTap: Automatically tails your application log file and parses Python (Traceback (most recent call last)...) and Node.js (Error: ... at ...) stack traces, as well as ERROR and CRITICAL log events.

• Zero-Latency State Store: Synchronizes runtime events between the CLI proxy process and the MCP server process using an atomic, cross-platform file buffer (.runtime_state.json).

🚀 Quickstart

1. Installation

Requires Python 3.14+:

# Clone the repository
git clone https://github.com/your-username/runtime-mcp.git
cd runtime-mcp

# Create and activate virtual environment
python3 -m venv .venv

# macOS / Linux
source .venv/bin/activate

# Windows (PowerShell)
# .venv\Scripts\Activate.ps1

# Install in editable mode
pip install -e .

2. Run the Live Traffic Tap

Start the interceptor proxy, binding your backend port, database, and log file:

# macOS / Linux / Windows
python -m src.cli tap --listen 8090 --target 3000 --db ./app.db --log ./app.log

Now, point your frontend or API client to http://localhost:8090 instead of 3000. All requests pass through transparently with minimal latency, and all errors are captured in real-time.

3. Check the Runtime Snapshot in Terminal

At any time, inspect the current runtime snapshot directly in your terminal:

python -m src.cli snapshot --db ./app.db --log ./app.log

4. Run the MCP Server

Launch the FastMCP server over standard I/O:

python -m src.cli serve

🤖 AI Agent Integration (MCP Configuration)

Add runtime-mcp to your AI assistant's MCP configuration.

For Google Antigravity & Claude Code & Cursor

Add this block to your mcpServers configuration file:

• Antigravity: ~/.gemini/antigravity/mcp_config.json or project settings

• Claude Code / Desktop: claude_desktop_config.json

• Cursor: .cursor/mcp.json

{
  "mcpServers": {
    "runtime-mcp": {
      "command": "python",
      "args": [
        "-m",
        "src.cli",
        "serve",
        "--state-file",
        "/absolute/path/to/project/.runtime_state.json"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/runtime-mcp"
      }
    }
  }
}

Tip for Windows users: Use forward slashes or escaped backslashes for paths (e.g. C:/Users/name/projects/runtime-mcp/.runtime_state.json).

🛠️ MCP Tools Reference

Once connected, your AI assistant gains access to three live tools:

💻 CLI Commands Reference

All commands can be invoked either via runtime-mcp <command> or python -m src.cli <command>:

tap

Starts the live HTTP proxy tap and monitors DB / logs:

runtime-mcp tap [OPTIONS]

Options:
  -l, --listen INTEGER  Port to listen on [default: 8090]
  -t, --target TEXT     Target backend port or URL (e.g. 3000 or http://localhost:3000) [default: 3000]
  -d, --db TEXT         Path to local SQLite database file
  --log TEXT            Path to application log file
  --state-file TEXT     Path to state file for persistence [default: .runtime_state.json]

snapshot

Prints the current verified runtime state in terminal with Rich formatting:

runtime-mcp snapshot [OPTIONS]

Options:
  -d, --db TEXT         Path to local SQLite database file
  --log TEXT            Path to application log file
  --state-file TEXT     Path to state file [default: .runtime_state.json]

serve

Runs the FastMCP server over stdio for IDE and AI agent connections:

runtime-mcp serve [OPTIONS]

Options:
  --state-file TEXT     Path to state file [default: .runtime_state.json]

🧪 Running Tests

The test suite covers SQLite schema extraction, read-only enforcement, async HTTP proxying, status 500 interception, log stack trace parsing, and direct MCP tool execution:

pytest -v

📄 License

This project is open-source software licensed under the MIT License.