@gscdump/cli 3.5.0 → 3.6.0

package/dist/commands/sync.mjs

@@ -1,10 +1,11 @@
 import { syncCommandMeta } from "../command-meta.mjs";
-import { OUTPUT_ARGS, applyOutputMode, clearLine, displayPath, formatAge, logger, progressBar, runWithConcurrency } from "../utils.mjs";
-import { TABLE_DIMS, allTables, createLocalStore, transformGscRow } from "../local-store.mjs";
+import { OUTPUT_ARGS, applyOutputMode, clearLine, displayPath, formatAge, logger, parseIntegerOption, progressBar, runWithConcurrency } from "../utils.mjs";
+import { TABLE_DIMS, allTables, assembleDatesRow, createLocalStore } from "../local-store.mjs";
 import { createCommandContext } from "../context.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import { SearchTypes } from "gscdump/query";
+import { createRowAccumulator } from "@gscdump/engine/ingest";
 import { createEmptyTypesStore } from "@gscdump/engine/entities";
 import { daysAgoUtc, getDateRange } from "gscdump/dates";
 import { DEFAULT_ROLLUPS, rebuildRollups } from "@gscdump/engine/rollups";
@@ -96,7 +97,7 @@ async function syncTable(store, siteUrl, table, searchType, dates, client, concu
 		failed
 	};
 }
-async function runOneDate(store, client, siteUrl, table, searchType, dims, date) {
+async function fetchDateRows(client, siteUrl, searchType, dims, date) {
 	const rowLimit = 25e3;
 	const rows = [];
 	let startRow = 0;
@@ -109,19 +110,33 @@ async function runOneDate(store, client, siteUrl, table, searchType, dims, date)
 			rowLimit,
 			startRow
 		})).rows || [];
-		for (const apiRow of batch) {
-			const transformed = transformGscRow(table, {
-				keys: apiRow.keys ?? [],
-				clicks: apiRow.clicks ?? 0,
-				impressions: apiRow.impressions ?? 0,
-				ctr: apiRow.ctr ?? 0,
-				position: apiRow.position ?? 0
-			});
-			if (transformed) rows.push(transformed.row);
-		}
+		for (const apiRow of batch) rows.push({
+			keys: apiRow.keys ?? [],
+			clicks: apiRow.clicks ?? 0,
+			impressions: apiRow.impressions ?? 0,
+			ctr: apiRow.ctr ?? 0,
+			position: apiRow.position ?? 0
+		});
 		if (batch.length === 0) break;
 		startRow += batch.length;
 	}
+	return rows;
+}
+async function runOneDate(store, client, siteUrl, table, searchType, dims, date) {
+	const apiRows = await fetchDateRows(client, siteUrl, searchType, dims, date);
+	let rows = [];
+	if (table === "dates") {
+		const totals = apiRows.find((row) => row.keys[0] === date);
+		if (totals) {
+			const deviceRows = await fetchDateRows(client, siteUrl, searchType, ["date", "device"], date);
+			const queryImpressions = (await fetchDateRows(client, siteUrl, searchType, TABLE_DIMS.queries, date)).reduce((sum, row) => sum + row.impressions, 0);
+			rows.push(assembleDatesRow(date, totals, deviceRows, queryImpressions).row);
+		}
+	} else {
+		const accumulator = createRowAccumulator({ maxRows: apiRows.length });
+		accumulator.push(table, apiRows);
+		rows = accumulator.drain().get(table)?.get(date) ?? [];
+	}
 	const writeCtx = {
 		userId: store.userId,
 		siteId: store.siteIdFor(siteUrl),
@@ -212,6 +227,8 @@ const syncCommand = defineCommand({
 	},
 	async run({ args }) {
 		const { json, quiet } = applyOutputMode(args);
+		const days = parseIntegerOption(args.days, "--days");
+		const concurrency = parseIntegerOption(args.concurrency, "--concurrency") ?? DEFAULT_CONCURRENCY;
 		if (args.status) {
 			const ctx = await createCommandContext();
 			await printSyncStatus({
@@ -232,12 +249,23 @@ const syncCommand = defineCommand({
 			logger.error(`No valid search types specified. Allowed: ${ALL_SEARCH_TYPES.join(",")}`);
 			process.exit(1);
 		}
-		const siteId = ctx.store.siteIdFor(siteUrl);
-		const emptyTypesStore = createEmptyTypesStore({ dataSource: ctx.store.dataSource });
-		const emptyTypesDoc = await emptyTypesStore.load({
-			userId: ctx.store.userId,
+		const store = ctx.store;
+		const siteId = store.siteIdFor(siteUrl);
+		const scope = {
+			userId: store.userId,
 			siteId
-		});
+		};
+		const emptyTypesStore = createEmptyTypesStore({ dataSource: store.dataSource });
+		let emptyTypesDoc = await emptyTypesStore.load(scope);
+		if (emptyTypesDoc.emptyTypes.length > 0) {
+			const entries = await store.engine.listLive(scope);
+			const populated = new Set(entries.filter((entry) => entry.rowCount > 0).map((entry) => entry.searchType ?? "web"));
+			const toClear = requestedTypes.filter((type) => emptyTypesDoc.emptyTypes.includes(type) && populated.has(type));
+			if (toClear.length > 0) {
+				if (!args["dry-run"]) emptyTypesDoc = await emptyTypesStore.clear(scope, toClear);
+				else emptyTypesDoc.emptyTypes = emptyTypesDoc.emptyTypes.filter((type) => !toClear.includes(type));
+			}
+		}
 		const forceTypes = Boolean(args["force-types"]);
 		const skippedTypes = [];
 		const types = [];
@@ -257,14 +285,13 @@ const syncCommand = defineCommand({
 		let startDate;
 		if (args.start) startDate = String(args.start);
 		else if (args.full) startDate = daysAgoUtc(450);
-		else if (args.days) startDate = daysAgoUtc(Number.parseInt(String(args.days), 10) + DEFAULT_PENDING_DAYS - 1);
+		else if (days !== void 0) startDate = daysAgoUtc(days + DEFAULT_PENDING_DAYS - 1);
 		else startDate = daysAgoUtc(5);
 		let dates = getDateRange(startDate, endDate);
 		if (dates.length === 0) {
 			logger.error(`No dates to sync (start=${startDate}, end=${endDate})`);
 			process.exit(1);
 		}
-		const store = ctx.store;
 		if (args["retry-failed"]) {
 			const failedSet = /* @__PURE__ */ new Set();
 			const selectedTables = new Set(tables);
@@ -316,7 +343,6 @@ const syncCommand = defineCommand({
 			logger.info(`Syncing ${siteUrl} (${tables.join(", ")}) [${types.join(", ")}] → ${displayPath(store.dataDir)}`);
 			logger.info(`Range: ${startDate} → ${endDate} (${dates.length} days)`);
 		}
-		const concurrency = args.concurrency ? Math.max(1, Number.parseInt(String(args.concurrency), 10) || DEFAULT_CONCURRENCY) : DEFAULT_CONCURRENCY;
 		const serialTables = Boolean(args["serial-tables"]);
 		const start = Date.now();
 		const totals = {};
@@ -330,9 +356,9 @@ const syncCommand = defineCommand({
 			});
 		}
 		const progress = createProgressTracker(dates.length * jobs.length, quiet);
-		if (serialTables) for (const job of jobs) totals[job.label] = await syncTable(store, siteUrl, job.table, job.type, dates, client, concurrency, args.force, progress);
+		if (serialTables) for (const job of jobs) totals[job.label] = await syncTable(store, siteUrl, job.table, job.type, dates, client, concurrency, args.force || forceTypes, progress);
 		else {
-			const results = await Promise.all(jobs.map((job) => syncTable(store, siteUrl, job.table, job.type, dates, client, concurrency, args.force, progress)));
+			const results = await Promise.all(jobs.map((job) => syncTable(store, siteUrl, job.table, job.type, dates, client, concurrency, args.force || forceTypes, progress)));
 			jobs.forEach((job, i) => {
 				totals[job.label] = results[i];
 			});
@@ -351,17 +377,24 @@ const syncCommand = defineCommand({
 		const anyFailed = Object.values(totals).some((t) => t.failed > 0);
 		const rowsByType = /* @__PURE__ */ new Map();
 		const failedByType = /* @__PURE__ */ new Map();
+		const skippedByType = /* @__PURE__ */ new Map();
 		for (const job of jobs) {
 			const t = totals[job.label];
 			rowsByType.set(job.type, (rowsByType.get(job.type) ?? 0) + t.rows);
 			failedByType.set(job.type, (failedByType.get(job.type) ?? 0) + t.failed);
+			skippedByType.set(job.type, (skippedByType.get(job.type) ?? 0) + t.skipped);
 		}
-		if (!forceTypes && dates.length >= EMPTY_TYPE_PROBE_MIN_DAYS) {
+		if (!forceTypes && tables.length > 0 && dates.length >= EMPTY_TYPE_PROBE_MIN_DAYS) {
 			const toMark = [];
 			for (const type of types) {
 				if (EMPTY_TYPE_PROTECTED.includes(type)) continue;
 				if ((failedByType.get(type) ?? 0) > 0) continue;
-				if ((rowsByType.get(type) ?? 0) === 0) toMark.push(type);
+				if ((skippedByType.get(type) ?? 0) > 0 || (rowsByType.get(type) ?? 0) > 0) continue;
+				if ((await store.engine.listLive({
+					...scope,
+					searchType: type
+				})).some((entry) => entry.rowCount > 0)) continue;
+				toMark.push(type);
 			}
 			if (toMark.length > 0) {
 				await emptyTypesStore.mark({

package/dist/config.mjs

@@ -1,13 +1,40 @@
 import { useCliRuntime } from "./runtime.mjs";
-import os from "node:os";
-import path from "node:path";
 import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import os from "node:os";
+import { SearchTypes } from "gscdump/query";
 function setConfigDir(dir) {
 	useCliRuntime().configDir = dir;
 }
 function getConfigDir() {
 	return useCliRuntime().configDir;
 }
+const configSchema = z.strictObject({
+	clientId: z.string().optional(),
+	clientSecret: z.string().optional(),
+	defaultSite: z.string().optional(),
+	defaultPeriod: z.string().optional(),
+	defaultFormat: z.enum(["json", "csv"]).optional(),
+	defaultDb: z.string().optional(),
+	dataDir: z.string().optional(),
+	defaultLimit: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+	defaultSearchType: z.enum(SearchTypes).optional(),
+	defaultDataState: z.enum([
+		"all",
+		"final",
+		"hourly_all"
+	]).optional(),
+	serviceAccountPath: z.string().optional()
+});
+function parseConfig(value) {
+	const parsed = configSchema.safeParse(value);
+	if (!parsed.success) {
+		const issues = parsed.error.issues.map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`);
+		throw new Error(`Invalid config at ${getConfigPath()}. ${issues.join("; ")}`);
+	}
+	return parsed.data;
+}
 function defaultDataDir() {
 	return path.join(os.homedir(), ".gscdump", "data");
 }
@@ -20,7 +47,14 @@ function expandTilde(p) {
 	return p;
 }
 async function loadConfig() {
-	return fs.readFile(path.join(getConfigDir(), "config.json"), "utf-8").then((data) => JSON.parse(data)).catch(() => ({}));
+	const data = await fs.readFile(getConfigPath(), "utf-8").catch((error) => {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	});
+	if (data === void 0) return {};
+	return parseConfig(await Promise.resolve().then(() => JSON.parse(data)).catch((cause) => {
+		throw new Error(`Invalid JSON at ${getConfigPath()}. Fix this file before running the command.`, { cause });
+	}));
 }
 async function loadResolvedConfig() {
 	const config = await loadConfig();
@@ -30,12 +64,13 @@ async function loadResolvedConfig() {
 	};
 }
 async function saveConfig(config) {
+	const parsed = parseConfig(config);
 	const configDir = getConfigDir();
 	await fs.mkdir(configDir, {
 		recursive: true,
 		mode: 448
 	});
-	await fs.writeFile(path.join(configDir, "config.json"), JSON.stringify(config, null, 2), { mode: 384 });
+	await fs.writeFile(path.join(configDir, "config.json"), JSON.stringify(parsed, null, 2), { mode: 384 });
 }
 function getConfigPath() {
 	return path.join(getConfigDir(), "config.json");

package/dist/context.mjs

@@ -1,6 +1,8 @@
+import { resolveAuthentication } from "./auth-state.mjs";
 import { loadResolvedConfig } from "./config.mjs";
 import { logger } from "./utils.mjs";
 import { resolveAuth } from "./auth.mjs";
+import { createCloudGoogleClient } from "./cloud-google.mjs";
 import { createLocalStore } from "./local-store.mjs";
 import process from "node:process";
 import { cancel, isCancel, select } from "@clack/prompts";
@@ -8,19 +10,17 @@ import { googleSearchConsole } from "gscdump/client";
 async function createCommandContext(opts = {}) {
 	const { needsAuth = false, needsStore = false, interactive = false, byok, fetchOptions } = opts;
 	const { config, dataDir } = await loadResolvedConfig();
-	const auth = needsAuth ? await resolveAuth({
+	const authentication = needsAuth ? await resolveAuthentication() : { _tag: "Local" };
+	const auth = needsAuth && authentication._tag === "Local" ? await resolveAuth({
 		interactive,
 		config,
 		byok
 	}) : null;
-	const client = auth ? googleSearchConsole(auth, { fetchOptions }) : null;
+	const client = needsAuth && authentication._tag === "Cloud" ? createCloudGoogleClient(authentication, fetchOptions) : auth ? googleSearchConsole(auth, { fetchOptions }) : null;
 	const store = needsStore ? createLocalStore({ dataDir }) : null;
 	const loadSites = async () => {
 		if (!client) throw new Error("loadSites requires needsAuth: true");
-		return (await client.sites().catch((e) => {
-			logger.error(`Failed to fetch sites: ${e.message}`);
-			process.exit(1);
-		})).filter((s) => s.siteUrl && s.permissionLevel !== "siteUnverifiedUser").map((s) => ({
+		return (await client.sites()).filter((s) => s.siteUrl && s.permissionLevel !== "siteUnverifiedUser").map((s) => ({
 			siteUrl: s.siteUrl,
 			permissionLevel: s.permissionLevel || "unknown"
 		}));
@@ -33,8 +33,12 @@ async function createCommandContext(opts = {}) {
 			process.exit(1);
 		}
 		if (hint) {
-			const match = sites.find((s) => s.siteUrl === hint || s.siteUrl.includes(hint));
-			if (match) return match.siteUrl;
+			const exact = sites.find((site) => site.siteUrl === hint);
+			if (exact) return exact.siteUrl;
+			const matches = sites.filter((site) => site.siteUrl.includes(hint));
+			if (matches.length === 1) return matches[0].siteUrl;
+			if (matches.length > 1) throw new Error(`Multiple Sites match "${hint}". Use an exact Site URL from gscdump sites.`);
+			throw new Error(`No verified Site matches "${hint}". Run gscdump sites to list available Sites.`);
 		}
 		if (sites.length === 1) return sites[0].siteUrl;
 		const selected = await select({
@@ -53,6 +57,7 @@ async function createCommandContext(opts = {}) {
 	return {
 		config,
 		dataDir,
+		authentication,
 		auth,
 		client,
 		store,

package/dist/env-file.mjs

@@ -1,7 +1,7 @@
 import { useCliRuntime } from "./runtime.mjs";
 import process from "node:process";
-import fs from "node:fs";
 import path from "node:path";
+import fs from "node:fs";
 const ENV_LINE_RE = /^([^=]+)=(.*)$/;
 function parseEnvFile(envPath) {
 	let content;

package/dist/local-store.mjs

@@ -1,7 +1,7 @@
 import { createNodeHarness } from "@gscdump/engine/node";
-import { TABLE_DIMS, transformGscRow } from "@gscdump/engine/ingest";
+import { TABLE_DIMS, assembleDatesRow } from "@gscdump/engine/ingest";
 import { allTables, inferTable } from "@gscdump/engine/schema";
 function createLocalStore(opts) {
 	return createNodeHarness(opts);
 }
-export { TABLE_DIMS, allTables, createLocalStore, inferTable, transformGscRow };
+export { TABLE_DIMS, allTables, assembleDatesRow, createLocalStore, inferTable };

package/dist/mcp/errors.mjs

@@ -26,6 +26,14 @@ const mcpHandlerErrors = {
 			message: `Unknown report id "${id}". Available: ${available.join(", ")}`
 		};
 	},
+	unsupportedReport(id, available) {
+		return {
+			kind: "unsupported-report",
+			id,
+			available,
+			message: `Report "${id}" cannot run through the live MCP Source. Use the CLI with the local Store.`
+		};
+	},
 	unknownPeriod(value) {
 		return {
 			kind: "unknown-period",

package/dist/mcp/handlers/diagnostics.mjs

@@ -1,9 +1,40 @@
+import { getCloudAccount } from "../../auth-state.mjs";
 import { missingRequiredScopes } from "../../auth-scopes.mjs";
 import { ofetch } from "ofetch";
 const FETCH_TIMEOUT_MS = 5e3;
 const TIME_SKEW_WARN_MS = 3e5;
 async function diagnostics(_input, ctx) {
 	const checks = [];
+	if (ctx.authentication?._tag === "Cloud") {
+		const [account, sites] = await Promise.all([getCloudAccount(ctx.authentication).catch((error) => error), ctx.client.sites().catch((error) => error)]);
+		checks.push(account instanceof Error ? {
+			name: "auth",
+			status: "fail",
+			detail: account.message
+		} : {
+			name: "auth",
+			status: "pass",
+			detail: `Cloud account: ${account.user.email}`
+		});
+		checks.push(sites instanceof Error ? {
+			name: "gsc.sites",
+			status: "fail",
+			detail: sites.message
+		} : {
+			name: "gsc.sites",
+			status: "pass",
+			detail: `${sites.length} Site(s) accessible through cloud authentication`
+		});
+		checks.push({
+			name: "auth.capabilities",
+			status: "info",
+			detail: "Google indexing and Site Verification require --mode local."
+		});
+		return {
+			ok: checks.every((check) => check.status !== "fail"),
+			checks
+		};
+	}
 	const token = await resolveAccessToken(ctx.auth);
 	if (!token) {
 		checks.push({

package/dist/mcp/handlers/reports.mjs

@@ -1,9 +1,10 @@
 import { enrichToolError, mcpHandlerErrorToException, mcpHandlerErrors } from "../errors.mjs";
+import { runReportInput } from "../types.mjs";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
-import { createGscApiQuerySource } from "@gscdump/engine-gsc-api";
+import { resolveWindow } from "@gscdump/engine/period";
+import { GSC_API_CAPABILITIES, createGscApiQuerySource } from "@gscdump/engine-gsc-api";
 import { err, ok, unwrapResult } from "gscdump/result";
 import { defaultReportRegistry, runReport } from "@gscdump/analysis/report";
-import { resolveWindow } from "@gscdump/engine/period";
 const PERIOD_ALIASES = {
 	"7d": "last-7d",
 	"28d": "last-28d",
@@ -22,18 +23,40 @@ const COMPARISON_ALIASES = {
 	"prior": "prev-period",
 	"yoy": "yoy"
 };
+function mcpArgName(name) {
+	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function supportsLiveSteps(steps) {
+	const capabilities = GSC_API_CAPABILITIES;
+	const supported = steps.map((step) => {
+		const analyzer = defaultAnalyzerRegistry.resolveAnalyzer(step.type, false);
+		return !!analyzer && analyzer.requires.every((capability) => capability !== "executeSql" && capabilities[capability] === true);
+	});
+	return supported.some(Boolean) && steps.every((step, index) => !step.required || supported[index]);
+}
+function supportsLiveReport(report) {
+	const args = Object.entries(report.argsSpec);
+	if (args.some(([name]) => !Object.hasOwn(runReportInput.shape, mcpArgName(name)))) return false;
+	const params = Object.fromEntries(args.map(([name, arg]) => [mcpArgName(name), arg.default ?? (arg.type === "number" ? 1 : arg.type === "boolean" ? false : "mcp-discovery")]));
+	const window = resolveWindow({
+		preset: report.defaultPeriod,
+		comparison: report.defaultComparison
+	});
+	return supportsLiveSteps(report.plan(params, window));
+}
 function listReports() {
-	return defaultReportRegistry.listReports().map((r) => ({
+	return defaultReportRegistry.listReports().filter(supportsLiveReport).map((r) => ({
 		id: r.id,
 		description: r.description,
-		defaultPeriod: r.defaultPeriod,
+		defaultPeriod: r.defaultPeriod.replace(/^last-/, ""),
 		defaultComparison: r.defaultComparison,
-		argsSpec: r.argsSpec
+		argsSpec: Object.fromEntries(Object.entries(r.argsSpec).map(([name, arg]) => [mcpArgName(name), arg]))
 	}));
 }
-async function runReportHandlerResult(input, ctx) {
+async function runReportHandlerResult(input, getContext) {
 	const report = defaultReportRegistry.getReport(input.id);
-	if (!report) return err(mcpHandlerErrors.unknownReport(input.id, defaultReportRegistry.listReportIds()));
+	if (!report) return err(mcpHandlerErrors.unknownReport(input.id, listReports().map((report) => report.id)));
+	if (!supportsLiveReport(report)) return err(mcpHandlerErrors.unsupportedReport(input.id, listReports().map((report) => report.id)));
 	const preset = input.period ? PERIOD_ALIASES[input.period.toLowerCase()] ?? null : report.defaultPeriod;
 	if (!preset) return err(mcpHandlerErrors.unknownPeriod(input.period ?? ""));
 	const comparison = input.comparison ? COMPARISON_ALIASES[input.comparison.toLowerCase()] ?? null : report.defaultComparison;
@@ -48,8 +71,12 @@ async function runReportHandlerResult(input, ctx) {
 		start: input.prevStart,
 		end: input.prevEnd
 	};
-	const params = {};
-	if (input.maxFindings != null) params.maxFindings = input.maxFindings;
+	const params = Object.fromEntries(Object.keys(report.argsSpec).map((name) => {
+		const key = mcpArgName(name);
+		return [key, input[key]];
+	}).filter(([, value]) => value !== void 0));
+	if (!supportsLiveSteps(report.plan(params, window))) return err(mcpHandlerErrors.unsupportedReport(input.id, listReports().map((report) => report.id)));
+	const ctx = await getContext();
 	const source = createGscApiQuerySource({
 		client: ctx.client,
 		siteUrl: input.siteUrl
@@ -66,8 +93,8 @@ async function runReportHandlerResult(input, ctx) {
 		ctx: reportCtx
 	}));
 }
-async function runReportHandler(input, ctx) {
-	return unwrapResult(await runReportHandlerResult(input, ctx).catch((thrown) => {
+async function runReportHandler(input, getContext) {
+	return unwrapResult(await runReportHandlerResult(input, getContext).catch((thrown) => {
 		throw enrichToolError(thrown) ?? thrown;
 	}), mcpHandlerErrorToException);
 }

package/dist/mcp/server/index.mjs

@@ -1,14 +1,15 @@
 import { discoverLiveSitemap } from "../../sitemap.mjs";
 import { diagnostics } from "../handlers/diagnostics.mjs";
 import { batchInspectUrls as batchInspectUrls$1, batchRequestIndexing as batchRequestIndexing$1, getIndexingStatus, requestIndexing as requestIndexing$1 } from "../handlers/indexing.mjs";
-import { getSitemap, listSitesWithSitemaps } from "../handlers/sites.mjs";
 import { batchInspectUrlsInput, batchRequestIndexingInput, getIndexingStatusInput, inspectUrlInput, listReportsInput, listSitemapsInput, listSitesInput, requestIndexingInput, runReportInput, sitemapInput } from "../types.mjs";
+import { listReports, runReportHandler } from "../handlers/reports.mjs";
+import { getSitemap, listSitesWithSitemaps } from "../handlers/sites.mjs";
+import { z } from "zod";
 import { SearchTypes } from "gscdump/query";
 import { googleSearchConsole } from "gscdump/client";
 import { getIndexingMetadata, runSequentialBatch } from "gscdump/indexing";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { addSite, deleteSite, getVerificationToken, getVerifiedSite, listVerifiedSites, unverifySite, verifySite } from "gscdump/sites";
-import { z } from "zod";
 async function runMcpSearchAnalyticsQuery(client, args) {
 	const totalLimit = Math.max(0, args.rowLimit ?? 25e3);
 	const pageSize = Math.min(totalLimit, 25e3);
@@ -54,20 +55,20 @@ async function runMcpSearchAnalyticsQuery(client, args) {
 	};
 }
 function createGscMcpServer(options) {
-	const { name = "gscdump", version = "1.0.0", getAuth } = options;
+	const { name = "gscdump", version = "1.0.0" } = options;
 	const server = new McpServer({
 		name,
 		version
 	});
-	const auth = async () => Promise.resolve(getAuth());
 	const getContext = async () => {
-		const a = await auth();
+		if (options.getContext) return options.getContext();
+		const a = await options.getAuth();
 		return {
 			auth: a,
 			client: googleSearchConsole(a)
 		};
 	};
-	const getClient = async () => googleSearchConsole(await auth());
+	const getClient = async () => (await getContext()).client;
 	server.registerTool("list-sites", {
 		description: "List all Google Search Console sites visible to the authenticated user.",
 		inputSchema: listSitesInput.shape
@@ -132,10 +133,9 @@ function createGscMcpServer(options) {
 		}] };
 	});
 	server.registerTool("list-reports", {
-		description: "List available reports (intent-keyed analyzer compositions). Returns id, description, default period/comparison, and per-report argsSpec.",
+		description: "List Reports supported by the live Google API. Returns defaults and argsSpec using run-report input names.",
 		inputSchema: listReportsInput.shape
 	}, async () => {
-		const { listReports } = await import("../handlers/reports.mjs");
 		const result = listReports();
 		return { content: [{
 			type: "text",
@@ -146,8 +146,7 @@ function createGscMcpServer(options) {
 		description: "Run a report against the GSC API. Returns a structured ReportResult with bounded findings per section. See list-reports for ids.",
 		inputSchema: runReportInput.shape
 	}, async (args) => {
-		const { runReportHandler } = await import("../handlers/reports.mjs");
-		const result = await runReportHandler(args, await getContext());
+		const result = await runReportHandler(args, getContext);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(result, null, 2)

package/dist/mcp/types.mjs

@@ -1,5 +1,5 @@
-import { SearchTypes } from "gscdump/query";
 import { z } from "zod";
+import { SearchTypes } from "gscdump/query";
 const periodSchema = z.object({
 	start: z.string().describe("Start date (YYYY-MM-DD)"),
 	end: z.string().describe("End date (YYYY-MM-DD)")
@@ -68,13 +68,18 @@ const batchInspectUrlsInput = z.object({
 const listReportsInput = z.object({});
 const runReportInput = z.object({
 	siteUrl: siteUrlSchema,
-	id: z.string().describe("Report id (e.g. health, movers, opportunities, risks). See list-reports."),
+	id: z.string().describe("Report ID supported by the live Google API. See list-reports."),
 	period: z.string().optional().describe("Window: 7d|28d|30d|90d|180d|365d|mtd|ytd|custom (default per report)."),
 	comparison: z.string().optional().describe("Comparison: none|prev-period|yoy (default per report)."),
 	start: z.string().optional().describe("Custom window start (YYYY-MM-DD); requires period=custom."),
 	end: z.string().optional().describe("Custom window end (YYYY-MM-DD); requires period=custom."),
 	prevStart: z.string().optional().describe("Override comparison-window start."),
 	prevEnd: z.string().optional().describe("Override comparison-window end."),
-	maxFindings: z.number().optional().describe("Cap findings per section (per-report default ~5).")
+	maxFindings: z.number().optional().describe("Cap findings per section (per-report default ~5)."),
+	minClicksChange: z.number().optional().describe("Minimum absolute click change for movers findings."),
+	target: z.string().optional().describe("Page URL or query for triage. This Report requires the local Store."),
+	targetKind: z.enum(["page", "query"]).optional().describe("Target kind for triage. Defaults to page."),
+	topic: z.string().optional().describe("Required for pre-publish: topic or URL slug to check."),
+	brandTerms: z.string().optional().describe("Required for brand: comma-separated brand terms.")
 });
 export { batchInspectUrlsInput, batchRequestIndexingInput, getIndexingStatusInput, inspectUrlInput, listReportsInput, listSitemapsInput, listSitesInput, periodSchema, queryOptionsSchema, requestIndexingInput, runReportInput, siteUrlSchema, sitemapInput };

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "3.5.0";
+var version = "3.6.0";
 export { version };

package/dist/papercut.mjs

@@ -0,0 +1,99 @@
+import { VERSION } from "./utils.mjs";
+import process from "node:process";
+import { z } from "zod";
+const DEFAULT_PAPERCUT_BASE_URL = "https://gscdump.com";
+const PAPERCUT_PATH = "/api/cli/papercuts";
+const REQUEST_TIMEOUT_MS = 1e4;
+const singleLine = (max) => z.string().trim().min(1).max(max).regex(/^\P{Cc}*$/u, "must be a single line without control characters");
+const papercutBodySchema = z.strictObject({
+	command: singleLine(200),
+	comment: z.string().trim().min(1).max(2e3),
+	agent: singleLine(100),
+	intent: z.enum(["bug", "improvement"]).default("bug"),
+	cliVersion: singleLine(64),
+	node: singleLine(64),
+	platform: singleLine(32)
+});
+const receiptSchema = z.object({
+	id: z.string().min(1),
+	status: z.literal("new")
+});
+function buildPapercutBody(input) {
+	const parsed = papercutBodySchema.safeParse({
+		command: input.command,
+		comment: input.comment,
+		agent: input.agent,
+		intent: input.intent ?? "bug",
+		cliVersion: VERSION,
+		node: process.versions.node,
+		platform: process.platform
+	});
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		return {
+			_tag: "Err",
+			message: `${issue?.path.join(".") || "input"}: ${issue?.message ?? "invalid"}`
+		};
+	}
+	return {
+		_tag: "Ok",
+		body: parsed.data
+	};
+}
+function resolvePapercutUrl(environment) {
+	return `${(environment.GSCDUMP_API_URL || "https://gscdump.com").replace(/\/+$/, "")}${PAPERCUT_PATH}`;
+}
+async function submitPapercut(body, deps) {
+	const response = await deps.fetch(deps.url, {
+		method: "POST",
+		headers: {
+			"content-type": "application/json",
+			"accept": "application/json",
+			"x-cli-version": body.cliVersion,
+			"user-agent": `gscdump-cli/${body.cliVersion}`
+		},
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+	}).catch((cause) => ({
+		_tag: "FetchFailed",
+		cause
+	}));
+	if ("_tag" in response) {
+		const detail = response.cause instanceof Error ? response.cause.message : String(response.cause);
+		return {
+			_tag: "Err",
+			reason: "unreachable",
+			message: `Could not reach ${deps.url}: ${detail}`
+		};
+	}
+	if (response.status === 429) {
+		const retryAfter = response.headers.get("retry-after");
+		return {
+			_tag: "Err",
+			reason: "rate_limited",
+			message: `Papercut limit reached. Try again in ${retryAfter ? `${retryAfter}s` : "an hour"}.`
+		};
+	}
+	if (response.status === 400 || response.status === 422) return {
+		_tag: "Err",
+		reason: "invalid_input",
+		message: `gscdump.com rejected the papercut: ${(await response.text().catch(() => "")).slice(0, 300) || response.status}`
+	};
+	if (!response.ok) return {
+		_tag: "Err",
+		reason: "rejected",
+		message: `gscdump.com answered ${response.status}.`
+	};
+	const json = await response.json().catch(() => null);
+	const receipt = receiptSchema.safeParse(json);
+	if (!receipt.success) return {
+		_tag: "Err",
+		reason: "rejected",
+		message: "gscdump.com answered without a papercut id."
+	};
+	return {
+		_tag: "Ok",
+		receipt: receipt.data
+	};
+}
+export { DEFAULT_PAPERCUT_BASE_URL, PAPERCUT_PATH, buildPapercutBody, papercutBodySchema, resolvePapercutUrl, submitPapercut };