ソースマップパーサー

🌐语言: 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

機能の概要

スタック解析: 指定された行番号、列番号、ソースマップファイルに基づいて、対応するソースコードの場所を解析します。
バッチ処理: 複数のスタックトレースを同時に解析し、バッチ結果を返すことをサポートします。
コンテキスト抽出: 指定された行数のコンテキストコードを抽出し、開発者がエラーが発生する環境をよりよく理解できるようにします。

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 で有効にしてください

Node.jsのバージョンを確認：Node.jsのバージョンが18以上であることを確認してください。18未満の場合は、Node.jsをアップグレードしてください。
実験的フラグを有効にする: 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メソッドを使用して新しいツールインターフェイスを追加できます。

注記

ソースマップファイル: 指定されたソースマップファイルのアドレスにアクセス可能であり、ファイル形式が正しいことを確認します。
エラー処理: 解析中に、ネットワークエラー、ファイル形式エラー、その他の問題が発生する可能性があります。呼び出しを行うときは適切なエラー処理を実装することをお勧めします。

寄稿ガイドライン

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

ライセンス

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

Source Map Parser MCP Server

Integrations