flaredump

Flight recorder for Cloudflare Workers: capture failed requests (D1, KV, R2, and Workers AI reads) into .cfreplay.json and replay them offline in milliseconds.

Install

Bun / npm:

bunx flaredump replay ./crash.cfreplay.json
npx flaredump replay ./crash.cfreplay.json

# or install in your project / globally
bun add -d flaredump
npm i -D flaredump

JSR:

bunx jsr add @kanchingyg/flaredump
npx jsr add @kanchingyg/flaredump

Related MCP server: FlowLens MCP

Quick start

npx flaredump replay ./crash.cfreplay.json
bunx flaredump replay ./crash.cfreplay.json
npx flaredump --explain ./crash.cfreplay.json --model ollama/qwen2.5-coder:7b
npx flaredump --mcp

Worker middleware

import { withFlareDump } from "flaredump";

export default withFlareDump(async (request, env) => {
  const rows = await env.DB.prepare("SELECT 1").all();
  return Response.json(rows);
});

On throw or status >= 500, flaredump serializes the request plus binding results (secrets redacted as [REDACTED]).

MCP (Cursor, Claude Code, Kilo Code, Pi)

Add to your MCP config:

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

Local models (Ollama / LM Studio)

Use --explain with any OpenAI-compatible or Ollama endpoint to summarize a capture:

npx flaredump --explain crash.cfreplay.json --model ollama/qwen2.5-coder:7b

MCP Tools Reference

Editor and Agent Integration

Cursor (.cursor/mcp.json)

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

Claude Code CLI

claude mcp add flaredump -- npx -y flaredump --mcp

Programmatic Usage (JSR / TypeScript)

import * as bridge from "jsr:@kanchingyg/flaredump/bridge";

Runtime Safety and Guardrails

• Stdio frame isolation: When --mcp is active, hijackStdoutForMcp() redirects accidental console.log calls to stderr so JSON-RPC 2.0 frames on stdout never corrupt.

• Read-only by default: Mutating tools (mutates: true) are blocked in --dry-run mode and require explicit --allow-write authorization.

• Loop breaker: Repeated identical (toolName, args) invocations are hashed with SHA-256 and halted after 3 consecutive repeats to prevent runaway agent loops.

• Context budget truncation: Tool outputs are middle-truncated (60% head / 40% tail) scaled to the probed local model n_ctx (Ollama /api/show, llama.cpp /props, vLLM /v1/models).

• Secret redaction and path normalization: AWS keys (AKIA*, ASIA*), bearer tokens, and sk-* keys are scrubbed before returning tool output, and Windows drive paths (C:\...) translate cleanly to /mnt/c/... when WSL mode is enabled.

License

MIT