codehealth-mcp

Code Health MCP (CodeScene)

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

Origem: 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. As instalações de plugins ECC não habilitam automaticamente servidores MCP empacotados. Copie a entrada para sua configuração apenas se desejar usá-la. Você pode excluí-la durante a instalação/sincronização ECC com ECC_DISABLED_MCPS=codescene,....

Credenciais: Nenhum token embutido. Defina CS_ACCESS_TOKEN você mesmo (veja getting-a-personal-access-token.md no repositório upstream). Nunca envie tokens para o repositório.

O que as ferramentas leem: Quando invocadas, as ferramentas analisam arquivos e o estado do git no repositório local que você apontar para elas (caminhos que você passar, mais o contexto do 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 skill para segredos, credenciais ou caminhos que você não deseja analisar.

Se o MCP estiver indisponível (offline, token inválido, falha no servidor): Não invente pontuações de Code Health. Informe ao usuário que a verificação foi pulada. 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 assim que o servidor conectar.

Quando usar

• O usuário pede para revisar qualidade de código, refatorar um arquivo, ou verificar se mudanças 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 escrito 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 cabeçalho é o que o ECC usa para ativação automática de skill.

Como funciona

1. Conectar 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. Use 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 mudança (verificação delta)
pre_commit_code_health_safeguard	Bloquear 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 faça referência a delta_analysis — não está disponível no standalone.

3. Interpretar 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 avulsas
1.0–3.9	Vermelho — dívida severa	Apenas escopo estreito

4. Executar 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 smells de código listados.
3. Planeje a menor mudança 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 mudança

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 no Flask

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

1. code_health_review em um módulo alvo (base 4.82)
2. Refatoração direcionada abordando os 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 imposição 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 — restrinja mudanças estritamente.
- Pontuação 5–7: faixa de aviso — sem refatorações amplas.

Após cada mudança: 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
[refatoração grande 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 avulsa em todo o módulo

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

Combinação com ECC

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

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

Skills relacionadas

• coding-standards — convenções base
• plankton-code-quality — hooks de lint/format na escrita
• verification-loop — barreira 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)