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

CodeCharter über den MCP-Server aus einem KI-Assistenten steuern und Regeln KI-gestützt schreiben.

Aktualisiert am 2026-09-01

CodeCharter bringt einen MCP-Server mit, damit ein KI-Coding-Assistent deinen Code analysieren und beim Schreiben von Regeln helfen kann, ohne den Chat zu verlassen. Der Assistent ruft eine kleine Menge an Tools auf; du behältst 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, gib 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ühre den Befehl einmal pro Tool aus, das du nutzt:

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 du das unter Windows in der Regel nicht von Hand ausführen musst.

Für einen MCP-Client, der nicht in der Liste steht, konfigurierst du 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, startest du 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 gibst du entweder direkt mit --token an oder über --token-file; der Dateiinhalt (ohne umgebende Leerzeichen) wird dann als Token verwendet. Gibst du 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 du nicht zusätzlich --allow-public angibst. 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 du ihn über den lokalen Rechner hinaus erreichbar machen musst, stell einen TLS-terminierenden Reverse-Proxy davor und halte das Token geheim.

CORS

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

Beispiel

Server mit festem Token starten:

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

Richte deinen 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 deine .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. Beachte 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) grenzt du 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, grenzt du 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. Rufe 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.

Requirements

Die Tabelle unten listet nur die drei rein lesenden Abfrage-Tools – die vollständigen zehn Requirement-MCP-Tools, einschließlich der schreibenden, prüfenden und Coverage-messenden, stehen unter Requirements über MCP.

Tool	Was es tut
`req_context`	Alles Relevante zu einem Code-Symbol oder einer Datei: die direkt verankerten Requirements, dazu was sie transitiv rechtfertigt, was sie verfeinert und was sich mit ihr überschneidet.
`req_search`	Requirements finden nach Id, Status, Art, Priorität, Vertragsflag, Abschnitt oder Freitext.
`req_justify`	Der Rückweg: von einem Code-Symbol oder einer Datei zurück zu den Requirement-Wurzeln, die dessen Existenz rechtfertigen.

Diese drei sind rein lesend – keines kann ein Requirement schreiben, prüfen oder annehmen. Das bleibt ein menschlicher Akt auf der Kommandozeile über codecharter req. Sie lesen aus demselben Requirement-Corpus und demselben warmen Per-Workspace-Analyse-Cache, den sich auch die Graph- und Analyze-Tools teilen, sodass ein Agent eine Änderung in dem dahinterstehenden Requirement verankern oder prüfen kann, ob ein Codestück überhaupt gerechtfertigt ist, ohne je die .req.md-Dateien direkt anzufassen.

req_context und req_justify lösen target genauso auf wie die Graph-Tools ihre Ziele: ein exakter oder groß-/kleinschreibungsunabhängiger vollständiger Typ-/Methodenname, ein Namenssuffix oder ein Quelldateipfad. Ein mehrdeutiges oder nicht aufgelöstes Target liefert eine Kandidatenliste statt zu raten. Der Parameter include von req_context wählt aus, welche Beziehungs-Sektionen berechnet werden (anchored, justified, refines, overlaps – standardmäßig alle vier); prose steuert, wie viel vom Fließtext jedes Requirements mitkommt (none, summary oder full). witness bei req_justify steuert, wie viel rechtfertigende Evidenz zusätzlich zum Ergebnis justified/not_justified/unknown mitkommt: none, roots (die Anchor-Stellen des rechtfertigenden Requirements, Standard) oder paths (eine token-begrenzte Pfadsuche, optional). Fehlende Evidenz wird nie als not_justified dargestellt – dieses Ergebnis setzt ein tatsächliches Code-Modell und ein Target voraus, das zu mindestens einer analysierbaren Deklaration aufgelöst wurde; alles andere kommt als unknown zurück. Alle drei akzeptieren max_tokens und melden estimatedTokens, passend zum Kürzungsvertrag der Graph-Tools.

Das Ergebnis eines rule:-Criteriums wird von diesen drei Tools bewusst nie ausgewertet – nur die pin-abgeleiteten Criteria (test, manual, integration, external). Ein Requirement mit einem rule:-Criterion listet es weiterhin auf, markiert als hier nicht ausgewertet; für das tatsächliche Ergebnis codecharter req check oder die analyze/analyze_diff-Tools ausführen.

Regelsuche

Tool	Was es tut
`search_rules`	Volltext- und facettierte Suche über den Regelkatalog auf dem Portal: deine 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 deinem Workspace aktiven Regeln sehen: Rufe search_rules vor scaffold_rule auf, um zu prüfen, ob im Katalog schon eine fast identische Regel existiert, die du erweitern oder anpassen kannst, statt dasselbe noch einmal zu schreiben.

Übergib eine Freitext-query und grenze mit scope ein (example für die kuratierten CodeCharter-Regeln oder mine für deine 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 dein Workspace die Regel tatsächlich durchsetzt (`enabled`), und mit welcher Severity sie nach den Overrides aus deiner `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 erste Regelverzeichnis schreiben, das die Config des über `path` benannten Workspace unter `rules:` deklariert. `path` ist Pflicht (siehe Workspace-Anker). Lehnt ab, wenn keines deklariert ist (deklariere eines mit `config_mutate`, Abschnitt `rules`), lehnt einen kaputten Entwurf ab und überschreibt eine bestehende Regel nur, wenn du `overwrite=true` angibst. 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 deine Konfiguration genauso anpassen, wie du es auf der Kommandozeile tätest, während du in der Hand behältst, 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 du die genaue Änderung zuerst seht. 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.
Übergib workspace_path: ein absoluter Pfad zu einer beliebigen Datei oder einem Verzeichnis im Workspace, dessen Konfiguration mutiert werden soll. Eine vorhandene Datei wird an ihrem enthaltenden Verzeichnis verankert. Ist dry_run false, ist der Parameter Pflicht; ein Dry Run ohne ihn nutzt das aktuelle Verzeichnis des Servers und sagt das (siehe Workspace-Anker).

Workspace-Anker

Jedes Tool, das einen Workspace liest oder schreibt, nimmt einen Anker: einen absoluten Pfad zu einer beliebigen Datei oder einem Verzeichnis in diesem Workspace. Das Arbeitsverzeichnis des Servers ist dort, wo dein KI-Tool ihn gestartet hat, meist dein Haupt-Checkout. Ein Agent, der in einem Git-Worktree oder einem zweiten Klon arbeitet, teilt sich diesen Server; ein Aufruf ohne Anker würde also stillschweigend den Haupt-Checkout statt des eigenen bearbeiten.

Schreibende Tools verlangen den Anker. save_rule, req_bind, req_draft, req_request_acceptance und req_acknowledge lehnen einen Aufruf ohne path ab (auch einen Dry Run), config_mutate lehnt einen Schreibvorgang (dry_run: false) ohne workspace_path ab. Die Ablehnung nennt das Verzeichnis, das der Aufruf verwendet hätte; geschrieben wird nichts.
Lesende Tools fallen sichtbar zurück. Ohne Anker nutzen sie das Arbeitsverzeichnis des Servers, und das Ergebnis sagt das in seinem Hinweiskanal (notice, notices oder message): "No path given, anchored at <Verzeichnis>". run_coverage schreibt nur eigene Artefakte und verhält sich wie ein lesendes Tool.
Im Git-Worktree immer den Anker übergeben. Die Beschreibung jedes workspace-gebundenen Tools wiederholt das.

Der Anker-Parameter heißt aus historischen Gründen je nach Tool anders. Die Namen bedeuten dasselbe und bleiben, wie sie sind, weil eine Umbenennung bestehende Clients brechen würde:

Parameter	Tools
`path`	`analyze_file` (laut Schema Pflicht), `analyze_diff`, `analyze_solution`, `dry_run_rule`, `list_rules`, `explain_rule`, `save_rule`, alle `graph_`-Tools, alle `req_`-Tools
`workspace_path`	`config_mutate` (dessen `path` benennt ein lokales Profil-Bundle, nicht den Workspace)
`root`	`run_coverage`

Das Gegenstück in der CLI ist die globale Option --workspace <dir>; siehe Workspace angeben.

Der Authoring-Loop

Das Schreiben einer Regel folgt typischerweise dieser Abfolge:

Gerüst scaffold_rule verwandelt eine einzeilige Beschreibung in ein .ccr-Gerüst mit ausgefülltem Frontmatter.
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.
Dry-Run dry_run_rule führt den Entwurf gegen deinen echten Code aus, ohne ihn zu speichern, damit du Über- und Unter-Matching vor dem Speichern erkennen kannst.
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 du beabsichtigt hast.
Speichern save_rule schreibt den validierten Entwurf in das erste Verzeichnis, das deine .codecharter/config.yml unter rules: deklariert, wo codecharter analyze ihn aufnimmt. Ohne rules:-Eintrag lehnt es ab und nennt den config_mutate-Aufruf, der einen deklariert, denn eine Regel in einem nicht deklarierten Ordner würde nie laufen. Ein fehlerhafter Entwurf wird abgelehnt.

Alle Schritte vor save_rule laufen im Speicher. Nichts berührt dein Regel-Set, bis du explizit speicherst. Mit get_authoring_docs kannst du jederzeit DSL-Grammatik oder Prädikat-Katalog in die Unterhaltung holen.

Welche Regeln der MCP-Server sieht

Jedes Tool liest die Regelquellen, die die .codecharter/config.yml des Workspace deklariert, genau wie codecharter analyze: die profiles: aus dem lokal entpackten Cache, danach die rules:-Verzeichnisse, wobei bei doppelter Regel-ID die spätere Quelle gewinnt. Der Server hat kein --rules, und kein Ordner wird aufgenommen, nur weil er existiert. Ist keine Quelle deklariert, liefern die Analyse-Tools ein inkonklusives Ergebnis, dessen Hinweis codecharter config init und codecharter config add profiles codeguard/csharp-all@^1.2 nennt. Die Ergebnisse behalten ruleSourceKind (profiles, rules-directory, composite, wenn beide Arten beitragen, oder none) und ruleSourceDetail (die Kennungen der aufgelösten Quellen, durch Kommas getrennt).

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.