Sourcemap Retrace

npm CI License: MIT

Your app crashed in production. The stack trace is useless. Your AI agent has no idea where the bug is.

MCP server that decodes minified production stack traces back to original TypeScript source files, lines, and columns — using source maps. Before your agent spends 20 minutes guessing at obfuscated code.

---

🤔 The problem

Your monitoring tool sends you this:

TypeError: Cannot read properties of undefined (reading 'userId')
    at e.<anonymous> (main.a3f2c1.js:1:47821)
    at h (vendor.d4e5f6.js:1:12045)
    at processQueue (main.a3f2c1.js:1:89234)

You ask your agent to debug it. The agent reads main.a3f2c1.js. It's 40,000 characters of minified JavaScript. It has no idea what e.<anonymous> at column 47821 means.

sourcemap-retrace-mcp maps that back to:

    at validateSession (src/auth/session.ts:142:8)
    at handleRequest (src/api/middleware.ts:67:3)

Now the agent knows exactly where to look.

---

🛠️ Tools

retrace_stack

Decode a minified stack trace back to original TypeScript source locations. Pass the raw stack trace and the directory containing your .js.map files.

Retrace Results
  Frames mapped: 3  |  Unmapped: 1

TypeError: Cannot read properties of undefined (reading 'userId')
    at validateSession (src/auth/session.ts:142:8)
    at handleRequest (src/api/middleware.ts:67:3)
    at processQueue (src/queue/processor.ts:28:12)
    at Module._compile (node:internal/modules/cjs/loader:1376:14)

retrieve_code_context

Show the original source lines surrounding a mapped error location — with line numbers and a column pointer.

Code Context
  File: src/auth/session.ts
  Target: line 142, column 8

  139 │   const session = await getSession(token);
  140 │   if (!session) throw new AuthError("invalid token");
  141 │
> 142 │   return session.userId;
        │         ^
  143 │ }
  144 │
  145 │ export async function refreshSession(token: string) {

audit_sourcemap_match

Validate that .map files in your dist directory are present and point to source files that actually exist on disk. Catches stale or missing maps before deployment.

Sourcemap Audit
  Directory: dist/
  Files checked: 4
  OK: 3  |  Missing maps: 0  |  Broken sources: 1

  ✓ main.a3f2c1.js — 47 source(s) mapped
  ✓ vendor.d4e5f6.js — 312 source(s) mapped
  ✓ worker.b1c2d3.js — 8 source(s) mapped
  ⚠ legacy.e7f8a9.js — 2 source(s) not found on disk:
      ../src/utils/deprecated.ts
      ../src/utils/compat.ts

---

⚡ Setup

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

---

🚀 Usage

"I have a production error. Here's the stack trace: [paste]. My dist files are in /path/to/dist. Retrace it, show me the code around the error, and tell me what's wrong."

The agent runs retrace_stack, then retrieve_code_context on the mapped location, and can finally read the actual TypeScript that crashed.

Works great alongside:

• env-secret-exposure-analyzer-mcp — scan for secrets before deploying
• release-readiness-triage-mcp — CI health check before release

---

📦 Links

• npm: npmjs.com/package/sourcemap-retrace-mcp
• GitHub: github.com/vola-trebla/sourcemap-retrace-mcp

License

MIT