Chino tradicional | Inglés

Servidor MCP del analizador Pprof

Este es un servidor de Protocolo de Contexto de Modelo (MCP) implementado en Go, que proporciona una herramienta para analizar los perfiles de rendimiento de Go pprof.

Características

Herramienta analyze_pprof :
- Analiza el archivo Go pprof especificado y devuelve resultados de análisis serializados (por ejemplo, lista Top N o gráfico de llama JSON).
- Tipos de perfiles admitidos:
  - cpu : analiza el consumo de tiempo de CPU durante la ejecución del código para encontrar puntos críticos.
  - heap : analiza el uso de memoria actual (asignaciones de montón) para encontrar objetos y funciones con alto consumo de memoria.
  - goroutine : muestra seguimientos de la pila de todas las goroutines actuales, y se utiliza para diagnosticar bloqueos, fugas o uso excesivo de goroutine.
  - allocs : Analiza las asignaciones de memoria (incluidas las liberadas) durante la ejecución del programa para localizar código con asignaciones frecuentes. ( Aún no implementado ).
  - mutex : Analiza la contención de mutex para encontrar bloqueos. ( Aún no implementado )
  - block : Analiza las operaciones que causan bloqueos de goroutine (p. ej., esperas de canal, llamadas al sistema). ( Aún no implementado )
- Formatos de salida admitidos: text , markdown , json (lista N superior), flamegraph-json (datos de gráfico de llama jerárquico, predeterminado).
  - text , markdown : Texto legible por humanos o formato Markdown.
  - json : genera los N resultados principales en formato JSON estructurado (implementado para cpu , heap , goroutine ).
  - flamegraph-json : Genera datos jerárquicos de gráficos de llama en formato JSON, compatible con d3-flame-graph (implementado para cpu , heap , formato predeterminado). La salida es compacta.
- Número configurable de resultados Top N ( top_n , predeterminado en 5, efectivo para formatos text , markdown y json ).
Herramienta generate_flamegraph :
- Utiliza go tool pprof para generar un gráfico de llama (formato SVG) para el archivo pprof especificado, lo guarda en la ruta especificada y devuelve la ruta y el contenido SVG.
- Tipos de perfil admitidos: cpu , heap , allocs , goroutine , mutex , block .
- Requiere que el usuario especifique la ruta del archivo SVG de salida.
- Importante: esta función depende de que Graphviz esté instalado.
Herramienta open_interactive_pprof (solo macOS):
- Intenta iniciar la interfaz web interactiva go tool pprof en segundo plano para el archivo pprof especificado. Usa el puerto :8081 por defecto si no se proporciona http_address .
- Devuelve el ID de proceso (PID) del proceso pprof en segundo plano tras un lanzamiento exitoso.
- Solo macOS: esta herramienta solo funcionará en macOS.
- Dependencias: Requiere que el comando go esté disponible en la RUTA del sistema.
- Limitaciones: El servidor no captura los errores del proceso pprof en segundo plano. Los archivos temporales descargados de URL remotas no se borran automáticamente hasta que finaliza el proceso (ya sea manualmente mediante disconnect_pprof_session o al salir del servidor MCP).
Herramienta disconnect_pprof_session :
- Intenta finalizar un proceso pprof en segundo plano iniciado previamente por open_interactive_pprof , utilizando su PID.
- Primero envía una señal de interrupción y luego una señal de eliminación si la interrupción falla.

Instalación (como biblioteca/herramienta)

Puede instalar este paquete directamente usando go install :

go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

Esto instalará el ejecutable pprof-analyzer-mcp en el directorio $GOPATH/bin o $HOME/go/bin . Asegúrese de que este directorio esté en la ruta de su sistema para ejecutar el comando directamente.

Construyendo desde la fuente

Asegúrese de tener un entorno Go instalado (se recomienda Go 1.18 o superior).

En el directorio raíz del proyecto ( pprof-analyzer-mcp ), ejecute:

go build

Esto generará un archivo ejecutable llamado pprof-analyzer-mcp (o pprof-analyzer-mcp.exe en Windows) en el directorio actual.

Usando `go install` (recomendado)

También puede usar go install para instalar el ejecutable en su directorio $GOPATH/bin o $HOME/go/bin . Esto le permite ejecutar pprof-analyzer-mcp directamente desde la línea de comandos (si el directorio está añadido a la variable de entorno PATH de su sistema).

# Installs the executable using the module path defined in go.mod
go install .
# Or directly using the GitHub path (recommended after publishing)
# go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

Ejecutando con Docker

Usar Docker es una forma conveniente de ejecutar el servidor, ya que incluye la dependencia Graphviz necesaria.

Construya la imagen de Docker: en el directorio raíz del proyecto (donde se encuentra el Dockerfile ), ejecute:
docker build -t pprof-analyzer-mcp .
Ejecute el contenedor Docker:
docker run -i --rm pprof-analyzer-mcp
- El indicador -i mantiene abierto STDIN, lo cual es necesario para el transporte stdio utilizado por este servidor MCP.
- El indicador --rm elimina automáticamente el contenedor cuando sale.
Configurar el cliente MCP para Docker: para conectar su cliente MCP (como Roo Cline) al servidor que se ejecuta dentro de Docker, actualice su .roo/mcp.json :
{ "mcpServers": { "pprof-analyzer-docker": { "command": "docker run -i --rm pprof-analyzer-mcp" } } }
Asegúrese de que la imagen pprof-analyzer-mcp se haya creado localmente antes de que el cliente intente ejecutar este comando.

Liberación (automatizada mediante acciones de GitHub)

Este proyecto utiliza GoReleaser y GitHub Actions para automatizar el proceso de lanzamiento. Los lanzamientos se activan automáticamente cuando se envía al repositorio una etiqueta de Git que coincide con el patrón v* (p. ej., v0.1.0 , v1.2.3 ).

Pasos de lanzamiento:

Realizar cambios: desarrollar nuevas funciones o corregir errores.
Confirmar cambios: Confirme sus cambios usando el formato convencional (p. ej., feat: ... , fix: ... ). Esto es importante para la generación automática del registro de cambios.
git add . git commit -m "feat: Add awesome new feature" # or git commit -m "fix: Resolve issue #42"
Enviar cambios: envía tus confirmaciones a la rama principal en GitHub.
git push origin main
Crear y enviar etiqueta: cuando esté listo para publicar, cree una nueva etiqueta Git y envíela a GitHub.
# Example: Create tag v0.1.0 git tag v0.1.0 # Push the tag to GitHub git push origin v0.1.0
Liberación automática: Al enviar la etiqueta, se activará la acción de GitHub GoReleaser definida en .github/workflows/release.yml . Esta acción:
- Cree binarios para Linux, macOS y Windows (amd64 y arm64).
- Generar un registro de cambios basado en confirmaciones convencionales desde la última etiqueta.
- Cree una nueva versión de GitHub con el registro de cambios y adjunte los binarios y las sumas de comprobación compilados como activos.

Puede ver el progreso del flujo de trabajo de lanzamiento en la pestaña "Acciones" del repositorio de GitHub.

Configuración del cliente MCP

Este servidor utiliza el protocolo de transporte stdio . Debe configurarlo en su cliente MCP (por ejemplo, la extensión Roo Cline para VS Code).

Normalmente, esto implica agregar la siguiente configuración al archivo .roo/mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "pprof-analyzer": {
      "command": "pprof-analyzer-mcp"
    }
  }
}

Nota: Ajuste el valor command según el método de compilación ( go build o go install ) y la ubicación del ejecutable. Asegúrese de que el cliente MCP pueda encontrarlo y ejecutarlo.

Después de la configuración, recargue o reinicie su cliente MCP y debería conectarse automáticamente al servidor PprofAnalyzer .

Dependencias

Graphviz : La herramienta generate_flamegraph requiere Graphviz para generar gráficos de llama SVG (el comando go tool pprof invoca dot al generar SVG). Asegúrese de que Graphviz esté instalado en su sistema y que el comando dot esté disponible en la variable de entorno PATH de su sistema.Instalación de Graphviz:
- macOS (usando Homebrew):
  brew install graphviz
- Debian/Ubuntu:
  sudo apt-get update && sudo apt-get install graphviz
- CentOS/Fedora:
  sudo yum install graphviz # or sudo dnf install graphviz
- Windows (usando Chocolatey):
  choco install graphviz
- Otros sistemas: consulte la página de descarga oficial de Graphviz .

Ejemplos de uso (a través del cliente MCP)

Una vez que el servidor esté conectado, puede llamar a las herramientas analyze_pprof y generate_flamegraph usando los URI file:// , http:// o https:// para el archivo de perfil.

Ejemplo: Analizar el perfil de la CPU (formato de texto, Top 5)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
  }
}

Ejemplo: Analizar perfil de montón (formato Markdown, Top 10)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "top_n": 10,
    "output_format": "markdown"
  }
}

Ejemplo: Analizar el perfil de Goroutine (formato de texto, Top 5)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/goroutine.pprof",
    "profile_type": "goroutine"
  }
}

Ejemplo: Generar un gráfico de llamas para el perfil de la CPU

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "output_svg_path": "/path/to/save/cpu_flamegraph.svg"
  }
}

Ejemplo: Generar un gráfico de llamas para el perfil del montón (inuse_space)

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_svg_path": "/path/to/save/heap_flamegraph.svg"
  }
}

Ejemplo: Analizar el perfil de la CPU (formato JSON, Top 3)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "top_n": 3,
    "output_format": "json"
  }
}

Ejemplo: Analizar el perfil de la CPU (formato JSON de Flame Graph predeterminado)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
    // output_format defaults to "flamegraph-json"
  }
}

Ejemplo: Analizar el perfil del montón (explícitamente en formato JSON de Flame Graph)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_format": "flamegraph-json"
  }
}

Ejemplo: Analizar el perfil de CPU remota (desde la URL HTTP)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://example.com/profiles/cpu.pprof",
    "profile_type": "cpu"
  }
}

Ejemplo: Analizar el perfil de CPU en línea (desde la URL sin procesar de GitHub)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu",
    "profile_type": "cpu",
    "top_n": 5
  }
}

Ejemplo: Generar un gráfico de llamas para el perfil de montón en línea (desde la URL sin formato de GitHub)

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.heap",
    "profile_type": "heap",
    "output_svg_path": "./online_heap_flamegraph.svg"
  }
}

Ejemplo: Abrir la interfaz de usuario interactiva de Pprof para el perfil de CPU en línea (solo macOS)

{
  "tool_name": "open_interactive_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu"
    // Optional: "http_address": ":8082" // Example of overriding the default port
  }
}

Ejemplo: Desconectar una sesión de Pprof

{
  "tool_name": "disconnect_pprof_session",
  "arguments": {
    "pid": 12345 // Replace 12345 with the actual PID returned by open_interactive_pprof
  }
}

Mejoras futuras (TODO)

Implementar lógica de análisis completa para allocs , mutex y perfiles block .
Implementar el formato de salida json para tipos de allocs , mutex y perfiles block .
Establezca tipos MIME apropiados en los resultados de MCP según output_format .
Agregue un manejo de errores más robusto y un control de nivel de registro.
~~Considere admitir URI de archivos pprof remotos (por ejemplo, http:// , https:// ).~~ (Hecho)

mcp-pprof-anaylzer

Integrations

Servidor MCP del analizador Pprof

Características

Instalación (como biblioteca/herramienta)

Construyendo desde la fuente

Usando `go install` (recomendado)

Ejecutando con Docker

Liberación (automatizada mediante acciones de GitHub)

Configuración del cliente MCP

Dependencias

Ejemplos de uso (a través del cliente MCP)

Mejoras futuras (TODO)

Integrations

Servidor MCP del analizador Pprof

Características

Instalación (como biblioteca/herramienta)

Construyendo desde la fuente

Usando go install (recomendado)

Ejecutando con Docker

Liberación (automatizada mediante acciones de GitHub)

Configuración del cliente MCP

Dependencias

Ejemplos de uso (a través del cliente MCP)

Mejoras futuras (TODO)

Usando `go install` (recomendado)