sourcemap-retrace-mcp

🗺️ sourcemap-retrace-mcp

本番環境でアプリがクラッシュしました。スタックトレースは役に立ちません。AI エージェントにもバグの場所が分かりません。

ソースマップを使って、本番環境の圧縮されたスタックトレースを元の TypeScript ソースファイル、行、列に変換する MCP サーバーです。エージェントが難読化されたコードを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)

エージェントにデバッグを依頼します。エージェントは 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)

これでエージェントは、確認すべき場所を正確に把握できます。

---

🛠️ ツール

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 にあります。トレースを元に戻して、エラー周辺のコードを表示し、原因を教えてください。」

エージェントは 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