feat(statistics): L2 — server-side aggregation for SEARCH_QUERY (1.0.3)

Computed summary instead of raw rows: totals over 100% of rows (exact period
total), top-N detail by metric (adaptive 95% cost cutoff), tail rollup,
zero-click/zero-conversion counts, conversions>clicks anomaly — all field-aware.
New params: sortBy/order/topN(cap 100)/minCost/queryContains/zeroClicksOnly/
zeroConversionsOnly. Pure aggregate module + 9 tests (89 pass).

Author: gistrec

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-yandex-direct",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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/tools/handlers.test.ts

@@ -101,6 +101,27 @@ test("explicit campaign filter with 0 rows fails loud (L3)", async () => {
   assert.match(res.content[0].text, /0 rows/);
 });
 
+test("SEARCH_QUERY returns a computed aggregate (L2), not raw rows", async () => {
+  // Rows match DEFAULT SEARCH_QUERY fields: CampaignName, Query, Impr, Clicks, Cost, Ctr, AvgCpc.
+  const tsv = ["EPK\tаудио в текст\t100\t20\t160.00\t20.0\t8.00", "EPK\tмусор\t40\t0\t0\t0\t0"].join(
+    "\n",
+  );
+  const { tools } = harness(registerStatisticsTools, { reportResult: tsv });
+  const res = await tools.get_statistics({ reportType: "SEARCH_QUERY_PERFORMANCE_REPORT" });
+  const out = JSON.parse(res.content[0].text);
+  assert.equal(out.aggregated, true);
+  assert.equal(out.rowsTotal, 2);
+  assert.equal(out.totals.Cost, 160);
+  assert.equal(out.counts.zeroClick, 1);
+  assert.equal(out.hasConversions, false); // Conversions not in default fields
+});
+
+test("non-heavy report (ACCOUNT) still returns raw TSV", async () => {
+  const { tools } = harness(registerStatisticsTools, { reportResult: "raw\ttsv" });
+  const res = await tools.get_statistics({ reportType: "ACCOUNT_PERFORMANCE_REPORT" });
+  assert.equal(res.content[0].text, "raw\ttsv");
+});
+
 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/statistics.aggregate.ts

@@ -0,0 +1,231 @@
+/**
+ * L2 — server-side aggregation for heavy statistics reports (SEARCH_QUERY, …).
+ *
+ * Pure functions, no network. Instead of returning thousands of raw TSV rows (which
+ * the consumer then truncates to a sample), we compute the answer over 100% of rows
+ * and return a compact, bounded summary:
+ *   - totals over ALL rows (the true period total — correctness for "сколько всего");
+ *   - a top-N detail list by a chosen metric (ranking — adaptive 95% cutoff for Cost);
+ *   - a tail rollup of everything not shown;
+ *   - zero-click / zero-conversion counts and a conversions>clicks anomaly slice.
+ *
+ * Field-aware: conversion-dependent numbers appear only when "Conversions" was among
+ * the requested fieldNames. No server-side n-gram/bigram extraction (naive whitespace
+ * tokenization breaks on Russian morphology — the model groups queries better).
+ */
+
+const METRIC_FIELDS = new Set([
+  "Impressions",
+  "Clicks",
+  "Cost",
+  "Ctr",
+  "AvgCpc",
+  "Conversions",
+  "ConversionRate",
+  "CostPerConversion",
+  "BounceRate",
+  "AvgPageviews",
+]);
+
+/** Metrics that are summable across rows (ratios like Ctr/AvgCpc are NOT summed). */
+const SUMMABLE = ["Impressions", "Clicks", "Cost", "Conversions"];
+/** Metrics shown in each detail row when present in the report. */
+const DISPLAY_METRICS = [
+  "Impressions",
+  "Clicks",
+  "Cost",
+  "Ctr",
+  "AvgCpc",
+  "Conversions",
+  "ConversionRate",
+  "CostPerConversion",
+  "BounceRate",
+];
+
+export const MAX_TOP_N = 100;
+const DEFAULT_TOP_N = 50;
+const COST_COVERAGE = 0.95; // adaptive cutoff: enough rows to cover 95% of detail Cost
+
+export interface AggregateOptions {
+  sortBy?: string;
+  order?: "asc" | "desc";
+  topN?: number;
+  minCost?: number;
+  queryContains?: string;
+  zeroClicksOnly?: boolean;
+  zeroConversionsOnly?: boolean;
+}
+
+export interface ReportAggregate {
+  reportType: string;
+  aggregated: true;
+  rowsTotal: number;
+  rowsReturned: number;
+  sortBy: string;
+  order: "asc" | "desc";
+  hasConversions: boolean;
+  totals: Record<string, number>;
+  counts: Record<string, number>;
+  filtered?: Record<string, number>;
+  top: Array<Record<string, number | string>>;
+  tail: Record<string, number>;
+  anomalies?: Array<Record<string, number | string>>;
+  note: string;
+}
+
+/** Parse a Yandex Reports cell into a number ("--" / "" → 0; tolerant of comma decimals). */
+function num(v: string | undefined): number {
+  if (v == null) return 0;
+  const s = String(v).trim();
+  if (s === "" || s === "--") return 0;
+  const n = parseFloat(s.replace(",", "."));
+  return Number.isFinite(n) ? n : 0;
+}
+
+interface ParsedRow {
+  dims: Record<string, string>;
+  m: Record<string, number>;
+}
+
+/** Splits a (headerless) TSV body into rows keyed positionally by fieldNames. */
+export function parseRows(tsv: string, fieldNames: string[]): ParsedRow[] {
+  const rows: ParsedRow[] = [];
+  for (const line of tsv.split("\n")) {
+    if (!line.trim()) continue;
+    const cells = line.split("\t");
+    const dims: Record<string, string> = {};
+    const m: Record<string, number> = {};
+    fieldNames.forEach((f, i) => {
+      const cell = cells[i] ?? "";
+      if (METRIC_FIELDS.has(f)) m[f] = num(cell);
+      else dims[f] = cell;
+    });
+    rows.push({ dims, m });
+  }
+  return rows;
+}
+
+function primaryDimension(fieldNames: string[]): string {
+  for (const f of ["Query", "Criterion", "AdGroupName", "CampaignName"]) {
+    if (fieldNames.includes(f)) return f;
+  }
+  return fieldNames.find((f) => !METRIC_FIELDS.has(f)) ?? "";
+}
+
+function sumMetrics(rows: ParsedRow[], keys: string[]): Record<string, number> {
+  const t: Record<string, number> = {};
+  for (const k of keys) t[k] = 0;
+  for (const r of rows) for (const k of keys) t[k] += r.m[k] ?? 0;
+  // Round Cost to 2 decimals to avoid float dust.
+  if ("Cost" in t) t.Cost = Math.round(t.Cost * 100) / 100;
+  return t;
+}
+
+export function aggregateReport(
+  tsv: string,
+  fieldNames: string[],
+  reportType: string,
+  opts: AggregateOptions = {},
+): ReportAggregate {
+  const rows = parseRows(tsv, fieldNames);
+  const hasConversions = fieldNames.includes("Conversions");
+  const dimKey = primaryDimension(fieldNames);
+  const sumKeys = SUMMABLE.filter((k) => fieldNames.includes(k));
+
+  // Totals over 100% of rows — the true period total (this is the correctness point).
+  const totals = sumMetrics(rows, sumKeys);
+  const counts: Record<string, number> = {
+    zeroClick: rows.filter((r) => (r.m.Clicks ?? 0) === 0).length,
+  };
+  if (hasConversions) {
+    counts.zeroConversion = rows.filter(
+      (r) => (r.m.Clicks ?? 0) > 0 && (r.m.Conversions ?? 0) === 0,
+    ).length;
+  }
+
+  // Filtered set drives the detail list (totals above stay over 100%).
+  let detail = rows;
+  if (opts.minCost != null) detail = detail.filter((r) => (r.m.Cost ?? 0) >= opts.minCost!);
+  if (opts.queryContains) {
+    const q = opts.queryContains.toLowerCase();
+    detail = detail.filter((r) => (r.dims[dimKey] ?? "").toLowerCase().includes(q));
+  }
+  if (opts.zeroClicksOnly) detail = detail.filter((r) => (r.m.Clicks ?? 0) === 0);
+  if (opts.zeroConversionsOnly && hasConversions) {
+    detail = detail.filter((r) => (r.m.Clicks ?? 0) > 0 && (r.m.Conversions ?? 0) === 0);
+  }
+
+  const sortBy = METRIC_FIELDS.has(opts.sortBy ?? "") ? (opts.sortBy as string) : "Cost";
+  const order = opts.order === "asc" ? "asc" : "desc";
+  const sorted = [...detail].sort((a, b) => {
+    const d = (a.m[sortBy] ?? 0) - (b.m[sortBy] ?? 0);
+    return order === "asc" ? d : -d;
+  });
+
+  const cap = Math.min(Math.max(opts.topN ?? DEFAULT_TOP_N, 1), MAX_TOP_N);
+  let take = Math.min(cap, sorted.length);
+  // Adaptive: for Cost desc, stop once cumulative cost covers 95% of the detail set —
+  // no point listing thousands of ~0-cost rows.
+  if (sortBy === "Cost" && order === "desc") {
+    const detailCost = sorted.reduce((s, r) => s + (r.m.Cost ?? 0), 0);
+    if (detailCost > 0) {
+      let cum = 0;
+      let n = 0;
+      for (const r of sorted) {
+        cum += r.m.Cost ?? 0;
+        n++;
+        if (cum >= COST_COVERAGE * detailCost) break;
+      }
+      take = Math.min(cap, n);
+    }
+  }
+
+  const topRows = sorted.slice(0, take);
+  const top = topRows.map((r) => {
+    const o: Record<string, number | string> = { ...r.dims };
+    for (const k of DISPLAY_METRICS) if (k in r.m) o[k] = r.m[k];
+    return o;
+  });
+
+  // tail rolls up the detail rows not shown, so top + tail reconstruct the detail set.
+  const tailRows = sorted.slice(take);
+  const tail = { rows: tailRows.length, ...sumMetrics(tailRows, sumKeys) };
+
+  const anomalies = hasConversions
+    ? rows
+        .filter((r) => (r.m.Conversions ?? 0) > (r.m.Clicks ?? 0))
+        .slice(0, 10)
+        .map((r) => ({
+          [dimKey]: r.dims[dimKey] ?? "",
+          clicks: r.m.Clicks ?? 0,
+          conversions: r.m.Conversions ?? 0,
+          reason: "conversions>clicks",
+        }))
+    : [];
+
+  const filtered =
+    detail.length !== rows.length
+      ? { rows: detail.length, ...sumMetrics(detail, sumKeys) }
+      : undefined;
+
+  return {
+    reportType,
+    aggregated: true,
+    rowsTotal: rows.length,
+    rowsReturned: top.length,
+    sortBy,
+    order,
+    hasConversions,
+    totals, // over 100% of rows — the full-period total
+    counts,
+    ...(filtered ? { filtered } : {}),
+    top,
+    tail,
+    ...(anomalies.length ? { anomalies } : {}),
+    note:
+      `totals are over all ${rows.length} row(s) (the full period, not a sample); ` +
+      `top lists ${top.length} row(s) by ${sortBy} ${order}` +
+      (filtered ? ` from ${detail.length} filtered row(s)` : "") +
+      "; tail rolls up the rest.",
+  };
+}

src/tools/statistics.test.ts

@@ -1,6 +1,17 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { DEFAULT_FIELDS_BY_TYPE, REPORT_TYPES } from "./statistics.js";
+import { aggregateReport } from "./statistics.aggregate.js";
+
+const SQ_FIELDS = ["Query", "Impressions", "Clicks", "Cost", "Conversions"];
+// аудио: conv(26) > clicks(20) → anomaly; mp3: clicks>0 & 0 conv → zeroConversion;
+// мусор: 0 clicks → zeroClick.
+const SQ_TSV = [
+  "аудио в текст\t100\t20\t160.00\t26",
+  "whisper\t50\t10\t90.00\t8",
+  "mp3 в текст\t30\t3\t27.00\t0",
+  "мусор\t40\t0\t0\t0",
+].join("\n");
 
 test("every report type has a default field set", () => {
   for (const type of REPORT_TYPES) {
@@ -35,3 +46,59 @@ test("SEARCH_QUERY default is the period aggregate: CampaignName + Query + metri
     "AvgCpc",
   ]);
 });
+
+// ---- L2 aggregation ----
+
+test("aggregate: totals are over 100% of rows (true period total)", () => {
+  const a = aggregateReport(SQ_TSV, SQ_FIELDS, "SEARCH_QUERY_PERFORMANCE_REPORT");
+  assert.equal(a.rowsTotal, 4);
+  assert.equal(a.totals.Impressions, 220);
+  assert.equal(a.totals.Clicks, 33);
+  assert.equal(a.totals.Cost, 277);
+  assert.equal(a.totals.Conversions, 34);
+  assert.equal(a.counts.zeroClick, 1); // мусор
+  assert.equal(a.counts.zeroConversion, 1); // mp3 в текст
+});
+
+test("aggregate: top sorted by Cost desc with 95% adaptive cutoff; tail = rest", () => {
+  const a = aggregateReport(SQ_TSV, SQ_FIELDS, "SEARCH_QUERY_PERFORMANCE_REPORT");
+  // cumulative cost reaches 95% at row 3 (160+90+27 = 277 of 277) → 3 shown, 1 in tail.
+  assert.equal(a.top.length, 3);
+  assert.equal(a.top[0].Query, "аудио в текст");
+  assert.equal(a.tail.rows, 1);
+  // top + tail reconstruct the full set.
+  const topCost = a.top.reduce((s, r) => s + Number(r.Cost), 0);
+  assert.equal(Math.round((topCost + a.tail.Cost) * 100) / 100, a.totals.Cost);
+});
+
+test("aggregate: conversions>clicks anomaly is flagged", () => {
+  const a = aggregateReport(SQ_TSV, SQ_FIELDS, "SEARCH_QUERY_PERFORMANCE_REPORT");
+  assert.equal(a.anomalies?.length, 1);
+  assert.equal(a.anomalies?.[0].Query, "аудио в текст");
+});
+
+test("aggregate: field-aware — no Conversions in fieldNames omits conversion data", () => {
+  const fields = ["Query", "Impressions", "Clicks", "Cost"];
+  const tsv = SQ_TSV.split("\n").map((l) => l.split("\t").slice(0, 4).join("\t")).join("\n");
+  const a = aggregateReport(tsv, fields, "SEARCH_QUERY_PERFORMANCE_REPORT");
+  assert.equal(a.hasConversions, false);
+  assert.equal(a.counts.zeroConversion, undefined);
+  assert.equal(a.anomalies, undefined);
+  assert.equal("Conversions" in a.totals, false);
+  assert.equal("Conversions" in a.top[0], false);
+});
+
+test("aggregate: filters drive the detail list; totals stay over 100%", () => {
+  const a = aggregateReport(SQ_TSV, SQ_FIELDS, "SEARCH_QUERY_PERFORMANCE_REPORT", { minCost: 50 });
+  assert.equal(a.totals.Cost, 277); // unchanged — totals are over all rows
+  assert.equal(a.filtered?.rows, 2); // only аудио + whisper survive minCost:50
+  assert.ok(a.top.every((r) => Number(r.Cost) >= 50));
+});
+
+test("aggregate: zeroClicksOnly filter", () => {
+  const a = aggregateReport(SQ_TSV, SQ_FIELDS, "SEARCH_QUERY_PERFORMANCE_REPORT", {
+    zeroClicksOnly: true,
+  });
+  assert.equal(a.filtered?.rows, 1);
+  assert.equal(a.top[0].Query, "мусор");
+});