【技术文档摘要】

源码映射解析器

🌐 语言: English | 简体中文

<a href="https://glama.ai/mcp/servers/@MasonChow/source-map-parser-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@MasonChow/source-map-parser-mcp/badge" /> </a>

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

MCP 集成

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

选项 1：直接使用 NPX 运行

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

选项 2：下载构建工件

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

node dist/main.es.js

作为 npm 包使用（自带 MCP 服务器）

你可以将这些工具嵌入到自己的 MCP 服务器进程中并自定义行为。

安装：

npm install source-map-parser-mcp

最小化服务器（TypeScript）：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
  registerTools,
  Parser,
  type ToolsRegistryOptions,
} from 'source-map-parser-mcp';

const server = new McpServer(
  { name: 'your-org.source-map-parser', version: '0.0.1' },
  { capabilities: { tools: {} } }
);

// 可选：通过环境变量控制上下文行数
const options: ToolsRegistryOptions = {
  contextOffsetLine:
    Number(process.env.SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE) || 1,
};

registerTools(server, options);

// 以标准 I/O 服务器启动
const transport = new StdioServerTransport();
await server.connect(transport);

// 如果你需要在没有 MCP 的情况下进行程序化解析：
const parser = new Parser({ contextOffsetLine: 1 });
// await parser.parseStack({ line: 10, column: 5, sourceMapUrl: 'https://...' });
// await parser.batchParseStack([{ line, column, sourceMapUrl }]);

构建与类型声明

此项目提供了 ESM 和 CJS 构建以及一个单一捆绑的 TypeScript 声明文件。

• 构建输出：
  • ESM: dist/index.es.js
  • CJS: dist/index.cjs.js
  • CLI 入口: dist/main.es.js
  • 类型: dist/index.d.ts (单个捆绑的 d.ts)

本地快速构建：

npm install
npm run build

在你的项目中使用类型：

import {
  Parser,
  registerTools,
  type ToolsRegistryOptions,
} from 'source-map-parser-mcp';

运行时参数配置

系统运行时参数可以通过环境变量灵活配置，以满足不同场景的需求

• SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE: 设置资源缓存占用的最大内存空间，默认为 200MB。适当调整此值可以平衡性能和内存使用。
• SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE: 定义显示在错误位置周围的上下文代码行数，默认为 1 行。增加此值可提供更多的上下文信息，有助于问题诊断。

示例：

# 设置 500MB 缓存并显示 3 行上下文
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. 堆栈解析：根据提供的行号、列号和源码映射文件解析对应的源代码位置。
2. 批量处理：支持同时解析多个堆栈追踪并返回批量结果。
3. 上下文提取：提取指定行数的上下文代码，帮助开发者更好地理解错误发生的环境。
4. 上下文查找：查找特定编译代码位置的原始源代码上下文。
5. 源码解包：从源码映射中提取所有源文件及其内容。

MCP 服务工具描述

操作指南

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

解析堆栈

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

请求示例

• stacks: 包括行号、列号和源码映射地址的堆栈信息。
  • line: 行号，必需。
  • column: 列号，必需。
  • sourceMapUrl: 源码映射地址，必需。

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

查找上下文

查找编译/压缩代码中特定行和列位置的原始源代码上下文。

请求示例

• line: 编译代码中的行号（从 1 开始），必需。
• column: 编译代码中的列号，必需。
• sourceMapUrl: 源码映射文件的 URL，必需。
• contextLines: 要包含的上下文行数（默认：5），可选。

{
  "line": 42,
  "column": 15,
  "sourceMapUrl": "https://example.com/app.js.map",
  "contextLines": 5
}

响应示例

{
  "content": [
    {
      "type": "text",
      "text": "{\"filePath\":\"src/utils.js\",\"targetLine\":25,\"contextLines\":[{\"lineNumber\":23,\"content\":\"function calculateSum(a, b) {\"},{\"lineNumber\":24,\"content\":\"  if (a < 0 || b < 0) {\"},{\"lineNumber\":25,\"content\":\"    throw new Error('Negative numbers not allowed');\"},{\"lineNumber\":26,\"content\":\"  }\"},{\"lineNumber\":27,\"content\":\"  return a + b;\"}]}"
    }
  ]
}

解包源码

从源码映射中提取所有源文件及其内容。

请求示例

• sourceMapUrl: 要解包的源码映射文件的 URL，必需。

{
  "sourceMapUrl": "https://example.com/bundle.js.map"
}

响应示例

{
  "content": [
    {
      "type": "text",
      "text": "{\"sources\":{\"src/index.js\":\"import { utils } from './utils.js';\\nconsole.log('Hello World!');\",\"src/utils.js\":\"export const utils = { add: (a, b) => a + b };\"},\"sourceRoot\":\"/\",\"file\":\"bundle.js\",\"totalSources\":2}"
    }
  ]
}

解析结果描述

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

示例运行

系统提示

根据实际需求，你可以使用系统提示来指导模型如何解析堆栈信息。出于安全或性能原因，某些团队可能不想直接将源码映射暴露给浏览器进行解析，而是处理源码映射上传路径。例如，将路径 bar-special.js 转换为 special/bar.js.map。在这种情况下，你可以通过提示规则指示模型执行路径转换。

这里是一个示例：

# 错误堆栈追踪解析规则

在执行源码映射解析时，请遵循以下规则：

1. 如果 URL 包含 `special`，则该文件应解析到 `special/` 目录下，同时从文件名中移除 `-special`。
2. 所有源码映射文件存储在以下 CDN 目录中：
   `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/`

## 示例

- `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 版本是 20 或更高。如果低于 20，请升级 Node.js。
2. 启用实验性标志：如果 Node.js 版本是 20+ 但仍然遇到问题，请使用以下命令启动工具：

   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 模块、检索源码映射内容及解析堆栈信息。
• server.ts: MCP 服务器的实现，提供 parse_stack 工具接口供外部调用。

2. 修改解析逻辑

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

3. 添加新工具

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

注意事项

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

贡献指南

欢迎通过 Issues 和 Pull Requests 提交贡献以改进此项目。

许可证

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