Skip to content

MCP-Regel-Authoring

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

Aktualisiert am 2026-06-10

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 ausschließlich unverschlüsseltes http; eingebautes TLS gibt es nicht. 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 sind keine Cross-Origin-Anfragen aus dem Browser erlaubt (nur Same-Origin). 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 zwei Gruppen von Tools bereit: Analyse-Tools, die Regeln gegen echten Code ausführen, und Authoring-Tools, die beim Entwerfen und Prüfen einer neuen Regel helfen. 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.

Authoring

Tool Was es tut
scaffold_rule Aus einer einzeiligen Beschreibung ein fertig editierbares .cgr-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.
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 und das Frontmatter auf Vollständigkeit prüfen. Parse-Fehler enthalten einen Hinweis auf das passende get_authoring_docs-Thema, 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).

Der Authoring-Loop

Das Schreiben einer Regel folgt typischerweise dieser Abfolge:

  1. Gerüst scaffold_rule verwandelt eine einzeilige Beschreibung in ein .cgr-Gerüst mit ausgefülltem Frontmatter.
  2. Validieren validate_rule prüft, ob der Entwurf parst und das Frontmatter vollständig ist. Syntax-Fehler tauchen hier auf, jeweils mit einem Hinweis auf das passende get_authoring_docs-Thema.
  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, danach ein rules-Ordner im Workspace, danach die neben dem codecharter-Binary mitgelieferten Regeln. 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. Fehlt beides, greifen die Tools auf die mitgelieferten Regeln zurück.

Verwandt