源映射解析器

🌐 语言: English | 简体中文

该项目实现了一个基于WebAssembly的源映射解析器，能够将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_API_KEY: 用于身份验证的API密钥。
• SOURCE_MAP_PARSER_CACHE_ENABLED: 控制缓存功能（值为true或false）。

功能概述

1. 初始化WebAssembly模块：通过JavaScript包装器加载和实例化WebAssembly模块，确保其正确运行。
2. 源映射内容检索：从指定的URL获取源映射文件内容，并进行必要的验证。
3. 堆栈信息解析：将错误堆栈追踪中的每个位置信息解析为目标源代码的位置。

MCP服务工具描述

核心接口

• parse_stack: 解析给定的错误堆栈字符串，返回解析后的结果。

示例用法

const result = await parse_stack({
  stack: /* 错误堆栈字符串 */,
  options: {
    cacheProvider: /* 缓存提供者实例 */,
    sourceMapCacheEnabled: true,
    apiKey: 'your_api_key'
  }
});

高级用法

自定义解析逻辑

在parser.ts文件中，可以通过重写getSourceToken方法来实现自定义的解析逻辑。

扩展工具接口

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

常见问题解答

1. WebAssembly模块初始化失败

   如果遇到以下错误信息：

   parser init error: WebAssembly.instantiate(): invalid value type 'externref', enable with --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
     

本地开发指南

安装依赖项

确保已安装Node.js和npm，然后运行以下命令安装项目依赖：

npm install

链接MCP服务

运行以下命令启动MCP服务器：

npx tsx src/main.ts

注意事项

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

贡献指南

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

许可证

本项目使用MIT许可证。更多细节请参见LICENSE文件。