feat: period-aggregate defaults + L3 input guards + deterministic getAll cap (1.0.2)

- LD: drop Date from default report fields (period aggregate, not daily split)
- L3: fail-loud on ALL_TIME without campaign filter and on explicit filter -> 0 rows
- L3: clamp list_* limit to MAX_TOOL_LIMIT=1000 (single-page); getAll pages at
  DEFAULT_PAGE_LIMIT deterministically, maxPages=100 (~1M cap), loud _truncated marker

Author: gistrec

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-yandex-direct",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP server for the Yandex Direct API v5 — manage PPC campaigns, ad groups, ads, keywords and pull statistics from AI agents.",
   "type": "module",
   "bin": {

src/client.test.ts

@@ -127,7 +127,7 @@ test("getAll merges pages by following LimitedBy and clears it when done", async
   }
 });
 
-test("getAll stops at maxPages and keeps LimitedBy as a 'more remains' signal", async () => {
+test("getAll stops at maxPages and flags the truncation loudly", async () => {
   let calls = 0;
   const mock = mockFetch(() => {
     calls++;
@@ -138,13 +138,17 @@ test("getAll stops at maxPages and keeps LimitedBy as a 'more remains' signal",
   });
   try {
     const client = new YandexDirectClient({ token: "T", lang: "ru", sandbox: true });
-    const result = await client.getAll<{ Campaigns: unknown[]; LimitedBy?: number }>(
-      "campaigns",
-      {},
-      2,
-    );
+    const result = await client.getAll<{
+      Campaigns: unknown[];
+      LimitedBy?: number;
+      _truncated?: boolean;
+      _truncatedNote?: string;
+    }>("campaigns", {}, 2);
     assert.equal(calls, 2);
     assert.equal(result.Campaigns.length, 2);
+    // Hitting the cap is explicit, not a bare LimitedBy that the model may ignore.
+    assert.equal(result._truncated, true);
+    assert.match(result._truncatedNote ?? "", /more objects remain/);
     assert.notEqual(result.LimitedBy, undefined);
   } finally {
     mock.restore();

src/client.ts

@@ -129,16 +129,26 @@ export class YandexDirectClient {
   /**
    * Runs a `get` request, following the LimitedBy cursor to fetch every page
    * and merging the entity array, so large accounts are not silently truncated.
-   * Bounded by maxPages; if the cap is hit, LimitedBy is kept as a "more remains"
-   * signal.
+   * Pages at DEFAULT_PAGE_LIMIT (10k) regardless of the per-tool `limit` clamp
+   * (which governs single-page calls only), so capacity is a DETERMINISTIC
+   * DEFAULT_PAGE_LIMIT × maxPages ≈ 1M objects — not path-dependent. maxPages is a
+   * safety stop for runaway loops, not a cost lever (context size is bounded
+   * downstream by the backend's per-result cap). If the cap IS hit, the merged
+   * result is flagged with `_truncated`/`_truncatedNote` and keeps LimitedBy, so a
+   * truncated full-export is explicit and never silent data loss.
    */
   async getAll<T = unknown>(
     service: string,
     params: Record<string, unknown>,
     maxPages = 100,
   ): Promise<T> {
     const basePage = (params.Page as Record<string, unknown> | undefined) ?? {};
-    const limit = Number(basePage.Limit ?? DEFAULT_PAGE_LIMIT);
+    // autoPaginate ("fetch all") ALWAYS pages at the API max, independent of the
+    // per-tool `limit` clamp (which governs single-page calls only). This keeps
+    // capacity deterministic — DEFAULT_PAGE_LIMIT × maxPages ≈ 1M — instead of
+    // path-dependent (a caller passing limit:1000 alongside autoPaginate must not
+    // silently shrink the export ceiling to 100k).
+    const limit = DEFAULT_PAGE_LIMIT;
     let offset = Number(basePage.Offset ?? 0);
     let merged: Record<string, unknown> | undefined;
     let entityKey: string | undefined;
@@ -161,6 +171,17 @@ export class YandexDirectClient {
       }
       offset = limitedBy;
     }
+    // Reached the page cap with LimitedBy still set → more objects remain. Make this
+    // LOUD: a bare LimitedBy number is easy for an LLM consumer to miss, and a silently
+    // truncated full-export is legitimate-data loss (the backend's char-cap only flags
+    // size, not pagination cutoff).
+    if (merged && typeof (merged as Record<string, unknown>).LimitedBy === "number") {
+      const m = merged as Record<string, unknown>;
+      m._truncated = true;
+      m._truncatedNote =
+        `Stopped at the ${maxPages}-page cap; more objects remain (LimitedBy=${m.LimitedBy}). ` +
+        "Narrow the filter or paginate manually with offset to get the rest.";
+    }
     return merged as T;
   }
 

src/tools/adGroups.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { YandexDirectClient } from "../client.js";
-import { buildPage, compact, fail, ok, okOrPartial } from "./util.js";
+import { buildPage, compact, fail, MAX_TOOL_LIMIT, ok, okOrPartial } from "./util.js";
 
 const DEFAULT_FIELDS = ["Id", "Name", "CampaignId", "RegionIds", "Status", "Type"];
 
@@ -16,7 +16,7 @@ export function registerAdGroupTools(server: McpServer, client: YandexDirectClie
         campaignIds: z.array(z.number().int()).optional().describe("Filter by campaign ids."),
         ids: z.array(z.number().int()).optional().describe("Filter by ad group ids."),
         fieldNames: z.array(z.string()).optional().describe("Ad group fields to return."),
-        limit: z.number().int().min(1).max(10000).optional().describe("Max objects per page."),
+        limit: z.number().int().min(1).max(MAX_TOOL_LIMIT).optional().describe("Max objects per page."),
         offset: z.number().int().min(0).optional().describe("Pagination offset (objects to skip)."),
         autoPaginate: z
           .boolean()

src/tools/ads.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { YandexDirectClient } from "../client.js";
-import { buildPage, compact, fail, ok, okOrPartial } from "./util.js";
+import { buildPage, compact, fail, MAX_TOOL_LIMIT, ok, okOrPartial } from "./util.js";
 
 const AD_STATES = ["ON", "OFF", "SUSPENDED", "OFF_BY_MONITORING", "ARCHIVED"] as const;
 const AD_STATUSES = ["ACCEPTED", "DRAFT", "MODERATION", "PREACCEPTED", "REJECTED"] as const;
@@ -21,7 +21,7 @@ export function registerAdTools(server: McpServer, client: YandexDirectClient):
         states: z.array(z.enum(AD_STATES)).optional().describe("Filter by ad states."),
         statuses: z.array(z.enum(AD_STATUSES)).optional().describe("Filter by moderation statuses."),
         fieldNames: z.array(z.string()).optional().describe("Ad fields to return."),
-        limit: z.number().int().min(1).max(10000).optional().describe("Max objects per page."),
+        limit: z.number().int().min(1).max(MAX_TOOL_LIMIT).optional().describe("Max objects per page."),
         offset: z.number().int().min(0).optional().describe("Pagination offset (objects to skip)."),
         autoPaginate: z
           .boolean()

src/tools/campaigns.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { YandexDirectClient } from "../client.js";
-import { buildPage, compact, fail, isoDate, normalizeMoney, ok, okOrPartial, toMicros } from "./util.js";
+import { buildPage, compact, fail, isoDate, MAX_TOOL_LIMIT, normalizeMoney, ok, okOrPartial, toMicros } from "./util.js";
 
 const CAMPAIGN_TYPES = [
   "TEXT_CAMPAIGN",
@@ -53,7 +53,7 @@ export function registerCampaignTools(server: McpServer, client: YandexDirectCli
           .optional()
           .describe("Filter by moderation statuses."),
         fieldNames: z.array(z.string()).optional().describe("Campaign fields to return."),
-        limit: z.number().int().min(1).max(10000).optional().describe("Max objects per page."),
+        limit: z.number().int().min(1).max(MAX_TOOL_LIMIT).optional().describe("Max objects per page."),
         offset: z.number().int().min(0).optional().describe("Pagination offset (objects to skip)."),
         autoPaginate: z
           .boolean()

src/tools/handlers.test.ts

@@ -72,6 +72,35 @@ test("get_statistics errors on CUSTOM_DATE without both dates and makes no reque
   assert.equal(reports.length, 0);
 });
 
+test("ALL_TIME without a campaign filter is rejected for SEARCH_QUERY (no request)", async () => {
+  const { reports, tools } = harness(registerStatisticsTools, { reportResult: "TSV" });
+  const res = await tools.get_statistics({
+    reportType: "SEARCH_QUERY_PERFORMANCE_REPORT",
+    dateRangeType: "ALL_TIME",
+  });
+  assert.equal(res.isError, true);
+  assert.equal(reports.length, 0);
+});
+
+test("ALL_TIME is allowed for SEARCH_QUERY when a campaign filter is present", async () => {
+  const { reports, tools } = harness(registerStatisticsTools, { reportResult: "TSV" });
+  const res = await tools.get_statistics({
+    reportType: "SEARCH_QUERY_PERFORMANCE_REPORT",
+    dateRangeType: "ALL_TIME",
+    campaignIds: [1],
+  });
+  assert.ok(!res.isError);
+  assert.equal(reports.length, 1);
+});
+
+test("explicit campaign filter with 0 rows fails loud (L3)", async () => {
+  const { reports, tools } = harness(registerStatisticsTools, { reportResult: "" });
+  const res = await tools.get_statistics({ campaignIds: [123], dateRangeType: "LAST_7_DAYS" });
+  assert.equal(res.isError, true);
+  assert.equal(reports.length, 1); // запрос сделан; ошибка — по факту 0 строк
+  assert.match(res.content[0].text, /0 rows/);
+});
+
 test("create_text_campaign applies the default strategy and converts the budget", async () => {
   const { calls, tools } = harness(registerCampaignTools, { callResult: { AddResults: [{ Id: 1 }] } });
   await tools.create_text_campaign({ name: "C", startDate: "2026-01-01", dailyBudgetAmount: 500 });

src/tools/keywords.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { YandexDirectClient } from "../client.js";
-import { buildPage, compact, fail, normalizeMoney, ok, okOrPartial, toMicros } from "./util.js";
+import { buildPage, compact, fail, MAX_TOOL_LIMIT, normalizeMoney, ok, okOrPartial, toMicros } from "./util.js";
 
 const DEFAULT_FIELDS = ["Id", "Keyword", "AdGroupId", "CampaignId", "Bid", "ContextBid", "State", "Status"];
 
@@ -17,7 +17,7 @@ export function registerKeywordTools(server: McpServer, client: YandexDirectClie
         adGroupIds: z.array(z.number().int()).optional().describe("Filter by ad group ids."),
         ids: z.array(z.number().int()).optional().describe("Filter by keyword ids."),
         fieldNames: z.array(z.string()).optional().describe("Keyword fields to return."),
-        limit: z.number().int().min(1).max(10000).optional().describe("Max objects per page."),
+        limit: z.number().int().min(1).max(MAX_TOOL_LIMIT).optional().describe("Max objects per page."),
         offset: z.number().int().min(0).optional().describe("Pagination offset (objects to skip)."),
         autoPaginate: z
           .boolean()

src/tools/statistics.test.ts

@@ -14,3 +14,24 @@ test("ACCOUNT_PERFORMANCE_REPORT defaults exclude fields the API rejects for it"
     assert.ok(!fields.includes(forbidden), `${forbidden} must not be a default`);
   }
 });
+
+test("defaults exclude Date so reports aggregate over the period (LD)", () => {
+  for (const type of REPORT_TYPES) {
+    assert.ok(
+      !DEFAULT_FIELDS_BY_TYPE[type].includes("Date"),
+      `${type} default must not include Date (would split the report by day)`,
+    );
+  }
+});
+
+test("SEARCH_QUERY default is the period aggregate: CampaignName + Query + metrics", () => {
+  assert.deepEqual(DEFAULT_FIELDS_BY_TYPE.SEARCH_QUERY_PERFORMANCE_REPORT, [
+    "CampaignName",
+    "Query",
+    "Impressions",
+    "Clicks",
+    "Cost",
+    "Ctr",
+    "AvgCpc",
+  ]);
+});

src/tools/statistics.ts

@@ -32,21 +32,26 @@ const METRICS = ["Impressions", "Clicks", "Cost", "Ctr", "AvgCpc"];
  * dimension fields — e.g. ACCOUNT_PERFORMANCE_REPORT rejects CampaignName — so
  * a single shared default cannot work. All sets below are verified against the
  * live Reports service.
+ *
+ * `Date` is intentionally OMITTED from the defaults: in the Reports service Date
+ * is a grouping dimension, so including it splits the report by day (one row per
+ * object × day → up to ×30 rows on LAST_30_DAYS). The default is a period-
+ * aggregate (one row per object); a caller asking about daily dynamics/trends
+ * adds "Date" to fieldNames explicitly.
  */
 export const DEFAULT_FIELDS_BY_TYPE: Record<ReportType, string[]> = {
-  ACCOUNT_PERFORMANCE_REPORT: ["Date", ...METRICS],
-  CAMPAIGN_PERFORMANCE_REPORT: ["Date", "CampaignId", "CampaignName", ...METRICS],
-  ADGROUP_PERFORMANCE_REPORT: ["Date", "CampaignName", "AdGroupId", "AdGroupName", ...METRICS],
-  AD_PERFORMANCE_REPORT: ["Date", "CampaignName", "AdGroupName", "AdId", ...METRICS],
+  ACCOUNT_PERFORMANCE_REPORT: [...METRICS],
+  CAMPAIGN_PERFORMANCE_REPORT: ["CampaignId", "CampaignName", ...METRICS],
+  ADGROUP_PERFORMANCE_REPORT: ["CampaignName", "AdGroupId", "AdGroupName", ...METRICS],
+  AD_PERFORMANCE_REPORT: ["CampaignName", "AdGroupName", "AdId", ...METRICS],
   CRITERIA_PERFORMANCE_REPORT: [
-    "Date",
     "CampaignName",
     "AdGroupName",
     "CriterionId",
     "Criterion",
     ...METRICS,
   ],
-  SEARCH_QUERY_PERFORMANCE_REPORT: ["Date", "CampaignName", "Query", ...METRICS],
+  SEARCH_QUERY_PERFORMANCE_REPORT: ["CampaignName", "Query", ...METRICS],
 };
 
 export function registerStatisticsTools(server: McpServer, client: YandexDirectClient): void {
@@ -55,7 +60,7 @@ export function registerStatisticsTools(server: McpServer, client: YandexDirectC
     {
       title: "Get statistics",
       description:
-        "Requests a TSV performance report via the Yandex Direct Reports service. Returns the report as tab-separated text with a column header row.",
+        "Requests a TSV performance report via the Yandex Direct Reports service. Returns tab-separated rows (no header row). By default the report is AGGREGATED over the whole period (one row per object) — add \"Date\" to fieldNames only for day-by-day dynamics or trend questions. ALL_TIME without a campaign filter is rejected for SEARCH_QUERY/CRITERIA reports; pass campaignIds or a bounded date range.",
       inputSchema: {
         reportType: z.enum(REPORT_TYPES).optional().describe("Report type. Default CAMPAIGN_PERFORMANCE_REPORT."),
         dateRangeType: z
@@ -74,6 +79,16 @@ export function registerStatisticsTools(server: McpServer, client: YandexDirectC
         const type = reportType ?? "CAMPAIGN_PERFORMANCE_REPORT";
         const range = dateRangeType ?? (dateFrom && dateTo ? "CUSTOM_DATE" : "LAST_30_DAYS");
 
+        // L3: ALL_TIME без фильтра по кампании для построчных «тяжёлых» отчётов тянет
+        // весь аккаунт за всё время → взрыв размера. Падаем громко, до запроса.
+        const heavy =
+          type === "SEARCH_QUERY_PERFORMANCE_REPORT" || type === "CRITERIA_PERFORMANCE_REPORT";
+        if (range === "ALL_TIME" && heavy && !campaignIds?.length) {
+          return fail(
+            `ALL_TIME without a campaign filter is not allowed for ${type} (it returns the whole account and explodes in size). Pass campaignIds, or a bounded date range like LAST_30_DAYS or CUSTOM_DATE.`,
+          );
+        }
+
         const selection: Record<string, unknown> = {};
         if (range === "CUSTOM_DATE") {
           if (!dateFrom || !dateTo) {
@@ -100,6 +115,14 @@ export function registerStatisticsTools(server: McpServer, client: YandexDirectC
         };
 
         const tsv = await client.report(params);
+        // L3 fail-loud: явный фильтр по кампании, но 0 строк — почти всегда неверный
+        // campaignId или период. Пустой ответ провоцирует модель «снять фильтр и
+        // расширить охват»; явная ошибка заставляет починить фильтр.
+        if (campaignIds?.length && tsv.trim() === "") {
+          return fail(
+            `Report returned 0 rows for campaignIds [${campaignIds.join(", ")}] over ${range}. Check the campaignId(s) and the date range — do not broaden the filter blindly.`,
+          );
+        }
         return ok(tsv);
       } catch (e) {
         return fail(e);