xcomet-mcp-server

Servidor MCP xCOMET

Versão em japonês do README disponível aqui

⚠️ Este é um projeto comunitário não oficial, não afiliado à Unbabel.

Servidor MCP de avaliação de qualidade de tradução, desenvolvido com xCOMET (COMET explicável).

🎯 Visão Geral

O Servidor MCP xCOMET fornece aos agentes de IA a capacidade de avaliar a qualidade de tradução automática. Ele se integra ao modelo xCOMET da Unbabel para fornecer:

• Pontuação de Qualidade: Pontuações entre 0 e 1 que indicam a qualidade da tradução
• Detecção de Erros: Identifica trechos com erros e seus níveis de gravidade (menor/maior/crítico)
• Processamento em Lote: Avalie vários pares de tradução de forma eficiente (carregamento otimizado de um único modelo)
• Suporte a GPU: Aceleração opcional por GPU para inferência mais 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

🔧 Pré-requisitos

Ambiente Python

• Python 3.9 - 3.12 recomendado (3.13+ ainda não é suportado pelas dependências do xCOMET)

O xCOMET requer Python com vários pacotes. Recomendamos usar um ambiente 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 que Python 3.9-3.12? unbabel-comet declara numpy = "^1.20.0", então ele resolve o numpy 1.x. A última versão do numpy 1.x, a 1.26.4, fornece wheels apenas para cp39-cp312. No Python 3.13 ou posterior, o pip precisa compilar o numpy a partir do código-fonte.

Observação (v0.5.0+): O worker Python agora se comunica com o Node.js via stdin/stdout (JSON-RPC delimitado por linhas). FastAPI, uvicorn e pydantic não são mais necessários — apenas unbabel-comet é.

Observação: Ao usar com o Claude Desktop ou outros hosts MCP, defina XCOMET_PYTHON_PATH para apontar para o Python do venv (consulte Configuração).

Download do Modelo

Importante: XCOMET-XL e XCOMET-XXL são modelos com acesso restrito no HuggingFace. Você deve:

1. Criar uma conta no HuggingFace

2. Visitar Unbabel/XCOMET-XL e solicitar acesso

3. Autenticar, seja via CLI:

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

   (huggingface-cli login ainda funciona, mas exibe um aviso de depreciação desde huggingface_hub 0.34; hf é o comando atual.)

   Ou definindo HF_TOKEN no bloco env do host MCP, que é a opção quando o host inicia o servidor em um ambiente onde nenhum login via CLI foi realizado:

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

   O huggingface_hub lê HF_TOKEN primeiro e, em seguida, recorre ao arquivo de token gravado por hf auth login.

Unbabel/wmt22-comet-da não requer autenticação (mas requer traduções de referência).

Após a autenticação, baixe o modelo (~14GB para XL, ~42GB para XXL):

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

Onde o modelo é armazenado

Não no virtualenv. O venv contém os pacotes Python; os pesos do modelo vão para o cache do huggingface_hub, que é um diretório separado compartilhado por todas as ferramentas da máquina que fazem download do 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() passa cache_dir=None para snapshot_download(), então o huggingface_hub escolhe o local: HF_HUB_CACHE, que por padrão é HF_HOME/hub, onde HF_HOME por padrão é $XDG_CACHE_HOME/huggingface (~/.cache/huggingface quando XDG_CACHE_HOME não está definido).

Três consequências que vale a pena conhecer:

• Recriar ou excluir o venv não baixa o modelo novamente.
• Vários venvs e outras ferramentas baseadas no Hub compartilham a mesma cópia.
• O tamanho do diretório do venv não inclui os 14GB. Use hf cache scan para ver o que realmente está no disco e hf cache delete para remover uma revisão.

Para colocar o checkpoint em outro lugar — um volume maior, um drive compartilhado — defina XCOMET_SAVING_DIRECTORY (v0.7.0+) ou o padrão HF_HOME. Ambos são lidos no momento do download, portanto, um modelo já baixado para o local padrão não é movido; ele é baixado novamente no novo local.

Node.js

• Node.js >= 22.0.0 (corresponde a engines.node em package.json; o CI executa nas versões 22 e 24)
• npm ou yarn

📦 Instalação

Observação: Se você deseja apenas usar o Servidor MCP xCOMET, não é necessário clonar este repositório. Instale o ambiente Python e o modelo (consulte Pré-requisitos) e depois use npx (consulte Uso). A seção abaixo é apenas para contribuidores e desenvolvimento local.

Desenvolvimento Local

Para contribuidores e desenvolvimento 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

Com o Claude Desktop (npx)

Adicione à configuração do seu Claude Desktop (claude_desktop_config.json):

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

Dica: Se você instalou os pacotes Python em todo o sistema ou usa pyenv, XCOMET_PYTHON_PATH pode ser omitido (a detecção automática o encontrará). Consulte Detecção Automática do Caminho do Python para obter detalhes.

Com o Claude Code

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

Instalação Global

Se você preferir instalar globalmente:

npm install -g xcomet-mcp-server

Em seguida, configure:

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

Build de Desenvolvimento Local

Se você clonou e compilou o repositório localmente (consulte Instalação):

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

🛠️ Ferramentas Disponíveis

xcomet_evaluate

Avalie a qualidade da tradução para um único par fonte-tradução.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
source	string	✅	Texto original de origem
translation	string	✅	Texto traduzido a ser avaliado
reference	string	❌	Tradução de referência
source_lang	string	❌	Código do idioma de origem (ISO 639-1)
target_lang	string	❌	Código do idioma de destino (ISO 639-1)
response_format	"json" | "markdown"	❌	Formato de saída (padrão: "json")
use_gpu	boolean	❌	Usar GPU para inferência (padrão: false)

Exemplo:

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

Resposta:

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

xcomet_detect_errors

Foco na detecção e categorização de erros de tradução.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
source	string	✅	Texto original de origem
translation	string	✅	Texto traduzido a ser analisado
reference	string	❌	Tradução de referência
min_severity	"minor" | "major" | "critical"	❌	Gravidade mínima (padrão: "minor")
response_format	"json" | "markdown"	❌	Formato de saída
use_gpu	boolean	❌	Usar GPU para inferência (padrão: false)

xcomet_batch_evaluate

Avalie vários pares de tradução em uma única solicitação.

Observação de Desempenho: Com a arquitetura de servidor persistente (v0.3.0+), o modelo permanece carregado na memória. A avaliação em lote processa todos os pares de forma eficiente, sem recarregar o modelo.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
pairs	array	✅	Matriz de {source, translation, reference?} (máx. 500)
source_lang	string	❌	Código do idioma de origem
target_lang	string	❌	Código do idioma de destino
response_format	"json" | "markdown"	❌	Formato de saída
use_gpu	boolean	❌	Usar GPU para inferência (padrão: false)
batch_size	number	❌	Tamanho do lote 1-64 (padrão: 8). Maior = mais rápido, porém usa mais memória

Exemplo:

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

🔗 Integração com Outros Servidores MCP

O Servidor MCP xCOMET foi projetado para funcionar em conjunto com outros servidores MCP para fluxos de trabalho completos de tradução:

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?

Fluxo de Trabalho Recomendado

1. Traduza usando o Servidor MCP DeepL (oficial)
2. Avalie usando o Servidor MCP xCOMET
3. Itere se a qualidade estiver abaixo do limite

Exemplo: Integração DeepL + xCOMET

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

Em seguida, peça ao Claude:

"Traduza este texto para japonês usando o DeepL e, em seguida, avalie a qualidade da tradução com o xCOMET. Se a pontuação for inferior a 0,8, sugira melhorias."

⚙️ Configuração

Variáveis de Ambiente

Variável	Padrão	Descrição
XCOMET_MODEL	Unbabel/XCOMET-XL	Modelo xCOMET a ser usado
XCOMET_PYTHON_PATH	(detecção automática)	Caminho do executável Python (veja abaixo)
XCOMET_PRELOAD	false	Pré-carregar o modelo na inicialização (v0.3.1+)
XCOMET_DEBUG	false	Ativar registro de depuração detalhado (v0.3.1+)
XCOMET_NUM_WORKERS	1	Workers do DataLoader para model.predict() (v0.6.0+). Aumente para utilizar melhor os núcleos de CPU ociosos ao executar lotes grandes, especialmente em GPU. Valores inválidos retornam silenciosamente para 1.
XCOMET_SAVING_DIRECTORY	(cache do HuggingFace)	Diretório para baixar o checkpoint (v0.7.0+). Se não definido, o modelo vai para o cache do huggingface_hub (HF_HOME, padrão ~/.cache/huggingface). Defina isso para colocar um checkpoint de 14GB (XL) ou 43GB (XXL) em outro volume.
XCOMET_LOCAL_FILES_ONLY	false	Resolver o checkpoint apenas no cache local (v0.7.0+). Defina como true para iniciar sem acesso à rede; o modelo já deve estar baixado.
HF_TOKEN	(não definido)	Token de acesso do HuggingFace, lido pelo huggingface_hub. Uma alternativa ao hf auth login para os modelos com acesso restrito (XCOMET-XL, XCOMET-XXL, os modelos CometKiwi).

Seleção do Modelo

Escolha o modelo com base nas suas necessidades de qualidade/desempenho:

Modelo	Parâmetros	Tamanho	Memória	Referência	Autenticação HF	Qualidade	Caso de Uso
Unbabel/XCOMET-XL	3,5B	~14GB	~8-10GB	Opcional	✅ Necessária	⭐⭐⭐⭐	Recomendado para a maioria dos casos de uso
Unbabel/XCOMET-XXL	10,7B	~42GB	~20GB	Opcional	✅ Necessária	⭐⭐⭐⭐⭐	Qualidade mais alta, requer mais recursos
Unbabel/wmt22-comet-da	580M	~2GB	~3GB	Necessária	Não necessária	⭐⭐⭐	Leve, carregamento mais rápido

Importante: XCOMET-XL e XCOMET-XXL são modelos com acesso restrito no HuggingFace. Cada modelo requer aprovação de acesso separada. Consulte Download do Modelo para configurar a autenticação.

Importante: wmt22-comet-da requer uma tradução reference para avaliação. Os modelos XCOMET oferecem suporte à avaliação sem referência.

Dica: Se você tiver problemas de memória ou carregamento lento do modelo, tente Unbabel/wmt22-comet-da para obter desempenho mais rápido com precisão ligeiramente menor (mas lembre-se de fornecer traduções de referência).

Para usar um modelo diferente, defina a variável de ambiente XCOMET_MODEL:

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

Detecção Automática do Caminho do Python

O servidor detecta automaticamente um ambiente Python com unbabel-comet instalado:

1. Variável de ambiente XCOMET_PYTHON_PATH (se definida)
2. Versões pyenv (~/.pyenv/versions/*/bin/python3) — verifica o módulo comet
3. Python do Homebrew (/opt/homebrew/bin/python3, /usr/local/bin/python3)
4. Fallback: comando python3

Isso garante que o servidor funcione corretamente mesmo quando o host MCP (por exemplo, Claude Desktop) usa um Python diferente do seu terminal.

Exemplo: Configuração explícita do caminho do Python

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

⚡ Desempenho

Arquitetura de Worker Persistente (v0.3.0+, stdio desde v0.5.0)

O servidor usa um processo worker Python persistente que mantém o modelo xCOMET carregado na memória. O servidor MCP Node.js se comunica com o worker via stdin/stdout usando um protocolo JSON-RPC delimitado por linhas — sem listener HTTP local, sem vinculação de porta, sem FastAPI.

Solicitação	Tempo	Observações
Primeira solicitação	~25-90s	Carregamento do modelo (varia conforme o tamanho do modelo)
Solicitações subsequentes	~500ms	Modelo já carregado

Isso proporciona uma aceleração de 177x para avaliações consecutivas em comparação com o recarregamento do modelo a cada vez.

Carregamento Antecipado (v0.3.1+)

Ative XCOMET_PRELOAD=true para pré-carregar o modelo na inicialização do servidor:

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

Com o pré-carregamento ativado, todas as solicitações são rápidas (~500ms), incluindo a primeira.

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

Otimização do Processamento em Lote

A ferramenta xcomet_batch_evaluate processa todos os pares com um único carregamento do modelo:

Pares	Tempo estimado
10	~30-40 s
50	~1-1,5 min
100	~2 min

Desempenho GPU vs CPU

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

Nota: GPU requer hardware compatível com CUDA e PyTorch com suporte a CUDA. Se GPU não estiver disponível, defina use_gpu: false (padrão).

Melhores práticas

1. Deixe o servidor persistente fazer seu trabalho

Com v0.3.0+, o modelo permanece na memória. Múltiplas chamadas xcomet_evaluate agora são 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 muitos pares, use avaliação em lote

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

3. Considerações de memória

• XCOMET-XL requer ~8-10 GB de RAM
• Para lotes grandes (500 pares), garanta memória suficiente
• Se a memória for limitada, divida em lotes menores (100-200 pares)

Reinício automático (v0.3.1+)

O servidor se recupera automaticamente de falhas:

• Monitora a saúde a cada 30 segundos
• Reinicia após 3 falhas consecutivas na verificação de saúde
• Até 3 tentativas de reinício antes de desistir

📊 Interpretação da pontuação de qualidade

Faixa de pontuação	Qualidade	Recomendação
0,9 - 1,0	Excelente	Pronto para uso
0,7 - 0,9	Bom	Revisão menor recomendada
0,5 - 0,7	Razoável	Pós-edição necessária
0,0 - 0,5	Ruim	Retradução recomendada

O que a pontuação informa e o que não informa

A pontuação responde "isto parece uma tradução daquela fonte", e é boa nisso. Ela não responde "os fatos nesta tradução estão corretos". Essas duas perguntas se separam de uma forma que importa quando a saída é um contrato, uma dosagem, um preço ou um procedimento.

Os seguintes foram medidos com Unbabel/XCOMET-XL na CPU através deste servidor. As duas primeiras linhas são o caso que a métrica trata bem; as duas últimas são o caso em que ela não trata.

Fonte	Tradução	Pontuação
ファイルを保存せずに終了しますか？	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

Uma tradução que não tem relação com a fonte cai para ~0,2, que é o que você quer. Mas uma frase fluente que troca um ano por dez, ou inverte a ordem de duas instruções, pontua 1,000 perfeito. Fornecer uma referência não resolve: com The warranty period is one year from the date of purchase. como referência, a tradução de "dez anos" ainda pontua 0,983.

Isto não é um defeito deste servidor ou do xCOMET especificamente. É uma propriedade conhecida das métricas neurais de MT: elas "têm dificuldade em detectar certos fenômenos que podem ser considerados erros críticos, como desvios em entidades e números" (Rei et al., 2023).

Usando de acordo

Bons usos

• Classificar ou triar um conjunto de traduções — quais segmentos revisar primeiro, qual dos dois sistemas de MT é melhor nos seus dados.
• Detectar colapso de adequação — saída truncada, segmento errado colado, um modelo que perdeu o fio, uma passagem não traduzida.
• Acompanhar a qualidade ao longo do tempo em um conjunto de teste fixo, onde a comparação é entre execuções, e não contra uma barra absoluta.
• Um filtro de primeira passagem antes da revisão humana, para decidir onde o tempo humano será gasto.

Usos inadequados

• Única porta de liberação para conteúdo onde um único número ou nome errado é a falha — médico, jurídico, financeiro, instruções de segurança. Verifique números, datas, unidades, moedas e entidades nomeadas separadamente, com uma regra que realmente os compare; a pontuação não fará isso por você.
• Uma afirmação absoluta de qualidade. 0,95 não é "95% correto", e o valor não é comparável entre modelos, pares de idiomas ou comprimentos de segmento.
• Segmentos muito curtos (um rótulo de interface, uma única palavra), onde a pontuação satura e deixa de discriminar.

Use xcomet_detect_errors junto com a pontuação. Os trechos de erro marcam onde o modelo acredita que algo deu errado, com uma severidade MQM. Uma pontuação alta com um trecho critical é um sinal mais útil do que qualquer um dos números isoladamente.

🔍 Solução de problemas

Problemas comuns

"No module named 'comet'"

Causa: Ambiente Python sem unbabel-comet instalado.

Solução:

# 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

O venv parou de funcionar após uma atualização do Homebrew

Sintoma: zsh: no such file or directory: .venv/bin/python3, ou python3 dentro de um venv ativado resolvendo para um interpretador diferente do do venv, ou No module named 'comet' em um venv que funcionava ontem.

Causa: Um venv não contém um interpretador — ele armazena um link simbólico absoluto para aquele a partir do qual foi criado, registrado em pyvenv.cfg:

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

Quando o Homebrew atualiza ou remove essa fórmula, o link fica pendente e o venv está morto. lib/python3.x/site-packages/ ainda está lá, mas nada pode executá-lo.

Verificação:

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

Solução: recrie-o. uv venv --python 3.12 é a forma mais durável, porque o uv busca e fixa esse interpretador por conta própria, em vez de tomar emprestado o atual do 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 os pacotes são algumas centenas de MB, mas o modelo não é baixado novamente: o checkpoint vive no cache do huggingface_hub, não no venv (veja Onde o modelo é armazenado).

Uma versão antiga inicia após uma atualização

Sintoma: uma correção que você sabe que foi publicada está ausente no servidor em execução. O banner de inicialização no log nomeia uma versão mais antiga.

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

(No macOS, o Claude Desktop grava o stderr de cada servidor MCP em ~/Library/Logs/Claude/mcp-server-<name>.log.)

Causa: npx resolve latest a partir dos metadados de registro em cache do npm, e executa a cópia que já instalou sob ~/.npm/_npx. Por um tempo após um lançamento, essa cópia é a versão anterior. Ela se atualiza sozinha, mas não em um momento que você escolhe. @latest não muda isso — para o npm significa o mesmo que escrever nenhuma versão.

Solução: limpe o cache do npx e reinicie o host MCP.

rm -rf ~/.npm/_npx

ps mostra qual cópia está em execução e de qual diretório de cache ela veio.

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

Para permanecer em uma compilação conhecida, fixe uma versão exata: xcomet-mcp-server@0.7.0.

O download do modelo falha ou expira

Causa: Arquivos grandes de modelo (~14 GB para XL) exigem conexão de internet estável. Os modelos XCOMET também exigem autenticação no HuggingFace (veja Download do modelo).

Solução:

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

Se o download foi interrompido, o cache mantém um diretório de snapshot sem checkpoints/model.ckpt nele. O servidor relata esse caminho e pede que você exclua o diretório; hf cache scan lista onde ele está.

GPU não detectada

Causa: PyTorch não instalado com suporte a CUDA.

Solução:

# 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

Desempenho lento no Mac (MPS)

Causa: O Mac MPS (Metal Performance Shaders) tem problemas de compatibilidade com algumas operações.

Solução: O servidor usa automaticamente num_workers=1 para compatibilidade com Mac MPS. Para melhor desempenho no Mac, use o modo CPU (use_gpu: false).

Alto uso de memória ou travamentos

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

Soluções:

1. Use o servidor persistente (v0.3.0+): O modelo carrega uma vez e permanece na memória, evitando picos repetidos de memória
2. Use um modelo mais leve: Defina XCOMET_MODEL=Unbabel/wmt22-comet-da para menor uso de memória (~3 GB)
3. Reduza o tamanho do lote: Para lotes grandes, processe em partes menores (100-200 pares)
4. Feche outros aplicativos: Libere RAM antes de executar avaliações grandes

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

VS Code ou IDE trava durante a avaliação

Causa: Alto uso de memória do modelo xCOMET (~8-10 GB para XL).

Solução:

• Com v0.3.0+, o modelo carrega uma vez e permanece na memória (sem carregamento repetido)
• Se a memória ainda for um problema, use um modelo mais leve: XCOMET_MODEL=Unbabel/wmt22-comet-da
• Feche outros aplicativos que consomem muita memória antes da avaliação

Obtendo ajuda

Se você encontrar problemas:

1. Verifique as Issues no GitHub
2. Ative o log de depuração (verifique os logs do Developer Mode do Claude Desktop, ou defina XCOMET_DEBUG=true)
3. Abra uma nova issue com:
   • Seu sistema operacional e versão do Python
   • A mensagem de erro
   • Sua configuração (sem dados sensíveis)

🧪 Desenvolvimento

# 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 chama python3 -m pytest, então o pytest precisa ser importável a partir de qualquer python3 que esteja no seu PATH. Ativar o venv do xCOMET não ajuda, a menos que o pytest esteja instalado nele. Qualquer uma destas opções 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 suíte, o que ela cobre e por quê.

📋 Histórico de versões

Veja CHANGELOG.md para o histórico de versões e atualizações.

📝 Licença

Licença MIT — veja LICENSE para detalhes.

🙏 Agradecimentos

• Unbabel pelo modelo xCOMET
• Anthropic pelo protocolo MCP
• Model Context Protocol comunidade

📚 Referências

• Artigo do xCOMET
• Framework COMET
• BLEU Meets COMET (Rei et al., 2023) — sobre métricas neurais que não detectam erros de entidades e números; a base para O que a pontuação informa e o que não informa
• Layout do cache do Hugging Face Hub
• Especificação MCP