Perfetto MCP

Convierte el lenguaje natural en un potente análisis de trazas de Perfetto

Un servidor del Protocolo de Contexto de Modelo (MCP) que transforma prompts en lenguaje natural en análisis enfocados de Perfetto. Explica rápidamente el jank, diagnostica ANR, detecta hilos de CPU críticos, descubre contención de bloqueos y encuentra fugas de memoria, todo sin escribir SQL.

✨ Características

• Lenguaje natural → SQL: Haz preguntas en inglés sencillo y obtén consultas precisas de Perfetto

• Detección de ANR: Identifica y analiza automáticamente eventos de "Application Not Responding"

• Análisis de rendimiento: Perfilado de CPU, detección de jank en fotogramas, detección de fugas de memoria

• Contención de hilos: Encuentra cuellos de botella de sincronización y contención de bloqueos

• Perfilado de Binder: Analiza el rendimiento de IPC y las interacciones lentas del sistema

📋 Requisitos previos

• Python 3.13+ (macOS/Homebrew):

  brew install python@3.13

• uv (recomendado):

  brew install uv

🚀 Primeros pasos

O añádelo a ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto):

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"]
    }
  }
}

Ejecuta este comando. Consulta la documentación de MCP de Claude Code para más información.

# Add to user scope
claude mcp add perfetto-mcp --scope user -- uvx perfetto-mcp

O edita ~/claude.json (macOS) o %APPDATA%\Claude\claude.json (Windows):

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"]
    }
  }
}

o añádelo a .vscode/mcp.json (proyecto) o ejecuta el comando "MCP: Add Server":

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"]
    }
  }
}

Habilítalo en el modo Agente de GitHub Copilot Chat.

Edita ~/.codex/config.toml:

[mcp_servers.perfetto-mcp]
command = "uvx"
args = ["perfetto-mcp"]

Opcional: Usar un binario local trace_processor_shell

Si tu entorno de red bloquea las descargas, establece PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH a una ruta absoluta de un binario local trace_processor_shell.

Cuando esta variable de entorno está configurada, perfetto-mcp utiliza ese binario directamente. Cuando no está configurada, el comportamiento predeterminado de Python perfetto no cambia.

Ejemplo (mcp.json):

{
  "mcpServers": {
    "perfetto-mcp": {
      "command": "uvx",
      "args": ["perfetto-mcp"],
      "env": {
        "PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH": "D:/tools/perfetto/trace_processor_shell.exe"
      }
    }
  }
}

Ejemplo (~/.codex/config.toml):

[mcp_servers.perfetto-mcp]
command = "uvx"
args = ["perfetto-mcp"]
[mcp_servers.perfetto-mcp.env]
PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH = "D:/tools/perfetto/trace_processor_shell.exe"

Instalación local (servidor de desarrollo)

cd perfetto-mcp-server
uv sync
uv run mcp dev src/perfetto_mcp/dev.py

{
  "mcpServers": {
    "perfetto-mcp-local": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/git/repo/perfetto-mcp",
        "run",
        "-m",
        "perfetto_mcp"
      ],
      "env": { "PYTHONPATH": "src" }
    }
  }
}

pip3 install perfetto-mcp
python3 -m perfetto_mcp

📖 Cómo usar

Ejemplo de prompt inicial:

In the perfetto trace, I see that the FragmentManager is taking 438ms to execute. Can you figure out why it's taking so long?

Parámetros requeridos

Cada herramienta necesita estas dos entradas:

En tus prompts

Sé explícito sobre la traza y el proceso, anteponiendo a tu prompt:

"Use perfetto trace /absolute/path/to/trace.perfetto-trace for process com.example.app"

Filtros opcionales

Muchas herramientas admiten filtrado adicional (pero deja que tu LLM lo gestione):

• time_range: {start_ms: 10000, end_ms: 25000}

• Umbrales específicos de la herramienta: min_block_ms, jank_threshold_ms, limit

🛠️ Herramientas disponibles

🔎 Exploración y descubrimiento

🚨 Análisis de ANR

Nota: Útil si la traza grabada contiene un ANR

🎯 Perfilado de rendimiento

📱 Rendimiento de la interfaz de usuario

🔒 Concurrencia e IPC

💾 Análisis de memoria

Formato de salida

Todas las herramientas devuelven JSON estructurado con:

• Summary: Hallazgos de alto nivel

• Details: Resultados específicos de la herramienta

• Metadata: Contexto de ejecución y cualquier alternativa utilizada

📚 Recursos

• Trace Processor Python API - Interfaz de Python de Perfetto

• Perfetto SQL Syntax - Referencia SQL para consultas personalizadas

📄 Licencia

Licencia Apache 2.0. Consulta LICENSE para más detalles.