codehealth-mcp

Code Health MCP (CodeScene)

Strukturorientierte Wartbarkeitsrückmeldungen für KI-gestütztes Programmieren. Ergänzt Stil-/Lint-Skills (coding-standards, plankton-code-quality) mit designbezogenen Gesundheits-Scores und Regressionsgattern.

Upstream: codescene-oss/codescene-mcp-server Paket: @codescene/codehealth-mcp (stdio via npx)

Sicherheit und Grenzen

Opt-in (ECC): Der codescene-Block in mcp-configs/mcp-servers.json ist nur eine Vorlage. ECC-Plugin-Installationen aktivieren gebündelte MCP-Server nicht automatisch. Kopiere den Eintrag nur in deine Konfiguration, wenn du ihn verwenden möchtest. Du kannst ihn während der ECC-Installation/Synchronisation mit ECC_DISABLED_MCPS=codescene,... ausschließen.

Zugangsdaten: Kein eingebetteter Token. Setze CS_ACCESS_TOKEN selbst (siehe getting-a-personal-access-token.md im Upstream-Repository). Committe niemals Tokens in das Repository.

Was die Werkzeuge lesen: Beim Aufruf analysieren die Werkzeuge Dateien und den Git-Status im lokalen Repository, auf das du sie verweist (Pfade, die du übergibst, plus Branch-Kontext für analyze_change_set). Sie laufen nicht von selbst. Für den eigenständigen Modus folge der Upstream-Datenschutzdokumentation: codescene-mcp-server README und CodeScene Policies. Verwende diesen Skill nicht für Geheimnisse, Anmeldedaten oder Pfade, die du nicht analysiert haben möchtest.

Wenn der MCP nicht verfügbar ist (offline, falscher Token, Serverabsturz): Erfinde keine Code-Gesundheits-Scores. Teile dem Benutzer mit, dass die Prüfung übersprungen wurde. Fahre nur mit ausdrücklicher Benutzerzustimmung fort. Verwende bevorzugt Lint/Tests/Verification-Loop für das Gating, wenn der MCP ausgefallen ist. Aktiviere die Prüfungen wieder, sobald der Server verbunden ist.

Wann verwenden

• Benutzer bittet um Überprüfung der Codequalität, Refactoring einer Datei oder möchte prüfen, ob KI-Änderungen die Wartbarkeit verschlechtert haben
• Vor der Bearbeitung eines Hotspots, Legacy-Moduls oder einer unbekannten Datei
• Vor Commit oder Pull-Request, wenn du eine Wartbarkeitsabsicherung benötigst
• Nach einem großen agentengeschriebenen Diff – verifiziere, dass sich die Code-Gesundheit nicht verschlechtert hat
• Kombiniere mit verification-loop, tdd-workflow oder /quality-gate als strukturelle Prüfung (kein Ersatz für Tests/Lint)

Wann aktivieren

Gleiche Auslöser wie Wann verwenden oben – diese Überschrift wird von ECC für die automatische Skill-Aktivierung verwendet.

Wie es funktioniert

1. MCP-Server verbinden

Kopiere den codescene-Eintrag aus mcp-configs/mcp-servers.json in deine MCP-Konfiguration.

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

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

Projektbezogen: Füge denselben Block in .mcp.json im Stammverzeichnis des Repositories ein.

Die Token-Einrichtung ist im Upstream-Repository dokumentiert (Link oben). Der eigenständige Modus erfordert kein kostenpflichtiges CodeScene-Plattformkonto für die vier unten aufgeführten Werkzeuge. Starte die Sitzung neu und bestätige, dass der codescene-Server verbunden ist, bevor du dich auf Scores verlässt.

2. Nur eigenständige Werkzeuge aufrufen

Werkzeug	Wann verwenden
code_health_review	Vollständige Strukturanalyse vor dem Ändern einer Datei
code_health_score	Schneller numerischer Score nach jeder Änderung (Delta-Prüfung)
pre_commit_code_health_safeguard	Commits blockieren, die Code-Gesundheits-Verschlechterungen einführen
analyze_change_set	Branch-Ebene-Prüfung vor dem Öffnen eines PRs

Rufe keine plattformexklusiven Werkzeuge auf (z. B. repositoryweite technische Schulden-Hotspot-Listen). Verweise nicht auf delta_analysis – im eigenständigen Modus nicht verfügbar.

3. Scores interpretieren (1–10)

Bereich	Bedeutung	Agentenverhalten
9.0–10.0	Grün – gesund	Sicherer zu erweitern; dennoch vertikale Slices bevorzugen
4.0–8.9	Gelb – Schulden	Vorsichtig vorgehen; keine zufälligen Refactorings
1.0–3.9	Rot – schwere Schulden	Nur enge Bereiche bearbeiten

4. Rückkopplungsschleife ausführen

Vor dem Berühren einer Datei

1. Führe code_health_review auf dem Zielpfad aus.
2. Notiere den Basis-Score und die aufgeführten Code-Gerüche.
3. Plane die kleinste Änderung, die die Aufgabe erfüllt.

Bereichsspezifisch nach Score: unter 5 – nur minimales Diff; 5–7 – keine breiten Refactorings; über 7 – sicherer zu refaktorisieren, dennoch nach jeder Bearbeitung überprüfen.

Nach jeder Änderung

1. Führe code_health_score auf derselben Datei aus.
2. Vergleiche mit dem Basiswert von code_health_review.
3. Wenn der Score gesunken ist, korrigiere vor dem Fortfahren. Erkläre die Aufgabe niemals als erledigt, während der Score niedriger ist als zu Beginn.

Vor jedem Commit – führe pre_commit_code_health_safeguard auf dem Repository-Pfad aus.

Vor einem PR – führe analyze_change_set gegen den Basis-Branch (z. B. main) aus.

Beispiele

Beispiel: Flask-Wartbarkeitsverbesserung

Auf pallets/flask, eine Agentenschleife, die nur eigenständige Werkzeuge verwendet:

1. code_health_review auf einem Zielmodul (Basiswert 4.82)
2. Gezieltes Refactoring, das die aufgeführten Gerüche adressiert
3. code_health_score nach jeder Bearbeitung
4. pre_commit_code_health_safeguard vor dem Commit
5. analyze_change_set vor dem PR

Ergebnis: Code-Gesundheit 4.82 → 9.1 (nur kostenloser eigenständiger Token).

Beispiel: AGENTS.md-Durchsetzungsblock

Füge in die Projekt-AGENTS.md oder CLAUDE.md ein:

## Code-Gesundheit (CodeScene MCP)

Vor dem Ändern einer Datei: führe `code_health_review` aus, notiere Score und Probleme.

- Score unter 5: problematischer Bereich – Änderungen eng eingrenzen.
- Score 5–7: Warnbereich – keine breiten Refactorings.

Nach jeder Änderung: führe `code_health_score` aus, um das Delta zu verifizieren.

- Wenn Score gesunken: korrigiere vor dem Fortfahren; erkläre niemals als erledigt, wenn der Score gefallen ist.

Vor jedem Commit: führe `pre_commit_code_health_safeguard` aus.

Vor PR: führe `analyze_change_set` aus.

Beispiel: Anti-Patterns vs. korrekte Schleife

# SCHLECHT: Erst bearbeiten, dann prüfen
[großes Refactoring ohne code_health_review]

# SCHLECHT: Score-Abfall ignorieren
"Tests bestanden" → Aufgabe als erledigt markieren, während die Code-Gesundheit gesunken ist

# SCHLECHT: Breites Refactoring auf einer Datei mit rotem Score (unter 5)
Zufällige Aufräumarbeiten im gesamten Modul

# GUT: review → kleine Änderung → score → commit safeguard → analyze_change_set

Kombination mit ECC

ECC-Skill / -Ablauf	Code Health MCP-Rolle
coding-standards	Stil/Benennung; Code-Gesundheit = Struktur/Komplexität
plankton-code-quality	Schreibzeit-Lint/Format; Code-Gesundheit = strukturelles Gate vor/nach Bearbeitung
verification-loop / /quality-gate	Strukturelle Regressionsprüfung vor „Erledigt" hinzufügen
security-review	Sicherheit vs. Wartbarkeit – bei Bedarf beide verwenden
tdd-workflow	Tests bestanden ≠ gesundes Design – Score nach Refactorings prüfen

Kontext-Tipp: ECC empfiehlt, die MCP-Anzahl niedrig zu halten. Aktiviere codescene bei substanziellen Bearbeitungen; deaktiviere es, wenn es nicht benötigt wird.

Verwandte Skills

• coding-standards – grundlegende Konventionen
• plankton-code-quality – Schreibzeit-Lint/Format-Hooks
• verification-loop – Build/Test/Lint-Gate
• tdd-workflow – testgetriebene Entwicklung
• security-review – Sicherheitscheckliste
• documentation-lookup – Bibliotheksdokumentation via Context7 (orthogonal)