verbatra

@verbatra/mcp

Stdio MCP server exposing verbatra's translation status, glossary, and editing capabilities as tools for any MCP client, without a browser.

Documentation | Connect a client | Changelog | Issues

Description

@verbatra/mcp starts a Model Context Protocol server over stdio, the standard local-process transport an MCP client uses to launch and talk to a tool server. It gives a terminal-hosted or headless agent the same translation-status, glossary, and editing capabilities Verbatra Studio exposes in the browser, without a browser, a port, or a served single-page app. It is a thin, SDK-backed surface over @verbatra/sdk, the same way @verbatra/cli is.

Installation

Most MCP clients spawn the server for you and need no local install at all: point the client at npx -y @verbatra/mcp and npx fetches it on demand. To pin it in your project instead:

npm install --save-dev @verbatra/mcp

Needs Node.js ^22.18.0 || >=24. The server is also reachable through verbatra mcp once both @verbatra/cli and @verbatra/mcp are installed.

Configuring an MCP client

Point your client at the verbatra-mcp binary, which the @verbatra/mcp package provides (the example runs it through npx). The shape below is the one most clients use; for an editor or desktop client, put it in that client's MCP server configuration file.

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

In Claude Code, npx @verbatra/cli init --agent (or claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp) writes an equivalent entry to a committed .mcp.json. The verbatra plugin bundles the agent skills with its own copy of this server, so use it instead of the .mcp.json entry, never both: together they register the server twice. VS Code (GitHub Copilot's agent mode) reads .vscode/mcp.json, whose top-level key is servers rather than mcpServers. The exact file, key, and working-directory handling for every client is in Connect an MCP client.

That configuration is read-only plus local editing: no provider is called and no API key is needed. Add --allow-spend to args, and the environment variable your configured provider reads its key from, once you also want the two provider-calling tools. --config <path> loads a specific config file instead of searching for one, and VERBATRA_MCP_ALLOW_SPEND is the environment equivalent of the flag, which the flag always wins over.

Tools

Every tool, listed in the order the server advertises them.

Tool	What it does
project.snapshot	Read the resolved project configuration: whether a usable config is loaded (configured), locales, format, path pattern, provider id, where the config came from, whether a glossary is configured
project.doctor	Check the project setup (config, format, provider, API key variable by name, network policy, source file) and get a fix for every failed check, with or without a usable config
status.check	Per target locale, how many keys are missing, stale, or up to date, and whether the locale is in sync
status.diff	Per target locale, the exact keys the next translate run would add, re-translate, or orphan
glossary.get	Every glossary term with its translation for all locales, per-locale translations, forbidden renderings, case sensitivity, note and part of speech, the terms kept untranslated, the glossary version and where it comes from; with locale, also the terms that locale is held to
glossary.write	Change one glossary term (a translation for all locales or one locale, forbidden renderings, note, partOfSpeech, caseSensitive, or doNotTranslate) and return the glossary afterward
lock.state	The lock file's version and its per-locale key counts, or exists: false before the first run
history.list	Recent git commits that touched a locale file, with hash, author name (never the email), date, subject and touched paths
key.integrity	One key's placeholder, inline markup, and ICU drift against the lock-file baseline, per locale
locale.integrity	Every translation that fails the placeholder, markup or ICU checks right now, per target locale
key.value	One key's current source text, its source file description, and, if translated, its current text in one target locale with who wrote it
key.context	What key.value returns plus the glossary terms that apply, the key's maxLength, and a check of an optional draft
locale.values	Source and target text of many keys, filtered by keys or a query, in pages of up to 1,000 entries
translation.editEntry	Write a manual translation for one key in one locale, accepted only if it passes the integrity gate
translation.estimate	Estimate what translation.translatePending would send and cost, optionally for a subset of locales, without calling a provider
translation.retranslateEntry	Ask the configured provider for a fresh translation of one key in one locale
translation.translatePending	Translate every missing or stale key across the configured target locales, or a named subset, in one run, within an optional maxTokens ceiling
review.queue	Every machine-written translation nobody has approved yet, read from the committed files, with the last run's flags
report.provenance	Per locale, how many values fall into each provenance bucket; with includeEntries, the keys, paged
review.approve	Record, on the user's instruction, that a named person approves one key's current translation
review.reject	Record, on the user's instruction, that a named person rejects one key's current translation, removing it so it gets replaced
usage.summary	Token usage and budget status left behind by the last run

Security and spend

• Spend is opt-in. translation.retranslateEntry and translation.translatePending are the two tools that call a provider. They are advertised only when the server is started with --allow-spend or VERBATRA_MCP_ALLOW_SPEND; without either, a client never sees them and calling one by name fails as an unknown tool. A config with provider: { id: "none" } never lists them, even with --allow-spend.
• Values can stay home. --redact-values (or VERBATRA_MCP_REDACT_VALUES) replaces every source text, translation, description, and glossary term in a result with a marker such as [redacted length=12 hash=3f9a0c1d2e4b5a6c], and leaves out reviewer and author names. Key names, counts, statuses, and integrity verdicts stay. review.approve and review.reject then take only the marker's hash as expectedHash, locale.values refuses query, and key.context refuses draft. This keeps values out of results; it does not stop an agent that probes on purpose, and what a provider receives does not change.
• Secrets are scrubbed. Every result and log line passes through a redaction pass first, so a value shaped like a provider API key, or the exact value of a configured provider variable, becomes [REDACTED] before it reaches the client or stderr.
• Stdout is protocol only. Nothing but MCP messages is written to stdout; every log and diagnostic line goes to stderr.
• Config changes need no restart. The server starts without a usable config (project.snapshot reports configured: false, project.doctor says what to fix) and reloads the config and its glossary file before each call. --allow-spend is fixed at startup, and a config change never widens it.

Every tool's input, and every closed-shape tool output, is a JSON Schema derived from the same zod schema the server validates the call against. See the verbatra mcp docs for the full tool reference, the exit-code contract, and worked examples.

Documentation

• verbatra mcp reference
• Connect an MCP client
• Agent recipes

Related packages

• @verbatra/sdk: the engine this server is a thin surface over.
• @verbatra/cli: the verbatra command, including verbatra mcp.
• @verbatra/studio: the same capabilities in a browser dashboard.

Contributing

See CONTRIBUTING.md.

License

MIT (c) Mario Kreitz