Was macht Code Health MCP (CodeScene)?
Strukturelles Wartbarkeits-Feedback für KI-gestütztes Programmieren. Ergänzt Style-/Lint-Skills (coding-standards, plankton-code-quality) mit Design-Level-Gesundheits-Scores und Regressions-Gattern.
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 keine gebündelten MCP-Server automatisch. Kopieren Sie den Eintrag nur in Ihre Konfiguration, wenn Sie ihn möchten. Sie können ihn während der ECC-Installation/Synchronisation mit ECC_DISABLED_MCPS=codescene,... ausschließen.
Anmeldedaten: Kein gebündelter Token. Setzen Sie CS_ACCESS_TOKEN selbst (siehe getting-a-personal-access-token.md im Upstream-Repo). Committen Sie niemals Token in das Repository.
Was die Tools lesen: Beim Aufruf analysieren die Tools Codedateien und Git-Zustand im lokalen Repository, auf das Sie sie verweisen (von Ihnen übergebene Pfade sowie Branch-Kontext für analyze_change_set). Sie laufen nicht von selbst. Für den eigenständigen Modus folgen Sie der Upstream-Datenschutzdokumentation: codescene-mcp-server README und CodeScene-Richtlinien. Verwenden Sie diesen Skill nicht für Geheimnisse, Anmeldedaten oder Pfade, die Sie nicht analysieren lassen möchten.
Wenn der MCP nicht verfügbar ist (offline, ungültiger Token, Serverabsturz): Erfinden Sie keine Code Health Scores. Teilen Sie dem Benutzer mit, dass die Prüfung übersprungen wurde. Fahren Sie nur mit expliziter Benutzerzustimmung fort. Bevorzugen Sie Lint/Tests/Verification-Schleife für das Gating, wenn der MCP ausgefallen ist. Aktivieren Sie die Prüfungen wieder, sobald der Server verbunden ist.
Wann verwenden
- Benutzer fragt nach Code-Qualitätsüberprüfung, Refactoring einer Datei oder ob KI-Änderungen die Wartbarkeit verschlechtert haben
- Vor der Bearbeitung eines Hotspots, Legacy-Moduls oder einer unbekannten Datei
- Vor Commit oder Pull Request, wenn Sie eine Wartbarkeitsabsicherung benötigen
- Nach einem großen KI-geschriebenen Diff – überprüfen, ob die Code Health nicht zurückgegangen ist
- Kombinieren mit
verification-loop,tdd-workflowoder/quality-gateals strukturelle Prüfung (kein Ersatz für Tests/Lint)
Wann aktivieren
Gleiche Auslöser wie unter Wann verwenden oben – diese Überschrift wird von ECC zur Skill-Autoaktivierung verwendet.
Funktionsweise
1. MCP-Server verbinden
Kopieren Sie den codescene-Eintrag aus mcp-configs/mcp-servers.json in Ihre MCP-Konfiguration.
Claude Code (~/.claude.json → mcpServers):
"codescene": {
"command": "npx",
"args": ["-y", "@codescene/codehealth-mcp"],
"env": {
"CS_ACCESS_TOKEN": "IHR_CS_ACCESS_TOKEN_HIER"
}
}
Projektweit: Fügen Sie denselben Block in .mcp.json im Repository-Stammverzeichnis ein.
Die Token-Einrichtung ist im Upstream-Repo dokumentiert (Link oben). Der eigenständige Modus erfordert kein kostenpflichtiges CodeScene-Plattformkonto für die vier unten aufgeführten Tools. Starten Sie die Sitzung neu und bestätigen Sie, dass der codescene-Server verbunden ist, bevor Sie sich auf Scores verlassen.
2. Nur eigenständige Tools aufrufen
| Tool | Wann verwenden |
|---|---|
code_health_review | Vollständige Strukturanalyse vor dem Ändern einer Datei |
code_health_score | Schnelle numerische Bewertung nach jeder Änderung (Delta-Prüfung) |
pre_commit_code_health_safeguard | Commits blockieren, die Code Health Regressionen einführen |
analyze_change_set | Branch-Ebene-Prüfung vor dem Öffnen eines PRs |
Rufen Sie keine Plattform-exklusiven Tools auf (z. B. repository-weite technische Schulden-Hotspot-Listen). Verweisen Sie 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 Refactorings nebenbei |
| 1.0–3.9 | Rot – schwere Schulden | Nur minimalen Umfang ändern |
4. Feedback-Schleife ausführen
Vor dem Bearbeiten einer Datei
code_health_reviewauf dem Zielpfad ausführen.- Basis-Score und aufgeführte Code Smells notieren.
- Die kleinste Änderung planen, die die Aufgabe erledigt.
Umfang nach Score: unter 5 – nur minimale Diffs; 5–7 – keine breiten Refactorings; über 7 – sicherer zu refaktorieren, dennoch nach jeder Bearbeitung überprüfen.
Nach jeder Änderung
code_health_scoreauf derselben Datei ausführen.- Mit dem Basiswert aus
code_health_reviewvergleichen. - Wenn der Score zurückgegangen ist, vor dem Fortfahren korrigieren. Die Aufgabe niemals als erledigt markieren, während der Score niedriger als zu Beginn ist.
Vor jedem Commit – führen Sie pre_commit_code_health_safeguard auf dem Repository-Pfad aus.
Vor einem PR – führen Sie analyze_change_set gegen den Basis-Branch (z. B. main) aus.
Beispiele
Beispiel: Flask-Wartbarkeitsverbesserung
Auf pallets/flask, eine Agentenschleife, die nur eigenständige Tools verwendet:
code_health_reviewauf einem Zielmodul (Basis 4.82)- Gezieltes Refactoring unter Berücksichtigung der aufgeführten Code Smells
code_health_scorenach jeder Bearbeitungpre_commit_code_health_safeguardvor dem Commitanalyze_change_setvor dem PR
Ergebnis: Code Health 4.82 → 9.1 (nur kostenloser eigenständiger Token).
Beispiel: AGENTS.md Durchsetzungsblock
Fügen Sie in die Projekt-AGENTS.md oder CLAUDE.md ein:
## Code Health (CodeScene MCP)
Vor dem Ändern einer Datei: `code_health_review` ausführen, Score und Probleme notieren.
- Score unter 5: problematischer Bereich – Änderungen eng begrenzen.
- Score 5–7: Warnbereich – keine breiten Refactorings.
Nach jeder Änderung: `code_health_score` ausführen, um das Delta zu überprüfen.
- Wenn Score zurückgegangen: vor dem Fortfahren korrigieren; niemals als erledigt erklären, wenn Score gesunken ist.
Vor jedem Commit: `pre_commit_code_health_safeguard` ausführen.
Vor PR: `analyze_change_set` ausführen.
Beispiel: Anti-Patterns vs. korrekte Schleife
# SCHLECHT: Erst bearbeiten, dann prüfen
[Großes Refactoring ohne code_health_review]
# SCHLECHT: Score-Abfall ignorieren
"Tests bestehen" → Aufgabe als erledigt markieren, während Code Health gesunken ist
# SCHLECHT: Breites Refactoring auf Datei mit rotem Score (unter 5)
Saubermachen auf dem gesamten Modul
# GUT: Überprüfung → kleine Änderung → Score → Commit-Sicherung → analyze_change_set
Kombination mit ECC
| ECC-Skill / -Flow | Code Health MCP-Rolle |
|---|---|
coding-standards | Stil/Benennung; Code Health = Struktur/Komplexität |
plankton-code-quality | Schreibzeit-Lint/Format; Code Health = strukturelles Gate vor/nach Bearbeitung |
verification-loop / /quality-gate | Strukturelle Regressionsprüfung vor "erledigt" hinzufügen |
security-review | Sicherheit vs. Wartbarkeit – bei Bedarf beides verwenden |
tdd-workflow | Tests bestanden ≠ gesundes Design – nach Refactorings Score prüfen |
Kontext-Tipp: ECC empfiehlt, die Anzahl der MCPs niedrig zu halten. Aktivieren Sie codescene bei substanziellen Änderungen; deaktivieren Sie es, wenn nicht benötigt.
Verwandte Skills
coding-standards– grundlegende Konventionenplankton-code-quality– Schreibzeit-Lint/Format-Hooksverification-loop– Build/Test/Lint-Gatetdd-workflow– Test-first-Entwicklungsecurity-review– Sicherheits-Checklistedocumentation-lookup– Bibliotheksdokumentation via Context7 (orthogonal)