@hzlmy2002/web-market 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+export declare const domain: z.ZodEffects<z.ZodString, string, string>;
+export declare const month: z.ZodString;
+export declare const domains: z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>;
+export declare const inputs: {
+    AIsa_similar_sites: z.ZodObject<{
+        country: z.ZodDefault<z.ZodEnum<["us", "ww"]>>;
+        max_price_usd: z.ZodOptional<z.ZodNumber>;
+        domain: z.ZodEffects<z.ZodString, string, string>;
+        end_month: z.ZodString;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        domain: string;
+        end_month: string;
+        limit: number;
+        country: "us" | "ww";
+        max_price_usd?: number | undefined;
+    }, {
+        domain: string;
+        end_month: string;
+        limit?: number | undefined;
+        country?: "us" | "ww" | undefined;
+        max_price_usd?: number | undefined;
+    }>;
+    AIsa_traffic_engagement: z.ZodObject<{
+        country: z.ZodDefault<z.ZodEnum<["us", "ww"]>>;
+        max_price_usd: z.ZodOptional<z.ZodNumber>;
+        domains: z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>;
+        start_month: z.ZodString;
+        end_month: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        end_month: string;
+        country: "us" | "ww";
+        domains: string[];
+        start_month: string;
+        max_price_usd?: number | undefined;
+    }, {
+        end_month: string;
+        domains: string[];
+        start_month: string;
+        country?: "us" | "ww" | undefined;
+        max_price_usd?: number | undefined;
+    }>;
+    AIsa_geography: z.ZodObject<{
+        domains: z.ZodEffects<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">, string[], string[]>;
+        max_price_usd: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        domains: string[];
+        max_price_usd?: number | undefined;
+    }, {
+        domains: string[];
+        max_price_usd?: number | undefined;
+    }>;
+    AIsa_website_keywords: z.ZodObject<{
+        country: z.ZodDefault<z.ZodEnum<["us", "ww"]>>;
+        max_price_usd: z.ZodOptional<z.ZodNumber>;
+        domain: z.ZodEffects<z.ZodString, string, string>;
+        month: z.ZodString;
+        limit: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        domain: string;
+        limit: number;
+        country: "us" | "ww";
+        month: string;
+        max_price_usd?: number | undefined;
+    }, {
+        domain: string;
+        month: string;
+        limit?: number | undefined;
+        country?: "us" | "ww" | undefined;
+        max_price_usd?: number | undefined;
+    }>;
+    AIsa_keyword_gap: z.ZodObject<{
+        country: z.ZodDefault<z.ZodEnum<["us", "ww"]>>;
+        max_price_usd: z.ZodOptional<z.ZodNumber>;
+        target_domain: z.ZodEffects<z.ZodString, string, string>;
+        competitor_domains: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+        month: z.ZodString;
+        limit_per_domain: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        country: "us" | "ww";
+        month: string;
+        target_domain: string;
+        competitor_domains: string[];
+        limit_per_domain: number;
+        max_price_usd?: number | undefined;
+    }, {
+        month: string;
+        target_domain: string;
+        competitor_domains: string[];
+        country?: "us" | "ww" | undefined;
+        max_price_usd?: number | undefined;
+        limit_per_domain?: number | undefined;
+    }>;
+};
+export type ToolName = keyof typeof inputs;
+export declare const output: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1.0.0">;
+    scope: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+    derived: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+    completeness: z.ZodObject<{
+        status: z.ZodEnum<["complete", "partial", "empty"]>;
+        requested_items: z.ZodArray<z.ZodString, "many">;
+        returned_items: z.ZodArray<z.ZodString, "many">;
+        failures: z.ZodArray<z.ZodObject<{
+            domain: z.ZodString;
+            code: z.ZodString;
+            message: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            code: string;
+            message: string;
+            domain: string;
+        }, {
+            code: string;
+            message: string;
+            domain: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        status: "complete" | "partial" | "empty";
+        requested_items: string[];
+        returned_items: string[];
+        failures: {
+            code: string;
+            message: string;
+            domain: string;
+        }[];
+    }, {
+        status: "complete" | "partial" | "empty";
+        requested_items: string[];
+        returned_items: string[];
+        failures: {
+            code: string;
+            message: string;
+            domain: string;
+        }[];
+    }>;
+    provenance: z.ZodArray<z.ZodObject<{
+        domain: z.ZodString;
+        endpoint: z.ZodString;
+        retrieved_at: z.ZodString;
+        data_as_of: z.ZodNullable<z.ZodString>;
+        reported_scope: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        status: z.ZodEnum<["success", "empty", "failed"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "success" | "empty" | "failed";
+        domain: string;
+        endpoint: string;
+        retrieved_at: string;
+        data_as_of: string | null;
+        reported_scope: Record<string, unknown>;
+    }, {
+        status: "success" | "empty" | "failed";
+        domain: string;
+        endpoint: string;
+        retrieved_at: string;
+        data_as_of: string | null;
+        reported_scope: Record<string, unknown>;
+    }>, "many">;
+    calculation: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    warnings: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    data: Record<string, unknown>[];
+    schema_version: "1.0.0";
+    scope: Record<string, unknown>;
+    derived: Record<string, unknown>[];
+    completeness: {
+        status: "complete" | "partial" | "empty";
+        requested_items: string[];
+        returned_items: string[];
+        failures: {
+            code: string;
+            message: string;
+            domain: string;
+        }[];
+    };
+    provenance: {
+        status: "success" | "empty" | "failed";
+        domain: string;
+        endpoint: string;
+        retrieved_at: string;
+        data_as_of: string | null;
+        reported_scope: Record<string, unknown>;
+    }[];
+    calculation: Record<string, unknown>;
+    warnings: string[];
+}, {
+    data: Record<string, unknown>[];
+    schema_version: "1.0.0";
+    scope: Record<string, unknown>;
+    derived: Record<string, unknown>[];
+    completeness: {
+        status: "complete" | "partial" | "empty";
+        requested_items: string[];
+        returned_items: string[];
+        failures: {
+            code: string;
+            message: string;
+            domain: string;
+        }[];
+    };
+    provenance: {
+        status: "success" | "empty" | "failed";
+        domain: string;
+        endpoint: string;
+        retrieved_at: string;
+        data_as_of: string | null;
+        reported_scope: Record<string, unknown>;
+    }[];
+    calculation: Record<string, unknown>;
+    warnings: string[];
+}>;
+export type Result = z.infer<typeof output>;
+export declare function monthIndex(m: string): number;
+export declare function fromIndex(i: number): string;
+export declare function windowMonths(start: string, end: string): string[];

package/dist/schema.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { isIP } from 'node:net';
+export const domain = z.string().max(2048).transform((input, ctx) => {
+    try {
+        const u = new URL(input.includes('://') ? input : `https://${input}`);
+        const d = u.hostname.toLowerCase().replace(/\.$/, '');
+        if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password || u.port || isIP(d) || d.startsWith('[') || !d.includes('.') || /\.(localhost|local|internal|test|invalid)$/.test(d) || d.length > 253 || !d.split('.').every(s => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(s)))
+            throw Error();
+        return d;
+    }
+    catch {
+        ctx.addIssue({ code: 'custom', message: 'Provide a public website domain or HTTP(S) URL without credentials or port.' });
+        return z.NEVER;
+    }
+});
+export const month = z.string().regex(/^20\d{2}-(0[1-9]|1[0-2])$/);
+export const domains = z.array(domain).min(1).max(5).refine(a => new Set(a).size === a.length, 'Domains must be unique after normalization.');
+const country = z.enum(['us', 'ww']).default('ww');
+const cap = z.number().finite().positive().max(1_000_000).optional().describe('Optional TOTAL USD ceiling for this tool invocation, split across its planned API calls.');
+const common = { country, max_price_usd: cap };
+export const inputs = {
+    AIsa_similar_sites: z.object({ domain, end_month: month.describe('Latest supported month for Similar Sites. Requests exactly this month and the two preceding months.'), limit: z.number().int().min(1).max(20).default(10), ...common }).strict(),
+    AIsa_traffic_engagement: z.object({ domains, start_month: month, end_month: month, ...common }).strict(),
+    AIsa_geography: z.object({ domains, max_price_usd: cap }).strict(),
+    AIsa_website_keywords: z.object({ domain, month, limit: z.number().int().min(1).max(20).default(20), ...common }).strict(),
+    AIsa_keyword_gap: z.object({ target_domain: domain, competitor_domains: z.array(domain).min(1).max(3), month, limit_per_domain: z.number().int().min(1).max(20).default(20), ...common }).strict(),
+};
+export const output = z.object({
+    schema_version: z.literal('1.0.0'), scope: z.record(z.unknown()),
+    data: z.array(z.record(z.unknown())), derived: z.array(z.record(z.unknown())),
+    completeness: z.object({ status: z.enum(['complete', 'partial', 'empty']), requested_items: z.array(z.string()), returned_items: z.array(z.string()), failures: z.array(z.object({ domain: z.string(), code: z.string(), message: z.string() })) }),
+    provenance: z.array(z.object({ domain: z.string(), endpoint: z.string(), retrieved_at: z.string(), data_as_of: z.string().nullable(), reported_scope: z.record(z.unknown()), status: z.enum(['success', 'empty', 'failed']) })),
+    calculation: z.record(z.unknown()), warnings: z.array(z.string()),
+});
+export function monthIndex(m) { const [y, n] = m.split('-').map(Number); return y * 12 + n - 1; }
+export function fromIndex(i) { return `${Math.floor(i / 12)}-${String(i % 12 + 1).padStart(2, '0')}`; }
+export function windowMonths(start, end) { return Array.from({ length: monthIndex(end) - monthIndex(start) + 1 }, (_, i) => fromIndex(monthIndex(start) + i)); }

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Transport } from './api.js';
+export declare function createServer(api?: Transport): McpServer;

package/dist/server.js

@@ -0,0 +1,20 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ApiClient, safeError } from './api.js';
+import { inputs, output } from './schema.js';
+import { execute, descriptions } from './tools.js';
+export function createServer(api = new ApiClient()) {
+    const server = new McpServer({ name: 'aisa-web-market', version: '0.1.0' }, { instructions: 'Website competitive analysis using five AIsa tools. Use the installed aisa-web-market skill for scenario guidance. Compare identical scope and preserve missing-data evidence. API calls are billed. Credentials come from AISA_API_KEY; never request the key in conversation.' });
+    for (const name of Object.keys(inputs)) {
+        server.registerTool(name, { description: descriptions[name], inputSchema: inputs[name], outputSchema: output.shape, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true } }, async (args, extra) => {
+            try {
+                const result = output.parse(await execute(name, args, api, extra.signal));
+                return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+            }
+            catch (e) {
+                const err = safeError(e);
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: { code: err.code, message: err.message, retryable: err.retryable, ...(err.status === undefined ? {} : { http_status: err.status }) } }) }] };
+            }
+        });
+    }
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,4 @@
+import { type Transport } from './api.js';
+import { type ToolName, type Result } from './schema.js';
+export declare const descriptions: Record<ToolName, string>;
+export declare function execute(name: ToolName, raw: unknown, api: Transport, signal?: AbortSignal): Promise<Result>;

package/dist/tools.js

@@ -0,0 +1,182 @@
+import { ApiError, paths, safeError } from './api.js';
+import { inputs, monthIndex, fromIndex, windowMonths } from './schema.js';
+export const descriptions = {
+    AIsa_similar_sites: 'Find similar website candidates for one domain. Returns domain, affinity and rank; similarity is not proof of a business competitor. Requires the latest supported end_month; fetches exactly three months. Up to 20 candidates. Use traffic_engagement for subsequent comparison. Billed AIsa API call.',
+    AIsa_traffic_engagement: 'Compare 1–5 domains over the SAME explicit monthly window (1–12 months), country and total web scope. Returns aligned visits, pages/visit, duration seconds, bounce-rate fractions, missing values and endpoint growth. Estimates, not first-party analytics. No cross-period averaging of rates. Billed once per domain.',
+    AIsa_geography: 'Fetch latest available worldwide traffic geography for 1–5 domains, at most 10 countries per domain. Returns country shares, visits and reported dates. Dates may differ between domains; no historical or country filter. Use only when geography is requested. Billed once per domain.',
+    AIsa_website_keywords: 'Read one website keyword sample for an explicit month, US or worldwide. At most 20 keywords with clicks, traffic share, position, intent and top URL when available. The API does not expose organic/nonbranded filters or volume/difficulty; do not infer them. For comparing sites use keyword_gap. Billed API call.',
+    AIsa_keyword_gap: 'Compare one target and 1–3 competitors using same-month, same-country keyword samples (max 20/site). Returns per-site evidence and deterministic position classes. competitor_only_in_sample means absent from a successful target SAMPLE, not no rankings. No organic/nonbranded filter, volume or difficulty guarantee. Does not generate content strategy. Billed once per domain.',
+};
+const numeric = (v) => typeof v === 'number' && Number.isFinite(v) ? v : null;
+const text = (v) => typeof v === 'string' ? v : null;
+function reportedScope(body) {
+    const source = body?.meta?.request ?? body?.meta ?? {};
+    return Object.fromEntries(['domain', 'country', 'start_date', 'end_date', 'granularity', 'web_source', 'main_domain_only', 'traffic_source', 'branded_type'].filter(k => ['string', 'boolean', 'number'].includes(typeof source[k])).map(k => [k, source[k]]));
+}
+function rows(body) {
+    if (!Array.isArray(body.data))
+        throw new ApiError('invalid_response', 'Expected an array of data rows.');
+    const flat = body.data.flat();
+    if (flat.some(x => !x || typeof x !== 'object' || Array.isArray(x)))
+        throw new ApiError('invalid_response', 'Invalid data row.');
+    return flat;
+}
+function keywords(body, limit) {
+    const seen = new Set();
+    return rows(body).slice(0, limit).map(r => {
+        if (typeof r.keyword !== 'string' || !r.keyword.trim())
+            throw new ApiError('invalid_response', 'Keyword row has no keyword.');
+        const key = r.keyword.normalize('NFKC').trim().toLowerCase();
+        if (seen.has(key))
+            throw new ApiError('invalid_response', 'Duplicate normalized keyword in sample.');
+        seen.add(key);
+        return { keyword: r.keyword, normalized_keyword: key, clicks: numeric(r.clicks), traffic_share: numeric(r.traffic_share), position: numeric(r.position), competition: numeric(r.competition), primary_intent: text(r.primary_intent), secondary_intent: text(r.secondary_intent), top_url: text(r.top_url) };
+    });
+}
+const metrics = { visits: 'visits', pages_per_visit: 'pages_per_visit', average_visit_duration_seconds: 'average_visit_duration', bounce_rate: 'bounce_rate' };
+export async function execute(name, raw, api, signal) {
+    const parsed = inputs[name].safeParse(raw);
+    if (!parsed.success)
+        throw new ApiError('invalid_input', parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`).join('; '));
+    const a = parsed.data;
+    if (name === 'AIsa_traffic_engagement' && (monthIndex(a.end_month) < monthIndex(a.start_month) || monthIndex(a.end_month) - monthIndex(a.start_month) >= 12))
+        throw new ApiError('invalid_input', 'Traffic window must cover 1–12 consecutive months.');
+    const ds = a.domains ?? (a.target_domain ? [a.target_domain, ...a.competitor_domains] : [a.domain]);
+    if (new Set(ds).size !== ds.length)
+        throw new ApiError('invalid_input', 'Target and competitor domains must all be distinct.');
+    const endpoint = name === 'AIsa_traffic_engagement' ? paths.traffic : name === 'AIsa_similar_sites' ? paths.similar : name === 'AIsa_geography' ? paths.geography : paths.keywords;
+    const scope = { ...a };
+    delete scope.max_price_usd;
+    if (name === 'AIsa_geography')
+        Object.assign(scope, { country: 'ww', time: 'latest_available_per_domain' });
+    else
+        Object.assign(scope, { web_source: 'total', granularity: 'monthly' });
+    if (name === 'AIsa_similar_sites')
+        scope.start_month = fromIndex(monthIndex(a.end_month) - 2);
+    if (endpoint === paths.keywords)
+        Object.assign(scope, { traffic_source: 'upstream_default', branded_type: 'upstream_default', sample_limit: a.limit ?? a.limit_per_domain });
+    const result = { schema_version: '1.0.0', scope, data: [], derived: [], completeness: { status: 'complete', requested_items: ds, returned_items: [], failures: [] }, provenance: [], calculation: {}, warnings: [] };
+    // Divide the total ceiling into integer nanodollars, rounding DOWN. No retry can spend a second slice.
+    const perCallCap = a.max_price_usd === undefined ? undefined : Math.floor(a.max_price_usd * 1e9 / ds.length) / 1e9;
+    if (perCallCap !== undefined && perCallCap <= 0)
+        throw new ApiError('cost_limit_exceeded', 'Budget is too small to divide across the requested domains.');
+    const records = new Map();
+    const outcomes = new Array(ds.length);
+    let cursor = 0;
+    const runSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(60_000)]) : AbortSignal.timeout(60_000);
+    await Promise.all(Array.from({ length: Math.min(3, ds.length) }, async () => {
+        while (cursor < ds.length) {
+            const i = cursor++;
+            const d = ds[i];
+            const at = new Date().toISOString();
+            try {
+                runSignal.throwIfAborted();
+                let query = { domain: d, country: a.country, web_source: 'total', granularity: 'monthly' };
+                if (endpoint === paths.traffic)
+                    Object.assign(query, { start_date: a.start_month, end_date: a.end_month, metrics: Object.values(metrics).join(','), main_domain_only: true });
+                else if (endpoint === paths.similar)
+                    Object.assign(query, { start_date: scope.start_month, end_date: a.end_month, limit: a.limit });
+                else if (endpoint === paths.keywords)
+                    Object.assign(query, { start_date: a.month, end_date: a.month, limit: a.limit ?? a.limit_per_domain });
+                else
+                    query = { domain: d };
+                const body = await api.get(endpoint, query, perCallCap, runSignal);
+                const reported = body.meta?.request ?? body.meta ?? {};
+                if (endpoint !== paths.geography) {
+                    for (const key of ['country', 'web_source', 'start_date', 'end_date']) {
+                        if (typeof reported[key] === 'string' && query[key] !== undefined && (key.endsWith('date') ? reported[key].slice(0, 7) : reported[key]) !== query[key])
+                            throw new ApiError('scope_mismatch', 'Upstream returned a different scope than requested.');
+                    }
+                }
+                let data;
+                if (endpoint === paths.keywords)
+                    data = keywords(body, a.limit ?? a.limit_per_domain);
+                else if (endpoint === paths.geography) {
+                    if (!Array.isArray(body.data?.countries))
+                        throw new ApiError('invalid_response', 'Expected a countries array.');
+                    data = body.data.countries.slice(0, 10).map((r) => ({ country_code: text(r.country_code), country_name: text(r.country_name), share: numeric(r.share), visits: numeric(r.visits) }));
+                }
+                else if (endpoint === paths.similar)
+                    data = rows(body).slice(0, a.limit).map(r => ({ domain: text(r.domain), affinity: numeric(r.affinity), rank: numeric(r.rank), category: text(r.category) }));
+                else {
+                    const source = rows(body);
+                    const byMonth = new Map();
+                    for (const r of source) {
+                        const m = typeof r.date === 'string' ? r.date.slice(0, 7) : '';
+                        if (!/^20\d\d-(0[1-9]|1[0-2])$/.test(m) || byMonth.has(m) || m < a.start_month || m > a.end_month)
+                            throw new ApiError('invalid_response', 'Traffic periods are missing, duplicated or outside the requested window.');
+                        byMonth.set(m, r);
+                    }
+                    data = source.length ? windowMonths(a.start_month, a.end_month).map(period => ({ period, ...Object.fromEntries(Object.entries(metrics).map(([out, upstream]) => [out, numeric(byMonth.get(period)?.[upstream])])) })) : [];
+                }
+                outcomes[i] = { body, data, at };
+            }
+            catch (error) {
+                outcomes[i] = { error: runSignal.aborted ? new ApiError('cancelled', 'Tool deadline or cancellation interrupted the operation.') : safeError(error), at };
+            }
+        }
+    }));
+    for (let i = 0; i < ds.length; i++) {
+        const d = ds[i], o = outcomes[i];
+        result.provenance.push({ domain: d, endpoint, retrieved_at: o.at, data_as_of: text(o.body?.meta?.last_updated ?? o.body?.meta?.data_as_of), reported_scope: reportedScope(o.body), status: o.error ? 'failed' : o.data?.length ? 'success' : 'empty' });
+        if (o.body?.meta?.empty_reason === 'provider_no_data')
+            result.warnings.push(`${d}: Similarweb has no data for the requested scope. This is not an unavailable API or invalid credential.`);
+        if (o.error)
+            result.completeness.failures.push({ domain: d, code: o.error.code, message: o.error.message });
+        else {
+            records.set(d, o.data);
+            if (o.data.length)
+                result.completeness.returned_items.push(d);
+            if (name !== 'AIsa_keyword_gap')
+                result.data.push(...o.data.map(r => endpoint === paths.similar ? { seed_domain: d, ...r } : { domain: d, ...r }));
+        }
+    }
+    if (outcomes.every(o => o.error))
+        throw outcomes[0].error;
+    if (endpoint === paths.traffic) {
+        result.scope.main_domain_only = true;
+        for (const [d, rr] of records) {
+            if (!rr.length)
+                continue;
+            for (const metric of Object.keys(metrics)) {
+                const first = rr[0][metric], last = rr.at(-1)[metric];
+                const missing = rr.filter(r => r[metric] === null).map(r => r.period);
+                if (missing.length)
+                    result.warnings.push(`${d}: ${metric} missing in ${missing.join(', ')}.`);
+                result.derived.push({ domain: d, metric, start_period: a.start_month, end_period: a.end_month, start_value: first, end_value: last, absolute_change: first === null || last === null ? null : last - first, relative_change: first === null || last === null || first === 0 ? null : (last - first) / first });
+                if (first === 0 || first === null)
+                    result.warnings.push(`${d}: ${metric} growth is null because the baseline is zero or unknown.`);
+            }
+        }
+        result.calculation = { algorithm_version: 'traffic-derived-v1', relative_change: '(end_value-start_value)/start_value', rate_unit: 'fraction', duration_unit: 'seconds', aggregation: 'no cross-period averaging' };
+    }
+    if (endpoint === paths.keywords)
+        result.warnings.push('Top-N sample only; organic/nonbranded filters and volume/difficulty are not supported by the current AIsa contract. Competition is preserved as reported, not renamed to difficulty.');
+    if (name === 'AIsa_keyword_gap') {
+        const keys = new Set();
+        for (const d of a.competitor_domains)
+            for (const r of records.get(d) ?? [])
+                keys.add(r.normalized_keyword);
+        for (const key of [...keys].sort()) {
+            const evidence = ds.map(d => ({ domain: d, sample_status: records.has(d) ? (records.get(d).length ? 'returned' : 'empty') : 'failed', row: records.get(d)?.find(r => r.normalized_keyword === key) ?? null }));
+            const target = evidence[0].row;
+            const competitors = evidence.slice(1).flatMap(e => e.row ? [e.row] : []);
+            const positions = competitors.map(r => r.position).filter((p) => typeof p === 'number' && p > 0);
+            const best = positions.length ? Math.min(...positions) : null;
+            const delta = target && target.position > 0 && best !== null ? target.position - best : null;
+            // A failed or empty target response is not evidence of target absence.
+            const category = !records.get(a.target_domain)?.length ? 'insufficient_data' : !target ? 'competitor_only_in_sample' : delta === null ? 'insufficient_data' : delta >= 5 ? 'target_weaker' : delta <= -5 ? 'target_stronger' : 'similar_position';
+            result.data.push({ keyword: competitors[0].keyword, normalized_keyword: key, category, position_delta: delta, best_competitor_position: best, evidence, max_competitor_clicks: maxKnown(competitors.map(r => r.clicks)) });
+        }
+        const order = ['competitor_only_in_sample', 'target_weaker', 'similar_position', 'target_stronger', 'insufficient_data'];
+        result.data.sort((x, y) => order.indexOf(x.category) - order.indexOf(y.category) || (y.max_competitor_clicks ?? -1) - (x.max_competitor_clicks ?? -1) || (x.normalized_keyword < y.normalized_keyword ? -1 : x.normalized_keyword > y.normalized_keyword ? 1 : 0));
+        const targetRows = records.get(a.target_domain) ?? [];
+        result.calculation = { algorithm_version: 'keyword-gap-v1', position_threshold: 5, ranking: ['category', 'max_competitor_clicks_desc_null_last', 'normalized_keyword'], target_only_in_sample: targetRows.filter(r => !keys.has(r.normalized_keyword)).length };
+    }
+    if (endpoint === paths.geography)
+        result.warnings.push('Latest available per-domain snapshots may cover different months. Inspect provenance before comparing.');
+    const incomplete = result.completeness.failures.length > 0 || (result.completeness.returned_items.length > 0 && result.completeness.returned_items.length < ds.length) || (endpoint === paths.traffic && result.data.some(r => Object.keys(metrics).some(m => r[m] === null)));
+    result.completeness.status = incomplete ? 'partial' : result.data.length ? 'complete' : 'empty';
+    return result;
+}
+function maxKnown(values) { const ns = values.map(numeric).filter((n) => n !== null); return ns.length ? Math.max(...ns) : null; }

package/docs/contract.md

@@ -0,0 +1,25 @@
+# Contract 1.0.0
+
+The Node runtime calls https://api.aisa.one/apis/v1 using Authorization: Bearer from AISA_API_KEY. Credentials stay in the process environment. It does not call mcp.aisa.one. Upstream operation definitions and examples are pinned in upstream-snapshot.json; the docs checkout is source material, not runtime instructions.
+
+| Public tool | API GET path | Maximum API requests |
+|---|---|---|
+| AIsa_similar_sites | /similarweb/website/similar-sites | 1 |
+| AIsa_traffic_engagement | /similarweb/website/traffic-engagement | 5 |
+| AIsa_geography | /similarweb/website-top-geographies | 5 |
+| AIsa_website_keywords | /similarweb/search/website-keywords | 1 |
+| AIsa_keyword_gap | /similarweb/search/website-keywords | 4 |
+
+Traffic translates start_month/end_month to start_date/end_date; the runtime explicitly requests total web and main_domain_only=true and four metrics. The public window is limited to 12 buckets even though upstream allows 120. Similar Sites computes exactly three months ending at end_month. Keywords send the same month for start and end and flatten the documented grouped-array representation. Geography uses the product API's data.countries. Tool names are a separate public contract, not a renamed export of every upstream operation.
+
+Outputs have schema_version, scope, data, derived, completeness, provenance, calculation and warnings. Data row shapes depend on the tool; the MCP output schema validates the common envelope. Traffic rows include period and four numeric-or-null metrics. Keyword evidence preserves original text and normalized matching key. Scope defaults and absent filters are explicit. Provenance copies only allowlisted scope fields, never arbitrary upstream metadata. Missing update timestamps are null. Empty and partial responses are successful MCP results; if every request fails, the tool returns isError and a stable error code in text content.
+
+Traffic algorithm traffic-derived-v1 compares requested endpoints only, leaves growth null for zero/missing baselines and performs no cross-period averaging. Missing periods are inserted as null cells. Keyword-gap-v1 applies NFKC, trim and lowercase; it does not merge synonyms. Classification threshold is 5 positions. Target-only sample keywords are counted but not placed in the opportunity list. Missing/failed target samples never establish absence. Partial comparisons use only observed competitors and expose all failures.
+
+Bearer, request headers and arbitrary upstream error bodies are not returned. 402 is payment_required because the gateway can use it for subscription or credit restrictions. No per-endpoint prices are hardcoded. max_price_usd is divided among planned calls; tiny budgets that round to zero fail before requests. A network interruption is not automatically replayed.
+
+Remaining integration limits: no OAuth, no automatic publication-date discovery, no organic/nonbranded keyword filters, no live price estimation, no durable query cache, no interactive-client evals. See live-verification-2026-09-05.md for test-account evidence. HTTP bearer requests and sample parsing are verified using fixtures, including the docs' example envelopes.
+
+404 diagnostics: only the known gateway error `api endpoint not found` maps to unavailable_operation. Other 404 responses map to not_found without assuming route disablement, account permissions or missing domain data. Tool errors include http_status when known; arbitrary upstream messages are never forwarded. The aisa-mcp catalogue includes website-top-geographies but explicitly excludes website/traffic-geography and website/folders based on its 2026-08-26 production checks. This historical catalogue is not a live availability guarantee.
+
+Live-confirmed Similarweb no-data signature: HTTP 404, meta.status=error, numeric meta.error_code=401, meta.error_message="Data not found", data=null. This exact signature becomes an empty result with a warning; unknown provider errors are not reclassified as empty.

package/docs/live-verification-2026-09-05.md

@@ -0,0 +1,39 @@
+# Live API verification — 2026-09-05
+
+User-authorized test-account calls, no price cap. Key was passed through stdin, retained only in process memory, and is absent from artifacts. Scope: the five Node tools and their four REST dependencies; not the full AIsa catalogue.
+
+## Results
+
+9 HTTP requests: 7 HTTP 200, 2 HTTP 404. No automatic retries. Actual charges were not queried or independently verified. The snapshot product API was used once to establish the published month (2026-07).
+
+| Tool | Scope | Result |
+|---|---|---|
+| AIsa_geography | estk.me + wikipedia.org, latest | estk.me: provider Data not found; wikipedia.org: 10 countries |
+| AIsa_traffic_engagement | same domains, worldwide, 2026-07 | estk.me: provider Data not found; wikipedia.org: four metrics |
+| AIsa_similar_sites | wikipedia.org, 2026-05 through 2026-07 | 5 candidates |
+| AIsa_website_keywords | wikipedia.org, worldwide, 2026-07, limit 5 | 5 keywords |
+| AIsa_keyword_gap | wikipedia.org vs britannica.com, same month/country, 5 per domain | 5 competitor-only-in-sample rows |
+
+## Root cause and fix
+
+The geography endpoint is available for this test account. The failing domain returned HTTP 404 with `meta.status=error`, `meta.error_code=401`, `meta.error_message="Data not found"`, `data=null`. This provider code is not an HTTP 401 authentication failure. The control domain succeeded on the same endpoint. The same domain-specific no-data condition occurred on traffic. This establishes absence only for the requested dataset/scope, not that the site has no traffic.
+
+The Node client now recognizes this exact error signature and produces an empty successful result with a no-data warning and the reported scope. Mixed-domain calls preserve usable results and report partial coverage. Unknown 404s remain not_found, and explicit gateway route errors remain unavailable_operation. No-data behavior is regression-tested by replaying the captured responses.
+
+All fetched keyword positions were null. No ranking-delta comparison can be claimed from these samples. The returned traffic_source and branded_type were all; the samples cannot be described as organic/nonbranded-only.
+
+## Request trace
+
+| Path and query | HTTP | Request ID |
+|---|---|---|
+| `/similarweb/website-top-geographies?domain=estk.me` | 404 | `imc_664ccfae120ba90a9cb90cdb3edaa878f2d2624b8f1afdab60e0c4c502557be9` |
+| `/similarweb/website-top-geographies?domain=wikipedia.org` | 200 | `imc_31c75e88d94e357b961cdadab9c6c9881a55d3a2f226bbb5d07d580b2b1e0607` |
+| `/similarweb/website-traffic-snapshot?domain=wikipedia.org` | 200 | `imc_6f123b083918352aab0b1256be492ab0941718fc2f21801f6673733680c04902` |
+| `/similarweb/website/traffic-engagement?domain=wikipedia.org&country=ww&web_source=total&granularity=monthly&start_date=2026-07&end_date=2026-07&metrics=visits%2Cpages_per_visit%2Caverage_visit_duration%2Cbounce_rate&main_domain_only=true` | 200 | `imc_ac10c6761a978fa96ac426ede97c811c48946e642a1700157b3a10797044da93` |
+| `/similarweb/website/traffic-engagement?domain=estk.me&country=ww&web_source=total&granularity=monthly&start_date=2026-07&end_date=2026-07&metrics=visits%2Cpages_per_visit%2Caverage_visit_duration%2Cbounce_rate&main_domain_only=true` | 404 | `imc_1168e3e4c205968b222d4e4fc2eb8dd882ff3ea0ec7d4cb78fd914564d36abfe` |
+| `/similarweb/website/similar-sites?domain=wikipedia.org&country=ww&web_source=total&granularity=monthly&start_date=2026-05&end_date=2026-07&limit=5` | 200 | `imc_7c18c6db3bede7494232833473246d68f77a51be798b5082ea4802ed4b0e19c6` |
+| `/similarweb/search/website-keywords?domain=wikipedia.org&country=ww&web_source=total&granularity=monthly&start_date=2026-07&end_date=2026-07&limit=5` | 200 | `imc_ce3260cd2bd334600c3d48c8fdc1b6239cc6b7f264a819279ea4d5a271acb55b` |
+| `/similarweb/search/website-keywords?domain=wikipedia.org&country=ww&web_source=total&granularity=monthly&start_date=2026-07&end_date=2026-07&limit=5` | 200 | `imc_3c2aedb4d04bf4322b4dcea810194e08a14c395d6e31917fcbac011d2e33d3e6` |
+| `/similarweb/search/website-keywords?domain=britannica.com&country=ww&web_source=total&granularity=monthly&start_date=2026-07&end_date=2026-07&limit=5` | 200 | `imc_ec88005bbec5ed0b919c30fcd8d203ff662ca5354e0a052a1e0bc3d55ba4d0ec` |
+
+Full public-data response fixtures and pre-fix tool outputs are in `tests/fixtures/live-2026-09-05.json`. Updated behavior is verified in `tests/live-regression.test.mjs`. No interactive Codex/Claude/Hermes UI eval was performed in this run.