Source Map 解析器

🌐 语言: English | 简体中文

本项目实现了一个基于 WebAssembly 的 Source Map 解析器，可以将 JavaScript 错误堆栈跟踪映射回原始源代码，并提取相关的上下文信息。开发者可以通过将 JavaScript 错误堆栈跟踪映射到原始源代码，从而轻松定位和修复问题。我们希望这份文档能够帮助开发者更好地理解和使用这个工具。

MCP 集成

注意：最低要求的 Node.js 版本为 18+。

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

功能特性

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

MCP 服务工具

operating_guide

检索 MCP 服务的使用指南。此工具提供了一种交互式的方式来了解如何使用 MCP 服务。

parse_stack

解析堆栈跟踪信息和 Source Map URL。

请求示例

• stacks: 堆栈跟踪信息，包括行号、列号和 Source Map URL。
  • line: 行号 (必需)。
  • column: 列号 (必需)。
  • sourceMapUrl: Source Map 文件的 URL (必需)。
• ctxOffset: 上下文行数 (默认为 5)。

{
  "stacks": [
    {
      "line": 10,
      "column": 5,
      "sourceMapUrl": "https://example.com/source.map"
    }
  ],
  "ctxOffset": 5
}

响应示例

{
  "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\"}}]"
    }
  ]
}

4. 解析结果说明

• success: 表示解析是否成功。
• token: 解析成功后返回的 token 对象，包括源代码行号、列号、上下文代码等。
• error: 解析失败时返回的错误信息。

高级用法

出于安全或性能原因，一些团队可能更喜欢不直接将 Source Map 暴露给浏览器进行解析。相反，他们会预处理 Source Map 的上传路径。例如，路径 /assets/index.js 可以转换为 source_backup/index.js.map。

在这种情况下，您可以引导模型使用基于提示的规则来完成路径转换。

提示示例

**Source Map 工具使用指南**

以下是解析远程 Source Map URL 的规则，其中 `origin_url` 表示堆栈跟踪中的错误路径。

1. 基于堆栈跟踪中的源路径替换 Source Map 资源 URL：
   `https://example.com${origin_url.replace('/assets/', '/source_backup/')}.map`

2. 如果没有找到匹配的规则，请使用以下回退规则：
   `${origin_url}.map` 并重试。

FAQ

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. Source Map 文件: 确保提供的 Source Map 文件 URL 可访问且文件格式正确。
2. 上下文行: ctxOffset 参数控制要提取的上下文行数。根据您的需要进行调整。
3. 错误处理: 解析可能会遇到网络错误或文件格式错误等问题。建议在调用该工具时适当处理错误。

贡献指南

我们欢迎 Issues 和 Pull Requests，共同改进这个项目。

许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。