Code Summarizer

Uma ferramenta de linha de comando que resume arquivos de código em um diretório usando Gemini Flash 2.0.

GitHub
6
Experimente este MCPPatrocinado

Documentação

Code Summarizer

Uma ferramenta de linha de comando que resume arquivos de código em um diretório usando o Gemini Flash 2.0. Agora com suporte a servidor MCP para integração com ferramentas de LLM!

Recursos

  • Processa recursivamente arquivos de código em um diretório
  • Respeita as regras de .gitignore
  • Ignora diretórios irrelevantes como node_modules, dist, etc.
  • Resume arquivos de código usando o Gemini Flash 2.0
  • Gera resumos em um arquivo de texto
  • Nível de detalhe e comprimento do resumo configuráveis
  • Servidor MCP para integração com Claude Desktop e outras ferramentas de LLM
  • Design modular para fácil integração em outros aplicativos
  • Gerenciamento seguro de chaves de API
  • Autenticação para endpoints do servidor MCP
  • Mecanismo de repetição com backoff exponencial para chamadas de LLM
  • Limitação de taxa para evitar abuso

Requisitos

  • Node.js 18+

Instalação

  1. Clone o repositório

    git clone https://github.com/nicobailon/code-summarizer.git
cd code-summarizer

  2. Instale as dependências:

    npm install

  3. Crie um arquivo .env com sua chave de API do Google:

    GOOGLE_API_KEY=your_api_key_here

  4. Compile o projeto:

    npm run build

Configuração e Integração do Servidor MCP

O resumidor de código inclui um servidor Model Context Protocol (MCP) que permite que ferramentas de LLM como Claude Desktop, Cursor AI e Cline acessem resumos de código e conteúdo de arquivos.

Iniciando o Servidor MCP

# Start the MCP server
npm start -- server

Por padrão, o servidor executa na porta 24312. Você pode alterar isso na sua configuração:

# Set custom MCP server port
npm start -- config set --port 8080

Conectando com o Claude Desktop

  1. Inicie o servidor MCP do code-summarizer
  2. Abra o Claude Desktop e clique no menu Claude, depois em "Settings..."
  3. Navegue até a seção "Developer"
  4. Crie um arquivo em ~/.claude/claude_desktop_config.json (macOS/Linux) ou %USERPROFILE%\.claude\claude_desktop_config.json (Windows) com este conteúdo:
{
  "code-summarizer": {
    "command": "npx",
    "args": ["-y", "your-path-to-code-summarizer/bin/code-summarizer.js", "server"],
    "env": {
      "GOOGLE_API_KEY": "your_api_key_here"
    }
  }
}
  1. Reinicie o Claude Desktop
  2. Após reiniciar, você pode pedir ao Claude para acessar seu código, por exemplo, "Resuma os arquivos do meu projeto"

Exemplos de prompts para o Claude Desktop:

  • "Você pode resumir todos os arquivos JavaScript do meu projeto?"
  • "Por favor, me dê uma visão geral de alto nível do meu código."
  • "Explique o que o arquivo 'src/config/config.ts' faz."
  • "Encontre todas as funções relacionadas à autenticação no meu código."

Conectando com o Cursor AI

  1. Inicie o servidor MCP do code-summarizer
  2. Crie um arquivo .cursor/mcp.json no diretório do seu projeto:
{
  "mcpServers": {
    "code-summarizer": {
      "transport": "sse",
      "url": "http://localhost:24312/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}
  1. Reinicie o Cursor ou recarregue seu projeto
  2. Pergunte ao Cursor sobre seu código, por exemplo, "Você pode resumir meu código?"

Exemplos de prompts para o Cursor:

  • "Resuma a estrutura deste código para mim."
  • "Quais são os principais componentes deste projeto?"
  • "Dê-me uma explicação detalhada da implementação do servidor MCP."
  • "Ajude-me a entender como funciona o mecanismo de repetição."

Conectando com o Cline

  1. Inicie o servidor MCP do code-summarizer
  2. No Cline, você pode adicionar o servidor MCP com um comando:
/mcp add code-summarizer http://localhost:24312/sse
  1. Em seguida, autentique-se com sua chave de API:
/mcp config code-summarizer headers.x-api-key your_api_key_here
  1. Você pode então pedir ao Cline para usar o code-summarizer, por exemplo, "Por favor, resuma meus arquivos de código"

Exemplos de prompts para o Cline:

  • "O que cada arquivo do meu projeto faz?"
  • "Crie um resumo de todos os arquivos TypeScript."
  • "Explique o fluxo de autenticação neste código."
  • "Quais são as principais funções no diretório 'summarizer'?"

O Que Você Pode Fazer com a Integração MCP

Usando a integração MCP, você pode:

  1. Obter resumos de arquivos: Solicitar explicações concisas sobre o que arquivos específicos fazem
  2. Explorar diretórios: Navegar pela estrutura do seu código
  3. Processamento em lote: Resumir vários arquivos de uma vez
  4. Consultas direcionadas: Encontrar padrões ou funcionalidades específicas no seu código
  5. Personalizar resumos: Controlar o nível de detalhe e o comprimento do resumo
  6. Atualizar configurações: Alterar opções de configuração pela interface MCP

O servidor MCP expõe seu código às ferramentas de LLM de forma estruturada, permitindo que elas leiam, naveguem e resumam seu código sem precisar colar trechos de código manualmente.

Detalhes da Integração do Servidor MCP

Recursos MCP

  • code://file/* - Acessar arquivos de código individuais
  • code://directory/* - Listar arquivos de código em um diretório
  • summary://file/* - Obter resumo de um arquivo específico
  • summary://batch/* - Obter resumos de vários arquivos

Ferramentas MCP

  • summarize_file - Resumir um único arquivo com opções
  • summarize_directory - Resumir um diretório com opções
  • set_config - Atualizar opções de configuração

Prompts MCP

  • code_summary - Modelo de prompt para resumir código
  • directory_summary - Modelo de prompt para resumir diretórios inteiros

Solução de Problemas

Problemas Comuns de Conexão MCP

  1. Conexão Recusada

    • Certifique-se de que o servidor MCP está em execução (npm start -- server)
    • Verifique se a porta está correta na sua configuração
    • Verifique se há problemas de firewall bloqueando a conexão

  2. Erros de Autenticação

    • Verifique se você adicionou a chave de API correta nos cabeçalhos (x-api-key)
    • Confirme se sua chave de API é válida e está formatada corretamente
    • Certifique-se de que as variáveis de ambiente estão definidas corretamente

  3. Erros de Transporte

    • Garanta que o tipo de transporte correto esteja especificado (SSE)
    • Verifique se a URL inclui o endpoint correto (/sse)
    • Verifique a conectividade de rede entre o cliente e o servidor

  4. Problemas de Permissão

    • Garanta que o servidor MCP tenha acesso de leitura ao seu código
    • Verifique as permissões de arquivo se o resumo falhar para arquivos específicos

  5. Claude Desktop Não Encontra o Servidor MCP

    • Verifique se o caminho em claude_desktop_config.json está correto
    • Certifique-se de que o comando e os argumentos apontam para o local certo
    • Verifique os logs do Claude Desktop para erros de configuração

  6. Limitação de Taxa

    • Se você vir erros de "Muitas solicitações", aguarde e tente novamente mais tarde
    • Considere ajustar as configurações de limitação de taxa no código do servidor

Para outros problemas, verifique os logs do servidor ou abra uma issue no repositório do GitHub.

Uso

Interface de Linha de Comando

# Default command (summarize)
npm start -- summarize [directory] [output-file] [options]

# Summarize code in the current directory (output to summaries.txt)
npm start -- summarize

# Summarize code with specific detail level and max length
npm start -- summarize --detail high --max-length 1000

# Show help
npm start -- --help

Gerenciamento de Configuração

# Set your API key
npm start -- config set --api-key "your-api-key" 

# Set default detail level and max length
npm start -- config set --detail-level high --max-length 1000

# Set MCP server port (default: 24312)
npm start -- config set --port 8080

# Show current configuration
npm start -- config show

# Reset configuration to defaults
npm start -- config reset

Autenticação de API

Ao conectar ao servidor MCP, você precisa incluir sua chave de API nos cabeçalhos da solicitação:

x-api-key: your_api_key_here

Todos os endpoints (exceto /health) exigem autenticação.

Opções

  • --detail, -d: Define o nível de detalhe dos resumos. As opções são 'low', 'medium' ou 'high'. O padrão é 'medium'.
  • --max-length, -l: Comprimento máximo de cada resumo em caracteres. O padrão é 500.

Recursos de Segurança

Gerenciamento de Chaves de API

  • As chaves de API são armazenadas com segurança e priorizam variáveis de ambiente em vez de arquivos de configuração
  • As chaves são validadas quanto ao formato correto antes do uso
  • As chaves de API nunca são expostas em logs ou mensagens de erro
  • O arquivo de configuração não armazena chaves de API quando elas são fornecidas via variáveis de ambiente

Autenticação

  • Todos os endpoints do servidor MCP (exceto verificação de integridade) exigem autenticação via chave de API
  • A autenticação usa o cabeçalho x-api-key para transmissão segura
  • Tentativas de autenticação com falha são registradas para monitoramento de segurança

Limitação de Taxa

  • A limitação de taxa integrada evita abuso do serviço
  • Padrão: 60 solicitações por minuto por endereço IP
  • Configurável através das configurações do servidor

Tratamento de Erros

  • Sistema de erros estruturado com categorização
  • Informações confidenciais nunca são expostas em mensagens de erro
  • Códigos de erro adequados são retornados para diferentes cenários de falha

Resiliência de Chamadas de LLM

  • Repetição automática com backoff exponencial para falhas transitórias
  • Configurações de repetição configuráveis, incluindo máximo de tentativas, atrasos e fator de backoff
  • Jitter adicionado ao tempo de repetição para evitar problemas de rebanho em massa
  • Rastreamento de ID de solicitação para rastrear problemas em todo o sistema

Tipos de Arquivo Suportados

  • TypeScript (.ts, .tsx)
  • JavaScript (.js, .jsx)
  • Python (.py)
  • Java (.java)
  • C++ (.cpp)
  • C (.c)
  • Go (.go)
  • Ruby (.rb)
  • PHP (.php)
  • C# (.cs)
  • Swift (.swift)
  • Rust (.rs)
  • Kotlin (.kt)
  • Scala (.scala)
  • Vue (.vue)
  • HTML (.html)
  • CSS (.css, .scss, .less)

Como Funciona

  1. A ferramenta examina o diretório especificado recursivamente, respeitando as regras de .gitignore.
  2. Ela filtra os arquivos com base nas extensões suportadas.
  3. Para cada arquivo suportado, ela lê o conteúdo e determina a linguagem de programação.
  4. Ela envia o código ao Gemini Flash 2.0 com um prompt para resumir, incluindo nível de detalhe e restrições de comprimento.
  5. Os resumos são coletados e gravados no arquivo de saída especificado.

Formato de Saída

O arquivo de saída terá o seguinte formato:

relative/path/to/file
Summary text here

relative/path/to/next/file
Next summary text here

Estrutura do Projeto

  • index.ts: Implementação principal da CLI
  • src/: Diretório do código-fonte
    • summarizer/: Funcionalidade principal de resumo
    • mcp/: Implementação do servidor MCP
    • config/: Gerenciamento de configuração
  • bin/: Ponto de entrada da CLI
  • config.json: Arquivo de configuração padrão
  • tsconfig.json: Configuração do TypeScript
  • package.json: Dependências e scripts do projeto
  • .env.example: Modelo para configurar variáveis de ambiente
  • .gitignore: Arquivos e diretórios a ignorar no Git
  • __tests__: Testes unitários e de integração
  • __mocks__/mock-codebase: Código de exemplo para testes

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser usadas para configurar o aplicativo:

VariávelDescriçãoPadrão
GOOGLE_API_KEYSua chave de API do Google GeminiNenhum (obrigatório)
PORTPorta do servidor MCP24312
ALLOWED_ORIGINSLista separada por vírgulas de origens CORS permitidashttp://localhost:3000
LOG_LEVELNível de registro (error, warn, info, debug)info

Consulte .env.example para um modelo.

Desenvolvimento

Executando Testes

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Test MCP server setup
npm run test:setup

Melhorias Futuras

  • Suporte a mais tipos de arquivo
  • Suporte a provedores alternativos de LLM
  • Integração com um aplicativo Electron para uma interface gráfica
  • Capacidades aprimoradas do servidor MCP
  • Rastreamento avançado de uso de tokens
  • Observabilidade baseada em OpenTelemetry
  • Capacidades aprimoradas de registro de auditoria
  • Integração de varredura de segredos