Zum Inhalt springen

Output Gate: JS-Policies für MCP-Tool-Calls

Das Output Gate ist ToolMeshs Inhaltskontrollschicht. JavaScript-Policies laufen vor (pre) und nach (post) jeder Tool-Ausführung und ermöglichen Eingabevalidierung, Ausgabefilterung und PII-Schwärzung.

Gate-Policies sind Top-Level-JavaScript-Dateien im policies/-Verzeichnis. Sie werden von goja ausgeführt, einer Go-nativen JavaScript-Engine, mit einem Timeout von 5 Sekunden pro Policy.

Jede Policy erhält eine einzige globale Variable ctx und läuft in einer von zwei Phasen:

  • pre — vor der Tool-Ausführung. ctx.params modifizieren, um den Aufruf umzuschreiben, oder throw, um ihn abzulehnen.
  • post — nach der Tool-Ausführung. ctx.response.content modifizieren, um die Antwort zu filtern.

Wirft das Skript einen String oder Error, wird der Aufruf abgelehnt. Läuft es ohne Throw durch, wird der Aufruf zugelassen.

FeldBeschreibung
ctx.phase"pre" oder "post"
ctx.toolTool-Name mit Backend-Präfix (z. B. github_merge_pull)
ctx.toolAccessDADL-Access-Tag: "read", "write", "admin", "dangerous" oder leer
ctx.paramsTool-Parameter (in pre mutierbar); bei REST-Tools gegen ihre DADL-Typen geprüft, siehe Was Policies sehen
ctx.response.contentTool-Antwort (in post mutierbar; nur in post befüllt)
ctx.user.userIDAuthentifizierte Nutzerkennung
ctx.user.callerIdCaller-Identität (z. B. cli, claude-desktop)
ctx.user.callerClass"trusted", "standard" oder "untrusted"
ctx.user.rolesArray mit Nutzerrollen
ctx.kitsDie Koffer, die der Aufrufer ganz oder teilweise hält, mit Namen; ohne Koffer ein leeres Array
ctx.kitCoveredtrue, wenn einer davon das Tool abdeckt
ctx.rateLimitExceeded(n)Funktion — liefert true, wenn der Nutzer n Aufrufe/Stunde überschritten hat

Bei Tools von REST-Backends sind die Parameter in ctx.params schon gegen ihre deklarierten DADL-Typen geprüft, bevor eine Policy läuft; eine Policy sieht also, was die API erhält:

  • Ein Wert vom falschen Typ erreicht keine Policy. Der Aufruf wird vorher mit invalid_input abgewiesen, etwa ein Boolean als String "false".
  • Numerische Strings für Parameter vom Typ integer und number kommen als Zahlen an (aus "007" wird 7). Eine ganze Zahl über 2^53 bleibt ein String, damit sie exakt bleibt; numerische Vergleiche schreiben Sie deshalb als Number(ctx.params.x).
  • In der DADL deklarierte Defaults sind eingesetzt, sodass eine Policy sie auch dann sieht, wenn der Aufrufer den Parameter weggelassen hat.
  • Eine Zahl oder ein Boolean für einen Parameter vom Typ string kommt als genau der Text an, den die API erhält ("42" statt 42).
  • Geprüft werden nur Parameter der obersten Ebene. Werte in einem Objekt- oder Array-Parameter kommen so an, wie der Aufrufer sie geschickt hat.

Tools von MCP-Backends und Units werden nicht gegen eine Deklaration geprüft: Ihre Policies sehen die Argumente des Aufrufers, und genau diese erhält auch der MCP-Server. Verschachtelte api.*-Aufrufe in einem Composite durchlaufen die Pre-Execution-Phase ebenfalls.

policies/block-force-delete.js
if (ctx.phase === "pre" && ctx.params.force_delete === true) {
throw "force_delete ist per Policy gesperrt";
}
policies/redact-email.js
if (ctx.phase === "post" && ctx.response && ctx.response.content) {
for (var i = 0; i < ctx.response.content.length; i++) {
var block = ctx.response.content[i];
if (block && block.type === "text" && block.text) {
block.text = block.text.replace(
/[\w.-]+@[\w.-]+\.\w+/g,
"[REDACTED]"
);
}
}
}

Mutationen an ctx.response.content werden in die Live-Antwort zurückpropagiert — nachgelagerte Evaluatoren und der Executor sehen den geschwärzten Inhalt.

Viele AI-Coding-Agents hängen Co-Authored-By-Trailer an Commit-Nachrichten und PR-Beschreibungen. Eine Pre-Gate-Policy entfernt diese vor dem GitHub-API-Aufruf:

policies/strip-co-authored-by.js
if (ctx.phase === "pre") {
var coAuthorPattern = /^[Cc]o-[Aa]uthored-[Bb]y:.*$/gm;
function stripTrailer(text) {
if (!text) return text;
return text
.replace(coAuthorPattern, "")
.replace(/\n{3,}/g, "\n\n")
.replace(/\n+$/, "\n");
}
if (ctx.tool === "github_create_pull" || ctx.tool === "github_update_pull") {
if (ctx.params.body) {
ctx.params.body = stripTrailer(ctx.params.body);
}
}
if (ctx.tool === "github_merge_pull" && ctx.params.commit_message) {
ctx.params.commit_message = stripTrailer(ctx.params.commit_message);
}
if (ctx.tool === "github_create_git_commit" && ctx.params.message) {
ctx.params.message = stripTrailer(ctx.params.message);
}
}

Der AI-Agent merkt nichts davon, und keine Co-Authored-By-Zeile erreicht das Repository.

Read-only-Durchsetzung für untrusted Caller (pre)

Abschnitt betitelt „Read-only-Durchsetzung für untrusted Caller (pre)“
policies/untrusted-readonly.js
if (ctx.phase === "pre" &&
ctx.user.callerClass === "untrusted" &&
ctx.toolAccess !== "read") {
throw "CallerClass 'untrusted' darf nur Tools mit Access-Tag 'read' aufrufen";
}

Das setzt auf den DADL-access-Tag (read, write, admin, dangerous), der pro Tool deklariert wird — siehe DADL-Spezifikation.

Das ToolMesh-Repository liefert config/policies/examples/prod-access-by-caller-class.js mit: eine Pre-Execution-Policy, die einen Aufruf nur durchlässt, wenn die Klasse des Aufrufers (aus caller-classes.yaml) die DADL-Access-Klasse des Tools nutzen darf, und unbekannte Klassen sowie unklassifizierte Tools mit einer Begründung ablehnt, die Tool und Klasse nennt. Kopieren Sie die Datei neben Ihre Policies und passen Sie die Tabelle an ihrem Anfang an. discover_tools und toolmesh.describe() zeigen das Feld access eines Tools, ein Agent sieht also vor dem Aufruf, was seine Klasse nutzen darf. Wie jede Policy ohne die Direktive unten weicht sie einem Koffer, den der Aufrufer hält.

Ein Aufrufer kann einen Koffer halten, ein Bündel von Tools, das ein Mensch befristet freigegeben hat. Für einen Aufruf, den ein gehaltener Koffer abdeckt, überspringt ToolMesh jede Pre-Execution-Policy außer denen, die in den Kommentarzeilen am Dateianfang vor der ersten Codezeile deklarieren:

// toolmesh: enforce-with-kit
  • Ohne die Direktive weicht eine Policy einem Koffer. Das ist der Standard und die richtige Wahl für Regeln auf Tool-Ebene, etwa eine Read-Only-Haltung oder eine Caller-Klasse, die keine Schreib-Tools nutzen darf: Ein Approver hat für diesen Aufrufer und diesen Koffer entschieden.
  • Mit der Direktive wird eine Policy auch mit Koffer durchgesetzt: Sie läuft, ob ein Koffer das Tool abdeckt oder nicht. Nehmen Sie die Direktive für Parameterfilter und für Bedingungen, die einschränken, was ein Scope erlaubt, etwa kein Force-Push auf main oder kein Abschalten eines Geräts. Ein Koffer gibt die Tools frei, nicht jedes Argument.

Die Post-Execution-Phase führt jede Policy ohnehin aus, Maskieren und Feldfilter gelten also auch für Koffer-Halter. Das Startlog nennt die Wahl je Policy (loaded policy name=readonly_gate.js pre_gate_with_kit=skipped), und ein Aufruf, bei dem ein Koffer das Gate ersetzt hat, wird als kit replaces the pre-execution gate geloggt; sein Audit-Eintrag trägt kit_applied und gate_skipped. Von den mitgelieferten Beispielen tragen default.js, github-branch-protection.js und shelly_write_protection.js die Direktive. Denies in config/authz.yaml entscheiden, bevor eine Policy läuft, und gewinnen gegen jeden Koffer.

Policies sehen die Koffer über ctx.kits (die gehaltenen Koffer, mit Namen) und ctx.kitCovered (true, wenn einer davon das Tool abdeckt).

Das Gate erhält die CallerClass und ermöglicht abgestufte Policies:

CallerClassTypische Filterung
trustedNur Credentials
standardHochrisiko-PII + Credentials
untrustedAlle PII-Muster, nur Read-Tools

Policies können ein Sliding-Window-Rate-Limit pro Nutzer durchsetzen:

if (ctx.phase === "pre" && ctx.rateLimitExceeded(100)) {
throw "Rate Limit überschritten (100/Stunde)";
}
Terminal-Fenster
GATE_EVALUATORS=goja # goja-Evaluator aktivieren (Standard)
TOOLMESH_POLICIES_DIR=/app/policies # Das Policies-Verzeichnis; das mitgelieferte docker-compose.yml mountet ./config/policies dorthin

ToolMesh lädt die Policies beim Start: eine Zeile loaded policy je Datei, und eine Warnung für jedes Tool-Namens-Literal in einer Policy, das zu keinem registrierten Tool passt.

Die Enterprise-Erweiterung fügt einen LLM-basierten Gate-Evaluator hinzu, der Inhalte gegen Compliance-Regeln klassifiziert. Das ermöglicht Policies wie „Antworten mit Finanzberatung blockieren”, ohne Regex-Muster schreiben zu müssen.