Source Map 解析器

🌐 语言: English | 简体中文

该项目实现了一个基于WebAssembly的Source Map解析器，可以将JavaScript错误堆栈跟踪映射回源代码，并提取相关的上下文信息。开发者可以轻松地将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

功能概述

1. 堆栈解析：根据提供的行号、列号和 Source Map 文件解析对应的源代码位置。
2. 批量处理：支持同时解析多个堆栈跟踪并返回批量结果。
3. 上下文提取：提取指定行数的上下文代码，帮助开发者更好地理解错误发生时的环境。

MCP 服务工具说明

operating_guide

获取 MCP 服务的使用说明。提供如何通过聊天互动使用 MCP 服务的信息。

parse_stack

通过提供堆栈跟踪和 Source Map 地址来解析堆栈信息。

请求示例

• stacks: 包含行号、列号和 Source Map 地址的堆栈信息。
  • line: 行号，必填。
  • column: 列号，必填。
  • sourceMapUrl: Source Map 地址，必填。

{
  "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: 解析失败时返回的错误信息。

示例运行

系统提示

根据实际需要，您可以使用系统提示来指导模型如何解析堆栈信息。出于安全或性能考虑，某些团队可能不希望直接将 Source Maps 暴露给浏览器进行解析，而是处理 Source Map 的上传路径。例如，将路径 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 模块加载失败

如果工具返回以下错误消息，请按如下步骤排查：

parser init error: WebAssembly.instantiate(): invalid value type 'externref', enable with --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 模块、获取 Source Map 内容以及解析堆栈信息。
• server.ts: MCP 服务器的实现，为外部调用提供 parse_stack 工具接口。

2. 修改解析逻辑

要修改解析逻辑，请编辑 parser.ts 文件中的 getSourceToken 方法。

3. 添加新工具

在 server.ts 文件中，可以使用 server.tool 方法添加新的工具接口。

注意事项

1. 源映射文件：确保提供的源映射文件地址可访问且文件格式正确。
2. 错误处理：在解析过程中可能会遇到网络错误、文件格式错误等问题；建议在调用时实现适当的错误处理。

贡献指南

欢迎通过 Issues 和 Pull Requests 为改进此项目做出贡献。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。