webmaster-mcp 0.1.0

package/dist/core/service.js

@@ -0,0 +1,48 @@
+import { normalizeError, WebmasterError } from './errors.js';
+import { validateSite, validateUrl, canonicalSite, range } from './validation.js';
+import { cacheKey } from './cache/index.js';
+export class WebmasterService {
+    providers;
+    cache;
+    providerFactory;
+    constructor(providers, cache, providerFactory) {
+        this.providers = providers;
+        this.cache = cache;
+        this.providerFactory = providerFactory;
+    }
+    selected(engines, account) { return this.providers.filter(p => (!engines || engines.includes(p.id)) && (!account || p.account === account)); }
+    oneAccount(rows, account) { if (account)
+        return rows; const chosen = new Map(); for (const row of rows) {
+        const current = chosen.get(row.engine);
+        if (!current || row.account === 'default')
+            chosen.set(row.engine, row.account ?? 'default');
+    } return rows.filter(row => (row.account ?? 'default') === chosen.get(row.engine)); }
+    async collect(capability, fn, engines, account) { if (this.providerFactory)
+        this.providers.splice(0, this.providers.length, ...this.providerFactory()); const selected = this.selected(engines, account); const settled = await Promise.allSettled(selected.map(async (p) => { if (!p.supports(capability))
+        throw new Error('UNSUPPORTED'); if (!await p.isAuthenticated()) {
+        if (engines?.includes(p.id) || account)
+            throw new WebmasterError('AUTH_FAILED', `${p.id}/${p.account} is not connected.`);
+        return [];
+    } return fn(p); })); const results = [], errors = []; settled.forEach((item, i) => { const p = selected[i]; if (item.status === 'fulfilled')
+        results.push(...item.value);
+    else
+        errors.push(item.reason?.message === 'UNSUPPORTED' ? { engine: p.id, account: p.account, code: 'UNSUPPORTED', message: `${capability} is not supported by ${p.id}.` } : normalizeError(p.id, p.account, item.reason)); }); return { results, errors }; }
+    async sites() { const data = await this.collect('sites', p => this.cached(p, '', 'sites', {}, 3600000, () => p.getSites())); const grouped = new Map(); for (const s of data.results) {
+        const id = canonicalSite(s.site);
+        const entry = grouped.get(id) ?? { site: id, engines: [], accounts: {} };
+        if (!entry.engines.includes(s.engine))
+            entry.engines.push(s.engine);
+        entry.accounts[s.engine] = [...(entry.accounts[s.engine] ?? []), s.account];
+        grouped.set(id, entry);
+    } return { results: [...grouped.values()], errors: data.errors }; }
+    async cached(p, site, operation, params, ttl, load) { const key = cacheKey(p.id, p.account, site, operation, params); const hit = this.cache.get(key); if (hit !== null)
+        return hit; const value = await load(); this.cache.set(key, value, ttl); return value; }
+    async metrics(operation, input, engines) { range.parse(input); validateSite(input.site); const id = canonicalSite(input.site); const data = await this.collect(operation, async (p) => { const sites = await this.cached(p, '', 'sites', {}, 3600000, () => p.getSites()); const owned = sites.find(s => canonicalSite(s.site) === id); if (!owned)
+        throw new WebmasterError('PERMISSION_DENIED', 'Site is not available in this account.'); const providerInput = { ...input, site: owned.site }; const rows = await this.cached(p, owned.site, operation, providerInput, 21600000, () => p[operation === 'performance' ? 'getPerformance' : operation === 'pages' ? 'getPages' : 'getQueries'](providerInput)); return rows.map(row => ({ ...row, site: id })); }, engines, input.account); data.results = this.oneAccount(data.results, input.account); if (input.sort)
+        data.results.sort((a, b) => (b[input.sort] ?? 0) - (a[input.sort] ?? 0)); if (input.limit)
+        data.results = data.results.slice(0, input.limit); return data; }
+    async sitemaps(site, engines, account) { validateSite(site); const id = canonicalSite(site); const data = await this.collect('sitemaps', async (p) => { const sites = await p.getSites(); const owned = sites.find(s => canonicalSite(s.site) === id); if (!owned)
+        throw new WebmasterError('PERMISSION_DENIED', 'Site is not available in this account.'); const rows = await this.cached(p, owned.site, 'sitemaps', {}, 1800000, () => p.getSitemaps(owned.site)); return rows.map(row => ({ ...row, site: id, account: p.account })); }, engines, account); data.results = this.oneAccount(data.results, account); return data; }
+    async inspect(site, url, engines, account) { validateUrl(site, url); const id = canonicalSite(site); const data = await this.collect('urlInspection', async (p) => { const sites = await p.getSites(); const owned = sites.find(s => canonicalSite(s.site) === id); if (!owned)
+        throw new WebmasterError('PERMISSION_DENIED', 'Site is not available in this account.'); const row = await this.cached(p, owned.site, 'inspect_url', { url }, 300000, () => p.inspectUrl(owned.site, url)); return [{ ...row, site: id, account: p.account }]; }, engines, account); data.results = this.oneAccount(data.results, account); return data; }
+}

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

@@ -0,0 +1,73 @@
+export type Engine = 'google' | 'bing' | 'yandex';
+export type Capability = 'sites' | 'performance' | 'queries' | 'pages' | 'sitemaps' | 'urlInspection' | 'urlSubmission' | 'indexing';
+export interface Site {
+    site: string;
+    engine: Engine;
+    account: string;
+    permission?: string;
+}
+export interface SearchMetric {
+    engine: Engine;
+    site: string;
+    account?: string;
+    query?: string;
+    page?: string;
+    country?: string;
+    device?: string;
+    date?: string;
+    clicks?: number;
+    impressions?: number;
+    ctr?: number;
+    position?: number;
+}
+export interface PerformanceQuery {
+    site: string;
+    from: string;
+    to: string;
+    account?: string;
+    limit?: number;
+    sort?: 'clicks' | 'impressions' | 'ctr' | 'position';
+}
+export interface Sitemap {
+    engine: Engine;
+    site: string;
+    url: string;
+    account?: string;
+    submitted?: string;
+    status?: string;
+}
+export type IndexState = 'indexed' | 'not_indexed' | 'unknown';
+export interface UrlInspection {
+    engine: Engine;
+    site: string;
+    url: string;
+    account?: string;
+    state: IndexState;
+    reason?: string;
+    inspectedAt?: string;
+}
+export interface ProviderError {
+    engine: Engine;
+    account: string;
+    code: 'AUTH_FAILED' | 'PERMISSION_DENIED' | 'RATE_LIMITED' | 'UNSUPPORTED' | 'INVALID_INPUT' | 'UPSTREAM_ERROR' | 'NETWORK_ERROR';
+    message: string;
+}
+export interface PartialResult<T> {
+    results: T[];
+    errors: ProviderError[];
+    warnings?: string[];
+}
+export interface WebmasterProvider {
+    readonly id: Engine;
+    readonly account: string;
+    supports(capability: Capability): boolean;
+    authenticate(): Promise<void>;
+    isAuthenticated(): Promise<boolean>;
+    getSites(): Promise<Site[]>;
+    getPerformance(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getPages(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getQueries(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getSitemaps?(site: string): Promise<Sitemap[]>;
+    inspectUrl?(site: string, url: string): Promise<UrlInspection>;
+    submitUrl?(site: string, url: string): Promise<void>;
+}

package/dist/core/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/core/validation.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const date: z.ZodISODate;
+export declare const range: z.ZodObject<{
+    site: z.ZodString;
+    from: z.ZodISODate;
+    to: z.ZodISODate;
+    account: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    sort: z.ZodOptional<z.ZodEnum<{
+        clicks: "clicks";
+        ctr: "ctr";
+        impressions: "impressions";
+        position: "position";
+    }>>;
+}, z.core.$strip>;
+export declare function validateSite(site: string): string;
+export declare function canonicalSite(site: string): string;
+export declare function validateUrl(site: string, url: string): string;

package/dist/core/validation.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { WebmasterError } from './errors.js';
+export const date = z.iso.date();
+export const range = z.object({ site: z.string().min(1), from: date, to: date, account: z.string().optional(), limit: z.number().int().min(1).max(25000).optional(), sort: z.enum(['clicks', 'impressions', 'ctr', 'position']).optional() }).refine(x => x.from <= x.to, 'from must be before to');
+export function validateSite(site) { if (/^sc-domain:[a-z0-9.-]+$/i.test(site))
+    return site; try {
+    const u = new URL(site);
+    if (!['http:', 'https:'].includes(u.protocol) || !u.hostname || u.username || u.password || u.hash)
+        throw new Error();
+    return site;
+}
+catch {
+    throw new WebmasterError('INVALID_INPUT', 'Site must be an HTTP(S) property URL or sc-domain property.');
+} }
+export function canonicalSite(site) { validateSite(site); if (site.startsWith('sc-domain:'))
+    return site.toLowerCase(); const u = new URL(site); u.hash = ''; return u.href; }
+export function validateUrl(site, url) { validateSite(site); try {
+    const target = new URL(url);
+    if (!['http:', 'https:'].includes(target.protocol) || target.username || target.password || target.hash)
+        throw new Error();
+    if (site.startsWith('sc-domain:')) {
+        const domain = site.slice(10);
+        if (target.hostname !== domain && !target.hostname.endsWith(`.${domain}`))
+            throw new Error();
+    }
+    else {
+        const property = new URL(site);
+        if (target.origin !== property.origin || !target.pathname.startsWith(property.pathname))
+            throw new Error();
+    }
+    return target.href;
+}
+catch {
+    throw new WebmasterError('INVALID_INPUT', 'URL must be HTTP(S) and belong to the selected site.');
+} }

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './core/types/index.js';
+export * from './core/analysis/index.js';
+export * from './core/service.js';
+export * from './core/cache/index.js';
+export * from './core/auth/store.js';
+export { GoogleProvider } from './providers/google/index.js';
+export { BingProvider } from './providers/bing/index.js';
+export { YandexProvider } from './providers/yandex/index.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from './core/types/index.js';
+export * from './core/analysis/index.js';
+export * from './core/service.js';
+export * from './core/cache/index.js';
+export * from './core/auth/store.js';
+export { GoogleProvider } from './providers/google/index.js';
+export { BingProvider } from './providers/bing/index.js';
+export { YandexProvider } from './providers/yandex/index.js';

package/dist/mcp/index.d.ts

@@ -0,0 +1 @@
+export declare function createServer(): import("mcponce").McpApp<unknown>;

package/dist/mcp/index.js

@@ -0,0 +1,4 @@
+import { createMcpServer } from 'mcponce';
+import { createContext } from '../server/context.js';
+import { registerTools } from './tools/index.js';
+export function createServer() { const { service } = createContext(); const app = createMcpServer({ name: 'webmaster-mcp', version: '0.1.0', background: process.env.MCP_BACKGROUND !== '0', coerceInputs: true, dataDir: process.env.WEBMASTER_MCP_DATA_DIR }); registerTools(app, service); return app; }

package/dist/mcp/tools/index.d.ts

@@ -0,0 +1,2 @@
+import type { WebmasterService } from '../../core/service.js';
+export declare function registerTools(app: any, service: WebmasterService): void;

package/dist/mcp/tools/index.js

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import { compareEngines, findCtrOpportunities, findNearFirstPage, findDecliningPages, findDecliningQueries, findImpressionGrowthWithoutClicks, findEngineGaps, findIndexingGaps } from '../../core/analysis/index.js';
+const engines = z.array(z.enum(['google', 'bing', 'yandex'])).optional();
+const base = { site: z.string(), from: z.iso.date(), to: z.iso.date(), engines, account: z.string().optional() };
+function previousRange(from, to) { const days = (Date.parse(to) - Date.parse(from)) / 86400000 + 1; const end = new Date(Date.parse(from) - 86400000); const start = new Date(end.getTime() - (days - 1) * 86400000); return { from: start.toISOString().slice(0, 10), to: end.toISOString().slice(0, 10) }; }
+export function registerTools(app, service) {
+    app.tool({ name: 'sites', description: 'List normalized sites across connected webmaster accounts.', handler: () => service.sites() });
+    for (const operation of ['performance', 'queries', 'pages'])
+        app.tool({ name: operation, description: `Get normalized ${operation} metrics with partial provider errors.`, inputSchema: z.object({ ...base, limit: z.number().int().min(1).max(25000).optional(), sort: z.enum(['clicks', 'impressions', 'ctr', 'position']).optional() }), handler: (a) => service.metrics(operation, a, a.engines) });
+    app.tool({ name: 'sitemaps', description: 'List submitted sitemaps for a verified site.', inputSchema: z.object({ site: z.string(), engines, account: z.string().optional() }), handler: (a) => service.sitemaps(a.site, a.engines, a.account) });
+    app.tool({ name: 'inspect_url', description: 'Inspect URL indexing where provider API offers evidence; unknown means unverified.', inputSchema: z.object({ site: z.string(), url: z.url(), engines, account: z.string().optional() }), handler: (a) => service.inspect(a.site, a.url, a.engines, a.account) });
+    app.tool({ name: 'compare_engines', description: 'Compare provider-reported metrics without equating their counting semantics.', inputSchema: z.object(base), handler: async (a) => { const data = await service.metrics('performance', a, a.engines); return { ...data, results: compareEngines(data.results) }; } });
+    app.tool({ name: 'opportunities', description: 'Deterministic CTR, ranking and trend candidates with supporting metrics.', inputSchema: z.object({ ...base, minImpressions: z.number().min(0).default(100), maxCtr: z.number().min(0).max(1).default(0.02), declineFraction: z.number().min(0).max(1).default(0.2) }), handler: async (a) => { const prior = previousRange(a.from, a.to); const [queries, pages, oldQueries, oldPages] = await Promise.all([service.metrics('queries', a, a.engines), service.metrics('pages', a, a.engines), service.metrics('queries', { ...a, ...prior }, a.engines), service.metrics('pages', { ...a, ...prior }, a.engines)]); return { results: [...findCtrOpportunities(queries.results, { minImpressions: a.minImpressions, maxCtr: a.maxCtr }), ...findNearFirstPage(queries.results), ...findDecliningPages(pages.results, oldPages.results, a.declineFraction), ...findDecliningQueries(queries.results, oldQueries.results, a.declineFraction), ...findImpressionGrowthWithoutClicks(queries.results, oldQueries.results)], errors: [...queries.errors, ...pages.errors, ...oldQueries.errors, ...oldPages.errors] }; } });
+    app.tool({ name: 'indexing_gaps', description: 'Find verified indexing differences for supplied URLs and search visibility gaps. Missing performance rows are not indexing proof.', inputSchema: z.object({ ...base, urls: z.array(z.url()).max(20).optional() }), handler: async (a) => { const pageData = await service.metrics('pages', a, a.engines); const selected = (a.engines ?? ['google', 'bing', 'yandex']).filter(engine => !pageData.errors.some(e => e.engine === engine)); const inspected = await Promise.all((a.urls ?? []).map((url) => service.inspect(a.site, url, a.engines, a.account))); return { results: { visibilityGaps: findEngineGaps(pageData.results, selected), verifiedIndexingGaps: findIndexingGaps(inspected.flatMap(x => x.results)), inspections: inspected.flatMap(x => x.results) }, errors: [...pageData.errors, ...inspected.flatMap(x => x.errors)] }; } });
+}

package/dist/providers/bing/index.d.ts

@@ -0,0 +1,20 @@
+import type { CredentialStore } from '../../core/auth/store.js';
+import type { Capability, PerformanceQuery, SearchMetric, Site, Sitemap, WebmasterProvider } from '../../core/types/index.js';
+export declare class BingProvider implements WebmasterProvider {
+    private store;
+    readonly account: string;
+    private fetcher;
+    readonly id: 'bing';
+    private scheduler;
+    constructor(store: CredentialStore, account?: string, fetcher?: typeof fetch);
+    supports(c: Capability): boolean;
+    authenticate(): Promise<void>;
+    isAuthenticated(): Promise<boolean>;
+    private request;
+    getSites(): Promise<Site[]>;
+    private stats;
+    getPerformance(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getPages(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getQueries(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getSitemaps(site: string): Promise<Sitemap[]>;
+}

package/dist/providers/bing/index.js

@@ -0,0 +1,31 @@
+import { WebmasterError } from '../../core/errors.js';
+import { providerScheduler, jsonFetch } from '../../core/scheduler.js';
+import { metric, finite } from '../../core/normalize/index.js';
+import { validateSite } from '../../core/validation.js';
+import { secretPrompt } from '../../core/auth/prompt.js';
+export class BingProvider {
+    store;
+    account;
+    fetcher;
+    id = 'bing';
+    scheduler = providerScheduler('bing');
+    constructor(store, account = 'default', fetcher = fetch) {
+        this.store = store;
+        this.account = account;
+        this.fetcher = fetcher;
+    }
+    supports(c) { return ['sites', 'performance', 'queries', 'pages', 'sitemaps'].includes(c); }
+    async authenticate() { const key = await secretPrompt('Bing Webmaster API key: '); if (!key)
+        throw new WebmasterError('INVALID_INPUT', 'Empty Bing API key.'); await this.store.set('bing', this.account, { apiKey: key }); }
+    async isAuthenticated() { return !!(await this.store.get('bing', this.account)); }
+    async request(method, params = {}) { const credential = await this.store.get('bing', this.account); if (!credential?.apiKey)
+        throw new WebmasterError('AUTH_FAILED', 'Bing is not connected. Run auth bing.'); const url = new URL(`https://ssl.bing.com/webmaster/api.svc/json/${method}`); url.searchParams.set('apikey', credential.apiKey); for (const [k, v] of Object.entries(params))
+        url.searchParams.set(k, v); return this.scheduler.run(async () => { const data = await jsonFetch(this.fetcher, url.href); if (data?.ErrorCode)
+        throw new WebmasterError(data.ErrorCode === 3 ? 'AUTH_FAILED' : 'UPSTREAM_ERROR', 'Bing rejected the request.'); return data.d; }); }
+    async getSites() { const rows = await this.request('GetUserSites'); return (rows ?? []).filter((x) => x.IsVerified).map((x) => ({ site: x.Url, engine: this.id, account: this.account })); }
+    async stats(input, method, dimension) { validateSite(input.site); const rows = await this.request(method, { siteUrl: input.site }); return (rows ?? []).map((r) => { const match = String(r.Date ?? '').match(/\/Date\((\d+)/); const date = match ? new Date(Number(match[1])).toISOString().slice(0, 10) : String(r.Date ?? '').slice(0, 10); return metric({ engine: this.id, site: input.site, account: this.account, date, ...(dimension ? { [dimension]: r.Query } : {}), clicks: finite(r.Clicks), impressions: finite(r.Impressions), position: finite(r.AvgImpressionPosition) }); }).filter((r) => r.date && r.date >= input.from && r.date <= input.to).slice(0, input.limit ?? 25000); }
+    getPerformance(input) { return this.stats(input, 'GetRankAndTrafficStats'); }
+    getPages(input) { return this.stats(input, 'GetPageStats', 'page'); }
+    getQueries(input) { return this.stats(input, 'GetQueryStats', 'query'); }
+    async getSitemaps(site) { validateSite(site); const rows = await this.request('GetFeeds', { siteUrl: site }); return (rows ?? []).map((r) => ({ engine: this.id, site, url: r.Url ?? r.FeedUrl, status: r.Status })); }
+}

package/dist/providers/google/auth.d.ts

@@ -0,0 +1,10 @@
+import type { CredentialStore } from '../../core/auth/store.js';
+export interface GoogleCredentials {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+}
+export declare function openBrowser(url: string): void;
+export declare function authenticateGoogle(store: CredentialStore, account: string, write?: boolean, fetcher?: typeof fetch): Promise<void>;
+export declare function googleToken(store: CredentialStore, account: string, fetcher?: typeof fetch): Promise<string>;

package/dist/providers/google/auth.js

@@ -0,0 +1,57 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { WebmasterError } from '../../core/errors.js';
+import { jsonFetch } from '../../core/scheduler.js';
+export function openBrowser(url) { const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32.exe' : 'xdg-open'; const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url]; const child = spawn(command, args, { stdio: 'ignore', detached: true }); child.on('error', () => { }); child.unref(); }
+export async function authenticateGoogle(store, account, write = false, fetcher = fetch) {
+    const clientId = process.env.GOOGLE_CLIENT_ID, clientSecret = process.env.GOOGLE_CLIENT_SECRET;
+    if (!clientId)
+        throw new WebmasterError('INVALID_INPUT', 'Set GOOGLE_CLIENT_ID to a Desktop OAuth client ID.');
+    const state = randomBytes(24).toString('base64url'), verifier = randomBytes(48).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    let resolveCode, rejectCode;
+    const codePromise = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+    const app = new Hono();
+    app.get('/callback', c => { if (c.req.query('state') !== state) {
+        return c.text('Invalid OAuth state.', 400);
+    } const code = c.req.query('code'); if (!code) {
+        rejectCode(new WebmasterError('AUTH_FAILED', 'OAuth authorization was declined.'));
+        return c.text('Authorization failed.', 400);
+    } resolveCode(code); return c.text('Authorization complete. You can close this tab.'); });
+    const server = await new Promise(resolve => { const s = serve({ fetch: app.fetch, port: 0, hostname: '127.0.0.1' }, () => resolve(s)); });
+    let timer;
+    try {
+        const address = server.address();
+        if (!address || typeof address === 'string')
+            throw new Error('No callback port');
+        const redirect = `http://127.0.0.1:${address.port}/callback`;
+        const scope = write ? 'https://www.googleapis.com/auth/webmasters' : 'https://www.googleapis.com/auth/webmasters.readonly';
+        const authorization = new URL('https://accounts.google.com/o/oauth2/v2/auth');
+        authorization.search = new URLSearchParams({ client_id: clientId, redirect_uri: redirect, response_type: 'code', scope, access_type: 'offline', prompt: 'consent', state, code_challenge: challenge, code_challenge_method: 'S256' }).toString();
+        process.stderr.write(`Open this URL if your browser does not start:\n${authorization.href}\n`);
+        openBrowser(authorization.href);
+        const code = await Promise.race([codePromise, new Promise((_, reject) => { timer = setTimeout(() => reject(new WebmasterError('AUTH_FAILED', 'OAuth callback timed out after two minutes.')), 120000); })]);
+        const body = new URLSearchParams({ client_id: clientId, code, code_verifier: verifier, redirect_uri: redirect, grant_type: 'authorization_code' });
+        if (clientSecret)
+            body.set('client_secret', clientSecret);
+        const data = await jsonFetch(fetcher, 'https://oauth2.googleapis.com/token', { method: 'POST', body });
+        if (!data.access_token)
+            throw new WebmasterError('AUTH_FAILED', 'Google did not issue an access token.');
+        const credentials = { accessToken: data.access_token, refreshToken: data.refresh_token, expiresAt: Date.now() + Number(data.expires_in ?? 3600) * 1000, scope };
+        await store.set('google', account, credentials);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        await new Promise(resolve => server.close(() => resolve()));
+    }
+}
+export async function googleToken(store, account, fetcher = fetch) { const c = await store.get('google', account); if (!c?.accessToken)
+    throw new WebmasterError('AUTH_FAILED', 'Google is not connected. Run auth google.'); if (!c.expiresAt || c.expiresAt > Date.now() + 60000)
+    return c.accessToken; if (!c.refreshToken)
+    throw new WebmasterError('AUTH_FAILED', 'Google token expired. Run auth google again.'); const clientId = process.env.GOOGLE_CLIENT_ID; if (!clientId)
+    throw new WebmasterError('AUTH_FAILED', 'GOOGLE_CLIENT_ID is required to refresh the token.'); const body = new URLSearchParams({ client_id: clientId, refresh_token: c.refreshToken, grant_type: 'refresh_token' }); if (process.env.GOOGLE_CLIENT_SECRET)
+    body.set('client_secret', process.env.GOOGLE_CLIENT_SECRET); const data = await jsonFetch(fetcher, 'https://oauth2.googleapis.com/token', { method: 'POST', body }); if (!data.access_token)
+    throw new WebmasterError('AUTH_FAILED', 'Google token refresh failed.'); const updated = { ...c, accessToken: data.access_token, expiresAt: Date.now() + Number(data.expires_in ?? 3600) * 1000 }; await store.set('google', account, updated); return updated.accessToken; }

package/dist/providers/google/index.d.ts

@@ -0,0 +1,22 @@
+import type { CredentialStore } from '../../core/auth/store.js';
+import type { Capability, PerformanceQuery, SearchMetric, Site, Sitemap, UrlInspection, WebmasterProvider } from '../../core/types/index.js';
+export declare class GoogleProvider implements WebmasterProvider {
+    private store;
+    readonly account: string;
+    private fetcher;
+    private write;
+    readonly id: 'google';
+    private scheduler;
+    constructor(store: CredentialStore, account?: string, fetcher?: typeof fetch, write?: boolean);
+    supports(c: Capability): boolean;
+    authenticate(): Promise<void>;
+    isAuthenticated(): Promise<boolean>;
+    private request;
+    getSites(): Promise<Site[]>;
+    private search;
+    getPerformance(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getPages(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getQueries(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getSitemaps(site: string): Promise<Sitemap[]>;
+    inspectUrl(site: string, url: string): Promise<UrlInspection>;
+}

package/dist/providers/google/index.js

@@ -0,0 +1,35 @@
+import { providerScheduler, jsonFetch } from '../../core/scheduler.js';
+import { metric } from '../../core/normalize/index.js';
+import { validateSite, validateUrl } from '../../core/validation.js';
+import { authenticateGoogle, googleToken } from './auth.js';
+export class GoogleProvider {
+    store;
+    account;
+    fetcher;
+    write;
+    id = 'google';
+    scheduler = providerScheduler('google');
+    constructor(store, account = 'default', fetcher = fetch, write = false) {
+        this.store = store;
+        this.account = account;
+        this.fetcher = fetcher;
+        this.write = write;
+    }
+    supports(c) { return ['sites', 'performance', 'queries', 'pages', 'sitemaps', 'urlInspection', 'indexing'].includes(c); }
+    authenticate() { return authenticateGoogle(this.store, this.account, this.write, this.fetcher); }
+    async isAuthenticated() { return !!(await this.store.get('google', this.account)); }
+    async request(url, body) { return this.scheduler.run(async () => jsonFetch(this.fetcher, url, { method: body ? 'POST' : 'GET', headers: { Authorization: `Bearer ${await googleToken(this.store, this.account, this.fetcher)}`, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined })); }
+    async getSites() { const data = await this.request('https://www.googleapis.com/webmasters/v3/sites'); return (data.siteEntry ?? []).map((s) => ({ site: s.siteUrl, engine: this.id, account: this.account, permission: s.permissionLevel })); }
+    async search(input, dimensions) { validateSite(input.site); const site = encodeURIComponent(input.site); const result = []; const limit = Math.min(input.limit ?? 25000, 25000); for (let startRow = 0; startRow < limit; startRow += 25000) {
+        const data = await this.request(`https://www.googleapis.com/webmasters/v3/sites/${site}/searchAnalytics/query`, { startDate: input.from, endDate: input.to, dimensions, rowLimit: Math.min(25000, limit - startRow), startRow });
+        const rows = data.rows ?? [];
+        result.push(...rows.map((r) => metric({ engine: this.id, site: input.site, account: this.account, ...Object.fromEntries(dimensions.map((d, i) => [d, r.keys?.[i]])), clicks: r.clicks, impressions: r.impressions, ctr: r.ctr, position: r.position })));
+        if (rows.length < Math.min(25000, limit - startRow))
+            break;
+    } return result; }
+    getPerformance(input) { return this.search(input, ['date']); }
+    getPages(input) { return this.search(input, ['page']); }
+    getQueries(input) { return this.search(input, ['query']); }
+    async getSitemaps(site) { validateSite(site); const d = await this.request(`https://www.googleapis.com/webmasters/v3/sites/${encodeURIComponent(site)}/sitemaps`); return (d.sitemap ?? []).map((s) => ({ engine: this.id, site, url: s.path, submitted: s.lastSubmitted, status: s.isPending ? 'pending' : undefined })); }
+    async inspectUrl(site, url) { validateUrl(site, url); const d = await this.request('https://searchconsole.googleapis.com/v1/urlInspection/index:inspect', { siteUrl: site, inspectionUrl: url }); const status = d.inspectionResult?.indexStatusResult; return { engine: this.id, site, url, state: status?.verdict === 'PASS' ? 'indexed' : status?.verdict === 'FAIL' || status?.verdict === 'NEUTRAL' ? 'not_indexed' : 'unknown', reason: status?.coverageState, inspectedAt: status?.lastCrawlTime }; }
+}

package/dist/providers/yandex/auth.d.ts

@@ -0,0 +1,5 @@
+import type { CredentialStore } from '../../core/auth/store.js';
+export declare function yandexAuthorizationUrl(): string;
+export declare function beginYandexAuth(): void;
+export declare function saveYandexToken(store: CredentialStore, account: string, token: string): Promise<void>;
+export declare function authenticateYandex(store: CredentialStore, account: string): Promise<void>;

package/dist/providers/yandex/auth.js

@@ -0,0 +1,9 @@
+import { WebmasterError } from '../../core/errors.js';
+import { openBrowser } from '../google/auth.js';
+import { secretPrompt } from '../../core/auth/prompt.js';
+export function yandexAuthorizationUrl() { const clientId = process.env.YANDEX_CLIENT_ID; if (!clientId)
+    throw new WebmasterError('INVALID_INPUT', 'Set YANDEX_CLIENT_ID for a Yandex OAuth app with webmaster:hostinfo permission.'); const url = new URL('https://oauth.yandex.com/authorize'); url.searchParams.set('response_type', 'token'); url.searchParams.set('client_id', clientId); return url.href; }
+export function beginYandexAuth() { const url = yandexAuthorizationUrl(); process.stderr.write(`Open Yandex OAuth and copy the displayed token:\n${url}\n`); openBrowser(url); }
+export async function saveYandexToken(store, account, token) { if (!/^[A-Za-z0-9._~-]{10,}$/.test(token))
+    throw new WebmasterError('INVALID_INPUT', 'Invalid Yandex OAuth token format.'); await store.set('yandex', account, { accessToken: token }); }
+export async function authenticateYandex(store, account) { beginYandexAuth(); await saveYandexToken(store, account, await secretPrompt('Yandex OAuth token: ')); }

package/dist/providers/yandex/index.d.ts

@@ -0,0 +1,22 @@
+import type { CredentialStore } from '../../core/auth/store.js';
+import type { Capability, PerformanceQuery, SearchMetric, Site, Sitemap, UrlInspection, WebmasterProvider } from '../../core/types/index.js';
+export declare class YandexProvider implements WebmasterProvider {
+    private store;
+    readonly account: string;
+    private fetcher;
+    readonly id: 'yandex';
+    private scheduler;
+    constructor(store: CredentialStore, account?: string, fetcher?: typeof fetch);
+    supports(c: Capability): boolean;
+    authenticate(): Promise<void>;
+    isAuthenticated(): Promise<boolean>;
+    private request;
+    private userId;
+    private host;
+    getSites(): Promise<Site[]>;
+    getPerformance(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getQueries(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getPages(input: PerformanceQuery): Promise<SearchMetric[]>;
+    getSitemaps(site: string): Promise<Sitemap[]>;
+    inspectUrl(site: string, url: string): Promise<UrlInspection>;
+}

package/dist/providers/yandex/index.js

@@ -0,0 +1,70 @@
+import { WebmasterError } from '../../core/errors.js';
+import { providerScheduler, jsonFetch } from '../../core/scheduler.js';
+import { metric, finite } from '../../core/normalize/index.js';
+import { validateSite, validateUrl } from '../../core/validation.js';
+import { authenticateYandex } from './auth.js';
+export class YandexProvider {
+    store;
+    account;
+    fetcher;
+    id = 'yandex';
+    scheduler = providerScheduler('yandex');
+    constructor(store, account = 'default', fetcher = fetch) {
+        this.store = store;
+        this.account = account;
+        this.fetcher = fetcher;
+    }
+    supports(c) { return ['sites', 'performance', 'queries', 'pages', 'sitemaps', 'urlInspection', 'indexing'].includes(c); }
+    authenticate() { return authenticateYandex(this.store, this.account); }
+    async isAuthenticated() { return !!(await this.store.get('yandex', this.account)); }
+    async request(path, body) { const credential = await this.store.get('yandex', this.account); if (!credential?.accessToken)
+        throw new WebmasterError('AUTH_FAILED', 'Yandex is not connected. Run auth yandex.'); return this.scheduler.run(() => jsonFetch(this.fetcher, `https://api.webmaster.yandex.net/v4/${path}`, { method: body ? 'POST' : 'GET', headers: { Authorization: `OAuth ${credential.accessToken}`, ...(body ? { 'Content-Type': 'application/json' } : {}) }, body: body ? JSON.stringify(body) : undefined })); }
+    async userId() { const d = await this.request('user'); return String(d.user_id); }
+    async host(site) { validateSite(site); const user = await this.userId(); const d = await this.request(`user/${encodeURIComponent(user)}/hosts`); const found = (d.hosts ?? []).find((h) => h.ascii_host_url === site || h.unicode_host_url === site); if (!found)
+        throw new WebmasterError('PERMISSION_DENIED', 'Site is not in this Yandex account.'); return { user, host: found.host_id }; }
+    async getSites() { const user = await this.userId(); const d = await this.request(`user/${encodeURIComponent(user)}/hosts`); return (d.hosts ?? []).filter((h) => h.verified).map((h) => ({ site: h.ascii_host_url, engine: this.id, account: this.account })); }
+    async getPerformance(input) { const { user, host } = await this.host(input.site); const url = new URL(`https://api.webmaster.yandex.net/v4/user/${encodeURIComponent(user)}/hosts/${encodeURIComponent(host)}/search-queries/all/history`); for (const x of ['TOTAL_SHOWS', 'TOTAL_CLICKS', 'AVG_SHOW_POSITION'])
+        url.searchParams.append('query_indicator', x); url.searchParams.set('date_from', input.from); url.searchParams.set('date_to', input.to); const d = await this.request(url.pathname.slice(4) + url.search); const byDate = new Map(); for (const [key, items] of Object.entries(d.indicators ?? {}))
+        for (const item of items) {
+            const date = String(item.date).slice(0, 10);
+            const row = byDate.get(date) ?? { engine: this.id, site: input.site, account: this.account, date };
+            if (key === 'TOTAL_SHOWS')
+                row.impressions = finite(item.value);
+            if (key === 'TOTAL_CLICKS')
+                row.clicks = finite(item.value);
+            if (key === 'AVG_SHOW_POSITION')
+                row.position = finite(item.value);
+            byDate.set(date, row);
+        } return [...byDate.values()].map(metric); }
+    async getQueries(input) { const { user, host } = await this.host(input.site); const url = new URL(`https://api.webmaster.yandex.net/v4/user/${encodeURIComponent(user)}/hosts/${encodeURIComponent(host)}/search-queries/popular`); url.searchParams.set('order_by', 'TOTAL_CLICKS'); for (const x of ['TOTAL_SHOWS', 'TOTAL_CLICKS', 'AVG_SHOW_POSITION'])
+        url.searchParams.append('query_indicator', x); url.searchParams.set('date_from', input.from); url.searchParams.set('date_to', input.to); const max = Math.min(input.limit ?? 500, 3000); const rows = []; for (let offset = 0; offset < max; offset += 500) {
+        url.searchParams.set('offset', String(offset));
+        url.searchParams.set('limit', String(Math.min(500, max - offset)));
+        const d = await this.request(url.pathname.slice(4) + url.search);
+        const batch = d.queries ?? [];
+        rows.push(...batch.map((q) => metric({ engine: this.id, site: input.site, account: this.account, query: q.query_text, clicks: q.indicators?.TOTAL_CLICKS, impressions: q.indicators?.TOTAL_SHOWS, position: q.indicators?.AVG_SHOW_POSITION })));
+        if (batch.length < Math.min(500, max - offset))
+            break;
+    } return rows; }
+    async getPages(input) { const earliest = new Date(Date.now() - 14 * 86400000).toISOString().slice(0, 10); if (input.from < earliest)
+        throw new WebmasterError('UNSUPPORTED', 'Yandex page analytics is available only for the last two weeks.'); const { user, host } = await this.host(input.site); const rows = []; const max = input.limit ?? 500; for (let offset = 0; offset < max; offset += 500) {
+        const d = await this.request(`user/${encodeURIComponent(user)}/hosts/${encodeURIComponent(host)}/query-analytics/list`, { offset, limit: Math.min(500, max - offset), text_indicator: 'URL', search_location: 'WEB_LOCATION' });
+        const items = d.text_indicator_to_statistics ?? [];
+        for (const item of items) {
+            const dates = new Map();
+            for (const stat of item.statistics ?? []) {
+                if (stat.date < input.from || stat.date > input.to)
+                    continue;
+                const row = dates.get(stat.date) ?? {};
+                row[stat.field] = stat.value;
+                dates.set(stat.date, row);
+            }
+            for (const [date, s] of dates)
+                rows.push(metric({ engine: this.id, site: input.site, account: this.account, page: item.text_indicator?.value, date, clicks: s.CLICKS, impressions: s.IMPRESSIONS, position: s.POSITION }));
+        }
+        if (items.length < Math.min(500, max - offset))
+            break;
+    } return rows; }
+    async getSitemaps(site) { const { user, host } = await this.host(site); const d = await this.request(`user/${encodeURIComponent(user)}/hosts/${encodeURIComponent(host)}/sitemaps`); return (d.sitemaps ?? []).map((s) => ({ engine: this.id, site, url: s.sitemap_url ?? s.url, status: s.status })); }
+    async inspectUrl(site, url) { validateUrl(site, url); const { user, host } = await this.host(site); const d = await this.request(`user/${encodeURIComponent(user)}/hosts/${encodeURIComponent(host)}/important-urls`); const item = (d.urls ?? []).find((x) => x.url === url); const searchable = item?.search_status?.searchable; return { engine: this.id, site, url, state: searchable === true ? 'indexed' : searchable === false ? 'not_indexed' : 'unknown', reason: item ? item.search_status?.excluded_url_status : 'URL is not in Yandex important-page monitoring.', inspectedAt: item?.update_date }; }
+}

package/dist/server/context.d.ts

@@ -0,0 +1,10 @@
+import { Cache } from '../core/cache/index.js';
+import { KeychainCredentialStore } from '../core/auth/store.js';
+import { AccountRegistry } from '../core/auth/accounts.js';
+import { WebmasterService } from '../core/service.js';
+export declare function createContext(): {
+    cache: Cache;
+    store: KeychainCredentialStore;
+    accounts: AccountRegistry;
+    service: WebmasterService;
+};

package/dist/server/context.js

@@ -0,0 +1,10 @@
+import { Cache } from '../core/cache/index.js';
+import { KeychainCredentialStore } from '../core/auth/store.js';
+import { AccountRegistry } from '../core/auth/accounts.js';
+import { GoogleProvider } from '../providers/google/index.js';
+import { BingProvider } from '../providers/bing/index.js';
+import { YandexProvider } from '../providers/yandex/index.js';
+import { WebmasterService } from '../core/service.js';
+export function createContext() { const cache = new Cache(); const store = new KeychainCredentialStore(); const accounts = new AccountRegistry(cache, store); const buildProviders = () => { const providers = []; for (const engine of ['google', 'bing', 'yandex'])
+    for (const name of accounts.names(engine))
+        providers.push(engine === 'google' ? new GoogleProvider(store, name) : engine === 'bing' ? new BingProvider(store, name) : new YandexProvider(store, name)); return providers; }; return { cache, store, accounts, service: new WebmasterService(buildProviders(), cache, buildProviders) }; }

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "webmaster-mcp",
+  "version": "0.1.0",
+  "description": "Local-first unified webmaster MCP for Google, Bing, and Yandex",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "webmaster-mcp": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import tsx --test test/*.test.ts",
+    "postbuild": "node -e \"require('node:fs').chmodSync('dist/cli/index.js', 0o755)\"",
+    "prepack": "npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.1",
+    "@napi-rs/keyring": "^2.1.0",
+    "better-sqlite3": "^11.10.0",
+    "hono": "^4.13.8",
+    "mcponce": "^0.2.3",
+    "unitup": "^0.3.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^9.6.0",
+    "@types/node": "^26.6.2",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
+}