# xCOMET MCP Server
[](https://www.npmjs.com/package/xcomet-mcp-server)
[](https://github.com/shuji-bonji/xcomet-mcp-server/actions/workflows/ci.yml)
[](https://modelcontextprotocol.io)
[](https://opensource.org/licenses/MIT)
**[English README](README.md)**
> ⚠️ これは非公式のコミュニティプロジェクトであり、Unbabel とは関係ありません。
[xCOMET](https://github.com/Unbabel/COMET)（eXplainable COMET）を使用した翻訳品質評価 MCP サーバーです。
## 概要
xCOMET MCP Server は、AI エージェントに機械翻訳の品質評価機能を提供します。Unbabel の xCOMET モデルと統合し、以下の機能を提供します：
- **品質スコアリング**: 0〜1 のスコアで翻訳品質を評価
- **エラー検出**: エラー箇所を重大度（minor/major/critical）付きで特定
- **バッチ処理**: 複数の翻訳ペアを効率的に評価（モデルの単一ロード最適化）
- **GPU サポート**: 高速推論のためのオプション GPU アクセラレーション
```mermaid
graph LR
A[AI エージェント] --> B[Node.js MCP サーバー]
B --> C[Python FastAPI サーバー]
C --> D[xCOMET モデル<br/>メモリ常駐]
D --> C
C --> B
B --> A
style D fill:#9f9
```
## 前提条件
### Python 環境
xCOMET には以下のパッケージがインストールされた Python が必要です：
```bash
pip install "unbabel-comet>=2.2.0" fastapi uvicorn
```
### モデルのダウンロード
初回実行時に xCOMET モデルがダウンロードされます（XL は約 14GB、XXL は約 42GB）：
```bash
# モデルの利用可能性をテスト
python -c "from comet import download_model; download_model('Unbabel/XCOMET-XL')"
```
### Node.js
- Node.js >= 18.0.0
- npm または yarn
## インストール
```bash
# リポジトリをクローン
git clone https://github.com/shuji-bonji/xcomet-mcp-server.git
cd xcomet-mcp-server
# 依存関係をインストール
npm install
# ビルド
npm run build
```
## 使い方
### Claude Desktop での利用（npx）
Claude Desktop の設定ファイル（`claude_desktop_config.json`）に追加：
```json
{
"mcpServers": {
"xcomet": {
"command": "npx",
"args": ["-y", "xcomet-mcp-server"]
}
}
}
```
### Claude Code での利用
```bash
claude mcp add xcomet -- npx -y xcomet-mcp-server
```
### ローカルインストール
ローカルにインストールする場合：
```bash
npm install -g xcomet-mcp-server
```
設定：
```json
{
"mcpServers": {
"xcomet": {
"command": "xcomet-mcp-server"
}
}
}
```
### HTTP モード（リモートアクセス）
```bash
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） |
**例:**
```json
{
"source": "The quick brown fox jumps over the lazy dog.",
"translation": "素早い茶色のキツネが怠惰な犬を飛び越える。",
"source_lang": "en",
"target_lang": "ja",
"use_gpu": true
}
```
**レスポンス:**
```json
{
"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）。大きいほど高速だがメモリ使用量増加 |
**例:**
```json
{
"pairs": [
{"source": "Hello", "translation": "こんにちは"},
{"source": "Goodbye", "translation": "さようなら"}
],
"use_gpu": true,
"batch_size": 16
}
```
## 他の MCP サーバーとの連携
xCOMET MCP Server は、完全な翻訳ワークフローのために他の MCP サーバーと連携するように設計されています：
```mermaid
sequenceDiagram
participant Agent as AI エージェント
participant DeepL as DeepL MCP Server
participant xCOMET as xCOMET MCP Server
Agent->>DeepL: テキストを翻訳
DeepL-->>Agent: 翻訳結果
Agent->>xCOMET: 品質を評価
xCOMET-->>Agent: スコア + エラー
Agent->>Agent: 判断: 採用 or 再試行?
```
### 推奨ワークフロー
1. DeepL MCP Server で**翻訳**
2. xCOMET MCP Server で**評価**
3. 品質が閾値以下なら**再試行**
### 設定例: DeepL + xCOMET 連携
Claude Desktop で両サーバーを設定：
```json
{
"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"]
}
}
}
```
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+） |
### モデル選択
品質とパフォーマンスのニーズに応じてモデルを選択：
| モデル | パラメータ | サイズ | メモリ | 参照訳 | 品質 | 用途 |
|-------|------------|------|--------|-----------|---------|----------|
| `Unbabel/XCOMET-XL` | 3.5B | 約 14GB | 約 8-10GB | 任意 | ⭐⭐⭐⭐ | ほとんどの用途に推奨 |
| `Unbabel/XCOMET-XXL` | 10.7B | 約 42GB | 約 20GB | 任意 | ⭐⭐⭐⭐⭐ | 最高品質、より多くのリソースが必要 |
| `Unbabel/wmt22-comet-da` | 580M | 約 2GB | 約 3GB | **必須** | ⭐⭐⭐ | 軽量、高速ロード |
> **重要**: `wmt22-comet-da` は評価に `reference`（参照訳）が**必須**です。XCOMET モデルは参照訳なしの評価をサポートしています。
> **ヒント**: メモリ不足やモデルロードが遅い場合は、`Unbabel/wmt22-comet-da` を使用すると、精度は若干低下しますがパフォーマンスが向上します（ただし参照訳の提供を忘れずに）。
**別のモデルを使用する場合**、`XCOMET_MODEL` 環境変数を設定：
```json
{
"mcpServers": {
"xcomet": {
"command": "npx",
"args": ["-y", "xcomet-mcp-server"],
"env": {
"XCOMET_MODEL": "Unbabel/XCOMET-XXL"
}
}
}
}
```
### Python パスの自動検出
サーバーは `unbabel-comet` がインストールされた Python 環境を自動検出します：
1. **`XCOMET_PYTHON_PATH`** 環境変数（設定されている場合）
2. **pyenv** バージョン（`~/.pyenv/versions/*/bin/python3`）- `comet` モジュールをチェック
3. **Homebrew** Python（`/opt/homebrew/bin/python3`、`/usr/local/bin/python3`）
4. **フォールバック**: `python3` コマンド
これにより、MCP ホスト（例: Claude Desktop）がターミナルとは異なる Python を使用している場合でも、サーバーが正しく動作します。
**例: 明示的な Python パス設定**
```json
{
"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 秒 | モデルロード（モデルサイズによる） |
| 2 回目以降 | **約 500ms** | モデルはロード済み |
これにより、毎回モデルを再ロードする場合と比較して、連続評価で**177 倍の高速化**を実現します。
### 即時ロード（v0.3.1+）
`XCOMET_PRELOAD=true` を有効にすると、サーバー起動時にモデルをプリロードします：
```json
{
"mcpServers": {
"xcomet": {
"command": "npx",
"args": ["-y", "xcomet-mcp-server"],
"env": {
"XCOMET_PRELOAD": "true"
}
}
}
}
```
プリロードを有効にすると、初回リクエストを含む**すべてのリクエストが高速**（約 500ms）になります。
### バッチ処理の最適化
`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` 呼び出しも効率的です：
```
✅ 高速: 初回呼び出しでモデルをロード、以降は再利用
xcomet_evaluate(pair1) # 約 90 秒（モデルロード）
xcomet_evaluate(pair2) # 約 500ms（モデルキャッシュ済み）
xcomet_evaluate(pair3) # 約 500ms（モデルキャッシュ済み）
```
**2. 多数のペアにはバッチ評価を使用**
```
✅ さらに高速: すべてのペアを一度に処理
xcomet_batch_evaluate(allPairs) # 最適なスループット
```
**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 環境
**解決策**:
```bash
# 使用されている Python を確認
python3 -c "import sys; print(sys.executable)"
# 必要なパッケージをすべてインストール
pip install "unbabel-comet>=2.2.0" fastapi uvicorn
# または Python パスを明示的に指定
export XCOMET_PYTHON_PATH=/path/to/python3
```
#### モデルのダウンロードが失敗またはタイムアウト
**原因**: 大きなモデルファイル（XL は約 14GB）には安定したインターネット接続が必要
**解決策**:
```bash
# モデルを手動で事前ダウンロード
python -c "from comet import download_model; download_model('Unbabel/XCOMET-XL')"
```
#### GPU が検出されない
**原因**: CUDA サポート付き PyTorch がインストールされていない
**解決策**:
```bash
# CUDA の利用可能性を確認
python -c "import torch; print(torch.cuda.is_available())"
# False の場合、CUDA 付き PyTorch を再インストール
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-XL は約 8-10GB の RAM が必要
**解決策**:
1. **永続サーバーを使用**（v0.3.0+）: モデルは一度ロードされてメモリに常駐し、繰り返しのメモリスパイクを回避
2. **軽量モデルを使用**: メモリ使用量を抑えるため `XCOMET_MODEL=Unbabel/wmt22-comet-da` を設定（約 3GB）
3. **バッチサイズを削減**: 大規模バッチは小さなチャンク（100-200 ペア）で処理
4. **他のアプリケーションを閉じる**: 大規模評価の前に RAM を解放
```bash
# 利用可能なメモリを確認
free -h # Linux
vm_stat | head -5 # macOS
```
#### VS Code や IDE が評価中にクラッシュ
**原因**: xCOMET モデルの高メモリ使用量（XL は約 8-10GB）
**解決策**:
- v0.3.0+ では、モデルは一度ロードされてメモリに常駐（繰り返しロードなし）
- それでもメモリが問題なら、軽量モデルを使用: `XCOMET_MODEL=Unbabel/wmt22-comet-da`
- 評価前にメモリを大量に使用する他のアプリケーションを閉じる
### サポートを受ける
問題が発生した場合：
1. [GitHub Issues](https://github.com/shuji-bonji/xcomet-mcp-server/issues) を確認
2. Claude Desktop の開発者モードログで詳細ログを確認
3. 以下の情報を含めて新しい Issue を作成：
- OS と Python バージョン
- エラーメッセージ
- 設定（機密データを除く）
## 開発
```bash
# 依存関係をインストール
npm install
# TypeScript をビルド
npm run build
# ウォッチモード
npm run dev
# テストを実行
npm test
# MCP Inspector でテスト
npm run inspect
```
## 変更履歴
バージョン履歴と更新については [CHANGELOG.md](CHANGELOG.md) を参照してください。
## ライセンス
MIT License - 詳細は [LICENSE](LICENSE) を参照してください。
## 謝辞
- [Unbabel](https://unbabel.com/) - xCOMET モデル
- [Anthropic](https://anthropic.com/) - MCP プロトコル
- [Model Context Protocol](https://modelcontextprotocol.io/) コミュニティ
## 参考文献
- [xCOMET 論文](https://direct.mit.edu/tacl/article/doi/10.1162/tacl_a_00683/124263/xcomet-Transparent-Machine-Translation-Evaluation)
- [COMET フレームワーク](https://github.com/Unbabel/COMET)
- [MCP 仕様](https://spec.modelcontextprotocol.io/)
