Saúde do Código 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.

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

Segurança e Limites

Opcional (ECC): O bloco codescene em mcp-configs/mcp-servers.json é apenas um modelo. Instalações de plugins ECC não ativam automaticamente os servidores MCP incluídos. Copie a entrada para sua configuração apenas se desejar. 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 (veja getting-a-personal-access-token.md no repositório anterior). 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 para o qual você as aponta (caminhos que você passa, mais o contexto do branch para analyze_change_set). Elas não rodam sozinhas. Para modo autônomo, siga as docs de privacidade anteriores: codescene-mcp-server README e Políticas da CodeScene. Não use esta habilidade para segredos, credenciais ou caminhos que você não queira que sejam analisados.

Se o MCP estiver indisponível (offline, token inválido, falha do servidor): Não invente pontuações de Saúde do Código. 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 portões quando o MCP estiver inativo. Reative as verificações assim que o servidor se conectar.

Quando Usar

• O usuário pede para revisar a qualidade do 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 do commit ou pull request quando você precisa de uma salvaguarda de manutenibilidade
• Após um grande diff escrito por agente — verifique se a Saúde do Código não regrediu
• Emparelhe com verification-loop, tdd-workflow ou /quality-gate como uma verificação estrutural (não um substituto para 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 a configuração MCP do seu harness.

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

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

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

A configuração do token é documentada no repositório anterior (link acima). O modo autônomo 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 autônomas

Não chame ferramentas exclusivas da plataforma (por exemplo, listas de hotspots de débito técnico em todo o repositório). Não referencie delta_analysis — não disponível no modo autônomo.

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

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 cheiros de código listados.
3. Planeje a menor mudança que atenda à tarefa.

Escopo por pontuação: abaixo de 5 — apenas diff mínimo; 5–7 — sem refatorações amplas; acima de 7 — mais seguro para 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 base registrada em code_health_review.

…