codehealth-mcp

Code Health MCP (CodeScene)

Retroalimentación estructural de mantenibilidad para codificación asistida por IA. Complementa las habilidades de estilo/lint (coding-standards, plankton-code-quality) con puntuaciones de salud a nivel de diseño y compuertas de regresión.

Origen: codescene-oss/codescene-mcp-server Paquete: @codescene/codehealth-mcp (stdio vía npx)

Seguridad y límites

Opt-in (ECC): El bloque codescene en mcp-configs/mcp-servers.json es solo una plantilla. Las instalaciones del plugin ECC no habilitan automáticamente los servidores MCP incluidos. Copia la entrada en tu configuración solo si la deseas. Puedes excluirla durante la instalación/sincronización de ECC con ECC_DISABLED_MCPS=codescene,....

Credenciales: No hay token incluido. Establece CS_ACCESS_TOKEN por tu cuenta (consulta getting-a-personal-access-token.md en el repositorio original). Nunca subas tokens al repositorio.

Lo que leen las herramientas: Al ser invocadas, las herramientas analizan archivos y el estado de git en el repositorio local al que les apuntas (rutas que pasas, más el contexto de la rama para analyze_change_set). No se ejecutan por sí solas. Para el modo independiente, sigue la documentación de privacidad del repositorio original: codescene-mcp-server README y políticas de CodeScene. No uses esta habilidad para secretos, credenciales o rutas que no desees analizar.

Si el MCP no está disponible (sin conexión, token incorrecto, caída del servidor): No inventes puntuaciones de Code Health. Informa al usuario que la verificación fue omitida. Continúa solo con la aprobación explícita del usuario. Prefiere lint/pruebas/bucle de verificación como compuerta cuando el MCP esté caído. Vuelve a habilitar las verificaciones una vez que el servidor se conecte.

Cuándo Usar

• El usuario pide revisar la calidad del código, refactorizar un archivo o verificar si los cambios de la IA degradaron la mantenibilidad
• Antes de editar un hotspot, módulo heredado o archivo desconocido
• Antes de un commit o pull request cuando necesitas una salvaguarda de mantenibilidad
• Después de un diff grande generado por un agente — verifica que Code Health no haya retrocedido
• Combínalo con verification-loop, tdd-workflow o /quality-gate como verificación estructural (no reemplaza pruebas/lint)

Cuándo Activar

Mismos desencadenantes que en Cuándo Usar arriba — este encabezado es lo que ECC usa para la activación automática de la habilidad.

Cómo Funciona

1. Conectar el servidor MCP

Copia la entrada codescene de mcp-configs/mcp-servers.json en la configuración MCP de tu entorno.

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

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

Ámbito de proyecto: fusiona el mismo bloque en .mcp.json en la raíz del repositorio.

La configuración del token está documentada en el repositorio original (enlace arriba). El modo independiente no requiere una cuenta de pago de la plataforma CodeScene para las cuatro herramientas listadas abajo. Reinicia la sesión y confirma que el servidor codescene esté conectado antes de confiar en las puntuaciones.

2. Usar solo herramientas independientes

Herramienta	Cuándo usarla
code_health_review	Análisis estructural completo antes de modificar un archivo
code_health_score	Puntuación numérica rápida tras cada cambio (verificación delta)
pre_commit_code_health_safeguard	Bloquear commits que introduzcan regresiones en Code Health
analyze_change_set	Verificación a nivel de rama antes de abrir un PR

No llames a herramientas solo de plataforma (ej. listas de hotspots de deuda técnica a nivel de repositorio). No hagas referencia a delta_analysis — no disponible en modo independiente.

3. Interpretar puntuaciones (1–10)

Rango	Significado	Comportamiento del agente
9.0–10.0	Verde — saludable	Más seguro para extender; sigue prefiriendo slices verticales
4.0–8.9	Amarillo — deuda	Sé cauteloso; sin refactors por impulso
1.0–3.9	Rojo — deuda severa	Solo alcance limitado

4. Ejecutar el bucle de retroalimentación

Antes de tocar un archivo

1. Ejecuta code_health_review en la ruta objetivo.
2. Registra la puntuación base y los code smells listados.
3. Planifica el cambio más pequeño que aborde la tarea.

Alcance según puntuación: por debajo de 5 — solo diff mínimo; 5–7 — sin refactors amplios; por encima de 7 — más seguro refactorizar, sigue verificando tras cada edición.

Después de cada cambio

1. Ejecuta code_health_score en el mismo archivo.
2. Compara con la puntuación base de code_health_review.
3. Si la puntuación retrocede, corrige antes de continuar. Nunca marques la tarea como completada mientras la puntuación sea menor que al inicio.

Antes de cada commit — ejecuta pre_commit_code_health_safeguard en la ruta del repositorio.

Antes de un PR — ejecuta analyze_change_set contra la rama base (ej. main).

Ejemplos

Ejemplo: Mejora de mantenibilidad en Flask

En pallets/flask, un bucle de agente usando solo herramientas independientes:

1. code_health_review en un módulo objetivo (base 4.82)
2. Refactorización dirigida abordando los code smells listados
3. code_health_score tras cada edición
4. pre_commit_code_health_safeguard antes del commit
5. analyze_change_set antes del PR

Resultado: Code Health 4.82 → 9.1 (solo token independiente gratuito).

Ejemplo: Bloque de cumplimiento para AGENTS.md

Pégalo en el AGENTS.md o CLAUDE.md del proyecto:

## Code Health (CodeScene MCP)

Antes de modificar cualquier archivo: ejecuta `code_health_review`, anota la puntuación y los problemas.

- Puntuación por debajo de 5: rango problemático — limita los cambios a un alcance reducido.
- Puntuación 5–7: rango de advertencia — sin refactors amplios.

Después de cada cambio: ejecuta `code_health_score` para verificar el delta.

- Si la puntuación retrocede: corrige antes de continuar; nunca declares completada la tarea si la puntuación bajó.

Antes de cada commit: ejecuta `pre_commit_code_health_safeguard`.

Antes del PR: ejecuta `analyze_change_set`.

Ejemplo: Antipatrones vs bucle correcto

# MALO: Editar primero, verificar después
[refactor grande sin code_health_review]

# MALO: Ignorar la caída de puntuación
"Las pruebas pasan" → marcar tarea como completada mientras Code Health disminuyó

# MALO: Refactor amplio en archivo con puntuación roja (por debajo de 5)
Limpieza transversal en todo el módulo

# BUENO: revisar → cambio pequeño → puntuación → salvaguarda commit → analyze_change_set

Combinación con ECC

Habilidad/flujo ECC	Rol de Code Health MCP
coding-standards	Estilo/nombres; Code Health = estructura/complejidad
plankton-code-quality	Lint/formato en tiempo de escritura; Code Health = compuerta estructural pre/post edición
verification-loop / /quality-gate	Añadir verificación de regresión estructural antes de "completado"
security-review	Seguridad vs mantenibilidad — usa ambas cuando sea relevante
tdd-workflow	Pruebas pasan ≠ diseño saludable — verifica puntuación tras refactors

Consejo de contexto: ECC recomienda mantener un número bajo de MCP. Habilita codescene cuando realices ediciones sustanciales; desactívalo cuando no sea necesario.

Habilidades Relacionadas

• coding-standards — convenciones base
• plankton-code-quality — hooks de lint/formato en tiempo de escritura
• verification-loop — compuerta de compilación/pruebas/lint
• tdd-workflow — desarrollo guiado por pruebas
• security-review — lista de verificación de seguridad
• documentation-lookup — documentación de librerías vía Context7 (ortogonal)