sourcemap-retrace-mcp

🗺️ sourcemap-retrace-mcp

你的应用在生产环境中崩溃了。堆栈跟踪毫无用处。你的 AI Agent 完全不知道 Bug 出在哪里。

MCP 服务利用 source map，将压缩后的生产环境堆栈跟踪还原为原始 TypeScript 源文件、行和列的位置——免得你的 Agent 花 20 分钟猜测混淆代码的含义。

---

🤔 问题

你的监控工具发来这样的信息：

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)

你让 Agent 帮忙调试。Agent 读取 main.a3f2c1.js。这是一个包含 40,000 个字符的压缩 JavaScript 文件。它完全不知道第 47821 列的 e.<anonymous> 是什么意思。

sourcemap-retrace-mcp 会将其映射回：

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

现在 Agent 确切知道该查看哪里了。

---

🛠️ 工具

retrace_stack

将压缩后的堆栈跟踪还原为原始 TypeScript 源代码位置。传入原始堆栈跟踪以及包含 .js.map 文件的目录。

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

显示映射后的错误位置周围的原始源代码行，并附带行号和列指示符。

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

验证 dist 目录中的 .map 文件是否存在，以及它们指向的源文件是否确实存在于磁盘上。在部署前发现过期或缺失的映射文件。

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

---

⚡ 设置

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

---

🚀 使用方法

“我遇到了生产环境错误。这是堆栈跟踪：[粘贴内容]。我的 dist 文件在 /path/to/dist。请还原堆栈跟踪，显示错误周围的代码，并告诉我问题出在哪里。”

Agent 会运行 retrace_stack，然后对映射后的位置运行 retrieve_code_context，最后就能读取实际发生崩溃的 TypeScript 代码。

也非常适合与以下工具搭配使用：

• env-secret-exposure-analyzer-mcp — 部署前扫描密钥
• release-readiness-triage-mcp — 发布前检查 CI 健康状况

---

📦 链接

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

许可证

MIT