vigilante

Runtime instrumentation that makes any app visible to LLMs — via MCP.

Built by @retamayo

Vigilante hooks into a running application with zero changes to your code. It records every HTTP request, function call, return value, object mutation, and error — then exposes it all to any MCP-capable LLM so it can autonomously debug your app.

Language-agnostic design. The MCP server speaks a universal event format. Per-language adaptors handle instrumentation. Node.js adaptor included, with plans to develop Rust, PHP, and Python adaptors.

---

Quick start

# 1. Clone and install
git clone https://github.com/retamayo/vigilante.git
cd vigilante
npm install

# 2. Run your app with instrumentation
node --require ./vigilante/adapters/node.js your-app.js

# 3. Add to your .mcp.json (Claude Code / Claude Desktop)

{
  "mcpServers": {
    "vigilante": {
      "command": "node",
      "args": ["path/to/vigilante/vigilante/server.js"]
    }
  }
}

Then tell the LLM: "the cart total is wrong" — it will query Vigilante and trace the runtime to find the bug.

---

How it works

Your App --> Adaptor (hooks functions) --> Events File (JSON) --> MCP Server --> LLM

The Node.js adaptor installs two hooks before your app runs:

Hook	What it captures
Module._load	Wraps exported functions of user-land modules (require('./...'))
http.createServer	Intercepts HTTP requests/responses, creates spans per request

Events go into a ring buffer (keeps the last 2000 events) flushed to a temp file. The MCP server reads it on demand. Queries return up to 500 events at a time.

Sensitive data is automatically redacted — passwords, tokens, secrets, and authorization headers are replaced with [redacted] before being written to the event buffer.

---

MCP interface

Connect any MCP client to node vigilante/server.js (stdio transport).

Resources

URI	Description
vigilante://spans	Summary of all request spans — method, path, status, event count
vigilante://events	Full event buffer
vigilante://context/stack	Current / last-known call stack

Tools

vigilante_help — Returns a reference guide for all resources, query params, and recommended workflow. Call this first.

vigilante_query — Query runtime events with composable filters:

Param	Type	Description
question	string	Natural language filter, or "all" to skip keywords
spanId	string	Filter to one request span (e.g. "http-3")
since	number	Events after this ID (incremental polling)
from / to	string	ISO timestamp range
track	string	Follow a key path through runtime (e.g. "user.balance")
dataflow	string	Trace data flow chain for a key path
diff	[string, string]	Compare two spans structurally
format	string	flat (default) or tree (nested call tree)
limit	number	Max events per query (default 50, max 500)

Example queries

"what errors occurred?"                          -> keyword filter
{ spanId: "http-3" }                             -> all events from one request
{ track: "user.balance" }                        -> follow balance through mutations
{ dataflow: "user.balance" }                     -> trace: read -> pass -> mutate -> return
{ diff: ["http-1", "http-3"] }                   -> compare working vs broken request
{ since: 42 }                                    -> incremental polling from last seen
{ spanId: "http-5", format: "tree" }             -> nested call tree for one request

---

Event format

{
  "id": 42,
  "timestamp": "2026-04-06T06:05:45.601Z",
  "type": "call",
  "spanId": "http-3",
  "depth": 0,
  "source": { "module": "./lib", "fn": "checkout" },
  "data": { "args": [{"balance": 500, "cart": [...]}, "alice", "HALF"] }
}

Event types: call, return, error, mutation, io_start, io_end

---

File structure

vigilante/
  context.js           -- ring buffer, span tracking, disk persistence
  server.js            -- MCP server (language-agnostic)
  register.js          -- backwards-compat entry point
  adapters/
    node.js            -- Node.js instrumentation adaptor
package.json
README.md
LICENSE

Adding a new language

Write an adaptor that:

1. Hooks function calls in the target language
2. Writes events to the same temp file in the universal format above
3. The MCP server works unchanged — it just reads the file

---

Security

Vigilante is a development-only debugging tool. It should not be used in production.

• Authorization headers are redacted automatically
• Passwords, tokens, secrets, and API keys in request bodies and function arguments are redacted
• The events file is written to the OS temp directory
• No data is sent over the network — the MCP server reads a local file via stdio

---

Philosophy

Vigilante records faithfully and analyzes nothing. The buffer is the source of truth. The LLM draws its own conclusions.