Diffchunk

Navegue por arquivos diff grandes com divisão inteligente em partes e ferramentas de navegação.

GitHub
8

Documentação

diffchunk

CI PyPI version Python 3.10+ License: MIT uv

Servidor MCP que permite que LLMs naveguem por arquivos de diff grandes de forma eficiente. Em vez de ler diffs inteiros sequencialmente, os LLMs podem pular diretamente para as alterações relevantes usando navegação baseada em padrões.

Problema

Diffs grandes excedem os limites de contexto dos LLMs e desperdiçam tokens com alterações irrelevantes. Um diff de 50k+ linhas não pode ser processado diretamente e a divisão manual perde as relações entre arquivos.

Solução

Servidor MCP com 5 ferramentas de navegação:

  • load_diff - Analisa o arquivo de diff com configurações personalizadas (opcional)
  • list_chunks - Mostra uma visão geral dos chunks com mapeamento de arquivos e contagem de linhas por arquivo (carregamento automático)
  • get_chunk - Recupera o conteúdo de um chunk específico (carregamento automático)
  • find_chunks_for_files - Localiza chunks por padrões de arquivo (carregamento automático)
  • get_file_diff - Extrai o diff completo de um único arquivo (carregamento automático)

Configuração

Pré-requisito: Instale o uv (um gerenciador de pacotes Python extremamente rápido) que fornece o comando uvx.

Adicione à configuração do seu cliente MCP:

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

Uso

Seu assistente de IA agora pode lidar com mudanças massivas que antes causavam falhas no Cline, Roocode, Cursor e outras ferramentas.

Usando com o Assistente de IA

Uma vez configurado, seu assistente de IA pode analisar commits, branches ou diffs grandes usando o diffchunk.

Aqui estão alguns exemplos de casos de uso:

Comparações de branches:

  • "Revise todas as alterações em develop que não estão na branch main em busca de bugs"
  • "Conte-me sobre todas as alterações que ainda não fiz merge"
  • "Quais novos recursos foram adicionados à branch staging?"
  • "Resuma todas as alterações neste repositório nas últimas 2 semanas"

Revisão de código:

  • "Use o diffchunk para verificar vulnerabilidades de segurança na minha branch de feature"
  • "Use o diffchunk para encontrar alterações que quebram algo antes de fazer merge em produção"
  • "Use o diffchunk para revisar esta grande refatoração em busca de problemas potenciais"

Análise de alterações:

  • "Use o diffchunk para me mostrar todas as migrações de banco de dados que precisam ser executadas"
  • "Use o diffchunk para encontrar quais alterações de API podem afetar nosso aplicativo móvel"
  • "Use o diffchunk para analisar todas as novas dependências adicionadas recentemente"

Análise direta de arquivos:

  • "Use o diffchunk para analisar o diff em /tmp/changes.diff e encontrar bugs"
  • "Crie um diff das minhas alterações não commitadas e revise-o"
  • "Compare minha branch local com a origin e destaque conflitos"

Dica: Regras do Assistente de IA

Adicione às instruções personalizadas do seu assistente de IA para uso automático:

When reviewing large changesets or git commits, use diffchunk to handle large diff files.
Create temporary diff files and tracking files as needed and clean up after analysis.

Como Funciona

Quando você pede ao seu assistente de IA para analisar alterações, ele usa as ferramentas do diffchunk estrategicamente:

  1. Cria o arquivo de diff (ex.: git diff main..develop > /tmp/changes.diff) com base na sua pergunta
  2. Usa list_chunks para obter uma visão geral da estrutura do diff e do escopo total, incluindo contagens de linhas por arquivo via file_details
  3. Usa find_chunks_for_files para localizar seções relevantes quando você pergunta sobre tipos específicos de arquivos
  4. Usa get_file_diff para buscar o diff completo de um arquivo específico sem carregar um chunk inteiro
  5. Usa get_chunk para examinar seções específicas sem carregar o diff inteiro no contexto
  6. Acompanha o progresso sistematicamente em grandes conjuntos de alterações, analisando chunk por chunk
  7. Limpa arquivos temporários após concluir a análise

Isso permite que seu assistente de IA lide com diffs massivos que normalmente travariam outras ferramentas, fornecendo uma análise completa sem perder contexto.

Padrões de Uso das Ferramentas

Visão geral primeiro:

list_chunks("/tmp/changes.diff")
# -> 5 chunks across 12 files, 3,847 total lines, ~15,420 tokens
# Each chunk includes token_count and file_details with per-file line counts
# Response includes total_token_count for context-budget planning

Segmentar arquivos específicos:

find_chunks_for_files("/tmp/changes.diff", "*.py")
# → [1, 3, 5] - Python file chunks

get_chunk("/tmp/changes.diff", 1)
# → Content of first Python chunk

Diff de arquivo único:

get_file_diff("/tmp/changes.diff", "src/main.py")
# → Complete diff for src/main.py (header + all hunks)

# Glob patterns work when they match exactly one file
get_file_diff("/tmp/changes.diff", "*.config")
# → Complete diff for the single matching config file

Análise sistemática:

# Process each chunk in sequence
get_chunk("/tmp/changes.diff", 1)
get_chunk("/tmp/changes.diff", 2)
# ... continue through all chunks

Configuração

Requisitos de Caminho

  • Somente caminhos absolutos: /home/user/project/changes.diff
  • Multiplataforma: Windows (C:\path) e Unix (/path)
  • Expansão de diretório pessoal: ~/project/changes.diff

Padrões de Carregamento Automático

As ferramentas carregam automaticamente com configurações otimizadas:

  • max_chunk_lines: 1000
  • skip_trivial: true (somente espaços em branco)
  • skip_generated: true (arquivos de lock, artefatos de build)

Configurações Personalizadas

Use load_diff para comportamento não padrão:

load_diff(
    "/tmp/large.diff",
    max_chunk_lines=2000,
    include_patterns="*.py,*.js",
    exclude_patterns="*test*",
    context_lines=2
)

Opções de Formato

Use o parâmetro format em get_chunk para transformar a saída para consumo por LLM:

# Default - raw diff output
get_chunk("/tmp/changes.diff", 1, format="raw")

# Annotated - structured with line numbers, file headers, hunk separation
get_chunk("/tmp/changes.diff", 1, format="annotated")

# Compact - token-efficient, only new hunks (context + added lines)
get_chunk("/tmp/changes.diff", 1, format="compact")

Formato anotado adiciona cabeçalhos ## File:, seções __new hunk__/__old hunk__ com números de linha do novo arquivo e contexto de função dos cabeçalhos @@.

Formato compacto mostra apenas o que foi adicionado ou mantido, omitindo linhas removidas e seções __old hunk__ completamente. Útil quando você só precisa ver o estado final.

Redução de Contexto

Use context_lines em load_diff para reduzir as linhas de contexto por hunk no momento do carregamento:

# Keep only 2 lines of context around each change
load_diff("/tmp/large.diff", context_lines=2)

# Keep only changes, no context
load_diff("/tmp/large.diff", context_lines=0)

Isso se combina com format - o contexto é reduzido no carregamento e a formatação é aplicada na exibição.

Formatos Suportados

  • Saída do Git diff (git diff, git show)
  • Formato de diff unificado (diff -u)
  • Múltiplos arquivos em um único diff
  • Indicadores de alteração de arquivos binários

Desempenho

  • Lida eficientemente com diffs de 100k+ linhas
  • Streaming eficiente em memória
  • Recarregamento automático em alterações de arquivo

Documentação

  • Design - Detalhes de arquitetura e implementação
  • Contribuindo - Diretrizes de contribuição e configuração de desenvolvimento

Licença

MIT