Source Map Parser MCP

🚀 Source Map Parser

This project implements a WebAssembly-based source map parser that can map JavaScript error stack traces back to the source code and extract relevant context information. Developers can easily map JavaScript error stack traces back to the source code, quickly locate and resolve issues.

🚀 Quick Start

This document aims to help developers better understand and use this tool.

📦 Installation

MCP Integration

⚠️ Important Note

Node.js version 18 or higher is required.

Option 1: Run directly via NPX

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

Option 2: Download the build artifacts Download the corresponding version of the build artifacts from the GitHub Releases page, then run:

node dist/main.es.js

Runtime Parameter Configuration

Use the following environment variables to configure the behavior of the parser:

• SOURCE_MAP_PARSER_API_KEY: API key for authentication.
• SOURCE_MAP_PARSER_CACHE_ENABLED: Control the cache function (value is true or false).

✨ Features

1. Initialize the WebAssembly module: Load and instantiate the WebAssembly module through a JavaScript wrapper to ensure its correct operation.
2. Retrieve source map content: Obtain the source map file content from the specified URL and perform necessary validation.
3. Parse stack information: Parse each location information in the error stack trace to the location of the target source code.

📚 Documentation

MCP Service Tool Description

Core Interfaces

• parse_stack: Parse the given error stack string and return the parsed result.

Usage Examples

Basic Usage

const result = await parse_stack({
  stack: /* Error stack string */,
  options: {
    cacheProvider: /* Cache provider instance */,
    sourceMapCacheEnabled: true,
    apiKey: 'your_api_key'
  }
});

Advanced Usage

Custom Parsing Logic

In the parser.ts file, you can implement custom parsing logic by overriding the getSourceToken method.

Extend Tool Interfaces

In the server.ts file, you can use the server.tool method to add new tool interfaces.

❓ Frequently Asked Questions

WebAssembly Module Initialization Failure

If you encounter the following error message:

parser init error: WebAssembly.instantiate(): invalid value type 'externref', enable with --experimental-wasm-reftypes @+86

Please follow these steps to troubleshoot:

• Check Node.js version: Ensure that the Node.js version is 18 or higher. If it is lower than 18, please upgrade Node.js.
• Enable experimental flags: If you are using Node.js 18+ but still encounter issues, you can start the tool using the following command:

npx --node-arg=--experimental-wasm-reftypes -y source-map-parser-mcp@latest

🛠️ Local Development Guide

Install Dependencies

Ensure that Node.js and npm are installed, then run the following command to install project dependencies:

npm install

Link MCP Service

Run the following command to start the MCP server:

npx tsx src/main.ts

💡 Usage Tip

• Source map files: Please ensure that the provided source map file address is accessible and in the correct format.
• Error handling: Network errors, file format errors, and other issues may occur during the parsing process. It is recommended to perform appropriate error handling when calling.

🤝 Contribution Guide

Contributions to this project via Issues and Pull Requests are welcome.

📄 License

This project is licensed under the MIT license. For more details, please refer to the LICENSE file.