Vibe-Marketolog Agent API → MCP (POC)

Минимальный рабочий пример по запросу Владимира: один инструмент, журнал вызовов, понятная цена цикла.

Что здесь есть

• vibe_client.py — клиент к https://lk.vibemarketolog.ru/api/agent. Каждый вызов инструмента пишет строку в call_log.jsonl и умеет посчитать сводку по деньгам за сессию.

• server.py — MCP-сервер (mcp SDK, FastMCP). Отдаёт наружу четыре tool'а: landing_audit, cycle_cost_summary, call_log, account_status. Подключается как обычный MCP-сервер в Cursor, VS Code или любой другой MCP-совместимой среде.

• demo_run.py — скрипт без MCP-клиента, чтобы проверить всё за один запуск: платный вызов → повторный из кеша → журнал → сводка стоимости.

• test_client.py — 13 тестов на моке HTTP-слоя: журнал, подсчёт стоимости, обработка ошибок и запускаемость MCP-сервера. Без реального ключа и сети.

Related MCP server: calltouch-mcp

Запуск

pip install -r requirements.txt
export VIBE_API_KEY=ваш_ключ_из_раздела_AGI_Агент

# Прямая демонстрация: вызов + повтор + журнал + цена цикла
python demo_run.py https://ваш-сайт.ru

# Или как MCP-сервер:
python server.py

Тесты без ключа и сети:

python -m pytest test_client.py -v

Версия MCP SDK в requirements.txt закреплена жёстко (mcp==1.9.4): в 2.x путь импорта mcp.server.fastmcp отсутствует, сервер под неё нужно переписывать отдельно.

Почему именно landing-audit

Это единственный существующий роут семейства direct/*. Проверено запросами без ключа: живой роут отвечает 401 missing_token, несуществующий — 404 not_found.

POST /api/agent/direct/landing-audit   -> 401 missing_token
POST /api/agent/direct/waste           -> 404 not_found
POST /api/agent/direct/search-queries  -> 404 not_found
POST /api/agent/direct/campaigns       -> 404 not_found

Плюс инструменту не нужен ни подключённый рекламный кабинет, ни кампания на платформе — только URL. Значит, POC можно честно прогнать сразу после получения ключа.

Журнал вызовов

Пишется в call_log.jsonl рядом с кодом, построчно, человекочитаемо. В журнал попадает каждый вызов, включая упавшие — иначе цена цикла считалась бы по неполным данным:

{"timestamp": "...", "session_id": "6c90b72e", "tool": "direct/landing-audit", "params": {"url": "..."}, "status": "ok", "cached": false, "price_rub": 39.0, "price_source": "api", "duration_ms": 1240, "note": "новый платный вызов"}
{"timestamp": "...", "session_id": "6c90b72e", "tool": "direct/landing-audit", "params": {"url": "..."}, "status": "ok", "cached": true, "price_rub": 0.0, "price_source": "cache", "duration_ms": 180, "note": "из кеша (бесплатно)"}
{"timestamp": "...", "session_id": "6c90b72e", "tool": "me", "params": {}, "status": "error", "cached": false, "price_rub": 0.0, "price_source": "none", "duration_ms": 519, "note": "HTTP 401 missing_token: Не передан ключ доступа."}

price_source показывает, откуда взялась цифра: api — пришла в ответе, cache — вызов бесплатный, unknown — API цену не сообщил.

Понятная цена цикла

cycle_cost_summary() считает по журналу, по умолчанию — только за текущий запуск (scope="session"). Журнал дописывается между запусками, и сумма за всю историю файла — это не цена цикла; за всю историю считает scope="all".

{
  "scope": "session",
  "session_id": "6c90b72e",
  "total_calls": 2,
  "paid_calls": 1,
  "cached_free_calls": 1,
  "unknown_price_calls": 0,
  "errors": 0,
  "total_spent_rub": 39.0,
  "cost_confirmed": true
}

cost_confirmed: false означает, что хотя бы по одному вызову API не сообщил цену: сумма ниже фактической, и это видно, а не замаскировано нулём.

Честно о границах этого POC

• Логика проверена на моке: 13 тестов проходят, включая регрессию на запускаемость MCP-сервера. Живой прогон платного вызова на реальном ключе ещё предстоит.

• Проверено вживую без ключа: базовый URL, /me, /capabilities и существование роута direct/landing-audit (401, а не 404), формат ошибок {status, error, message, request_id}.

• Не проверено: имена полей стоимости и кеша в ответе landing-audit. Публичная документация называет стоимость cost, а /capabilities этот инструмент не описывает вовсе. Клиент принимает price_rub, cost и charged_rub, а если не нашёл ни одного — помечает цену как неизвестную. Наличие бесплатного кеша на 24 часа тоже не подтверждено документацией: если второй вызов придёт платным, demo_run.py скажет об этом прямо.

• Не проверено: хватает ли скоупов промо-ключа на этот роут. direct/* не описан в публичном /capabilities, а секция partner_only относит программную работу с Директом к партнёрскому соглашению — возможен 403 insufficient_scope.

• Остальные инструменты директолога не обёрнуты, потому что обёртывать нечего: других роутов direct/* в API нет.

• Слой дельт в MVP не показан намеренно: landing-audit не кампанейский, дельте там взяться не из чего.

Следующий шаг, если направление подтвердится

1. Прогнать demo_run.py на реальном ключе, приложить фактический call_log.jsonl и скриншот баланса до/после — это заодно закроет вопрос об именах полей стоимости и о наличии кеша.

2. Если скоупов на direct/* не хватает — перенести тот же контур (смета → бюджетный потолок → журнал → цена цикла) на /generate, где биллинг трёхфазный (reserved → cost → refunded) и честный подсчёт стоимости заметно нетривиальнее.

3. Слой дельт — на том, что реально отдаёт API.