xCOMET MCP Server

Японская версия README доступна здесь

⚠️ Это неофициальный общественный проект, не связанный с Unbabel.

MCP-сервер для оценки качества перевода на базе xCOMET (eXplainable COMET).

🎯 Обзор

xCOMET MCP Server предоставляет ИИ-агентам возможность оценивать качество машинного перевода. Он интегрируется с моделью xCOMET от Unbabel для обеспечения:

• Оценки качества: баллы от 0 до 1, указывающие на качество перевода

• Обнаружения ошибок: выявление фрагментов с ошибками с уровнями серьезности (незначительные/значительные/критические)

• Пакетной обработки: эффективная оценка нескольких пар перевода (оптимизированная загрузка одной модели)

• Поддержки GPU: опциональное ускорение на GPU для более быстрого вывода

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

🔧 Предварительные требования

Среда Python

• Рекомендуется Python 3.9 - 3.12 (версии 3.13+ пока не поддерживаются зависимостями xCOMET)

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

Примечание: При использовании с 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
   huggingface-cli login

Unbabel/wmt22-comet-da не требует аутентификации (но требует эталонные переводы).

После аутентификации загрузите модель (~14 ГБ для XL, ~42 ГБ для 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 или 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"],
      "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

Глобальная установка

Если вы предпочитаете глобальную установку:

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

Режим HTTP (удаленный доступ)

TRANSPORT=http PORT=3000 npm start

Затем подключитесь к http://localhost:3000/mcp

🛠️ Доступные инструменты

xcomet_evaluate

Оценка качества перевода для одной пары «исходник-перевод».

Параметры:

Пример:

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

Фокус на обнаружении и классификации ошибок перевода.

Параметры:

xcomet_batch_evaluate

Оценка нескольких пар перевода в одном запросе.

Примечание по производительности: Благодаря архитектуре постоянного сервера (v0.3.0+), модель остается загруженной в памяти. Пакетная оценка эффективно обрабатывает все пары без перезагрузки модели.

Параметры:

Пример:

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

Затем спросите Claude:

"Переведи этот текст на японский с помощью DeepL, затем оцени качество перевода с помощью xCOMET. Если оценка ниже 0.8, предложи улучшения."

⚙️ Конфигурация

Переменные окружения

Выбор модели

Выберите модель в зависимости от ваших потребностей в качестве/производительности:

Важно: XCOMET-XL и XCOMET-XXL — это модели с ограниченным доступом на HuggingFace. Каждая модель требует отдельного одобрения доступа. См. Загрузка модели для настройки аутентификации.

Важно: wmt22-comet-da требует эталонный перевод для оценки. Модели XCOMET поддерживают оценку без эталона.

Совет: Если вы столкнулись с проблемами памяти или медленной загрузкой модели, попробуйте Unbabel/wmt22-comet-da для более высокой производительности с немного меньшей точностью (но не забудьте предоставить эталонные переводы).

Чтобы использовать другую модель, установите переменную окружения XCOMET_MODEL:

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

Автоматическое обнаружение пути к Python

Сервер автоматически обнаруживает среду Python с установленным unbabel-comet:

1. Переменная окружения XCOMET_PYTHON_PATH (если установлена)

2. Версии pyenv (~/.pyenv/versions/*/bin/python3) - проверяет наличие модуля comet

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

4. Резерв: команда python3

Это гарантирует, что сервер работает правильно, даже если хост MCP (например, Claude Desktop) использует другой Python, чем ваш терминал.

Пример: Явная конфигурация пути к Python

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

⚡ Производительность

Архитектура постоянного сервера (v0.3.0+)

Сервер использует постоянный Python FastAPI-сервер, который держит модель xCOMET загруженной в памяти:

Это обеспечивает 177-кратное ускорение для последовательных оценок по сравнению с перезагрузкой модели каждый раз.

Предварительная загрузка (v0.3.1+)

Включите XCOMET_PRELOAD=true для предварительной загрузки модели при запуске сервера:

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

С включенной предварительной загрузкой все запросы выполняются быстро (~500 мс), включая первый.

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

Оптимизация пакетной обработки

Инструмент xcomet_batch_evaluate обрабатывает все пары с одной загрузкой модели:

Производительность GPU vs CPU

Примечание: GPU требует оборудования, совместимого с CUDA, и PyTorch с поддержкой CUDA. Если 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-10 ГБ ОЗУ

• Для больших пакетов (500 пар) убедитесь в наличии достаточного объема памяти

• Если память ограничена, разбивайте на меньшие пакеты (100-200 пар)

Автоматический перезапуск (v0.3.1+)

Сервер автоматически восстанавливается после сбоев:

• Мониторит состояние каждые 30 секунд

• Перезапускается после 3 последовательных сбоев проверки состояния

• До 3 попыток перезапуска перед тем, как сдаться

📊 Интерпретация оценки качества

🔍 Устранение неполадок

Распространенные проблемы

"No module named 'comet'"

Причина: Среда Python без установленного `unbabel-