本文へスキップ
本文へスキップ

ドキュメント / ガイド

機械翻訳されたページ

このページは自動翻訳のため、誤りや不自然な表現が含まれている可能性があります。正式な内容は英語版です。英語の原文を読む。

ブラウザーエージェントで Studio を操作する

Verbatra Studio のレビュー操作を WebMCP ツールとして登録し、ブラウザーの AI エージェントが開いている認証済みのダッシュボードのタブを操作できるようにします。

Gemini や Claude in Chrome などのブラウザーの AI エージェントに、開いている Studio のタブでドリフトの確認、レビューキューの処理、エントリの修正をさせる手順です。プロジェクトのセットアップやリモートアクセスには使えません。

必要なもの:

  • プロジェクトで起動している Studio(Studio でレビューする)
  • Chrome 149 以上で chrome://flags/#enable-webmcp-testing を有効にしたもの、またはネイティブの WebMCP に対応したブラウザー(ヘッドレスではない通常のウィンドウ)

試験的機能

WebMCP はフラグで有効にする新しいブラウザー機能で、仕様がまだ変わる可能性があります。

ツールを有効にする

verbatra studio --expose-agent-tools

VERBATRA_STUDIO_AGENT_TOOLS=1 でも同じ結果になります。オプションと環境変数がどう解決されるかは、課金ツールとエージェントツールを参照してください。表示された URL を WebMCP 対応のブラウザーで開くと、そのタブのエージェントがツールを見つけます。

エージェントにプロバイダーを呼び出させるには、--allow-spend も付けて Studio を起動します。

エージェントは、ページに表示されるとおり、すべての値を秘匿化せずに読み取ります。タブ上のエージェントはどのみちページを読めるためです。例外は用語集のツールと verbatra_history_keyRevisions です。これらの値はシークレットの秘匿化を通るため、API キーの形をした値はプレースホルダーに置き換わって返ります。エージェントに値を見せたくない場合は、代わりに MCP サーバーを --redact-values 付きで使います。NDA(秘密保持契約)の対象プロジェクトについては、Studio と MCP を参照してください。

エージェントが呼び出せるものを知る

各ツールは、verbatra_ で始まる Studio の操作です。読み取りツールには読み取り専用の印が付き、書き込みツールが変更するのはローカルのファイルだけで、課金ツールは --allow-spend を付けたときだけ登録されます。

読み取りツール

ツール機能
verbatra_project_snapshot読み込まれた設定、機能の一覧、capabilities.limits 配下にある retranslate、reviewDecision、2 つの値置換メソッドのレート制限
verbatra_status_checkロケールごとの対応率
verbatra_status_diffロケールごとの欠落しているキー、変更されたキー、孤立したキー
verbatra_glossary_get解決済みの用語集(シークレットは秘匿化)
verbatra_lock_stateロケールごとのロックファイルの状態
verbatra_history_listロケールファイルへの最近のコミットと作成者の名前(メールアドレスは含みません)
verbatra_history_keyRevisions1 つのロケールにおける 1 つのキーのコミットと単語単位の差分(API キーは消去済み) 新機能
verbatra_key_integrityソースが変わったロケールでの、1 つのキーのプレースホルダー、マークアップ、ICU のチェック
verbatra_review_queueコミット済みのファイルにある、誰も承認していない機械翻訳の値すべて
verbatra_key_value1 つのキーのソース値とターゲット値、およびターゲット値を書いた主体
verbatra_key_context1 つのキーの説明、用語集の用語、maxLength、および任意の draft のチェック
verbatra_locale_valuesターゲットロケールごとのキーの値(デフォルトは 1 ページ 200 件、locales、keys、query で絞り込み)
verbatra_locale_integrity整合性チェックに失敗しているすべての訳文
verbatra_translation_estimate未処理の変更を翻訳する呼び出しで送信される内容と費用(プロバイダーは呼び出さない)
verbatra_usage_summary直近の実行のトークン使用量と予算、および失敗または途中で止まったロケールがある場合の incomplete 新機能
verbatra_usage_history記録された実行(新しい順)のトークン、費用、対応率(件数のみ) 新機能

書き込みツール

ツール機能
verbatra_glossary_writeファイルに保存された用語集の用語を 1 つ変更する
verbatra_review_approve名前を指定した人による 1 つの値の承認を記録する
verbatra_review_reject名前を指定した人による却下を記録し、値を削除する
verbatra_translation_editEntry整合性ゲートを通して 1 つの値を書き込む

課金ツール

ツール機能
verbatra_translation_retranslateEntry1 つのロケールの 1 つのキーを再翻訳する
verbatra_translation_translatePending未処理のものをすべて翻訳する(locales で一部のロケールに絞り込み、maxTokens の上限を設定することも可能)

verbatra_key_integrity が返すのは、キーのソースが変わったロケールだけです。リストが空なら、チェックが必要なものはありません。返される行は、MCP サーバーの key.integrity より平坦な構造です。project.doctor と report.provenance は MCP サーバーにしかありません。verbatra_locale_values は、MCP サーバーの locale.values と同じ limit と cursor でページ分割されます(その他の入力と結果)。

ツールが従うルールを知る

すべての呼び出しは、ダッシュボード自身の認証済みループバック RPC を通り、同じ入力の検証と整合性ゲート(翻訳の安全性を参照)が適用されます。チェックに失敗した値は書き込まれず、拒否されます。

呼び出しごとのルール

  • 来歴:エージェントの編集は出どころ agent として記録され、レビューキューに残ります。ダッシュボードでの編集は human です。読み取りツールは、各値を誰が書いたかを報告します(ロックファイルと来歴)。
  • 人手の作業:再翻訳は、人が書いた値を KEY_PROTECTED で拒否し(humanEdits: "overwrite" の場合を除く)、固定されたキーを KEY_PINNED で拒否します。編集も固定されたキーを拒否します(人手翻訳を保護する)。
  • レビューの判断:承認と却下は、人の判断を中継するだけです。どちらも、人の名前を示す reviewer と、レビューしたテキストを示す expectedValue が必要です。値が変わっている場合は REVIEW_VALUE_CHANGED で拒否されます。
  • 一括ツールなし:Approve selected(選択項目を承認)、Reject selected(選択項目を却下)、Retranslate selected(選択項目を再翻訳)、Approve all in(一括承認)、Search and replace(検索と置換)は、人だけが操作できます。
  • 先に見積もる:不明なロケールは、費用が発生する前に UNKNOWN_LOCALE で拒否されます。呼び出しの maxTokens と設定の maxTokens は、小さいほうが適用されます(実行前に費用を見積もる)。
  • レート制限:1 分間の移動ウィンドウあたり、再翻訳 20 回、編集 20 回、用語集の書き込み 20 回、レビューの判断 60 回、未処理の変更を翻訳する呼び出し 5 回(同時に実行できるのは 1 つ)です。

失敗した呼び出しを読み解く

どのツールもダッシュボードのエンベロープ(envelope)を返すため、失敗は { "ok": false, "error": { "code": ..., "message": ... } } の形になります。SDK 自身のコードに加えて、RPC 層が次のコードを追加します。

エラーコード意味
REQUEST_INVALID読み取れるエンベロープではないリクエストまたはレスポンス
METHOD_UNKNOWNこの Studio のバージョンにそのメソッドがない
SPEND_DISABLED課金がオフのときに呼び出された課金メソッドです。Studio が --allow-spend なしで動いているか、プロバイダーが none です。メッセージにどちらかが示されます。
PARAMS_INVALIDパラメーターの検証に失敗しました。issues に各フィールドが示されます。
METHOD_RATE_LIMITEDレート制限を超えました。retryAfterSeconds に、呼び出しが制限内に収まるまでの秒数が示されます。
BATCH_TOO_LARGEバッチがレート制限のウィンドウ全体を超えています。エントリを減らして送ります。
ALREADY_IN_PROGRESS処理中のエントリに対する 2 回目の呼び出し(HTTP 409)
SESSION_EXPIREDStudio が新しいセッショントークンで再起動しました。表示された URL を開きます。
INTERNALハンドラーが予期しないエラーで失敗しました(HTTP 500)。メッセージは汎用的なものです。

機能低下したツールを直す

ブラウザーがツールの登録を拒否すると、すべての画面に次のような警告が表示されます。

Agent tools degraded: 2 of the agent tool registrations failed with SecurityError. The dashboard itself is unaffected. The browser console lists every failing tool.

ブラウザーのコンソールには、失敗ごとに 1 行が出力されます。

出力
Verbatra agent tools: 2 of 20 tool registrations failed. verbatra_status_diff (SecurityError: ...); verbatra_key_value (SecurityError: ...)

まずそこでエラー名を確認し、タブを再読み込みして登録をやり直します。フラグがない場合や、WebMCP のないブラウザーでは、この通知は表示されず、何も登録されないまま静かに終わります。--allow-spend なしのセッションで試みる登録は 2 件少なくなりますが、これは失敗ではありません。

課金のリスクを見極める

ツールを使っても、ネットワークへの公開範囲は広がりません。Studio は引き続き 127.0.0.1 にだけバインドし、すべてのリクエストにセッショントークンが付きます。プロジェクトのテキストを返すツールはそのテキストを信頼できないものとして示すため、エージェントはデータとして扱います。

警告

--allow-spend と --expose-agent-tools を両方付けると、エージェントは呼び出しごとの確認なしに、レート制限の範囲内でプロバイダーに費用をかけられます。Studio はエージェントの呼び出しと人のクリックを区別できないため、承認ダイアログは追加されません。読み取りと編集だけにしたい場合は、--allow-spend を付けないでください。

関連項目

GitHub で編集

このページの内容