Regeln KI-gestützt über den CodeCharter-MCP-Server schreiben

CodeCharter bringt einen MCP-Server mit, damit ein KI-Coding-Assistent Ihren Code analysieren und beim Schreiben von Regeln helfen kann, ohne den Chat zu verlassen. Der Assistent ruft eine kleine Menge an Tools auf; Sie behalten die Kontrolle darüber, was gespeichert wird.

Server im KI-Tool installieren

Voraussetzungen: Die CodeCharter CLI muss installiert und im PATH verfügbar sein, und eine gültige Lizenz wird benötigt; sowohl codecharter mcp als auch codecharter mcp install brechen sonst mit einem Lizenzfehler ab. Der Install-Befehl schreibt nur die Konfigurationsdatei des Clients; das KI-Tool selbst wird erst gebraucht, um den Server tatsächlich zu nutzen.

codecharter mcp install --client <claude-code|claude-desktop|cursor|windsurf|gemini>

Standardmäßig schreibt der Befehl den CodeCharter-MCP-Server in eine projektweite Konfigurationsdatei im aktuellen Verzeichnis (zum Beispiel .mcp.json für Claude Code); mit --scope user landet er stattdessen in der nutzerweiten Konfiguration. Claude Desktop und Windsurf unterstützen nur die nutzerweite Konfiguration, geben Sie für diese Clients --scope user an. Mit --dry-run gibt der Befehl den resultierenden Diff aus, ohne etwas zu schreiben, und mit --force überschreibt er einen bestehenden CodeCharter-Eintrag. Führen Sie den Befehl einmal pro Tool aus, das Sie nutzen:

codecharter mcp install --client claude-code
codecharter mcp install --client cursor

Unterstützte --client-Werte sind claude-code, claude-desktop, cursor, windsurf und gemini (Googles Gemini CLI). Der Windows-Installer kann den Server für die erkannten Tools registrieren, sodass Sie das unter Windows in der Regel nicht von Hand ausführen müssen.

Für einen MCP-Client, der nicht in der Liste steht, konfigurieren Sie den Client so, dass er codecharter mcp startet; das startet den Server über stdio. Zusätzlich steht ein HTTP-Transport zur Verfügung, siehe den nächsten Abschnitt.

HTTP-Transport

Für Clients, die sich per HTTP statt über stdio verbinden, starten Sie den Server mit --transport http:

codecharter mcp --transport http

Standardmäßig lauscht der Server auf http://127.0.0.1:7777/mcp und gibt die Adresse auf stderr aus. Er stellt zwei Endpunkte bereit:

• POST /mcp: hierhin sendet der Client JSON-RPC-Anfragen.
• GET /mcp: ein Server-Sent-Events-Stream (SSE) für Benachrichtigungen vom Server an den Client.

Flag	Standard	Zweck
--port	7777	TCP-Port, auf dem der Server lauscht.
--bind	127.0.0.1	IP-Adresse, an die der Server gebunden wird.
--token	automatisch erzeugt	Bearer-Token (Literalwert).
--token-file	–	Datei, deren Inhalt als Bearer-Token verwendet wird.
--allow-public	aus	Erforderlich, um an eine Nicht-Loopback-Adresse zu binden.
--cors-origin	nur Same-Origin	CORS-Origin auf der Whitelist; mehrfach angebbar.

Authentifizierung

Bearer-Token-Authentifizierung ist verpflichtend: Jede Anfrage muss einen Authorization: Bearer <token>-Header tragen. Ein fehlendes oder falsches Token wird mit 401 Unauthorized beantwortet. Das Token geben Sie entweder direkt mit --token an oder über --token-file; der Dateiinhalt (ohne umgebende Leerzeichen) wird dann als Token verwendet. Geben Sie keines von beiden an, erzeugt der Server beim Start ein zufälliges Token und gibt es einmalig auf stderr aus:

[codecharter mcp] Bearer token: <erzeugtes-token>

Erreichbarkeit im Netzwerk

Die Standard-Bind-Adresse 127.0.0.1 macht den Server nur vom lokalen Rechner aus erreichbar; localhost und andere Loopback-Adressen verhalten sich genauso. Das Binden an eine Nicht-Loopback-Adresse lehnt der Server ab, solange Sie nicht zusätzlich --allow-public angeben. Das ist eine bewusste Sicherheitssperre, damit der Server nie versehentlich im Netzwerk exponiert wird. Mit --allow-public startet der Server und gibt eine Sicherheitswarnung auf stderr aus.

Der Server spricht unverschlüsseltes http. Wenn Sie ihn über den lokalen Rechner hinaus erreichbar machen müssen, stellen Sie einen TLS-terminierenden Reverse-Proxy davor und halten Sie das Token geheim.

CORS

Standardmäßig beantwortet der Server nur Same-Origin-Anfragen aus dem Browser. Geben Sie --cors-origin einmal pro Origin an, den Sie freischalten möchten, zum Beispiel --cors-origin https://app.example.com.

Beispiel

Server mit festem Token starten:

codecharter mcp --transport http --port 8080 --token my-secret-token

Richten Sie Ihren MCP-Client dann auf http://127.0.0.1:8080/mcp mit dem Header Authorization: Bearer my-secret-token. Zum manuellen Prüfen der Verbindung:

curl -X POST http://127.0.0.1:8080/mcp \
  -H "Authorization: Bearer my-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Die Tools

Der Server stellt sechs Gruppen von Tools bereit: Analyse-Tools, die Regeln gegen echten Code ausführen, ein Coverage-Tool, das das Test-Coverage-Gate ausführt, Graph-Tools, die den Code als Kopplungsgraph zugänglich machen, ein Regelsuche-Tool über den Regelkatalog des Portals, Authoring-Tools, die beim Entwerfen und Prüfen einer neuen Regel helfen, und ein Konfigurations-Tool, das Ihre .codecharter/config.yml bearbeitet. Neben den Tools stellt er außerdem MCP-Ressourcen bereit (docs://getting-started, docs://dsl-grammar, docs://predicates, docs://rule-examples und rules://catalog) für Clients, die Ressourcen anzeigen.

Analyse

Tool	Was es tut
analyze_solution	Das aktive Regel-Set gegen eine ganze .sln / .slnx / .csproj ausführen und die Findings zurückgeben.
analyze_file	Die Regeln gegen eine einzelne Datei ausführen. Schnelles Feedback beim Editieren.
analyze_diff	Die Regeln gegen einen Diff ausführen (z. B. die gestageten Änderungen), sodass der Assistent nur das Geänderte sieht.

Jedes Finding trägt neben der Meldung auch die Empfehlung der Regel, sodass der Assistent einen Fix vorschlagen kann, ohne ein zweites explain_rule aufzurufen.

Alle drei Analyse-Tools akzeptieren einen Parameter min_severity, der die Findings filtert: einer der Werte info, warn oder error. Beachten Sie die Schreibweise warn, nicht warning; auch die Findings melden ihre Severity als warn. Ohne Angabe werden alle Severities zurückgegeben.

Hinweise zu einzelnen Tools:

• analyze_solution akzeptiert zusätzlich include_paths und exclude_paths, jeweils eine Liste von Glob-Mustern wie src/**/*.cs oder tests/**. Ohne include_paths werden alle Dateien einbezogen; Ausschlüsse werden nach den Einschlüssen angewendet. Während das Tool die Quelldateien durchläuft, sendet es MCP-Fortschrittsbenachrichtigungen, sodass ein Client bei großen Solutions den Fortschritt anzeigen kann. Bricht der Client den Aufruf ab, liefert das Tool die bis dahin gesammelten Findings als Teilergebnis mit gesetztem isCancelled-Flag zurück.
• analyze_diff nimmt die Änderungen über genau einen von zwei Parametern entgegen: diff (roher Unified-Diff-Text, z. B. die Ausgabe von git diff) oder git_ref (ein Ref-Bereich wie main..HEAD, den der Server selbst über git diff auflöst). Beide oder keinen anzugeben ist ein Fehler.
• analyze_diff liefert mit include_context: true zusätzlich Findings in vom Diff berührten Dateien, deren gemeldete Zeile außerhalb der geänderten Zeilen liegt, etwa ein Dokumentations-Finding zu einer neu hinzugefügten Methode, wenn die Diagnose auf eine Zeile außerhalb des geänderten Bereichs zeigt. Diese indirekten Findings kommen in einer separaten Sammlung contextFindings, überschneiden sich nie mit den direkten Findings und respektieren min_severity. Der Standard (include_context: false) entspricht dem bisherigen Verhalten.

Coverage

Tool	Funktion
run_coverage	Führt das Test-Coverage-Gate aus und liefert das Ergebnis: die Coverage-Zusammenfassung, den Testausgang je Projekt und jede ungedeckte Region mit Datei, Methode, Zeilennummern und Quelltext-Ausschnitt. Das Gegenstück zu codecharter coverage.

Die Schwelle stammt aus der .codecharter/config.yml, genau wie auf der Kommandozeile. min_coverage überschreibt sie für einen einzelnen Aufruf. Die optionalen Parameter root, skip_tests und results_root entsprechen den Argumenten der CLI. Während die Tests laufen, sendet das Tool Fortschrittsmeldungen, damit der Client bei einer großen Solution nicht in einen Timeout läuft.

Das Ergebnis benennt seinen Ausgang ausdrücklich (success, below-threshold, tests-failed, no-data, no-test-projects oder ein Fehler in Aufruf beziehungsweise Konfiguration), statt den Assistenten Fließtext auswerten zu lassen, und ein fehlgeschlagenes Testprojekt bringt den relevanten Ausschnitt der Testausgabe mit. Damit schließt sich der Kreis: Der Assistent schreibt Code, führt das Gate aus und bekommt genau die Zeilen zurück, denen noch ein Test fehlt.

Mit git_ref (etwa main..HEAD) grenzen Sie das Gate auf die von diesem Bereich geänderten Zeilen statt der ganzen Solution ein; das Ergebnis trägt dann eine Sektion diffCoverage mit den geänderten Zeilennummern und den Regionen, denen ein Test fehlt. Mit affected_by, gesetzt auf denselben Bereich wie git_ref, grenzen Sie zusätzlich ein, welche Testprojekte überhaupt laufen: das Äquivalent zu --affected-by auf dem coverage-Befehl, mit denselben Regeln. Es setzt denselben Bereich wie git_ref voraus und ist mit skip_tests unvereinbar. Die eingegrenzte Auswahl erscheint im coverageScope des Ergebnisses (welche Suiten liefen, welche übersprungen wurden), und eine geänderte Datei ohne jegliche Coverage-Daten lässt den Lauf weiterhin scheitern: Eine engere Auswahl rendert nie als bestandenes Gate über Daten, die sie nie gemessen hat.

Graph

Tool	Was es tut
graph_overview	Eine Solution-weite Sicht auf den Kopplungsgraphen des Codes, aggregiert auf Projekt- oder Namespace-Ebene: Knotenzahlen und die am stärksten gewichteten Kanten zwischen ihnen.
graph_neighborhood	Der aufgelöste Fokus-Typ mit vollständigen Member-Signaturen, danach seine Nachbarn gruppiert nach Beziehung (erbt von/wird beerbt von, implementiert/wird implementiert von, nutzt/wird genutzt von, ruft auf/wird aufgerufen von) bis zur angeforderten Tiefe.
graph_impact	Nur mit target: der transitive Eingangsabschluss ("wer hängt von diesem Typ ab"), gruppiert nach Distanz. Zusätzlich mit source: die kürzesten Abhängigkeitspfade zwischen beiden.
graph_cycles	Jeder Abhängigkeitszyklus im Kopplungsgraphen (starke Zusammenhangskomponenten), aggregiert auf Typ-, Namespace- (Standard) oder Projekt-Ebene. Jeder Zyklus liefert seine Mitglieder, einen repräsentativen kürzesten Zyklus sowie jede schließende Kante mit der Angabe, ob deren alleinige Entfernung den Zyklus bereits auflösen würde.
graph_hubs	Die am stärksten gekoppelten Knoten im Kopplungsgraphen, gerankt nach Fan-in, Fan-out oder Instabilität, aggregiert auf Typ- (Standard), Namespace- oder Projekt-Ebene. Die Grade werden aus den eigenen Kanten des Graphen berechnet, nicht aus den Analyse-Metriken der Regeln, sodass die Werte unabhängig von den aktiven Regeln verfügbar und konsistent bleiben.
graph_paths	Ob jeder Pfad von from nach to über einen optionalen Engpass must_pass_through läuft (oder, ohne diesen, die reine Erreichbarkeit), auf Typ- (Standard) oder Methoden-Ebene. Ein Dreizustands-Ergebnis: true/false werden nur zurückgegeben, wenn die Suche erschöpfend war; eine gekürzte Suche meldet undecided statt eines möglicherweise falschen Ergebnisses. Ein false-Ergebnis trägt einen konkreten Gegenbeispiel-Pfad.
graph_diff	Vergleicht den Kopplungsgraphen zwischen zwei Git-Refs: hinzugefügte/entfernte Knoten, hinzugefügte/entfernte/geänderte Kanten und eine Zusammenfassung der Kopplungsänderungen je Aggregat. base ist erforderlich; head fällt standardmäßig auf den Working Tree zurück.

graph_neighborhood, graph_impact, graph_cycles und graph_paths lösen target/from/to/must_pass_through (und bei graph_impact zusätzlich das optionale source) auf Typ-Ebene auf dieselbe Art auf: ein exakter oder groß-/kleinschreibungsunabhängiger vollständiger Typname, ein Namenssuffix oder ein Quelldateipfad. Ein mehrdeutiges oder nicht aufgelöstes Target liefert eine Kandidatenliste statt zu raten. Die Kanten stammen aus deklarierter Vererbung, Interface-Implementierung, Member-, Parameter-, Rückgabe-, Feld- und Event-Typen sowie standardmäßig aus Methodenrumpf-Aufrufen, die zu einem eindeutigen Methodensymbol aufgelöst wurden und dem deklarierenden Typ des Aufgerufenen zugeordnet werden, aus angewendeten Attributen und aus Objekterzeugungsausdrücken, die zu einem eindeutigen Konstruktorsymbol aufgelöst wurden; jedes Graph-Tool akzeptiert edge_kinds, um einzuschränken, welche der sechs Kantenarten enthalten sind (graph_paths ignoriert edge_kinds bei level: "methods", siehe unten). Alle sieben Tools teilen sich den warmen Per-Workspace-Cache der Analyse-Tools: der erste Aufruf nach einer Änderung ist langsamer, die folgenden sind schnell, mit Ausnahme der base-Seite von graph_diff, siehe unten. Das CLI-Gegenstück, ausgearbeitete Beispiele und die vollständige Liste der Grenzen stehen unter codecharter graph.

graph_paths löst from/to/must_pass_through bei level: "methods" stattdessen gegen die kanonische Signatur einer Methode, ihren um den deklarierenden Typ ergänzten Namen oder ein bloßes Methodennamens-Suffix auf und durchläuft dabei einen bei Bedarf gebildeten induzierten Teilgraphen aus Methodenaufruf-Kanten statt des persistierten Typ-Ebenen-Graphen; siehe paths und Methodenebenen-Ehrlichkeit, warum ein true-Ergebnis dort einen Unterapproximations-Vorbehalt trägt, den Ergebnisse auf Typ-Ebene nicht haben.

Anders als bei den übrigen Graph-Tools wird die base-Seite von graph_diff nicht aus dem warmen Cache bedient: Ein Cache-Miss kostet dort einen dotnet restore plus eine vollständige Solution-Analyse, daher liefert der erste Aufruf für ein gegebenes base/head-Paar sofort isPending: true, statt darauf zu warten. Rufen Sie das Tool erneut mit denselben Werten für base, head und path auf, um das fertige Ergebnis zu erhalten, oder um weiter zu warten, wenn es kurz vor dem Abschluss steht; eine bereits analysierte base wird wie bei jedem anderen Graph-Tool aus einem schnellen Cache je Commit bedient. Knoten- und Kanten-Ids mit einem ordinalen #n-Suffix zur Unterscheidung werden vom Diff ausgeschlossen, da dieses Suffix über zwei unabhängig analysierte Revisionen hinweg nicht stabil garantiert ist.

Regelsuche

Tool	Was es tut
search_rules	Volltext- und facettierte Suche über den Regelkatalog auf dem Portal: Ihre eigenen Regeln oder der kuratierte Beispielkorpus. Das Äquivalent zum Befehl codecharter rules search.

search_rules ergänzt list_rules und explain_rule, die nur die bereits in Ihrem Workspace aktiven Regeln sehen: Rufen Sie search_rules vor scaffold_rule auf, um zu prüfen, ob im Katalog schon eine fast identische Regel existiert, die Sie erweitern oder anpassen können, statt dasselbe noch einmal zu schreiben.

Übergeben Sie eine Freitext-query und grenzen Sie mit scope ein (example für die kuratierten CodeCharter-Regeln oder mine für Ihre eigenen Regeln; example ist der Standard), außerdem mit categories, severities und tags (ein Treffer muss jeden angegebenen Tag tragen). in_profile grenzt auf Regeln ein, die in einem Profil verwendet oder nicht verwendet werden. Die Ergebnisse sind mit page und page_size paginiert (standardmäßig 25 pro Seite, maximal 100), und die Antwort enthält neben den Treffern auch Facetten-Zählungen (je Kategorie, Severity und Tag), sodass ein Assistent eine engere Suche vorschlagen kann, statt zu raten. Dieses Tool ruft das Portal auf und braucht deshalb dieselbe Lizenz- und Portal-Verbindung wie jeder andere Portal-gestützte Befehl.

Authoring

Tool	Was es tut
scaffold_rule	Aus einer einzeiligen Beschreibung ein fertig editierbares .ccr-Gerüst erzeugen, mit ausgefülltem Frontmatter und dem nächstpassenden Beispiel zum Anpassen.
get_authoring_docs	DSL-Grammatik, Prädikat-Katalog oder Beispiele als Text abrufen, sodass der Assistent gegen die echte Referenz entwirft statt zu raten.
list_rules	Die aktuell aktiven Regeln mit Ids und Severities auflisten. Jeder Eintrag zeigt zusätzlich, ob Ihr Workspace die Regel tatsächlich durchsetzt (enabled), und mit welcher Severity sie nach den Overrides aus Ihrer config.yml meldet (effective_severity, neben der von der Regel deklarierten Severity). Deaktivierte Regeln werden standardmäßig mit aufgeführt und markiert; mit include_disabled=false bleiben sie außen vor.
explain_rule	In Klartext erklären, was eine Regel matcht und warum. Bei einer unbekannten rule_id antwortet das Tool mit Vorschlägen der am nächsten liegenden bekannten Regel-Ids.
validate_rule	Eine Entwurfs-Regel parsen, das Frontmatter auf Vollständigkeit prüfen und jede Property-/Methodenreferenz in der Query statisch gegen das DSL-Schema auflösen (auch über verkettete Zugriffe und Lambda-Parameter). Parse-Fehler enthalten einen Hinweis auf das passende get_authoring_docs-Thema, eine unbekannte Property/Methode kommt als Fehler mit „Did you mean"-Vorschlag zurück, wenn eine nahe Übereinstimmung existiert, und ein dünnes Frontmatter erscheint als Warnung. Das Äquivalent zu codecharter validate.
dry_run_rule	Eine Entwurfs-Regel gegen echten Code ausführen, ohne sie zu speichern, um zu sehen, was sie melden würde. Liefert standardmäßig bis zu 50 Treffer (mehr über max_results) und kennzeichnet abgeschnittene Ergebnisse. Akzeptiert dieselben include_paths- / exclude_paths-Globs wie analyze_solution, und severity_override (info, warn, error) ersetzt die in der Regel deklarierte @severity nur für diesen Lauf.
test_rule_spec	Eine Entwurfs-Regel gegen eine .spec.md aus Treffern und Nicht-Treffern ausführen. Das Äquivalent zu codecharter test.
save_rule	Einen validierten Entwurf in das ./rules-Verzeichnis Ihres Workspace schreiben. Lehnt einen kaputten Entwurf ab und überschreibt eine bestehende Regel nur, wenn Sie overwrite=true angeben. Der Dateiname kommt aus rule_id; ohne Angabe wird er als Slug aus der @name-Direktive der Regel abgeleitet (kleingeschrieben, durch Bindestriche getrennt).

Konfiguration

Tool	Was es tut
config_mutate	Eine einzelne Mutation der .codecharter/config.yml anwenden (set, unset, add, remove oder promote), mit derselben Validierung und demselben Schreibverhalten wie die config-Befehle der CLI.

Mit config_mutate kann der Assistent Ihre Konfiguration genauso anpassen, wie Sie es auf der Kommandozeile täten, während Sie in der Hand behalten, was tatsächlich geschrieben wird:

• Die Mutation wählt operation: einen gepunkteten Schlüssel set / unset (params.<rule>.<name>, overrides.<rule>.severity, profiles.<slug>); einen Listeneintrag in einer section (exclude, profiles, ignore, include) über list_value add / remove (oder ein lokaler Bundle-path für ein Profil); oder einen Schlüssel aus der config.local.yml per promote in die eingecheckte config.yml hochziehen. Ein ignore/include-Eintrag lässt sich mit in_namespace und match eingrenzen.
• Standardmäßig ein Dry-Run. Mit dry_run: true (der Standard) gibt das Tool den Unified-Diff der Änderung zurück, statt zu schreiben, sodass der Assistent und Sie die genaue Änderung zuerst sehen. Mit dry_run: false wird die Datei tatsächlich geschrieben.
• Mit use_local: true zielt die Mutation auf config.local.yml statt auf die eingecheckte config.yml. Bei promote zieht all das gesamte lokale Overlay hoch und keep kopiert statt zu verschieben (der Eintrag bleibt in der config.local.yml).
• Regel- und Parameter-Referenzen werden gegen dasselbe aktive Regel-Set geprüft, das auch die Analyse-Tools sehen. Eine Mutation, die eine unbekannte Regel oder einen Parameter außerhalb des gültigen Bereichs nennt, wird daher abgelehnt, bevor sie geschrieben wird, genau wie die CLI sie ablehnt.

Der Authoring-Loop

Das Schreiben einer Regel folgt typischerweise dieser Abfolge:

1. Gerüst scaffold_rule verwandelt eine einzeilige Beschreibung in ein .ccr-Gerüst mit ausgefülltem Frontmatter.
2. Validieren validate_rule prüft, ob der Entwurf parst, das Frontmatter vollständig ist und jede Property-/Methodenreferenz in der Query gegen das DSL-Schema auflöst. Syntax-Fehler tauchen hier auf, jeweils mit einem Hinweis auf das passende get_authoring_docs-Thema; eine unbekannte Property oder Methode (etwa ein Tippfehler) wird jetzt ebenfalls hier erkannt, statt erst bei dry_run_rule oder test_rule_spec.
3. Dry-Run dry_run_rule führt den Entwurf gegen Ihren echten Code aus, ohne ihn zu speichern, damit Sie Über- und Unter-Matching vor dem Speichern erkennen können.
4. Spec test_rule_spec führt den Entwurf gegen eine .spec.md mit expliziten Treffern und Nicht-Treffern aus. Eine bestandene Spec bedeutet, die Regel tut, was Sie beabsichtigt haben.
5. Speichern save_rule schreibt den validierten Entwurf in das ./rules-Verzeichnis Ihres Workspace, wo codecharter analyze ihn aufnimmt. Ein fehlerhafter Entwurf wird abgelehnt.

Alle Schritte vor save_rule laufen im Speicher. Nichts berührt Ihr Regel-Set, bis Sie explizit speichern. Mit get_authoring_docs können Sie jederzeit DSL-Grammatik oder Prädikat-Katalog in die Unterhaltung holen.

Welche Regeln der MCP-Server sieht

Der Server löst sein Regelverzeichnis in derselben Reihenfolge auf wie codecharter analyze: Ein explizit angegebener Regelpfad gewinnt, sonst ein rules-Ordner im Workspace. codecharter mcp hat kein Flag für einen expliziten Pfad, in der Praxis verwenden die Analyse-Tools daher den rules-Ordner neben der gefundenen Solution oder dem gefundenen Projekt, während list_rules und explain_rule den rules-Ordner in dem Verzeichnis nutzen, aus dem der Server gestartet wurde.

Verwandt

• codecharter validate und codecharter test sind die CLI-Äquivalente zu validate_rule und test_rule_spec.
• codecharter config ist das CLI-Äquivalent zu config_mutate.
• Regeln schreiben behandelt die DSL, in der der Assistent entwirft.