Bluente Translate

bluente-translate-mcp-server は、Bluente の翻訳機能を AI クライアントに公開する公式のオープンソース MCP サーバーです。

Bluente API を本番環境に対応した MCP ツールとして提供し、チームが Claude Desktop、Cursor、その他の MCP 対応ランタイムから多言語文書ワークフローを自動化できるようにします。

Bluente を選ぶ理由

Bluente は、精度、フォーマットの整合性、速度が重要となるエンタープライズ品質の文書翻訳に注力しています。

Bluente.com および Blu Translate の中核となる製品の特長は次のとおりです。

• プロフェッショナルなユースケース向けの AI 翻訳
• 文書中心のワークフローにおける元のレイアウトの保持
• 幅広い言語とファイル形式への対応
• 機密コンテンツを安全性優先で取り扱う設計

この MCP サーバーは、標準プロトコルのインターフェースを通じて、これらの機能をエージェントのワークフローに取り入れます。

ブランドアイデンティティ

このリポジトリは Bluente が管理しており、Bluente の公開開発者エコシステムの一部です。

• 会社のウェブサイト：https://www.bluente.com
• 製品ページ：https://www.bluente.com/translator
• API ドキュメント：https://www.bluente.com/docs

目次

• 提供内容
• アーキテクチャ
• 対応する Bluente API
• MCP ツール
• クイックスタート
• ローカル開発
• 運用上の注意事項
• データの取り扱いとプライバシー
• セキュリティ
• ロードマップ
• コントリビューションとガバナンス
• ライセンス

提供内容

• 明確なレイヤー構成（config、client、service、tools）を備えたモジュール式 Node.js MCP サーバー
• 保守しやすい、ツールごとにファイルを分けた実装
• 統一されたツールのレスポンス形式（ok/tool/data と構造化エラー）
• エンドツーエンドの翻訳ワークフローツール（アップロード -> 開始 -> ポーリング -> ダウンロード）
• CI チェックとローカルのスモークテスト

アーキテクチャ

AI Client (Claude / Cursor / Agents)
            |
            | MCP (stdio)
            v
+---------------------------------------+
| Bluente Translate MCP Server          |
|                                       |
|  tools/  -> MCP tool handlers         |
|  services/ -> workflow orchestration  |
|  clients/ -> Bluente HTTP API client  |
|  config/ + lib/ -> env/errors/results |
+---------------------------------------+
            |
            | HTTPS
            v
      Bluente Translation APIs

プロジェクトの構成：

src/
  clients/bluente-http-client.js
  config/env.js
  constants/api.js
  lib/errors.js
  lib/mcp-result.js
  services/translation-workflow-service.js
  tools/*.tool.js
  tools/schemas.js
  tools/register-tools.js
  server.js
  index.js
tests/smoke/core-smoke.test.js

対応する Bluente API

• GET /blu_translate/supported_languages
• POST /blu_translate/upload
• GET /blu_translate/check
• POST /blu_translate/translate
• GET /blu_translate/download
• GET /blu_translate/account

参照：Bluente API ドキュメント

MCP ツール

• bluente_get_supported_languages
• bluente_upload_file
• bluente_get_translation_status
• bluente_translate_file
• bluente_download_file
• bluente_translate_document_workflow
• bluente_get_account — 読み取り専用です。サインイン中のユーザーのメールアドレスと名前、所属組織（名前と役割）、機能ごとのクレジット残高、支払い元（組織の共有プールまたは個人クレジット）、最も早く期限を迎えるクレジットを確認できます。

これらのツールは、Bluente のホスト型 MCP サーバーが公開するツールと一致しているため、一方を対象に作成したプロンプトやエージェントは、もう一方でも使用できます。違いは、ローカルサーバーでのみ可能な次の 2 点です。ソースとしての file_path と、結果をディスクに保存する output_path です（ホスト型サーバーでは代わりにダウンロードリンクが提供されます）。

ツールの動作に関する注意事項：

• 確認ゲート：bluente_translate_document_workflow は 2 回の呼び出しで完了するフローです。最初の呼び出しではファイルをアップロードし、page_count とユーザー向けの確認カードを返します。翻訳は開始されず、クレジットも差し引かれません。カードには現在の翻訳残高、この翻訳後の残高、支払い元を示す Balance: の行が含まれます。残高が不足している場合は警告が表示されます。アカウント情報の取得に失敗した場合、または 3 秒以上かかった場合は、アカウント情報なしでカードが表示されます。実際に開始するには、返された task_id、confirmed=true、明示的な to、to_type、bilingual の値を指定して、もう一度呼び出してください。bluente_translate_file には確認ゲートがなく、すぐに開始します。
• ファイルソース：file_path（このマシン上のファイル）、file_url（公開リンク）、または file_content_base64（2 MB 未満）を指定できます。
• bluente_translate_file：action="start" の場合は from と to が必須で、action="cancel" の場合は省略可能です。
• to_type：pdf、word、または pptx を指定します。ワークフローツールでは配列（例：["word", "pdf"]）も受け付けます。追加の形式は、同じ翻訳結果をダウンロード時に変換するもので、追加クレジットはかかりません。
• entry / status_entry：get_status（翻訳の進行状況。デフォルト）または get_page_count（アップロードしたファイルのページ数）を指定します。
• 言語コード：Bluente では標準とは異なるコード（zh、cht、jp、kor、fra、spa など）を使用します。一般的な ISO 表記（zh-CN、zh-TW、ja、ko、fr、es）は自動的に別名として処理されます。全一覧を確認するには、bluente_get_supported_languages を呼び出してください。
• bilingual：on にすると翻訳と原文を併記し、off（デフォルト）にすると翻訳のみの文書を作成します。on の場合は、bilingual_layout に left-right（左右に並べる）または top-down（上下に重ねる）を設定してください。Bluente がサポートするレイアウトはこの 2 種類のみです。数値の vertical_bilingual フラグは非推奨の別名です。
• mode：standard（多くのデジタル文書向け）、scanned (text)（スキャン画像を OCR 処理し、テキストのみの文書を作成）、scanned (overlay)（スキャン画像の元のレイアウト上に翻訳を配置）、または image（パンフレットやポスターなどの画像を対象言語で再レンダリング。1 ページあたり 5 クレジット。標準料金を超える料金がかかる唯一のモードで、スキャンモードは標準モードと同じ料金です）を指定します。数値の scanned 0～3 フラグは非推奨の別名です。
• page_range（例："1-3,5"）：選択したページのみを翻訳します。クレジットはそのページ分のみ課金されます。
• translate_images：on にすると、Word または PowerPoint ファイル（DOC、DOCX、PPT、PPTX）に埋め込まれた画像内のテキスト（グラフ、スクリーンショット、スキャン画像など）も翻訳します。off（デフォルト）では文書内のテキストのみを翻訳します。追加クレジットはかかりません。標準モードでのみ利用可能です。PDF、またはバイリンガル出力との併用はできません（バックエンドで拒否されます）。確認後の呼び出しでも再度指定してください。省略した場合は off として扱われます。
• 用語集：ワークフローツールでは常に用語集を有効にして翻訳します（Bluente のウェブ製品と同じ動作です）。glossary / custom_glossary 引数は非推奨で、無視されます。直接 bluente_translate_file ツールを使用する場合、バックエンドは glossary と custom_glossary の両方が 1 のときにのみ用語集を適用します。

成功時のエンベロープ：

{
  "ok": true,
  "tool": "bluente_upload_file",
  "data": {
    "code": 0,
    "message": "success",
    "data": { "id": "task_xxx" }
  }
}

エラー時のエンベロープ：

{
  "isError": true,
  "ok": false,
  "tool": "bluente_translate_file",
  "error": {
    "name": "BluenteApiError",
    "message": "Bluente API request failed.",
    "details": { "status": 401 }
  }
}

クイックスタート

必要条件：Node.js >= 20（node --version で確認できます。nodejs.org からインストールしてください）および Bluente API キー。

API キーの取得： translate.bluente.com にログインし、My Files → API Keys and Webhook に移動します。このキーはパスワードと同様に扱ってください。アカウントに請求される翻訳を実行できるため、バージョン管理や共有ドキュメントに含めないでください。

オプション 1：コーディングエージェントに任せる

最も手早いインストール方法は、インストールしないことです。Claude Code、Cursor、または MCP 対応のコーディングエージェントを使用している場合は、このプロンプトを貼り付ければ、設定ファイル、キー、検証まで、すべてを 1 分以内に処理してくれます。YOUR_KEY_HERE を API キーに置き換えてください。

このクライアントに Bluente Translate MCP サーバーをインストールしてください。npm パッケージは @bluente/translate-mcp-server で、npx -y @bluente/translate-mcp-server（stdio）で実行します。また、サーバー設定の env ブロックに環境変数 BLUENTE_API_KEY を設定する必要があります。キーには YOUR_KEY_HERE を使用してください。設定後、bluente_get_supported_languages ツールを呼び出してインストールを検証し、結果を表示してください。ドキュメント：https://github.com/Bluente/bluente-translate-mcp-server

エージェントがクライアントに適した設定ファイルを見つけ、設定ブロックを書き込み、対応言語の一覧を表示してインストールが機能することを確認します。

API キーをエージェントとの会話に貼り付けたくない場合は、エージェントにキーとして REPLACE_ME を使わせてから、設定ファイルを手動で編集し、クライアントを再起動してください。

オプション 2：手動でインストールする

Claude Desktop

1. Settings → Developer → Edit Config を開きます（claude_desktop_config.json が開きます）。

2. 次のブロックを追加します（mcpServers がすでにある場合は、その中に統合してください）。API キーを挿入してください。

   {
     "mcpServers": {
       "bluente-translate": {
         "command": "npx",
         "args": ["-y", "@bluente/translate-mcp-server"],
         "env": {
           "BLUENTE_API_KEY": "your_api_key_here"
         }
       }
     }
   }
   

3. Claude Desktop を終了して再度開きます。ツールアイコンに 7 つの bluente_* ツールが表示されます。

Claude Code — コマンドを 1 つ実行し、セッションを再起動してから /mcp で確認します。

claude mcp add bluente-translate -e BLUENTE_API_KEY=your_api_key_here -- npx -y @bluente/translate-mcp-server

Cursor — Settings → MCP → Add server を選択するか、プロジェクト内に .cursor/mcp.json を作成し、Claude Desktop と同じ JSON ブロックを追加します。

動作確認（すべてのクライアント）： 「Bluente 翻訳がサポートしている言語は何ですか？」 と尋ねてください。これは無料の読み取り専用呼び出しです。言語一覧が返ってくれば、キーと接続の両方が機能しています。初回の実行では、npx がパッケージをダウンロードするため、数秒余分にかかります。

API キーのトラブルシューティング

サーバーは環境変数から BLUENTE_API_KEY を読み取ります。ツールの引数として渡したり、ファイルに保存したりする必要はありません。サーバーが Missing BLUENTE_API_KEY を報告する場合、キーがサーバープロセスに渡っていません。env ブロックに誤字がないか確認し、クライアントを再起動してください。ターミナルからテストするときは、サーバーのコマンド自体の前に BLUENTE_API_KEY=your_api_key_here npx -y @bluente/translate-mcp-server を付けてください。シェルのパイプラインでは、代入を npx の直前に置く必要があります。行頭に置くと、パイプの最初のコマンドにだけ適用されます。

任意の環境変数：

変数	デフォルト	用途
BLUENTE_API_KEY	（必須）	Bluente API キー
BLUENTE_API_BASE_URL	https://api.bluente.com/api/20250924	API ベース URL
BLUENTE_API_TIMEOUT_MS	90000	HTTP タイムアウト（ミリ秒）

ローカル開発

git clone https://github.com/bluente/bluente-translate-mcp-server.git
cd bluente-translate-mcp-server
npm install
cp .env.example .env   # then set BLUENTE_API_KEY
npm start              # run the server on stdio
npm run check          # syntax check
npm test               # run tests

MCP クライアントをローカルのチェックアウトに接続するには、上記の npx 設定の代わりに "command": "node" と "args": ["/absolute/path/to/bluente-translate-mcp-server/src/index.js"] を使用してください。

運用上の注意事項

• ワークフローツールは翻訳が始まるとすぐに応答を返します。bluente_get_translation_status を READY になるまでポーリングしてから、bluente_download_file を呼び出してください。
• auto_download=true を指定すると、翻訳が完了するまで待機し、ファイルをディスクに保存します。小さなドキュメントに限り安全に使用できます。翻訳には数分かかることが多く、先に MCP クライアントがリクエストをタイムアウトする可能性があるためです。
• max_poll_attempts は、アップロードと翻訳の各フェーズで共有される単一の上限です。
• タイムアウトは BLUENTE_API_TIMEOUT_MS で設定できます。
• 本番環境では、環境ごとに別の API キーを使用してください。

データの取り扱いとプライバシー

• 翻訳するドキュメントは、処理のため Bluente の API（デフォルトでは api.bluente.com）にアップロードされます。 第三者サービスへの送信が許可されていないドキュメントは翻訳しないでください。
• ツールは AI モデルによって制御されます。 ローカル（stdio）で実行する場合、file_path を使ってモデルがユーザーアカウントで読み取り可能な任意のファイルを読み取り、Bluente にアップロードできます。また、output_path を使って書き込み可能な任意のパスにダウンロードしたファイルを書き込めます。ツールの呼び出しを承認する前に、MCP クライアントで内容を確認してください。特に信頼できないドキュメントを扱う際は注意してください。悪意のあるドキュメントが、モデルにこれらのツールを不正に使わせようとする可能性があります。
• ツールから返された翻訳結果（ファイルの内容、ステータスのペイロード）は AI クライアントのコンテキストに入り、LLM プロバイダーから閲覧可能になります。
• API キーはお使いのマシン内に保持されます。環境変数から読み取られ、設定された Bluente API のベース URL に Authorization ヘッダーとしてのみ送信されます。ログに記録されたり、ツールの応答に含まれたりすることはありません。

セキュリティ

• API キーや .env ファイルをコミットしないでください。
• 漏えいしたキーは直ちにローテーションしてください。
• リポジトリの非公開の脆弱性報告機能を使用してください。

開示ポリシーについては、SECURITY.md を参照してください。

ロードマップ

• 公開 API ドキュメントで提供されている場合は、テキスト翻訳ツールを追加
• API のモックを使った、より充実した統合テストを追加
• コンテナーイメージと、ワンコマンドでローカル起動するためのプロファイルを追加

貢献とガバナンス

• 貢献ガイド：CONTRIBUTING.md
• セキュリティポリシー：SECURITY.md
• 変更履歴：CHANGELOG.md
• コードの所有者：.github/CODEOWNERS

Bluente について

Bluente は、専門チーム向けの AI 翻訳およびビジネスコミュニケーションソリューションを構築しています。

• ウェブサイト：bluente.com
• 製品ページ：Blu Translate
• API ドキュメント：bluente.com/docs

ライセンス

MIT