verbatra mcp

Starte einen Model-Context-Protocol-Server über stdio: den Standard-Transport für lokale Prozesse, mit dem MCP-Clients (Claude Desktop, Claude Code, Cursor und andere) einen Tool-Server starten und mit ihm sprechen. Er gibt einem Agenten im Terminal oder ohne Oberfläche dieselben Fähigkeiten für Übersetzungsstatus, Glossar und Bearbeitung, die die Browser-Agent-Tools von Studio bereitstellen, ganz ohne Browser, Port oder ausgelieferte Single-Page-App.

Synopsis

verbatra mcp [flags]

@verbatra/mcp liefert außerdem sein eigenes Binary, sodass ein MCP-Client es direkt starten kann, ganz ohne die verbatra-CLI:

verbatra-mcp [flags]

Beide Formen nehmen dieselben drei Flags und starten denselben Server, aber die Hüllen darum unterscheiden sich:

• verbatra mcp lädt vor dem Start .env.local und danach .env aus dem Arbeitsverzeichnis; verbatra-mcp lädt keine der beiden, übergib einen API-Key also in der Umgebung, mit der der MCP-Client es startet.
• verbatra mcp lehnt ein unbekanntes Flag als Verwendungsfehler ab und endet mit 2; verbatra-mcp ignoriert unbekannte Flags.
• Ein Start- oder Konfigurationsfehler endet bei verbatra mcp mit 2 und bei verbatra-mcp mit 1.
• verbatra mcp wird bei einem zweiten Interrupt während des Herunterfahrens mit Exit-Code 130 zwangsbeendet; verbatra-mcp hat keinen solchen Pfad.

Flags

Fehlt --allow-spend, liest der Server stattdessen die Umgebungsvariable VERBATRA_MCP_ALLOW_SPEND: 1, true, yes oder on (Groß-/Kleinschreibung egal) zählt als an. Das CLI-Flag gewinnt immer gegenüber der Umgebungsvariable. Ohne beides werden translation.retranslateEntry und translation.translatePending überhaupt nicht bereitgestellt: Ein MCP-Client, der die Tools auflistet, sieht sie nie, und der Aufruf eines der beiden Namen schlägt als unbekanntes Tool fehl. Das ist eine Garantie pro Prozess, keine Prüfung pro Aufruf: Ein Tool hinter dem Spend-Gate ist strukturell nicht aufrufbar, statt beim Aufruf nur abgelehnt zu werden.

Einen MCP-Client konfigurieren

Richte deinen MCP-Client auf das verbatra-mcp-Binary aus. Für Claude Desktop fügst du das zu deiner claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "verbatra": {
      "command": "npx",
      "args": ["-y", "@verbatra/mcp", "--cwd", "/path/to/your/project"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Lass den env-Block und sein --allow-spend ganz weg für einen Server, der nur liest und nur lokal bearbeitet: project.snapshot, die Status- und Glossar-Tools sowie translation.editEntry rufen nie einen Provider auf und brauchen keinen Key. Füge --allow-spend zum args-Array hinzu, sobald du auch translation.retranslateEntry und translation.translatePending verfügbar haben willst, und setze die Umgebungsvariable für den API-Key, die dein konfigurierter Provider liest (siehe Provider).

Rufst du bereits alles über die verbatra-CLI auf, starte es stattdessen als Unterbefehl:

{
  "mcpServers": {
    "verbatra": {
      "command": "npx",
      "args": ["-y", "@verbatra/cli", "mcp", "--cwd", "/path/to/your/project"]
    }
  }
}

Tools

translation.retranslateEntry und translation.translatePending werden nur bereitgestellt, wenn der Server mit --allow-spend gestartet wurde. Der Input jedes Tools und, wo die Ergebnisform klein und geschlossen ist, auch der Output sind ein JSON-Schema, abgeleitet aus demselben zod-Schema, gegen das der Server den Aufruf validiert. Der Aufruf eines unbekannten Tool-Namens ist ein Fehler auf Protokollebene; der Aufruf eines bekannten Tools mit Input, der die Validierung nicht besteht, liefert ein Ergebnis, das das betroffene Feld nennt, sodass ein Agent den Fehler lesen und selbst korrigieren kann.

Die beiden Eintrags-Schreiber, translation.editEntry und translation.retranslateEntry, sind zusätzlich pro Tool, Locale und Key abgesichert: Während ein Aufruf für einen Eintrag noch läuft, wird ein zweiter Aufruf desselben Tools mit demselben locale und key weder eingereiht noch parallel ausgeführt. Er bekommt ein isError-Ergebnis, dessen Text sagt, dass bereits ein passender Aufruf läuft, damit zwei Agenten (oder ein Agent, der es erneut versucht) nicht über dasselbe Tool in ein Wettrennen um denselben Eintrag geraten. Aufrufe für andere Keys oder andere Locales laufen weiterhin parallel. translation.translatePending hat keine solche Sperre.

Inputs und Ergebnisse

• status.check, status.diff und key.integrity nehmen ein optionales locales-Array (mindestens ein Eintrag), das das Ergebnis auf diese Locales eingrenzt; key.integrity nimmt außerdem den zu prüfenden key.
• translation.editEntry nimmt locale, key und value, wobei value auf 20.000 Zeichen begrenzt ist.
• glossary.write nimmt { term, translation }, wobei term auf 200 Zeichen und translation auf 2.000 begrenzt ist; translation: null entfernt den Begriff. Es braucht ein dateibasiertes Glossar (das glossary der Konfiguration zeigt auf eine JSON-Datei); ein Inline-Glossar oder gar keines schlägt mit GLOSSARY_NOT_FILE_BACKED fehl.
• translation.editEntry und translation.retranslateEntry liefern { accepted, value, reason?, details? }. Ein abgelehnter Wert trägt reason, einen von placeholder, markup, icu, degenerate oder empty, und details, das benennt, was fehlgeschlagen ist; translation.retranslateEntry ergänzt ein akzeptiertes Ergebnis um reviewReasons: die Flags der Review-Heuristiken für den neuen Wert, leer, wenn keine angeschlagen hat.
• lock.state liefert exists und, wenn die Lock-Datei existiert, ihre version sowie pro Locale die Zahlen keyCount, missing, stale und upToDate.
• usage.summary liefert die usage des letzten Laufs und, wenn ein Token-Budget konfiguriert war, ein budget, dessen standing within, stopped-before-ceiling oder reached ist und dessen supported angibt, ob die gezählte Zahl vollständig aus dem vom Provider selbst gemeldeten Verbrauch stammt.

Die Inline-Markup-Prüfungen in key.integrity (markupMatches, markupDetails) und in translation.editEntry (der Grund markup), eine custom:-Format-ID in project.snapshot und budget.standing in usage.summary kamen mit diesem Release.

Secrets werden geschwärzt

Jedes Tool-Ergebnis und jede Log-Zeile durchläuft dasselbe Schwärzen von Secrets, das auch Studio verwendet: Ein Wert, der wie ein Provider-API-Key aussieht, oder der exakte aktuelle Wert einer konfigurierten Provider-Umgebungsvariable, wird durch [REDACTED] ersetzt, bevor er den Client oder stderr überhaupt erreicht. glossary.get und glossary.write melden zudem, welche Begriffe geschwärzt wurden, sodass du einen geschwärzten Platzhalter vom echten Text unterscheiden kannst und ihn nicht versehentlich zurückschreibst.

stdout ist der Protokollkanal

Der stdio-Transport von MCP nutzt stdout ausschließlich für Protokollnachrichten. verbatra mcp und verbatra-mcp geben niemals ein Banner, eine Log-Zeile oder irgendetwas anderes auf stdout aus; jedes Log und jede Diagnose geht stattdessen auf stderr. Der Server lädt die Konfiguration, bevor er den Transport verbindet; ein Konfigurationsfehler wird also sofort auf stderr geschrieben, und der Prozess endet, ohne je das Protokoll zu sprechen. Sobald er läuft, gehen auch die Diagnosen pro Aufruf (ein fehlgeschlagener Aufruf, ein abgelehnter Aufruf, weil bereits ein passender läuft, ein unbekanntes Tool) auf stderr.

Installation

@verbatra/mcp ist ein eigenes Paket, das über einen dynamischen Import erreicht wird, damit der Rest der CLI auch ohne es funktioniert. Ist es nicht installiert, beendet sich verbatra mcp mit 2 und gibt aus:

Verbatra's MCP server requires @verbatra/mcp. Install it with: pnpm add -D @verbatra/mcp

verbatra-mcp direkt aufzurufen, braucht überhaupt keine CLI: Installiere @verbatra/mcp allein, oder lass npx es wie oben gezeigt bei Bedarf holen.

Beispiele

# start the MCP server with only local, non-spending tools
verbatra mcp

# also advertise the provider-calling tools
verbatra mcp --allow-spend

# resolve a project outside the current directory
verbatra mcp --cwd /path/to/project --config verbatra.config.ts

Exit-Codes

Das sind die Exit-Codes von verbatra mcp; das eigenständige verbatra-mcp weicht davon ab, wie oben in der Übersicht beschrieben.

Siehe auch

• verbatra studio und Studio mit einem Browser-Agenten bedienen behandeln die Browser-basierte Agent-Oberfläche, die dieser Server ergänzt.
• Provider dokumentiert, aus welcher Umgebungsvariable jeder Provider seinen API-Key liest.
• verbatra check und verbatra diff sind dieselben Berechnungen, die status.check und status.diff bereitstellen.