Code Health MCP (CodeScene)
Retroalimentación de mantenibilidad estructural para codificación asistida por IA. Complementa habilidades de estilo/lint (coding-standards, plankton-code-quality) con puntuaciones de salud a nivel de diseño y controles de regresión.
Upstream: codescene-oss/codescene-mcp-server
Paquete: @codescene/codehealth-mcp (stdio vía npx)
Seguridad y límites
Opción explícita (ECC): El bloque codescene en mcp-configs/mcp-servers.json es solo una plantilla. Las instalaciones de plugins 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. Configura CS_ACCESS_TOKEN tú mismo (consulta getting-a-personal-access-token.md en el repositorio upstream). Nunca subas tokens al repositorio.
Lo que leen las herramientas: Cuando se invocan, las herramientas analizan archivos y el estado de git en el repositorio local al que apuntas (rutas que pasas, más contexto de rama para analyze_change_set). No se ejecutan solas. Para el modo independiente, sigue la documentación de privacidad upstream: README de codescene-mcp-server y políticas de CodeScene. No uses este skill para secretos, credenciales o rutas que no quieras 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 aprobación explícita del usuario. Prefiere lint/pruebas/bucle de verificación para el control cuando el MCP esté caído. Vuelve a habilitar las verificaciones cuando el servidor se conecte.
Cuándo Usar
- El usuario pide revisar la calidad del código, refactorizar un archivo, o comprobar si cambios de IA degradaron la mantenibilidad
- Antes de editar un hotspot, módulo legacy o archivo desconocido
- Antes de commit o pull request cuando necesitas una salvaguarda de mantenibilidad
- Después de un diff grande generado por agente: verifica que Code Health no haya empeorado
- Combínalo con
verification-loop,tdd-workflowo/quality-gatecomo verificación estructural (no reemplaza pruebas/lint)
Cuándo Activar
Mismos desencadenantes que en Cuándo Usar arriba: este encabezado es lo que usa ECC para la activación automática del skill.
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 upstream (enlace arriba). El modo independiente no requiere una cuenta paga 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 las 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 después de cada cambio (verificación de delta) |
pre_commit_code_health_safeguard | Bloquear commits que introducen 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 (por ejemplo, listas de hotspots de deuda técnica de todo el repositorio). No hagas referencia a delta_analysis: no está disponible en modo independiente.
3. Interpretar puntuaciones (1–10)
| Rango | Significado | Comportamiento del agente |
|---|---|---|
| 9.0–10.0 | Verde — saludable | Más seguro extender; aun así, prefiere cortes verticales |
| 4.0–8.9 | Amarillo — deuda | Actúa con cuidado; 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
- Ejecuta
code_health_reviewen la ruta objetivo. - Registra la puntuación base y los code smells listados.
- Planifica el cambio más pequeño que aborde la tarea.
Alcance según puntuación: menor de 5 — solo diff mínimo; 5–7 — sin refactors amplios; mayor de 7 — más seguro refactorizar, pero verifica después de cada edición.
Después de cada cambio
- Ejecuta
code_health_scoreen el mismo archivo. - Compara con la línea base de
code_health_review. - Si la puntuación empeoró, corrige antes de continuar. Nunca declares 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 (por ejemplo, main).
Ejemplos
Ejemplo: Mejora de mantenibilidad en Flask
En pallets/flask, un bucle de agente usando solo herramientas independientes:
code_health_reviewen un módulo objetivo (línea base 4.82)- Refactor dirigido abordando los code smells listados
code_health_scoredespués de cada ediciónpre_commit_code_health_safeguardantes del commitanalyze_change_setantes del PR
Resultado: Code Health 4.82 → 9.1 (solo token independiente gratuito).
Ejemplo: Bloque de enforce en AGENTS.md
Pega 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 menor de 5: rango problemático — limita el alcance de los cambios.
- 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 empeora: corrige antes de continuar; nunca declares terminado si la puntuación bajó.
Antes de cada commit: ejecuta `pre_commit_code_health_safeguard`.
Antes del PR: ejecuta `analyze_change_set`.
Ejemplo: Anti-patrones vs bucle correcto
# MAL: Editar primero, verificar después
[refactor grande sin code_health_review]
# MAL: Ignorar la caída de puntuación
"Las pruebas pasan" → marcar tarea como completada mientras Code Health disminuyó
# MAL: Refactor amplio en archivo con puntuación roja (menor de 5)
Limpieza por impulso en todo el módulo
# BIEN: revisar → cambio pequeño → puntuación → salvaguarda de commit → analyze_change_set
Integración con ECC
| Skill / flujo de ECC | Rol de Code Health MCP |
|---|---|
coding-standards | Estilo/nombrado; Code Health = estructura/complejidad |
plankton-code-quality | Lint/formato en tiempo de escritura; Code Health = control estructural pre/post edición |
verification-loop / /quality-gate | Agregar verificación de regresión estructural antes de "terminado" |
security-review | Seguridad vs mantenibilidad: usa ambos cuando sea relevante |
tdd-workflow | Pruebas pasan ≠ diseño saludable: verifica puntuación después de refactors |
Consejo de contexto: ECC recomienda mantener bajo el número de MCP. Habilita codescene cuando hagas ediciones sustanciales; deshabilítalo cuando no sea necesario.
Skills Relacionados
coding-standards— convenciones baseplankton-code-quality— hooks de lint/formato en tiempo de escrituraverification-loop— control de build/test/linttdd-workflow— desarrollo guiado por pruebassecurity-review— lista de verificación de seguridaddocumentation-lookup— documentación de librerías vía Context7 (ortogonal)