](https://mseep.ai/app/masonchow-source-map-parser-mcp)
源码映射解析器
🌐（这个符号本身没有直接对应的中文翻译，它通常代表“互联网”或“世界”的概念，可以理解为“网络世界”或“全球互联”的象征） 语言: 英语 | 简体中文
](https://nodejs.org) ](https://www.npmjs.com/package/source-map-parser-mcp) ](https://npmjs.com/package/source-map-parser-mcp)   
此项目实现了一个基于WebAssembly的源映射解析器，能够将JavaScript错误堆栈跟踪映射回源代码，并提取相关的上下文信息。开发者可以轻松地将JavaScript错误堆栈跟踪映射回源代码，以便快速识别和解决问题。本文档旨在帮助开发者更好地理解和使用这一工具。
MCP 集成
注：需要Node.js 20+版本支持
选项1：直接使用NPX运行
npx -y source-map-parser-mcp@latest选项2：下载构建产物
从（相应的地方）下载对应版本的构建产物 页面，然后运行：
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: {} } }
);
// Optional: control context lines via env
const options: ToolsRegistryOptions = {
contextOffsetLine:
Number(process.env.SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE) || 1,
};
registerTools(server, options);
// Start as stdio server
const transport = new StdioServerTransport();
await server.connect(transport);
// If you need programmatic parsing without MCP:
const parser = new Parser({ contextOffsetLine: 1 });
// await parser.parseStack({ line: 10, column: 5, sourceMapUrl: 'https://...' });
// await parser.batchParseStack([{ line, column, sourceMapUrl }]);构建声明和类型声明
此项目同时提供ESM（ECMAScript模块）和CJS（CommonJS）构建版本，以及一个单独的打包TypeScript声明文件。
- 构建输出：
- ESM：（此处为缩写，具体含义需根据上下文确定，一般可翻译为“经济与社会模型”或根据具体语境翻译为其他相应含义） dist/index.es.js - CJS:（此处为缩写，具体含义需根据上下文确定，但直接翻译即为“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行。增加此值可提供更多信息上下文，有助于问题诊断。
示例：
# 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
通过提供堆栈跟踪和源映射地址来解析堆栈信息。
请求示例
- 堆栈：堆栈信息，包括行号、列号和源映射地址。
- 行号：行号，必填。 - 列：列号，必填。 - 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\"}}]"
}
]
}lookup_context
查找编译/压缩代码中特定行和列位置的原始源代码上下文。
请求示例
- 行号：编译代码中的行号（从1开始计数），必填。
- 列：编译代码中的列号，必填。
- sourceMapUrl：源映射文件的URL，必需。
- 上下文行数：要包含的上下文行数（默认：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 a + b };\"},\"sourceRoot\":\"/\",\"file\":\"bundle.js\",\"totalSources\":2}"
}
]
}解析结果描述
success指示解析是否成功。token解析成功时返回的Token对象，包含源代码行号、列号、上下文代码以及其他信息。error解析失败时返回错误信息。
示例运行
系统提示
根据实际需求，您可以使用系统提示来指导模型如何解析堆栈信息。出于安全或性能考虑，有些团队可能不希望直接将源映射（Source Maps）暴露给浏览器进行解析，而是处理源映射的上传路径。例如，转换路径 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)常见问题解答（FAQ）
1. WebAssembly模块加载失败
如果工具返回以下错误信息，请按以下步骤进行故障排除：
解析器初始化错误：WebAssembly.instantiate(): 无效的值类型 'externref'，需启用 --experimental-wasm-reftypes 选项 @+86
- 检查 Node.js 版本确保 Node.js 版本为 20 或更高。如果低于 20，请升级 Node.js。
- 启用实验性标志如果 Node.js 版本是 20+ 但你仍然遇到问题，请使用以下命令来启动工具：
npx --node-arg=--experimental-wasm-reftypes -y source-map-parser-mcp@latest本地开发指南
1. 安装依赖项
确保已安装 Node.js 和 npm，然后运行以下命令来安装项目依赖：
npm install2. 链接MCP服务
运行以下命令以启动MCP服务器：
npx tsx src/main.ts内部逻辑概述
1. 主文件说明
stack_parser_js_sdk.jsWebAssembly模块的JavaScript封装，提供核心栈解析功能。parser.ts解析器的主要实现部分，负责初始化WebAssembly模块、获取源映射（Source Map）内容以及解析堆栈信息。server.tsMCP服务器的实施，提供parse_stack用于外部调用的工具接口。
2. 修改解析逻辑
要修改解析逻辑，请编辑 getSourceToken 方法在……中 parser.ts 文件。
3. 添加新工具
在……里 server.ts 文件，可以使用（该工具）添加新的工具接口 server.tool 方法。
注释
- 源映射文件确保提供的源映射文件地址可访问且文件格式正确。
- 错误处理在解析过程中，可能会遇到网络错误、文件格式错误以及其他问题；建议在调用时实现适当的错误处理机制。
贡献指南
欢迎通过问题报告和拉取请求为本项目做出贡献。
许可证
此项目采用MIT许可证授权。详见LICENSE文件。