ソースマップパーサー

🌐语言: English |简体中文

このプロジェクトは、JavaScriptエラーのスタックトレースをソースコードにマッピングし、関連するコンテキスト情報を抽出できるWebAssemblyベースのソースマップパーサーを実装します。開発者はJavaScriptエラーのスタックトレースをソースコードに簡単にマッピングできるため、問題を迅速に特定して解決できます。このドキュメントは、開発者がこのツールをより深く理解し、活用するのに役立つことを目的としています。

MCP統合

注: Node.js 18+のサポートが必要です

オプション1: NPXで直接実行する

npx -y source-map-parser-mcp@latest

オプション2: ビルド成果物をダウンロードする

GitHub リリースページから対応するバージョンのビルド成果物をダウンロードし、次のコマンドを実行します。

node dist/main.es.js

ランタイムパラメータ設定

システムランタイムパラメータは、さまざまなシナリオのニーズに合わせて環境変数を通じて柔軟に設定できます。

• SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE : リソースキャッシュが占有する最大メモリ容量を設定します。デフォルトは200MBです。この値を適切に調整することで、パフォーマンスとメモリ使用量のバランスをとることができます。

• SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE : エラー箇所の周囲に表示するコンテキストコード行数を定義します。デフォルトは1行です。この値を増やすと、より多くのコンテキスト情報が提供され、問題の診断が容易になります。

例：

# Set 500MB cache and display 3 lines of context
export SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE=500
export SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE=3
npx -y source-map-parser-mcp@latest

Related MCP server: Last9 Observability MCP

機能の概要

1. スタック解析: 指定された行番号、列番号、ソース マップ ファイルに基づいて、対応するソース コードの場所を解析します。

2. バッチ処理: 複数のスタック トレースを同時に解析し、バッチ結果を返すことをサポートします。

3. コンテキスト抽出: 指定された行数のコンテキスト コードを抽出し、開発者がエラーが発生する環境をよりよく理解できるようにします。

MCP サービスツールの説明

operating_guide

MCPサービスの利用手順をご確認いただけます。チャットでのやり取りを通じて、MCPサービスの利用方法に関する情報を提供します。

parse_stack

スタック トレースとソース マップ アドレスを指定してスタック情報を解析します。

リクエスト例

• スタック: 行番号、列番号、ソース マップ アドレスなどのスタック情報。

  • line: 行番号、必須。

  • column: 列番号、必須。

  • sourceMapUrl: ソース マップ アドレス (必須)。

{
  "stacks": [
    {
      "line": 10,
      "column": 5,
      "sourceMapUrl": "https://example.com/source.map"
    }
  ]
}

応答例

{
  "content": [
    {
      "type": "text",
      "text": "[{\"success\":true,\"token\":{\"line\":10,\"column\":5,\"sourceCode\":[{\"line\":8,\"isStackLine\":false,\"raw\":\"function foo() {\"},{\"line\":9,\"isStackLine\":false,\"raw\":\"  console.log('bar');\"},{\"line\":10,\"isStackLine\":true,\"raw\":\"  throw new Error('test');\"},{\"line\":11,\"isStackLine\":false,\"raw\":\"}\"}],\"src\":\"index.js\"}}]"
    }
  ]
}

解析結果の説明

• success : 解析が成功したかどうかを示します。

• token : 解析が成功したときに返される Token オブジェクト。ソース コードの行番号、列番号、コンテキスト コードなどの情報が含まれます。

• error : 解析が失敗したときに返されるエラー情報。

実行例

システムプロンプト

実際のニーズに応じて、システムプロンプトを使用して、モデルにスタック情報の解析方法を指示することができます。セキュリティやパフォーマンス上の理由から、ソースマップをブラウザに直接公開して解析するのではなく、ソースマップのアップロードパスを処理したいチームもあるかもしれません。例えば、パスbar-special.jsをspecial/bar.js.mapに変換する場合などです。このような場合、プロンプトルールを通じてモデルにパス変換を指示することができます。

次に例を示します。

# Error Stack Trace Parsing Rules

When performing source map parsing, please follow these rules:

1. If the URL contains `special`, the file should be parsed into the `special/` directory, while removing `-special` from the filename.
2. All source map files are stored in the following CDN directory:  
   `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/`

## Examples

- Source map address for `bar-special.js`:  
  `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/special/bar.js.map`

実行時の例

エラースタック

Uncaught Error: This is a error
    at foo-special.js:49:34832
    at ka (foo-special.js:48:83322)
    at Vs (foo-special.js:48:98013)
    at Et (foo-special.js:48:97897)
    at Vs (foo-special.js:48:98749)
    at Et (foo-special.js:48:97897)
    at Vs (foo-special.js:48:98059)
    at sv (foo-special.js:48:110550)
    at foo-special.js:48:107925
    at MessagePort.Ot (foo-special.js:25:1635)

よくある質問

1. WebAssemblyモジュールの読み込み失敗

ツールが次のエラー メッセージを返す場合は、次のようにトラブルシューティングしてください。

パーサー初期化エラー: WebAssembly.instantiate(): 無効な値型 'externref'、--experimental-wasm-reftypes @+86 で有効にしてください

1. Node.jsのバージョンを確認：Node.jsのバージョンが18以上であることを確認してください。18未満の場合は、Node.jsをアップグレードしてください。

2. 実験的フラグを有効にする: Node.js のバージョンが 18 以上であるにもかかわらず問題が発生する場合は、次のコマンドを使用してツールを起動します。

   npx --node-arg=--experimental-wasm-reftypes -y source-map-parser-mcp@latest

地域開発ガイド

1. 依存関係をインストールする

Node.js と npm がインストールされていることを確認してから、次のコマンドを実行してプロジェクトの依存関係をインストールします。

npm install

2. MCPサービスへのリンク

MCP サーバーを起動するには、次のコマンドを実行します。

npx tsx src/main.ts

内部ロジックの概要

1. メインファイルの説明

• stack_parser_js_sdk.js : WebAssembly モジュールの JavaScript ラッパー。コア スタック解析機能を提供します。

• parser.ts : パーサーのメイン実装。WebAssembly モジュールの初期化、ソースマップ コンテンツの取得、スタック情報の解析を担当します。

• server.ts : MCP サーバーの実装。外部呼び出し用のparse_stackツール インターフェイスを提供します。

2. 解析ロジックを変更する

解析ロジックを変更するには、 parser.tsファイル内のgetSourceTokenメソッドを編集します。

3. 新しいツールを追加する

server.tsファイルでは、 server.toolメソッドを使用して新しいツール インターフェイスを追加できます。

注記

1. ソース マップ ファイル: 指定されたソース マップ ファイルのアドレスにアクセス可能であり、ファイル形式が正しいことを確認します。

2. エラー処理: 解析中に、ネットワーク エラー、ファイル形式エラー、その他の問題が発生する可能性があります。呼び出しを行うときは適切なエラー処理を実装することをお勧めします。

寄稿ガイドライン

このプロジェクトを改善するために、Issue および Pull Request による貢献を歓迎します。

ライセンス

このプロジェクトはMITライセンスの下で提供されています。詳細はLICENSEファイルをご覧ください。