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 original 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. This documentation aims to help developers better understand and use this tool.

🚀 Quick Start

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: Controls the cache function (values are true or false).

✨ Features

Function Overview

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 into the location of the target source code.

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'
  }
});

🔧 Technical Details

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

1. WebAssembly module initialization fails If you encounter the following error message:

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

Please troubleshoot according to the following steps:

• Check the 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 problems, 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

Important Notes

⚠️ Important Note

Ensure that the provided source map file address is accessible and in the correct format.

💡 Usage Tip

During the parsing process, you may encounter issues such as network errors and file format errors. It is recommended to perform appropriate error handling when making calls.

🤝 Contribution Guide

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

📄 License

This project uses the MIT license. For more details, please refer to the LICENSE file.