Perfetto

Perfetto MCP

Transforme linguagem natural em análise poderosa de traces do Perfetto

Um servidor Model Context Protocol (MCP) que transforma prompts em linguagem natural em análises focadas do Perfetto. Explique rapidamente jank, diagnostique ANRs, identifique threads quentes de CPU, descubra contenção de locks e encontre vazamentos de memória – tudo sem escrever SQL.

✨ Recursos

• Linguagem Natural → SQL: Faça perguntas em inglês simples, obtenha consultas precisas do Perfetto
• Detecção de ANR: Identifique e analise automaticamente eventos de Application Not Responding
• Análise de Performance: Perfil de CPU, detecção de jank de frames, detecção de vazamento de memória
• Contenção de Threads: Encontre gargalos de sincronização e contenção de locks
• Perfil de Binder: Analise performance de IPC e interações lentas do sistema

📋 Pré-requisitos

• Python 3.13+ (macOS/Homebrew):

  brew install python@3.13
  

• uv (recomendado):

  brew install uv
  

🚀 Começando

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

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

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

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

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

Opcional: Use um Binário Local trace_processor_shell

Se o seu ambiente de rede bloquear downloads, defina PERFETTO_MCP_TRACE_PROCESSOR_BIN_PATH para um caminho absoluto de um binário local trace_processor_shell.

Quando esta variável de ambiente estiver definida, perfetto-mcp usa esse binário diretamente. Quando não estiver definida, o comportamento padrão do Python perfetto permanece inalterado.

Exemplo (mcp.json):

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

Exemplo (~/.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"

Instalação Local (servidor de desenvolvimento)

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

📖 Como Usar

Exemplo de prompt inicial:

No trace do perfetto, vejo que o FragmentManager está levando 438ms para executar. Você consegue descobrir por que está demorando tanto?

Parâmetros Obrigatórios

Cada ferramenta precisa destas duas entradas:

Nos Seus Prompts

Seja explícito sobre o trace e o processo, prefixe seu prompt com:

"Use o trace do perfetto /absolute/path/to/trace.perfetto-trace para o processo com.example.app"

Filtros Opcionais

Muitas ferramentas suportam filtragem adicional (mas deixe seu LLM cuidar disso):

• time_range: {start_ms: 10000, end_ms: 25000}
• Limiares específicos da ferramenta: min_block_ms, jank_threshold_ms, limit

🛠️ Ferramentas Disponíveis

🔎 Exploração e Descoberta

🚨 Análise de ANR

Nota: Útil se o trace gravado contiver ANR

🎯 Perfil de Performance

📱 Performance de UI

🔒 Concorrência e IPC

💾 Análise de Memória

Formato de Saída

Todas as ferramentas retornam JSON estruturado com:

• Resumo: Descobertas de alto nível
• Detalhes: Resultados específicos da ferramenta
• Metadados: Contexto de execução e quaisquer fallbacks usados

📚 Recursos

• Trace Processor Python API - Interface Python do Perfetto
• Perfetto SQL Syntax - Referência SQL para consultas personalizadas

📄 Licença

Licença Apache 2.0. Consulte LICENSE para detalhes.

GitHub • Issues • Documentation