Servidor MCP xCOMET

日本語版 README はこちら

⚠️ Este es un proyecto comunitario no oficial, no afiliado a Unbabel.

Servidor MCP de evaluación de calidad de traducción impulsado por xCOMET (eXplainable COMET).

🎯 Descripción general

xCOMET MCP Server proporciona a los agentes de IA la capacidad de evaluar la calidad de la traducción automática. Se integra con el modelo xCOMET de Unbabel para proporcionar:

• Puntuación de calidad: Puntuaciones entre 0 y 1 que indican la calidad de la traducción.

• Detección de errores: Identifica segmentos con errores y niveles de gravedad (menor/mayor/crítico).

• Procesamiento por lotes: Evalúa múltiples pares de traducción de manera eficiente (carga optimizada de un solo modelo).

• Soporte para GPU: Aceleración opcional por GPU para una inferencia más rápida.

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

🔧 Requisitos previos

Entorno de Python

• Se recomienda Python 3.9 - 3.12 (3.13+ aún no es compatible con las dependencias de xCOMET).

xCOMET requiere Python con varios paquetes. Recomendamos usar un entorno virtual:

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

Nota: Cuando lo utilice con Claude Desktop u otros hosts MCP, establezca XCOMET_PYTHON_PATH para que apunte al Python del entorno virtual (consulte Configuración).

Descarga del modelo

Importante: XCOMET-XL y XCOMET-XXL son modelos restringidos en HuggingFace. Debe:

1. Crear una cuenta en HuggingFace.

2. Visitar Unbabel/XCOMET-XL y solicitar acceso.

3. Iniciar sesión a través de la CLI:

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

Unbabel/wmt22-comet-da no requiere autenticación (pero requiere traducciones de referencia).

Después de la autenticación, descargue el modelo (~14 GB para XL, ~42 GB para 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 o yarn

📦 Instalación

Nota: Si solo desea usar el servidor MCP xCOMET, no necesita clonar este repositorio. Instale el entorno de Python y el modelo (consulte Requisitos previos), luego use npx (consulte Uso). La siguiente sección es solo para colaboradores y desarrollo local.

Desarrollo local

Para colaboradores y desarrollo local:

# 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

🚀 Uso

Con Claude Desktop (npx)

Añada a su configuración de Claude Desktop (claude_desktop_config.json):

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

Consejo: Si instaló paquetes de Python en todo el sistema o usa pyenv, puede omitir XCOMET_PYTHON_PATH (la detección automática lo encontrará). Consulte Detección automática de la ruta de Python para obtener más detalles.

Con Claude Code

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

Instalación global

Si prefiere instalarlo globalmente:

npm install -g xcomet-mcp-server

Luego configure:

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

Compilación para desarrollo local

Si clonó y compiló el repositorio localmente (consulte Instalación):

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

Modo HTTP (Acceso remoto)

TRANSPORT=http PORT=3000 npm start

Luego conéctese a http://localhost:3000/mcp

🛠️ Herramientas disponibles

xcomet_evaluate

Evalúa la calidad de la traducción para un solo par de origen-traducción.

Parámetros:

Ejemplo:

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

Respuesta:

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

xcomet_detect_errors

Se centra en detectar y categorizar errores de traducción.

Parámetros:

xcomet_batch_evaluate

Evalúa múltiples pares de traducción en una sola solicitud.

Nota de rendimiento: Con la arquitectura de servidor persistente (v0.3.0+), el modelo permanece cargado en la memoria. La evaluación por lotes procesa todos los pares de manera eficiente sin recargar el modelo.

Parámetros:

Ejemplo:

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

🔗 Integración con otros servidores MCP

xCOMET MCP Server está diseñado para funcionar junto con otros servidores MCP para flujos de trabajo de traducción completos:

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?

Flujo de trabajo recomendado

1. Traducir usando el servidor MCP de DeepL (oficial)

2. Evaluar usando el servidor MCP de xCOMET

3. Iterar si la calidad está por debajo del umbral

Ejemplo: Integración DeepL + xCOMET

Configure ambos servidores en 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"
      }
    }
  }
}

Luego pregúntele a Claude:

"Traduce este texto al japonés usando DeepL, luego evalúa la calidad de la traducción con xCOMET. Si la puntuación es inferior a 0.8, sugiere mejoras."

⚙️ Configuración

Variables de entorno

Selección de modelo

Elija el modelo según sus necesidades de calidad/rendimiento:

Importante: XCOMET-XL y XCOMET-XXL son modelos restringidos en HuggingFace. Cada modelo requiere una aprobación de acceso por separado. Consulte Descarga del modelo para la configuración de autenticación.

Importante: wmt22-comet-da requiere una traducción de referencia para la evaluación. Los modelos XCOMET admiten la evaluación sin referencia.

Consejo: Si experimenta problemas de memoria o carga lenta del modelo, pruebe Unbabel/wmt22-comet-da para un rendimiento más rápido con una precisión ligeramente menor (pero recuerde proporcionar traducciones de referencia).

Para usar un modelo diferente, establezca la variable de entorno XCOMET_MODEL:

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

Detección automática de la ruta de Python

El servidor detecta automáticamente un entorno de Python con unbabel-comet instalado:

1. Variable de entorno XCOMET_PYTHON_PATH (si está establecida)

2. Versiones de pyenv (~/.pyenv/versions/*/bin/python3) - comprueba el módulo comet

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

4. Respaldo: comando python3

Esto garantiza que el servidor funcione correctamente incluso cuando el host MCP (por ejemplo, Claude Desktop) utiliza un Python diferente al de su terminal.

Ejemplo: Configuración explícita de la ruta de Python

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

⚡ Rendimiento

Arquitectura de servidor persistente (v0.3.0+)

El servidor utiliza un servidor FastAPI de Python persistente que mantiene el modelo xCOMET cargado en la memoria:

Esto proporciona una aceleración de 177x para evaluaciones consecutivas en comparación con recargar el modelo cada vez.

Carga anticipada (v0.3.1+)

Habilite XCOMET_PRELOAD=true para precargar el modelo al iniciar el servidor:

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

Con la precarga habilitada, todas las solicitudes son rápidas (~500ms), incluida la primera.

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

Optimización del procesamiento por lotes

La herramienta xcomet_batch_evaluate procesa todos los pares con una sola carga de modelo:

Rendimiento GPU vs CPU

Nota: La GPU requiere hardware compatible con CUDA y PyTorch con soporte CUDA. Si la GPU no está disponible, establezca use_gpu: false (predeterminado).

Mejores prácticas

1. Deje que el servidor persistente haga su trabajo

Con v0.3.0+, el modelo permanece en la memoria. Varias llamadas a xcomet_evaluate ahora son eficientes:

✅ 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. Para muchos pares, use la evaluación por lotes

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

3. Consideraciones de memoria

• XCOMET-XL requiere ~8-10GB de RAM

• Para lotes grandes (500 pares), asegúrese de tener suficiente memoria

• Si la memoria es limitada, divida en lotes más pequeños (100-200 pares)

Reinicio automático (v0.3.1+)

El servidor se recupera automáticamente de los fallos:

• Supervisa el estado cada 30 segundos

• Se reinicia después de 3 fallos consecutivos en la comprobación de estado

• Hasta 3 intentos de reinicio antes de rendirse

📊 Interpretación de la puntuación de calidad

🔍 Solución de problemas

Problemas comunes

"No module named 'comet'"

Causa: Entorno de Python sin unbabel-comet instalado.

Solución:

# 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

La descarga del modelo falla o se agota el tiempo de espera

Causa: Los archivos de modelo grandes (~14GB para XL) requieren una conexión a Internet estable. Los modelos XCOMET también requieren autenticación de HuggingFace (consulte Descarga del modelo).

Solución:

# 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 no detectada

Causa: PyTorch no instalado con soporte CUDA.

**Solución