@digestseo/mcp-gsc 0.4.0 → 0.4.1

package/src/quick-wins-schema.ts

@@ -1,5 +1,9 @@
 import { z } from 'zod';
 import { SEARCH_CONSOLE_DATE_SCHEMA } from './date-validation';
+import {
+  DEFAULT_ANALYSIS_RESULT_LIMIT,
+  MAX_ANALYSIS_RESULT_LIMIT,
+} from './result-bounds';
 
 const POSITION_RANGE_ERROR = {
   message: 'min_position must be less than or equal to max_position.',
@@ -19,6 +23,19 @@ export function createQuickWinsInputSchema(siteUrlDescription: string) {
       start_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('Start date (inclusive) in YYYY-MM-DD format.'),
       end_date: SEARCH_CONSOLE_DATE_SCHEMA.describe('End date (inclusive) in YYYY-MM-DD format. Note the 2-3 day GSC data lag.'),
       ...QUICK_WINS_THRESHOLDS_SHAPE,
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_ANALYSIS_RESULT_LIMIT)
+        .default(DEFAULT_ANALYSIS_RESULT_LIMIT)
+        .describe('Maximum ranked quick-win results to return in this response.'),
+      start_row: z
+        .number()
+        .int()
+        .min(0)
+        .default(0)
+        .describe('Zero-based offset into the ranked quick-win result list.'),
     })
     .refine(
       ({ min_position, max_position }) => min_position <= max_position,

package/src/result-bounds.ts

@@ -0,0 +1,91 @@
+export const STRUCTURED_RESULT_BYTE_BUDGET = 48_000;
+export const DEFAULT_ANALYSIS_RESULT_LIMIT = 50;
+export const MAX_ANALYSIS_RESULT_LIMIT = 100;
+export const MAX_DIRECT_SOURCE_ROWS = 500;
+
+export interface BoundedItems<T> {
+  items: T[];
+  byteLimitReached: boolean;
+}
+
+function jsonByteLength(value: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+
+/**
+ * Keep one structured-content list inside a conservative byte budget.
+ *
+ * Count limits alone are not sufficient because Search Console keys are
+ * caller-controlled strings (queries and URLs). This helper therefore applies
+ * both the requested item ceiling and an encoded-JSON byte ceiling.
+ */
+export function takeBoundedItems<T>(
+  items: readonly T[],
+  maxItems: number,
+  byteBudget = STRUCTURED_RESULT_BYTE_BUDGET,
+): BoundedItems<T> {
+  if (!Number.isInteger(maxItems) || maxItems < 1) {
+    throw new Error('maxItems must be a positive integer.');
+  }
+  if (!Number.isInteger(byteBudget) || byteBudget < 1) {
+    throw new Error('byteBudget must be a positive integer.');
+  }
+
+  const bounded: T[] = [];
+  // Account for the surrounding JSON array. Per-item commas are added below.
+  let usedBytes = 2;
+  let byteLimitReached = false;
+
+  for (const item of items.slice(0, maxItems)) {
+    const itemBytes = jsonByteLength(item) + (bounded.length > 0 ? 1 : 0);
+    if (usedBytes + itemBytes > byteBudget) {
+      byteLimitReached = true;
+      break;
+    }
+    bounded.push(item);
+    usedBytes += itemBytes;
+  }
+
+  return { items: bounded, byteLimitReached };
+}
+
+export interface ResultPageMetadata {
+  start_row: number;
+  limit: number;
+  returned_count: number;
+  total_count?: number;
+  has_more: boolean;
+  truncated: boolean;
+  byte_limit_reached: boolean;
+  next_start_row?: number;
+}
+
+export function resultPageMetadata(input: {
+  startRow: number;
+  limit: number;
+  returnedCount: number;
+  totalCount?: number;
+  hasMore: boolean;
+  byteLimitReached: boolean;
+}): ResultPageMetadata {
+  const {
+    startRow,
+    limit,
+    returnedCount,
+    totalCount,
+    hasMore,
+    byteLimitReached,
+  } = input;
+  return {
+    start_row: startRow,
+    limit,
+    returned_count: returnedCount,
+    ...(totalCount !== undefined ? { total_count: totalCount } : {}),
+    has_more: hasMore,
+    truncated: hasMore || byteLimitReached,
+    byte_limit_reached: byteLimitReached,
+    ...(hasMore && returnedCount > 0
+      ? { next_start_row: startRow + returnedCount }
+      : {}),
+  };
+}