codehealth-mcp

Code Health MCP (CodeScene)

Feedback de manutenibilidade estrutural para codificação assistida por IA. Complementa habilidades de estilo/lint (coding-standards, plankton-code-quality) com pontuações de saúde em nível de design e portões de regressão.

Upstream: codescene-oss/codescene-mcp-server Pacote: @codescene/codehealth-mcp (stdio via npx)

Segurança e limites

Opt-in (ECC): O bloco codescene em mcp-configs/mcp-servers.json é apenas um modelo. A instalação do plugin ECC não habilita automaticamente servidores MCP incluídos. Copie a entrada para sua configuração apenas se desejar usá-la. Você pode excluí-la durante a instalação/sincronização do ECC com ECC_DISABLED_MCPS=codescene,....

Credenciais: Nenhum token incluído. Defina CS_ACCESS_TOKEN você mesmo (consulte getting-a-personal-access-token.md no repositório upstream). Nunca commite tokens no repositório.

O que as ferramentas leem: Quando invocadas, as ferramentas analisam arquivos e estado git no repositório local que você apontar (caminhos que você passar, mais contexto de branch para analyze_change_set). Elas não são executadas sozinhas. Para modo standalone, siga a documentação de privacidade upstream: codescene-mcp-server README e políticas do CodeScene. Não use esta habilidade para segredos, credenciais ou caminhos que você não deseja analisar.

Se o MCP estiver indisponível (offline, token inválido, falha do servidor): Não invente pontuações de Code Health. Informe ao usuário que a verificação foi ignorada. Continue apenas com aprovação explícita do usuário. Prefira lint/testes/loop de verificação para bloqueio quando o MCP estiver inativo. Reative as verificações quando o servidor conectar.

Quando usar

• O usuário pede para revisar qualidade de código, refatorar um arquivo, ou verificar se alterações de IA degradaram a manutenibilidade
• Antes de editar um hotspot, módulo legado, ou arquivo desconhecido
• Antes de commit ou pull request quando você precisa de uma salvaguarda de manutenibilidade
• Após um grande diff gerado por agente — verifique se o Code Health não regrediu
• Combine com verification-loop, tdd-workflow ou /quality-gate como uma verificação estrutural (não substitui testes/lint)

Quando ativar

Mesmos gatilhos de Quando usar acima — este título é o que o ECC usa para ativação automática da habilidade.

Como funciona

1. Conecte o servidor MCP

Copie a entrada codescene de mcp-configs/mcp-servers.json para sua configuração MCP.

Claude Code (~/.claude.json → mcpServers):

"codescene": {
  "command": "npx",
  "args": ["-y", "@codescene/codehealth-mcp"],
  "env": {
    "CS_ACCESS_TOKEN": "SEU_CS_ACCESS_TOKEN_AQUI"
  }
}

Escopo de projeto: mescle o mesmo bloco em .mcp.json na raiz do repositório.

A configuração do token está documentada no repositório upstream (link acima). O modo standalone não requer uma conta paga da plataforma CodeScene para as quatro ferramentas listadas abaixo. Reinicie a sessão e confirme que o servidor codescene está conectado antes de confiar nas pontuações.

2. Chame apenas ferramentas standalone

Ferramenta	Quando usar
code_health_review	Análise estrutural completa antes de modificar um arquivo
code_health_score	Pontuação numérica rápida após cada alteração (verificação de delta)
pre_commit_code_health_safeguard	Bloqueie commits que introduzam regressões de Code Health
analyze_change_set	Verificação em nível de branch antes de abrir um PR

Não chame ferramentas exclusivas da plataforma (ex.: listas de hotspots de dívida técnica em todo o repositório). Não referencie delta_analysis — não disponível no modo standalone.

3. Interprete pontuações (1–10)

Faixa	Significado	Comportamento do agente
9.0–10.0	Verde — saudável	Mais seguro para estender; ainda prefira fatias verticais
4.0–8.9	Amarelo — dívida	Tome cuidado; sem refatorações de passagem
1.0–3.9	Vermelho — dívida severa	Apenas escopo estreito

4. Execute o loop de feedback

Antes de tocar em um arquivo

1. Execute code_health_review no caminho alvo.
2. Registre a pontuação base e os code smells listados.
3. Planeje a menor alteração que resolva a tarefa.

Escopo por pontuação: abaixo de 5 — apenas diff mínimo; 5–7 — sem refatorações amplas; acima de 7 — mais seguro refatorar, ainda verifique após cada edição.

Após cada alteração

1. Execute code_health_score no mesmo arquivo.
2. Compare com a pontuação base de code_health_review.
3. Se a pontuação regrediu, corrija antes de continuar. Nunca marque a tarefa como concluída enquanto a pontuação estiver menor do que quando você começou.

Antes de cada commit — execute pre_commit_code_health_safeguard no caminho do repositório.

Antes de um PR — execute analyze_change_set contra o branch base (ex.: main).

Exemplos

Exemplo: Melhoria de manutenibilidade Flask

No pallets/flask, um loop de agente usando apenas ferramentas standalone:

1. code_health_review em um módulo alvo (pontuação base 4.82)
2. Refatoração direcionada abordando os code smells listados
3. code_health_score após cada edição
4. pre_commit_code_health_safeguard antes do commit
5. analyze_change_set antes do PR

Resultado: Code Health 4.82 → 9.1 (token standalone gratuito apenas).

Exemplo: Bloco de execução em AGENTS.md

Cole no AGENTS.md ou CLAUDE.md do projeto:

## Code Health (CodeScene MCP)

Antes de modificar qualquer arquivo: execute `code_health_review`, anote a pontuação e problemas.

- Pontuação abaixo de 5: faixa problemática — escopo de alterações estreito.
- Pontuação 5–7: faixa de aviso — sem refatorações amplas.

Após cada alteração: execute `code_health_score` para verificar o delta.

- Se a pontuação regrediu: corrija antes de continuar; nunca declare concluído se a pontuação caiu.

Antes de cada commit: execute `pre_commit_code_health_safeguard`.

Antes do PR: execute `analyze_change_set`.

Exemplo: anti-padrões vs loop correto

# RUIM: Editar primeiro, verificar depois
[grande refatoração sem code_health_review]

# RUIM: Ignorar queda de pontuação
"Testes passam" → marcar tarefa como concluída enquanto Code Health diminuiu

# RUIM: Refatoração ampla em arquivo com pontuação vermelha (abaixo de 5)
Limpeza de passagem em todo o módulo

# BOM: revisar → pequena alteração → pontuação → salvaguarda de commit → analyze_change_set

Pareamento com ECC

Habilidade / fluxo ECC	Papel do Code Health MCP
coding-standards	Estilo/nomenclatura; Code Health = estrutura/complexidade
plankton-code-quality	Lint/format em tempo de escrita; Code Health = portão estrutural pré/pós edição
verification-loop / /quality-gate	Adicione verificação de regressão estrutural antes de "concluído"
security-review	Segurança vs manutenibilidade — use ambos quando relevante
tdd-workflow	Testes passarem ≠ design saudável — verifique pontuação após refatorações

Dica de contexto: ECC recomenda manter o número de MCPs baixo. Habilite codescene ao fazer edições substanciais; desabilite quando não for necessário.

Habilidades relacionadas

• coding-standards — convenções base
• plankton-code-quality — hooks de lint/format em tempo de escrita
• verification-loop — portão de build/teste/lint
• tdd-workflow — desenvolvimento orientado a testes
• security-review — checklist de segurança
• documentation-lookup — documentação de bibliotecas via Context7 (ortogonal)