source-map-parser-mcp

[](https://mseep.ai/app/masonchow-source-map-parser-mcp) # Source Map Parser 🌐 **语言**: [English](README.md) | [简体中文](README.zh-CN.md) [](https://nodejs.org) [](https://www.npmjs.com/package/source-map-parser-mcp) [](https://npmjs.com/package/source-map-parser-mcp) [](https://github.com/MasonChow/source-map-parser-mcp/actions) [](https://codecov.io/gh/MasonChow/source-map-parser-mcp)  <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的Source Map解析器，可以将JavaScript错误堆栈追踪映射回源代码，并提取相关的上下文信息。开发者可以轻松地将JavaScript错误堆栈追踪映射回源代码，以快速识别和解决问题。本文件旨在帮助开发者更好地理解和使用该工具。 ## MCP集成 > 注意：需要支持Node.js 20+ 选项1：直接使用NPX运行 ```bash npx -y source-map-parser-mcp@latest ``` 选项2：下载构建产物 从[GitHub Release](https://github.com/MasonChow/source-map-parser-mcp/releases)页面下载相应版本的构建产物，然后运行： ```bash node dist/main.es.js ``` ### 作为npm包使用（自带MCP服务器） 您可以将工具嵌入到自己的MCP服务器进程中，并自定义行为。 安装： ```bash npm install source-map-parser-mcp ``` 最小服务器（TypeScript）： ```ts 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); // 作为stdio服务器启动 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） 快速本地构建： ```bash npm install npm run build ``` 在您的项目中使用类型： ```ts 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行。增加此值可以提供更多上下文信息，便于问题诊断。 **示例：** ```bash # 设置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. **堆栈解析**：根据提供的行号、列号和Source Map文件解析相应的源代码位置。 2. **批处理**：支持同时解析多个堆栈追踪并返回批量结果。 3. **上下文提取**：提取指定行数的上下文代码，帮助开发者更好地理解错误发生的环境。 4. **上下文查找**：查找特定编译代码位置的原始源代码上下文。 5. **源代码解包**：从Source Map中提取所有源文件及其内容。 ## MCP服务工具描述 ### `operating_guide` 获取MCP服务的使用说明。提供如何通过聊天交互使用MCP服务的信息。 ### `parse_stack` 通过提供堆栈追踪和Source Map地址解析堆栈信息。 #### 请求示例 - stacks：包含行号、列号和Source Map地址的堆栈信息。 - line：行号，必填。 - column：列号，必填。 - sourceMapUrl：Source Map地址，必填。 ```json { "stacks": [ { "line": 10, "column": 5, "sourceMapUrl": "https://example.com/source.map" } ] } ``` #### 响应示例 ```json { "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` 查找编译/压缩代码中特定行和列位置的原始源代码上下文。 #### 请求示例 - line：编译代码中的行号（1-based），必填。 - column：编译代码中的列号，必填。 - sourceMapUrl：Source Map文件的URL，必填。 - contextLines：要包含的上下文行数（默认：5），可选。 ```json { "line": 42, "column": 15, "sourceMapUrl": "https://example.com/app.js.map", "contextLines": 5 } ``` #### 响应示例 ```json { "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;\"}]}" } ] } ``` ### `unpack_sources` 从Source Map中提取所有源文件及其内容。 #### 请求示例 - sourceMapUrl：要解包的Source Map文件的URL，必填。 ```json { "sourceMapUrl": "https://example.com/bundle.js.map" } ``` #### 响应示例 ```json { "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`：解析失败时返回的错误信息。 ## 示例运行 ### 系统提示 根据实际需要，您可以使用系统提示来指导模型如何解析堆栈信息。出于安全或性能原因，一些团队可能不希望直接将Source Maps暴露给浏览器进行解析，而是处理Source Map的上传路径。例如，将路径`bar-special.js`转换为`special/bar.js.map`。在这种情况下，您可以通过提示规则指示模型执行路径转换。 以下是一个示例： ```markdown # 错误堆栈追踪解析规则 在进行Source Map解析时，请遵循以下规则： 1. 如果URL包含`special`，则文件应解析到`special/`目录，同时从文件名中移除`-special`。 2. 所有Source Map文件存储在以下CDN目录： `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/` ## 示例 - `bar-special.js`的Source Map地址： `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+但仍然遇到问题，请使用以下命令启动工具： ```bash npx --node-arg=--experimental-wasm-reftypes -y source-map-parser-mcp@latest ``` ## 本地开发指南 ### 1. 安装依赖 确保已安装Node.js和npm，然后运行以下命令安装项目依赖： ```bash npm install ``` ### 2. 链接MCP服务 运行以下命令启动MCP服务器： ```bash 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文件地址可访问，并且文件格式正确。 2. **错误处理**：在解析过程中，可能会遇到网络错误、文件格式错误等问题；建议在调用时实现适当的错误处理。 ## 贡献指南 欢迎通过Issues和Pull Requests贡献，以改善该项目。 ## 许可证 该项目根据MIT许可证进行许可。有关详细信息，请参见LICENSE文件。