@gscdump/cli 3.8.0 → 4.0.0

package/dist/mcp/errors.mjs

@@ -1,22 +1,13 @@
-import { isQueryError } from "gscdump/query";
+import { HOSTED_KEY_REJECTED, HOSTED_KEY_REJECTED_REASON } from "../error-handler.mjs";
+import { resolveAuthentication } from "../auth-state.mjs";
+import { resolveBYOK, resolveServiceAccount } from "../auth.mjs";
+import { COMPARISON_FLAGS, PERIOD_FLAGS } from "../window.mjs";
 import { isAnalysisError } from "@gscdump/analysis/errors";
 import { isEngineError } from "@gscdump/engine/errors";
-const PERIODS = [
-	"7d",
-	"28d",
-	"30d",
-	"90d",
-	"180d",
-	"365d",
-	"mtd",
-	"ytd",
-	"custom"
-];
-const COMPARISONS = [
-	"none",
-	"prev-period",
-	"yoy"
-];
+import { classifyError } from "gscdump/errors";
+import { isQueryError } from "gscdump/query";
+const PERIODS = PERIOD_FLAGS;
+const COMPARISONS = COMPARISON_FLAGS;
 const mcpHandlerErrors = {
 	unknownReport(id, available) {
 		return {
@@ -50,6 +41,12 @@ const mcpHandlerErrors = {
 			message: `Unknown comparison "${value}". Supported: ${COMPARISONS.join(", ")}.`
 		};
 	},
+	invalidWindow(message) {
+		return {
+			kind: "invalid-window",
+			message
+		};
+	},
 	noValidDimension() {
 		return {
 			kind: "no-valid-dimension",
@@ -90,4 +87,60 @@ function asAnalysisError(error) {
 	const tagged = error?.analysisError;
 	return isAnalysisError(tagged) ? tagged : null;
 }
-export { enrichToolError, mcpHandlerErrorToException, mcpHandlerErrors };
+function httpStatus(error) {
+	const value = error;
+	const status = value?.statusCode ?? value?.status ?? value?.response?.status;
+	return typeof status === "number" ? status : void 0;
+}
+async function authenticationMode() {
+	if ((await resolveAuthentication().catch(() => null))?._tag === "Cloud") return "cloud";
+	if (await resolveServiceAccount().then(Boolean).catch(() => null)) return "service-account";
+	return await Promise.resolve().then(() => resolveBYOK()).catch(() => null) ? "byok" : "local";
+}
+const OAUTH_TOKEN_FAILURE_RE = /invalid_grant|invalid_client|unauthorized_client|token has been expired|token has been revoked/i;
+function classifyGoogleError(error) {
+	const classified = classifyError(error);
+	if (classified.kind !== "validation") return classified;
+	const text = `${classified.message} ${googleMessage(error) ?? ""}`;
+	return OAUTH_TOKEN_FAILURE_RE.test(text) ? {
+		...classified,
+		kind: "auth-expired"
+	} : classified;
+}
+function nextStep(error, status, mode) {
+	if (error.kind === "rate-limited") return `Google quota or rate limit reached. Try again in ${error.retryAfter ? `${error.retryAfter}s` : "a few minutes"}.`;
+	if (status === 403) {
+		if (mode === "cloud") return "The gscdump.com account cannot open this Site. Check the Site is connected to your account at gscdump.com.";
+		return "The signed-in account cannot open this Site. Check its Search Console permissions, or run `gscdump auth status` to see the account.";
+	}
+	if (status === 401 || error.kind === "auth-expired") {
+		if (mode === "cloud") return "Set or refresh GSCDUMP_API_KEY to a user API key from your gscdump.com settings.";
+		if (mode === "service-account") return "Fix the service-account key (GSC_SERVICE_ACCOUNT_JSON or GOOGLE_APPLICATION_CREDENTIALS) in the MCP server configuration and restart the MCP client, or run `gscdump auth status`.";
+		if (mode === "byok") return "Refresh GSC_ACCESS_TOKEN (or GSC_CLIENT_ID, GSC_CLIENT_SECRET, and GSC_REFRESH_TOKEN) in the MCP server configuration and restart the MCP client.";
+		return "Run `gscdump auth login` in a terminal to connect again.";
+	}
+	if (error.kind === "not-found") return "Check the Site and URL. Call list-sites to see the Sites of this account.";
+	if (error.kind === "validation") return "Check the tool arguments.";
+	return status >= 500 ? "Try again later." : "";
+}
+function describeApiError(error, mode = "local") {
+	const status = httpStatus(error);
+	if (status === void 0) return null;
+	const classified = classifyGoogleError(error);
+	const message = googleMessage(error) ?? classified.message;
+	return `API error ${status}: ${(message === HOSTED_KEY_REJECTED ? HOSTED_KEY_REJECTED_REASON : message).replace(/\s+/g, " ").trim().replace(/\.$/, "")}. ${nextStep(classified, status, mode)}`.trim();
+}
+function googleMessage(error) {
+	const bodies = [error?.data, error?.response?.data];
+	for (const body of bodies) {
+		const data = body;
+		const nested = (data?.error)?.message;
+		const message = typeof nested === "string" ? nested : data?.error_description;
+		if (typeof message === "string" && message) return message;
+	}
+}
+async function toolErrorMessage(error) {
+	const mode = await authenticationMode();
+	return enrichToolError(error)?.message ?? describeApiError(error, mode) ?? (error instanceof Error ? error.message : String(error));
+}
+export { describeApiError, enrichToolError, mcpHandlerErrorToException, mcpHandlerErrors, toolErrorMessage };

package/dist/mcp/handlers/diagnostics.mjs

@@ -1,5 +1,6 @@
 import { getCloudAccount } from "../../auth-state.mjs";
 import { missingRequiredScopes } from "../../auth-scopes.mjs";
+import { currentAccessToken, fetchTokenInfo, redactTokens } from "../../token-info.mjs";
 import { ofetch } from "ofetch";
 const FETCH_TIMEOUT_MS = 5e3;
 const TIME_SKEW_WARN_MS = 3e5;
@@ -35,12 +36,12 @@ async function diagnostics(_input, ctx) {
 			checks
 		};
 	}
-	const token = await resolveAccessToken(ctx.auth);
-	if (!token) {
+	const current = await resolveAccessToken(ctx.auth);
+	if (current.kind === "failed") {
 		checks.push({
 			name: "auth",
 			status: "fail",
-			detail: "no usable access token (refresh failed or no credentials)"
+			detail: `no usable access token: ${current.detail}`
 		});
 		return {
 			ok: false,
@@ -48,24 +49,24 @@ async function diagnostics(_input, ctx) {
 		};
 	}
 	const [tokenInfo, timeCheck, gscReachable, indexingReachable, sites] = await Promise.all([
-		ofetch("https://oauth2.googleapis.com/tokeninfo", { query: { access_token: token } }).catch((e) => ({ error: e.message })),
+		fetchTokenInfo(current.token),
 		probeTimeSkew(),
 		probeReachable("https://searchconsole.googleapis.com/$discovery/rest?version=v1"),
 		probeReachable("https://indexing.googleapis.com/$discovery/rest?version=v3"),
 		ctx.client.sites().catch((e) => e)
 	]);
-	if ("error" in tokenInfo) checks.push({
+	if (tokenInfo.kind === "invalid") checks.push({
 		name: "auth",
 		status: "fail",
-		detail: `tokeninfo failed: ${tokenInfo.error}`
+		detail: `tokeninfo failed: ${tokenInfo.detail}`
 	});
 	else {
 		checks.push({
 			name: "auth",
 			status: "pass",
-			detail: tokenInfo.email ?? "token valid"
+			detail: tokenInfo.info.email ?? "token valid"
 		});
-		const scopes = tokenInfo.scope ? tokenInfo.scope.split(/\s+/) : [];
+		const scopes = tokenInfo.info.scope ? tokenInfo.info.scope.split(/\s+/) : [];
 		const missing = missingRequiredScopes(scopes);
 		checks.push(missing.length > 0 ? {
 			name: "auth.scopes",
@@ -91,7 +92,7 @@ async function diagnostics(_input, ctx) {
 	if (sites instanceof Error) checks.push({
 		name: "gsc.sites",
 		status: "fail",
-		detail: `sites() failed: ${sites.message}`
+		detail: `sites() failed: ${redactTokens(sites.message, [current.token])}`
 	});
 	else {
 		const verified = sites.filter((s) => s.permissionLevel !== "siteUnverifiedUser").length;
@@ -107,9 +108,11 @@ async function diagnostics(_input, ctx) {
 	};
 }
 async function resolveAccessToken(auth) {
-	if (typeof auth === "string") return auth;
-	if (auth && typeof auth === "object" && "getAccessToken" in auth) return (await auth.getAccessToken().catch(() => null))?.token ?? null;
-	return null;
+	if (typeof auth === "string" || auth && typeof auth === "object") return currentAccessToken(auth);
+	return {
+		kind: "failed",
+		detail: "no credentials"
+	};
 }
 async function probeTimeSkew() {
 	const dateHeader = await ofetch.raw("https://oauth2.googleapis.com/tokeninfo", {

package/dist/mcp/handlers/reports.mjs

@@ -1,28 +1,25 @@
+import { parseWindowFlags, windowFlagErrorToException } from "../../window.mjs";
 import { enrichToolError, mcpHandlerErrorToException, mcpHandlerErrors } from "../errors.mjs";
 import { runReportInput } from "../types.mjs";
+import { getLatestGscDate } from "gscdump/dates";
+import { err, ok, unwrapResult } from "gscdump/result";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
-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";
-const PERIOD_ALIASES = {
-	"7d": "last-7d",
-	"28d": "last-28d",
-	"30d": "last-30d",
-	"90d": "last-90d",
-	"180d": "last-180d",
-	"365d": "last-365d",
-	"mtd": "mtd",
-	"ytd": "ytd",
-	"custom": "custom"
-};
-const COMPARISON_ALIASES = {
-	"none": "none",
-	"prev": "prev-period",
-	"prev-period": "prev-period",
-	"prior": "prev-period",
-	"yoy": "yoy"
-};
+function reportWindowDefaults(report) {
+	if (report.defaultPeriod === "custom") throw new Error(`Report "${report.id}" declares a custom default period. Declare a preset.`);
+	return {
+		preset: report.defaultPeriod,
+		comparison: report.defaultComparison
+	};
+}
+function toMcpWindowError(error) {
+	switch (error.kind) {
+		case "unknown-period": return mcpHandlerErrors.unknownPeriod(error.value);
+		case "unknown-comparison": return mcpHandlerErrors.unknownComparison(error.value);
+		default: return mcpHandlerErrors.invalidWindow(error.message);
+	}
+}
 function mcpArgName(name) {
 	return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 }
@@ -38,10 +35,7 @@ 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
-	});
+	const window = unwrapResult(parseWindowFlags({}, reportWindowDefaults(report), getLatestGscDate()), windowFlagErrorToException);
 	return supportsLiveSteps(report.plan(params, window));
 }
 function listReports() {
@@ -53,36 +47,33 @@ function listReports() {
 		argsSpec: Object.fromEntries(Object.entries(r.argsSpec).map(([name, arg]) => [mcpArgName(name), arg]))
 	}));
 }
-async function runReportHandlerResult(input, getContext) {
+async function runReportHandlerResult(input, getContext, resolveSite = async (siteUrl) => siteUrl) {
 	const report = defaultReportRegistry.getReport(input.id);
 	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;
-	if (!comparison) return err(mcpHandlerErrors.unknownComparison(input.comparison ?? ""));
-	const window = resolveWindow({
-		preset,
-		comparison,
+	const parsed = parseWindowFlags({
+		period: input.period,
+		vs: input.comparison,
 		start: input.start,
-		end: input.end
-	});
-	if (input.prevStart && input.prevEnd) window.comparison = {
-		start: input.prevStart,
-		end: input.prevEnd
-	};
+		end: input.end,
+		prevStart: input.prevStart,
+		prevEnd: input.prevEnd
+	}, reportWindowDefaults(report), getLatestGscDate());
+	if (!parsed.ok) return err(toMcpWindowError(parsed.error));
+	const window = parsed.value;
 	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 siteUrl = await resolveSite(input.siteUrl);
 	const ctx = await getContext();
 	const source = createGscApiQuerySource({
 		client: ctx.client,
-		siteUrl: input.siteUrl
+		siteUrl
 	});
 	const reportCtx = {
-		site: input.siteUrl,
+		site: siteUrl,
 		window,
 		params,
 		registryVersion: defaultReportRegistry.version
@@ -93,8 +84,8 @@ async function runReportHandlerResult(input, getContext) {
 		ctx: reportCtx
 	}));
 }
-async function runReportHandler(input, getContext) {
-	return unwrapResult(await runReportHandlerResult(input, getContext).catch((thrown) => {
+async function runReportHandler(input, getContext, resolveSite) {
+	return unwrapResult(await runReportHandlerResult(input, getContext, resolveSite).catch((thrown) => {
 		throw enrichToolError(thrown) ?? thrown;
 	}), mcpHandlerErrorToException);
 }

package/dist/mcp/server/index.mjs

@@ -1,12 +1,15 @@
+import { formatSiteResolution } from "../../context.mjs";
 import { discoverLiveSitemap } from "../../sitemap.mjs";
+import { toolErrorMessage } from "../errors.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 { batchInspectUrlsInput, batchRequestIndexingInput, getIndexingStatusInput, inspectUrlInput, listReportsInput, listSitemapsInput, listSitesInput, requestIndexingInput, runReportInput, sitemapInput } from "../types.mjs";
+import { batchInspectUrlsInput, batchRequestIndexingInput, getIndexingStatusInput, inspectUrlInput, listReportsInput, listSitemapsInput, listSitesInput, requestIndexingInput, runReportInput, siteUrlSchema, 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 { resolveSiteInput } from "gscdump";
 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";
@@ -60,6 +63,13 @@ function createGscMcpServer(options) {
 		name,
 		version
 	});
+	const registerTool = ((toolName, config, callback) => server.registerTool(toolName, config, (...args) => Promise.resolve().then(() => callback(...args)).catch(async (error) => ({
+		isError: true,
+		content: [{
+			type: "text",
+			text: await toolErrorMessage(error)
+		}]
+	}))));
 	const getContext = async () => {
 		if (options.getContext) return options.getContext();
 		const a = await options.getAuth();
@@ -69,20 +79,43 @@ function createGscMcpServer(options) {
 		};
 	};
 	const getClient = async () => (await getContext()).client;
-	server.registerTool("list-sites", {
+	let siteList;
+	const fetchSites = async () => {
+		return (await (await getClient()).sites()).flatMap((s) => s.siteUrl && s.permissionLevel !== "siteUnverifiedUser" ? [{
+			siteUrl: s.siteUrl,
+			permissionLevel: s.permissionLevel || "unknown"
+		}] : []);
+	};
+	const cacheSiteList = (sites) => {
+		const cached = sites.then((list) => list.map(({ siteUrl }) => ({ siteUrl }))).catch((error) => {
+			if (siteList === cached) siteList = void 0;
+			throw error;
+		});
+		siteList = cached;
+		return cached;
+	};
+	const loadSiteList = () => siteList ?? cacheSiteList(fetchSites());
+	const withSite = async (args) => {
+		const resolution = resolveSiteInput(args.siteUrl, await loadSiteList());
+		if (resolution.kind !== "resolved") throw new Error(formatSiteResolution(resolution, "account"));
+		return {
+			...args,
+			siteUrl: resolution.siteUrl
+		};
+	};
+	registerTool("list-sites", {
 		description: "List all Google Search Console sites visible to the authenticated user.",
 		inputSchema: listSitesInput.shape
 	}, async () => {
-		const sites = (await (await getClient()).sites()).filter((s) => s.siteUrl && s.permissionLevel !== "siteUnverifiedUser").map((s) => ({
-			siteUrl: s.siteUrl,
-			permissionLevel: s.permissionLevel || "unknown"
-		}));
+		const fetched = fetchSites();
+		cacheSiteList(fetched).catch(() => {});
+		const sites = await fetched;
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(sites, null, 2)
 		}] };
 	});
-	server.registerTool("list-sites-with-sitemaps", {
+	registerTool("list-sites-with-sitemaps", {
 		description: "List all GSC sites with their sitemaps",
 		inputSchema: listSitesInput.shape
 	}, async (args) => {
@@ -92,47 +125,50 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("list-sitemaps", {
+	registerTool("list-sitemaps", {
 		description: "List sitemaps for a specific site",
 		inputSchema: listSitemapsInput.shape
-	}, async (args) => {
+	}, async (input) => {
+		const args = await withSite(input);
 		const sitemaps = await (await getClient()).sitemaps.list(args.siteUrl);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(sitemaps, null, 2)
 		}] };
 	});
-	server.registerTool("get-sitemap", {
+	registerTool("get-sitemap", {
 		description: "Get details for a specific sitemap",
 		inputSchema: sitemapInput.shape
 	}, async (args) => {
-		const result = await getSitemap(args, await getContext());
+		const result = await getSitemap(await withSite(args), await getContext());
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("submit-sitemap", {
+	registerTool("submit-sitemap", {
 		description: "Submit a sitemap to Google Search Console",
 		inputSchema: sitemapInput.shape
-	}, async (args) => {
+	}, async (input) => {
+		const args = await withSite(input);
 		await (await getClient()).sitemaps.submit(args.siteUrl, args.feedpath);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({ success: true }, null, 2)
 		}] };
 	});
-	server.registerTool("delete-sitemap", {
+	registerTool("delete-sitemap", {
 		description: "Delete a sitemap from Google Search Console",
 		inputSchema: sitemapInput.shape
-	}, async (args) => {
+	}, async (input) => {
+		const args = await withSite(input);
 		await (await getClient()).sitemaps.delete(args.siteUrl, args.feedpath);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({ success: true }, null, 2)
 		}] };
 	});
-	server.registerTool("list-reports", {
+	registerTool("list-reports", {
 		description: "List Reports supported by the live Google API. Returns defaults and argsSpec using run-report input names.",
 		inputSchema: listReportsInput.shape
 	}, async () => {
@@ -142,11 +178,11 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("run-report", {
+	registerTool("run-report", {
 		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 result = await runReportHandler(args, getContext);
+		const result = await runReportHandler(args, getContext, async (siteUrl) => (await withSite({ siteUrl })).siteUrl);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(result, null, 2)
@@ -176,10 +212,10 @@ function createGscMcpServer(options) {
 		groupType: z.enum(["and"]).optional().describe("Only \"and\" is supported; multiple groups do not implement OR"),
 		filters: z.array(dimensionFilterSchema)
 	});
-	server.registerTool("query", {
+	registerTool("query", {
 		description: "Run a custom search analytics query with dimension filters (regex/contains/equals). Multiple filter groups do not implement OR.",
 		inputSchema: z.object({
-			siteUrl: z.string().describe("GSC property URL (e.g., sc-domain:example.com)"),
+			siteUrl: siteUrlSchema,
 			startDate: z.string().describe("Start date (YYYY-MM-DD)"),
 			endDate: z.string().describe("End date (YYYY-MM-DD)"),
 			dimensions: z.array(z.enum([
@@ -196,7 +232,8 @@ function createGscMcpServer(options) {
 			aggregationType: z.enum(["byPage", "byProperty"]).optional().describe("Aggregation type"),
 			dimensionFilterGroups: z.array(filterGroupSchema).optional().describe("Filter groups use \"and\" internally. Multiple groups do not implement OR.")
 		}).shape
-	}, async ({ siteUrl, startDate, endDate, dimensions, rowLimit, type, dataState, aggregationType, dimensionFilterGroups }) => {
+	}, async ({ siteUrl: input, startDate, endDate, dimensions, rowLimit, type, dataState, aggregationType, dimensionFilterGroups }) => {
+		const { siteUrl } = await withSite({ siteUrl: input });
 		const result = await runMcpSearchAnalyticsQuery(await getClient(), {
 			siteUrl,
 			startDate,
@@ -213,17 +250,18 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("inspect-url", {
+	registerTool("inspect-url", {
 		description: "Inspect a URL to check its indexing status in Google Search Console",
 		inputSchema: inspectUrlInput.shape
-	}, async (args) => {
+	}, async (input) => {
+		const args = await withSite(input);
 		const result = await (await getClient()).inspect(args.siteUrl, args.inspectionUrl);
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("request-indexing", {
+	registerTool("request-indexing", {
 		description: "Request Google to index or remove a URL via the Indexing API",
 		inputSchema: requestIndexingInput.shape
 	}, async (args) => {
@@ -233,7 +271,7 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("get-indexing-status", {
+	registerTool("get-indexing-status", {
 		description: "Get indexing status metadata for a URL",
 		inputSchema: getIndexingStatusInput.shape
 	}, async (args) => {
@@ -243,7 +281,7 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("batch-request-indexing", {
+	registerTool("batch-request-indexing", {
 		description: "Batch request indexing for multiple URLs with rate limiting",
 		inputSchema: batchRequestIndexingInput.shape
 	}, async (args) => {
@@ -253,17 +291,17 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("batch-inspect-urls", {
+	registerTool("batch-inspect-urls", {
 		description: "Batch inspect multiple URLs to check their indexing status",
 		inputSchema: batchInspectUrlsInput.shape
 	}, async (args) => {
-		const result = await batchInspectUrls$1(args, await getContext());
+		const result = await batchInspectUrls$1(await withSite(args), await getContext());
 		return { content: [{
 			type: "text",
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("diagnostics", {
+	registerTool("diagnostics", {
 		description: "Run health checks on the active GSC connection: auth/scopes, time skew, API reachability, sites count.",
 		inputSchema: listSitesInput.shape
 	}, async (args) => {
@@ -273,12 +311,13 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(result, null, 2)
 		}] };
 	});
-	server.registerTool("add-site", {
+	registerTool("add-site", {
 		description: "Register a property in Search Console (unverified). Verify ownership separately.",
 		inputSchema: z.object({ siteUrl: z.string().describe("Property URL (https://example.com/ or sc-domain:example.com)") }).shape
 	}, async ({ siteUrl }) => {
 		const client = await getClient();
 		await addSite(client, siteUrl);
+		siteList = void 0;
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -288,12 +327,13 @@ function createGscMcpServer(options) {
 			}, null, 2)
 		}] };
 	});
-	server.registerTool("delete-site", {
+	registerTool("delete-site", {
 		description: "Remove a property from Search Console.",
 		inputSchema: z.object({ siteUrl: z.string().describe("Property URL") }).shape
 	}, async ({ siteUrl }) => {
 		const client = await getClient();
 		await deleteSite(client, siteUrl);
+		siteList = void 0;
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -310,7 +350,7 @@ function createGscMcpServer(options) {
 		"ANALYTICS",
 		"TAG_MANAGER"
 	]);
-	server.registerTool("get-verification-token", {
+	registerTool("get-verification-token", {
 		description: "Get a verification token to place on the site or in DNS.",
 		inputSchema: z.object({
 			siteUrl: z.string(),
@@ -329,7 +369,7 @@ function createGscMcpServer(options) {
 			}, null, 2)
 		}] };
 	});
-	server.registerTool("verify-site", {
+	registerTool("verify-site", {
 		description: "Trigger Google to validate a placed verification token.",
 		inputSchema: z.object({
 			siteUrl: z.string(),
@@ -338,6 +378,7 @@ function createGscMcpServer(options) {
 	}, async ({ siteUrl, method }) => {
 		const client = await getClient();
 		const resource = await verifySite(client, siteUrl, method);
+		siteList = void 0;
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -347,7 +388,7 @@ function createGscMcpServer(options) {
 			}, null, 2)
 		}] };
 	});
-	server.registerTool("list-verified-sites", {
+	registerTool("list-verified-sites", {
 		description: "List verified WebResources from the Site Verification API.",
 		inputSchema: z.object({}).shape
 	}, async () => {
@@ -358,7 +399,7 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(resources, null, 2)
 		}] };
 	});
-	server.registerTool("get-verified-site", {
+	registerTool("get-verified-site", {
 		description: "Fetch a single verified WebResource by id.",
 		inputSchema: z.object({ id: z.string().describe("WebResource id (from list-verified-sites)") }).shape
 	}, async ({ id }) => {
@@ -369,12 +410,13 @@ function createGscMcpServer(options) {
 			text: JSON.stringify(resource, null, 2)
 		}] };
 	});
-	server.registerTool("unverify-site", {
+	registerTool("unverify-site", {
 		description: "Drop the calling user's verified ownership of a WebResource. Remove the placed token first or Google may re-verify.",
 		inputSchema: z.object({ id: z.string().describe("WebResource id (from list-verified-sites)") }).shape
 	}, async ({ id }) => {
 		const client = await getClient();
 		await unverifySite(client, id);
+		siteList = void 0;
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({
@@ -383,7 +425,7 @@ function createGscMcpServer(options) {
 			}, null, 2)
 		}] };
 	});
-	server.registerTool("discover-sitemap", {
+	registerTool("discover-sitemap", {
 		description: "Probe a domain's robots.txt + common paths for an advertised sitemap (no auth).",
 		inputSchema: z.object({ domain: z.string().describe("Domain (e.g., example.com)") }).shape
 	}, async ({ domain }) => {
@@ -399,7 +441,7 @@ function createGscMcpServer(options) {
 			}, null, 2)
 		}] };
 	});
-	server.registerTool("batch-get-indexing-status", {
+	registerTool("batch-get-indexing-status", {
 		description: "Get indexing notification metadata for multiple URLs.",
 		inputSchema: z.object({
 			urls: z.array(z.string()).describe("URLs"),

package/dist/mcp/types.mjs

@@ -4,7 +4,7 @@ const periodSchema = z.object({
 	start: z.string().describe("Start date (YYYY-MM-DD)"),
 	end: z.string().describe("End date (YYYY-MM-DD)")
 }).describe("Date range for the query");
-const siteUrlSchema = z.string().describe("GSC property URL (e.g., sc-domain:example.com or https://example.com/)");
+const siteUrlSchema = z.string().describe("Site, for example example.com. Scheme, www and case do not matter. The tool resolves it to the Search Console property.");
 const queryOptionsSchema = z.object({
 	type: z.enum(SearchTypes).optional().describe("Data type"),
 	dataState: z.enum(["final", "all"]).optional().describe("Data state: final (settled) or all (includes fresh)"),
@@ -69,12 +69,12 @@ const listReportsInput = z.object({});
 const runReportInput = z.object({
 	siteUrl: siteUrlSchema,
 	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."),
+	period: z.string().optional().describe("Window: 7d|28d|30d|90d|180d|365d|mtd|qtd|ytd|last-quarter|custom (default per report). Windows end on the newest final GSC date."),
+	comparison: z.string().optional().describe("Comparison: none|prev-period|yoy (default per report). yoy compares with the same weekdays 52 weeks earlier."),
+	start: z.string().optional().describe("Custom window start (YYYY-MM-DD). Implies period=custom."),
+	end: z.string().optional().describe("Custom window end (YYYY-MM-DD). Implies period=custom."),
+	prevStart: z.string().optional().describe("Override comparison-window start. Pass with prevEnd."),
+	prevEnd: z.string().optional().describe("Override comparison-window end. Pass with prevStart."),
 	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."),