verbatra

@verbatra/mcp

ブラウザーを使わずに、verbatraの翻訳ステータス、用語集、編集機能をあらゆるMCPクライアント向けのツールとして公開する、Stdio MCP サーバーです。

ドキュメント | クライアントの接続 | 変更履歴 | 課題

説明

@verbatra/mcp は、MCPクライアントがツールサーバーを起動して通信する際に使う標準的なローカルプロセス用トランスポートであるstdio経由で、Model Context Protocol サーバーを起動します。ターミナル上で動作するエージェントやヘッドレスエージェントに、Verbatra Studioがブラウザーで提供するものと同じ翻訳ステータス、用語集、編集機能を提供します。ブラウザー、ポート、配信されるシングルページアプリは必要ありません。これは@verbatra/cliと同様、@verbatra/sdkを基盤とする薄いインターフェースです。

インストール

ほとんどのMCPクライアントはサーバーを自動的に起動するため、ローカルへのインストールは不要です。クライアントでnpx -y @verbatra/mcpを指定すれば、npxが必要に応じて取得します。代わりに、プロジェクトに固定するには次のようにします。

npm install --save-dev @verbatra/mcp

Node.js ^22.18.0 || >=24 が必要です。@verbatra/cliと@verbatra/mcpの両方をインストールすると、verbatra mcpからもサーバーにアクセスできます。

MCP クライアントの設定

クライアントの接続先を、@verbatra/mcp パッケージが提供する verbatra-mcp バイナリに指定します（以下の例では npx を通じて実行します）。以下の形式はほとんどのクライアントで使用されます。エディターまたはデスクトップクライアントの場合は、そのクライアントの MCP サーバー設定ファイルに記述してください。

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

Claude Code では、npx @verbatra/cli init --agent（または claude mcp add --transport stdio --scope project verbatra -- npx -y @verbatra/mcp）を実行すると、同等のエントリがコミット対象の .mcp.json に書き込まれます。verbatra plugin には、独自のサーバーとともにエージェントスキルが含まれているため、.mcp.json のエントリと併用せず、どちらか一方を使用してください。両方を使うと、サーバーが二重に登録されます。VS Code（GitHub Copilot のエージェントモード）では .vscode/mcp.json が読み込まれます。このファイルのトップレベルキーは mcpServers ではなく servers です。各クライアントのファイル、キー、作業ディレクトリの扱いについては、MCP クライアントの接続をご覧ください。

この設定では読み取りとローカル編集のみが可能です。プロバイダーは呼び出されず、API キーも必要ありません。プロバイダーを呼び出す2つのツールも使う場合は、args に --allow-spend を追加し、設定したプロバイダーがキーを読み取る環境変数も設定してください。--config <path> を指定すると、設定ファイルを検索せず、指定したファイルを読み込みます。VERBATRA_MCP_ALLOW_SPEND はこのフラグに相当する環境変数ですが、フラグが常に優先されます。

ツール

サーバーが通知する順に、すべてのツールを記載しています。

ツール	機能
project.snapshot	解決済みのプロジェクト設定を読み取ります。使用可能な設定が読み込まれているか（configured）、ロケール、フォーマット、パスパターン、プロバイダー ID、設定の取得元、用語集が設定されているかを確認します
project.doctor	プロジェクトのセットアップ（設定、フォーマット、プロバイダー、名前で指定された API キー変数、ネットワークポリシー、ソースファイル）を確認し、使用可能な設定の有無にかかわらず、チェックごとに失敗した場合の fix を取得します
status.check	対象ロケールごとに、不足、古い状態、最新の各キーの数と、ロケールが同期されているかを確認します
status.diff	対象ロケールごとに、次回の翻訳実行で追加、再翻訳、または孤立化されるキーを正確に確認します
glossary.get	すべての用語と全ロケールでの翻訳、ロケールごとの翻訳、使用禁止の訳語、大文字と小文字の区別、注記、品詞、翻訳せずに保持する用語、用語集のバージョンと取得元を取得します。locale を指定すると、そのロケールで適用される用語も取得します
glossary.write	用語を1つ変更します（全ロケールまたは1つの locale の翻訳、forbidden の訳語、note、partOfSpeech、caseSensitive、または doNotTranslate）。その後、用語集を返します
lock.state	ロックファイルのバージョンとロケールごとのキー数を返します。初回実行前は exists: false を返します
history.list	ロケールファイルを変更した最近の git コミットについて、ハッシュ、作成者名（メールアドレスは含みません）、日付、件名、変更されたパスを取得します
key.integrity	1つのキーについて、ロックファイルのベースラインと比較したプレースホルダー、インラインマークアップ、ICU の差異をロケールごとに確認します
locale.integrity	現在、プレースホルダー、マークアップ、または ICU のチェックに失敗しているすべての翻訳を対象ロケールごとに確認します
key.value	1つのキーの現在のソーステキスト、ソースファイルの説明、翻訳済みの場合は対象ロケールでの現在のテキストと作成者を取得します
key.context	key.value の戻り値に加えて、該当する用語集の用語、キーの maxLength、省略可能な draft のチェック結果を取得します
locale.values	keys または query で絞り込んだ多数のキーのソーステキストと対象テキストを、最大1,000件のページに分けて取得します
translation.editEntry	1つのロケールの1つのキーに手動翻訳を書き込みます。整合性チェックに合格した場合のみ受け付けられます
translation.estimate	プロバイダーを呼び出さずに、translation.translatePending で送信される内容と費用を見積もります。ロケールの一部を任意で指定できます
translation.retranslateEntry	設定済みのプロバイダーに、1つのロケールの1つのキーの新しい翻訳を依頼します
translation.translatePending	設定済みの対象ロケールすべて、または指定したロケールの一部で、不足または古い状態のキーをすべて、任意の maxTokens 上限内で1回の実行で翻訳します
review.queue	まだ承認されていない、機械生成の翻訳をすべて、コミット済みのファイルから読み取り、前回の実行時のフラグとともに取得します
report.provenance	ロケールごとに、各由来区分に該当する値の数を取得します。includeEntries を指定すると、キーをページ分けして取得します
review.approve	ユーザーの指示に基づき、指定された人物が1つのキーの現在の翻訳を承認したことを記録します
review.reject	ユーザーの指示に基づき、指定された人物が1つのキーの現在の翻訳を却下したことを記録し、置き換えられるようにその翻訳を削除します
usage.summary	前回の実行で残されたトークン使用量と予算状況を取得します

セキュリティと支出

• 支出はオプトインです。 translation.retranslateEntry と translation.translatePending は、プロバイダーを呼び出す2つのツールです。サーバーを --allow-spend または VERBATRA_MCP_ALLOW_SPEND を指定して起動した場合にのみ公開されます。どちらも指定しない場合、クライアントに表示されず、名前を指定して呼び出すと不明なツールとして失敗します。provider: { id: "none" } を設定した構成では、--allow-spend を指定しても、これらのツールは表示されません。
• 値をローカルに留められます。 --redact-values（または VERBATRA_MCP_REDACT_VALUES）を指定すると、結果内のすべてのソーステキスト、翻訳、説明、用語集の用語が [redacted length=12 hash=3f9a0c1d2e4b5a6c] のようなマーカーに置き換えられ、レビュアー名と作成者名は除外されます。キー名、件数、ステータス、整合性の判定結果はそのまま残ります。その場合、review.approve と review.reject では expectedHash としてマーカーのハッシュのみを受け付け、locale.values は query を拒否し、key.context は draft を拒否します。これにより値が結果に含まれなくなりますが、意図的に探ろうとするエージェントを止めるものではなく、プロバイダーに送信される内容も変わりません。
• シークレットはマスキングされます。 すべての結果とログ行には、クライアントや stderr に送られる前に必ずマスキング処理が行われるため、プロバイダーの API キーの形式に一致する値や、設定済みのプロバイダー変数の値と完全に一致する値は [REDACTED] に置き換えられます。
• 標準出力にはプロトコルのみが出力されます。 MCP メッセージ以外は標準出力に書き込まれず、すべてのログ行と診断行は stderr に送られます。
• 構成を変更しても再起動は不要です。 サーバーは使用可能な構成がなくても起動し（project.snapshot は configured: false を報告し、project.doctor は修正が必要な箇所を示します）、各呼び出しの前に構成と用語集ファイルを再読み込みします。--allow-spend は起動時に固定されるため、構成を変更しても許可範囲が広がることはありません。

各ツールの入力と、形状が固定されたすべてのツール出力は、サーバーが呼び出しを検証する際に使用するものと同じ zod スキーマから生成された JSON Schema です。すべてのツールリファレンス、終了コードの仕様、実例については、verbatra mcp docs を参照してください。

ドキュメント

• verbatra mcp リファレンス
• MCP クライアントを接続する
• エージェントのレシピ

関連パッケージ

• @verbatra/sdk：このサーバーの基盤となるエンジンです。
• @verbatra/cli：verbatra mcp を含む verbatra コマンドです。
• @verbatra/studio：同じ機能をブラウザのダッシュボードで利用できます。

コントリビューション

CONTRIBUTING.md を参照してください。

ライセンス

MIT (c) Mario Kreitz