Codex Code Review MCP

Servidor MCP local para revisar manualmente Merge Requests do GitLab e Pull Requests do GitHub, sempre com confirmação explícita antes de criar comentários, respostas ou commits.

Segurança e limites

• Não executa webhook, polling ou tarefas automáticas.

• Não faz merge, aprovação formal, exclusão ou resolve discussões automaticamente.

• Só permite os projetos e repositórios definidos na allowlist da conexão.

• A allowlist aceita repositórios exatos (owner/repository) e, somente para GitHub, todos os repositórios diretos de um owner (owner/*).

• Não publica sem uma prévia aprovada nesta conversa e um actionId ainda válido.

• Não responde nem prepara correções para threads já resolvidas; o estado é revalidado imediatamente antes da publicação.

• Para cada thread não resolvida, o Codex avalia tecnicamente a observação. Quando válida, prepara a correção, cria o commit na branch de origem e responde à mesma thread com o SHA do commit; quando inválida, responde à mesma thread com justificativa técnica. Todas as escritas permanecem sujeitas à confirmação explícita.

• Para review, o Codex deve aplicar code-review-nodejs ou code-review-reactjs. MRs/PRs sem stack suportada são bloqueados.

Related MCP server: GitLab Code Review MCP

Configuração

Crie ~/.config/codex-code-review-mcp/connections.json a partir de connections.example.json. O arquivo contém apenas URLs, allowlists e os nomes das variáveis de ambiente; não coloque tokens nele.

Use owner/repository para autorizar apenas um repositório. Em conexões GitHub, owner/* autoriza qualquer repositório diretamente pertencente ao owner; outros formatos com * são rejeitados na inicialização.

Exemplo de variáveis globais no macOS:

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

Reinicie o Codex após alterar as variáveis ou o connections.json. Aplicações abertas pelo Finder podem não herdar variáveis exportadas no shell; nesse caso, defina-as no ambiente que inicia o Codex e confirme com code_review_list_connections antes de usar o servidor.

Para GitHub Enterprise Server, use a URL da API da instância, normalmente https://github.empresa.com/api/v3. Para GitLab self-managed, informe a URL raiz da instância; o servidor usa /api/v4 automaticamente.

Permissões no GitLab

O servidor autentica na API REST do GitLab pelo cabeçalho PRIVATE-TOKEN e chama os endpoints de Merge Request, alterações, discussões, usuário autenticado e criação de commits. Prefira um Project Access Token (para um único projeto) ou um Group Access Token (para vários projetos da mesma área), limitado aos repositórios informados em allowedRepositories.

Para usar todas as tools com um único token, conceda somente o escopo api e o papel Developer no projeto. Não é necessário habilitar write_repository: esta integração cria commits pela API REST, e esse escopo é exclusivo para Git-over-HTTP. Também não são necessários sudo, admin_mode, permissões de merge, de aprovação formal, de exclusão ou de gerenciamento do projeto.

Como as prévias de resposta e correção só são permitidas para MRs cuja autoria coincide com o usuário autenticado, um Project/Group Access Token deve ser usado apenas se o respectivo bot for o autor do MR. Para revisar e comentar MRs de outras pessoas, use um token de um usuário ou bot com acesso ao projeto; correções continuam restritas aos MRs de sua própria autoria.

As permissões efetivas também dependem das regras do projeto, como visibilidade, restrições de branch protegida e CODEOWNERS. Use um token com validade curta, rotacione-o e mantenha-o apenas na variável de ambiente indicada pela conexão.

Registro no Codex

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 /Users/seu-usuario/projetos/codex-code-review-mcp/src/server.mjs

No Windows, execute o equivalente no PowerShell, ajustando o caminho do projeto:

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:\Users\seu-usuario\projetos\codex-code-review-mcp\src\server.mjs

Inclua um --env para cada variável tokenEnv configurada no seu connections.json.

Abra uma nova sessão e use /mcp para verificar o servidor.

Uso previsto

1. Peça ao Codex para carregar o contexto, por exemplo: “Revise o PR 42 em acme/web, conexão github”.

2. O Codex identifica a skill de review exigida, analisa o diff e apresenta uma prévia dos comentários.

3. Confirme explicitamente o lote exibido.

4. O Codex executa a ação pendente com confirmedByUser: true.

As prévias de respostas e correções são exibidas em Markdown no prompt, incluindo os textos a enviar, mensagem de commit e conteúdo dos arquivos modificados. Revise esse conteúdo antes de confirmar.

Para uma observação em thread não resolvida, peça para avaliá-la. Se ela for válida, o Codex prepara o diff, executa validações, revisa novamente e mostra o commit e a resposta antes de enviá-los. Após a confirmação, o MCP cria e envia o commit primeiro e responde à mesma thread com o SHA efetivamente criado. Se não for válida, mostra a justificativa técnica antes de publicá-la.

Desenvolvimento

Requer Node.js 20 ou superior.

npm test