yandex-direct-mcp-plus 1.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 theYahia
+Copyright (c) 2026 Pavelsiba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# yandex-direct-mcp-plus
+
+MCP-сервер для API Яндекс.Директ — управление контекстной рекламой из любого MCP-клиента (Claude, Cursor и др.): кампании, объявления, аудитории, изображения, фиды, уточнения, ставки, минус-фразы, стратегии, расписание показов, статистика и баланс. **51 инструмент.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-green.svg)](https://nodejs.org)
+
+> Деньги — **в рублях** (бюджеты, ставки на вводе и выводе); сервер сам конвертирует в микроединицы API. Поддержан **агентский режим** (Client-Login).
+>
+> Все ID передаются строками (`"1915016273214320641"`). Это сохраняет 64-битные идентификаторы Яндекс.Директа без потери точности в JavaScript.
+
+> [!NOTE]
+> В npm пакет пока не опубликован — ставится сборкой из исходников. Публикация будет отдельным релизом.
+
+## Установка
+
+```bash
+git clone git@github.com:Pavelsiba/yandex-direct-mcp-plus.git
+cd yandex-direct-mcp-plus
+npm ci && npm run build
+```
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "yandex-direct": {
+      "command": "node",
+      "args": ["/путь/к/yandex-direct-mcp-plus/dist/app/index.js"],
+      "env": {
+        "YANDEX_DIRECT_TOKEN": "ваш_токен"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add yandex-direct -e YANDEX_DIRECT_TOKEN=ваш_токен -- node /путь/к/yandex-direct-mcp-plus/dist/app/index.js
+```
+## Конфигурация (переменные окружения)
+
+| Переменная | Обязательна | Назначение |
+|------------|:-----------:|------------|
+| `YANDEX_DIRECT_TOKEN` | да | OAuth-токен Яндекс.Директ |
+| `YANDEX_DIRECT_LOGIN` | нет | Логин клиента для агентских токенов (заголовок `Client-Login`). Обязателен, если токен агентский |
+| `YANDEX_DIRECT_POLYGON_CAMPAIGN_ID` | нет | Только для `npm run test:int`: ID кампании-полигона, оставленной черновиком. Сетевые тесты пишут в неё и ни во что другое; без переменной они пропускаются |
+
+### Как получить токен
+
+OAuth-токен выпускается для приложения, зарегистрированного в [Яндекс OAuth](https://oauth.yandex.ru/), с доступом к API Директа. Подробности — [регистрация приложения и получение токена](https://yandex.ru/dev/direct/doc/ru/token). Доступ к API нужно [запросить в интерфейсе Директа](https://yandex.ru/dev/direct/doc/ru/access-request).
+
+## ⚠️ Внимание: реальные траты
+
+Инструменты `create_campaign`, `create_text_ad`, `add_keywords`, `set_keyword_bids` и др. меняют боевой рекламный аккаунт и могут **расходовать деньги**.
+
+Тестовой среды у Яндекс.Директа больше нет: песочница отключена с июля 2026, и любой вызов идёт по боевому аккаунту. Отлаживать сценарии приходится на отдельной кампании, оставленной черновиком, — показов она не даёт и потому не тратит бюджет, пока не пройдёт модерацию и не будет включена.
+
+## Инструменты (51)
+
+**Кампании**
+
+| Инструмент | Описание |
+|------------|----------|
+| `list_campaigns` | Список кампаний (фильтр по статусу/типу, пагинация) |
+| `get_campaign` | Детальная информация о кампании по ID |
+| `create_campaign` | Создать кампанию (бюджет в рублях, выбор стратегии, часовой пояс, UTM-разметка) |
+| `update_campaign` | Обновить название/бюджет/UTM-разметку и/или статус (SUSPEND/RESUME/ARCHIVE/UNARCHIVE) |
+| `manage_campaigns` | suspend/resume/archive/unarchive для списка кампаний |
+| `get_strategy` | Получить стратегию текстово-графической кампании |
+| `set_strategy` | Сменить стратегию: ручная, максимум кликов, средняя цена клика/конверсии, оплата за конверсию |
+| `get_time_targeting` | Расписание показов: часовой пояс, часы по дням недели, праздники |
+| `set_time_targeting` | Задать расписание показов и почасовые коэффициенты (заменяет целиком) |
+
+**Группы объявлений**
+
+| Инструмент | Описание |
+|------------|----------|
+| `list_ad_groups` | Группы объявлений выбранных кампаний |
+| `create_ad_group` | Создать группу с таргетингом по регионам |
+| `delete_ad_groups` | Удалить группы по ID |
+| `set_ad_group_negative_keywords` | Минус-фразы группы: `mode` обязателен — `replace`, `add` или `remove` |
+
+**Объявления**
+
+| Инструмент | Описание |
+|------------|----------|
+| `list_ads` | Объявления в группах |
+| `create_text_ad` | Создать текстовое объявление (≤56/≤30/≤81) |
+| `update_text_ad` | Обновить заголовок/текст/ссылку |
+| `manage_ads` | suspend/resume/archive/unarchive/moderate/delete |
+| `moderate_ads` | Отправить объявления на модерацию |
+
+**Ключевые слова и ставки**
+
+| Инструмент | Описание |
+|------------|----------|
+| `list_keywords` | Ключевые фразы в группах (ставки в рублях) |
+| `add_keywords` | Добавить ключевые фразы |
+| `set_keyword_bids` | Установить ставки (поиск/сети, рубли) на фразах/группах/кампаниях |
+| `manage_keywords` | suspend/resume/delete |
+| `set_campaign_negative_keywords` | Минус-фразы кампании: `mode` обязателен — `replace`, `add` или `remove` |
+| `get_campaign_negative_keywords` | Получить минус-фразы кампаний |
+
+**Быстрые ссылки, уточнения и корректировки**
+
+| Инструмент | Описание |
+|------------|----------|
+| `list_sitelinks` | Получить наборы быстрых ссылок |
+| `set_sitelinks` | Создать новый набор быстрых ссылок |
+| `list_ad_extensions` | Получить уточнения (callouts) |
+| `add_ad_extensions` | Создать уточнения |
+| `delete_ad_extensions` | Удалить уточнения |
+| `manage_ad_images` | Загрузить, получить или удалить изображения |
+| `get_bid_adjustments` | Получить корректировки по устройствам, полу и возрасту |
+| `set_bid_adjustments` | Изменить коэффициенты существующих корректировок |
+
+**Аудитории, цели и фиды**
+
+| Инструмент | Описание |
+|------------|----------|
+| `list_retargeting_lists` | Получить условия ретаргетинга и подбора аудитории |
+| `add_retargeting_list` | Создать условие ретаргетинга |
+| `list_audience_targets` | Получить аудиторные цели |
+| `set_audience_targets` | add/set_bids/suspend/resume/delete аудиторных целей |
+| `list_dynamic_targets` | Получить динамические цели |
+| `manage_dynamic_targets` | add/set_bids/suspend/resume/delete динамических целей |
+| `list_feeds` | Получить товарные фиды |
+| `list_negative_keyword_shared_sets` | Получить общие наборы минус-фраз |
+| `manage_negative_keyword_shared_sets` | add/update/delete общих наборов |
+| `link_negative_keyword_sets` | Привязать общие наборы к кампаниям и группам объявлений |
+
+**Статистика, аккаунт, справочники**
+
+| Инструмент | Описание |
+|------------|----------|
+| `get_statistics` | Статистика за период (показы, клики, расход, CTR, CPC) |
+| `get_search_queries` | Фактические поисковые запросы для подбора минус-фраз |
+| `get_changes` | Проверить изменения кампаний, групп и объявлений |
+| `list_vcards` | Получить виртуальные визитки |
+| `add_vcard` | Создать виртуальную визитку |
+| `list_businesses` | Получить профили организаций Яндекс Бизнеса |
+| `get_account_balance` | Баланс аккаунта (Live API v4) |
+| `get_regions` | Справочник кодов регионов (225 = Россия) |
+| `list_time_zones` | Справочник часовых поясов для расписания показов |
+
+## Примеры запросов
+
+```
+Покажи все активные рекламные кампании
+Создай кампанию "Летняя распродажа" с бюджетом 5000 ₽/день, старт 2026-05-01
+Установи ставку 25 ₽ на ключевые фразы 111 и 222
+Добавь минус-фразы "бесплатно", "скачать" в кампанию 12345
+Какая статистика у кампаний 12345 и 67890 за последнюю неделю?
+Найди код региона для Новосибирска
+Покажи баланс аккаунта
+```
+
+## Разработка
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # vitest (моки fetch)
+npm run dev        # tsx --conditions=development src/app/index.ts
+npm run lint       # biome
+npm run typecheck  # tsc --noEmit
+npm run lint:dead  # knip
+```
+
+Код разложен по слоям `app → tools → shared`; инструмент — это каталог
+`src/tools/<домен>/` с `schema.ts`, `handler.ts` и `tool.ts`. Подробности —
+в [docs/architecture.md](docs/architecture.md).
+
+## Происхождение и благодарности
+
+Проект начат на коде [`theYahia/yandex-direct-mcp`](https://github.com/theYahia/yandex-direct-mcp) под лицензией MIT. Расширение с 20 до 48 инструментов и перевод ID на строки — работа [**Maxim (DrSeedon)**](https://github.com/DrSeedon), [PR #7](https://github.com/theYahia/yandex-direct-mcp/pull/7); в npm эта версия не публиковалась. Дальше проект развивается самостоятельно и апстрим не отслеживает.
+
+История до отделения от апстрима (версии 3.0.0–5.0.0, включая вклад DrSeedon) — в [docs/CHANGELOG-upstream.md](docs/CHANGELOG-upstream.md); дальнейшие изменения — в [CHANGELOG.md](CHANGELOG.md). План — в [docs/roadmap.md](docs/roadmap.md), архитектура — в [docs/architecture.md](docs/architecture.md).
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE). Уведомление об авторских правах исходного проекта сохранено.

package/dist/app/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/app/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Точка входа: поднимает сервер на stdio-транспорте и больше ничего не делает.
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { tools } from "#app/registry";
+import { createServer, readVersion } from "#app/server";
+async function main() {
+    const server = createServer(tools);
+    await server.connect(new StdioServerTransport());
+    // stdout занят транспортом MCP — любые сообщения только в stderr.
+    console.error(`[yd-mcp] v${readVersion()} запущен. ${tools.length} инструментов. Требуется YANDEX_DIRECT_TOKEN.`);
+}
+main().catch((error) => {
+    console.error("[yd-mcp] Ошибка запуска:", error);
+    process.exit(1);
+});

package/dist/app/registry.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDescriptor } from "#shared/lib/tool";
+export declare const tools: readonly ToolDescriptor[];

package/dist/app/registry.js

@@ -0,0 +1,83 @@
+import { getAccountBalanceTool } from "#tools/account/tool";
+import { addAdExtensionsTool, deleteAdExtensionsTool, listAdExtensionsTool } from "#tools/ad-extensions/tool";
+import { createAdGroupTool, deleteAdGroupsTool, listAdGroupsTool } from "#tools/ad-groups/tool";
+import { manageAdImagesTool } from "#tools/ad-images/tool";
+import { createTextAdTool, listAdsTool, manageAdsTool, moderateAdsTool, updateTextAdTool } from "#tools/ads/tool";
+import { listAudienceTargetsTool, setAudienceTargetsTool } from "#tools/audience-targets/tool";
+import { getBidAdjustmentsTool, setBidAdjustmentsTool } from "#tools/bid-adjustments/tool";
+import { listBusinessesTool } from "#tools/businesses/tool";
+import { createCampaignTool, getCampaignTool, getStrategyTool, listCampaignsTool, manageCampaignsTool, setStrategyTool, updateCampaignTool } from "#tools/campaigns/tool";
+import { getChangesTool } from "#tools/changes/tool";
+import { getRegionsTool, listTimeZonesTool } from "#tools/dictionaries/tool";
+import { listDynamicTargetsTool, manageDynamicTargetsTool } from "#tools/dynamic-targets/tool";
+import { listFeedsTool } from "#tools/feeds/tool";
+import { addKeywordsTool, listKeywordsTool, manageKeywordsTool, setKeywordBidsTool } from "#tools/keywords/tool";
+import { getCampaignNegativeKeywordsTool, linkNegativeKeywordSetsTool, listNegativeKeywordSharedSetsTool, manageNegativeKeywordSharedSetsTool, setAdGroupNegativeKeywordsTool, setCampaignNegativeKeywordsTool } from "#tools/negative-keywords/tool";
+import { addRetargetingListTool, listRetargetingListsTool } from "#tools/retargeting/tool";
+import { getSearchQueriesTool } from "#tools/search-queries/tool";
+import { listSitelinksTool, setSitelinksTool } from "#tools/sitelinks/tool";
+import { getStatisticsTool } from "#tools/statistics/tool";
+import { getTimeTargetingTool, setTimeTargetingTool } from "#tools/time-targeting/tool";
+import { addVcardTool, listVcardsTool } from "#tools/vcards/tool";
+export const tools = [
+    // Кампании и стратегии
+    listCampaignsTool,
+    getCampaignTool,
+    createCampaignTool,
+    updateCampaignTool,
+    manageCampaignsTool,
+    getStrategyTool,
+    setStrategyTool,
+    getTimeTargetingTool,
+    setTimeTargetingTool,
+    // Группы объявлений
+    listAdGroupsTool,
+    createAdGroupTool,
+    deleteAdGroupsTool,
+    // Объявления
+    listAdsTool,
+    createTextAdTool,
+    updateTextAdTool,
+    manageAdsTool,
+    moderateAdsTool,
+    // Ключевые фразы и ставки
+    listKeywordsTool,
+    addKeywordsTool,
+    manageKeywordsTool,
+    setKeywordBidsTool,
+    // Минус-фразы
+    getCampaignNegativeKeywordsTool,
+    setCampaignNegativeKeywordsTool,
+    setAdGroupNegativeKeywordsTool,
+    listNegativeKeywordSharedSetsTool,
+    manageNegativeKeywordSharedSetsTool,
+    linkNegativeKeywordSetsTool,
+    // Ассеты объявления
+    listSitelinksTool,
+    setSitelinksTool,
+    listAdExtensionsTool,
+    addAdExtensionsTool,
+    deleteAdExtensionsTool,
+    manageAdImagesTool,
+    listVcardsTool,
+    addVcardTool,
+    // Таргетинг и корректировки
+    listAudienceTargetsTool,
+    setAudienceTargetsTool,
+    listDynamicTargetsTool,
+    manageDynamicTargetsTool,
+    listRetargetingListsTool,
+    addRetargetingListTool,
+    getBidAdjustmentsTool,
+    setBidAdjustmentsTool,
+    // Отчёты
+    getStatisticsTool,
+    getSearchQueriesTool,
+    // Аккаунт и справочники
+    getAccountBalanceTool,
+    listBusinessesTool,
+    getChangesTool,
+    listFeedsTool,
+    getRegionsTool,
+    listTimeZonesTool
+];

package/dist/app/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ToolDescriptor } from "#shared/lib/tool";
+export declare function readVersion(): string;
+export declare function createServer(tools: readonly ToolDescriptor[]): McpServer;

package/dist/app/server.js

@@ -0,0 +1,30 @@
+// Композиция сервера: единственное место, знающее про McpServer и транспорт.
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+export function readVersion() {
+    try {
+        // biome-ignore lint/plugin: package.json, идентификаторов Директа здесь нет
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export function createServer(tools) {
+    const server = new McpServer({ name: "yd-mcp", version: readVersion() });
+    for (const tool of tools) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.schema.shape,
+            annotations: tool.annotations
+        }, async (params) => ({
+            content: [{ type: "text", text: await tool.run(params) }]
+        }));
+    }
+    return server;
+}

package/dist/shared/api/client.d.ts

@@ -0,0 +1 @@
+export declare function apiPost(service: string, method: string, params?: Record<string, unknown>): Promise<unknown>;

package/dist/shared/api/client.js

@@ -0,0 +1,16 @@
+// JSON API v5 — основной клиент: один POST на сервис с телом { method, params }.
+import { assertNoApiError } from "#shared/api/errors";
+import { commonHeaders, fetchWithRetry, logUnits } from "#shared/api/fetch";
+import { parseJson, stringifyJson } from "#shared/api/json";
+import { BASE_URL } from "#shared/config/endpoints";
+export async function apiPost(service, method, params = {}) {
+    const response = await fetchWithRetry(`${BASE_URL}${service}`, {
+        method: "POST",
+        headers: commonHeaders(),
+        body: stringifyJson({ method, params })
+    });
+    logUnits(response);
+    const data = parseJson(await response.text());
+    assertNoApiError(data);
+    return data;
+}

package/dist/shared/api/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function assertNoApiError(data: unknown): void;
+export declare function assertNoApiErrorV4(data: Record<string, unknown> | null): void;

package/dist/shared/api/errors.js

@@ -0,0 +1,21 @@
+// Разбор ошибок Директа. Хендлеры сюда не заглядывают: их дело — сценарий.
+// v5 возвращает ошибку уровня запроса телом с HTTP 200 — статус проверять бесполезно,
+// признак ошибки один: ключ `error`. Док: https://yandex.ru/dev/direct/doc/en/concepts/errors-list
+export function assertNoApiError(data) {
+    const error = data?.error;
+    if (!error || typeof error !== "object")
+        return;
+    const parts = [`Ошибка API Яндекс.Директ [${error.error_code ?? "?"}]: ${error.error_string ?? "неизвестная ошибка"}`];
+    if (error.error_detail)
+        parts.push(`— ${error.error_detail}`);
+    if (error.request_id)
+        parts.push(`(request_id: ${error.request_id})`);
+    throw new Error(parts.join(" "));
+}
+// v4 отвечает по-своему: error_str вместо error_string, признак — любой из двух ключей.
+export function assertNoApiErrorV4(data) {
+    if (!data || (data.error_code === undefined && data.error_str === undefined))
+        return;
+    const detail = data.error_detail ? ` — ${data.error_detail}` : "";
+    throw new Error(`Ошибка API v4 [${data.error_code ?? "?"}]: ${data.error_str ?? "неизвестная ошибка"}${detail}`);
+}

package/dist/shared/api/fetch.d.ts

@@ -0,0 +1,5 @@
+export declare function commonHeaders(): Record<string, string>;
+export declare function logUnits(response: Response): void;
+export type Transport = (url: string, options: RequestInit) => Promise<Response>;
+export declare function setTransport(next: Transport): void;
+export declare function fetchWithRetry(url: string, options?: RequestInit, retries?: number): Promise<Response>;

package/dist/shared/api/fetch.js

@@ -0,0 +1,62 @@
+// Транспорт: заголовки, повторы, таймаут. Знает про HTTP и токен, не знает про домен.
+import { getClientLogin, getToken } from "#shared/config/env";
+import { MAX_RETRIES, MAX_RETRY_DELAY_MS, REQUEST_TIMEOUT_MS } from "#shared/config/limits";
+export function commonHeaders() {
+    const headers = {
+        Authorization: `Bearer ${getToken()}`,
+        "Content-Type": "application/json",
+        "Accept-Language": "ru"
+    };
+    const clientLogin = getClientLogin();
+    if (clientLogin)
+        headers["Client-Login"] = clientLogin;
+    return headers;
+}
+// Units = «израсходовано/остаток/суточный лимит» баллов API. В stdout писать нельзя —
+// там транспорт MCP, поэтому stderr.
+export function logUnits(response) {
+    const units = response.headers?.get?.("Units");
+    if (units)
+        console.error(`[yd-mcp] Баллы API (потрачено/остаток/лимит): ${units}`);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Шов для тестов. Раньше они подменяли globalThis.fetch — глобал один на процесс, и
+// подмена задевала всё, что в нём живёт, включая SDK. Здесь шов свой, объявлен типом
+// и виден в коде; сеть трогает единственная строка ниже.
+let transport = (url, options) => fetch(url, options);
+export function setTransport(next) {
+    transport = next;
+}
+export async function fetchWithRetry(url, options = {}, retries = MAX_RETRIES) {
+    for (let attempt = 1; attempt <= retries; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const response = await transport(url, { ...options, signal: controller.signal });
+            clearTimeout(timer);
+            if (response.ok)
+                return response;
+            if (response.status >= 500 && attempt < retries) {
+                const backoff = Math.min(1000 * 2 ** (attempt - 1), MAX_RETRY_DELAY_MS);
+                console.error(`[yd-mcp] ${response.status} от ${url}, повтор через ${backoff}мс (${attempt}/${retries})`);
+                await delay(backoff);
+                continue;
+            }
+            const body = await response.text().catch(() => "");
+            throw new Error(`HTTP ${response.status}: ${response.statusText}. ${body}`);
+        }
+        catch (error) {
+            clearTimeout(timer);
+            if (attempt === retries)
+                throw error;
+            if (error instanceof DOMException && error.name === "AbortError") {
+                console.error(`[yd-mcp] Таймаут ${url}, повтор (${attempt}/${retries})`);
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error("Все попытки исчерпаны");
+}

package/dist/shared/api/json.d.ts

@@ -0,0 +1,2 @@
+export declare function parseJson(text: string): unknown;
+export declare function stringifyJson(value: unknown): string;

package/dist/shared/api/json.js

@@ -0,0 +1,13 @@
+// biome-ignore-all lint/plugin: единственное место в проекте, где вызывается разбор JSON
+// ID Директа — 64-битные целые, в живых аккаунтах 19-значные. Родной JSON.parse молча
+// округляет их до 2^53−1, превращая ID в валидное число, указывающее на другой объект.
+// storeAsString отдаёт большие числа строками; сериализация принимает BigInt.
+// Разбор и сериализация JSON живут только здесь — держит GritQL-плагин Biome.
+import JSONbigFactory from "json-bigint";
+const JSONbig = JSONbigFactory({ storeAsString: true });
+export function parseJson(text) {
+    return JSONbig.parse(text);
+}
+export function stringifyJson(value) {
+    return JSONbig.stringify(value);
+}

package/dist/shared/api/parse.d.ts

@@ -0,0 +1,2 @@
+import type { z } from "zod";
+export declare function parseApiResult<Schema extends z.ZodType>(schema: Schema, value: unknown, what: string): z.infer<Schema>;

package/dist/shared/api/parse.js

@@ -0,0 +1,10 @@
+import { prettifyError } from "zod";
+// Схемы ответов пишутся нестрогими (`z.looseObject`): Директ добавляет поля без
+// предупреждения, и строгая схема превратила бы такое добавление в отказ инструмента.
+// Обязательными объявляются только поля, на которые опирается сам инструмент.
+export function parseApiResult(schema, value, what) {
+    const parsed = schema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    throw new Error(`Директ вернул ${what} в неожиданной форме: ${prettifyError(parsed.error)}`);
+}

package/dist/shared/api/reports.d.ts

@@ -0,0 +1,6 @@
+export type ReportOptions = {
+    skipReportHeader?: boolean;
+    skipReportSummary?: boolean;
+    skipColumnHeader?: boolean;
+};
+export declare function apiReport(params: Record<string, unknown>, opts?: ReportOptions): Promise<string>;

package/dist/shared/api/reports.js

@@ -0,0 +1,45 @@
+// ReportService отдаёт TSV и работает офлайн: 200 — отчёт готов, 201 — поставлен
+// в очередь, 202 — ещё формируется, повторить через retryIn секунд.
+// Док: https://yandex.ru/dev/direct/doc/en/codes
+import { commonHeaders, fetchWithRetry, logUnits } from "#shared/api/fetch";
+import { stringifyJson } from "#shared/api/json";
+import { REPORT_URL } from "#shared/config/endpoints";
+import { REPORT_DEFAULT_RETRY_IN_SEC, REPORT_MAX_POLLS, REPORT_MAX_RETRY_IN_SEC } from "#shared/config/limits";
+function reportHeaders(opts) {
+    return {
+        ...commonHeaders(),
+        processingMode: "auto",
+        returnMoneyInMicros: "false",
+        skipReportHeader: opts.skipReportHeader === false ? "false" : "true",
+        skipReportSummary: opts.skipReportSummary ? "true" : "false",
+        skipColumnHeader: opts.skipColumnHeader ? "true" : "false"
+    };
+}
+// Сервер называет паузу в заголовке retryIn; на мусор и его отсутствие — свой дефолт.
+function retryInSeconds(response) {
+    const raw = response.headers?.get?.("retryIn");
+    const parsed = raw == null ? Number.NaN : Number(raw);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : REPORT_DEFAULT_RETRY_IN_SEC;
+}
+export async function apiReport(params, opts = {}) {
+    const headers = reportHeaders(opts);
+    const body = stringifyJson({ params });
+    for (let poll = 0; poll <= REPORT_MAX_POLLS; poll++) {
+        const response = await fetchWithRetry(REPORT_URL, { method: "POST", headers, body });
+        logUnits(response);
+        if (response.status === 200)
+            return response.text();
+        if (response.status === 201 || response.status === 202) {
+            if (poll === REPORT_MAX_POLLS) {
+                throw new Error(`Отчёт всё ещё формируется после ${REPORT_MAX_POLLS} попыток опроса. Повторите запрос позже.`);
+            }
+            const retryIn = retryInSeconds(response);
+            console.error(`[yd-mcp] Отчёт формируется (HTTP ${response.status}), повтор через ${retryIn}с (${poll + 1}/${REPORT_MAX_POLLS})`);
+            await new Promise((resolve) => setTimeout(resolve, Math.min(retryIn, REPORT_MAX_RETRY_IN_SEC) * 1000));
+            continue;
+        }
+        // Прочие коды сюда не доходят: fetchWithRetry бросает на всём, что не ok.
+        return response.text();
+    }
+    throw new Error("Не удалось получить отчёт");
+}

package/dist/shared/api/v4.d.ts

@@ -0,0 +1 @@
+export declare function apiV4(method: string, param?: Record<string, unknown>): Promise<unknown>;

package/dist/shared/api/v4.js

@@ -0,0 +1,18 @@
+// Live API v4 — только ради баланса аккаунта, в v5 финансовой информации нет.
+// Формат тела свой: { method, token, param }, токен внутри, а не в заголовке.
+import { assertNoApiErrorV4 } from "#shared/api/errors";
+import { fetchWithRetry, logUnits } from "#shared/api/fetch";
+import { parseJson, stringifyJson } from "#shared/api/json";
+import { V4_URL } from "#shared/config/endpoints";
+import { getToken } from "#shared/config/env";
+export async function apiV4(method, param = {}) {
+    const response = await fetchWithRetry(V4_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Accept-Language": "ru" },
+        body: stringifyJson({ method, token: getToken(), param })
+    });
+    logUnits(response);
+    const data = parseJson(await response.text());
+    assertNoApiErrorV4(data);
+    return data;
+}

package/dist/shared/config/endpoints.d.ts

@@ -0,0 +1,3 @@
+export declare const BASE_URL = "https://api.direct.yandex.com/json/v5/";
+export declare const REPORT_URL = "https://api.direct.yandex.com/json/v5/reports";
+export declare const V4_URL = "https://api.direct.yandex.ru/live/v4/json/";

package/dist/shared/config/endpoints.js

@@ -0,0 +1,8 @@
+// Эндпоинты Директа. Выбирать не из чего: песочница отключена Яндексом с июля 2026
+// (ответ поддержки 05.09.2026), контур один — боевой. Отсюда константы, а не функции.
+export const BASE_URL = "https://api.direct.yandex.com/json/v5/";
+export const REPORT_URL = `${BASE_URL}reports`;
+// Баланс общего счёта есть только в Live API v4 (AccountManagement.Get). Финансы в v5
+// не отсутствуют вовсе — у кампании это поле Funds, у клиента Bonuses и
+// OverdraftSumAvailable, — но суммы на счёте среди них нет. Сверено с WSDL 05.09.2026.
+export const V4_URL = "https://api.direct.yandex.ru/live/v4/json/";

package/dist/shared/config/enums.d.ts

@@ -0,0 +1,30 @@
+export declare const CAMPAIGN_STATUSES: readonly ["ACCEPTED", "DRAFT", "MODERATION", "REJECTED"];
+export declare const KEYWORD_ACTIONS: readonly ["suspend", "resume", "delete"];
+export declare const AD_ACTIONS: readonly ["suspend", "resume", "archive", "unarchive", "moderate", "delete"];
+export declare const CAMPAIGN_ACTIONS: readonly ["suspend", "resume", "archive", "unarchive"];
+export declare const CAMPAIGN_STATUS_ACTIONS: readonly ["SUSPEND", "RESUME", "ARCHIVE", "UNARCHIVE"];
+export declare const CAMPAIGN_TYPES_CREATABLE: readonly ["TEXT_CAMPAIGN", "DYNAMIC_TEXT_CAMPAIGN"];
+export declare const CAMPAIGN_TYPES: readonly ["TEXT_CAMPAIGN", "MOBILE_APP_CAMPAIGN", "DYNAMIC_TEXT_CAMPAIGN", "CPM_BANNER_CAMPAIGN", "SMART_CAMPAIGN", "UNIFIED_CAMPAIGN"];
+export declare const SEARCH_STRATEGIES: readonly ["HIGHEST_POSITION", "IMPRESSIONS_BELOW_SEARCH", "WB_MAXIMUM_CLICKS", "WB_MAXIMUM_CONVERSION_RATE", "WEEKLY_CLICK_PACKAGE", "AVERAGE_CPC", "AVERAGE_CPA", "AVERAGE_CPA_MULTIPLE_GOALS", "AVERAGE_ROI", "AVERAGE_CRR", "PAY_FOR_CONVERSION", "PAY_FOR_CONVERSION_CRR", "PAY_FOR_CONVERSION_MULTIPLE_GOALS", "MAX_PROFIT", "SERVING_OFF"];
+export declare const NETWORK_STRATEGIES: readonly ["NETWORK_DEFAULT", "MAXIMUM_COVERAGE", "WB_MAXIMUM_CLICKS", "WB_MAXIMUM_CONVERSION_RATE", "WEEKLY_CLICK_PACKAGE", "AVERAGE_CPC", "AVERAGE_CPA", "AVERAGE_CPA_MULTIPLE_GOALS", "AVERAGE_ROI", "AVERAGE_CRR", "PAY_FOR_CONVERSION", "PAY_FOR_CONVERSION_CRR", "PAY_FOR_CONVERSION_MULTIPLE_GOALS", "MAX_PROFIT", "SERVING_OFF"];
+export declare const NEGATIVE_KEYWORD_SET_ACTIONS: readonly ["add", "update", "delete"];
+export declare const AD_EXTENSION_STATES: readonly ["ON", "DELETED"];
+export declare const AD_EXTENSION_STATUSES: readonly ["ACCEPTED", "DRAFT", "MODERATION", "REJECTED"];
+export declare const AD_IMAGE_TYPES: readonly ["REGULAR", "WIDE", "FIXED_IMAGE", "AUTO"];
+export declare const AD_IMAGE_ACTIONS: readonly ["add", "get", "delete"];
+export declare const ASSOCIATED_FLAGS: readonly ["YES", "NO"];
+export declare const RETARGETING_TYPES: readonly ["RETARGETING", "AUDIENCE"];
+export declare const RETARGETING_RULE_OPERATORS: readonly ["ALL", "ANY", "NONE"];
+export declare const BID_ADJUSTMENT_TYPES: readonly ["MOBILE_ADJUSTMENT", "TABLET_ADJUSTMENT", "DESKTOP_ADJUSTMENT", "DESKTOP_ONLY_ADJUSTMENT", "DEMOGRAPHICS_ADJUSTMENT"];
+export declare const BID_ADJUSTMENT_LEVELS: readonly ["CAMPAIGN", "AD_GROUP"];
+export declare const AUDIENCE_TARGET_STATES: readonly ["ON", "SUSPENDED"];
+export declare const AUDIENCE_TARGET_ACTIONS: readonly ["add", "set_bids", "suspend", "resume", "delete"];
+export declare const STRATEGY_PRIORITIES: readonly ["LOW", "NORMAL", "HIGH"];
+export declare const DYNAMIC_TARGET_ACTIONS: readonly ["add", "set_bids", "suspend", "resume", "delete"];
+export declare const WEBPAGE_CONDITION_OPERANDS: readonly ["URL", "DOMAIN", "PAGE_TITLE", "PAGE_CONTENT", "OFFERS_LIST_URL"];
+export declare const WEBPAGE_CONDITION_OPERATORS: readonly ["EQUALS_ANY", "NOT_EQUALS_ALL", "CONTAINS_ANY", "NOT_CONTAINS_ALL"];
+export declare const CHANGES_MODES: readonly ["campaigns", "objects"];
+export declare const CHANGES_FIELD_NAMES: readonly ["CampaignIds", "AdGroupIds", "AdIds", "CampaignsStat"];
+export declare const SETTABLE_SEARCH_STRATEGIES: readonly ["HIGHEST_POSITION", "WB_MAXIMUM_CLICKS", "AVERAGE_CPC", "AVERAGE_CPA", "PAY_FOR_CONVERSION", "SERVING_OFF"];
+export declare const SETTABLE_NETWORK_STRATEGIES: readonly ["NETWORK_DEFAULT", "MAXIMUM_COVERAGE", "WB_MAXIMUM_CLICKS", "AVERAGE_CPC", "AVERAGE_CPA", "PAY_FOR_CONVERSION", "SERVING_OFF"];
+export declare const WEEKDAYS: readonly ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"];