@moabpro/le1-mcp

MCP-сервер (Model Context Protocol) для публичного API биржи LE1. Позволяет управлять биржей человеческим языком из Claude Code, Claude Desktop, Cursor и любого другого MCP-клиента: смотреть сайты, страницы, блоки, начисления и пользователей, строить финансовые отчёты, запускать инструменты биржи и следить за их выполнением.

Сервер — тонкая обёртка над REST API /api/v1 (интерактивная документация — Scalar на {LE1_API_URL}/api-docs). Работает по stdio, ничего не хранит локально, все данные ходят напрямую между MCP-клиентом и API биржи.

Требования

• Node.js ≥ 20 (используется встроенный fetch);
• персональный API-ключ биржи (см. ниже).

Авторизация

Используется тот же ключ, что и у публичного REST API — заголовок X-Api-Key.

Где взять ключ: веб-интерфейс биржи → клик на свой email в шапке → диалог «API-ключ» → «Сгенерировать». Ключи доступны только администраторам (роль buyer); пользователь без ключа доступа к API не имеет. Ключ передаётся серверу через переменную окружения LE1_API_KEY.

⚠️ Ключ даёт полный админ-доступ к бирже, включая запуск инструментов, меняющих данные. Храните его как пароль, не коммитьте в репозитории. Отозвать ключ можно в том же диалоге («Удалить» или «Сгенерировать новый» — старый перестаёт работать сразу).

Установка

Claude Code

Глобально для всех проектов и сессий (--scope user, рекомендуется):

claude mcp add --scope user le1 -e LE1_API_KEY=ВАШ_КЛЮЧ -- npx -y @moabpro/le1-mcp

Без --scope user сервер добавится только для текущей папки (scope local). Проверка: claude mcp list → le1 … ✔ Connected. Удаление: claude mcp remove --scope user le1.

Разрешить инструменты без запросов подтверждения

По умолчанию Claude Code спрашивает разрешение на каждый вызов инструмента. Чтобы разрешить все инструменты le1 сразу, добавьте "mcp__le1" в permissions.allow файла ~/.claude/settings.json (Windows: C:\Users\<ИМЯ>\.claude\settings.json):

{
  "permissions": {
    "allow": [
      "mcp__le1"
    ]
  }
}

Если файл уже существует — не заменяйте его целиком, а допишите "mcp__le1" в существующий массив allow. Изменение подхватится в новой сессии.

Точечный вариант — разрешить только чтение, а запуск инструментов биржи оставить под подтверждение: вместо "mcp__le1" перечислите конкретные инструменты ("mcp__le1__le1_list_sites", "mcp__le1__le1_list_accruals", …) — тогда le1_run_tool и прочие будут по-прежнему требовать подтверждения.

Claude Desktop / Cursor / прочие MCP-клиенты

В конфиг MCP-серверов (для Claude Desktop — claude_desktop_config.json):

{
  "mcpServers": {
    "le1": {
      "command": "npx",
      "args": ["-y", "@moabpro/le1-mcp"],
      "env": { "LE1_API_KEY": "ВАШ_КЛЮЧ" }
    }
  }
}

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

| Переменная | Обязательна | Описание | |---|---|---| | LE1_API_KEY | да | Персональный API-ключ (диалог «API-ключ» в профиле) | | LE1_API_URL | нет | Базовый URL API. По умолчанию https://cpa-goods.ru:5050 |

Соглашения

• Все идентификаторы (id, siteId, userId…) — строки MongoDB ObjectId (24 hex-символа, например 63d7e6ed7f256430f748313e).
• Списки пагинированы: page (с 1), pageSize (1–500, по умолчанию 50); ответ — { items, totalCount, page, pageSize }.
• Даты передаются строкой YYYY-MM-DD.
• Ответы — JSON «как есть» из API; ошибки — человекочитаемый текст на русском (isError: true), включая подсказку при неверном ключе (401).

Инструменты

Служебные

| Инструмент | Что делает | |---|---| | le1_me | Проверка ключа: возвращает email и роль владельца. Первый вызов при проблемах с доступом |

Данные (только чтение)

| Инструмент | Параметры | Что делает | |---|---|---| | le1_list_sites | search?, status?, userId?, userEmail?, page?, pageSize? | Сайты-доноры. search — подстрока URL/email владельца; status — например Working (в работе), Added, Deleted, Declined, BuyingStopped; userEmail — точный email владельца без учёта регистра | | le1_get_site | id | Полная карточка сайта: статусы, трафик, цены блоков, расходы, счётчики | | le1_list_site_pages | siteId, search?, page?, pageSize? | Страницы сайта: URL, title, HTTP-статус, глубина, индексация, установлен ли код | | le1_list_blocks | siteId?, pageId?, status?, search?, page?, pageSize? | Рекламные блоки (размещения). Активные размещения — только с status=Active, иначе в выборке будут и снятые. Статусы: Active, Inactive, AwaitingModeration, BlockedPermanently | | le1_get_block | id | Карточка блока: анкор, URL акцептора, цена, видимость, проект | | le1_list_accruals | dateFrom, dateTo, siteId?, userId?, page?, pageSize? | Начисления — записи ежедневных проверок блоков. Одна запись = один блок за один день; price — дневная ставка блока в ₽ (начисление за день = price, сумма за период = сумма price по записям). Диапазон дат обязателен, максимум 62 дня | | le1_list_users | role?, search?, page?, pageSize? | Пользователи: buyer — админы, seller — вебмастера. Без паролей и ключей | | le1_get_user | id | Карточка пользователя: email, статус, Telegram, способ выплаты, комментарий |

Справочники

| Инструмент | Что делает | |---|---| | le1_list_templates | Шаблоны рекламных блоков (метаданные) | | le1_get_template (id) | Шаблон с содержимым: HTML (DotLiquid), CSS, JS | | le1_list_gray_topics | Серые тематики (категория + маркер) для модерации площадок |

Отчёты

| Инструмент | Параметры | Что делает | |---|---|---| | le1_report_dates | — | Месяцы, за которые есть данные. Поле id → параметр dateId отчётов | | le1_report | type, dateId, date?, acceptorId?, ownerId?, anchor?, url?, donorDomain?, donorPage?, page?, pageSize? | Финансовые отчёты в JSON (см. типы ниже) | | le1_report_file | type | Легаси-отчёты файлом: yandexMetrikaLight, yandexMetrikaFull, monthlyMoney → { url } на скачивание |

Типы le1_report:

• baseDays — суммы по каждому дню месяца (оплата бирже/вебмастерам, количество ссылок и сайтов);
• baseMonth — агрегаты по вебмастерам за весь месяц;
• owner — по вебмастерам за конкретный день (обязателен date);
• link — по каждой ссылке за день (обязателен date; строк могут быть тысячи — используйте page/pageSize);
• site — по сайтам за день (обязателен date).

Типовой сценарий: le1_report_dates → взять свежий id → le1_report с нужным типом.

Инструменты биржи (меняют данные!)

| Инструмент | Что делает | |---|---| | le1_list_tools | Каталог фоновых инструментов с описанием позиционных параметров. Вызывать перед первым запуском | | le1_run_tool (toolName, parameters?) | Запуск инструмента. Возвращает taskId. Одновременно работает только один инструмент (глобальная блокировка) | | le1_tool_status (toolName, after?) | Статус (idle / running / completed / failed / cancelled) и инкрементальный лог: передавайте index последнего сообщения в after | | le1_cancel_tool (toolName) | Отмена выполняющегося инструмента | | le1_validate_change_prices (sheetUrl) | Сводка изменений цен по прайсу Google Sheets — без применения. Обязательный шаг перед changePrices | | le1_validate_remove_blocks (acceptorUrl) | Сколько активных блоков будет снято режимом byAcceptor. Обязательный шаг перед removeBlocks |

Доступные инструменты (актуальный список и параметры — в le1_list_tools): поиск релевантных страниц, поиск кода на сайтах, диагностика блоков, рассылка вебмастерам, смена цен, массовые фиксации, снятие ссылок, сканирование сайта.

Примеры запросов к Claude

• «Покажи все сайты вебмастера [email protected] и сколько на них активных блоков»
• «Сколько мы начислили по сайту X за июль? Разбей по дням»
• «Сравни отчёт по вебмастерам за 1 и 15 число прошлого месяца»
• «Проверь прайс https://docs.google.com/spreadsheets/… и скажи, что изменится, но цены не меняй»
• «Запусти сканирование сайта example.com и следи за ходом, пока не закончится»

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

| Симптом | Причина / решение | |---|---| | Не задан LE1_API_KEY | Переменная окружения не дошла до сервера — проверьте конфиг MCP-клиента | | ✗ API-ключ не принят (401) | Ключ неверен или отозван — сгенерируйте новый в профиле | | ✗ Доступ запрещён (403) | Ключ принадлежит пользователю без роли buyer | | Долгие ответы отчётов | Тяжёлые отчёты (особенно le1_report_file) генерируются на сервере — это нормально |

Разработка

Исходники — в репозитории биржи LE1, папка le1-mcp/ (TypeScript, сборка tsc).

npm install
npm run build
LE1_API_URL=http://localhost:5211 LE1_API_KEY=... node dist/index.js

npm publish собирает автоматически (prepublishOnly).

Версии

• 0.1.1 — исправлена семантика price в начислениях: это дневная ставка, а не месячная (старое описание заставляло агентов занижать суммы в ~30 раз).
• 0.1.0 — первый релиз: 21 инструмент (данные, справочники, отчёты, запуск инструментов биржи).