artgas1/yandex-metrika-mcp

MCP-сервер к API Яндекс Метрики. Покрыты все 108 методов; по умолчанию объявляются **десять** —
те, которыми считают. Остальное включается одной переменной.
mcp-name: io.github.artgas1/yandex-metrika-mcp-server
*English*
Форк atomkraft/yandex-metrika-mcp (апстрим — Vadim Bezymianyi, MIT).
С версии 2.0.0 инструменты не пишутся руками, а порождаются из спеки, собранной по официальной документации.
Покрытие
| API | методов | из них в профиле core | примеры инструментов |
| --- | ---: | ---: | --- |
| Management | 95 (21 ресурс) | 4 | metrika_counter_list, metrika_goal_create, metrika_segment_update |
| Logs | 7 | — | metrika_logs_create, metrika_logs_get, metrika_logs_download |
| Stat | 6 | 6 | metrika_stat_data, metrika_stat_bytime, metrika_stat_pivot |
Имя инструмента — metrika_ _ , где ресурс взят из URL самого API без переименований.
Поэтому metrika_goal_list однозначно отображается в GET /management/v1/counter/{id}/goals
и в свою страницу документации.
Контракт
Сервер переписан из-за двух наблюдавшихся отказов: он отдавал не то, что просили, и молча
подмешивал фильтр. Отсюда четыре правила, каждое закрыто тестом.
1. **Никакой молчаливой подмены.** Что попросили — то и уходит в API. Сервер не досочиняет
ни измерений, ни периода, ни фильтров.
2. **Всё, что сервер добавил от себя, видно в ответе.** Ответ приходит как
{"_meta": {...}, "data": {...}}, где _meta.applied_by_server перечисляет добавленное,
а _meta.notes — принятые за вызывающего решения.
3. **Отказ остаётся отказом.** Ошибка API возвращается с isError: true и телом ответа Метрики.
Повтор делается по статусу (429/500/502/503/504 и сетевые сбои), а не по подстроке
в тексте; у 429 соблюдается Retry-After с потолком 30 секунд. Число повторов всегда
видно в _meta.retries.
4. **Обрезание выдачи видно.** В _meta едут rows_returned, rows_total и truncated —
Метрика режет ответ по умолчанию, и молчать об этом нельзя. Если сервер сам урезал ответ
по потолку длины, это отдельно объявлено в _meta.truncated_by_server с числом
выброшенных строк.
5. **Секреты не уезжают в ответ.** У metrika_measurement_delete есть параметр token;
в показанном _meta.request_url его значение заменено на REDACTED. Сам OAuth-токен
уходит только заголовком и в ответе не появляется никогда.
Фильтр роботов
В отчётах Stat API по умолчанию применяется собственный флаг робота Метрики, и только он:
Он **объявлен**: виден в схеме инструмента, отключается параметром human_traffic_only: false
и всегда перечислен в _meta.applied_by_server. Если в запросе есть метрики ym:ad: или
ym:ev:, фильтр не применяется (Метрика отвечает на такое сочетание 400) — и это попадает
в _meta.notes, а не остаётся молчаливым исключением.
Своё условие задаётся переменной METRIKA_TRAFFIC_FILTER — **целиком**, включая isRobot,
если он нужен:
Это образец формы, а не рекомендация. Какой рез верен — зависит от того, какие боты ходят
именно к вам: отсечка по стране, по заголовку браузера или по подсети осмысленна только на
своих данных. Копировать чужой список бессмысленно и опасно: он вырежет живой трафик.
Заданное своё условие сервер называет в stderr при старте — оно меняет числа в каждом
отчёте, и молчать об этом нельзя.
Сравнение периодов: ответ, который выглядит валидным
У metrika_stat_comparison и metrika_stat_comparison_drilldown даты периодов
**необязательны**, и Метрика на их отсутствие не ругается. Она подставляет собственное окно
(последняя неделя) в **оба** набора и возвращает сравнение периода с самим собой:
Отказывать сервер не будет — запрос ушёл ровно тем, каким его собрали. Но такой ответ
приходит с пометкой в _meta.notes: и когда даты не заданы, и когда периоды совпали явно.
Как устроена спека
Публичного openapi.json у Метрики нет, но каждая страница метода сгенерирована из OpenAPI
движком Diplodoc и отдаётся как text/markdown. Семантика (тип, required, комбинатор,
ассертация) лежит в CSS-классах вида {.json-schema-property}, поэтому спека собирается
построчным сканером по классам, а не markdown-парсером.
spec/metrika-api.json коммитится — это состав API на момент сборки. Тест на дрейф сверяет
его с llms.txt: Яндекс добавил или удалил метод — тест краснеет.
Разбор привязан к версии генератора (Diplodoc Platform v5.57.3): вся семантика висит на его