{
  "markdown": "[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/masonchow-source-map-parser-mcp-badge.png)](https://mseep.ai/app/masonchow-source-map-parser-mcp)\n\n# Source Map Parser\n\n🌐 **语言**: [English](README.md) | [简体中文](README.zh-CN.md)\n\n[![Node Version](https://img.shields.io/node/v/source-map-parser-mcp)](https://nodejs.org)\n[![npm](https://img.shields.io/npm/v/source-map-parser-mcp.svg)](https://www.npmjs.com/package/source-map-parser-mcp)\n[![Downloads](https://img.shields.io/npm/dm/source-map-parser-mcp)](https://npmjs.com/package/source-map-parser-mcp)\n[![Build Status](https://github.com/MasonChow/source-map-parser-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MasonChow/source-map-parser-mcp/actions)\n[![codecov](https://codecov.io/gh/MasonChow/source-map-parser-mcp/graph/badge.svg)](https://codecov.io/gh/MasonChow/source-map-parser-mcp)\n![](https://badge.mcpx.dev?type=server&features=tools 'MCP server with tools')\n\n<a href=\"https://glama.ai/mcp/servers/@MasonChow/source-map-parser-mcp\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@MasonChow/source-map-parser-mcp/badge\" />\n</a>\n\nThis project implements a WebAssembly-based Source Map parser that can map JavaScript error stack traces back to source code and extract relevant context information. Developers can easily map JavaScript error stack traces back to source code for quick problem identification and resolution. This documentation aims to help developers better understand and use this tool.\n\n## MCP Integration\n\n> Note: Requires Node.js 20+ support\n\nOption 1: Run directly with NPX\n\n```bash\nnpx -y source-map-parser-mcp@latest\n```\n\nOption 2: Download the build artifacts\n\nDownload the corresponding version of the build artifacts from the [GitHub Release](https://github.com/MasonChow/source-map-parser-mcp/releases) page, then run:\n\n```bash\nnode dist/main.es.js\n```\n\n### Use as an npm package (bring your own MCP server)\n\nYou can embed the tools into your own MCP server process and customize behavior.\n\nInstall:\n\n```bash\nnpm install source-map-parser-mcp\n```\n\nMinimal server (TypeScript):\n\n```ts\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport {\n  registerTools,\n  Parser,\n  type ToolsRegistryOptions,\n} from 'source-map-parser-mcp';\n\nconst server = new McpServer(\n  { name: 'your-org.source-map-parser', version: '0.0.1' },\n  { capabilities: { tools: {} } }\n);\n\n// Optional: control context lines via env\nconst options: ToolsRegistryOptions = {\n  contextOffsetLine:\n    Number(process.env.SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE) || 1,\n};\n\nregisterTools(server, options);\n\n// Start as stdio server\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n\n// If you need programmatic parsing without MCP:\nconst parser = new Parser({ contextOffsetLine: 1 });\n// await parser.parseStack({ line: 10, column: 5, sourceMapUrl: 'https://...' });\n// await parser.batchParseStack([{ line, column, sourceMapUrl }]);\n```\n\n### Build and Type Declarations\n\nThis project ships both ESM and CJS builds and a single bundled TypeScript declaration file.\n\n- Build outputs:\n  - ESM: `dist/index.es.js`\n  - CJS: `dist/index.cjs.js`\n  - CLI entry: `dist/main.es.js`\n  - Types: `dist/index.d.ts` (single bundled d.ts)\n\nQuick build locally:\n\n```bash\nnpm install\nnpm run build\n```\n\nUsing types in your project:\n\n```ts\nimport {\n  Parser,\n  registerTools,\n  type ToolsRegistryOptions,\n} from 'source-map-parser-mcp';\n```\n\n### Runtime Parameter Configuration\n\n> System runtime parameters can be flexibly configured through environment variables to meet the needs of different scenarios\n\n- `SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE`: Sets the maximum memory space occupied by resource cache, default is 200MB. Adjusting this value appropriately can balance performance and memory usage.\n- `SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE`: Defines the number of context code lines to display around the error location, default is 1 line. Increasing this value provides more context information, facilitating problem diagnosis.\n\n**Example:**\n\n```bash\n# Set 500MB cache and display 3 lines of context\nexport SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE=500\nexport SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE=3\nnpx -y source-map-parser-mcp@latest\n```\n\n## Feature Overview\n\n1. **Stack Parsing**: Parse the corresponding source code location based on provided line number, column number, and Source Map file.\n2. **Batch Processing**: Support parsing multiple stack traces simultaneously and return batch results.\n3. **Context Extraction**: Extract context code for a specified number of lines to help developers better understand the environment where errors occur.\n4. **Context Lookup**: Look up original source code context for specific compiled code positions.\n5. **Source Unpacking**: Extract all source files and their content from source maps.\n\n## MCP Service Tool Description\n\n### `operating_guide`\n\nGet usage instructions for the MCP service. Provides information on how to use the MCP service through chat interaction.\n\n### `parse_stack`\n\nParse stack information by providing stack traces and Source Map addresses.\n\n#### Request Example\n\n- stacks: Stack information including line number, column number, and Source Map address.\n  - line: Line number, required.\n  - column: Column number, required.\n  - sourceMapUrl: Source Map address, required.\n\n```json\n{\n  \"stacks\": [\n    {\n      \"line\": 10,\n      \"column\": 5,\n      \"sourceMapUrl\": \"https://example.com/source.map\"\n    }\n  ]\n}\n```\n\n#### Response Example\n\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"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\\\"}}]\"\n    }\n  ]\n}\n```\n\n### `lookup_context`\n\nLook up original source code context for a specific line and column position in compiled/minified code.\n\n#### Request Example\n\n- line: The line number in the compiled code (1-based), required.\n- column: The column number in the compiled code, required.\n- sourceMapUrl: The URL of the source map file, required.\n- contextLines: Number of context lines to include (default: 5), optional.\n\n```json\n{\n  \"line\": 42,\n  \"column\": 15,\n  \"sourceMapUrl\": \"https://example.com/app.js.map\",\n  \"contextLines\": 5\n}\n```\n\n#### Response Example\n\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"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;\\\"}]}\"\n    }\n  ]\n}\n```\n\n### `unpack_sources`\n\nExtract all source files and their content from a source map.\n\n#### Request Example\n\n- sourceMapUrl: The URL of the source map file to unpack, required.\n\n```json\n{\n  \"sourceMapUrl\": \"https://example.com/bundle.js.map\"\n}\n```\n\n#### Response Example\n\n```json\n{\n  \"content\": [\n    {\n      \"type\": \"text\",\n      \"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}\"\n    }\n  ]\n}\n```\n\n### Parsing Result Description\n\n- `success`: Indicates whether the parsing was successful.\n- `token`: The Token object returned when parsing is successful, containing source code line number, column number, context code, and other information.\n- `error`: Error information returned when parsing fails.\n\n## Example Run\n\n### System Prompt\n\nAccording to actual needs, you can use system prompts to guide the model on how to parse stack information. For security or performance reasons, some teams may not want to expose Source Maps directly to the browser for parsing, but instead process the upload path of the Source Map. For example, converting the path `bar-special.js` to `special/bar.js.map`. In this case, you can instruct the model to perform path conversion through prompt rules.\n\nHere is an example:\n\n```markdown\n# Error Stack Trace Parsing Rules\n\nWhen performing source map parsing, please follow these rules:\n\n1. If the URL contains `special`, the file should be parsed into the `special/` directory, while removing `-special` from the filename.\n2. All source map files are stored in the following CDN directory:  \n   `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/`\n\n## Examples\n\n- Source map address for `bar-special.js`:  \n  `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/special/bar.js.map`\n```\n\n### Runtime Example\n\nError Stack\n\n```\nUncaught Error: This is a error\n    at foo-special.js:49:34832\n    at ka (foo-special.js:48:83322)\n    at Vs (foo-special.js:48:98013)\n    at Et (foo-special.js:48:97897)\n    at Vs (foo-special.js:48:98749)\n    at Et (foo-special.js:48:97897)\n    at Vs (foo-special.js:48:98059)\n    at sv (foo-special.js:48:110550)\n    at foo-special.js:48:107925\n    at MessagePort.Ot (foo-special.js:25:1635)\n```\n\n![Runtime Example](https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/example_en.png)\n\n## FAQ\n\n### 1. WebAssembly Module Loading Failure\n\nIf the tool returns the following error message, please troubleshoot as follows:\n\n> parser init error: WebAssembly.instantiate(): invalid value type 'externref', enable with --experimental-wasm-reftypes @+86\n\n1. **Check Node.js Version**: Ensure Node.js version is 20 or higher. If it's lower than 20, please upgrade Node.js.\n2. **Enable Experimental Flag**: If Node.js version is 20+ but you still encounter issues, use the following command to start the tool:\n   ```bash\n   npx --node-arg=--experimental-wasm-reftypes -y source-map-parser-mcp@latest\n   ```\n\n## Local Development Guide\n\n### 1. Install Dependencies\n\nEnsure Node.js and npm are installed, then run the following command to install project dependencies:\n\n```bash\nnpm install\n```\n\n### 2. Link MCP Service\n\nRun the following command to start the MCP server:\n\n```bash\nnpx tsx src/main.ts\n```\n\n### Internal Logic Overview\n\n#### 1. Main File Description\n\n- **`stack_parser_js_sdk.js`**: JavaScript wrapper for the WebAssembly module, providing core stack parsing functionality.\n- **`parser.ts`**: Main implementation of the parser, responsible for initializing the WebAssembly module, retrieving Source Map content, and parsing stack information.\n- **`server.ts`**: Implementation of the MCP server, providing the `parse_stack` tool interface for external calls.\n\n#### 2. Modify Parsing Logic\n\nTo modify the parsing logic, edit the `getSourceToken` method in the `parser.ts` file.\n\n#### 3. Add New Tools\n\nIn the `server.ts` file, new tool interfaces can be added using the `server.tool` method.\n\n## Notes\n\n1. **Source Map Files**: Ensure that the provided Source Map file address is accessible and the file format is correct.\n2. **Error Handling**: During parsing, network errors, file format errors, and other issues may be encountered; it's recommended to implement proper error handling when making calls.\n\n## Contribution Guidelines\n\nContributions via Issues and Pull Requests are welcome to improve this project.\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n",
  "bytes": 11696,
  "sha": "489d7d2ddb926f8f01ee8253f66f232ea163ba015d522ad633d9ed902181d64d",
  "repo_slug": "masonchow/source-map-parser-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_masonchow_source_map_parser_mc_0a4fc241/readme"
}