v1.8.0 — аннотации, плагины Claude Code, навыки, воронки GA4

Восьмой релиз: инструменты научились честно рассказывать о себе, появился маркетплейс плагинов Claude Code с навыками, тесты дошли до собранных артефактов, а GA4 закрыл разрыв с возможностями Analytics API.

Установка в один клик

Claude Code — маркетплейс плагинов, один источник = один плагин:

claude plugin marketplace add antohins/seo-tools-mcp
claude plugin install ga4@seo-tools-mcp

Доступны xmlstock, xmlriver, wordstat, gsc, ga4, ywm, metrika, aparser и бандл seo-tools (все восемь сразу). Ключи спрашиваются диалогом при установке; помеченные секретными уходят в системное хранилище, а не в settings.json.

Claude Desktop — .mcpb ниже, двойным кликом.

Что нового

Аннотации инструментов

Все 101 инструмент теперь машиночитаемо объявляют, что делают: readOnlyHint, openWorldHint и человекочитаемый title. Клиенты перестают спрашивать подтверждение на безопасные вызовы.

Важная деталь: read-only заявлен не всем. Его нет у 18 инструментов, которые пишут в конфиг (set_credentials, OAuth-потоки), и у 20, каждый вызов которых тратит платный ресурс — запросы к XMLStock/XMLRiver и задачи A-Parser, жгущие прокси-трафик. Иначе клиент счёл бы их безобидными и перестал спрашивать перед прогоном по пулу из сотен ключей. У платных ещё idempotentHint: false: повтор стоит ещё раз.

Маркетплейс плагинов и навыки

Девять плагинов, у каждого свои навыки — процедурные инструкции по своему источнику: как не сжечь баланс на снятии позиций, почему широкая частотность Вордстата завышает трафик в разы, отчего GA4 молча отдаёт нули, чем усреднённая позиция GSC отличается от снятой из выдачи, как читать Вебмастер вместе с Метрикой. В контексте — ~110 токенов на навык, тело подгружается при срабатывании.

Бандл ставит всё сразу, но это ~100 инструментов в каждой сессии: если работаешь с двумя источниками, ставь два плагина.

GA4: воронки, аннотации, карточка свойства, квота

• ga4_funnel — сколько пользователей дошло до каждого шага и где отвалились, с разбивкой по измерению.
• ga4_annotations — пометки на датах, включая созданные самой GA4: обычно это и есть ответ на «почему тут скачок».
• ga4_property_details — таймзона отчётов, валюта, уровень сервиса и потоки данных с их Measurement ID G-XXXXXXX.
• includeQuota во всех отчётах — сколько «токенов» Data API съел запрос и сколько осталось.

Две ловушки воронок забраны внутрь: шаги используют схему Exploration API (pagePath там отвергается), а при разбивке GA4 подмешивает к каждому шагу строку-итог, неотличимую от обычного значения — сумма по шагу удваивалась бы. Всё проверено на живом свойстве.

Тесты по протоколу

pnpm test:e2e поднимает все восемь собранных серверов как stdio-процессы и опрашивает настоящим MCP-клиентом: рукопожатие, точный список инструментов, title и аннотации. Раньше 563 теста били по исходникам, а в npm уезжает dist — этот разрыв уже приводил к бандлам, которые не стартовали.

Исправления

• Неподставленный плейсхолдер хоста (${user_config.KEY}) больше не принимается за ключ: непустая строка шаблона проходила бы за настоящий и давала ready при неработающей авторизации.
• ga4_property_details больше не выдаёт сбой запроса потоков за «у свойства нет Measurement ID».
• ga4_annotations отвергает ключевые слова дат локально — за ним Admin API, который понимает только YYYY-MM-DD.
• ga4_funnel не утверждает полноту там, где API её не сообщает.
• Гейты version:check и plugins:check в CI: версия дублируется в 42 местах, каталог plugins/ целиком генерируется из спеки.

Полный список — CHANGELOG.md.

Файлы

.mcpb — самодостаточные бандлы для Claude Desktop (~0.2 МБ, зависимости внутри). Скачать нужный и открыть двойным кликом.

v1.7.0

Added — ga4

• ga4_metadata — which dimensions/metrics exist in this property (custom ones included). A property exposes hundreds of fields (375 / 119 on a live account), so the list is searchable and capped. Each field carries type and blockedReasons — a blocked metric silently returns zeros and makes a metric filter fail with 400.
• ga4_check_compatibility — is a combination valid for this property, without paying for a report. When incompatible, the tool isolates and names the offending field (GA4 itself only says "the dimensions and metrics are incompatible"). Filters participate in compatibility, so they can be passed too.
• Period comparison in every report tool (compareStartDate/compareEndDate) — rows gain a dateRange column (current/previous). GA4's limit applies to the whole response, so a truncated comparison returns an explicit note.
• metricFilters — filter by metric values (sessions > 50).
• includeTotals — metric totals, one row per period when comparing.

Fixed — post-release review of 1.6.0 (two passes + live verification)

• ga4_events(keyEventsOnly: true) returned ALL events — the flag added a metric but no filter. Now filters on isKeyEvent. This is why seo-tools-mcp-ga4@1.6.0 is deprecated.
• landingPage → landingPagePlusQueryString; pathContains filters the grouping dimension; orderBy validated locally; ga4_realtime no longer fabricates timeZone/currency/thresholded; truncated accounts for offset; ga4_list_properties walks all pages.
• shared/google: the browser page after OAuth consent named gsc_oauth_finish for every server — GA4 users were sent to the wrong tool. 429/403 classification improved, and the 403 hint no longer discards Google's own message (which contains the "enable this API" link).

npm: seo-tools-mcp-<server>@1.7.0 (8 servers). Full details in CHANGELOG.

v1.6.0

Added

• New server ga4 — Google Analytics 4 via the Data API v1beta + Admin API (8th server): ga4_list_properties, ga4_report (arbitrary dimensions × metrics, filters, sorting), ga4_bytime, ga4_traffic_sources, ga4_geo, ga4_devices, ga4_top_pages, ga4_events, ga4_realtime.
  The OAuth app is shared with gsc (GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET) — GA4 only needs its own consent (different scope) and uses loopback port 8586 so both servers can run at once. Responses carry totalRows/truncated, the property timeZone and thresholded. Dates accept YYYY-MM-DD and GA4 keywords (28daysAgo, yesterday…), resolved in the property's timezone.
  NOTE: GA4 returns bounceRate/engagementRate as a 0..1 fraction, not a percent.

Changed

• shared: Google authorization extracted from servers/gsc into a reusable subpath @seo-tools/shared/google (createGoogleAuth, registerGoogleOauthTools, loopback). Like ./serp, it's a separate subpath so google-auth-library stays out of non-Google server bundles. gsc/index.ts shrank 644 → 323 lines with no behavior change.
• docs: .mcp.json had been missing aparser since 1.4.0 — added, together with ga4; both READMEs, .env.example and the older Dockerfiles now cover all 8 servers.

npm: seo-tools-mcp-<server>@1.6.0 (8 servers). See CHANGELOG.

v1.5.1

Patch release: code-review fixes for v1.5.0 + re-synchronization of all release channels.

Fixed

• xmlstock (billing): `yandex_xml` no longer spends an extra paid request on a partial final page.
• xmlriver: additional SERP blocks (`includeAdditional`) strip markup from title/question fields.
• xmlriver_maps: coordinate-less places are no longer emitted at `0,0` (`lat`/`lng` now optional).
• release: the 1.5.0 commit left `server.json` (×7) and the plugin manifest at 1.4.0 — all channels are re-synced at 1.5.1 (the MCP Registry goes straight to 1.5.1).

npm: `seo-tools-mcp-@1.5.1` (7 servers). See CHANGELOG.

v1.5.0

Added

• xmlriver: `xmlriver_maps` (Google Maps local pack) + geo-targeting for verticals + device tablet/os; `includeAdditional` — additional SERP blocks in `xmlriver_serp`.
• xmlstock: `yandex_xml` engine — official Yandex.XML (groupby 100, hlword highlights).
• gsc: `gsc_query` gains dimension filters + `aggregationType`.

Published to npm as `seo-tools-mcp-@1.5.0` (7 servers). Full details in CHANGELOG.

v1.4.0

Added

• New server `aparser` — bridge to a self-hosted A-Parser instance via its HTTP API (7th server). v1 is synchronous and read-only: ping/status/proxies/parsers/parser_fields/get_preset, `aparser_serp_google`, `aparser_serp_yandex`, `aparser_suggest`, `aparser_request` (universal — any of ~150 parsers) and `aparser_bulk_request`. Proxy packs are read/verified/selected (never created); presets first-class; live-proxy preflight + human captcha/burned-proxy diagnostics. Verified against a live instance. Config: `APARSER_URL` + `APARSER_PASSWORD`.
• xmlriver: `xmlriver_suggest` (Google suggestions), `xmlriver_related_questions` (People Also Ask), Google geo-targeting (`location`/`country`) and full AI Overview in `xmlriver_serp` (`includeAIOverview`).

Changed / Fixed

• Repo-wide review across all 7 servers + shared (~70 findings): security (GSC path traversal, secret masking), error classification, in-flight cache dedup, date/timezone (MSK) validation, per-server logic extracted to modules and unit-tested (tests: ~110 → ~390).
• BREAKING (metrika, 3 tools): `bounceRate` in `metrika_landing_behavior`/`metrika_search_phrases`/`metrika_top_landings` is now a percent (0–100), consistent with all other metrika tools (was a 0–1 fraction).

Published to npm as `seo-tools-mcp-@1.4.0` (7 servers). Full details in CHANGELOG.

v1.3.0

Added

• XMLStock server: Yandex Wordstat (endpoint `/wordstat/json/`, official Wordstat API v2). New tools: `xmlstock_wordstat` (top + related queries with frequency, region-scoped, Wordstat operators), `xmlstock_wordstat_dynamics` (frequency over time), `xmlstock_wordstat_regions` (demand by region + affinity index, region names resolved), `xmlstock_wordstat_regions_tree`.

Uses the same `XMLSTOCK_*` key as SERP — no separate Yandex Cloud setup needed. Verified against the live API. Published to npm as `seo-tools-mcp-@1.3.0` (6 servers).

v1.2.1

Docs-only release: promo/branding renamed Satellite1 → PBN Workers (pbn-workers.com) across all READMEs. No code changes. Published to npm as seo-tools-mcp-<server>@1.2.1 (6 servers).

v1.2.0

Added

• New server xmlriver — Google/Yandex SERP via XMLRiver, a second SERP provider alongside XMLStock. Tools: `xmlriver_serp` (organic, depth in one request via `groupby`, AI-Overview flag), `xmlriver_images`, `xmlriver_news`, `xmlriver_check_index` (URL indexation — Google, unique to XMLRiver), `xmlriver_balance`. All requests over HTTPS. Verified end-to-end against the live API.
• Shared Yandex.XML SERP parser (`@seo-tools/shared/serp`) reused by XMLStock and XMLRiver.

Changed

• Docker images: filtered per-server install, `tini` as PID 1, manifest-first layer caching.

Published to npm as `seo-tools-mcp-@1.2.0` (6 servers) and the official MCP Registry.

v1.1.0

Major read-only tool expansion across all five servers (~14 → ~38 tools), each verified against live APIs.

Added

• GSC (2→6): `gsc_inspect_url` (URL Inspection — index status, coverage, canonical, last crawl, mobile usability, rich results), `gsc_list_sitemaps`, `gsc_get_sitemap`, `gsc_get_site`; `dataState` on `gsc_query`.
• XMLStock (2→5): Google verticals `xmlstock_images` / `_news` / `_video`; new web params — `safeSearch`, `includeSimilar` (Google), `filter`, `sortby`, `maxpassages`, `l10n` (Yandex).
• Wordstat: `wordstat_regions` now resolves `region_id` → region name (cached).
• YWM (4→13): `ywm_summary`, `ywm_sqi_history`, `ywm_indexing_history`, `ywm_external_links` (backlinks), `ywm_broken_links`, `ywm_diagnostics`, `ywm_important_urls`, `ywm_sitemaps`, `ywm_queries_history`.
• Metrica (4→10): `metrika_report` (arbitrary dimensions × metrics), `metrika_bytime`, `metrika_traffic_sources`, `metrika_geo`, `metrika_devices`, `metrika_goals`.

All servers remain read-only. Published to npm as `seo-tools-mcp-@1.1.0`.