源映射解析器
🌐语言(README.md)|简体中文
该项目实现了一个基于 WebAssembly 的 Source Map 解析器，它可以将 JavaScript 错误堆栈轨迹映射回源代码并提取相关的上下文信息。开发者可以轻松地将 JavaScript 错误堆栈轨迹映射回源代码，以便快速识别和解决问题。本文档旨在帮助开发者更好地理解和使用此工具。
MCP 集成
注意：需要 Node.js 18+ 支持
选项 1：直接使用 NPX 运行
npx -y source-map-parser-mcp@latest
选项 2：下载构建工件
从GitHub Release页面下载相应版本的构建工件，然后运行：
运行时参数配置
系统运行时参数可通过环境变量灵活配置，满足不同场景的需求
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 已安装，然后运行以下命令安装项目依赖项：
2. 链接MCP服务
运行以下命令启动 MCP 服务器：
内部逻辑概述
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 许可证。详情请参阅许可证文件。