codeforces-mcp

MCP-сервер, который даёт агентам для написания кода доступ к тренировочным данным Codeforces. Он помогает разобраться в своих слабых тегах и находить задачи, которые вы ещё не решали.

Сервер работает в режиме чтения, использует публичный API Codeforces и не требует аутентификации Codeforces. Он работает с VS Code Copilot, Claude Desktop/Code и другими MCP-клиентами, поддерживающими stdio-серверы.

Возможности

• Находить задачи по рейтингу и тегу, при необходимости исключая уже решённые задачи пользователя.

• Ранжировать теги хэндла по доле решённых задач и среднему рейтингу решённых.

• Просматривать последние посылки и фильтровать их по вердикту.

• Смотреть профиль пользователя и историю рейтинга.

• Выводить список ближайших соревнований.

• Возвращать результаты в читаемом Markdown или структурированном JSON.

• Локально кэшировать ответы API и соблюдать разумную частоту запросов.

Related MCP server: cf-mcp-orange

Требования

• Python 3.10 или новее

• Хэндл Codeforces для инструментов, связанных с конкретным пользователем

• VS Code с GitHub Copilot Agent mode, Claude или другой MCP-совместимый клиент

API-ключ не требуется.

Установка

Клонируйте репозиторий и создайте виртуальное окружение:

git clone https://github.com/<owner>/codeforces-mcp.git
cd codeforces-mcp
python -m venv .venv

Активируйте окружение:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

Установите пакет:

python -m pip install -e .

Для разработки установите также тестовые зависимости и зависимости для линтера:

python -m pip install -e ".[dev]"

В результате установки в виртуальном окружении создаётся команда codeforces-mcp.

Использование с VS Code Copilot

В репозитории есть конфигурация рабочей области в .vscode/mcp.json. В Windows она может указывать прямо на созданное виртуальное окружение:

{
  "servers": {
    "codeforces": {
      "type": "stdio",
      "command": "E:\\path\\to\\codeforces-mcp\\.venv\\Scripts\\codeforces-mcp.exe"
    }
  }
}

Замените путь на фактическое расположение вашей клонированной копии. Для macOS/Linux используйте:

{
  "servers": {
    "codeforces": {
      "type": "stdio",
      "command": "/path/to/codeforces-mcp/.venv/bin/codeforces-mcp"
    }
  }
}

В VS Code:

1. Выполните MCP: Open Workspace Folder Configuration из палитры команд.

2. Добавьте или обновите запись сервера codeforces.

3. Откройте Copilot Chat и переключитесь в режим Agent.

4. Откройте меню инструментов, запустите или включите сервер codeforces и разрешите его инструменты.

Затем попросите Copilot о чём-то вроде:

Найди для хэндл-хэндла найди и нерешённых задач по DP рейтинга 1300–1500.

Сервер использует stdio, поэтому сервер запускается и останавливается по мере необходимости. Не запускайте вторую копию вручную, пока Copilot подключён.

Использование с Claude

После активации виртуального окружения зарегистрируйте команду в Claude Code:

claude mcp add codeforces -- codeforces-mcp

Если команды нет в PATH, используйте исполняемый файл напрямую:

claude mcp add codeforces -- .\.venv\Scripts\codeforces-mcp.exe

Эквивалентная команда для macOS/Linux:

claude mcp add codeforces -- .venv/bin/codeforces-mcp

Инструменты

Все инструменты работают в режиме чтения и поддерживают параметр response_format, который может быть "markdown" (по умолчанию) или "json".

codeforces_search_problems

Ищет задачи, начиная с самых простых. Задайте exclude_solved_by, чтобы скрыть задачи, для которых вердикт указанного хэндла OK.

Пример запроса:

Find 5 unsolved dp problems rated 1300-1500 for 3.141f.

Эквивалентные аргументы:

{
  "min_rating": 1300,
  "max_rating": 1500,
  "tags": ["dp"],
  "exclude_solved_by": "3.141f",
  "limit": 5
}

codeforces_tag_performance

Вычисляет по каждому тегу количество попыток, решений, долю решённых задач и рейтинги эндла. Результаты упорядочены от самой низкой доли решений к высокой. min_attempted предотвращает доминирование очень маленьких выборок в рейтинге.

{
  "handle": "3.141f",
  "min_attempted": 8,
  "response_format": "markdown"
}

codeforces_recent_submissions

Показывает последние посылки хэндла. Используйте verdict, например WRONG_ANSWER, TIME_LIMIT_EXCEEDED или OK, чтобы отфильтровать список.

{
  "handle": "3.141f",
  "verdict": "WRONG_ANSWER",
  "limit": 10
}

codeforces_user_profile

Показывает текущий рейтинг хэндла, максимальный рейтинг, звание и организацию.

{
  "handle": "3.141f"
}

codeforces_rating_history

Показывает изменения рейтинга по каждому состязанию, от самых старых к новым. Задайте limit, чтобы вернуть только самые последние состязания.

{
  "handle": "3.141f",
  "limit": 10
}

codeforces_upcoming_contests

Список состязаний, которые ещё не начались, от самых ближайших.

{
  "limit": 5
}

Пример вывода

**5 of 208 matching problems** (offset 0, more available)

| Rating | Problem | Tags | Link |
| --- | --- | --- | --- |
| 1300 | 189A - Cut Ribbon | brute force, dp | https://codeforces.com/problemset/problem/189/A |
| 1300 | 234C - Weather | dp, implementation | https://codeforces.com/problemset/problem/234/C |
| 1300 | 416B - Art Union | brute force, dp, implementation | https://codeforces.com/problemset/problem/416/B |

Формат JSON содержит те же типизированные данные для приложений, которым нужна программная обработка результата.

Кэш и частота запросов

Согласно документации Codeforces API, рекомендуется выполнять примерно один запрос в две секунды. Клиент соблюдает это ограничение и по умолчанию сохраняет ответы в каталоге ~/.cache/codeforces-mcp. Время жизни кэша отражает частоту изменений данных: шесть часов для набора задач, пять минут для посылок и один час для профилей пользователей.

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

Сервер не запускается

Проверьте, что исполняемый файл существует в окружении, используемом вашей MCP-конфигурацией:

Test-Path .\.venv\Scripts\codeforces-mcp.exe

./.venv/bin/codeforces-mcp

Если вы установили в другое виртуальное окружение, обновите путь command в mcp.json.

Codeforces возвращает ошибку

Проверьте написание хэндла и повторите попытку позже. Сервер передаёт в клиент понятные комментарии об ошибках Codeforces. Публичный API также может быть временно ограничен или недоступен.

Разработка

Запустите детерминированные проверки перед отправкой изменения:

ruff check .
mypy src/
pytest tests/contract -q
python eval/run_eval.py

Живые тесты обращаются к Codeforces и включаются вручную:

pytest -m live -q

Переписывание дат локальных коммитов

Репозиторий содержит rebase-commits-to-july.sh для переписывания всех коммитов текущей ветки к 14 и 15 июля 2026 года. Он создаёт резервную ветку перед вторжением в историю:

bash rebase-commits-to-july.sh

Рабочее дерево должно быть чистым, и скрипт должен запускаться из ветки с названием — запускаться из именованной ветки. Он переписывает идентификаторы коммитов, поэтому без согласования не используйте его в общей ветке. Чтобы восстановить исходную вершину, используйте резервную ветку, которую напечатал скрипт:

git reset --hard backup/pre-date-rebase-<timestamp>

Прочтите SPEC.md перед изменением поведения инструмента. Он определяет контракты и критерии приёмки, и каждый критерий соответствует контрактному тесту.

Структура проекта

Публикация

1. Откройте информацию о баге или предлагаемом изменении поведения.

2. Обновите SPEC.md и его контрактный тест перед изменением поведения.

3. Держите логику инструментов в src/codeforces_mcp/tools/ без MCP-импортов.

4. Запустите проверки для разработчика и включите соответствующие тестовые выводы в pull request.

Пожалуйста, избегайте коммитов виртуальных окружений, кэшей, артефактов сборки или API-записей, содержащих персональные данные. Файл .gitexclude/repository уже исключает созданные этим проектом локальные артефакты разработки.

Связанная документация

• SPEC.md — контракты инструментов и проектные решения

• docs/TECHNICAL-OVERVIEW.md — архитектура и детали реализации