xCOMET MCP Server

Hier geht es zur englischen README

⚠️ Dies ist ein inoffizielles Community-Projekt, das nicht mit Unbabel verbunden ist.

MCP-Server zur Bewertung der Übersetzungsqualität, basierend auf xCOMET (eXplainable COMET).

🎯 Übersicht

xCOMET MCP Server bietet KI-Agenten die Möglichkeit, die Qualität maschineller Übersetzungen zu bewerten. Er lässt sich in das xCOMET-Modell von Unbabel integrieren und bietet:

• Qualitätsbewertung: Scores zwischen 0-1 zur Angabe der Übersetzungsqualität

• Fehlererkennung: Identifiziert Fehlerbereiche mit Schweregraden (gering/mittel/kritisch)

• Stapelverarbeitung: Effiziente Bewertung mehrerer Übersetzungspaare (optimiertes Laden des Modells)

• GPU-Unterstützung: Optionale GPU-Beschleunigung für schnellere Inferenz

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

🔧 Voraussetzungen

Python-Umgebung

• Python 3.9 - 3.12 empfohlen (3.13+ wird von xCOMET-Abhängigkeiten noch nicht unterstützt)

xCOMET benötigt Python mit mehreren Paketen. Wir empfehlen die Verwendung einer virtuellen Umgebung:

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

Hinweis: Wenn Sie Claude Desktop oder andere MCP-Hosts verwenden, setzen Sie XCOMET_PYTHON_PATH auf den Pfad zum Python der virtuellen Umgebung (siehe Konfiguration).

Modell-Download

Wichtig: XCOMET-XL und XCOMET-XXL sind gated models auf HuggingFace. Sie müssen:

1. Ein HuggingFace-Konto erstellen

2. Unbabel/XCOMET-XL besuchen und Zugriff anfordern

3. Über CLI anmelden:

   source ~/.xcomet-venv/bin/activate
   huggingface-cli login

Unbabel/wmt22-comet-da erfordert keine Authentifizierung (benötigt jedoch Referenzübersetzungen).

Nach der Authentifizierung laden Sie das Modell herunter (~14GB für XL, ~42GB für XXL):

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 oder yarn

📦 Installation

Hinweis: Wenn Sie den xCOMET MCP Server nur verwenden möchten, müssen Sie dieses Repository nicht klonen. Installieren Sie die Python-Umgebung und das Modell (siehe Voraussetzungen) und verwenden Sie dann npx (siehe Verwendung). Der folgende Abschnitt ist nur für Mitwirkende und die lokale Entwicklung gedacht.

Lokale Entwicklung

Für Mitwirkende und die lokale Entwicklung:

# 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

🚀 Verwendung

Mit Claude Desktop (npx)

Fügen Sie dies Ihrer Claude Desktop-Konfiguration (claude_desktop_config.json) hinzu:

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

Tipp: Wenn Sie Python-Pakete systemweit installiert haben oder pyenv verwenden, kann XCOMET_PYTHON_PATH weggelassen werden (die automatische Erkennung findet es). Details finden Sie unter Automatische Erkennung des Python-Pfads.

Mit Claude Code

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

Globale Installation

Wenn Sie eine globale Installation bevorzugen:

npm install -g xcomet-mcp-server

Dann konfigurieren:

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

Build für lokale Entwicklung

Wenn Sie das Repository lokal geklont und gebaut haben (siehe Installation):

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

HTTP-Modus (Fernzugriff)

TRANSPORT=http PORT=3000 npm start

Verbinden Sie sich dann mit http://localhost:3000/mcp

🛠️ Verfügbare Tools

xcomet_evaluate

Bewertet die Übersetzungsqualität für ein einzelnes Quell-Übersetzungs-Paar.

Parameter:

Beispiel:

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

Antwort:

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

xcomet_detect_errors

Konzentriert sich auf das Erkennen und Kategorisieren von Übersetzungsfehlern.

Parameter:

xcomet_batch_evaluate

Bewertet mehrere Übersetzungspaare in einer einzigen Anfrage.

Performance-Hinweis: Mit der persistenten Serverarchitektur (v0.3.0+) bleibt das Modell im Arbeitsspeicher geladen. Die Stapelverarbeitung bewertet alle Paare effizient, ohne das Modell neu zu laden.

Parameter:

Beispiel:

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

🔗 Integration mit anderen MCP-Servern

xCOMET MCP Server ist darauf ausgelegt, für vollständige Übersetzungsworkflows mit anderen MCP-Servern zusammenzuarbeiten:

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?

Empfohlener Workflow

1. Übersetzen mit DeepL MCP Server (offiziell)

2. Bewerten mit xCOMET MCP Server

3. Iterieren, falls die Qualität unter dem Schwellenwert liegt

Beispiel: DeepL + xCOMET Integration

Konfigurieren Sie beide Server in 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"
      }
    }
  }
}

Fragen Sie dann Claude:

"Übersetze diesen Text mit DeepL ins Japanische und bewerte dann die Übersetzungsqualität mit xCOMET. Wenn der Score unter 0,8 liegt, schlage Verbesserungen vor."

⚙️ Konfiguration

Umgebungsvariablen

Modellauswahl

Wählen Sie das Modell basierend auf Ihren Qualitäts-/Leistungsanforderungen:

Wichtig: XCOMET-XL und XCOMET-XXL sind gated models auf HuggingFace. Jedes Modell erfordert eine separate Zugriffsgenehmigung. Siehe Modell-Download für die Authentifizierungseinrichtung.

Wichtig: wmt22-comet-da erfordert eine reference-Übersetzung zur Bewertung. XCOMET-Modelle unterstützen referenzlose Bewertung.

Tipp: Wenn Sie Speicherprobleme oder langsames Laden des Modells feststellen, versuchen Sie Unbabel/wmt22-comet-da für eine schnellere Leistung bei etwas geringerer Genauigkeit (denken Sie aber daran, Referenzübersetzungen bereitzustellen).

Um ein anderes Modell zu verwenden, setzen Sie die Umgebungsvariable XCOMET_MODEL:

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

Automatische Erkennung des Python-Pfads

Der Server erkennt automatisch eine Python-Umgebung, in der unbabel-comet installiert ist:

1. XCOMET_PYTHON_PATH Umgebungsvariable (falls gesetzt)

2. pyenv Versionen (~/.pyenv/versions/*/bin/python3) - prüft auf comet-Modul

3. Homebrew Python (/opt/homebrew/bin/python3, /usr/local/bin/python3)

4. Fallback: python3 Befehl

Dies stellt sicher, dass der Server korrekt funktioniert, auch wenn der MCP-Host (z. B. Claude Desktop) ein anderes Python verwendet als Ihr Terminal.

Beispiel: Explizite Konfiguration des Python-Pfads

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

⚡ Performance

Persistente Serverarchitektur (v0.3.0+)

Der Server verwendet einen persistenten Python FastAPI-Server, der das xCOMET-Modell im Arbeitsspeicher geladen hält:

Dies bietet eine 177-fache Beschleunigung für aufeinanderfolgende Bewertungen im Vergleich zum jedes Mal erneuten Laden des Modells.

Eager Loading (v0.3.1+)

Aktivieren Sie XCOMET_PRELOAD=true, um das Modell beim Serverstart vorzuladen:

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

Mit aktiviertem Preload sind alle Anfragen schnell (~500ms), einschließlich der ersten.

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

Optimierung der Stapelverarbeitung

Das Tool xcomet_batch_evaluate verarbeitet alle Paare mit einem einzigen Modell-Ladevorgang:

GPU vs CPU Performance

Hinweis: GPU erfordert CUDA-kompatible Hardware und PyTorch mit CUDA-Unterstützung. Wenn keine GPU verfügbar ist, setzen Sie use_gpu: false (Standard).

Best Practices

1. Lassen Sie den persistenten Server seine Arbeit tun

Mit v0.3.0+ bleibt das Modell im Speicher. Mehrere xcomet_evaluate-Aufrufe sind jetzt effizient:

✅ 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. Verwenden Sie für viele Paare die Stapelbewertung

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

3. Speicherüberlegungen

• XCOMET-XL benötigt ~8-10GB RAM

• Stellen Sie bei großen Stapeln (500 Paare) sicher, dass genügend Speicher vorhanden ist

• Wenn der Speicher begrenzt ist, teilen Sie ihn in kleinere Stapel auf (100-200 Paare)

Automatischer Neustart (v0.3.1+)

Der Server erholt sich automatisch von Fehlern:

• Überwacht den Status alle 30 Sekunden

• Startet nach 3 aufeinanderfolgenden fehlgeschlagenen Gesundheitsprüfungen neu

• Bis zu 3 Neustartversuche, bevor aufgegeben wird

📊 Interpretation des Qualitätsscores

🔍 Fehlerbehebung

Häufige Probleme

"No module named 'comet'"

Ursache: Python-Umgebung ohne installiertes unbabel-comet.

Lösung:

# 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

Modell-Download schlägt fehl oder Zeitüberschreitung

Ursache: Große Modelldateien (~14GB für XL) erfordern eine stabile Internetverbindung. XCOMET-Modelle erfordern außerdem eine