该项目实现了一个基于 WebAssembly 的 Source Map 解析器，它可以将 JavaScript 错误堆栈轨迹映射回源代码并提取相关的上下文信息。开发者可以轻松地将 JavaScript 错误堆栈轨迹映射回源代码，以便快速识别和解决问题。本文档旨在帮助开发者更好地理解和使用此工具。
注意：需要 Node.js 18+ 支持
选项 1：直接使用 NPX 运行
npx -y source-map-parser-mcp@latest选项 2：下载构建工件
从GitHub Release页面下载相应版本的构建工件，然后运行：
node dist/main.es.js系统运行时参数可通过环境变量灵活配置，满足不同场景的需求
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@latestRelated MCP server: Error Debugging MCP Server
堆栈解析：根据提供的行号、列号和源映射文件解析相应的源代码位置。
批处理：支持同时解析多个堆栈跟踪并返回批处理结果。
上下文提取：提取指定行数的上下文代码，帮助开发人员更好地了解错误发生的环境。
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)
如果工具返回以下错误信息，请按照如下方法排除故障：
解析器初始化错误：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确保 Node.js 和 npm 已安装，然后运行以下命令安装项目依赖项：
npm install运行以下命令启动 MCP 服务器：
npx tsx src/main.tsstack_parser_js_sdk.js ：WebAssembly 模块的 JavaScript 包装器，提供核心堆栈解析功能。
parser.ts ：解析器的主要实现，负责初始化 WebAssembly 模块、检索 Source Map 内容以及解析堆栈信息。
server.ts ：MCP 服务器的实现，提供parse_stack工具接口供外部调用。
要修改解析逻辑，请编辑parser.ts文件中的getSourceToken方法。
在server.ts文件中，可以使用server.tool方法添加新的工具接口。
源映射文件：确保提供的源映射文件地址可访问且文件格式正确。
错误处理：解析过程中可能会遇到网络错误、文件格式错误等问题，建议在调用时做好错误处理。
欢迎通过问题和拉取请求做出贡献来改进这个项目。
本项目遵循 MIT 许可证。详情请参阅许可证文件。
This tool looks up original source code context for a specific line and column position in compiled/minified code.
line: The line number in the compiled code (1-based)
column: The column number in the compiled code
sourceMapUrl: The URL of the source map file
contextLines (optional): Number of context lines to include before and after the target line (default: 5)
A JSON object containing the source code context snippet with file path, target line info, and surrounding context lines
Returns null if the position cannot be mapped
| Name | Required | Description | Default |
|---|---|---|---|
| line | Yes | The line number in the compiled code (1-based) | |
| column | Yes | The column number in the compiled code | |
| sourceMapUrl | Yes | The URL of the source map file | |
| contextLines | No | Number of context lines to include (default: 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It mentions the return value includes a JSON object or null if unmappable, but does not disclose side effects, authentication needs, or error handling behavior for invalid input or network issues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with markdown headings and a clear list of parameters. Every sentence adds value, though the parameter descriptions could be omitted since they duplicate the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup tool without output schema, the description adequately covers purpose, parameters, and return behavior including null case. It lacks error scenarios and relation to sibling tools, but is sufficient for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions. The tool description largely repeats those descriptions but adds the default value for contextLines and includes a Returns section not present in the schema. It adds minimal new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool looks up original source code context for a specific line and column in compiled code. It identifies the exact action and resource, and implicitly distinguishes from siblings like parse_stack and unpack_sources through its unique focus on source map lookups.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus its siblings (parse_stack, unpack_sources). It doesn't mention any context or prerequisites, leaving the agent without clear decision criteria for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This tool allows you to parse error stack traces by providing the following:
A downloadable source map URL.
The line and column numbers from the stack trace.
The tool will map the provided stack trace information to the corresponding source code location using the source map. It also supports fetching additional context lines around the error location for better debugging.
stacks: An array of stack trace objects, each containing:
line: The line number in the stack trace.
column: The column number in the stack trace.
sourceMapUrl: The URL of the source map file corresponding to the stack trace.
ctxOffset (optional): The number of additional context lines to include before and after the error location in the source code. Defaults to 5.
A JSON object containing the parsed stack trace information, including the mapped source code location and context lines.
If parsing fails, an error message will be returned for the corresponding stack trace.
| Name | Required | Description | Default |
|---|---|---|---|
| stacks | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the return format and error handling, but does not disclose any behavioral traits like side effects, rate limits, or authentication requirements. The description is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a header, explanation, parameter list, and return section. It is somewhat verbose but each part contributes to clarity. It is front-loaded with the purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description covers the tool's purpose, parameters, return values, and error behavior. It is missing explicit usage guidelines and a note on sibling differentiation, but overall provides sufficient context for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three fields in stacks, giving high coverage. The description adds value by explaining the optional 'ctxOffset' parameter and its default, which is not present in the schema. This enriches understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool parses error stack traces using source maps to map to source code locations. It is specific and distinct from the sibling tools 'lookup_context' and 'unpack_sources', but does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does and its parameters, but it does not provide explicit guidance on when to use this tool versus the siblings or what prerequisites are needed. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
This tool extracts all source files and their content from a source map.
sourceMapUrl: The URL of the source map file to unpack
A JSON object containing:
sources: Object with source file paths as keys and their content as values
sourceRoot: The source root path from the source map
file: The original file name
totalSources: Total number of source files found
| Name | Required | Description | Default |
|---|---|---|---|
| sourceMapUrl | Yes | The URL of the source map file to unpack |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the output format (JSON with sources, sourceRoot, etc.) but does not mention side effects, permissions, error handling, or rate limits. For a read-only tool, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one heading, a brief description, and a bulleted return list. Every sentence adds value. Information is front-loaded and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains the return format. The single parameter is described. The tool is simple and the description is complete for an agent to understand and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter, and the description restates 'sourceMapUrl' but adds no extra meaning beyond the schema. However, it does detail the return structure, which adds context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it extracts all source files and content from a source map, using specific verb 'extract' and resource 'source map sources'. It distinguishes from siblings like 'lookup_context' and 'parse_stack' by focusing on source map unpacking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Description lacks context about prerequisites, limitations, or when not to use it. Sibling tools are not compared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0lookup_contextoperating_guideunpack_sourcesoperating_guideparse_stackScored across 3 tools
Each tool has a clear, distinct purpose: lookup_context maps a single position to source context, parse_stack processes multiple stack entries, and unpack_sources extracts all source files. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun pattern in snake_case: lookup_context, parse_stack, unpack_sources. The naming is predictable and easy to understand.
With 3 tools, the server is focused and each tool serves a core need in source map parsing. While the count is small, it is appropriate for the domain; adding a validation or metadata tool could be beneficial but not necessary.
The toolset covers the primary tasks: single position mapping, stack trace parsing, and source extraction. Minor gaps exist (e.g., no direct source map metadata or validation), but the core functionality is well-covered.
Session replays, JS errors, funnel drop-offs and revenue-loss diagnostics.
Investigate errors, track deployments, analyze performance, and manage application monitoring
Track errors, manage performance alerts, and configure dashboards and monitors
Production bugs with replay, network, console and stack, ranked for your coding agent to fix.
