startgg-mcp-server

Сервер Model Context Protocol для GraphQL API start.gg. Он позволяет MCP-клиентам (Claude Code, Claude Desktop и другим) находить турниры, просматривать события, участников, сеты, турнирные таблицы и стримы для любой игры на start.gg с помощью естественного языка.

Что это?

start.gg предоставляет мощный, но сложный GraphQL API: участники vs игроки vs игроки, целочисленные состояния сетов, пагинация с ограничением сложности, временные метки в эпохе. Этот сервер оборачивает этот API в небольшой набор MCP-инструментов с:

• Нормализованным выводом — сеты возвращаются как { round, state: "COMPLETED", entrant1: { gamerTag, seed }, score, winnerEntrantId, ... } вместо сырой вложенности GraphQL

• Разрешением URL — вставьте URL start.gg, получите идентификаторы турнира/события

• Встроенными ограничением скорости, повторами и кэшированием, настроенными под документированные лимиты start.gg

Сервер не зависит от конкретной игры. Игровая логика (например, обнаружение апсетов в Smash) должна быть реализована в приложениях поверх него — см. examples/smash-ultimate-watcher.

Related MCP server: Start.gg MCP Server

Возможности

• 15 инструментов только для чтения, покрывающих поиск, турниры, события, игроков, стримы и разрешение URL

• Проверка входных данных (Zod) для каждого инструмента — неверные идентификаторы, слишком большие размеры страниц и некорректные URL никогда не достигают API

• Скользящее окно ограничения скорости (по умолчанию 75 запросов/60 с против 80 у start.gg), повторы с экспоненциальной задержкой и поддержка Retry-After

• Кэш в памяти с коротким TTL для метаданных запросов

• Типизированные коды ошибок: AUTH_ERROR, RATE_LIMITED, NOT_FOUND, INVALID_INPUT, STARTGG_GRAPHQL_ERROR, NETWORK_ERROR, INTERNAL_ERROR

• GraphQL-документы хранятся в файлах graphql/, отдельно от кода

• Токен API никогда не появляется в выводе, логах или сообщениях об ошибках

Требования

• Node.js >= 20

• Токен API start.gg

Получение токена API start.gg

1. Войдите в start.gg

2. Откройте настройки разработчика (Профиль → Настройки разработчика)

3. Создайте персональный токен доступа и скопируйте его

Относитесь к токену как к паролю. Этот сервер читает его только из переменной окружения STARTGG_TOKEN.

Установка

git clone https://github.com/tomo789/startgg-mcp-server.git
cd startgg-mcp-server
npm install
npm run build

Настройка MCP-клиента

Claude Code (CLI)

claude mcp add startgg --env STARTGG_TOKEN=YOUR_TOKEN -- node /path/to/startgg-mcp-server/dist/cli.js

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "startgg": {
      "command": "node",
      "args": ["/path/to/startgg-mcp-server/dist/cli.js"],
      "env": {
        "STARTGG_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Любой MCP-клиент, поддерживающий stdio-серверы, работает так же: запустите node dist/cli.js (или бинарник startgg-mcp-server после установки через npm) с установленным STARTGG_TOKEN.

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

Поиск

Турнир

Событие

Игрок

Утилиты

Инструменты турниров/событий принимают либо числовой идентификатор, слаг, либо полный URL start.gg — вам редко понадобится resolve_startgg_url явно, но он доступен, когда нужны идентификаторы.

Нормализованная форма сета

{
  "id": 106877974,
  "round": "Grand Final",
  "roundNumber": 3,
  "state": "COMPLETED",
  "stateRaw": 3,
  "completedAt": "2026-08-24T07:19:34.000Z",
  "entrant1": {
    "entrantId": 24480092,
    "name": "LittleMacMain",
    "seed": 5,
    "players": [{ "playerId": 3655189, "gamerTag": "LittleMacMain", "prefix": "" }],
    "score": 2
  },
  "entrant2": { "...": "same shape" },
  "score": { "entrant1": 2, "entrant2": 3, "displayScore": "LittleMacMain 2 - RenSuø 3" },
  "winnerEntrantId": 24481002,
  "phase": { "id": 1994001, "name": "Bracket" },
  "vodUrl": null
}

Примечания, основанные на живом API:

• roundNumber < 0 означает сетку проигравших; round — человекочитаемое название

• счёт -1 — маркер дисквалификации start.gg

• не начатые "предпросмотровые" сеты имеют строковые идентификаторы, например "preview_3430499_2_0"

• названия state декодируются из целочисленного stateRaw; возвращаются оба значения

• entrant1/entrant2 используют массив players, поэтому пары/команды работают без изменений

Примеры

Что можно спросить у MCP-клиента после подключения:

Find upcoming Super Smash Bros. Ultimate tournaments this week.

Get the entrants and seeds for this start.gg tournament URL:
https://www.start.gg/tournament/.../event/...

Show me completed sets from Top 8 of that event.

Which streams are assigned to sets at this tournament?

What were the biggest seed upsets in this event?

Автономное примерное приложение (поиск видеоигры → предстоящие турниры → сеты → кандидаты на апсет по разнице посева) находится в examples/smash-ultimate-watcher.

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

Конечная точка API намеренно не настраивается через окружение: токен отправляется только на api.start.gg. При использовании клиента как библиотеки (тесты, инструменты) передайте apiUrl/fetchFn через конструктор StartggClient.

Без STARTGG_TOKEN сервер всё равно запускается и перечисляет инструменты, но каждый вызов возвращает понятную ошибку AUTH_ERROR с объяснением, как её исправить.

Безопасность

• Токен читается только из окружения, отправляется только на api.start.gg и никогда не включается в вывод инструментов, логи или сообщения об ошибках

• Все инструменты только для чтения; мутации не реализованы

• Файлы .env игнорируются git; используйте .env.example как шаблон

• Пользовательский ввод проверяется схемой до построения любого запроса

Ограничение скорости

start.gg разрешает 80 запросов за 60 секунд и не более 1000 объектов за запрос. Этот сервер:

• поддерживает скользящее окно бюджета ниже лимита запросов (по умолчанию 75/60 с)

• повторяет 429 (с учётом Retry-After) и временные ошибки 5xx с экспоненциальной задержкой, максимум 3 повтора — ошибки GraphQL никогда не повторяются

• ограничивает perPage для каждого инструмента, чтобы ответы оставались в пределах лимита сложности в 1000 объектов (сеты дорогие: ~26+ объектов каждый, поэтому perPage <= 30)

• ограничивает fetchAll фиксированным бюджетом страниц и сообщает truncated: true, когда останавливается раньше

Разработка

npm run dev        # run from source (tsx)
npm run build      # compile to dist/
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm run format     # prettier

GraphQL-документы находятся в graphql/*.graphql (один файл на домен, несколько именованных операций в файле; запросы выбирают операцию через operationName). Факты о схеме, проверенные на живом API, записаны в docs/startgg-api-notes.md — прочитайте его перед добавлением полей.

Тестирование

npm test                    # unit tests (fixtures/mocks only, no network)
STARTGG_INTEGRATION=1 STARTGG_TOKEN=... npm test   # + 2 live API smoke tests
STARTGG_TOKEN=... node scripts/smoke.mjs           # full stdio end-to-end smoke (~10 live requests)

Модульные тесты покрывают резолвер URL, нормализаторы, проверку входных данных, пагинацию, обработку ошибок GraphQL/HTTP, ограничитель скорости и кэш.

Лицензия

MIT