リファレンス / CLI
機械翻訳されたページ
verbatra mcp
verbatra のツールをあらゆる MCP クライアントに公開する stdio MCP サーバーを起動します。有料のプロバイダーを呼び出すツールは、デフォルトで一覧に出ません。
stdio 経由で Model Context Protocol サーバーを起動します。stdio は、MCP クライアントがツールサーバーを起動するときに使うトランスポートです。プロトコルのリビジョン 2024-10-07 から 2026-07-28 に対応します。HTTP トランスポートはありません。HTTP にすると、書き込みツールと課金ツールが公開されてしまうためです。
書式
verbatra mcp [flags]
verbatra-mcp [flags]verbatra-mcpは@verbatra/mcpが提供するバイナリで、クライアントが CLI なしでサーバーを起動できます。-q/--quietを除いて同じオプションを受け付け、同じサーバーを起動しますが、.envファイルは読み込まず、--versionでは@verbatra/mcpのバージョンを出力します。- どちらも、未知のオプション、オプションの値の欠落、余分な引数があると終了コード
2で終了します。verbatra-mcpでこの動作と-h、-Vを使うには、@verbatra/mcp0.3.0 以上が必要です。
例
# 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
# run the standalone server without the CLI
npx -y @verbatra/mcp --cwd /path/to/projectオプション
| オプション | 引数 | デフォルト | 説明 |
|---|---|---|---|
--allow-spend | なし | VERBATRA_、なければオフ | 翻訳プロバイダーを呼び出す 2 つのツールを公開する。課金ツールを参照 |
--redact-values | なし | VERBATRA_、なければオフ | ツールの結果に含まれる訳文の値をすべてマーカーに置き換える。秘匿化された値を参照 |
グローバルオプションの --cwd と --config も使えます。stdout がプロトコルのチャネルなので、--json は使えません。--cwd がない場合、プロジェクトディレクトリは CLAUDE_ から決まることがあります。プロジェクトディレクトリを参照してください。
動作
プロジェクトディレクトリ
--cwd がなく、CLAUDE_ が既存のディレクトリを指している場合、サーバーはそれをプロジェクトディレクトリとして使います。このとき verbatra mcp は、そのディレクトリから環境ファイルを読み込みます。環境ファイルの中だけで設定した CLAUDE_ は無視されます。
設定ファイルの探索はそこから始まり、見つかった設定ファイルのあるディレクトリが、ツールのパスの基準になるプロジェクトルートです。
課金ツール
translation.retranslateEntry と translation.translatePending が公開されるのは、--allow-spend がある場合、またはオプションがなく VERBATRA_ が 1、true、yes、on のいずれかに設定されている場合だけです(大文字と小文字は区別せず、前後の空白は無視します)。オプションが変数より優先されます。verbatra mcp は先に .env.local と .env を読み込むため、変数はそこに置けます。verbatra-mcp は、自身の環境からしか読み取りません。
それ以外の場合、この 2 つは一覧に出ず、呼び出すと未知のツールとして失敗します。provider: { id: "none" } の設定では、--allow-spend があっても一覧に出ません。ほかのツールはすべてプロバイダーを呼び出さず、API キーも不要です。サーバーに API キーを渡すのは、課金を有効にするときだけにしてください。
エージェントへの指示
サーバーは、ハンドシェイクに固定の instructions を返します。多くのクライアントは、これを最初にモデルへ渡します。この指示は、呼び出しの順序(先に読み取りと差分、費用をかける前に見積もりと明示的な了承)を定め、レビューの判断と人の作業を人に任せ、すべての文字列をデータとして扱い、[REDACTED] の値を書き戻さないようにします。
ツール
| ツール | 機能 | 読み取り専用 | プロバイダーを呼び出す |
|---|---|---|---|
project.snapshot | 解決された設定:configured、configSource、ロケール、フォーマット、files.pattern、プロバイダー、用語集、humanEdits、prune、valuesRedacted | はい | いいえ |
project.doctor | すべての構成チェックと、その status、detail、失敗した場合は fix | はい | いいえ |
status.check | ロケールごとの、欠落しているキー、古くなったキー、最新のキーの数 | はい | いいえ |
status.diff | ロケールごとの、追加される、再翻訳される、孤立しているキーの一覧 | はい | いいえ |
glossary.get | すべての用語集の用語と、その訳語、禁止された訳、コンテキスト(シークレットは秘匿化) | はい | いいえ |
glossary.write | 用語集の用語を 1 つ変更する:訳語、ロケールごとのデータ、コンテキスト、翻訳しないかどうか | いいえ | いいえ |
lock.state | ロックファイルのバージョンと、ターゲットロケールごとのキー数と、欠落しているキー、古くなったキー、最新のキーの数 | はい | いいえ |
history.list | ロケールファイルに触れた最近の git コミットと、作成者、日付、件名、パス | はい | いいえ |
history.keyRevisions | ロケールにおける 1 つのキーのリビジョンと単語単位の差分 新機能 | はい | いいえ |
key.integrity | ロケールごとの、ロックファイルのベースラインに対する 1 つのキーのプレースホルダー、マークアップ、ICU 構文、ICU の分岐のドリフト | はい | いいえ |
locale.integrity | プレースホルダー、マークアップ、ICU のチェックに現在失敗しているすべての訳文(ロケールごと) | はい | いいえ |
key.value | 1 つのキーの現在のソーステキストとターゲットテキスト、来歴、翻訳者向けのコンテキスト | はい | いいえ |
key.context | key.value が返す内容に加えて、適用される用語集の用語、maxLength、任意の draft のチェック | はい | いいえ |
locale.values | 多数のキーのソーステキストとターゲットテキスト(keys または query で絞り込み、ページ単位) | はい | いいえ |
translation.editEntry | 1 つのロケールの 1 つのキーに、手動の訳文を書き込む(整合性チェックを通す) | いいえ | いいえ |
translation.estimate | translation.translatePending が送る内容と費用(translate --estimate と同じ) | はい | いいえ |
translation.retranslateEntry | 1 つのロケールの 1 つのキーを、設定されたプロバイダーに再翻訳させる | いいえ | はい |
translation.translatePending | 欠落または古くなったキーをすべて翻訳する(locales で一部のロケールに絞り込み、maxTokens の上限内で実行することも可能) | いいえ | はい |
review.queue | まだ誰も承認していない機械翻訳の値すべてと、直近の実行のフラグ | はい | いいえ |
report.provenance | verbatra report provenance と同じ、ロケールごとの来歴の件数と、要求に応じたページ分割されたキー | はい | いいえ |
review.approve | ユーザーの指示に基づき、名前を指定した人が 1 つのキーの現在の訳文を承認したことを記録する | いいえ | いいえ |
review.reject | ユーザーの指示に基づき、名前を指定した人が 1 つのキーの訳文を却下したことを記録し、訳文を削除する | いいえ | いいえ |
usage.summary | 直近の実行のトークン使用量と予算の状況 | はい | いいえ |
usage.history | 最近の実行、費用、対応率 新機能 | はい | いいえ |
- 同時に 1 つの呼び出しだけ:同じエントリに対する同じツールの 2 回目の呼び出し(
translation.editEntry、translation.retranslateEntry)や、2 回目のtranslation.translatePendingの実行は、最初の呼び出しが実行されている間、isErrorで拒否されます。 - 人の作業:
translation.retranslateEntryは、固定されたキーをKEY_で拒否し、PINNED humanEdits: "overwrite"でなければ、人が書いた値をKEY_で拒否します。PROTECTED translation.editEntryは固定されたキーを拒否します。translation.translatePendingは、そのようなキーをprotectedの下に一覧表示します。人手翻訳を保護するを参照してください。 - 来歴:
translation.editEntryが書いた値は、出どころagentになります。review.queueは Studio に表示されるのと同じキューで、承認されていないmachine、memory、fuzzy、agentの値がすべて入ります。レビューの判断を参照してください。 - レビューの判断:
review.approveとreview.rejectは、locale、key、expectedValueまたはexpectedHash(値が変わっている場合はREVIEW_で拒否されます)、VALUE_ CHANGED reviewerの名前を受け取ります。承認はverbatra check --require-reviewedの対象になります。
入力と結果
status.check、status.diff、key.integrityは、任意のlocales配列を受け取ります。key.integrityはkeyも受け取ります。key.integrityは{ locales: [{ locale, entries }] }を返します。各エントリにはmatches、missing、extra、icuValid、markupMatchesとその詳細が入ります。translation.editEntryはlocale、key、最大 20,000 文字のvalueを受け取り、{ accepted, value, reason?, details? }を返します。translation.retranslateEntryも同じものを返し、さらにreviewReasons?とusage?が加わります。reasonはplaceholder、markup、icu、degenerate、emptyのいずれかです。glossary.writeにはファイルに保存された用語集が必要で、そうでなければGLOSSARY_で失敗します。大文字と小文字だけが違う用語は、保存済みの用語を更新します。NOT_ FILE_ BACKED
その他の入力と結果
translation.estimate、locale.integrity、locale.values、report.provenanceも同じ任意のlocales配列を受け取ります。key.integrityは、不明なキーに対してUNKNOWN_で失敗します。KEY key.integrityの各エントリには、icuArmsMatchとその詳細も入ります。glossary.getは任意のlocaleを受け取り、そのロケールが従う用語を示すeffectiveを加えます。key.value、lock.state、status.check、status.diffには来歴が含まれます。verbatra.provenance.jsonを読み取れない場合は省かれます。locale.valuesとreport.provenanceは、エントリをソースのキーの順にページ分割します。limit(デフォルトは 200、最大 1,000)と、前のページのnextCursorをcursorとして渡します。ページに一覧表示されるのは、そのページがエントリを持つロケールだけで、古いカーソルは不正な入力として失敗します。locale.valuesはkeysまたは大文字と小文字を区別しないqueryを受け取り、Studio のキーのマップではなく、エントリの配列を返します。report.provenanceは常に完全な件数を返し、includeEntriesを付けるとキーが加わります(bucketsで一部の分類に絞り込めます)。history.listはlimit(デフォルトは 50、最大 200)を受け取ります。available: falseの場合、reasonはgit-missing、not-a-repository、bare-repository、dubious-ownership、timeout、output-too-large、unsafe-config、git-too-oldのいずれかです。usage.historyは、新しい順に何件の実行を返すかを示すlimit(デフォルトは 50、最大 200)を受け取ります 新機能。history.keyRevisionsは、locale、key(最大 1,024 文字)、調べるコミット数を示すlimit(デフォルトは 50、最大 200)を受け取ります 新機能。usage.summaryが読むのは直近の実行だけです(以前の実行はusage.historyが一覧表示します)。その実行が使用量を報告しなかった場合はusageを省き、予算のフィールドはmaxTokensの予算がある場合にだけ含めます。budget.supported: falseは、リクエストが使用量を報告しなかったか、失敗したことを意味します。その場合のtokensUsedには、使用量が 0 または未報告だった各リクエストについて、verbatra 自身の予測値が加わるため、プロバイダーが課金した値ではありません。実行に、失敗した、または途中で止まったロケールがあった場合はincomplete: { failed, partial }も含まれるため、使用量が少ないことを、成功した実行と読み違えることはありません 新機能。- 書き込みツールは、任意の
lockTimeoutMs(0から600000、デフォルトは30000)を受け取ります。これは、保持されている書き込みロックを待つ時間で、過ぎると何も書き込まずにLOCK_で失敗します。CONTENDED - 入力と出力は JSON Schema です。不正な入力には、フィールドを示す結果が返ります。結果が
outputSchemaに一致しない場合は、OUTPUT_で失敗します。書き込みツールでは、変更はすでに適用されているため、再試行しないでください。SCHEMA_ MISMATCH - 失敗した呼び出しのテキストは、
UNKNOWN_のようにエラーコードで始まり、エラーに次の手順がある場合はKEY: ... Next step: ...の行で終わります。これは CLI のhintと同じテキストです。
見積もってから費用をかける
translation.estimate は常に一覧に出ます。translation.translatePending は、任意の locales(設定にないロケールは、費用が発生する前に UNKNOWN_ で失敗します)と、設定の上限を厳しくすることしかできない maxTokens を受け取ります。実行前に費用を見積もるを参照してください。
進捗
translation.translatePending の呼び出しに progressToken が付いていると、verbatra はバッチが完了するたびに notifications/progress を送ります。progress は完了したバッチ数、total は計画されたロケールごとに増え、message にロケールとバッチ(de: batch 3/7)が示されます。送信は 250 ミリ秒に 1 回までで、最後に 1 回送られます。課金を伴う呼び出しをキャンセルする(notifications/cancelled)と、結果も以降の進捗もなく停止します。translation.translatePending は、届いた分を保持し、残りは未処理のままです。
設定がない場合
サーバーは、それでも起動します。このとき project.snapshot は、configProblem と nextStep を付けて configured: false を返し、project.doctor は対処を報告し、ほかのツールはすべて設定のエラーで拒否します。stderr に理由が出力されます。
Running without a usable project config: CONFIG_NOT_FOUND: No verbatra configuration found. ...
verbatra MCP server running on stdio (project ., spend tools off)
No usable verbatra config: project.snapshot and project.doctor work, every other tool refuses until one loads.
set it up: npx @verbatra/cli init in the project, or fix the config project.doctor names
no restart needed: the server loads the config on the next call once it is valid設定の変更後
サーバーは、呼び出しのたびに、設定ファイル、探索で試すファイル、または用語集ファイルが変わっていれば、設定を再読み込みします。設定がインポートしているモジュールは監視されません。--allow-spend は 1 回だけ読み取られるため、変更で課金ツールを隠すことはできますが、オプションなしで一覧に出すことはできません。ツールの一覧が変わると、サーバーは notifications/tools/list_ を送ります。再読み込みでプロジェクトルートが移ると、verbatra mcp はそのルートの環境ファイルを読み込み、verbatra: project root is now <root> と出力します。この行は --quiet で非表示になります。
シークレットの秘匿化
シークレットは、Studio と同じく、すべての結果とログの行から秘匿化されます。API キーの形をした値や、設定された API キーの変数の値は [REDACTED] になり、用語集のツールは秘匿化された用語を示します。訳文の値を隠すには、--redact-values を使います。
秘匿化された値
--redact-values を付けた場合、または VERBATRA_ に VERBATRA_ が受け付ける値を設定した場合、結果のソーステキスト、訳文、説明、用語集の用語は、マーカー [redacted length=12 hash=3f9a0c1d2e4b5a6c] に置き換えられます。レビュー担当者と作成者の名前、単語単位の差分、history.keyRevisions の件名は含まれません。同じ値は、サーバーが止まるまで同じハッシュを共有します。値を含みうるエラーは、コードと次の手順を残し、メッセージはマーカーになります。キー名、件数、出どころ、整合性の判定、コミットの件名、パスは残ります。review.approve と review.reject は、マーカーのハッシュだけを expectedHash として受け取ります。glossary.write は件数で応答します。locale.values は query を拒否し、key.context は draft を拒否します。プロバイダーには、引き続きテキストが送られます。エージェントが、用語集の書き込みや key.context の用語集のヒットを使って、意図的に探りを入れることまでは防げません。
stdout と stderr
stdout に出力されるのは MCP のプロトコルメッセージだけで、ログはすべて stderr に出力されます。接続すると、verbatra mcp は準備完了の行を出力し、停止するときにも 1 行出力します。
verbatra MCP server running on stdio (project ., spend tools off)
verbatra MCP server stopped (client closed stdin)ターミナルでは、クライアントが起動する前提のものだという案内も出力されます。--quiet はこれらの行を非表示にしますが、設定がない理由は非表示にしません。
インストール
@verbatra/mcp は別のパッケージで、CLI が必要に応じて読み込みます。ない場合、verbatra mcp は次のメッセージを出力して終了コード 2 で終了します。
Verbatra's MCP server requires @verbatra/mcp. Run it without the CLI with: npx -y @verbatra/mcp, or install it alongside the CLI with: npm install --save-dev @verbatra/mcp各リリースは、公式の MCP Registry にも io.github.verbatra/verbatra として登録されています。
終了コード
| 終了コード | 意味 |
|---|---|
0 | 1 回の割り込み、またはクライアントによる stdin のクローズで、正常に停止した |
1 | シャットダウン中にサーバーを閉じられなかった |
2 | 起動できなかった。--config のファイルがない、@verbatra/mcp がない(--redact-values では古すぎる場合も含む)、または使い方の誤り |
130 | シャットダウン中の 2 回目の割り込みで強制停止された |
停止すると、ロケールの書き込みロックはすべて解放されます。verbatra-mcp は、起動エラーで終了コード 1 を返し、SIGTERM のあとに強制停止された場合は 143 を返します(143 を返すには @verbatra/mcp 0.3.0 以上が必要です)。終了コードの仕様を参照してください。
関連項目
- MCP クライアントを接続するは、stdio クライアントのセットアップを説明します。
- ブラウザーエージェントで Studio を操作する:このサーバーのツールに対応する、ブラウザー側の機能です。
verbatra checkとverbatra diffは、status.checkとstatus.diffを支えています。