ndlovu-code-reviewer

Servidor MCP de Revisão de Código

Um assistente de revisão de código alimentado por Gemini-CLI (por enquanto), que executa como um servidor Model Context Protocol (MCP).

Por que este projeto existe

Revisões manuais de código consomem tempo e muitas vezes perdem a oportunidade de combinar análise estática com feedback contextual e amigável. Este projeto foi criado para experimentar ferramentas MCP que dão aos assistentes de IA acesso a um revisor específico:

• Automatiza o trabalho de coletar diffs e resultados de lint de alterações locais não commitadas.
• Transmite esse contexto para o Gemini CLI para que o modelo possa focar em insights acionáveis.
• Retorna uma revisão JSON estruturada que se encaixa naturalmente em clientes compatíveis com MCP.

O que ele faz

• Conecta-se a clientes MCP via stdio usando o @modelcontextprotocol/sdk oficial.
• Executa um fluxo de trabalho de revisão "híbrido" que coleta a saída do git diff e descobertas do linter.
• Alterna entre ESLint, JSHint e TypeScript para maximizar a cobertura entre projetos.
• Invoca com segurança o Gemini CLI, lidando com prompts longos e timeouts.
• É distribuído como TypeScript com tipos baseados em Zod para respostas MCP previsíveis.

Requisitos

• Node.js 18 ou posterior (módulos ES e AbortSignals são usados em todo o projeto).
• npm (instalado com Node.js).
• Git (usado para coletar diffs locais).
• Google Gemini CLI (gemini) instalado e autenticado. Veja o guia de início rápido do Gemini para instruções de configuração.

Instalação

git clone https://github.com/<your-org>/ndlovu-code-reviewer.git
cd ndlovu-code-reviewer
npm install
npm run build

Se você planeja iterar no código-fonte TypeScript, pode pular o npm run build e contar com o script de desenvolvimento descrito abaixo.

Uso

Iniciar o servidor MCP

npm start

O servidor se comunica via stdio, então está pronto para ser registrado em qualquer cliente compatível com MCP (por exemplo, integrações de IDE ou sandboxes de assistente). Uma vez conectado, chame a ferramenta review-local-changes para acionar a análise híbrida e receber a revisão JSON.

Como chamar a ferramenta MCP

O servidor expõe uma única ferramenta chamada review-local-changes que realiza análise abrangente das suas alterações locais não commitadas.

Pré-requisitos:

• Você deve ter alterações não commitadas no seu repositório git
• Os arquivos alterados devem ser JavaScript, TypeScript ou Vue (.js, .ts, .tsx, .vue)
• O Gemini CLI deve estar instalado e autenticado

Usando a ferramenta:

Uma vez que seu cliente MCP esteja conectado ao servidor, você pode chamar a ferramenta review-local-changes. A ferramenta:

1. Detecta alterações automaticamente - Encontra todos os arquivos JS/TS/Vue modificados/adicionados usando git diff
2. Executa análise estática - Executa o melhor linter disponível (ESLint, JSHint ou compilador TypeScript)
3. Realiza revisão de IA - Envia o contexto combinado para o Gemini CLI para análise inteligente
4. Retorna resultados estruturados - Fornece uma resposta JSON com descobertas e recomendações

Como usar com Claude Code:

Para melhores resultados, seja explícito sobre o uso da funcionalidade de revisão de código. Embora solicitações em linguagem natural às vezes funcionem, a abordagem mais confiável é usar palavras-chave específicas:

Solicitações mais confiáveis (recomendadas):

• "Use a ferramenta de revisão de código para analisar minhas alterações"
• "Execute revisão de código nas minhas alterações locais"
• "Realize uma revisão de código abrangente das minhas alterações não commitadas"
• "Analise minhas alterações de código com análise estática"

Solicitações em linguagem natural (podem funcionar, mas menos confiáveis):

• "Por favor, revise minhas alterações locais"
• "Você pode analisar as alterações de código que fiz?"

Invocação explícita da ferramenta (mais confiável):

• "Use a ferramenta review-local-changes"
• "Chame a ferramenta review-local-changes para verificar minhas modificações"

A ferramenta foi aprimorada com melhores descrições para ajudar o Claude a reconhecer quando usá-la, mas ser específico sobre "revisão de código", "analisar alterações" ou mencionar o nome da ferramenta diretamente dará os resultados mais consistentes.

Exemplo de formato de saída:

{
  "summary": "Overview of changes made",
  "assessment": "Overall code quality evaluation",
  "findings": [
    {
      "filePath": "src/example.js",
      "lineNumber": 42,
      "severity": "warning",
      "category": "style",
      "comment": "Detailed explanation of the issue",
      "suggestion": "Specific recommendation for improvement"
    }
  ]
}

Nota: Se nenhum arquivo relevante foi alterado, a ferramenta retornará uma mensagem "Nenhum arquivo relevante alterado", o que é comportamento normal.

Desenvolvimento local

• npm run dev – Inicia o servidor com ts-node para iteração rápida.
• npm run build – Produz a saída JavaScript compilada em dist/.

A estrutura do projeto é intencionalmente pequena:

• src/ – Código-fonte TypeScript para o servidor MCP.
• dist/ – JavaScript compilado criado por npm run build.
• assets/ – Ativos estáticos, incluindo o logotipo usado acima.

Conectar a partir de clientes MCP

Antes de conectar o servidor a qualquer cliente, certifique-se de ter executado npm run build para que dist/index.js exista. Os comandos abaixo assumem que você executa o cliente a partir da raiz do repositório para que o servidor possa ler seu workspace git.

Claude Code (extensão VS Code)

1. No VS Code, abra a paleta de comandos (Cmd/Ctrl+Shift+P) e execute Claude: Edit Config File.

2. Localize a seção mcpServers (crie-a se necessário) e adicione uma entrada semelhante a:

   {
     "mcpServers": {
       "ndlovu-code-reviewer": {
         "command": "node",
         "args": ["/absolute/path/to/ndlovu-code-reviewer/dist/index.js"],
         "cwd": "/absolute/path/to/ndlovu-code-reviewer"
       }
     }
   }
   

3. Salve o arquivo e execute Claude: Restart Claude Code (ou recarregue o VS Code) para que o servidor apareça em Ferramentas.

4. Habilite a ferramenta para uma conversa; o Claude Code transmitirá os resultados do review-local-changes diretamente na barra lateral.

Gemini CLI

1. A partir da raiz do projeto, execute:

   gemini mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js
   

2. Verifique o registro com gemini mcp list.

3. Inicie gemini a partir do mesmo diretório do repositório e use a ferramenta review-local-changes (por exemplo, execute :tools no CLI e selecione-a). O CLI inicia o servidor e encaminha o stdout de volta como o JSON da revisão.

Roo Code

1. Abra o Roo Code e clique no ícone do servidor no topo do painel Roo.

2. Escolha Adicionar Servidor MCP → STDIO e preencha:

   • Nome: ndlovu-code-reviewer
   • Comando: node
   • Argumentos: /absolute/path/to/ndlovu-code-reviewer/dist/index.js
   • Diretório de Trabalho: /absolute/path/to/ndlovu-code-reviewer

3. Salve a configuração e habilite o servidor para seu workspace. O Roo o armazena no arquivo global mcp_settings.json ou no arquivo do projeto .roo/mcp.json.

4. Para compartilhar com colegas, faça commit de um .roo/mcp.json que contenha seu comando de inicialização preferido, por exemplo:

   {
     "mcpServers": {
       "ndlovu-code-reviewer": {
         "command": "npm",
         "args": ["run", "start"],
         "cwd": "."
       }
     }
   }
   

   O Roo resolve o diretório de trabalho relativo à raiz do projeto, então o script npm run start se baseia nos scripts de pacote do próprio repositório.

Codex CLI

1. Registre o servidor uma vez:

   codex mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js
   

2. Use codex mcp list para confirmar a entrada e, em seguida, inicie o Codex a partir da raiz do repositório. O CLI expõe review-local-changes como uma ferramenta que você pode chamar em execuções interativas.

Contribuindo

Contribuições são muito bem-vindas. Se você tiver ideias para novas ferramentas, melhores linters ou prompts aprimorados:

1. Abra uma issue ou discussão para alinharmos o escopo.
2. Faça um fork do repositório e crie um branch de funcionalidade.
3. Adicione ou atualize documentação/testes onde ajudar futuros contribuidores.
4. Envie um pull request descrevendo a mudança e como você a validou.

Se você não tiver certeza por onde começar, sinta-se à vontade para entrar em contato—há muito espaço para expandir as capacidades do revisor, adicionar exemplos de clientes e aprimorar os prompts.

Licença

Este projeto é licenciado sob a Licença ISC. Veja LICENSE (se presente) para detalhes.