@georanker/seo-mcp 0.14.0

package/dist/src/remote.js

@@ -0,0 +1,278 @@
+import { randomUUID } from 'node:crypto';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport, StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { AppError } from './errors.js';
+import { secureUrl } from './config.js';
+import { installationHeaders } from './enrollment.js';
+import { deviceFingerprint } from './identity.js';
+export { deviceFingerprint } from './identity.js';
+import { PRODUCT_PROFILES, SERVER_VERSION } from './product-contract.js';
+import { SEO_REPORT_CATALOG, SEO_REPORT_HEADER, SEO_TOOL_NAMES } from './seo-contract.js';
+import { createServer } from './server.js';
+export const PILOT_MCP_URL = 'https://grmcp.ibl.ro/mcp';
+const MAX_ERROR_TEXT = 8192;
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+const localCatalogs = new Map();
+function localInputSchemas(service, profile) {
+    let catalog = localCatalogs.get(profile);
+    if (!catalog) {
+        // Use the same SDK serialization as the advertised local tools. This
+        // metadata-only exchange cannot invoke a provider or create a data job.
+        catalog = (async () => {
+            const server = createServer(service, profile);
+            const client = new Client({ name: 'local-schema-check', version: SERVER_VERSION });
+            const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+            try {
+                await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+                const listed = await client.listTools();
+                return new Map(listed.tools.map(tool => [tool.name, tool.inputSchema]));
+            }
+            finally {
+                await client.close();
+                await server.close();
+            }
+        })().catch(error => { localCatalogs.delete(profile); throw error; });
+        localCatalogs.set(profile, catalog);
+    }
+    return catalog;
+}
+function canonicalSchema(value, mode = 'schema') {
+    if (Array.isArray(value))
+        return value.map(item => canonicalSchema(item, mode));
+    const data = record(value);
+    if (!data)
+        return value;
+    return Object.fromEntries(Object.keys(data).sort().flatMap(key => {
+        if (mode === 'schema' && ['description', 'title', '$schema', '$comment', 'examples'].includes(key))
+            return [];
+        let childMode = mode === 'map' ? 'schema' : mode;
+        if (mode === 'schema') {
+            if (['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas', 'dependencies'].includes(key))
+                childMode = 'map';
+            else if (['default', 'const', 'enum', 'required'].includes(key))
+                childMode = 'data';
+        }
+        let child = canonicalSchema(data[key], childMode);
+        if (mode === 'schema' && ['enum', 'required'].includes(key) && Array.isArray(child))
+            child = child.sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+        return [[key, child]];
+    }));
+}
+function schemaDifferences(expected, actual, path = 'inputSchema') {
+    if (JSON.stringify(expected) === JSON.stringify(actual))
+        return [];
+    const left = record(expected), right = record(actual);
+    if (!left || !right)
+        return [path];
+    return [...new Set([...Object.keys(left), ...Object.keys(right)])].sort()
+        .flatMap(key => schemaDifferences(left[key], right[key], `${path}.${key}`)).slice(0, 12);
+}
+function recoveryFields(value) {
+    const data = record(value), fields = {};
+    if (typeof data?.reportId === 'string' && /^seo_[a-f0-9-]{36}$/.test(data.reportId))
+        fields.reportId = data.reportId;
+    if (typeof data?.jobId === 'string' && /^[a-zA-Z0-9_-]{1,200}$/.test(data.jobId))
+        fields.jobId = data.jobId;
+    if (typeof data?.submissionUncertain === 'boolean')
+        fields.submissionUncertain = data.submissionUncertain;
+    return fields;
+}
+function textDiagnostic(content) {
+    let text = '', truncated = false;
+    if (Array.isArray(content))
+        for (const item of content) {
+            const block = record(item);
+            if (block?.type !== 'text' || typeof block.text !== 'string' || !block.text.trim())
+                continue;
+            const separator = text ? '\n' : '';
+            const remaining = MAX_ERROR_TEXT - text.length - separator.length;
+            if (remaining <= 0) {
+                truncated = true;
+                break;
+            }
+            text += separator + block.text.slice(0, remaining);
+            if (block.text.length > remaining) {
+                truncated = true;
+                break;
+            }
+        }
+    let value;
+    if (text && !truncated) {
+        try {
+            value = record(JSON.parse(text));
+        }
+        catch { /* SDK validation errors are ordinary text. */ }
+    }
+    // Recover only explicitly labelled identifiers. Prose cannot prove that a
+    // submission was refused, so never infer submission certainty from text.
+    const reportId = text.match(/\breportId["']?\s*[:=]\s*["']?(seo_[a-f0-9-]{36})(?![a-zA-Z0-9_-])/i)?.[1];
+    const jobId = text.match(/\bjobId["']?\s*[:=]\s*["']?([a-zA-Z0-9_-]{1,200})(?![a-zA-Z0-9_-])/i)?.[1];
+    return { text: text.trim(), truncated, value, details: { ...recoveryFields({ reportId, jobId }), ...(truncated ? { diagnosticTruncated: true } : {}) } };
+}
+function remoteToolError(result) {
+    const diagnostic = textDiagnostic(result.content);
+    const structured = record(result.structuredContent);
+    const envelope = structured && (record(structured.error) || typeof structured.message === 'string') ? structured : diagnostic.value;
+    const error = record(envelope?.error) ?? envelope;
+    const code = typeof error?.code === 'string' && error.code.length > 0 && error.code.length <= 128 ? error.code : 'REMOTE_ERROR';
+    const message = typeof error?.message === 'string' && error.message.trim() ? error.message : diagnostic.text || 'The hosted tool failed without a diagnostic.';
+    const retry = typeof error?.retryAfterSeconds === 'number' && Number.isFinite(error.retryAfterSeconds) && error.retryAfterSeconds >= 0 ? error.retryAfterSeconds : undefined;
+    return new AppError(code, message, retry, { ...diagnostic.details, ...recoveryFields(structured), ...recoveryFields(envelope), ...recoveryFields(error), ...record(error?.details) });
+}
+function requestError(error, name, input, profile) {
+    const arguments_ = record(input);
+    const details = { ...recoveryFields({ reportId: arguments_?.reportId, jobId: arguments_?.jobId }), ...error.details };
+    details.submissionUncertain = typeof details.submissionUncertain === 'boolean' ? details.submissionUncertain : !name.startsWith('get_');
+    details.automaticRetryPerformed = false;
+    if (typeof details.nextAction !== 'string' || !details.nextAction.trim()) {
+        if (details.reportId) {
+            const getter = name === 'update_rank_tracking_schedule' ? 'get_rank_tracking_report' : name.replace(/^create_/, 'get_');
+            details.nextAction = `Retain this reportId and use ${getter} to check the existing report before submitting another report or schedule change.`;
+        }
+        else if (details.jobId) {
+            details.nextAction = `Retain this jobId and use ${PRODUCT_PROFILES[profile].resultTool} to check the existing job before submitting another job.`;
+        }
+        else if (details.submissionUncertain) {
+            details.nextAction = 'The submission outcome is unknown. Ask the operator to reconcile this request before resubmitting; another create call could duplicate paid work.';
+        }
+        else {
+            details.nextAction = name.startsWith('get_')
+                ? 'Retry this retrieval with the same identifier after resolving the error or waiting for retryAfterSeconds. Do not create a replacement job.'
+                : 'No new work was submitted. Resolve the reported error or wait for retryAfterSeconds before explicitly retrying this request.';
+        }
+    }
+    return new AppError(error.code, error.message, error.retryAfterSeconds, details);
+}
+function queuedRefusal(error) {
+    // The pinned SDK includes the HTTP error body in this error. Accept only our
+    // bounded, explicit pre-dispatch refusal; other failures stay uncertain.
+    if (!(error instanceof StreamableHTTPError) || error.code !== 503 || error.message.length > 8192)
+        return;
+    const prefix = 'Streamable HTTP error: Error POSTing to endpoint: ';
+    if (!error.message.startsWith(prefix))
+        return;
+    try {
+        const value = JSON.parse(error.message.slice(prefix.length)).error;
+        if (value?.code === 'CAPACITY_LIMIT' && value.details?.submissionUncertain === false && ['queue_full', 'queue_timeout'].includes(value.details.reason)) {
+            return new AppError('CAPACITY_LIMIT', 'The hosted MCP request queue is busy. No tool was started. Retry shortly.', 1, { submissionUncertain: false, reason: value.details.reason });
+        }
+    }
+    catch { /* An unrecognized response cannot prove whether work started. */ }
+}
+export class RemoteService {
+    env;
+    profile;
+    connection;
+    url;
+    headers;
+    constructor(env, profile = 'combined') {
+        this.env = env;
+        this.profile = profile;
+        this.url = secureUrl(env.GEORANKER_MCP_URL || new URL(PRODUCT_PROFILES[profile].endpoint, PILOT_MCP_URL).href, 'GEORANKER_MCP_URL');
+        if (!env.GEORANKER_ACCESS_TOKEN && !env.GEORANKER_INSTALLATION_ID)
+            return;
+        if (!env.GEORANKER_ACCESS_TOKEN || !env.GEORANKER_INSTALLATION_ID)
+            throw new AppError('CONFIG_ERROR', 'Set both manual credential fields or neither for automatic registration.');
+        const fingerprint = env.GEORANKER_DEVICE_FINGERPRINT || deviceFingerprint();
+        if (!/^[a-f0-9]{64}$/.test(fingerprint))
+            throw new AppError('CONFIG_ERROR', 'GEORANKER_DEVICE_FINGERPRINT must be a lowercase SHA-256 hex string.');
+        this.headers = { Authorization: `Bearer ${env.GEORANKER_ACCESS_TOKEN}`, 'X-GeoRanker-Installation-Id': env.GEORANKER_INSTALLATION_ID, 'X-GeoRanker-Device-Fingerprint': fingerprint };
+    }
+    connect() {
+        if (!this.connection) {
+            const client = new Client({ name: `${PRODUCT_PROFILES[this.profile].name}-bridge`, version: SERVER_VERSION });
+            this.connection = (async () => {
+                this.headers ??= await installationHeaders(this.url, this.env);
+                if (this.profile === 'seo')
+                    this.headers[SEO_REPORT_HEADER] = SEO_REPORT_CATALOG;
+                // JSON-RPC IDs are unique only inside this transport. The namespace
+                // lets a stateless server correlate cancellation without affecting
+                // another AI host sharing the same installation credentials.
+                const headers = { ...this.headers, 'X-GeoRanker-Request-Group': randomUUID() };
+                const transport = new StreamableHTTPClientTransport(this.url, { requestInit: { headers, redirect: 'error' } });
+                await client.connect(transport);
+                return client;
+            })().catch(async (error) => {
+                this.connection = undefined;
+                await client.close().catch(() => { });
+                if (error instanceof AppError)
+                    throw new AppError(error.code, error.message, error.retryAfterSeconds, { ...error.details, submissionUncertain: false });
+                const refusal = queuedRefusal(error);
+                if (refusal)
+                    throw refusal;
+                throw new AppError('REMOTE_CONNECTION_FAILED', 'Cannot connect to the hosted MCP. Check its URL, installation credentials, device fingerprint, and availability.', undefined, { submissionUncertain: false });
+            });
+        }
+        return this.connection;
+    }
+    async initialize() {
+        const listed = await (await this.connect()).listTools();
+        const product = PRODUCT_PROFILES[this.profile];
+        const required = [product.resultTool, ...('searchTool' in product ? [product.searchTool] : []), ...('fetchTool' in product ? [product.fetchTool] : []), ...(this.profile === 'seo' ? SEO_TOOL_NAMES : [])].sort();
+        const available = listed.tools.map(tool => tool.name).sort();
+        if (required.length !== available.length || required.some((name, index) => name !== available[index])) {
+            throw new AppError('REMOTE_PROFILE_MISMATCH', `The hosted endpoint does not provide the expected tools for ${product.title}. Check GEORANKER_MCP_URL and the server deployment. No query was submitted.`, undefined, { submissionUncertain: false, automaticRetryPerformed: false });
+        }
+        const local = await localInputSchemas(this, this.profile);
+        const differences = listed.tools.flatMap(tool => {
+            const paths = schemaDifferences(canonicalSchema(local.get(tool.name)), canonicalSchema(tool.inputSchema));
+            return paths.length ? [{ toolName: tool.name, paths }] : [];
+        });
+        if (differences.length) {
+            throw new AppError('REMOTE_SCHEMA_MISMATCH', `The local and hosted input contracts differ for ${differences.map(item => item.toolName).join(', ')}. Update the client and hosted service to compatible versions before submitting work. No query was submitted.`, undefined, {
+                submissionUncertain: false, automaticRetryPerformed: false, schemaDifferences: differences,
+                nextAction: 'Compare the listed inputSchema fields and update the mismatched client or hosted deployment. Rerun setup before creating any jobs.',
+            });
+        }
+    }
+    async call(name, input, signal) {
+        try {
+            if (signal?.aborted)
+                throw new AppError('CANCELLED', 'The hosted MCP request was cancelled before submission.', undefined, { submissionUncertain: false });
+            const client = await this.connect();
+            if (signal?.aborted)
+                throw new AppError('CANCELLED', 'The hosted MCP request was cancelled before submission.', undefined, { submissionUncertain: false });
+            const result = await client.callTool({ name, arguments: { ...input } }, undefined, { signal, timeout: 100_000 });
+            if (result.isError)
+                throw remoteToolError(result);
+            const value = record(result.structuredContent);
+            if (!value) {
+                const diagnostic = textDiagnostic(result.content);
+                throw new AppError('REMOTE_RESPONSE_INVALID', 'The hosted MCP returned an unsupported result. A submitted job may still exist. No automatic tool retry was performed.', undefined, { ...diagnostic.details, ...recoveryFields({ reportId: diagnostic.value?.reportId, jobId: diagnostic.value?.jobId }) });
+            }
+            return value;
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw requestError(error, name, input, this.profile);
+            const refusal = queuedRefusal(error);
+            if (refusal)
+                throw requestError(refusal, name, input, this.profile);
+            throw requestError(new AppError('REMOTE_REQUEST_FAILED', 'The hosted MCP request did not complete. No automatic tool retry was performed.'), name, input, this.profile);
+        }
+    }
+    search(input, signal) {
+        const product = PRODUCT_PROFILES[this.profile];
+        if (!('searchTool' in product))
+            return Promise.reject(new AppError('PROFILE_TOOL_UNAVAILABLE', 'SERP search is not available through this MCP profile.'));
+        return this.call(product.searchTool, input, signal);
+    }
+    seoReport(name, input, signal) {
+        if (this.profile !== 'seo' || !SEO_TOOL_NAMES.includes(name))
+            return Promise.reject(new AppError('PROFILE_TOOL_UNAVAILABLE', 'SEO reports require the SEO MCP profile.'));
+        return this.call(name, input, signal);
+    }
+    fetchPage(input, signal) {
+        const product = PRODUCT_PROFILES[this.profile];
+        if (!('fetchTool' in product))
+            return Promise.reject(new AppError('PROFILE_TOOL_UNAVAILABLE', 'Page fetching is not available through this MCP profile.'));
+        return this.call(product.fetchTool, input, signal);
+    }
+    getSearchResult(input, signal) {
+        const { expectedKind: _expectedKind, ...arguments_ } = input;
+        return this.call(PRODUCT_PROFILES[this.profile].resultTool, arguments_, signal);
+    }
+    async close() { if (this.connection)
+        await (await this.connection).close(); }
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1 @@
+export declare function run(): Promise<void>;

package/dist/src/runtime.js

@@ -0,0 +1,35 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { AppError } from './errors.js';
+import { RemoteService } from './remote.js';
+import { createServer, SERVER_VERSION } from './server.js';
+import { CLIENT_PROFILE } from './product.js';
+export async function run() {
+    const args = process.argv.slice(2);
+    if (args.length > 1 || (args.length === 1 && !['--setup', '--help', '-h', '--version', '-v'].includes(args[0]))) {
+        throw new AppError('CLI_ARGUMENTS', 'Unsupported argument. Use --help. This package only connects to the hosted GeoRanker service.');
+    }
+    if (args[0] === '--version' || args[0] === '-v') {
+        process.stdout.write(`${SERVER_VERSION}\n`);
+        return;
+    }
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(`GeoRanker ${CLIENT_PROFILE} MCP ${SERVER_VERSION}\n\nLaunch with no arguments from an MCP host.\n--setup: verify automatic enrollment and tool discovery without a data request.\n--version: show version.\n--update: prepare the latest signed release for an idle worker swap or next launch.\nUpdates check quietly every five minutes; workers switch after 60 idle seconds; set GEORANKER_MCP_AUTO_UPDATE=0 to opt out.\nOptional GEORANKER_MCP_URL and GEORANKER_STATE_DIR.\nBoth GeoRanker products share the existing installation identity for the same service origin.\n`);
+        return;
+    }
+    const service = new RemoteService({ ...process.env }, CLIENT_PROFILE);
+    try {
+        await service.initialize();
+        if (args[0] === '--setup') {
+            process.stdout.write(`GeoRanker ${CLIENT_PROFILE} MCP is connected. No data query was submitted.\n`);
+            await service.close();
+            return;
+        }
+        const server = createServer(service, CLIENT_PROFILE);
+        server.server.onclose = () => { void service.close().catch(() => { }); };
+        await server.connect(new StdioServerTransport());
+    }
+    catch (error) {
+        await service.close().catch(() => { });
+        throw error;
+    }
+}

package/dist/src/search-depth.d.ts

@@ -0,0 +1,10 @@
+export declare const RESULTS_PER_PAGE = 10;
+export declare const MAX_SEARCH_PAGES = 10;
+export declare const MAX_SEARCH_RESULTS: number;
+export declare function resolveSearchDepth(input: {
+    pages?: number;
+    limit?: number;
+}): {
+    maxResults: number;
+    limit: number;
+};

package/dist/src/search-depth.js

@@ -0,0 +1,19 @@
+import { AppError } from './errors.js';
+export const RESULTS_PER_PAGE = 10;
+export const MAX_SEARCH_PAGES = 10;
+export const MAX_SEARCH_RESULTS = RESULTS_PER_PAGE * MAX_SEARCH_PAGES;
+// Pages express organic-result depth from the first result, not a page offset.
+export function resolveSearchDepth(input) {
+    if (input.pages !== undefined && (!Number.isInteger(input.pages) || input.pages < 1 || input.pages > MAX_SEARCH_PAGES)) {
+        throw new AppError('INVALID_INPUT', `pages must be an integer between 1 and ${MAX_SEARCH_PAGES}.`);
+    }
+    if (input.limit !== undefined && (!Number.isInteger(input.limit) || input.limit < 1 || input.limit > MAX_SEARCH_RESULTS)) {
+        throw new AppError('INVALID_INPUT', `limit must be an integer between 1 and ${MAX_SEARCH_RESULTS}.`);
+    }
+    const pages = input.pages ?? Math.ceil((input.limit ?? RESULTS_PER_PAGE) / RESULTS_PER_PAGE);
+    const maxResults = pages * RESULTS_PER_PAGE;
+    const limit = input.limit ?? maxResults;
+    if (limit > maxResults)
+        throw new AppError('INVALID_INPUT', 'limit cannot exceed pages × 10. Increase pages or omit it to infer the depth from limit.');
+    return { maxResults, limit };
+}

package/dist/src/seo-contract.d.ts

@@ -0,0 +1,101 @@
+/** Public report contracts only. Provider credentials and storage stay in the private service. */
+import { z } from 'zod';
+export declare const SEO_REPORT_HEADER = "X-GeoRanker-SEO-Tools";
+export declare const SEO_REPORT_CATALOG = "reports-v1";
+export declare const SEO_REPORT_KINDS: readonly ["rank_tracking", "onpage", "broken_links", "backlinks", "keyword_volume"];
+export type SeoReportKind = typeof SEO_REPORT_KINDS[number];
+export declare const SEO_INPUT_SCHEMAS: {
+    readonly create_rank_tracking_report: z.ZodObject<{
+        campaignName: z.ZodOptional<z.ZodString>;
+        reportName: z.ZodDefault<z.ZodString>;
+        targetDomain: z.ZodString;
+        keywords: z.ZodArray<z.ZodString>;
+        locations: z.ZodArray<z.ZodString>;
+        engines: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        device: z.ZodDefault<z.ZodEnum<{
+            desktop: "desktop";
+            mobile: "mobile";
+        }>>;
+        trackTop: z.ZodDefault<z.ZodNumber>;
+        isRecurring: z.ZodDefault<z.ZodBoolean>;
+        scheduleDays: z.ZodOptional<z.ZodNumber>;
+        fetchKeywordData: z.ZodDefault<z.ZodBoolean>;
+        forceLive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+    readonly get_rank_tracking_report: z.ZodObject<{
+        reportId: z.ZodString;
+    }, z.core.$strict>;
+    readonly update_rank_tracking_schedule: z.ZodObject<{
+        reportId: z.ZodString;
+        isRecurring: z.ZodBoolean;
+        scheduleDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    readonly create_onpage_report: z.ZodObject<{
+        campaignName: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+        devices: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            desktop: "desktop";
+            mobile: "mobile";
+        }>>>;
+        isRecurring: z.ZodDefault<z.ZodLiteral<false>>;
+        forceLive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+    readonly get_onpage_report: z.ZodObject<{
+        reportId: z.ZodString;
+    }, z.core.$strict>;
+    readonly create_broken_links_report: z.ZodObject<{
+        campaignName: z.ZodOptional<z.ZodString>;
+        url: z.ZodString;
+        scope: z.ZodDefault<z.ZodEnum<{
+            site: "site";
+            page: "page";
+            domain: "domain";
+        }>>;
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        maxPages: z.ZodDefault<z.ZodNumber>;
+        checkExternalLinks: z.ZodDefault<z.ZodLiteral<false>>;
+        forceLive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+    readonly get_broken_links_report: z.ZodObject<{
+        reportId: z.ZodString;
+    }, z.core.$strict>;
+    readonly create_backlinks_report: z.ZodObject<{
+        campaignName: z.ZodOptional<z.ZodString>;
+        target: z.ZodString;
+        endpoint: z.ZodDefault<z.ZodEnum<{
+            backlinks: "backlinks";
+            summary: "summary";
+            referring_domains: "referring_domains";
+            anchors: "anchors";
+            history: "history";
+            timeseries_new_lost: "timeseries_new_lost";
+            competitors: "competitors";
+            domain_pages: "domain_pages";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+        forceLive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+    readonly get_backlinks_report: z.ZodObject<{
+        reportId: z.ZodString;
+    }, z.core.$strict>;
+    readonly create_keyword_volume_report: z.ZodObject<{
+        campaignName: z.ZodOptional<z.ZodString>;
+        name: z.ZodDefault<z.ZodString>;
+        keywords: z.ZodArray<z.ZodString>;
+        location: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+        endpoint: z.ZodOptional<z.ZodString>;
+        forceLive: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>;
+    readonly get_keyword_volume_report: z.ZodObject<{
+        reportId: z.ZodString;
+    }, z.core.$strict>;
+};
+export type SeoToolName = keyof typeof SEO_INPUT_SCHEMAS;
+export declare const SEO_TOOL_NAMES: SeoToolName[];
+export declare function parseSeoInput(name: SeoToolName, input: unknown): Record<string, unknown>;
+export declare function seoAdmissionUnits(name: SeoToolName, raw: unknown): number;
+export declare const SEO_TOOL_DESCRIPTIONS: Record<SeoToolName, {
+    title: string;
+    description: string;
+}>;

package/dist/src/seo-contract.js

@@ -0,0 +1,105 @@
+/** Public report contracts only. Provider credentials and storage stay in the private service. */
+import { z } from 'zod';
+import { AppError } from './errors.js';
+export const SEO_REPORT_HEADER = 'X-GeoRanker-SEO-Tools';
+export const SEO_REPORT_CATALOG = 'reports-v1';
+export const SEO_REPORT_KINDS = ['rank_tracking', 'onpage', 'broken_links', 'backlinks', 'keyword_volume'];
+const text = z.string().trim().min(1).max(500);
+const publicUrl = z.string().trim().max(2048).url().regex(/^https?:\/\//i);
+const forceLive = z.boolean().default(false).describe('Bypass completed-result reuse (seven days by default). Retain unresolved work instead of creating a duplicate report.');
+const reportId = z.string().regex(/^seo_[a-f0-9-]{36}$/).describe('The MCP reportId returned by the matching create tool, not a provider report ID.');
+const campaignName = z.string().trim().min(2).max(120).regex(/^[^\u0000-\u001f\u007f]+$/).optional().describe('Campaign name within your own account. Omit to use this installation’s default campaign. A name never grants access to another user’s campaign. Campaign assignment must be supported by the report provider.');
+const scheduleDays = z.number().int().min(1).max(365).optional();
+const lookup = z.object({ reportId }).strict();
+export const SEO_INPUT_SCHEMAS = {
+    create_rank_tracking_report: z.object({
+        campaignName,
+        reportName: text.default('MCP rank tracking'),
+        targetDomain: text.describe('Public domain whose ranking is tracked.'),
+        keywords: z.array(text).min(1).max(200),
+        locations: z.array(z.string().trim().min(1).max(200)).min(1).max(50).describe('Location names, for example Bucharest, Romania. Every keyword is checked in every location and engine.'),
+        engines: z.array(z.string().trim().min(1).max(50)).min(1).max(10).default(['google']),
+        device: z.enum(['desktop', 'mobile']).default('desktop'),
+        trackTop: z.number().int().min(1).max(100).default(10),
+        isRecurring: z.boolean().default(false).describe('Enable provider-managed recurring work only when explicitly requested. Future runs can consume credits.'),
+        scheduleDays,
+        fetchKeywordData: z.boolean().default(false),
+        forceLive,
+    }).strict().refine(value => !value.isRecurring || value.scheduleDays !== undefined, { message: 'Set scheduleDays explicitly when enabling recurring tracking.', path: ['scheduleDays'] }),
+    get_rank_tracking_report: lookup,
+    update_rank_tracking_schedule: z.object({ reportId, isRecurring: z.boolean(), scheduleDays }).strict()
+        .refine(value => !value.isRecurring || value.scheduleDays !== undefined, { message: 'Set scheduleDays explicitly when enabling recurring tracking.', path: ['scheduleDays'] }),
+    create_onpage_report: z.object({
+        campaignName,
+        url: publicUrl,
+        devices: z.array(z.enum(['mobile', 'desktop'])).min(1).max(2).default(['mobile', 'desktop']),
+        isRecurring: z.literal(false).default(false),
+        forceLive,
+    }).strict(),
+    get_onpage_report: lookup,
+    create_broken_links_report: z.object({
+        campaignName,
+        url: publicUrl,
+        scope: z.enum(['site', 'page', 'domain']).default('site').describe('Use site for a bounded site crawl or page for analysis of links on the supplied page. The legacy domain value is a deprecated alias for site. Path-restricted crawling is unsupported; do not substitute a different coverage without the user choosing it.'),
+        maxDepth: z.number().int().min(1).max(10).default(2).describe('Maximum crawl depth; MCP limit 10.'),
+        maxPages: z.number().int().min(1).max(1000).default(20).describe('Maximum pages to crawl; MCP limit 1000. Each block of up to 100 requested pages counts as one shared admission unit (rounded up). Keep the user-requested crawl coverage.'),
+        checkExternalLinks: z.literal(false).default(false).describe('Return internal link and resource checks only. Output states the hostname boundary, excluded rows and actual crawl coverage.'),
+        forceLive,
+    }).strict(),
+    get_broken_links_report: lookup,
+    create_backlinks_report: z.object({
+        campaignName,
+        target: z.string().trim().min(1).max(2048).describe('Public domain or URL to analyze.'),
+        endpoint: z.enum(['summary', 'backlinks', 'referring_domains', 'anchors', 'history', 'timeseries_new_lost', 'competitors', 'domain_pages']).default('summary'),
+        name: text.optional(),
+        forceLive,
+    }).strict(),
+    get_backlinks_report: lookup,
+    create_keyword_volume_report: z.object({
+        campaignName,
+        name: text.default('MCP keyword volumes'),
+        keywords: z.array(text).min(1).max(200).describe('Keywords for the volume report; MCP limit 200.'),
+        location: z.string().trim().min(1).max(200).optional(),
+        provider: z.string().trim().min(1).max(100).optional().describe('Documented SEO API provider identifier. Omit to use the operator-configured volume provider.'),
+        endpoint: z.string().trim().min(1).max(100).optional().describe('Documented volume endpoint identifier. Omit to use the operator-configured volume endpoint.'),
+        forceLive,
+    }).strict(),
+    get_keyword_volume_report: lookup,
+};
+export const SEO_TOOL_NAMES = Object.keys(SEO_INPUT_SCHEMAS);
+export function parseSeoInput(name, input) {
+    if (name === 'create_broken_links_report' && input && typeof input === 'object' && 'scope' in input && input.scope === 'path') {
+        throw new AppError('INVALID_INPUT', 'Broken-link scope "path" is unsupported. Choose "site" for a bounded site crawl or "page" to analyze links on the supplied page. Ask the user to choose the intended coverage; do not silently replace a path restriction.', undefined, { field: 'scope', allowedValues: ['site', 'page'], submissionUncertain: false });
+    }
+    const result = SEO_INPUT_SCHEMAS[name]?.safeParse(input);
+    if (!result?.success)
+        throw new AppError('INVALID_INPUT', 'Report arguments do not match the tool schema. Check required fields, report ID, batch limits and schedule.');
+    if (name === 'create_broken_links_report' && 'scope' in result.data && result.data.scope === 'domain')
+        return { ...result.data, scope: 'site' };
+    return result.data;
+}
+export function seoAdmissionUnits(name, raw) {
+    const input = parseSeoInput(name, raw);
+    if (name === 'create_rank_tracking_report')
+        return input.keywords.length * input.locations.length * input.engines.length;
+    if (name === 'create_broken_links_report')
+        return Math.ceil(input.maxPages / 100);
+    if (name === 'create_keyword_volume_report')
+        return input.keywords.length;
+    if (name === 'create_onpage_report')
+        return input.devices.length;
+    return 1;
+}
+export const SEO_TOOL_DESCRIPTIONS = {
+    create_rank_tracking_report: { title: 'Track rankings across keywords and locations', description: 'Create a domain rank report for multiple keywords, locations and engines. Requested checks are keywords × locations × engines and consume the shared allowance. Optional recurring tracking must be explicitly requested and enabled by the operator; future provider runs can consume credits. Use get_rank_tracking_report for the returned reportId.' },
+    get_rank_tracking_report: { title: 'Get rank tracking report', description: 'Retrieve an owned rank tracking report and its keyword results, without creating another report. Preserve checked coverage and provider timestamps; do not infer absent rankings.' },
+    update_rank_tracking_schedule: { title: 'Update rank tracking schedule', description: 'Enable, change or stop provider-managed recurring tracking for an owned report. Enabling requires an explicit interval and can cause future credit-consuming runs. This changes persistent report settings; use only when requested.' },
+    create_onpage_report: { title: 'Run Lighthouse on-page SEO analysis', description: 'Create a Lighthouse/PSI report for one public URL on mobile, desktop or both. This audits the specified page; it is not a site-wide crawl. Use get_onpage_report for the returned reportId.' },
+    get_onpage_report: { title: 'Get Lighthouse SEO report', description: 'Retrieve an owned Lighthouse/PSI summary with category scores, audit findings, explanations, metrics and completion status for each requested device. Missing devices are named explicitly. Embedded screenshots and detailed audit/resource tables are omitted and labeled. Does not run a new audit.' },
+    create_broken_links_report: { title: 'Analyze broken internal links', description: 'Analyze internal links with a bounded site crawl (scope site, the default) or links on the supplied page (scope page). The old domain scope is accepted as an alias for site; path-restricted crawling is unsupported. External-link checking is disabled. Each block of up to 100 requested pages uses one shared admission unit. Keep the user-requested coverage; do not silently shrink it to fit an allowance or change a path restriction to another scope. Use get_broken_links_report for the returned reportId.' },
+    get_broken_links_report: { title: 'Get broken internal links report', description: 'Retrieve internal link and resource checks without re-running the crawl. Coverage separates returned internal rows from provider totals and excluded external rows. A completed bounded crawl does not establish full-site navigation coverage; HTTP 403 means access denied, not necessarily a missing page.' },
+    create_backlinks_report: { title: 'Create backlink intelligence report', description: 'Request backlink summary, backlinks, referring domains, anchors, history, new/lost timeseries, competitors or domain pages for a public target. New reports can consume provider credits. Use get_backlinks_report for the returned reportId.' },
+    get_backlinks_report: { title: 'Get backlink report', description: 'Retrieve an owned backlink report and provider results without creating another report. Preserve report type, timestamps and actual coverage. Ready means the requested response is available; coverage states returned rows versus provider totals. These tools do not export additional provider pages.' },
+    create_keyword_volume_report: { title: 'Research keyword search volumes', description: 'Create a keyword report using the configured volume provider and endpoint, or explicitly supplied documented identifiers. Supports multiple keywords and an optional location. New work can consume credits. Use get_keyword_volume_report for the returned reportId.' },
+    get_keyword_volume_report: { title: 'Get keyword volume report', description: 'Retrieve an owned keyword report and its provider data without creating another report. Only describe volume, date, units and location actually returned by the provider.' },
+};

package/dist/src/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ProductProfile, type SearchServiceLike } from './product-contract.js';
+export { SERVER_VERSION } from './product-contract.js';
+export type { SearchInput, SearchResultInput, FetchPageInput, SearchServiceLike } from './product-contract.js';
+export declare function createServer(service: SearchServiceLike, profile?: ProductProfile, options?: {
+    seoReports?: boolean;
+}): McpServer;