Codex Code Review MCP

Servidor MCP local e interface web para revisar Merge Requests do GitLab e Pull Requests do GitHub. O projeto concentra a coleta de contexto, a preparação de comentários, respostas e correções, e só publica uma alteração remota após uma prévia e confirmação explícita da pessoa usuária.

O que o projeto faz

• Conecta-se a instâncias GitLab (SaaS ou self-managed) e GitHub (incluindo GitHub Enterprise Server).

• Restringe o acesso a conexões e repositórios previamente autorizados em uma allowlist.

• Carrega PRs/MRs abertas, branches, diff, arquivos alterados e discussões.

• Detecta a stack alterada e exige a skill de revisão correspondente: Laravel/PHP, Node.js ou React.

• Prepara comentários de review, comentários gerais, respostas a threads e commits de correção.

• Oferece a mesma operação por MCP (stdin/stdout JSON-RPC) e por uma UI React servida apenas em localhost.

Não é um bot de revisão autônomo: não executa polling, webhooks ou publicação automática.

Related MCP server: Code Review MCP Server

Salvaguardas de publicação

O fluxo de escrita foi desenhado para ser deliberado e verificável:

1. A conexão precisa existir no arquivo de configuração e o repositório precisa constar na sua allowlist.

2. Uma prévia cria um actionId temporário, válido por 30 minutos.

3. A publicação requer confirmedByUser: true; o actionId é consumido uma única vez.

4. Antes de publicar, o servidor consulta novamente a PR/MR e bloqueia a ação se o SHA da branch de origem mudou.

5. Respostas e correções só são aceitas para threads ainda abertas. O estado é revalidado imediatamente antes do envio.

6. Correções e respostas a observações são limitadas a PRs/MRs cujo autor é o usuário autenticado pelo token.

O servidor não realiza merge, aprovação formal, encerramento de discussão ou exclusão automática.

Arquitetura

As ações pendentes existem somente em memória. Reiniciar o processo invalida prévias que ainda não foram publicadas.

Compatibilidade e requisitos

• Node.js 20 ou superior.

• Um token GitLab ou GitHub acessível por variável de ambiente.

• Acesso de rede à instância configurada.

• Para uma revisão feita pelo Codex, o repositório deve estar no workspace; se não estiver, a instrução MCP determina cloná-lo antes da análise.

Instale as dependências:

npm install

Configuração de conexões

Copie connections.example.json para um dos locais abaixo:

• padrão: ~/.config/codex-code-review-mcp/connections.json;

• personalizado: defina a variável CODE_REVIEW_CONNECTIONS_FILE com o caminho absoluto do arquivo.

O arquivo contém URLs, identificadores, allowlists e o nome da variável de ambiente do token. Nunca inclua tokens nele.

{
  "connections": [
    {
      "id": "gitlab-corporativo",
      "provider": "gitlab",
      "baseUrl": "https://gitlab.example.com",
      "tokenEnv": "CODE_REVIEW_GITLAB_CORPORATIVO_TOKEN",
      "allowedRepositories": ["grupo/api-exemplo"]
    },
    {
      "id": "github",
      "provider": "github",
      "baseUrl": "https://api.github.com",
      "tokenEnv": "CODE_REVIEW_GITHUB_TOKEN",
      "allowedRepositories": ["organization/*"]
    }
  ]
}

allowedRepositories aceita o nome exato do repositório (owner/repository ou grupo/projeto). Apenas no GitHub, owner/* autoriza os repositórios diretamente pertencentes a esse owner; outros curingas são rejeitados ao iniciar.

Para GitLab self-managed, informe a URL raiz da instância; o cliente acrescenta /api/v4 quando necessário. Para GitHub Enterprise Server, informe normalmente a URL da API, como https://github.empresa.com/api/v3.

Exemplos de variáveis de ambiente:

$env:CODE_REVIEW_GITLAB_CORPORATIVO_TOKEN = "glpat-..."
$env:CODE_REVIEW_GITHUB_TOKEN = "github_pat_..."

export CODE_REVIEW_GITLAB_CORPORATIVO_TOKEN='glpat-...'
export CODE_REVIEW_GITHUB_TOKEN='github_pat_...'

Reinicie o processo do MCP após alterar variáveis ou a configuração. Em macOS, aplicações abertas pelo Finder podem não herdar variáveis exportadas pelo shell.

Permissões recomendadas

GitLab

O cliente usa o cabeçalho PRIVATE-TOKEN e a API REST. Prefira Project Access Token para um projeto ou Group Access Token para um conjunto limitado de projetos.

Para cobrir todas as operações com um único token, use api e papel Developer. write_repository não é necessário, pois os commits são criados pela API REST, não por Git-over-HTTP.

GitHub

O token deve poder ler repositórios, Pull Requests, arquivos/diffs e comentários. Para publicar, também deve ter permissão de escrever comentários de issue/review; para correções, precisa poder atualizar a branch de origem. Em GitHub Enterprise Server, confirme que a API GraphQL está disponível: ela é consultada para verificar se uma review thread foi resolvida.

Use tokens de menor privilégio, com validade curta e rotação regular.

Registro como MCP no Codex

No macOS/Linux, ajuste o caminho do projeto e execute:

codex mcp add code-review \
  --env CODE_REVIEW_GITLAB_CORPORATIVO_TOKEN="$CODE_REVIEW_GITLAB_CORPORATIVO_TOKEN" \
  --env CODE_REVIEW_GITHUB_TOKEN="$CODE_REVIEW_GITHUB_TOKEN" \
  -- node /caminho/para/codex-code-review-mcp/src/server.mjs

No Windows PowerShell:

codex mcp add code-review `
  --env CODE_REVIEW_GITLAB_CORPORATIVO_TOKEN="$env:CODE_REVIEW_GITLAB_CORPORATIVO_TOKEN" `
  --env CODE_REVIEW_GITHUB_TOKEN="$env:CODE_REVIEW_GITHUB_TOKEN" `
  -- node C:\caminho\para\codex-code-review-mcp\src\server.mjs

Inclua um --env para cada tokenEnv existente no arquivo de conexões. Abra uma nova sessão e use /mcp para confirmar que o servidor está disponível.

Ferramentas MCP

Uma revisão é bloqueada quando a alteração não corresponde a uma stack suportada. A detecção é feita pelos arquivos modificados:

• Laravel/PHP: arquivos .php, artisan, composer.* ou diretórios Laravel usuais;

• React: .jsx, .tsx ou caminhos com @presentation;

• Node.js: .js, .ts, .mjs, .cjs ou caminhos com @server/@worker.

Comentários de achados no diff precisam ser inline e apontar para uma linha efetivamente modificada, do lado RIGHT (novo) ou LEFT (anterior). Achados fora do diff devem ser comentários gerais.

Fluxo de uso

1. Carregue o contexto, por exemplo: “Revise o PR 42 em acme/web, na conexão github”.

2. O Codex identifica a skill exigida, compara a branch de origem com a de destino e monta uma prévia de comentários.

3. Revise a prévia e confirme explicitamente nesta conversa.

4. O Codex chama code_review_execute com o actionId e confirmedByUser: true.

Para uma observação existente, primeiro solicite a avaliação técnica. Antes de preparar uma resposta ou correção, o Codex deve apresentar separadamente um plano de correção e um plano de resposta. Quando a observação for válida, a correção é publicada antes da resposta, que recebe o SHA efetivo do commit. Quando for inválida, apenas a justificativa técnica é publicada na mesma thread.

Interface web local

Com os tokens e o arquivo de conexões já configurados:

npm run start:web

O comando inicia conjuntamente:

• API HTTP: http://localhost:9898;

• interface React: http://localhost:5599.

A API escuta apenas em 127.0.0.1 e aceita CORS somente das origens locais da interface. A UI nunca recebe o token; ela chama a API local, que preserva allowlist, prévia, expiração e confirmação. Use npm run start:web:client quando a API já estiver ativa e npm run build:web para gerar os arquivos estáticos em dist/.

Endpoints locais disponíveis:

Desenvolvimento e validação

Os testes cobrem expiração e confirmação de ações, allowlist, configuração, clientes GitHub/GitLab, detecção de stack, validação de comentários inline, proteção contra atualização remota, estado de threads e API HTTP.

Limitações atuais

• As prévias pendentes não sobrevivem ao reinício do processo.

• A interface permite preparar uma entrada por vez; a API e o MCP aceitam lotes de comentários.

• A listagem de arquivos da PR/MR usa páginas de até 100 itens conforme a API remota; para mudanças maiores, valide se a instância fornece todos os arquivos necessários à análise.

• Somente Laravel/PHP, Node.js e React são elegíveis para o fluxo de revisão automatizado pelo MCP.