xCOMET MCP Server

npm version MCP License: MIT

日本語版 README はこちら

⚠️ これは非公式のコミュニティプロジェクトであり、Unbabelとは提携していません。

xCOMET (eXplainable COMET) を活用した翻訳品質評価MCPサーバーです。

🎯 概要

xCOMET MCP Serverは、AIエージェントに機械翻訳の品質を評価する機能を提供します。UnbabelのxCOMETモデルと統合し、以下を実現します：

品質スコアリング: 翻訳品質を示す0〜1のスコア
エラー検出: 重大度レベル（軽微/重大/致命的）を伴うエラー箇所の特定
バッチ処理: 複数の翻訳ペアを効率的に評価（モデルのロードを最適化）
GPUサポート: 高速な推論のためのGPUアクセラレーション（オプション）

graph LR
    A[AI Agent] --> B[Node.js MCP Server]
    B --> C[Python FastAPI Server]
    C --> D[xCOMET Model<br/>Persistent in Memory]
    D --> C
    C --> B
    B --> A

    style D fill:#9f9

🔧 前提条件

Python環境

Python 3.9 - 3.12 を推奨（3.13以降はxCOMETの依存関係でまだサポートされていません）

xCOMETにはPythonといくつかのパッケージが必要です。仮想環境の使用を推奨します：

# If using uv (recommended - auto-downloads the correct Python version)
uv venv ~/.xcomet-venv --python 3.12
source ~/.xcomet-venv/bin/activate
uv pip install "unbabel-comet>=2.2.0" "fastapi>=0.100.0" "uvicorn>=0.23.0" "pydantic>=2.0.0"

# Or using standard venv (requires Python 3.9-3.12 already installed)
python3 -m venv ~/.xcomet-venv
source ~/.xcomet-venv/bin/activate  # Windows: ~/.xcomet-venv\Scripts\activate
pip install "unbabel-comet>=2.2.0" "fastapi>=0.100.0" "uvicorn>=0.23.0" "pydantic>=2.0.0"

注: Claude Desktopや他のMCPホストで使用する場合は、XCOMET_PYTHON_PATHに仮想環境のPythonパスを設定してください（設定を参照）。

モデルのダウンロード

重要: XCOMET-XLおよびXCOMET-XXLはHuggingFace上のゲート付きモデルです。以下の手順が必要です：
HuggingFaceアカウントを作成する
Unbabel/XCOMET-XL にアクセスし、アクセス権をリクエストする
CLI経由でログインする：
source ~/.xcomet-venv/bin/activate
huggingface-cli login
Unbabel/wmt22-comet-da は認証を必要としません（ただし、参照翻訳が必要です）。

認証後、モデルをダウンロードします（XLは約14GB、XXLは約42GB）：

source ~/.xcomet-venv/bin/activate
python -c "from comet import download_model; download_model('Unbabel/XCOMET-XL')"

Node.js

Node.js >= 18.0.0
npm または yarn

📦 インストール

注: xCOMET MCP Serverを使用するだけであれば、このリポジトリをクローンする必要はありません。Python環境とモデルをインストールし（前提条件を参照）、npxを使用してください（使用方法を参照）。以下のセクションはコントリビューターおよびローカル開発用です。

ローカル開発

コントリビューターおよびローカル開発用：

# Clone the repository
git clone https://github.com/shuji-bonji/xcomet-mcp-server.git
cd xcomet-mcp-server

# Set up Python virtual environment and install dependencies
uv venv .venv --python 3.12    # or: python3 -m venv .venv
source .venv/bin/activate
pip install -r python/requirements.txt

# Install Node.js dependencies and build
npm install
npm run build

🚀 使用方法

Claude Desktop (npx) での使用

Claude Desktopの設定ファイル（claude_desktop_config.json）に追加します：

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server"],
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

ヒント: Pythonパッケージをシステム全体にインストールしている場合やpyenvを使用している場合は、XCOMET_PYTHON_PATHを省略できます（自動検出されます）。詳細はPythonパスの自動検出を参照してください。

Claude Code での使用

claude mcp add xcomet --env XCOMET_PYTHON_PATH=~/.xcomet-venv/bin/python3 -- npx -y xcomet-mcp-server

グローバルインストール

グローバルにインストールする場合：

npm install -g xcomet-mcp-server

その後、設定します：

{
  "mcpServers": {
    "xcomet": {
      "command": "xcomet-mcp-server",
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

ローカル開発ビルド

リポジトリをクローンしてローカルでビルドした場合（インストールを参照）：

{
  "mcpServers": {
    "xcomet": {
      "command": "node",
      "args": ["/path/to/xcomet-mcp-server/dist/index.js"],
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

HTTPモード（リモートアクセス）

TRANSPORT=http PORT=3000 npm start

その後、http://localhost:3000/mcp に接続します。

🛠️ 利用可能なツール

`xcomet_evaluate`

単一のソースと翻訳のペアの翻訳品質を評価します。

パラメータ:

名前	型	必須	説明
`source`	string	✅	元のソーステキスト
`translation`	string	✅	評価する翻訳テキスト
`reference`	string	❌	参照翻訳
`source_lang`	string	❌	ソース言語コード (ISO 639-1)
`target_lang`	string	❌	ターゲット言語コード (ISO 639-1)
`response_format`	"json"	"markdown"	❌	出力形式 (デフォルト: "json")
`use_gpu`	boolean	❌	推論にGPUを使用 (デフォルト: false)

例:

{
  "source": "The quick brown fox jumps over the lazy dog.",
  "translation": "素早い茶色のキツネが怠惰な犬を飛び越える。",
  "source_lang": "en",
  "target_lang": "ja",
  "use_gpu": true
}

レスポンス:

{
  "score": 0.847,
  "errors": [],
  "summary": "Good quality (score: 0.847) with 0 error(s) detected."
}

`xcomet_detect_errors`

翻訳エラーの検出と分類に焦点を当てます。

パラメータ:

名前	型	必須	説明
`source`	string	✅	元のソーステキスト
`translation`	string	✅	分析する翻訳テキスト
`reference`	string	❌	参照翻訳
`min_severity`	"minor"	"major"	"critical"	❌	最小重大度 (デフォルト: "minor")
`response_format`	"json"	"markdown"	❌	出力形式
`use_gpu`	boolean	❌	推論にGPUを使用 (デフォルト: false)

`xcomet_batch_evaluate`

単一のリクエストで複数の翻訳ペアを評価します。

パフォーマンスに関する注意: 常駐サーバーアーキテクチャ（v0.3.0以降）では、モデルがメモリにロードされたままになります。バッチ評価は、モデルを再ロードすることなくすべてのペアを効率的に処理します。

パラメータ:

名前	型	必須	説明
`pairs`	array	✅	{source, translation, reference?} の配列 (最大500)
`source_lang`	string	❌	ソース言語コード
`target_lang`	string	❌	ターゲット言語コード
`response_format`	"json"	"markdown"	❌	出力形式
`use_gpu`	boolean	❌	推論にGPUを使用 (デフォルト: false)
`batch_size`	number	❌	バッチサイズ 1-64 (デフォルト: 8)。大きいほど高速だがメモリ消費が増加

例:

{
  "pairs": [
    {"source": "Hello", "translation": "こんにちは"},
    {"source": "Goodbye", "translation": "さようなら"}
  ],
  "use_gpu": true,
  "batch_size": 16
}

🔗 他のMCPサーバーとの統合

xCOMET MCP Serverは、完全な翻訳ワークフローのために他のMCPサーバーと連携するように設計されています：

sequenceDiagram
    participant Agent as AI Agent
    participant DeepL as DeepL MCP Server
    participant xCOMET as xCOMET MCP Server
    
    Agent->>DeepL: Translate text
    DeepL-->>Agent: Translation result
    Agent->>xCOMET: Evaluate quality
    xCOMET-->>Agent: Score + Errors
    Agent->>Agent: Decide: Accept or retry?

推奨ワークフロー

DeepL MCP Server（公式）を使用して翻訳する
xCOMET MCP Serverを使用して評価する
品質がしきい値を下回った場合は改善する

例: DeepL + xCOMET 統合

Claude Desktopで両方のサーバーを設定します：

{
  "mcpServers": {
    "deepl": {
      "command": "npx",
      "args": ["-y", "@anthropic/deepl-mcp-server"],
      "env": {
        "DEEPL_API_KEY": "your-api-key"
      }
    },
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server"],
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

その後、Claudeに尋ねます：

"DeepLを使ってこのテキストを日本語に翻訳し、xCOMETで翻訳品質を評価してください。スコアが0.8未満の場合は改善案を提示してください。"

⚙️ 設定

環境変数

変数	デフォルト	説明
`TRANSPORT`	`stdio`	トランスポートモード: `stdio` または `http`
`PORT`	`3000`	HTTPサーバーポート (TRANSPORT=httpの場合)
`XCOMET_MODEL`	`Unbabel/XCOMET-XL`	使用するxCOMETモデル
`XCOMET_PYTHON_PATH`	(自動検出)	Python実行可能パス (下記参照)
`XCOMET_PRELOAD`	`false`	起動時にモデルをプリロード (v0.3.1+)
`XCOMET_DEBUG`	`false`	詳細なデバッグログを有効化 (v0.3.1+)

モデルの選択

品質とパフォーマンスのニーズに基づいてモデルを選択してください：

モデル	パラメータ	サイズ	メモリ	参照	HF認証	品質	ユースケース
`Unbabel/XCOMET-XL`	3.5B	~14GB	~8-10GB	オプション	✅ 必要	⭐⭐⭐⭐	ほとんどのユースケースに推奨
`Unbabel/XCOMET-XXL`	10.7B	~42GB	~20GB	オプション	✅ 必要	⭐⭐⭐⭐⭐	最高品質、より多くのリソースが必要
`Unbabel/wmt22-comet-da`	580M	~2GB	~3GB	必要	不要	⭐⭐⭐	軽量、高速ロード

重要: XCOMET-XLおよびXCOMET-XXLはHuggingFace上のゲート付きモデルです。各モデルには個別のアクセス承認が必要です。認証設定についてはモデルのダウンロードを参照してください。

重要: wmt22-comet-da は評価に reference 翻訳が必要です。xCOMETモデルは参照なしの評価をサポートしています。

ヒント: メモリの問題やモデルのロードが遅い場合は、精度はわずかに下がりますが、より高速な Unbabel/wmt22-comet-da を試してください（ただし、参照翻訳を提供することを忘れないでください）。

別のモデルを使用するには、XCOMET_MODEL環境変数を設定します：

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server"],
      "env": {
        "XCOMET_MODEL": "Unbabel/XCOMET-XXL"
      }
    }
  }
}

Pythonパスの自動検出

サーバーは unbabel-comet がインストールされているPython環境を自動的に検出します：

XCOMET_PYTHON_PATH 環境変数（設定されている場合）
pyenv バージョン (~/.pyenv/versions/*/bin/python3) - comet モジュールを確認
Homebrew Python (/opt/homebrew/bin/python3, /usr/local/bin/python3)
フォールバック: python3 コマンド

これにより、MCPホスト（Claude Desktopなど）がターミナルと異なるPythonを使用している場合でも、サーバーが正しく動作します。

例: 明示的なPythonパスの設定

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server"],
      "env": {
        "XCOMET_PYTHON_PATH": "/Users/you/.pyenv/versions/3.11.0/bin/python3"
      }
    }
  }
}

⚡ パフォーマンス

常駐サーバーアーキテクチャ (v0.3.0+)

サーバーは、xCOMETモデルをメモリにロードしたままにする常駐Python FastAPIサーバーを使用します：

リクエスト	時間	メモ
初回リクエスト	~25-90秒	モデルロード（モデルサイズにより異なる）
後続リクエスト	~500ms	モデルロード済み

これにより、毎回モデルを再ロードする場合と比較して、連続評価で177倍の高速化を実現します。

イーガーロード (v0.3.1+)

XCOMET_PRELOAD=true を有効にすると、サーバー起動時にモデルをプリロードします：

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server"],
      "env": {
        "XCOMET_PRELOAD": "true"
      }
    }
  }
}

プリロードを有効にすると、初回を含めすべてのリクエストが高速（~500ms）になります。

graph LR
    A[MCP Request] --> B[Node.js Server]
    B --> C[Python FastAPI Server]
    C --> D[xCOMET Model<br/>in Memory]
    D --> C
    C --> B
    B --> A

    style D fill:#9f9

バッチ処理の最適化

xcomet_batch_evaluate ツールは、単一のモデルロードですべてのペアを処理します：

ペア数	推定時間
10	~30-40秒
50	~1-1.5分
100	~2分

GPU vs CPU パフォーマンス

モード	100ペア (推定)
CPU (batch_size=8)	~2分
GPU (batch_size=16)	~20-30秒

注: GPUにはCUDA互換ハードウェアとCUDAサポート付きのPyTorchが必要です。GPUが利用できない場合は、use_gpu: false（デフォルト）に設定してください。

ベストプラクティス

1. 常駐サーバーに任せる

v0.3.0以降、モデルはメモリに保持されます。複数の xcomet_evaluate 呼び出しは効率的です：

✅ Fast: First call loads model, subsequent calls reuse it
   xcomet_evaluate(pair1)  # ~90s (model loads)
   xcomet_evaluate(pair2)  # ~500ms (model cached)
   xcomet_evaluate(pair3)  # ~500ms (model cached)

2. 多数のペアにはバッチ評価を使用する

✅ Even faster: Batch all pairs in one call
   xcomet_batch_evaluate(allPairs)  # Optimal throughput

3. メモリに関する考慮事項

XCOMET-XLには約8-10GBのRAMが必要です
大規模なバッチ（500ペア）の場合は、十分なメモリを確保してください
メモリが制限されている場合は、小さなバッチ（100-200ペア）に分割してください

自動再起動 (v0.3.1+)

サーバーは障害から自動的に復旧します：

30秒ごとにヘルスチェックを実行
3回連続でヘルスチェックに失敗すると再起動
諦めるまでに最大3回の再起動試行

📊 品質スコアの解釈

スコア範囲	品質	推奨事項
0.9 - 1.0	優秀	使用可能
0.7 - 0.9	良好	軽微なレビューを推奨
0.5 - 0.7	普通	ポストエディットが必要
0.0 - 0.5	不良	再翻訳を推奨

🔍 トラブルシューティング

よくある問題

"No module named 'comet'"

原因: unbabel-comet がインストールされていないPython環境。

解決策:

# Check which Python is being used
python3 -c "import sys; print(sys.executable)"

# If using a virtual environment, make sure it's activated
source .venv/bin/activate
pip install -r python/requirements.txt

# For MCP hosts (e.g., Claude Desktop), specify the venv Python path
export XCOMET_PYTHON_PATH=~/.xcomet-venv/bin/python3

モデルのダウンロードが失敗またはタイムアウトする

原因: 大規模なモデルファイル（XLで約14GB）には安定したインターネット接続が必要です。また、xCOMETモデルにはHuggingFace認証が必要です（モデルのダウンロードを参照）。

解決策:

# Login to HuggingFace (required for XCOMET-XL/XXL)
huggingface-cli login

# Pre-download the model manually
python -c "from comet import download_model; download_model('Unbabel/XCOMET-XL')"

GPUが検出されない

原因: CUDAサポート付きでPyTorchがインストールされていない。

解決策:

# Check CUDA availability
python -c "import torch; print(torch.cuda.is_available())"

# If False, reinstall PyTorch with CUDA
pip install torch --index-url https://download.pytorch.org/whl/cu118

Mac (MPS) でのパフォーマンス低下

原因: MacのMPS (Metal Performance Shaders) は一部の操作で互換性の問題があります。

解決策: サーバーはMac MPS互換性のために自動的に num_workers=1 を使用します。Macで最高のパフォーマンスを得るには、CPUモード（use_gpu: false）を使用してください。

xCOMET MCP Server

🎯 概要

🔧 前提条件

Python環境

モデルのダウンロード

Node.js

📦 インストール

ローカル開発

🚀 使用方法

Claude Desktop (npx) での使用

Claude Code での使用

グローバルインストール

ローカル開発ビルド

HTTPモード（リモートアクセス）

🛠️ 利用可能なツール

xcomet_evaluate

xcomet_detect_errors

xcomet_batch_evaluate

🔗 他のMCPサーバーとの統合

推奨ワークフロー

例: DeepL + xCOMET 統合

⚙️ 設定

環境変数

モデルの選択

Pythonパスの自動検出

⚡ パフォーマンス

常駐サーバーアーキテクチャ (v0.3.0+)

イーガーロード (v0.3.1+)

バッチ処理の最適化

GPU vs CPU パフォーマンス

ベストプラクティス

自動再起動 (v0.3.1+)

📊 品質スコアの解釈

🔍 トラブルシューティング

よくある問題

"No module named 'comet'"

モデルのダウンロードが失敗またはタイムアウトする

GPUが検出されない

Mac (MPS) でのパフォーマンス低下

高

Resources

Tools

Latest Blog Posts

MCP directory API

`xcomet_evaluate`

`xcomet_detect_errors`

`xcomet_batch_evaluate`