codehealth-mcp

Code Health MCP (CodeScene)

Retour sur la maintenabilité structurelle pour le codage assisté par IA. Complète les compétences de style et de lint (coding-standards, plankton-code-quality) avec des scores de santé au niveau de la conception et des vérifications de régression.

Source : codescene-oss/codescene-mcp-server Package : @codescene/codehealth-mcp (stdio via npx)

Sécurité et limites

Adhésion volontaire (ECC) : Le bloc codescene dans mcp-configs/mcp-servers.json n'est qu'un modèle. Les installations de plugins ECC n'activent pas automatiquement les serveurs MCP inclus. Copiez l'entrée dans votre configuration uniquement si vous le souhaitez. Vous pouvez l'exclure lors de l'installation/synchronisation ECC avec ECC_DISABLED_MCPS=codescene,....

Informations d'identification : Aucun jeton fourni. Définissez CS_ACCESS_TOKEN vous-même (voir getting-a-personal-access-token.md dans le dépôt source). Ne jamais valider les jetons dans le dépôt.

Ce que les outils lisent : Lorsqu'ils sont invoqués, les outils analysent les fichiers et l'état git dans le dépôt local que vous leur indiquez (chemins que vous transmettez, plus le contexte de branche pour analyze_change_set). Ils ne s'exécutent pas seuls. Pour le mode autonome, suivez la documentation sur la confidentialité de la source : codescene-mcp-server README et CodeScene policies. N'utilisez pas cette compétence pour des secrets, informations d'identification ou chemins que vous ne souhaitez pas analyser.

Si le MCP est indisponible (hors ligne, mauvais jeton, panne du serveur) : N'inventez pas de scores de Code Health. Informez l'utilisateur que la vérification a été ignorée. Continuez uniquement avec l'approbation explicite de l'utilisateur. Privilégiez les vérifications de lint/tests/loop de vérification pour le verrouillage lorsque le MCP est en panne. Réactivez les vérifications une fois le serveur connecté.

Quand l'utiliser

• L'utilisateur demande de réviser la qualité du code, refactoriser un fichier, ou vérifier si les modifications IA ont dégradé la maintenabilité
• Avant de modifier un hotspot, un module hérité ou un fichier inconnu
• Avant un commit ou une pull request lorsque vous avez besoin d'une garantie de maintenabilité
• Après un large diff écrit par l'agent — vérifiez que Code Health n'a pas régressé
• Associer avec verification-loop, tdd-workflow, ou /quality-gate comme vérification structurelle (pas un remplacement des tests/lint)

Quand l'activer

Mêmes déclencheurs que Quand l'utiliser ci-dessus — ce titre est ce qu'ECC utilise pour l'activation automatique de la compétence.

Comment ça fonctionne

1. Connecter le serveur MCP

Copiez l'entrée codescene de mcp-configs/mcp-servers.json dans votre configuration MCP harnais.

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

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

Étendu au projet : fusionnez le même bloc dans .mcp.json à la racine du dépôt.

La configuration du jeton est documentée dans le dépôt source (lien ci-dessus). Le mode autonome ne nécessite pas de compte CodeScene payant pour les quatre outils listés ci-dessous. Redémarrez la session et confirmez que le serveur codescene est connecté avant de vous fier aux scores.

2. Utiliser uniquement les outils autonomes

Outil	Quand l'utiliser
code_health_review	Analyse structurelle complète avant de modifier un fichier
code_health_score	Score numérique rapide après chaque modification (vérification d'écart)
pre_commit_code_health_safeguard	Bloquer les commits qui introduisent des régressions de Code Health
analyze_change_set	Vérification au niveau de la branche avant d'ouvrir une PR

N'appelez pas les outils réservés à la plateforme (par exemple, les listes de hotspots de dette technique à l'échelle du dépôt). Ne référencez pas delta_analysis — non disponible en mode autonome.

3. Interpréter les scores (1–10)

Plage	Signification	Comportement de l'agent
9.0–10.0	Vert — sain	Plus sûr pour étendre ; privilégier toujours les découpages verticaux
4.0–8.9	Jaune — dette	Agir avec prudence ; pas de refactoring non sollicité
1.0–3.9	Rouge — dette sévère	Périmètre de modification étroit uniquement

4. Exécuter la boucle de rétroaction

Avant de toucher un fichier

1. Exécutez code_health_review sur le chemin cible.
2. Enregistrez le score de base et les odeurs de code listées.
3. Planifiez la modification la plus petite qui répond à la tâche.

Adaptez le périmètre au score : < 5 — diff minimal uniquement ; 5–7 — pas de refactoring large ; > 7 — plus sûr de refactoriser, vérifier après chaque modification.

Après chaque modification

1. Exécutez code_health_score sur le même fichier.
2. Comparez avec le score de base de code_health_review.
3. Si le score a régressé, corrigez avant de continuer. Ne marquez jamais la tâche comme terminée tant que le score est inférieur à celui de départ.

Avant chaque commit — exécutez pre_commit_code_health_safeguard sur le chemin du dépôt.

Avant une PR — exécutez analyze_change_set par rapport à la branche de base (par exemple main).

Exemples

Exemple : Amélioration de la maintenabilité Flask

Sur pallets/flask, une boucle d'agent utilisant uniquement les outils autonomes :

1. code_health_review sur un module cible (score de base 4.82)
2. Refactoring ciblé adressant les odeurs listées
3. code_health_score après chaque modification
4. pre_commit_code_health_safeguard avant le commit
5. analyze_change_set avant la PR

Résultat : Code Health 4.82 → 9.1 (jeton autonome gratuit uniquement).

Exemple : Bloc d'application dans AGENTS.md

Collez dans le fichier AGENTS.md ou CLAUDE.md du projet :

## Code Health (CodeScene MCP)

Avant de modifier un fichier : exécutez `code_health_review`, notez le score et les problèmes.

- Score inférieur à 5 : plage problématique — modifications ciblées.
- Score 5–7 : plage d'avertissement — pas de refactoring large.

Après chaque modification : exécutez `code_health_score` pour vérifier l'écart.

- Si le score a régressé : corrigez avant de continuer ; ne déclarez jamais la tâche terminée si le score a baissé.

Avant chaque commit : exécutez `pre_commit_code_health_safeguard`.

Avant une PR : exécutez `analyze_change_set`.

Exemple : anti-patrons vs boucle correcte

# MAUVAIS : Modifier d'abord, vérifier après
[large refactor without code_health_review]

# MAUVAIS : Ignorer la baisse de score
"Les tests passent" → marquer la tâche terminée alors que Code Health a diminué

# MAUVAIS : Refactoring large sur un fichier rouge (score inférieur à 5)
Nettoyage non sollicité dans tout le module

# BON : revue → petite modification → score → garantie de commit → analyze_change_set

Association avec ECC

Compétence / flux ECC	Rôle de Code Health MCP
coding-standards	Style/nommage ; Code Health = structure/complexité
plankton-code-quality	Lint/formatage à l'écriture ; Code Health = vérification structurelle avant/après modification
verification-loop / /quality-gate	Ajouter la vérification de régression structurelle avant "terminé"
security-review	Sécurité vs maintenabilité — utiliser les deux si pertinent
tdd-workflow	Tests passent ≠ conception saine — vérifier le score après les refactorings

Conseil de contexte : ECC recommande de garder un faible nombre de MCP. Activez codescene lors de modifications substantielles ; désactivez-le quand ce n'est pas nécessaire.

Compétences associées

• coding-standards — conventions de base
• plankton-code-quality — hooks de lint/formatage à l'écriture
• verification-loop — porte build/test/lint
• tdd-workflow — développement piloté par les tests
• security-review — liste de contrôle de sécurité
• documentation-lookup — documentation de bibliothèque via Context7 (orthogonal)