Перейти к основному содержимому

Агенты и MCP

SteamMarketRunner рассчитан на работу не только людей, но и AI-агентов. Для этого есть три уровня поддержки.

1. llms.txt​

Сайт документации публикует машиночитаемые сводки по стандарту llmstxt.org:

  • https://docs.steammarketrunner.com/llms.txt — оглавление со ссылками на все разделы;
  • https://docs.steammarketrunner.com/llms-full.txt — полный текст документации одним файлом.

Агенту достаточно загрузить llms-full.txt, чтобы получить весь контекст по продукту. Используйте абсолютные URL — относительные пути агент не сможет разрешить вне сайта.

2. OpenAPI​

Публичная спецификация API доступна:

  • интерактивно — на странице API Reference;
  • как файл — https://docs.steammarketrunner.com/openapi.json (абсолютный URL).

Из публичной спеки скрыты внутренние и операторские ручки — остаются только эндпоинты, нужные для пользовательских интеграций. Для автоматизации заведите сервис-ключ в своём кабинете: ключи привязаны к вашему пользователю (тенанту), хранится только их хеш, а сам ключ показывается единожды при создании. Мутации, ставящие задачи, идемпотентны через заголовок x-idempotency-key. Управление аккаунтами и торговлей — через per-account роуты /steam-accounts/{id}/trading/* (start/stop), список своих задач — /steam-accounts/{id}/decisions/jobs, свой аудит — /audit-log.

Модель работы: ставим задачу, опрашиваем результат​

Торговые действия асинхронны и идемпотентны: вы ставите задачу в очередь (получаете её id), фоновый воркер её исполняет, а вы опрашиваете результат по id.

Повтор того же x-idempotency-key по тому же аккаунту вернёт уже существующую задачу, а не создаст дубль — безопасно ретраить.

Сквозной пример​

Аутентификация — сервис-ключ передаётся в заголовке x-api-key (cookie-сессия владельца — только для браузера). Дополнительно рекомендуется слать x-steammarketrunner-actor (кто вы) и x-request-id (для корреляции в аудите).

1. Получить сервис-ключ. В кабинете под сессией владельца (plaintext-ключ возвращается только при создании — сохраните его сразу):

curl -X POST https://api.steammarketrunner.com/auth/service-keys \
  -H "content-type: application/json" \
  -H "cookie: steammarketrunner_session=..." \
  -d '{"name":"my-agent"}'
# → { "id": "...", "key": "<plaintext — показывается один раз>", ... }

2. Поставить задачу (здесь — dry-run buy-анализ; начинайте с dryRun:true):

curl -X POST https://api.steammarketrunner.com/steam-accounts/$STEAM_ACCOUNT_ID/decisions/jobs \
  -H "content-type: application/json" \
  -H "x-api-key: $STEAMMARKETRUNNER_SERVICE_API_KEY" \
  -H "x-steammarketrunner-actor: my-agent" \
  -H "x-request-id: my-agent-2026-06-14-0001" \
  -H "x-idempotency-key: my-agent-buy-analysis-0001" \
  -d '{"type":"buy_analysis","appid":252490,"dryRun":true}'
# → { "id": "$JOB_QUEUE_ID", ... }

3. Забрать результат по id задачи:

curl "https://api.steammarketrunner.com/steam-accounts/$STEAM_ACCOUNT_ID/decisions/jobs/$JOB_QUEUE_ID/result" \
  -H "x-api-key: $STEAMMARKETRUNNER_SERVICE_API_KEY" \
  -H "x-steammarketrunner-actor: my-agent"

Список своих задач — GET /steam-accounts/{id}/decisions/jobs?status=queued&type=buy_analysis. Глобальные операторские ручки (/jobs*, /audit-events) — только для роли admin. Полный набор примеров (recover-stale, requeue, cancel, проверка ключа через /auth/service/me) — в технической документации бэкенда (docs/backend/SERVICE_API.md).

3. MCP-сервер​

Пакет @steammarketrunner/mcp поднимает MCP-сервер над документацией и OpenAPI-спекой. Агент получает их как инструменты, а не как «простыню» текста. Сервер предоставляет ровно 6 инструментов:

ИнструментЧто делает
list_docsсписок всех страниц документации (id, заголовок, url)
read_docполный markdown одной страницы по её id
search_docsпоиск по документации с ранжированием и сниппетами
list_api_operationsсписок операций API (метод, путь, теги; фильтр по тегу/методу)
search_apiпоиск операций API по ключевым словам
get_api_operationполная схема операции (параметры, тело, ответы)

Транспорт — stdio, поэтому сервер подключается к Claude Code, Claude Desktop, Cursor и другим MCP-клиентам.

Подключение к Claude Code​

pnpm --filter @steammarketrunner/mcp build
claude mcp add steammarketrunner -- node /абсолютный/путь/steammarketrunner/apps/mcp/dist/index.js

Подключение через конфиг клиента​

{
  "mcpServers": {
    "steammarketrunner": {
      "command": "node",
      "args": ["/абсолютный/путь/steammarketrunner/apps/mcp/dist/index.js"]
    }
  }
}
Путь к серверу — абсолютный

args должен содержать абсолютный путь до dist/index.js. Относительный путь не разрешится: рабочая директория MCP-клиента, как правило, не совпадает с корнем репозитория.

Подробности — в apps/mcp/README.md.

Дальше​