xCOMET MCP Server

xCOMET MCP サーバー

日本語版 README はこちら

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

xCOMET（eXplainable COMET）を利用した翻訳品質評価用 MCP サーバーです。

🎯 概要

xCOMET MCP サーバーは、AI エージェントが機械翻訳の品質を評価できるようにします。Unbabel の xCOMET モデルと連携し、次の機能を提供します。

• 品質スコアリング：翻訳品質を示す 0～1 のスコア
• エラー検出：重大度レベル（軽微／重大／致命的）とともにエラー箇所を特定
• バッチ処理：複数の翻訳ペアを効率的に評価（モデルの読み込みを 1 回に最適化）
• GPU サポート：推論を高速化するオプションの GPU アクセラレーション

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

    style D fill:#9f9

🔧 前提条件

Python 環境

• Python 3.9～3.12 を推奨（xCOMET の依存関係が 3.13 以降をまだサポートしていません）

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.7,<3.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.7,<3.0"

Python 3.9～3.12 が必要な理由 unbabel-comet は numpy = "^1.20.0" を宣言しているため、 numpy 1.x に解決されます。最後の numpy 1.x リリースである 1.26.4 のホイールは cp39-cp312 のみを対象としています。Python 3.13 以降では、pip が numpy をソースからビルドする必要があります。

注（v0.5.0 以降）：Python ワーカーは標準入力／標準出力を介して Node.js と通信するようになりました （行区切りの JSON-RPC）。FastAPI、uvicorn、pydantic は不要になり、 必要なのは unbabel-comet のみです。

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

モデルのダウンロード

重要：XCOMET-XL と XCOMET-XXL は HuggingFace のアクセス制限付きモデルです。次の手順が必要です。

1. HuggingFace アカウントを作成します

2. Unbabel/XCOMET-XL にアクセスし、アクセスを申請します

3. CLI で認証します。

   source ~/.xcomet-venv/bin/activate
   hf auth login
   

   （huggingface-cli login も引き続き動作しますが、huggingface_hub 0.34 以降では非推奨の警告が表示されます。 hf が現在のコマンドです。）

   または、MCP ホストの env ブロックで HF_TOKEN を設定します。これは、CLI ログインを行っていない環境で ホストがサーバーを起動する場合に使用します。

   "env": {
     "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3",
     "HF_TOKEN": "hf_..."
   }
   

   huggingface_hub はまず HF_TOKEN を読み取り、次に hf auth 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')"

モデルの保存場所

仮想環境内ではありません。 仮想環境には Python パッケージが保存されます。モデルの重みは huggingface_hub のキャッシュに保存されます。これは別のディレクトリで、Hub からダウンロードするマシン上のすべてのツールで共有されます。

~/.xcomet-venv/                              ← Python packages only
└── lib/python3.x/site-packages/
    ├── comet/                               unbabel-comet itself
    └── torch/  transformers/  ...           its dependencies

~/.cache/huggingface/                        ← the model weights live here
└── hub/
    └── models--Unbabel--XCOMET-XL/
        ├── blobs/                           the actual ~14GB checkpoint
        └── snapshots/<revision>/
            ├── checkpoints/model.ckpt       what download_model() returns
            └── hparams.yaml

download_model() は cache_dir=None を snapshot_download() に渡すため、保存場所は huggingface_hub が決定します。場所は HF_HUB_CACHE で、デフォルトは HF_HOME/hub です。HF_HOME のデフォルトは $XDG_CACHE_HOME/huggingface（XDG_CACHE_HOME が設定されていない場合は ~/.cache/huggingface）です。

知っておくべき点が 3 つあります。

• 仮想環境を再構築または削除しても、モデルは再ダウンロードされません。
• 複数の仮想環境や、Hub ベースの他のツールでも同じコピーが共有されます。
• 仮想環境のディレクトリサイズには、14GB のモデルサイズは含まれません。ディスク上の実際の内容を確認するには hf cache scan を、リビジョンを削除するには hf cache delete を使用してください。

チェックポイントを別の場所（より大容量のボリュームや共有ドライブなど）に保存するには、XCOMET_SAVING_DIRECTORY（v0.7.0 以降）または標準の HF_HOME を設定してください。どちらもダウンロード時に読み取られるため、デフォルトの場所にすでにダウンロードされたモデルは移動されず、新しい場所に再度ダウンロードされます。

Node.js

• Node.js >= 22.0.0（package.json の engines.node と一致します。CI は 22 および 24 で実行されます）
• 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@latest"],
      "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@latest

グローバルインストール

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

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"
      }
    }
  }
}

🛠️ 利用可能なツール

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

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

パフォーマンスに関する注意：永続サーバーアーキテクチャ（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?

推奨ワークフロー

1. DeepL MCP Server（公式）を使用して翻訳します
2. xCOMET MCP Server を使用して評価します
3. 品質がしきい値を下回る場合は反復します

例：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@latest"],
      "env": {
        "XCOMET_PYTHON_PATH": "~/.xcomet-venv/bin/python3"
      }
    }
  }
}

次に、Claude に次のように依頼します。

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

⚙️ 設定

環境変数

変数	デフォルト	説明
XCOMET_MODEL	Unbabel/XCOMET-XL	使用する xCOMET モデル
XCOMET_PYTHON_PATH	(auto-detect)	Python 実行ファイルのパス（下記参照）
XCOMET_PRELOAD	false	起動時にモデルを事前読み込みします（v0.3.1+）
XCOMET_DEBUG	false	詳細なデバッグログを有効にします（v0.3.1+）
XCOMET_NUM_WORKERS	1	model.predict() の DataLoader ワーカー数（v0.6.0+）。特に GPU で大きなバッチを実行する際、アイドル状態の CPU コアをより有効に活用するには、この値を増やしてください。無効な値は警告なしで 1 に戻ります。
XCOMET_SAVING_DIRECTORY	(HuggingFace cache)	チェックポイントのダウンロード先ディレクトリ（v0.7.0+）。設定しない場合、モデルは huggingface_hub のキャッシュ（HF_HOME、デフォルトは ~/.cache/huggingface）に保存されます。14GB（XL）または 43GB（XXL）のチェックポイントを別のボリュームに保存するには、これを設定します。
XCOMET_LOCAL_FILES_ONLY	false	ローカルキャッシュのみからチェックポイントを取得します（v0.7.0+）。ネットワークに接続せずに起動するには true に設定します。その場合、モデルはあらかじめダウンロードされている必要があります。
HF_TOKEN	(unset)	huggingface_hub が読み取る HuggingFace アクセストークンです。アクセス制限付きモデル（XCOMET-XL、XCOMET-XXL、CometKiwi モデル）を使用する際、hf auth login の代わりに利用できます。

モデルの選択

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

モデル	パラメーター数	サイズ	メモリ	参照訳	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@latest"],
      "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 パスの明示的な設定

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

⚡ パフォーマンス

永続ワーカーアーキテクチャ（v0.3.0 以降、stdio は v0.5.0 以降）

サーバーは、xCOMET モデルをメモリに保持する永続 Python ワーカープロセスを使用します。Node.js MCP サーバーは、行区切りの JSON-RPC プロトコルを使って stdin/stdout 経由でワーカーと通信します。ローカル HTTP リスナーやポートのバインド、FastAPI は不要です。

リクエスト	時間	備考
最初のリクエスト	~25～90 秒	モデルの読み込み（モデルサイズによって異なります）
2 回目以降のリクエスト	~500ms	モデルはすでに読み込み済みです

モデルを毎回再読み込みする場合と比べて、連続評価の速度が177 倍向上します。

先行読み込み（v0.3.1 以降）

XCOMET_PRELOAD=true を有効にすると、サーバー起動時にモデルを先行読み込みします。

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

先行読み込みを有効にすると、最初のリクエストを含め、すべてのリクエストが高速になります（約 500ms）。

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

    style D fill:#9f9

バッチ処理の最適化

xcomet_batch_evaluate ツールは、1 回のモデル読み込みですべてのペアを処理します。

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

GPU と 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	低品質	再翻訳を推奨します

What the score does and does not tell you

The score answers "does this read like a translation of that source", and it is good at it. It does not answer "are the facts in this translation correct". Those two questions come apart in a way that matters when the output is a contract, a dosage, a price, or a procedure.

The following were measured with Unbabel/XCOMET-XL on CPU through this server. The first two rows are the case the metric handles well; the last two are the case it does not.

Source	Translation	Score
ファイルを保存せずに終了しますか？	Do you want to quit without saving the file?	0.956
ファイルを保存せずに終了しますか？	The mountain sings in violet every third Thursday.	0.212
保証期間は購入日から一年間です。	The warranty period is ten years from the date of purchase.	1.000
電源を切ってから、カバーを取り外してください。	Remove the cover, then turn off the power.	1.000

A translation that is unrelated to the source collapses to ~0.2, which is what you want. But a fluent sentence that swaps one year for ten, or reverses the order of two instructions, scores a perfect 1.000. Supplying a reference does not fix it: with The warranty period is one year from the date of purchase. as the reference, the "ten years" translation still scores 0.983.

This is not a defect in this server or in xCOMET specifically. It is a known property of neural MT metrics: they "struggle with detecting certain phenomena that can be considered as critical errors, such as deviations in entities and numbers" (Rei et al., 2023).

Using it accordingly

Good fits

• Ranking or triaging a set of translations — which segments to review first, which of two MT systems is better on your data.
• Catching adequacy collapse — truncated output, the wrong segment pasted in, a model that lost the thread, an untranslated passthrough.
• Tracking quality over time on a fixed test set, where the comparison is between runs rather than against an absolute bar.
• A first-pass filter ahead of human review, to decide where the human time goes.

Poor fits

• A sole release gate for content where a single wrong number or name is the failure — medical, legal, financial, safety instructions. Check numbers, dates, units, currencies, and named entities separately, with a rule that actually compares them; the score will not do it for you.
• An absolute quality claim. 0.95 is not "95% correct", and the value is not comparable across models, language pairs, or segment lengths.
• Very short segments (a UI label, a single word), where the score saturates and stops discriminating.

Use xcomet_detect_errors alongside the score. The error spans mark where the model believes something went wrong, with an MQM severity. A high score with a critical span is a more useful signal than either number alone.

🔍 Troubleshooting

Common Issues

"No module named 'comet'"

Cause: Python environment without unbabel-comet installed.

Solution:

# 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

Homebrew のアップグレード後に venv が動作しなくなった

症状：zsh: no such file or directory: .venv/bin/python3 が表示される、またはアクティブ化した venv 内の python3 が、venv のものとは異なるインタープリターを指す、あるいは昨日まで動作していた venv で No module named 'comet' が表示される。

原因：venv にインタープリターは含まれていません。作成元のインタープリターへの絶対パスのシンボリックリンクが pyvenv.cfg に記録されています。

home = /opt/homebrew/opt/[email protected]/bin
version = 3.14.3

Homebrew がそのフォーミュラをアップグレードまたは削除すると、リンクが切れて venv は使用できなくなります。lib/python3.x/site-packages/ は残っていますが、実行できるものがありません。

確認方法：

ls -l .venv/bin/python3 && .venv/bin/python3 -V
cat .venv/pyvenv.cfg

解決方法：venv を作り直します。uv venv --python 3.12 のほうが長期的に安定した方法です。Homebrew の現在のインタープリターを借りるのではなく、uv 自体がインタープリターを取得し、固定するためです。

rm -rf .venv
uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install "unbabel-comet>=2.2.7,<3.0"

パッケージの再インストールには数百 MB かかりますが、モデルは再ダウンロードされません。チェックポイントは venv ではなく huggingface_hub のキャッシュに保存されています（モデルの保存場所を参照）。

アップグレード後に古いバージョンが起動する

症状：公開済みのはずの修正が、実行中のサーバーに反映されていません。ログの起動バナーに古いバージョンが表示されています。

grep "running on stdio" ~/Library/Logs/Claude/mcp-server-xcomet.log | tail -1
xcomet-mcp-server v0.6.3 running on stdio

（macOS では、Claude Desktop は各 MCP サーバーの stderr を ~/Library/Logs/Claude/mcp-server-<name>.log に書き込みます。）

原因：npx は npm のキャッシュされたレジストリメタデータから latest を解決し、すでに ~/.npm/_npx にインストールされているコピーを実行します。リリース後しばらくは、そのコピーが以前のバージョンのままです。いずれ自動的に更新されますが、更新のタイミングは選べません。@latest を付けても状況は変わりません。npm では、バージョンを指定しないのと同じ意味だからです。

解決方法：npx のキャッシュを消去してから、MCP ホストを再起動します。

rm -rf ~/.npm/_npx

ps を使うと、実行中のコピーと、そのコピーがどのキャッシュディレクトリにあるかを確認できます。

ps -axo pid,command | grep xcomet-mcp-server | grep -v grep

既知のビルドを使い続けるには、[email protected] のように正確なバージョンを指定してください。

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

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

解決方法：

# Authenticate with HuggingFace (required for XCOMET-XL/XXL)
hf auth login          # or: export HF_TOKEN=hf_...

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

ダウンロードが中断されると、キャッシュには checkpoints/model.ckpt がないスナップショットディレクトリが残ります。サーバーはそのパスを表示してディレクトリの削除を求めます。hf cache scan を使うと、その場所を確認できます。

GPU が検出されない

原因：PyTorch が CUDA 対応なしでインストールされています。

解決方法：

# 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-XL には約 8～10GB の RAM が必要です。

解決方法：

1. 永続サーバーを使用する（v0.3.0+）：モデルを一度だけ読み込み、メモリに保持するため、メモリ使用量が繰り返し急増するのを防げます
2. 軽量なモデルを使用する：XCOMET_MODEL=Unbabel/wmt22-comet-da を設定すると、メモリ使用量を抑えられます（約 3GB）
3. バッチサイズを小さくする：大きなバッチは、より小さいチャンク（100～200 ペア）に分けて処理します
4. ほかのアプリケーションを終了する：大規模な評価を実行する前に RAM を空けてください

# Check available memory
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を確認します
2. デバッグログを有効にします（Claude Desktop の Developer Mode のログを確認するか、XCOMET_DEBUG=true を設定します）
3. 次の情報を添えて新しい issue を作成します。
   • OS と Python のバージョン
   • エラーメッセージ
   • 設定（機密情報は含めないでください）

🧪 開発

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run tests (Vitest)
npm test

# Run the Python-side tests (pytest only — no comet, no model)
npm run test:python

# Test with MCP Inspector
npm run inspect

npm run test:python は python3 -m pytest を呼び出すため、PATH 上にある python3 から pytest をインポートできる必要があります。xCOMET の仮想環境を有効にしても、そこに pytest がインストールされていなければ役に立ちません。次のいずれかの方法で実行できます。

uvx pytest tests/test_server.py -q                    # nothing to install
~/.xcomet-venv/bin/python -m pip install pytest       # add it to the xCOMET venv
python3 -m venv .venv-dev && .venv-dev/bin/pip install pytest

tests/README.md では、すべてのテストスイートとその対象、実施する理由を説明しています。

📋 変更履歴

バージョン履歴と更新については、CHANGELOG.md をご覧ください。

📝 ライセンス

MIT ライセンスです。詳細は LICENSE をご覧ください。

🙏 謝辞

• xCOMET モデルを提供してくださった Unbabel
• MCP プロトコルを提供してくださった Anthropic
• Model Context Protocol コミュニティ

📚 参考資料

• xCOMET 論文
• COMET フレームワーク
• BLEU Meets COMET（Rei ほか、2023） — ニューラル評価指標がエンティティや数値の誤りを見逃す問題について。スコアが示すこと、示さないことの根拠となった資料です。
• Hugging Face Hub のキャッシュ構成
• MCP 仕様