Analizador de mapas de origen

🌐语言: Inglés |简体中文

Este proyecto implementa un analizador de mapas de origen basado en WebAssembly que puede mapear los rastros de pila de errores de JavaScript al código fuente y extraer información de contexto relevante. Los desarrolladores pueden mapear fácilmente los rastros de pila de errores de JavaScript al código fuente para una rápida identificación y resolución de problemas. Esta documentación tiene como objetivo ayudar a los desarrolladores a comprender y utilizar mejor esta herramienta.

Integración MCP

Nota: Requiere compatibilidad con Node.js 18+

Opción 1: Ejecutar directamente con NPX

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

Opción 2: Descargar los artefactos de compilación

Descargue la versión correspondiente de los artefactos de compilación desde la página de lanzamiento de GitHub y luego ejecute:

node dist/main.es.js

Configuración de parámetros de tiempo de ejecución

Los parámetros de tiempo de ejecución del sistema se pueden configurar de forma flexible a través de variables de entorno para satisfacer las necesidades de diferentes escenarios.

• SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE : Establece el espacio máximo de memoria ocupado por la caché de recursos; el valor predeterminado es 200 MB. Ajustar este valor correctamente puede equilibrar el rendimiento y el uso de memoria.

• SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE : Define el número de líneas de código de contexto que se mostrarán alrededor de la ubicación del error; el valor predeterminado es 1 línea. Aumentar este valor proporciona más información de contexto, lo que facilita el diagnóstico del problema.

Ejemplo:

# 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@latest

Related MCP server: Error Debugging MCP Server

Descripción general de las funciones

1. Análisis de pila : analiza la ubicación del código fuente correspondiente según el número de línea, el número de columna y el archivo de mapa de origen proporcionados.

2. Procesamiento por lotes : admite el análisis de múltiples seguimientos de pila simultáneamente y devuelve resultados por lotes.

3. Extracción de contexto : extrae el código de contexto para una cantidad específica de líneas para ayudar a los desarrolladores a comprender mejor el entorno donde ocurren los errores.

Descripción de la herramienta de servicio MCP

operating_guide

Obtenga instrucciones de uso del servicio MCP. Proporciona información sobre cómo usarlo mediante chat.

parse_stack

Analizar la información de la pila proporcionando seguimientos de pila y direcciones del mapa de origen.

Ejemplo de solicitud

• pilas: información de la pila que incluye el número de línea, el número de columna y la dirección del mapa de origen.

  • línea: Número de línea, obligatorio.

  • columna: Número de columna, obligatorio.

  • sourceMapUrl: Dirección del mapa de origen, obligatoria.

{
  "stacks": [
    {
      "line": 10,
      "column": 5,
      "sourceMapUrl": "https://example.com/source.map"
    }
  ]
}

Ejemplo de respuesta

{
  "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\"}}]"
    }
  ]
}

Descripción del resultado del análisis

• success : indica si el análisis fue exitoso.

• token : el objeto Token devuelto cuando el análisis es exitoso, que contiene el número de línea del código fuente, el número de columna, el código de contexto y otra información.

• error : Se devuelve información de error cuando falla el análisis.

Ejemplo de ejecución

Indicador del sistema

Según las necesidades reales, puede usar indicaciones del sistema para guiar al modelo sobre cómo analizar la información de la pila. Por razones de seguridad o rendimiento, algunos equipos podrían no querer exponer los mapas de origen directamente al navegador para su análisis, sino procesar su ruta de carga. Por ejemplo, convertir la ruta bar-special.js a special/bar.js.map . En este caso, puede indicar al modelo que realice la conversión de ruta mediante reglas de indicaciones.

He aquí un ejemplo:

# 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`

Ejemplo de tiempo de ejecución

Pila de errores

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)

Preguntas frecuentes

1. Error al cargar el módulo WebAssembly

Si la herramienta devuelve el siguiente mensaje de error, solucione el problema de la siguiente manera:

Error de inicialización del analizador: WebAssembly.instantiate(): tipo de valor no válido 'externref', habilitar con --experimental-wasm-reftypes @+86

1. Verificar la versión de Node.js : Asegúrate de que la versión de Node.js sea la 18 o superior. Si es inferior a la 18, actualiza Node.js.

2. Habilitar bandera experimental : si la versión de Node.js es 18+ pero aún tiene problemas, use el siguiente comando para iniciar la herramienta:

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

Guía de desarrollo local

1. Instalar dependencias

Asegúrese de que Node.js y npm estén instalados, luego ejecute el siguiente comando para instalar las dependencias del proyecto:

npm install

2. Enlace del servicio MCP

Ejecute el siguiente comando para iniciar el servidor MCP:

npx tsx src/main.ts

Descripción general de la lógica interna

1. Descripción del archivo principal

• stack_parser_js_sdk.js : contenedor de JavaScript para el módulo WebAssembly, que proporciona una funcionalidad básica de análisis de pila.

• parser.ts : implementación principal del analizador, responsable de inicializar el módulo WebAssembly, recuperar el contenido del mapa fuente y analizar la información de la pila.

• server.ts : Implementación del servidor MCP, que proporciona la interfaz de la herramienta parse_stack para llamadas externas.

2. Modificar la lógica de análisis

Para modificar la lógica de análisis, edite el método getSourceToken en el archivo parser.ts .

3. Agregar nuevas herramientas

En el archivo server.ts , se pueden agregar nuevas interfaces de herramientas utilizando el método server.tool .

Notas

1. Archivos de mapas de origen : asegúrese de que la dirección del archivo de mapas de origen proporcionada sea accesible y que el formato del archivo sea correcto.

2. Manejo de errores : durante el análisis, pueden encontrarse errores de red, errores de formato de archivo y otros problemas; se recomienda implementar un manejo de errores adecuado al realizar llamadas.

Pautas de contribución

Las contribuciones a través de problemas y solicitudes de extracción son bienvenidas para mejorar este proyecto.

Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulte el archivo de LICENCIA para más detalles.