mcp-google-gsc 1.1.2 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@ MCP server for Google Search Console -- search analytics, URL inspection, and si
 
 - **Search Analytics** -- Query clicks, impressions, CTR, and position with flexible dimension filters (query, page, device, country, date)
 - **URL Inspection** -- Check indexing status, mobile usability, and rich results for any URL
-- **Site Listing** -- List all verified Search Console properties accessible to your service account
+- **Site Listing** -- List all verified Search Console properties accessible to your authenticated account (OAuth user or service account)
 - **Multi-Client Support** -- Manage multiple GSC properties with per-directory config mapping
 
 ## Installation
@@ -30,32 +30,74 @@ npm run build
 
 **Security:** Never share your `.mcp.json` file or commit it to git -- it may contain API credentials. Add `.mcp.json` to your `.gitignore`.
 
-### Service Account Setup
+mcp-gsc supports **two authentication modes**. Pick whichever fits your setup. Neither requires any file living at a hardcoded machine-local path -- credentials come from environment variables (or a `config.json` you create).
 
-1. Create a Google Cloud service account with Search Console API access
-2. Download the JSON key file
-3. Add the service account email as a user in Google Search Console for each property
+**Which mode to use:**
+- **Service Account (Mode B) -- recommended for unattended / server / headless use.** A service account has no interactive login to expire or re-consent, so it is the right fit for always-on deployments. The one setup requirement is that the service account's email must be **granted access on each Search Console property** you want to query (see Mode B).
+- **User OAuth (Mode A) -- for personal / interactive use**, where you want to authorize with your own Google login.
 
-### Config File
+**Precedence when both are configured:** if a service-account keyfile is explicitly set (`GOOGLE_APPLICATION_CREDENTIALS`, or `credentials_file` in `config.json`), it **wins** over any OAuth refresh token or stored OAuth credentials. If neither is configured, the server fails loudly at startup with an onboarding message rather than silently guessing -- there is no machine-local default and no silent runtime failover between modes.
 
-Create a `config.json` in the project root (see `config.example.json` for the full structure):
+### Mode A: User OAuth (bring your own Google account)
+
+Use this if you want to authorize with your own Google login (the account that has Search Console access). Best for personal / interactive use.
+
+1. In the Google Cloud Console, create an **OAuth 2.0 Client ID** of type **Desktop app** and enable the **Search Console API**. (For a Desktop-app client, Google accepts any `http://localhost` loopback redirect -- you do not need to pre-register a port.)
+2. Export your client credentials:
+   ```bash
+   export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
+   export GOOGLE_GSC_CLIENT_SECRET=...
+   ```
+3. Mint a refresh token (opens your browser, uses PKCE + `access_type=offline`):
+   ```bash
+   node get-refresh-token.cjs
+   ```
+   > Do **not** redirect this command's stdout to a shared log -- it prints the refresh token to stdout by design.
+4. Copy the printed line into your environment:
+   ```bash
+   export GOOGLE_GSC_REFRESH_TOKEN=...
+   ```
+
+The server reads `GOOGLE_GSC_CLIENT_ID`, `GOOGLE_GSC_CLIENT_SECRET`, and `GOOGLE_GSC_REFRESH_TOKEN` from the environment at runtime.
+
+Alternatively, run the guided helper `npx mcp-gsc-auth`, which performs the same PKCE OAuth flow, lets you pick a default Search Console property, and writes the result to a per-user credentials file.
+
+### Mode B: Service Account (recommended for unattended / server use)
+
+Use this for server / headless / always-on contexts -- it is the recommended path when no human is present to complete or refresh an interactive login.
+
+1. Create a Google Cloud **service account** with Search Console API access and download its JSON key file.
+2. **Grant the service account's email access on each Search Console property** you want to query (add it as a user in Search Console). Without this grant on the property, the service account can authenticate but will see no sites.
+3. Point the server at the key file **via an environment variable** (no hardcoded path):
+   ```bash
+   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
+   ```
+
+### OAuth scope
+
+Both modes request a single, **read-only** scope: `https://www.googleapis.com/auth/webmasters.readonly`. All four tools are reads -- nothing writes -- so the server never asks for read/write access.
+
+The scope is defined once in `config.json` under `oauth.scope` (see `config.example.json`). The OAuth helper and the runtime read the same value, so they never drift. If `config.json` is absent (e.g. a fresh install), the committed read-only default is used.
+
+### Multi-client config (optional)
+
+To map working directories to Search Console properties, create a `config.json` in the project root (see `config.example.json`):
 
 ```json
 {
-  "default_credentials": "/path/to/service-account-key.json",
+  "oauth": {
+    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
+  },
   "clients": {
     "my-project": {
-      "site_url": "sc-domain:example.com",
-      "credentials": "/path/to/service-account-key.json"
+      "name": "My Project",
+      "folder": "/path/to/project",
+      "site_url": "https://example.com/"
     }
   }
 }
 ```
 
-### Environment Variable
-
-Alternatively, set `GOOGLE_APPLICATION_CREDENTIALS` to the path of your service account key file. The config file takes precedence when present.
-
 ## Usage
 
 Add to your Claude Code `.mcp.json`:
@@ -91,7 +133,7 @@ Or if installed globally:
 | Tool | Description |
 |------|-------------|
 | `gsc_get_client_context` | Detect the GSC property from your working directory based on config mapping |
-| `gsc_list_sites` | List all verified Search Console properties accessible to the service account |
+| `gsc_list_sites` | List all verified Search Console properties accessible to the authenticated account |
 | `gsc_search_analytics` | Query search performance data (clicks, impressions, CTR, position) with dimension and filter support |
 | `gsc_inspection` | Inspect a URL for indexing status, mobile usability, and rich results |
 

package/config.example.json

@@ -1,5 +1,7 @@
 {
-  "credentials_file": "/path/to/service-account.json",
+  "oauth": {
+    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
+  },
   "clients": {
     "my-client": {
       "name": "My Client",

package/dist/auth-cli.d.ts

@@ -1,2 +1,12 @@
 #!/usr/bin/env node
+/** Resolve the OAuth scope from config.json (falls back to the read-only default). */
+export declare function resolveAuthScope(configPath?: string): string;
+export interface BuildAuthUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    scope: string;
+    state: string;
+    codeChallenge: string;
+}
+export declare function buildAuthUrl({ clientId, redirectUri, scope, state, codeChallenge, }: BuildAuthUrlOptions): string;
 export declare function run(argv?: string[]): Promise<void>;

package/dist/auth-cli.js

@@ -1,17 +1,32 @@
 #!/usr/bin/env node
 import { google } from "googleapis";
 import http from "http";
+import path from "path";
+import { fileURLToPath } from "url";
 import promptsImport from "prompts";
 import { URL } from "url";
 import { writeStoredCredentials, credentialsFilePath, CREDENTIALS_FILE_VERSION } from "./credentials.js";
 import { EMBEDDED_CLIENT_ID, EMBEDDED_CLIENT_SECRET } from "./embedded-secrets.js";
 import { classifyError, GscAuthError } from "./errors.js";
 import { findFreeLoopbackPort, openBrowser } from "./platform.js";
+import { loadOAuthScopeFromFile } from "./oauthScope.js";
+import {
+  computeCodeChallenge,
+  generateCodeVerifier,
+  buildLoopbackRedirectUri
+} from "./pkce.js";
 import { logger, withResilience } from "./resilience.js";
 const prompts = promptsImport.default ?? promptsImport;
-const OAUTH_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
 const OAUTH_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
 const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const DEFAULT_CONFIG_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "config.json"
+);
+function resolveAuthScope(configPath = DEFAULT_CONFIG_PATH) {
+  return loadOAuthScopeFromFile(configPath);
+}
 function parseArgs(argv) {
   const args = { help: false };
   for (let i = 0; i < argv.length; i++) {
@@ -41,15 +56,26 @@ function printHelp() {
     ].join("\n")
   );
 }
-function buildAuthUrl(clientId, redirectUri, state) {
+function buildAuthUrl({
+  clientId,
+  redirectUri,
+  scope,
+  state,
+  codeChallenge
+}) {
   const params = new URLSearchParams({
     client_id: clientId,
     redirect_uri: redirectUri,
     response_type: "code",
-    scope: OAUTH_SCOPE,
+    scope,
     access_type: "offline",
+    // REQUIRED for Google to return a refresh_token
     prompt: "consent",
-    state
+    // force a refresh_token even on re-consent
+    state,
+    code_challenge: codeChallenge,
+    // PKCE S256
+    code_challenge_method: "S256"
   });
   return `${OAUTH_AUTH_URL}?${params.toString()}`;
 }
@@ -135,14 +161,16 @@ function renderPage(title, body) {
 function escapeHtml(s) {
   return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 }
-async function exchangeCodeForTokens(code, clientId, clientSecret, redirectUri) {
+async function exchangeCodeForTokens(code, clientId, clientSecret, redirectUri, codeVerifier) {
   return withResilience(async () => {
     const body = new URLSearchParams({
       code,
       client_id: clientId,
       client_secret: clientSecret,
       redirect_uri: redirectUri,
-      grant_type: "authorization_code"
+      grant_type: "authorization_code",
+      code_verifier: codeVerifier
+      // PKCE proof — sent on exchange
     });
     const res = await fetch(OAUTH_TOKEN_URL, {
       method: "POST",
@@ -232,13 +260,16 @@ async function run(argv = process.argv.slice(2)) {
     process.exit(2);
   }
   const port = await findFreeLoopbackPort();
-  const redirectUri = `http://127.0.0.1:${port}`;
+  const redirectUri = buildLoopbackRedirectUri(port);
+  const scope = resolveAuthScope();
   const state = randomState();
-  const authUrl = buildAuthUrl(clientId, redirectUri, state);
+  const codeVerifier = generateCodeVerifier();
+  const codeChallenge = computeCodeChallenge(codeVerifier);
+  const authUrl = buildAuthUrl({ clientId, redirectUri, scope, state, codeChallenge });
   process.stderr.write("\n=== mcp-gsc authentication ===\n");
   const { code } = await waitForAuthorizationCode(port, state, authUrl);
   process.stderr.write("Authorization code received. Exchanging for tokens...\n");
-  const tokens = await exchangeCodeForTokens(code, clientId, clientSecret, redirectUri);
+  const tokens = await exchangeCodeForTokens(code, clientId, clientSecret, redirectUri, codeVerifier);
   if (!tokens.refresh_token) {
     throw new GscAuthError(
       "Google did not return a refresh token. This can happen if you previously granted consent to this app. Revoke access at https://myaccount.google.com/permissions and try again."
@@ -253,7 +284,7 @@ async function run(argv = process.argv.slice(2)) {
     site_urls: sites.map((s) => s.siteUrl),
     primary_site_url: chosen.siteUrl,
     obtained_at: (/* @__PURE__ */ new Date()).toISOString(),
-    scopes: [OAUTH_SCOPE]
+    scopes: [scope]
   };
   writeStoredCredentials(stored);
   process.stderr.write(
@@ -276,14 +307,22 @@ function randomState() {
   globalThis.crypto.getRandomValues(bytes);
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
-run().catch((err) => {
-  const classified = classifyError(err);
-  process.stderr.write(`
+function isEntryPoint() {
+  const entry = process.argv[1] || "";
+  return /(^|[\\/])auth-cli(\.[cm]?js)?$/.test(entry);
+}
+if (isEntryPoint()) {
+  run().catch((err) => {
+    const classified = classifyError(err);
+    process.stderr.write(`
 ${classified.message}
 `);
-  process.exit(1);
-});
+    process.exit(1);
+  });
+}
 export {
+  buildAuthUrl,
+  resolveAuthScope,
   run
 };
 //# sourceMappingURL=auth-cli.js.map

package/dist/authMode.d.ts

@@ -0,0 +1,22 @@
+export interface AuthModeInputs {
+    /** Absolute service-account keyfile path (from GOOGLE_APPLICATION_CREDENTIALS or config.json). "" if none. */
+    credentialsFile: string;
+    /** User-OAuth refresh token from env (GOOGLE_GSC_REFRESH_TOKEN). "" if none. */
+    refreshToken: string;
+    /** True if a stored OAuth credentials file (auth-helper output) exists on disk. */
+    hasStoredCreds: boolean;
+}
+export type AuthMode = "service_account" | "oauth" | "unconfigured";
+export interface AuthModeSelection {
+    mode: AuthMode;
+    /** Echoed back for service_account so the caller can load the keyfile. */
+    credentialsFile: string;
+}
+/**
+ * Decide the auth mode. Precedence:
+ *   1. service_account — an explicit keyfile path wins (matches historical
+ *      loadConfig precedence and is the most explicit signal).
+ *   2. oauth — a refresh token (env) or a stored credentials file.
+ *   3. unconfigured — no signal; caller must surface an onboarding error.
+ */
+export declare function selectAuthMode(inputs: AuthModeInputs): AuthModeSelection;

package/dist/authMode.js

@@ -0,0 +1,14 @@
+function selectAuthMode(inputs) {
+  const credentialsFile = (inputs.credentialsFile || "").trim();
+  if (credentialsFile) {
+    return { mode: "service_account", credentialsFile };
+  }
+  if ((inputs.refreshToken || "").trim() || inputs.hasStoredCreds) {
+    return { mode: "oauth", credentialsFile: "" };
+  }
+  return { mode: "unconfigured", credentialsFile: "" };
+}
+export {
+  selectAuthMode
+};
+//# sourceMappingURL=authMode.js.map

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "e1f706c",
-  "builtAt": "2026-04-18T18:17:03.690Z",
+  "sha": "6fd2d02",
+  "builtAt": "2026-07-09T14:24:13.759Z",
   "embeddedSecrets": true
 }

package/dist/credentials.js

@@ -49,11 +49,11 @@ function resolveOAuthCredentials(credsFilePath = credentialsFilePath) {
   if (!client_secret) missing.push("client_secret");
   if (!refresh_token) missing.push("refresh_token");
   if (missing.length > 0) {
-    throw new Error(buildMissingCredentialsMessage(missing, Boolean(stored)));
+    throw new Error(buildMissingCredentialsMessage(missing, Boolean(stored), credsFilePath));
   }
   return { client_id, client_secret, refresh_token, site_urls, primary_site_url, source };
 }
-function buildMissingCredentialsMessage(missing, hasFile) {
+function buildMissingCredentialsMessage(missing, hasFile, credsFilePath = credentialsFilePath) {
   const runAuth = "npx mcp-gsc-auth";
   const lines = [
     `Missing GSC OAuth credentials: ${missing.join(", ")}.`,
@@ -63,12 +63,12 @@ function buildMissingCredentialsMessage(missing, hasFile) {
     ``,
     `This will open your browser, walk you through Google sign-in, let you pick which`,
     `Search Console property to use, and save the result to:`,
-    `    ${credentialsFilePath}`
+    `    ${credsFilePath}`
   ];
   if (hasFile) {
     lines.push(
       ``,
-      `A credentials file exists at ${credentialsFilePath} but is missing required fields.`,
+      `A credentials file exists at ${credsFilePath} but is missing required fields.`,
       `Re-run the auth helper to refresh it.`
     );
   }

package/dist/index.d.ts

@@ -1,2 +1,54 @@
 #!/usr/bin/env node
+import { type AuthModeSelection } from "./authMode.js";
+interface ClientConfig {
+    name: string;
+    folder: string;
+    site_url: string;
+}
+interface Config {
+    credentials_file: string;
+    oauth_credentials_file: string;
+    oauth_scope: string;
+    clients: Record<string, ClientConfig>;
+}
+/**
+ * Decide the runtime auth mode through the shared selectAuthMode() decision
+ * point (NOT an inline `if (credentials_file)` branch). Signals:
+ *   - credentialsFile: SA keyfile path (config.json / GOOGLE_APPLICATION_CREDENTIALS)
+ *   - refreshToken:     env GOOGLE_GSC_REFRESH_TOKEN
+ *   - hasStoredCreds:   a StoredCredentials file (auth-helper output) exists
+ * Returns "service_account" | "oauth" | "unconfigured". Never silently defaults
+ * to service_account when nothing is configured.
+ */
+export interface RuntimeAuthModeOptions {
+    /** Path checked for an existing StoredCredentials file. Defaults to the
+     *  per-config path (config.oauth_credentials_file) or the global default.
+     *  Injectable so tests can isolate from a real credentials file on the box. */
+    storedCredsPath?: string;
+    /** Env-like source for the refresh token. Defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare function resolveRuntimeAuthMode(config: Config, opts?: RuntimeAuthModeOptions): AuthModeSelection;
+/** Construct a GscManager, surfacing the onboarding error for the unconfigured case. */
+export declare function buildGscManager(config: Config, opts?: RuntimeAuthModeOptions): GscManager;
+declare class GscManager {
+    private config;
+    private service;
+    private authMode;
+    constructor(config: Config, authOpts?: RuntimeAuthModeOptions);
+    private oauthCredsPath;
+    private getService;
+    listSites(): Promise<any>;
+    searchAnalytics(options: {
+        startDate: string;
+        endDate: string;
+        dimensions: string[];
+        searchType: string;
+        dimensionFilter: string;
+        rowLimit: number;
+        aggregationType: string;
+        siteUrl: string;
+    }): Promise<any>;
+    inspection(url: string, siteUrl: string): Promise<any>;
+}
 export {};

package/dist/index.js

@@ -7,6 +7,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { readFileSync, existsSync } from "fs";
 import { join, dirname, resolve, isAbsolute } from "path";
+import { fileURLToPath } from "url";
 import { google } from "googleapis";
 import {
   GscAuthError,
@@ -15,14 +16,16 @@ import {
   classifyError,
   validateCredentials
 } from "./errors.js";
-import { resolveOAuthCredentials } from "./credentials.js";
+import { resolveOAuthCredentials, credentialsFilePath } from "./credentials.js";
+import { loadOAuthScopeFromFile } from "./oauthScope.js";
+import { selectAuthMode } from "./authMode.js";
 import { tools } from "./tools.js";
 import { withResilience, safeResponse, logger } from "./resilience.js";
-import { checkForUpdate } from "./updateNotifier.js";
+import { checkForUpdate } from "mcp-updatenotifier";
 import v8 from "v8";
-const __cliPkg = JSON.parse(readFileSync(join(dirname(new URL(import.meta.url).pathname), "..", "package.json"), "utf-8"));
+const __cliPkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8"));
 try {
-  const __buildInfoDir = dirname(new URL(import.meta.url).pathname);
+  const __buildInfoDir = dirname(fileURLToPath(import.meta.url));
   const buildInfo = JSON.parse(readFileSync(join(__buildInfoDir, "build-info.json"), "utf-8"));
   console.error(`[build] SHA: ${buildInfo.sha} (${buildInfo.builtAt})`);
 } catch {
@@ -68,12 +71,17 @@ if (heapLimit < 256 * 1024 * 1024) {
 }
 const envTrimmed = (key) => (process.env[key] || "").trim().replace(/^["']|["']$/g, "");
 function loadConfig() {
-  const configPath = join(dirname(new URL(import.meta.url).pathname), "..", "config.json");
+  const defaultConfigPath = join(dirname(fileURLToPath(import.meta.url)), "..", "config.json");
+  const configPath = envTrimmed("MCP_GSC_CONFIG_PATH") || defaultConfigPath;
+  const oauth_scope = loadOAuthScopeFromFile(configPath);
   if (existsSync(configPath)) {
     const raw = JSON.parse(readFileSync(configPath, "utf-8"));
     const rawCf = raw.credentials_file || envTrimmed("GOOGLE_APPLICATION_CREDENTIALS");
+    const rawOauth = raw.oauth_credentials_file || "";
     return {
       credentials_file: rawCf && !isAbsolute(rawCf) ? resolve(rawCf) : rawCf,
+      oauth_credentials_file: rawOauth && !isAbsolute(rawOauth) ? resolve(rawOauth) : rawOauth,
+      oauth_scope,
       clients: raw.clients || {}
     };
   }
@@ -82,11 +90,15 @@ function loadConfig() {
   if (credsFile) {
     return {
       credentials_file: credsFile,
+      oauth_credentials_file: "",
+      oauth_scope,
       clients: {}
     };
   }
   return {
     credentials_file: "",
+    oauth_credentials_file: "",
+    oauth_scope,
     clients: {}
   };
 }
@@ -138,14 +150,33 @@ function parseDimensionFilter(filterStr) {
   }
   return null;
 }
+function resolveRuntimeAuthMode(config2, opts = {}) {
+  const credsPath = opts.storedCredsPath ?? (config2.oauth_credentials_file || credentialsFilePath);
+  const env = opts.env ?? process.env;
+  const refreshToken = (env.GOOGLE_GSC_REFRESH_TOKEN || "").trim().replace(/^["']|["']$/g, "");
+  return selectAuthMode({
+    credentialsFile: config2.credentials_file,
+    refreshToken,
+    hasStoredCreds: existsSync(credsPath)
+  });
+}
+function buildGscManager(config2, opts = {}) {
+  return new GscManager(config2, opts);
+}
 class GscManager {
   config;
   service = null;
   authMode = "service_account";
-  constructor(config2) {
+  constructor(config2, authOpts = {}) {
     this.config = config2;
-    if (config2.credentials_file) {
-      const creds = validateCredentials(config2.credentials_file);
+    const selection = resolveRuntimeAuthMode(config2, authOpts);
+    if (selection.mode === "unconfigured") {
+      const msg = "No GSC credentials configured. Choose one auth mode:\n  - User OAuth: run `npx mcp-gsc-auth` (or `node get-refresh-token.cjs`) to mint a refresh token, then set GOOGLE_GSC_CLIENT_ID / GOOGLE_GSC_CLIENT_SECRET / GOOGLE_GSC_REFRESH_TOKEN.\n  - Service account: set GOOGLE_APPLICATION_CREDENTIALS to a JSON key file path.";
+      console.error(`[STARTUP ERROR] ${msg}`);
+      throw new GscAuthError(msg);
+    }
+    if (selection.mode === "service_account") {
+      const creds = validateCredentials(selection.credentialsFile);
       if (!creds.valid) {
         const msg = `[STARTUP ERROR] Missing required credentials: ${creds.missing.join(", ")}. MCP will not function.`;
         console.error(msg);
@@ -153,21 +184,25 @@ class GscManager {
       }
       this.authMode = "service_account";
     } else {
-      resolveOAuthCredentials();
+      resolveOAuthCredentials(this.oauthCredsPath());
       this.authMode = "oauth";
     }
   }
+  // Per-config OAuth token path when set, else undefined (global default).
+  oauthCredsPath() {
+    return this.config.oauth_credentials_file || void 0;
+  }
   getService() {
     if (!this.service) {
       if (this.authMode === "service_account") {
         const auth = new google.auth.GoogleAuth({
           keyFile: this.config.credentials_file,
-          scopes: ["https://www.googleapis.com/auth/webmasters.readonly"]
+          scopes: [this.config.oauth_scope]
         });
         this.service = google.searchconsole({ version: "v1", auth });
         console.error(`[startup] Service account loaded from: ${this.config.credentials_file}`);
       } else {
-        const resolved = resolveOAuthCredentials();
+        const resolved = resolveOAuthCredentials(this.oauthCredsPath());
         const oauth2Client = new google.auth.OAuth2(
           resolved.client_id,
           resolved.client_secret
@@ -292,8 +327,8 @@ class GscManager {
     }, "gsc_inspection");
   }
 }
-const config = loadConfig();
-const gscManager = new GscManager(config);
+let config;
+let gscManager;
 const server = new Server(
   {
     name: __cliPkg.name,
@@ -415,6 +450,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 async function main() {
+  config = loadConfig();
+  gscManager = new GscManager(config);
   try {
     await gscManager.listSites();
     console.error("[startup] Auth verified: GSC API call succeeded");
@@ -439,5 +476,15 @@ process.on("SIGPIPE", () => {
 process.on("unhandledRejection", (reason) => {
   console.error("[error] Unhandled promise rejection:", reason);
 });
-main().catch(console.error);
+function isEntryPoint() {
+  const entry = process.argv[1] || "";
+  return /(^|[\\/])index(\.[cm]?js)?$/.test(entry) || /[\\/]mcp-gsc$/.test(entry);
+}
+if (isEntryPoint()) {
+  main().catch(console.error);
+}
+export {
+  buildGscManager,
+  resolveRuntimeAuthMode
+};
 //# sourceMappingURL=index.js.map

package/dist/oauthScope.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Minimum scope this MCP needs: READ-ONLY Search Console. All four tools
+ * (list sites, search analytics, URL inspection, client context) are reads;
+ * nothing writes, so we never request `webmasters` (read/write).
+ */
+export declare const DEFAULT_GSC_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
+/** Normalize a comma/space/newline-separated scope list to space-separated. */
+export declare function normalizeScope(raw: string): string;
+/**
+ * Resolve the OAuth scope from an already-parsed config object.
+ * Falls back to DEFAULT_GSC_SCOPE when oauth.scope is absent/empty.
+ */
+export declare function resolveOAuthScope(config: unknown): string;
+/**
+ * Read the OAuth scope from a config file on disk (config.json). Returns the
+ * committed default if the file is missing or unparseable.
+ */
+export declare function loadOAuthScopeFromFile(filePath: string): string;

package/dist/oauthScope.js

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync } from "fs";
+const DEFAULT_GSC_SCOPE = "https://www.googleapis.com/auth/webmasters.readonly";
+function normalizeScope(raw) {
+  return raw.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean).join(" ");
+}
+function resolveOAuthScope(config) {
+  const scope = config && typeof config === "object" && "oauth" in config && config.oauth && typeof config.oauth.scope === "string" ? config.oauth.scope : "";
+  const normalized = normalizeScope(scope);
+  return normalized || DEFAULT_GSC_SCOPE;
+}
+function loadOAuthScopeFromFile(filePath) {
+  if (!existsSync(filePath)) return DEFAULT_GSC_SCOPE;
+  try {
+    return resolveOAuthScope(JSON.parse(readFileSync(filePath, "utf-8")));
+  } catch {
+    return DEFAULT_GSC_SCOPE;
+  }
+}
+export {
+  DEFAULT_GSC_SCOPE,
+  loadOAuthScopeFromFile,
+  normalizeScope,
+  resolveOAuthScope
+};
+//# sourceMappingURL=oauthScope.js.map

package/dist/pkce.d.ts

@@ -0,0 +1,9 @@
+/** base64url with no padding (RFC 4648 §5). */
+export declare function base64url(buf: Buffer): string;
+/** 43–128 chars of the unreserved set. 32 random bytes -> 43 base64url chars. */
+export declare function generateCodeVerifier(): string;
+/** code_challenge = base64url(SHA256(code_verifier)), S256. */
+export declare function computeCodeChallenge(verifier: string): string;
+export declare const LOOPBACK_HOST = "localhost";
+export declare const LOOPBACK_PATH = "/callback";
+export declare function buildLoopbackRedirectUri(port: number): string;

package/dist/pkce.js

@@ -0,0 +1,24 @@
+import { createHash, randomBytes } from "crypto";
+function base64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier() {
+  return base64url(randomBytes(32));
+}
+function computeCodeChallenge(verifier) {
+  return base64url(createHash("sha256").update(verifier, "ascii").digest());
+}
+const LOOPBACK_HOST = "localhost";
+const LOOPBACK_PATH = "/callback";
+function buildLoopbackRedirectUri(port) {
+  return `http://${LOOPBACK_HOST}:${port}${LOOPBACK_PATH}`;
+}
+export {
+  LOOPBACK_HOST,
+  LOOPBACK_PATH,
+  base64url,
+  buildLoopbackRedirectUri,
+  computeCodeChallenge,
+  generateCodeVerifier
+};
+//# sourceMappingURL=pkce.js.map