MCP

API リファレンス

Verbumia ships a native MCP server so any MCP-aware client — Claude Desktop, Cursor, your own agent — can search keys, propose translations, review PRs, and inspect the missing-key queue. Two lines of config, your token, done.

1. API キーを取得

ダッシュボードで Org Settings → API Keys → Create に進みます。スコープは mcp:*(以下の 5 つのツールすべてをカバー)。シークレットは 1 度だけ 表示されるので、vrb_live_<prefix>.<secret> 文字列の全体をコピーしてください。

OS のキーチェーン、またはローカルの .env に保存し、絶対にコミットしないでください。キーは org に紐づき(任意で 1 プロジェクトにも)、スコープ外の呼び出しは 404 を返します。ダッシュボードからいつでも失効可能で、失効後は次回呼び出しで 401 になります。

2. Install (or skip)

The MCP server is published to npm and Homebrew. With npx you don't need to install anything — Claude Desktop pulls the latest version on every launch. With brew you get a pinned local binary, useful behind strict firewalls.

npx(推奨)

1// インストール不要 — npx が必要に応じて最新の @verbumia/mcp を取得します2npx -y @verbumia/mcp --version

Homebrew(代替) Tap は V1 公開予定

1// 任意: グローバルに 1 度インストール — V1 ローンチに合わせて提供2brew install verbumia/tap/verbumia-mcp

3. Claude Desktop に接続

Claude Desktop の設定ファイルを開き、mcpServers の下に verbumia エントリを追加してから、アプリを終了して再起動します。

claude_desktop_config.json

1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "verbumia": {6      "command": "npx",7      "args": ["-y", "@verbumia/mcp"],8      "env": {9        "VERBUMIA_TOKEN":   "vrb_live_<prefix>.<secret>",10        "VERBUMIA_PROJECT": "<project_uuid>"11      }12    }13  }14}

環境変数は計 3 つです: VERBUMIA_TOKEN(必須)、VERBUMIA_PROJECT(任意 — プロジェクトを事前指定すると、エージェントが先に list_projects を呼ぶ必要がなくなります)、VERBUMIA_API_BASE(任意 — デフォルトは https://api.verbumia.ca。セルフホストやステージング向けに上書きしてください)。

Cursor(およびその他の MCP クライアント)

JSON は同じで、ファイルの場所が違います。Cursor では .cursor/mcp.json(プロジェクト単位)または ~/.cursor/mcp.json(ユーザー単位)に置きます。他のクライアントでは、それぞれの MCP 設定ドキュメントに従ってください — mcpServers.verbumia エントリは同一です。

.cursor/mcp.json

1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "verbumia": {5      "command": "npx",6      "args": ["-y", "@verbumia/mcp"],7      "env": { "VERBUMIA_TOKEN": "vrb_live_<prefix>.<secret>" }8    }9  }10}

V1 の 5 つのツール

設定後、エージェントはこれらのツールを利用できます。名前で直接呼び出すのではなく、チャットで意図を伝えればエージェントが選択します。以下の名前はキャノニカル ID で、エージェントトレースを読むときや、同じサーバー上にカスタムエージェントを構築するときに役立ちます。

list_projects 現在の API キーでアクセスできるプロジェクトを列挙します。チャット冒頭でワークスペースを選ぶのに便利です。

引数

limit number 返されるプロジェクト数の任意上限

プロンプト例

「List my Verbumia projects.」

get_project_info プロジェクトのメタデータを取得します: ソース言語、ターゲット言語、namespace、キーの総数。

引数

project_uuid string required

プロンプト例

「Checkout プロジェクトはどの言語と namespace を扱っていますか?」

list_missing_keys ランタイム SDK が捕捉した欠落キーイベント(cursor ページネーション)を一覧します。namespace または言語でフィルタ可能です。

引数

project_uuid string required
namespace string 1 つの namespace に絞り込み(例: "checkout")
language_code string 1 つの言語に絞り込み(例: "ja")
cursor string 前回呼び出しで返ったページネーション cursor
limit number ページサイズ(デフォルト 20)

プロンプト例

「checkout namespace で ja に欠けている翻訳キーは?」

propose_translation ターゲット言語のキーに翻訳値を提案します。常に draft として保存され、人間のレビュアーが後でプロモートします — Verbumia はマネージャーであり、エンジンではありません。

引数

project_uuid string required
key string required
namespace string required
language_code string required
value string required

プロンプト例

「Propose \"Confirmer la commande\" for checkout.review.confirm in fr-CA.」

validate_translations push 前に JSON i18next ペイロードをリント: ICU プレースホルダーの整合性、欠落/余剰キー、ロケール間の型ドリフト。

引数

project_uuid string required
language_code string required
payload object required JSON i18next 形式の翻訳マップ

プロンプト例

「この翻訳ファイルをプロジェクトの英語ソースと照合して検証して。」

動作確認

1 Claude Desktop を完全に再起動します(終了 → 再起動。設定は起動時に読み込まれます)。
2 新しいチャットを開きます。ハンマーアイコンに verbumia と 5 つのツールが表示されるはずです。
3 「List my Verbumia projects.」 と入力してください。エージェントが list_projects を呼び、ワークスペース一覧を返します。