源映射解析器

🌐语言:英语|简体中文

该项目实现了一个基于 WebAssembly 的 Source Map 解析器，它可以将 JavaScript 错误堆栈轨迹映射回源代码并提取相关的上下文信息。开发者可以轻松地将 JavaScript 错误堆栈轨迹映射回源代码，以便快速识别和解决问题。本文档旨在帮助开发者更好地理解和使用此工具。

MCP 集成

注意：需要 Node.js 18+ 支持

选项 1：直接使用 NPX 运行

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

选项 2：下载构建工件

从GitHub Release页面下载相应版本的构建工件，然后运行：

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`

通过提供堆栈跟踪和源映射地址来解析堆栈信息。

请求示例

stacks：堆栈信息，包括行号、列号和 Source Map 地址。
- line：行号，必填。
- column：列号，必填。
- sourceMapUrl：SourceMap地址，必填。

{
  "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 Map 直接暴露给浏览器进行解析，而是需要对 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 模块加载失败

如果工具返回以下错误信息，请按照如下方法排除故障：

解析器初始化错误：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 模块、检索 Source Map 内容以及解析堆栈信息。
server.ts ：MCP 服务器的实现，提供parse_stack工具接口供外部调用。

2.修改解析逻辑

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

3.添加新工具

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

笔记

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

贡献指南

欢迎通过问题和拉取请求做出贡献来改进这个项目。

执照

本项目遵循 MIT 许可证。详情请参阅许可证文件。

Source Map Parser MCP Server

Integrations