webmaster-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webmaster-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# webmaster-mcp
+
+Local-first MCP server for Google Search Console, Bing Webmaster Tools, and Yandex Webmaster. One normalized tool surface, local credential storage, SQLite response cache, and a shared background process through mcponce.
+
+## Requirements
+
+- Node.js 20 or newer
+- An OS credential store (macOS Keychain, Windows Credential Manager, or Linux Secret Service)
+- Provider accounts with access to the sites you want to inspect
+
+Install and run after publication:
+
+```bash
+npx webmaster-mcp auth google
+npx webmaster-mcp auth bing
+npx webmaster-mcp auth yandex
+npx webmaster-mcp auth status
+npx webmaster-mcp sites
+npx webmaster-mcp mcp
+```
+
+For a local checkout:
+
+```bash
+npm install
+npm run build
+node dist/cli/index.js auth status
+node dist/cli/index.js mcp
+```
+
+### MCP Client Configuration
+
+Add `webmaster-mcp` to your preferred AI environment's configuration file:
+
+#### Google Antigravity
+Add to `~/.gemini/config/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace):
+```json
+{
+  "mcpServers": {
+    "webmaster": {
+      "command": "npx",
+      "args": ["-y", "webmaster-mcp", "mcp"]
+    }
+  }
+}
+```
+
+#### Cursor
+Add to `~/.cursor/mcp.json` or `.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "webmaster": {
+      "command": "npx",
+      "args": ["-y", "webmaster-mcp", "mcp"]
+    }
+  }
+}
+```
+
+#### Claude Desktop
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+```json
+{
+  "mcpServers": {
+    "webmaster": {
+      "command": "npx",
+      "args": ["-y", "webmaster-mcp", "mcp"]
+    }
+  }
+}
+```
+
+#### OpenAI Codex CLI
+Add via CLI or edit `~/.codex/config.json`:
+```bash
+codex mcp add webmaster -- npx -y webmaster-mcp mcp
+```
+
+`mcponce` automatically starts and reuses one local background instance, so multiple clients safely share the SQLite response cache, rate limits, and authentication state.
+
+## Authentication
+
+### Google
+
+#### Setting Up Google Cloud OAuth 2.0 (Step-by-Step)
+
+1. **Create a Google Cloud Project:**
+   - Go to the [Google Cloud Console](https://console.cloud.google.com/).
+   - Click the project dropdown in the top bar and select **New Project**.
+   - Enter a project name (e.g., `Webmaster-MCP`) and click **Create**.
+   - Select your newly created project from the top dropdown.
+
+2. **Enable Google Search Console API:**
+   - Navigate to **APIs & Services** > **Library** in the left navigation menu.
+   - Search for **Google Search Console API**.
+   - Click on it and select **Enable**.
+
+3. **Configure OAuth Consent Screen:**
+   - Go to **APIs & Services** > **OAuth consent screen**.
+   - **User Type Selection:**
+     - **Recommended for Google Workspace / Organization accounts:** Choose **Internal**. This skips app verification, requires no test user management, and grants immediate access to any user in your domain.
+     - **For personal `@gmail.com` accounts:** Choose **External** (Google only allows External for standard Gmail).
+   - Enter the required application details:
+     - **App name:** `Webmaster MCP`
+     - **User support email:** Your email address.
+     - **Developer contact information:** Your email address.
+   - Click **Save and Continue**.
+   - In the **Scopes** step, click **Add or Remove Scopes**, search for `webmasters`, select `.../auth/webmasters.readonly` (and optionally `.../auth/webmasters` if you need write scope), then click **Update** and **Save and Continue**.
+   - In the **Test users** step *(CRITICAL for External mode)*:
+     - Click **+ Add Users** and add your Google account email address.
+     - *(Note: If this step is omitted on External/Testing apps, Google blocks login with `Error 403: access_denied`).*
+     - Click **Save and Continue**.
+
+4. **Create Desktop OAuth Client Credentials:**
+   - Go to **APIs & Services** > **Credentials**.
+   - Click **+ Create Credentials** at the top and select **OAuth client ID**.
+   - For **Application type**, choose **Desktop app** (*Desktop application types automatically support dynamic loopback redirect URIs like `http://127.0.0.1:<port>/callback` without static URI registration*).
+   - Set a name (e.g., `Webmaster CLI Client`) and click **Create**.
+   - Copy the generated **Client ID** and **Client Secret**.
+
+5. **Set Environment Variables:**
+   - On macOS / Linux (`zsh` / `bash`):
+     ```bash
+     export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+     export GOOGLE_CLIENT_SECRET="your-client-secret"
+     ```
+   - On Windows (PowerShell):
+     ```powershell
+     $env:GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
+     $env:GOOGLE_CLIENT_SECRET="your-client-secret"
+     ```
+
+6. **Authorize via CLI:**
+   - Run:
+     ```bash
+     npx webmaster-mcp auth google
+     # or locally:
+     node dist/cli/index.js auth google
+     ```
+   - The CLI opens your default browser with a PKCE code challenge and starts a local loopback server.
+   - Log in with your authorized Google account. If Google displays "Google hasn't verified this app", click **Advanced** > **Go to Webmaster MCP (unsafe)**.
+   - Once authorized, the refresh token is securely stored in your OS keychain / credential store. The loopback server shuts down immediately. Tokens are refreshed automatically.
+
+The default scope is `webmasters.readonly`. Run `auth google --write` only if you explicitly want the broader `webmasters` scope; this version has no write MCP tools.
+
+### Bing
+
+#### Generating a Bing Webmaster API Key (Step-by-Step)
+
+1. Go to [Bing Webmaster Tools](https://www.bing.com/webmasters) and sign in with your Microsoft/Google account.
+2. In the top-right corner, click the **Settings** gear icon (⚙️).
+3. In the Settings menu, select **API Access** > **API Key**.
+4. Click **Generate API Key** (or copy your existing API key).
+5. Run:
+   ```bash
+   npx webmaster-mcp auth bing
+   # or locally:
+   node dist/cli/index.js auth bing
+   ```
+6. Paste your API key into the hidden terminal prompt. The key is securely saved to your OS keychain / credential store.
+
+Bing's JSON API transmits the key as an HTTPS query parameter as required by that API; this application does not log request URLs or include them in MCP errors.
+
+### Yandex
+
+#### Setting Up Yandex OAuth (Step-by-Step)
+
+1. Go to the [Yandex OAuth App Console](https://oauth.yandex.com/client/new).
+2. Enter an **App name** (e.g., `Webmaster MCP`).
+3. Under **Platforms**, select **Web services** and set the callback URL or use the default verification code flow (`https://oauth.yandex.com/verification_code`).
+4. Under **Data access (Permissions)**, search and add permissions for **Yandex Webmaster** (`webmaster:hostinfo` and `webmaster:verify`).
+5. Save the application and copy your generated **Client ID**.
+6. Set the environment variable:
+   ```bash
+   export YANDEX_CLIENT_ID="your-yandex-client-id"
+   ```
+7. Run:
+   ```bash
+   npx webmaster-mcp auth yandex
+   # or locally:
+   node dist/cli/index.js auth yandex
+   ```
+8. The CLI opens the Yandex authorization page in your browser. Copy the authorization token/code displayed on the page and paste it into the hidden terminal prompt. The token is securely stored in your OS keychain.
+
+### Multi-Account & Credential Management
+
+- **Named Accounts:** Add `--name personal` or `--name work` to any auth command to manage multiple accounts:
+  ```bash
+  npx webmaster-mcp auth google --name agency
+  npx webmaster-mcp auth bing --name client1
+  ```
+- **Check Status:** View all stored accounts and their connection status:
+  ```bash
+  npx webmaster-mcp auth status
+  ```
+- **Disconnect / Logout:** Remove a specific account:
+  ```bash
+  npx webmaster-mcp auth logout google --name agency
+  ```
+- **MCP Tool Selection:** Tools accept an optional `account` parameter. If omitted, connected accounts are queried automatically and one account per engine is selected for each property (preferring `default`).
+
+For development only, environment fallback values can be set as `WEBMASTER_GOOGLE_TOKEN`, `WEBMASTER_BING_TOKEN`, or `WEBMASTER_YANDEX_TOKEN` for the default account, or `WEBMASTER_GOOGLE_PERSONAL` and analogous names for a named account. Google environment access tokens cannot refresh. No credentials are stored in SQLite.
+
+## Tools
+
+`sites`, `performance`, `queries`, `pages`, `sitemaps`, `inspect_url`, `compare_engines`, `opportunities`, and `indexing_gaps`.
+
+For example, call `performance` with:
+
+```json
+{"site":"https://example.com/","from":"2026-08-01","to":"2026-08-28","engines":["google","bing"]}
+```
+
+Tools return `results` plus sanitized `errors` for individual providers. Provider requests run concurrently. The analysis tools use deterministic thresholds and return the metrics supporting each finding. `indexing_gaps` accepts up to 20 `urls`; it reports **verified** differences only when both provider results have a known state. It also reports search visibility gaps, which mean only that a provider returned no performance row, not that a page is unindexed.
+
+## Metric meaning and limits
+
+- `ctr` is a fraction (`0.02` means 2%). It is computed from clicks and impressions when both exist; missing metrics remain absent.
+- Google Search Analytics returns top rows and can omit lower-traffic rows. `performance` groups by day; `queries` and `pages` group by their names. [Google API reference](https://developers.google.com/webmaster-tools/v1/searchanalytics/query)
+- Bing performance is daily. Its query and page statistics are weekly, and its `GetPageStats` uses a field named `Query` to hold the page URL. Bing traffic can include more than web search verticals, so cross-engine totals are directional comparisons. [Bing traffic reference](https://learn.microsoft.com/en-us/dotnet/api/microsoft.bing.webmaster.api.interfaces.iwebmasterapi.getrankandtrafficstats?view=bing-webmaster-dotnet), [page reference](https://learn.microsoft.com/en-us/dotnet/api/microsoft.bing.webmaster.api.interfaces.iwebmasterapi.getpagestats?view=bing-webmaster-dotnet)
+- Yandex all-query history supports dated site totals. Popular queries support date ranges but return a bounded top set. URL-level query monitoring covers only the last two weeks, so longer `pages` requests return an `UNSUPPORTED` error for Yandex. [Yandex history](https://yandex.com/dev/webmaster/doc/en/reference/host-search-queries-history-all), [URL monitoring](https://yandex.ru/dev/webmaster/doc/ru/reference/host-query-analytics)
+- Google URL inspection checks the version in Google's index. Yandex inspection can verify only URLs already present in Important Page Monitoring; other URLs return `unknown`. Bing URL information does not establish an indexing verdict, so the Bing adapter does not claim URL inspection support. [Google inspection](https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect), [Yandex important pages](https://yandex.com/dev/webmaster/doc/en/reference/host-id-important-urls)
+
+No cross-engine position equivalence is assumed. Missing rows and `unknown` inspection states are never interpreted as proof of non-indexing.
+
+## Development
+
+```bash
+npm run build
+npm test
+```
+
+`src/core` contains the provider-independent model, credential interface, cache, service, scheduler, and pure analysis functions. Each adapter lives under `src/providers`. The `src/mcp` layer contains only tool definitions and mcponce integration. Provider HTTP calls accept an injected `fetch` for offline tests.
+
+Set `MCP_BACKGROUND=0` to run one foreground MCP process for local debugging. Normal runs use mcponce's shared background mode.
+
+SQLite defaults to the OS user cache/application-data directory. Override it with `WEBMASTER_MCP_DATA_DIR` for tests or isolated local use. History responses are cached for six hours, site lists for one hour, sitemaps for 30 minutes, and URL inspection for five minutes. Authentication failures are never cached.

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { createContext } from '../server/context.js';
+import { GoogleProvider } from '../providers/google/index.js';
+import { BingProvider } from '../providers/bing/index.js';
+import { YandexProvider } from '../providers/yandex/index.js';
+import { createServer } from '../mcp/index.js';
+import { WebmasterError } from '../core/errors.js';
+async function main() { const args = process.argv.slice(2); const command = args[0] ?? 'mcp'; if (command === 'mcp' || args.includes('--mcponce-background') || process.env.MCPONCE_BACKGROUND_SERVER === '1') {
+    await createServer().run();
+    return;
+} const { service, store, accounts } = createContext(); const nameIndex = args.indexOf('--name'); const name = nameIndex >= 0 ? args[nameIndex + 1] ?? 'default' : 'default'; if (!/^[A-Za-z0-9_-]{1,40}$/.test(name))
+    throw new Error('Invalid account name.'); if (command === 'sites') {
+    process.stdout.write(`${JSON.stringify(await service.sites(), null, 2)}\n`);
+    return;
+} if (command !== 'auth')
+    throw new Error('Usage: webmaster-mcp [mcp|sites|auth]'); const action = args[1]; if (action === 'status') {
+    for (const engine of ['google', 'bing', 'yandex'])
+        for (const account of accounts.names(engine)) {
+            const connected = !!await store.get(engine, account);
+            process.stdout.write(`${engine.padEnd(7)} ${account.padEnd(12)} ${connected ? '✓ connected' : '✗ not connected'}\n`);
+        }
+    return;
+} if (action === 'logout') {
+    const engine = args[2];
+    if (!['google', 'bing', 'yandex'].includes(engine))
+        throw new Error('Choose google, bing, or yandex.');
+    await accounts.remove(engine, name);
+    process.stdout.write(`${engine}/${name} disconnected.\n`);
+    return;
+} if (action === 'google') {
+    await new GoogleProvider(store, name, fetch, args.includes('--write')).authenticate();
+    accounts.add('google', name);
+}
+else if (action === 'bing') {
+    await new BingProvider(store, name).authenticate();
+    accounts.add('bing', name);
+}
+else if (action === 'yandex') {
+    await new YandexProvider(store, name).authenticate();
+    accounts.add('yandex', name);
+}
+else
+    throw new Error('Usage: webmaster-mcp auth [google|bing|yandex|status|logout]'); process.stdout.write(`${action}/${name} connected.\n`); }
+main().catch(error => { if (error instanceof WebmasterError) {
+    process.stderr.write(`${error.code}: ${error.message}\n`);
+}
+else {
+    process.stderr.write(`ERROR: ${error instanceof Error ? error.message : String(error)}\n`);
+} process.exitCode = 1; });

package/dist/core/analysis/index.d.ts

@@ -0,0 +1,43 @@
+import type { Engine, SearchMetric, UrlInspection } from '../types/index.js';
+export interface Opportunity {
+    kind: 'low_ctr' | 'near_first_page' | 'declining_page' | 'declining_query' | 'impression_growth_without_clicks';
+    metric: SearchMetric;
+    previous?: SearchMetric;
+    reason: string;
+}
+export declare function findCtrOpportunities(rows: SearchMetric[], config?: {
+    minImpressions: number;
+    maxCtr: number;
+}): Opportunity[];
+export declare function findNearFirstPage(rows: SearchMetric[], config?: {
+    minImpressions: number;
+    minPosition: number;
+    maxPosition: number;
+}): Opportunity[];
+export declare function findDecliningPages(current: SearchMetric[], previous: SearchMetric[], fraction?: number): Opportunity[];
+export declare function findDecliningQueries(current: SearchMetric[], previous: SearchMetric[], fraction?: number): Opportunity[];
+export declare function findImpressionGrowthWithoutClicks(current: SearchMetric[], previous: SearchMetric[], config?: {
+    minGrowth: number;
+    maxClickGrowth: number;
+}): Opportunity[];
+export declare function compareEngines(rows: SearchMetric[]): {
+    engine: Engine;
+    site: string;
+    clicks: number | undefined;
+    impressions: number | undefined;
+    ctr: number | undefined;
+    position: number | undefined;
+    semantics: string;
+}[];
+export declare function findEngineGaps(rows: SearchMetric[], engines: Engine[], minImpressions?: number): {
+    page: string;
+    visibleIn: Engine[];
+    absentFromResults: Engine[];
+    interpretation: string;
+}[];
+export declare function findIndexingGaps(inspections: UrlInspection[]): {
+    url: string;
+    indexed: Engine[];
+    notIndexed: Engine[];
+    evidence: UrlInspection[];
+}[];

package/dist/core/analysis/index.js

@@ -0,0 +1,14 @@
+import { aggregate } from '../normalize/index.js';
+export function findCtrOpportunities(rows, config = { minImpressions: 100, maxCtr: 0.02 }) { return rows.filter(r => (r.impressions ?? 0) >= config.minImpressions && r.ctr !== undefined && r.ctr <= config.maxCtr).map(metric => ({ kind: 'low_ctr', metric, reason: `${metric.impressions} impressions with ${(metric.ctr * 100).toFixed(2)}% CTR` })); }
+export function findNearFirstPage(rows, config = { minImpressions: 50, minPosition: 8, maxPosition: 20 }) { return rows.filter(r => (r.impressions ?? 0) >= config.minImpressions && r.position !== undefined && r.position >= config.minPosition && r.position <= config.maxPosition).map(metric => ({ kind: 'near_first_page', metric, reason: `Average position ${metric.position.toFixed(1)} with ${metric.impressions} impressions` })); }
+function declines(current, previous, key, fraction) { const older = new Map(aggregate(previous, key).map(r => [`${r.engine}\0${r.site}\0${r[key]}`, r])); return aggregate(current, key).flatMap(metric => { const before = older.get(`${metric.engine}\0${metric.site}\0${metric[key]}`); if (!before || !before.clicks || metric.clicks === undefined || metric.clicks > before.clicks * (1 - fraction))
+    return []; return [{ kind: key === 'page' ? 'declining_page' : 'declining_query', metric, previous: before, reason: `Clicks fell from ${before.clicks} to ${metric.clicks}` }]; }); }
+export function findDecliningPages(current, previous, fraction = 0.2) { return declines(current, previous, 'page', fraction); }
+export function findDecliningQueries(current, previous, fraction = 0.2) { return declines(current, previous, 'query', fraction); }
+export function findImpressionGrowthWithoutClicks(current, previous, config = { minGrowth: 0.3, maxClickGrowth: 0.05 }) { const older = new Map(aggregate(previous, 'query').map(r => [`${r.engine}\0${r.site}\0${r.query}`, r])); return aggregate(current, 'query').flatMap(metric => { const before = older.get(`${metric.engine}\0${metric.site}\0${metric.query}`); if (!before?.impressions || metric.impressions === undefined || metric.impressions < before.impressions * (1 + config.minGrowth) || (metric.clicks ?? 0) > (before.clicks ?? 0) * (1 + config.maxClickGrowth))
+    return []; return [{ kind: 'impression_growth_without_clicks', metric, previous: before, reason: `Impressions grew from ${before.impressions} to ${metric.impressions} while clicks stayed near ${before.clicks ?? 0}` }]; }); }
+export function compareEngines(rows) { return aggregate(rows, 'engine').map(r => ({ engine: r.engine, site: r.site, clicks: r.clicks, impressions: r.impressions, ctr: r.ctr, position: r.position, semantics: 'Provider reported metrics; counting, position, and data freshness can differ.' })); }
+export function findEngineGaps(rows, engines, minImpressions = 1) { const byPage = new Map(); for (const r of aggregate(rows.filter(x => !!x.page), 'page'))
+    byPage.set(r.page, [...(byPage.get(r.page) ?? []), r]); return [...byPage].flatMap(([page, found]) => { const visible = found.filter(r => (r.impressions ?? 0) >= minImpressions).map(r => r.engine); const absent = engines.filter(e => !found.some(r => r.engine === e)); return visible.length && absent.length ? [{ page, visibleIn: visible, absentFromResults: absent, interpretation: 'No row returned for this engine; this does not prove the URL is not indexed.' }] : []; }); }
+export function findIndexingGaps(inspections) { const byUrl = new Map(); for (const i of inspections)
+    byUrl.set(i.url, [...(byUrl.get(i.url) ?? []), i]); return [...byUrl].flatMap(([url, items]) => { const indexed = items.filter(i => i.state === 'indexed').map(i => i.engine); const notIndexed = items.filter(i => i.state === 'not_indexed').map(i => i.engine); return indexed.length && notIndexed.length ? [{ url, indexed, notIndexed, evidence: items }] : []; }); }

package/dist/core/auth/accounts.d.ts

@@ -0,0 +1,11 @@
+import type { Engine } from '../types/index.js';
+import type { CredentialStore } from './store.js';
+import type { Cache } from '../cache/index.js';
+export declare class AccountRegistry {
+    private cache;
+    private store;
+    constructor(cache: Cache, store: CredentialStore);
+    names(engine: Engine): string[];
+    add(engine: Engine, account: string): void;
+    remove(engine: Engine, account: string): Promise<void>;
+}

package/dist/core/auth/accounts.js

@@ -0,0 +1,12 @@
+export class AccountRegistry {
+    cache;
+    store;
+    constructor(cache, store) {
+        this.cache = cache;
+        this.store = store;
+    }
+    names(engine) { const rows = this.cache.db.prepare('SELECT account FROM accounts WHERE provider=? ORDER BY account').all(engine); const names = rows.map(r => r.account); if (!names.includes('default'))
+        names.unshift('default'); return names; }
+    add(engine, account) { this.cache.db.prepare('INSERT OR IGNORE INTO accounts(provider,account) VALUES (?,?)').run(engine, account); }
+    async remove(engine, account) { await this.store.delete(engine, account); this.cache.db.prepare('DELETE FROM accounts WHERE provider=? AND account=?').run(engine, account); }
+}

package/dist/core/auth/prompt.d.ts

@@ -0,0 +1 @@
+export declare function secretPrompt(label: string): Promise<string>;

package/dist/core/auth/prompt.js

@@ -0,0 +1,4 @@
+import { createInterface } from 'node:readline';
+import { Writable } from 'node:stream';
+export async function secretPrompt(label) { if (!process.stdin.isTTY)
+    throw new Error('Interactive terminal required.'); process.stderr.write(label); const output = new Writable({ write(_chunk, _encoding, callback) { callback(); } }); const rl = createInterface({ input: process.stdin, output, terminal: true }); return new Promise(resolve => rl.question('', answer => { rl.close(); process.stderr.write('\n'); resolve(answer.trim()); })); }

package/dist/core/auth/store.d.ts

@@ -0,0 +1,11 @@
+export interface CredentialStore {
+    get(provider: string, account?: string): Promise<unknown | null>;
+    set(provider: string, account: string, credentials: unknown): Promise<void>;
+    delete(provider: string, account: string): Promise<void>;
+}
+export declare class KeychainCredentialStore implements CredentialStore {
+    private entry;
+    get(provider: string, account?: string): Promise<unknown | null>;
+    set(provider: string, account: string, credentials: unknown): Promise<void>;
+    delete(provider: string, account: string): Promise<void>;
+}

package/dist/core/auth/store.js

@@ -0,0 +1,22 @@
+import { Entry } from '@napi-rs/keyring';
+export class KeychainCredentialStore {
+    entry(provider, account) { return new Entry('webmaster-mcp', `${provider}/${account}`); }
+    async get(provider, account = 'default') { const env = process.env[`WEBMASTER_${provider.toUpperCase()}_${account.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`] ?? (account === 'default' ? process.env[`WEBMASTER_${provider.toUpperCase()}_TOKEN`] : undefined); if (env)
+        return provider === 'bing' ? { apiKey: env } : { accessToken: env }; try {
+        const value = this.entry(provider, account).getPassword();
+        return value ? JSON.parse(value) : null;
+    }
+    catch (e) {
+        if (String(e).toLowerCase().includes('no entry'))
+            return null;
+        throw new Error('OS credential store unavailable. Configure a desktop keyring or use a development environment variable.');
+    } }
+    async set(provider, account, credentials) { this.entry(provider, account).setPassword(JSON.stringify(credentials)); }
+    async delete(provider, account) { try {
+        this.entry(provider, account).deletePassword();
+    }
+    catch (e) {
+        if (!String(e).toLowerCase().includes('no entry'))
+            throw e;
+    } }
+}

package/dist/core/cache/index.d.ts

@@ -0,0 +1,11 @@
+import Database from 'better-sqlite3';
+import type { Engine } from '../types/index.js';
+export declare function defaultDataPath(): string;
+export declare function cacheKey(provider: Engine, account: string, site: string, operation: string, params: unknown): string;
+export declare class Cache {
+    readonly db: Database.Database;
+    constructor(path?: string);
+    get<T>(key: string): T | null;
+    set(key: string, value: unknown, ttlMs: number): void;
+    close(): void;
+}

package/dist/core/cache/index.js

@@ -0,0 +1,21 @@
+import Database from 'better-sqlite3';
+import { createHash } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+export function defaultDataPath() { if (process.env.WEBMASTER_MCP_DATA_DIR)
+    return `${process.env.WEBMASTER_MCP_DATA_DIR}/cache.db`; if (process.platform === 'darwin')
+    return `${homedir()}/Library/Application Support/webmaster-mcp/cache.db`; if (process.platform === 'win32')
+    return `${process.env.LOCALAPPDATA ?? homedir()}/webmaster-mcp/cache.db`; return `${process.env.XDG_CACHE_HOME ?? `${homedir()}/.cache`}/webmaster-mcp/cache.db`; }
+function stable(value) { if (Array.isArray(value))
+    return value.map(stable); if (value && typeof value === 'object')
+    return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)])); return value; }
+export function cacheKey(provider, account, site, operation, params) { return createHash('sha256').update(JSON.stringify(stable({ provider, account, site, operation, params }))).digest('hex'); }
+export class Cache {
+    db;
+    constructor(path = defaultDataPath()) { if (path !== ':memory:')
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); this.db = new Database(path); this.db.pragma('busy_timeout = 5000'); this.db.pragma('journal_mode = WAL'); this.db.exec('CREATE TABLE IF NOT EXISTS accounts(provider TEXT NOT NULL,account TEXT NOT NULL,PRIMARY KEY(provider,account)); CREATE TABLE IF NOT EXISTS cache(key TEXT PRIMARY KEY,value TEXT NOT NULL,expires INTEGER NOT NULL)'); }
+    get(key) { const row = this.db.prepare('SELECT value FROM cache WHERE key=? AND expires>?').get(key, Date.now()); return row ? JSON.parse(row.value) : null; }
+    set(key, value, ttlMs) { this.db.prepare('INSERT INTO cache(key,value,expires) VALUES (?,?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value,expires=excluded.expires').run(key, JSON.stringify(value), Date.now() + ttlMs); }
+    close() { this.db.close(); }
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,9 @@
+import type { Engine, ProviderError } from './types/index.js';
+export declare class WebmasterError extends Error {
+    code: ProviderError['code'];
+    status?: number | undefined;
+    constructor(code: ProviderError['code'], message: string, status?: number | undefined);
+}
+export declare function normalizeError(engine: Engine, account: string, error: unknown): ProviderError;
+export declare function httpError(status: number): WebmasterError;
+export declare function redact(value: string): string;

package/dist/core/errors.js

@@ -0,0 +1,24 @@
+export class WebmasterError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export function normalizeError(engine, account, error) {
+    if (error instanceof WebmasterError)
+        return { engine, account, code: error.code, message: error.message };
+    return { engine, account, code: 'UPSTREAM_ERROR', message: 'Provider request failed. Check provider status and local configuration.' };
+}
+export function httpError(status) {
+    if (status === 401)
+        return new WebmasterError('AUTH_FAILED', 'Credentials were rejected or expired.', status);
+    if (status === 403)
+        return new WebmasterError('PERMISSION_DENIED', 'This account lacks access to the requested property.', status);
+    if (status === 429)
+        return new WebmasterError('RATE_LIMITED', 'Provider rate limit reached.', status);
+    return new WebmasterError('UPSTREAM_ERROR', `Provider returned HTTP ${status}.`, status);
+}
+export function redact(value) { return value.replace(/(Bearer|OAuth|apikey=|access_token=|refresh_token=)\s*[^\s&"']+/gi, '$1 [REDACTED]'); }

package/dist/core/normalize/index.d.ts

@@ -0,0 +1,4 @@
+import type { SearchMetric } from '../types/index.js';
+export declare function finite(value: unknown): number | undefined;
+export declare function metric(input: SearchMetric): SearchMetric;
+export declare function aggregate(rows: SearchMetric[], key: 'engine' | 'page' | 'query'): SearchMetric[];

package/dist/core/normalize/index.js

@@ -0,0 +1,15 @@
+export function finite(value) { const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN; return Number.isFinite(n) ? n : undefined; }
+export function metric(input) {
+    const clicks = finite(input.clicks), impressions = finite(input.impressions);
+    const ctr = finite(input.ctr) ?? (clicks !== undefined && impressions !== undefined && impressions > 0 ? clicks / impressions : undefined);
+    return { ...input, clicks, impressions, ctr, position: finite(input.position) };
+}
+export function aggregate(rows, key) {
+    const groups = new Map();
+    for (const row of rows) {
+        const value = String(row[key] ?? '');
+        const id = `${row.engine}\0${row.site}\0${value}`;
+        groups.set(id, [...(groups.get(id) ?? []), row]);
+    }
+    return [...groups.values()].map(group => { const first = group[0]; const clicks = group.some(r => r.clicks !== undefined) ? group.reduce((n, r) => n + (r.clicks ?? 0), 0) : undefined; const impressions = group.some(r => r.impressions !== undefined) ? group.reduce((n, r) => n + (r.impressions ?? 0), 0) : undefined; const positions = group.filter(r => r.position !== undefined); const weight = positions.reduce((n, r) => n + (r.impressions ?? 1), 0); return metric({ engine: first.engine, site: first.site, account: first.account, [key]: first[key], clicks, impressions, position: weight ? positions.reduce((n, r) => n + r.position * (r.impressions ?? 1), 0) / weight : undefined }); });
+}

package/dist/core/scheduler.d.ts

@@ -0,0 +1,18 @@
+import type { Engine } from './types/index.js';
+export interface SchedulerPolicy {
+    concurrency: number;
+    minimumDelay: number;
+    retries: number;
+}
+export declare class RequestScheduler {
+    private policy;
+    private active;
+    private next;
+    private queue;
+    constructor(policy: SchedulerPolicy);
+    private slot;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
+export declare const schedules: Record<Engine, SchedulerPolicy>;
+export declare function providerScheduler(engine: Engine): RequestScheduler;
+export declare function jsonFetch(fetcher: typeof fetch, url: string, options?: RequestInit): Promise<any>;

package/dist/core/scheduler.js

@@ -0,0 +1,52 @@
+import { httpError, WebmasterError } from './errors.js';
+export class RequestScheduler {
+    policy;
+    active = 0;
+    next = 0;
+    queue = [];
+    constructor(policy) {
+        this.policy = policy;
+    }
+    async slot() { if (this.active >= this.policy.concurrency)
+        await new Promise(resolve => this.queue.push(resolve));
+    else
+        this.active++; const delay = Math.max(0, this.next - Date.now()); this.next = Math.max(Date.now(), this.next) + this.policy.minimumDelay; if (delay)
+        await new Promise(r => setTimeout(r, delay)); return () => { const next = this.queue.shift(); if (next)
+        next();
+    else
+        this.active--; }; }
+    async run(fn) { const release = await this.slot(); try {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (e) {
+                const retryable = e instanceof WebmasterError ? e.code === 'RATE_LIMITED' || e.code === 'NETWORK_ERROR' || (e.status !== undefined && e.status >= 500) : e instanceof TypeError;
+                if (!retryable || attempt >= this.policy.retries)
+                    throw e;
+                await new Promise(r => setTimeout(r, Math.min(5000, 250 * 2 ** attempt + Math.random() * 100)));
+            }
+        }
+    }
+    finally {
+        release();
+    } }
+}
+export const schedules = { google: { concurrency: 3, minimumDelay: 100, retries: 2 }, bing: { concurrency: 2, minimumDelay: 250, retries: 2 }, yandex: { concurrency: 2, minimumDelay: 200, retries: 2 } };
+const shared = new Map();
+export function providerScheduler(engine) { let scheduler = shared.get(engine); if (!scheduler) {
+    scheduler = new RequestScheduler(schedules[engine]);
+    shared.set(engine, scheduler);
+} return scheduler; }
+export async function jsonFetch(fetcher, url, options = {}) { let response; try {
+    response = await fetcher(url, { ...options, signal: options.signal ?? AbortSignal.timeout(15000) });
+}
+catch {
+    throw new WebmasterError('NETWORK_ERROR', 'Provider network request failed.');
+} if (!response.ok)
+    throw httpError(response.status); try {
+    return await response.json();
+}
+catch {
+    throw new WebmasterError('UPSTREAM_ERROR', 'Provider returned invalid JSON.');
+} }

package/dist/core/service.d.ts

@@ -0,0 +1,30 @@
+import type { Capability, Engine, PartialResult, PerformanceQuery, SearchMetric, UrlInspection, WebmasterProvider } from './types/index.js';
+import { Cache } from './cache/index.js';
+export declare class WebmasterService {
+    readonly providers: WebmasterProvider[];
+    readonly cache: Cache;
+    private providerFactory?;
+    constructor(providers: WebmasterProvider[], cache: Cache, providerFactory?: (() => WebmasterProvider[]) | undefined);
+    private selected;
+    private oneAccount;
+    collect<T>(capability: Capability, fn: (p: WebmasterProvider) => Promise<T[]>, engines?: Engine[], account?: string): Promise<PartialResult<T>>;
+    sites(): Promise<{
+        results: {
+            site: string;
+            engines: Engine[];
+            accounts: Partial<Record<Engine, string[]>>;
+        }[];
+        errors: import("./types/index.js").ProviderError[];
+    }>;
+    private cached;
+    metrics(operation: 'performance' | 'queries' | 'pages', input: PerformanceQuery, engines?: Engine[]): Promise<PartialResult<SearchMetric>>;
+    sitemaps(site: string, engines?: Engine[], account?: string): Promise<PartialResult<{
+        engine: Engine;
+        url: string;
+        submitted?: string;
+        status?: string;
+        site: string;
+        account: string;
+    }>>;
+    inspect(site: string, url: string, engines?: Engine[], account?: string): Promise<PartialResult<UrlInspection>>;
+}