xcomet-mcp-server

Servidor MCP xCOMET

日本語版 README はこちら

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

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

🎯 Descripción general

El Servidor MCP xCOMET 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-1 que indican la calidad de la traducción
• Detección de errores: Identifica tramos de error con niveles de gravedad (menor/grave/crítico)
• Procesamiento por lotes: Evalúa múltiples pares de traducción de manera eficiente (carga de modelo único optimizada)
• Soporte GPU: Aceleración opcional por GPU para una inferencia más rápida

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

🔧 Requisitos previos

Entorno Python

• Python 3.9 - 3.12 recomendado (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.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"

¿Por qué Python 3.9-3.12? unbabel-comet declara numpy = "^1.20.0", por lo que resuelve numpy 1.x. La última versión de numpy 1.x, 1.26.4, incluye wheels para cp39-cp312 únicamente. En Python 3.13 o posterior, pip tiene que compilar numpy desde el código fuente.

Nota (v0.5.0+): El worker de Python ahora se comunica con Node.js a través de stdin/stdout (JSON-RPC delimitado por líneas). FastAPI, uvicorn y pydantic ya no son necesarios — solo unbabel-comet lo es.

Nota: Cuando se use con Claude Desktop u otros hosts MCP, configure XCOMET_PYTHON_PATH para que apunte al Python del venv (consulte Configuración).

Descarga del modelo

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

1. Crear una cuenta de HuggingFace

2. Visitar Unbabel/XCOMET-XL y solicitar acceso

3. Autenticarse, ya sea mediante la CLI:

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

   (huggingface-cli login todavía funciona pero muestra una advertencia de obsolescencia desde huggingface_hub 0.34; hf es el comando actual.)

   O configurando HF_TOKEN en el bloque env del host MCP, que es la opción cuando el host lanza el servidor en un entorno donde no se ha realizado ningún inicio de sesión por CLI:

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

   huggingface_hub lee HF_TOKEN primero y recurre al archivo de token escrito por hf auth login.

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

Después de la autenticación, descargue el modelo (~14GB para XL, ~42GB para XXL):

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

Dónde se almacena el modelo

No en el entorno virtual. El venv contiene los paquetes de Python; los pesos del modelo van a la caché de huggingface_hub, que es un directorio separado compartido por cada herramienta en la máquina que descarga del 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() pasa cache_dir=None a snapshot_download(), por lo que huggingface_hub elige la ubicación: HF_HUB_CACHE, que por defecto es HF_HOME/hub, donde HF_HOME por defecto es $XDG_CACHE_HOME/huggingface (~/.cache/huggingface cuando XDG_CACHE_HOME no está configurado).

Tres consecuencias que vale la pena conocer:

• Reconstruir o eliminar el venv no vuelve a descargar el modelo.
• Varios venv y otras herramientas basadas en Hub comparten la misma copia.
• El tamaño del directorio del venv no incluye los 14GB. Use hf cache scan para ver lo que realmente está en disco, y hf cache delete para eliminar una revisión.

Para colocar el checkpoint en otro lugar — un volumen más grande, una unidad compartida — configure XCOMET_SAVING_DIRECTORY (v0.7.0+) o el estándar HF_HOME. Ambos se leen en el momento de la descarga, por lo que un modelo ya descargado en la ubicación predeterminada no se mueve; se descarga nuevamente en la nueva ubicación.

Node.js

• Node.js >= 22.0.0 (coincide con engines.node en package.json; CI se ejecuta en 22 y 24)
• npm o yarn

📦 Instalación

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

Desarrollo local

Para contribuyentes 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)

Agregue a su configuración de Claude Desktop (claude_desktop_config.json):

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

Consejo: Si instaló los paquetes de Python a nivel de sistema o usa pyenv, XCOMET_PYTHON_PATH puede omitirse (la detección automática lo encontrará). Consulte Detección automática de ruta de Python para más detalles.

Con Claude Code

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

Instalación global

Si prefiere instalar 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 de 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"
      }
    }
  }
}

🛠️ Herramientas disponibles

xcomet_evaluate

Evalúa la calidad de traducción para un único par fuente-traducción.

Parámetros:

Nombre	Tipo	Requerido	Descripción
source	string	✅	Texto fuente original
translation	string	✅	Texto traducido a evaluar
reference	string	❌	Traducción de referencia
source_lang	string	❌	Código de idioma fuente (ISO 639-1)
target_lang	string	❌	Código de idioma destino (ISO 639-1)
response_format	"json" | "markdown"	❌	Formato de salida (predeterminado: "json")
use_gpu	boolean	❌	Usar GPU para inferencia (predeterminado: false)

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:

Nombre	Tipo	Requerido	Descripción
source	string	✅	Texto fuente original
translation	string	✅	Texto traducido a analizar
reference	string	❌	Traducción de referencia
min_severity	"minor" | "major" | "critical"	❌	Gravedad mínima (predeterminado: "minor")
response_format	"json" | "markdown"	❌	Formato de salida
use_gpu	boolean	❌	Usar GPU para inferencia (predeterminado: false)

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 memoria. La evaluación por lotes procesa todos los pares de manera eficiente sin recargar el modelo.

Parámetros:

Nombre	Tipo	Requerido	Descripción
pairs	array	✅	Matriz de {source, translation, reference?} (máx. 500)
source_lang	string	❌	Código de idioma fuente
target_lang	string	❌	Código de idioma destino
response_format	"json" | "markdown"	❌	Formato de salida
use_gpu	boolean	❌	Usar GPU para inferencia (predeterminado: false)
batch_size	number	❌	Tamaño de lote 1-64 (predeterminado: 8). Más grande = más rápido pero usa más memoria

Ejemplo:

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

🔗 Integración con otros servidores MCP

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

Luego pídale 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

Variable	Predeterminado	Descripción
XCOMET_MODEL	Unbabel/XCOMET-XL	Modelo xCOMET a usar
XCOMET_PYTHON_PATH	(detección automática)	Ruta del ejecutable de Python (ver más abajo)
XCOMET_PRELOAD	false	Precargar el modelo al inicio (v0.3.1+)
XCOMET_DEBUG	false	Habilitar registro de depuración detallado (v0.3.1+)
XCOMET_NUM_WORKERS	1	Workers de DataLoader para model.predict() (v0.6.0+). Aumente para aprovechar mejor los núcleos de CPU inactivos al ejecutar lotes grandes, especialmente en GPU. Los valores no válidos recurren silenciosamente a 1.
XCOMET_SAVING_DIRECTORY	(caché de HuggingFace)	Directorio para descargar el checkpoint (v0.7.0+). Si no se configura, el modelo va a la caché de huggingface_hub (HF_HOME, predeterminado ~/.cache/huggingface). Configúrelo para colocar un checkpoint de 14GB (XL) o 43GB (XXL) en otro volumen.
XCOMET_LOCAL_FILES_ONLY	false	Resolver el checkpoint solo desde la caché local (v0.7.0+). Configúrelo en true para iniciar sin acceso a la red; el modelo ya debe estar descargado.
HF_TOKEN	(sin configurar)	Token de acceso de HuggingFace, leído por huggingface_hub. Una alternativa a hf auth login para los modelos restringidos (XCOMET-XL, XCOMET-XXL, los modelos CometKiwi).

Selección del modelo

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

Modelo	Parámetros	Tamaño	Memoria	Referencia	Autenticación HF	Calidad	Caso de uso
Unbabel/XCOMET-XL	3.5B	~14GB	~8-10GB	Opcional	✅ Requerida	⭐⭐⭐⭐	Recomendado para la mayoría de los casos de uso
Unbabel/XCOMET-XXL	10.7B	~42GB	~20GB	Opcional	✅ Requerida	⭐⭐⭐⭐⭐	Máxima calidad, requiere más recursos
Unbabel/wmt22-comet-da	580M	~2GB	~3GB	Requerida	No requerida	⭐⭐⭐	Ligero, carga más rápida

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

Importante: wmt22-comet-da requiere una traducción reference para la evaluación. Los modelos XCOMET admiten 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, configure la variable de entorno XCOMET_MODEL:

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

Detección automática de ruta de Python

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

1. Variable de entorno XCOMET_PYTHON_PATH (si está configurada)
2. Versiones de pyenv (~/.pyenv/versions/*/bin/python3) - verifica 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) usa 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@latest"],
      "env": {
        "XCOMET_PYTHON_PATH": "/Users/you/.pyenv/versions/3.11.0/bin/python3"
      }
    }
  }
}

⚡ Rendimiento

Arquitectura de worker persistente (v0.3.0+, stdio desde v0.5.0)

El servidor usa un proceso worker de Python persistente que mantiene el modelo xCOMET cargado en memoria. El servidor MCP de Node.js se comunica con el worker a través de stdin/stdout usando un protocolo JSON-RPC delimitado por líneas — sin listener HTTP local, sin enlace de puerto, sin FastAPI.

Solicitud	Tiempo	Notas
Primera solicitud	~25-90s	Carga del modelo (varía según el tamaño del modelo)
Solicitudes posteriores	~500ms	Modelo ya cargado

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 inicio del servidor:

{
  "mcpServers": {
    "xcomet": {
      "command": "npx",
      "args": ["-y", "xcomet-mcp-server@latest"],
      "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 -- stdio JSON-RPC --> C[Python Worker]
    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 del modelo:

Pares	Tiempo estimado
10	~30-40 seg
50	~1-1.5 min
100	~2 min

Rendimiento GPU vs CPU

Modo	100 pares (estimado)
CPU (batch_size=8)	~2 min
GPU (batch_size=16)	~20-30 seg

Nota: GPU requiere hardware compatible con CUDA y PyTorch con soporte CUDA. Si 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 memoria. Múltiples llamadas 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 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), asegure memoria suficiente
• 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 fallos:

• Monitorea la salud cada 30 segundos
• Se reinicia después de 3 fallos consecutivos en la verificación de salud
• Hasta 3 intentos de reinicio antes de rendirse

📊 Interpretación de la puntuación de calidad

Rango de puntuación	Calidad	Recomendación
0.9 - 1.0	Excelente	Listo para usar
0.7 - 0.9	Buena	Revisión menor recomendada
0.5 - 0.7	Aceptable	Se necesita posedición
0.0 - 0.5	Deficiente	Se recomienda retraducción

Qué dice y qué no dice la puntuación

La puntuación responde a "¿esto se lee como una traducción de esa fuente?", y es buena en eso. No responde a "¿los hechos en esta traducción son correctos?". Esas dos preguntas se separan de una manera que importa cuando el resultado es un contrato, una dosis, un precio o un procedimiento.

Lo siguiente se midió con Unbabel/XCOMET-XL en CPU a través de este servidor. Las dos primeras filas son el caso que la métrica maneja bien; las dos últimas son el caso que no maneja.

Fuente	Traducción	Puntuación
ファイルを保存せずに終了しますか？	¿Quieres salir sin guardar el archivo?	0.956
ファイルを保存せずに終了しますか？	La montaña canta en violeta cada tercer jueves.	0.212
保証期間は購入日から一年間です。	El período de garantía es de diez años desde la fecha de compra.	1.000
電源を切ってから、カバーを取り外してください。	Retire la cubierta y luego apague la alimentación.	1.000

Una traducción que no está relacionada con la fuente cae a ~0.2, que es lo que usted quiere. Pero una oración fluida que cambia un año por diez, o invierte el orden de dos instrucciones, obtiene una puntuación perfecta de 1.000. Proporcionar una referencia no lo soluciona: con The warranty period is one year from the date of purchase. como referencia, la traducción de "diez años" aún obtiene 0.983.

Esto no es un defecto de este servidor ni de xCOMET específicamente. Es una propiedad conocida de las métricas neuronales de MT: "tienen dificultades para detectar ciertos fenómenos que pueden considerarse errores críticos, como desviaciones en entidades y números" (Rei et al., 2023).

Uso en consecuencia

Buenos usos

• Clasificar o priorizar un conjunto de traducciones: qué segmentos revisar primero, cuál de dos sistemas de MT es mejor en sus datos.
• Detectar colapso de adecuación: salida truncada, segmento incorrecto pegado, un modelo que perdió el hilo, un passthrough sin traducir.
• Seguimiento de la calidad a lo largo del tiempo en un conjunto de prueba fijo, donde la comparación es entre ejecuciones en lugar de contra una barra absoluta.
• Un filtro de primera pasada antes de la revisión humana, para decidir dónde va el tiempo humano.

Malos usos

• Una única puerta de liberación para contenido donde un solo número o nombre incorrecto es el fallo: instrucciones médicas, legales, financieras, de seguridad. Verifique números, fechas, unidades, monedas y entidades nombradas por separado, con una regla que realmente los compare; la puntuación no lo hará por usted.
• Una afirmación de calidad absoluta. 0.95 no es "95% correcto", y el valor no es comparable entre modelos, pares de idiomas o longitudes de segmento.
• Segmentos muy cortos (una etiqueta de interfaz, una sola palabra), donde la puntuación se satura y deja de discriminar.

Use xcomet_detect_errors junto con la puntuación. Los tramos de error marcan dónde cree el modelo que algo salió mal, con una severidad MQM. Una puntuación alta con un tramo critical es una señal más útil que cualquiera de los dos números por separado.

🔍 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

El venv dejó de funcionar después de una actualización de Homebrew

Síntoma: zsh: no such file or directory: .venv/bin/python3, o python3 dentro de un venv activado que resuelve a un intérprete diferente al del venv, o No module named 'comet' en un venv que funcionaba ayer.

Causa: Un venv no contiene un intérprete: almacena un enlace simbólico absoluto al que se creó, registrado en pyvenv.cfg:

home = /opt/homebrew/opt/python@3.14/bin
version = 3.14.3

Cuando Homebrew actualiza o elimina esa fórmula, el enlace queda colgando y el venv está muerto. lib/python3.x/site-packages/ sigue ahí, pero nada puede ejecutarlo.

Verificación:

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

Solución: recréelo. uv venv --python 3.12 es la forma más duradera, porque uv obtiene y fija ese intérprete por sí mismo en lugar de tomar prestado el actual de Homebrew.

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

Reinstalar los paquetes son unos pocos cientos de MB, pero el modelo no se vuelve a descargar: el checkpoint vive en la caché de huggingface_hub, no en el venv (consulte Dónde se almacena el modelo).

Una versión antigua se inicia después de una actualización

Síntoma: una corrección que sabe que está publicada falta en el servidor en ejecución. El banner de inicio en el registro nombra una versión anterior.

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

(En macOS, Claude Desktop escribe el stderr de cada servidor MCP en ~/Library/Logs/Claude/mcp-server-<name>.log.)

Causa: npx resuelve latest desde los metadatos de registro en caché de npm, y ejecuta la copia que ya instaló bajo ~/.npm/_npx. Durante un tiempo después de un lanzamiento, esa copia es la versión anterior. Se pone al día por sí sola, pero no en un momento que usted elija. @latest no cambia esto: para npm significa lo mismo que escribir sin versión alguna.

Solución: limpie la caché de npx y luego reinicie el host MCP.

rm -rf ~/.npm/_npx

ps muestra qué copia se está ejecutando y de qué directorio de caché proviene.

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

Para mantenerse en una compilación conocida, fije una versión exacta: xcomet-mcp-server@0.7.0.

La descarga del modelo falla o se agota el tiempo

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:

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

Si la descarga se interrumpió, la caché conserva un directorio de instantánea sin checkpoints/model.ckpt en él. El servidor informa esa ruta y le pide que elimine el directorio; hf cache scan enumera dónde está.

GPU no detectada

Causa: PyTorch no instalado con soporte CUDA.

Solución:

# 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

Rendimiento lento en Mac (MPS)

Causa: Mac MPS (Metal Performance Shaders) tiene problemas de compatibilidad con algunas operaciones.

Solución: El servidor usa automáticamente num_workers=1 para compatibilidad con Mac MPS. Para un mejor rendimiento en Mac, use el modo CPU (use_gpu: false).

Alto uso de memoria o fallos

Causa: XCOMET-XL requiere ~8-10GB de RAM.

Soluciones:

1. Use el servidor persistente (v0.3.0+): El modelo se carga una vez y permanece en memoria, evitando picos de memoria repetidos
2. Use un modelo más ligero: Establezca XCOMET_MODEL=Unbabel/wmt22-comet-da para un menor uso de memoria (~3GB)
3. Reduzca el tamaño del lote: Para lotes grandes, procese en fragmentos más pequeños (100-200 pares)
4. Cierre otras aplicaciones: Libere RAM antes de ejecutar evaluaciones grandes

# Check available memory
free -h  # Linux
vm_stat | head -5  # macOS

VS Code o IDE se bloquea durante la evaluación

Causa: Alto uso de memoria del modelo xCOMET (~8-10GB para XL).

Solución:

• Con v0.3.0+, el modelo se carga una vez y permanece en memoria (sin carga repetida)
• Si la memoria sigue siendo un problema, use un modelo más ligero: XCOMET_MODEL=Unbabel/wmt22-comet-da
• Cierre otras aplicaciones que consuman mucha memoria antes de la evaluación

Obtención de ayuda

Si encuentra problemas:

1. Consulte los Problemas de GitHub
2. Habilite el registro de depuración (consulte los registros del Modo Desarrollador de Claude Desktop, o establezca XCOMET_DEBUG=true)
3. Abra un nuevo problema con:
   • Su sistema operativo y versión de Python
   • El mensaje de error
   • Su configuración (sin datos sensibles)

🧪 Desarrollo

# 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 llama a python3 -m pytest, por lo que pytest debe poder importarse desde cualquier python3 que esté en su PATH. Activar el venv de xCOMET no ayuda a menos que pytest esté instalado en él. Cualquiera de estas opciones funciona:

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 documenta cada suite, qué cubre y por qué.

📋 Registro de cambios

Consulte CHANGELOG.md para el historial de versiones y actualizaciones.

📝 Licencia

Licencia MIT: consulte LICENSE para más detalles.

🙏 Agradecimientos

• Unbabel por el modelo xCOMET
• Anthropic por el protocolo MCP
• Model Context Protocol comunidad

📚 Referencias

• Artículo de xCOMET
• Marco COMET
• BLEU Meets COMET (Rei et al., 2023) — sobre métricas neuronales que omiten errores de entidades y números; la base para Qué dice y qué no dice la puntuación
• Diseño de caché de Hugging Face Hub
• Especificación MCP