@bridgeline-digital/hawk-app-cli 0.0.0-stage → 0.1.0-dev.20261020202308

package/src/mcp-hawksearch.mjs

@@ -0,0 +1,342 @@
+// The MCP server's `hawksearch_api` tool: HawkSearch's own API reference (developerdocs.hawksearch.com), with what an app
+// can call of it and how. The operations come from the site's llms.txt; each operation's page embeds its OpenAPI
+// definition (path, parameters, body and response schemas), which is read when one operation is asked for. What apps
+// may call of it (which dashboard resources take writes, which Indexing API operations exist for apps, their scopes and
+// limits) is the platform's own GET /meta/rules (mcp-rules.mjs). Public docs: no key, no client data.
+import { FALLBACK } from './mcp-rules.mjs';
+
+export const INDEX_URL = 'https://developerdocs.hawksearch.com/llms.txt';
+const CACHE_MS = 10 * 60_000;
+const TIMEOUT_MS = 10_000;
+const MAX_TEXT = 8000;
+
+/** The bridge's own helpers for some Indexing API operations; the rest go through index.call(operation, body). */
+const INDEX_HELPERS = {
+    indexes: 'index.indexes()',
+    current: 'index.current()',
+    'index-items': 'index.items.upsert(items, { indexName })',
+    'update-items': 'index.items.update(items, { indexName })',
+    'delete-items': 'index.items.delete(ids, { indexName })',
+    create: "index.create({ suffix: 'spring' })",
+    'set-current': 'index.setCurrent(indexName)',
+    'delete-index': 'index.deleteIndex(indexName)',
+    'rebuild-all': 'index.rebuildAll(indexName)',
+};
+
+export const APIS = {
+    dashboard: 'Dashboard API: app.dashboard.get/post/put/delete',
+    search: 'Search API: app.hawksearch.search / autocomplete',
+    recommendations: 'Recommendation API: app.hawksearch.recommendations',
+    indexing: 'Indexing API: app.hawksearch.index',
+    tracking: 'Tracking API',
+};
+
+/** Which API an llms.txt "## API Reference: …" section is, or null for the overview. */
+function apiOf(section) {
+    if (/overview/i.test(section)) return null;
+    if (/hawksearch\.api\s*$/i.test(section)) return 'dashboard';
+    if (/search\s*api/i.test(section)) return 'search';
+    if (/recommend/i.test(section)) return 'recommendations';
+    if (/index/i.test(section)) return 'indexing';
+    if (/track/i.test(section)) return 'tracking';
+    return section.trim();
+}
+
+/** The API reference operations in llms.txt: [{ id, title, url, summary, api, group }]. */
+export function operationsIn(text) {
+    const operations = [];
+    let api = null;
+    let group = null;
+    // Some summaries hold a bare \r (a line break in HawkSearch's own text): part of the line, not the end of it.
+    for (const line of text.replace(/\r\n/g, '\n').replace(/\r/g, ' ').split('\n')) {
+        const section = /^## (.*)$/.exec(line);
+        if (section) {
+            const reference = /^API Reference:\s*(.+)$/.exec(section[1]);
+            api = reference ? apiOf(reference[1]) : null;
+            group = null;
+            continue;
+        }
+        if (!api) continue;
+        const heading = /^- ([^[\]]+?)\s*$/.exec(line);
+        if (heading) {
+            group = heading[1];
+            continue;
+        }
+        const link = /^\s*- \[(.+?)\]\((https:\/\/developerdocs\.hawksearch\.com\/reference\/([\w.-]+?)\.md)\)(?::\s*(.*))?$/.exec(line);
+        if (link) operations.push({ id: link[3], title: link[1], url: link[2], summary: stripHtml(link[4] ?? ''), api, group: group ?? '' });
+    }
+    return operations;
+}
+
+const stripHtml = (text) => text.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();
+
+/** What an app can do with a whole group of operations, for the list (the exact answer is per operation). */
+function groupAccess(api, group, rules) {
+    const name = group.toLowerCase();
+    switch (api) {
+        case 'dashboard':
+            if (name === 'index') return 'not through app.dashboard: app.hawksearch.index.rebuild() (hawksearch:index)';
+            if (name.startsWith('report')) return 'reads with hawksearch:read; for reporting prefer app.analytics.report() (analytics_reports)';
+            return writable(rules, name) ? 'reads hawksearch:read, writes hawksearch:write' : 'read only (hawksearch:read)';
+        case 'search':
+            if (name === 'searchv2') return 'app.hawksearch.search (hawksearch:search)';
+            if (name === 'autocompletev2') return 'app.hawksearch.autocomplete (hawksearch:search)';
+            return null;
+        case 'recommendations':
+            return rules.recommendations.available ? 'app.hawksearch.recommendations (hawksearch:recommendations)' : null;
+        case 'indexing':
+            if (['indexv2', 'hierarchy', 'mapping', 'embedding'].includes(name)) return 'some operations, scope per operation (hawksearch:index, :index:items, :index:manage)';
+            return null;
+        default:
+            return null;
+    }
+}
+
+const writable = (rules, resource) => rules.dashboard.writeResources.some((r) => r.toLowerCase() === resource.toLowerCase());
+
+function list(operations, api, rules, from) {
+    const apis = api ? [api] : [...new Set(operations.map((o) => o.api))];
+    const lines = [
+        `HawkSearch's API reference (${INDEX_URL}), with what apps can call through the bridge (the platform's rules, from ${from}).`,
+        api ? 'Call again with operation: "<id>" for its path, parameters, body and response fields, and the bridge call.' : 'Call again with api: "<name>" for each operation\'s title, or operation: "<id or words>" for one in full.',
+    ];
+    for (const name of apis) {
+        const ofApi = operations.filter((o) => o.api === name);
+        if (!ofApi.length) continue;
+        lines.push('', `## ${name}: ${APIS[name] ?? name}`);
+        for (const group of [...new Set(ofApi.map((o) => o.group))]) {
+            const ofGroup = ofApi.filter((o) => o.group === group);
+            const access = groupAccess(name, group, rules);
+            if (!access) {
+                lines.push(`- ${group || '(no group)'}: not available to apps (${ofGroup.length} operation${ofGroup.length === 1 ? '' : 's'})`);
+            } else if (api) {
+                lines.push(`- ${group}: ${access}`, ...ofGroup.map((o) => `  - ${o.id}: ${o.title}${o.summary && o.summary !== o.title ? ` (${o.summary.slice(0, 120)})` : ''}`));
+            } else {
+                lines.push(`- ${group}: ${access}. ${ofGroup.map((o) => o.id).join(', ')}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+
+/** The OpenAPI definition a reference page embeds (its first ```json block), or null. */
+export function definitionIn(markdown) {
+    const block = /```json\s*\n([\s\S]*?)\n```/.exec(markdown);
+    if (!block) return null;
+    try {
+        return JSON.parse(block[1]);
+    } catch {
+        return null;
+    }
+}
+
+const quote = (path) => (path.includes('{') ? `\`${path.replace(/\{(\w+)\}/g, (_, name) => `\${${name}}`)}\`` : `'${path}'`);
+
+/** A path with its {placeholders} blanked, to compare HawkSearch's paths with the platform's ({notificationId} vs {id}). */
+const shape = (path) => path.replace(/^\/+/, '').toLowerCase().replace(/\{[^}]*\}/g, '{}');
+
+/** How an app calls one operation under the platform's rules: { call, scope, note } or { unavailable }. */
+export function bridgeCall(api, method, path, rules = FALLBACK) {
+    const m = method.toUpperCase();
+    const rel = path.replace(/^\/+/, '');
+    if (api === 'dashboard') {
+        const { writeResources, writesPerMinute, maxBulkItems } = rules.dashboard;
+        const resourcePath = rel.replace(/^api\/(v\d+\/)?/i, '');
+        const resource = resourcePath.split('/')[0];
+        if (m === 'GET') return { call: `await app.dashboard.get(${quote(resourcePath)})`, scope: 'hawksearch:read', note: 'Query parameters go in { query: { … } } as the second argument.' };
+        if (resource.toLowerCase() === 'index') return { unavailable: 'Index rebuilds go through app.hawksearch.index.rebuild() (hawksearch:index, elevated), not the dashboard API.' };
+        if (!writable(rules, resource)) return { unavailable: `Writes to ${resource} aren't allowed (403 path_not_allowed): apps write only ${writeResources.join(', ')}.` };
+        if (m === 'DELETE' && resource.toLowerCase() === 'landingpage' && /^bulk/i.test(resourcePath.split('/')[1] ?? '')) return { unavailable: 'Bulk landing-page deletes are blocked (403 path_not_allowed).' };
+        const verb = m.toLowerCase();
+        return {
+            call: `await app.dashboard.${verb}(${quote(resourcePath)}${verb === 'delete' ? '' : ', body'})`,
+            scope: 'hawksearch:write (elevated)',
+            note: `Site keys only; ${writesPerMinute} writes a minute; bulk paths up to ${maxBulkItems} items; audit-logged, never retried.`,
+        };
+    }
+    if (api === 'search') {
+        const limit = `${rules.search.perMinute} calls a minute.`;
+        if (rel === 'api/v2/search') return { call: "await app.hawksearch.search({ Keyword: 'boots' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's; IsInPreview: true runs on the preview search API. ${limit}` };
+        if (rel === 'api/v2/autocomplete') return { call: "await app.hawksearch.autocomplete({ Keyword: 'boo' })", scope: 'hawksearch:search', note: `The platform sets ClientGuid to the engine's. ${limit}` };
+        return { unavailable: 'Apps can call only search and autocomplete of the Search API.' };
+    }
+    if (api === 'recommendations') {
+        const { available, perMinute, maxBulkWidgets } = rules.recommendations;
+        if (!available) return { unavailable: "This platform has no recommendation API set up (503 recommendations_not_configured)." };
+        const note = `The platform sets clientGuid, adds visitorId/visitId when you send none, and keeps the call out of the recommendation reports. ${perMinute} calls a minute.`;
+        if (rel === 'api/recommendation/v2/getwidgetitems') return { call: 'await app.hawksearch.recommendations({ widgetUids: [{ widgetGuid, uniqueId }] })', scope: 'hawksearch:recommendations', note };
+        if (rel === 'api/recommendation/v2/getbulkwidgetitems') return { call: 'await app.hawksearch.recommendations({ widgets: [ … ] })', scope: 'hawksearch:recommendations', note: `Up to ${maxBulkWidgets} widgets. ${note}` };
+        return { unavailable: 'Apps get recommendation widgets only (getwidgetitems and getbulkwidgetitems).' };
+    }
+    if (api === 'indexing') {
+        const { operations, maxItemsPerCall, maxIdsPerCall, itemWritesPerMinute, managePerMinute } = rules.indexing;
+        const found = operations.find((o) => o.method.toUpperCase() === m && shape(o.path) === shape(rel));
+        if (!found) return { unavailable: "Not on the platform's Indexing API list (group indexing, index templates, unset-current and internal endpoints are left out on purpose)." };
+        // The app's operation with HawkSearch's own placeholder names (embedding/status/{id} → `embedding/status/${notificationId}`).
+        const names = [...rel.matchAll(/\{(\w+)\}/g)].map((p) => p[1]);
+        const operation = found.operation.includes('{') ? quote(found.operation.replace(/\{[^}]*\}/g, () => `{${names.shift() ?? 'id'}}`)) : `'${found.operation}'`;
+        const helper = INDEX_HELPERS[found.operation];
+        const write = found.scope !== 'hawksearch:index';
+        return {
+            call: `await app.hawksearch.${helper ?? `index.call(${operation}${m === 'POST' ? ', body' : ''})`}`,
+            scope: `${found.scope} (elevated)`,
+            note: write
+                ? `Site keys only; ${maxItemsPerCall} items (or ${maxIdsPerCall} ids) a call; ${found.scope === 'hawksearch:index:items' ? `${itemWritesPerMinute} item writes` : `${managePerMinute} management calls`} a minute; audit-logged, never retried.${found.scope === 'hawksearch:index:items' ? ' Item writes are live at once.' : ''}`
+                : undefined,
+        };
+    }
+    return { unavailable: "Apps can't call this API." };
+}
+
+const HIDDEN_PARAMETERS = /^x-hawksearch-(group)?apikey$/i;
+
+function resolve(schema, spec) {
+    let current = schema;
+    for (let i = 0; current?.$ref && i < 10; i++) current = spec.components?.schemas?.[current.$ref.split('/').pop()];
+    return current ?? {};
+}
+
+function typeOf(schema) {
+    if (!schema) return 'any';
+    if (schema.$ref) return schema.$ref.split('/').pop();
+    if (schema.type === 'array') return `${typeOf(schema.items)}[]`;
+    if (schema.enum) return schema.enum.map((v) => JSON.stringify(v)).join(' | ');
+    if (schema.pattern && /^\^\([\w|]+\)\$$/.test(schema.pattern)) return schema.pattern.slice(2, -2).split('|').map((v) => `"${v}"`).join(' | ');
+    if (schema.type === 'object' && schema.additionalProperties) return `{ [key]: ${typeOf(schema.additionalProperties)} }`;
+    return [schema.type ?? 'object', schema.format].filter(Boolean).join(' ');
+}
+
+const refsOf = (schema) => {
+    if (!schema) return [];
+    if (schema.$ref) return [schema.$ref.split('/').pop()];
+    if (schema.type === 'array') return refsOf(schema.items);
+    if (schema.additionalProperties) return refsOf(schema.additionalProperties);
+    return [];
+};
+
+/** A schema's fields, then those of the schemas it refers to (breadth first, each once). */
+function describeSchema(label, schema, spec) {
+    const lines = [`${label}: ${typeOf(schema)}`];
+    const queue = refsOf(schema);
+    if (!queue.length) {
+        const own = resolve(schema, spec);
+        if (own.properties) lines.push(...fieldLines(own));
+        return lines;
+    }
+    const seen = new Set();
+    while (queue.length) {
+        const name = queue.shift();
+        if (seen.has(name)) continue;
+        seen.add(name);
+        const own = spec.components?.schemas?.[name];
+        if (!own) continue;
+        lines.push('', `${name}${own.description ? ` (${stripHtml(own.description)})` : ''}:`, ...fieldLines(own));
+        for (const property of Object.values(own.properties ?? {})) queue.push(...refsOf(property));
+    }
+    return lines;
+}
+
+function fieldLines(schema) {
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties ?? {}).map(([name, property]) => {
+        const description = property.description ? `: ${stripHtml(property.description)}` : '';
+        return `- ${name} (${typeOf(property)}${required.has(name) ? ', required' : ''}${property.nullable ? ', nullable' : ''})${description}`;
+    });
+}
+
+const jsonContent = (content) => content?.['application/json'] ?? Object.values(content ?? {})[0];
+
+function detail(operation, definition, rules) {
+    const [path, item] = Object.entries(definition?.paths ?? {})[0] ?? [];
+    const [method, op] = Object.entries(item ?? {}).find(([key]) => /^(get|post|put|delete|patch)$/i.test(key)) ?? [];
+    if (!op) return `# ${operation.title}\n\nThe page has no OpenAPI definition to read: ${operation.url.replace(/\.md$/, '')}`;
+    const access = bridgeCall(operation.api, method, path, rules);
+    const parameters = (op.parameters ?? []).filter((p) => !HIDDEN_PARAMETERS.test(p.name));
+    const body = jsonContent(op.requestBody?.content)?.schema;
+    const response = jsonContent(op.responses?.['200']?.content ?? op.responses?.['201']?.content)?.schema;
+    return [
+        `# ${operation.id}: ${op.summary ?? operation.title}`,
+        `${method.toUpperCase()} ${path} (HawkSearch ${operation.api === 'dashboard' ? 'Dashboard' : operation.api} API, ${operation.group})`,
+        '',
+        stripHtml(op.description ?? operation.summary ?? ''),
+        '',
+        ...(access.unavailable
+            ? [`Not available to apps: ${access.unavailable}`]
+            : ['From an app:', access.call, `Scope: ${access.scope}.${access.note ? ` ${access.note}` : ''}`]),
+        ...(parameters.length
+            ? ['', 'Parameters:', ...parameters.map((p) => `- ${p.name} (${p.in}, ${typeOf(p.schema)}${p.required ? ', required' : ''})${p.description ? `: ${stripHtml(p.description)}` : ''}`)]
+            : []),
+        ...(body ? ['', ...describeSchema('Request body', body, definition)] : []),
+        ...(response ? ['', ...describeSchema('Response', response, definition)] : []),
+        '',
+        `Source: ${operation.url.replace(/\.md$/, '')}`,
+    ]
+        .filter((line, i, all) => line !== '' || all[i - 1] !== '')
+        .join('\n');
+}
+
+async function fetchText(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+    return response.text();
+}
+
+/** The platform's default rules, for a reference made without the platform (tests, or no platform at all). */
+const builtInRules = async () => ({ rules: FALLBACK, from: 'the CLI (the platform\'s defaults)' });
+
+/**
+ * describe({ api, operation, offset }) for the tool. llms.txt and each page are cached for a while; when the site
+ * can't be reached, an earlier copy is used if there is one. `rules` is mcp-rules.mjs's createPlatformRules().
+ */
+export function createHawkSearchReference({ load = fetchText, now = Date.now, rules = builtInRules } = {}) {
+    const cache = new Map();
+    async function get(url) {
+        const hit = cache.get(url);
+        if (hit && now() - hit.at < CACHE_MS) return { text: hit.text };
+        try {
+            const text = await load(url);
+            cache.set(url, { text, at: now() });
+            return { text };
+        } catch (error) {
+            if (hit) return { text: hit.text, stale: `(developerdocs.hawksearch.com couldn't be reached just now: ${error.message}. This is the copy from earlier.)` };
+            throw error;
+        }
+    }
+
+    return async function describe({ api, operation, offset = 0 } = {}) {
+        let index;
+        try {
+            index = await get(INDEX_URL);
+        } catch (error) {
+            return { ok: false, text: `Couldn't read HawkSearch's API reference (${error.message}). It's at https://developerdocs.hawksearch.com/reference/getting-started-with-your-api.` };
+        }
+        const operations = operationsIn(index.text);
+        const platform = await rules();
+        const stale = (loaded) => [loaded.stale, platform.note].filter(Boolean).map((note) => `\n\n${note}`).join('');
+        if (api && !operations.some((o) => o.api === api)) return { ok: false, text: `No API "${api}". The APIs: ${Object.keys(APIS).join(', ')}.` };
+        if (operation === undefined) return { ok: true, text: list(operations, api, platform.rules, platform.from) + stale(index) };
+
+        const wanted = operation.trim().toLowerCase();
+        const pool = api ? operations.filter((o) => o.api === api) : operations;
+        let matches = pool.filter((o) => o.id.toLowerCase() === wanted);
+        if (!matches.length) {
+            const words = wanted.split(/[^a-z0-9_]+/).filter((w) => w.length > 1);
+            matches = pool.filter((o) => words.length && words.every((w) => `${o.id} ${o.title} ${o.summary} ${o.group}`.toLowerCase().includes(w)));
+        }
+        if (!matches.length) return { ok: false, text: `No operation matches "${operation}". Call without operation for the list.` };
+        if (matches.length > 1) {
+            return { ok: true, text: `Several operations match "${operation}"; call again with one id:\n${matches.slice(0, 20).map((o) => `- ${o.id}: ${o.title} (${o.api}, ${o.group})`).join('\n')}${matches.length > 20 ? `\n… and ${matches.length - 20} more: use more words.` : ''}` };
+        }
+
+        const [found] = matches;
+        let page;
+        try {
+            page = await get(found.url);
+        } catch (error) {
+            return { ok: false, text: `Couldn't read ${found.url} (${error.message}).` };
+        }
+        const text = detail(found, definitionIn(page.text), platform.rules).slice(offset);
+        const cut = text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}\n… (more: call again with offset ${offset + MAX_TEXT})` : text;
+        return { ok: true, text: cut + stale(page) };
+    };
+}

package/src/mcp-reports.mjs

@@ -0,0 +1,130 @@
+// The MCP server's `analytics_reports` tool: which reports app.analytics.report() can call, read from the HawkSearch
+// Analytics API's own OpenAPI spec (the developer portal), so a new report is known as soon as the analytics API
+// documents it. The dev spec, as the MCP only works against the dev platform, which calls the dev analytics API; the
+// prod spec only to mark the reports prod doesn't have yet, which an app can't use once it's live. The platform's
+// rules (mcp-rules.mjs) mark the reports it blocks. The specs are public: no key, no client data.
+import { parse } from 'yaml';
+import { FALLBACK } from './mcp-rules.mjs';
+
+export const SPEC_URL = 'https://developers.analytics.hawksearch.com/dev/openapi.yaml';
+export const PROD_SPEC_URL = 'https://developers.analytics.hawksearch.com/openapi.yaml';
+const PORTAL_URL = 'https://developers.analytics.hawksearch.com/';
+const CACHE_MS = 10 * 60_000;
+const TIMEOUT_MS = 10_000;
+const DEV_ONLY = 'dev only: not on prod yet, so an app using it fails once it is live';
+const BLOCKED = 'blocked by the platform: apps get 404 report_not_allowed';
+
+/** The notes on one report: dev only, blocked. */
+const marks = (name, prod, blocked) => [prod && !prod.has(name) ? DEV_ONLY : null, blocked.includes(name) ? BLOCKED : null].filter(Boolean);
+
+async function fetchSpec(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+    return response.text();
+}
+
+/** The reports in a parsed spec: one per POST path, by the name app.analytics.report() takes ("" for the root). */
+export function reportsIn(spec) {
+    return Object.entries(spec?.paths ?? {})
+        .filter(([, item]) => item?.post)
+        .map(([path, item]) => ({ name: path.replace(/^\/+|\/+$/g, ''), tag: item.post.tags?.[0] ?? 'Other', summary: item.post.summary ?? '', operation: item.post }));
+}
+
+const call = (name) => `app.analytics.report(${JSON.stringify(name)}`;
+const title = (name) => (name === '' ? '"" (the root)' : name);
+
+function list(reports, url, prod, blocked) {
+    const groups = new Map();
+    for (const r of reports) groups.set(r.tag, [...(groups.get(r.tag) ?? []), r]);
+    const lines = [`Analytics reports app.analytics.report(name, request) can call (scope reports:read), from ${url}. Call again with report: "<name>" for its columns, filters and an example.`];
+    for (const [tag, items] of groups) {
+        lines.push('', `## ${tag}`);
+        for (const r of items) {
+            const notes = marks(r.name, prod, blocked);
+            lines.push(`- ${title(r.name)}${notes.length ? ` (${notes.join('; ')})` : ''}: ${r.summary}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+/** A request body's examples: inline, or through a $ref to components.requestBodies. */
+function requestExamples(op, spec) {
+    const body = op.requestBody?.$ref ? spec.components?.requestBodies?.[op.requestBody.$ref.split('/').pop()] : op.requestBody;
+    return body?.content?.['application/json']?.examples;
+}
+
+function detail(report, spec, prod, blocked) {
+    const op = report.operation;
+    const example = op.responses?.['200']?.content?.['application/json']?.example;
+    // x-report is the spec's checked list (the analytics API's tests keep it in step); examples can be out of date.
+    const x = op['x-report'];
+    const columns = (x?.columns ?? example?.columns ?? []).map((c) => `${c.name} (${c.type})`);
+    const fields = x && x.kind !== 'write'
+        ? [`filters takes: ${Object.keys(x.filters ?? {}).join(', ') || 'none'}; having takes: ${(x.having ?? []).join(', ') || 'none'}.`]
+        : [];
+    const bodyExamples = requestExamples(op, spec);
+    const sample = report.name === '' ? { query: 'top 10 keywords by searches last week' } : { startDate: '2026-06-01', endDate: '2026-06-30', page: 1, limit: 50 };
+    return [
+        `# ${title(report.name)}: ${report.summary}`,
+        ...marks(report.name, prod, blocked).flatMap((note) => ['', `Note: ${note}.`]),
+        '',
+        (op.description ?? '').trim(),
+        ...(columns.length ? ['', `Columns: ${columns.join(', ')}.`] : []),
+        ...fields,
+        '',
+        'From an app:',
+        `const result = await ${call(report.name)}, ${JSON.stringify(sample)});`,
+        report.name === ''
+            ? ''
+            : x
+              ? '// result: { columns, data, totalRecords, page, hasMore }, data typed by the bridge (numbers and booleans converted). startDate/endDate default to the host\'s date range.'
+              : '// result: { columns, data, totalRecords, page, hasMore }. startDate/endDate default to the host\'s date range; numbers and booleans can come back as strings.',
+        ...(bodyExamples ? ['', 'Request examples:', ...Object.values(bodyExamples).map((e) => `- ${e.summary ?? ''}: ${JSON.stringify(e.value)}`)] : []),
+        ...(example?.data?.length ? ['', `Example row: ${JSON.stringify(example.data[0])}`] : []),
+    ]
+        .filter((line, i, all) => line !== '' || all[i - 1] !== '')
+        .join('\n');
+}
+
+/**
+ * describe({ report }) for the tool: the list of reports, or one report in full. The specs are cached for a while; when
+ * the portal can't be reached, an earlier copy is used if there is one. Without the prod spec, nothing is marked dev only.
+ * `rules` is mcp-rules.mjs's createPlatformRules(); without it, no report is marked blocked (the platform's default).
+ */
+export function createReportCatalog({ url = SPEC_URL, prodUrl = PROD_SPEC_URL, load = fetchSpec, now = Date.now, rules = async () => ({ rules: FALLBACK }) } = {}) {
+    let cached;
+    async function specs() {
+        if (cached && now() - cached.at < CACHE_MS) return cached;
+        const [dev, prod] = await Promise.allSettled([load(url), load(prodUrl)]);
+        try {
+            if (dev.status === 'rejected') throw dev.reason;
+            const prodNames = prod.status === 'fulfilled' ? new Set(reportsIn(parse(prod.value)).map((r) => r.name)) : cached?.prod;
+            cached = { spec: parse(dev.value), prod: prodNames, at: now() };
+            return cached;
+        } catch (error) {
+            if (cached) return { ...cached, stale: `(The portal couldn't be reached just now: ${error.message}. This is the copy from earlier.)` };
+            throw error;
+        }
+    }
+
+    return async function describe({ report } = {}) {
+        let loaded;
+        try {
+            loaded = await specs();
+        } catch (error) {
+            return { ok: false, text: `Couldn't read the analytics API's spec (${error.message}). The reports are documented at ${PORTAL_URL}.` };
+        }
+        const reports = reportsIn(loaded.spec);
+        const platform = await rules();
+        const blocked = platform.rules.analytics.blockedReports;
+        const stale = [loaded.stale, platform.note].filter(Boolean).map((note) => `\n\n${note}`).join('');
+        if (report === undefined) return { ok: true, text: list(reports, url, loaded.prod, blocked) + stale };
+
+        const wanted = report.trim().replace(/^\/+|\/+$/g, '').toLowerCase();
+        const found = reports.find((r) => r.name === wanted);
+        if (found) return { ok: true, text: detail(found, loaded.spec, loaded.prod, blocked) + stale };
+        const words = wanted.split('-').filter(Boolean);
+        const close = reports.filter((r) => r.name && words.some((w) => r.name.includes(w))).map((r) => r.name);
+        return { ok: false, text: `No report "${report}" in the analytics API's spec.${close.length ? ` Close: ${close.join(', ')}.` : ''} Call without report for the list.` };
+    };
+}

package/src/mcp-rules.mjs

@@ -0,0 +1,109 @@
+// What apps may call, for the MCP server's hawksearch_api and analytics_reports tools: the platform's own
+// GET /meta/rules (the rules in effect there, configuration included), read from the dev platform the MCP deploys to.
+// FALLBACK is the platform's built-in defaults, for when the platform can't be reached (or predates /meta/rules);
+// test/mcp-hawksearch.test.mjs checks it against platform/src. Public: no key, no client data.
+import { PLATFORMS } from './env.mjs';
+
+const CACHE_MS = 10 * 60_000;
+const TIMEOUT_MS = 10_000;
+
+const index = (method, operation, path, scope) => ({ method, operation, path, scope });
+const READ = 'hawksearch:index';
+const ITEMS = 'hawksearch:index:items';
+const MANAGE = 'hawksearch:index:manage';
+
+/** The platform's defaults (HawkSearchOptions, IndexingApiRules, AnalyticsOptions), in /meta/rules' shape. */
+export const FALLBACK = {
+    version: 1,
+    dashboard: {
+        apiVersion: 'v11',
+        writeResources: ['banner', 'boostbury', 'campaign', 'visibility', 'visitortarget', 'redirect', 'synonym', 'spellcheck', 'paginationset', 'sortingset', 'recommendationvisibility', 'landingpagelayout', 'facet', 'landingpage'],
+        maxBulkItems: 1000,
+        maxWriteRequestBytes: 5 * 1024 * 1024,
+        writesPerMinute: 120,
+    },
+    search: { perMinute: 600, maxRequestBytes: 64 * 1024 },
+    recommendations: { available: true, maxBulkWidgets: 10, perMinute: 600 },
+    indexing: {
+        operations: [
+            index('GET', 'indexes', 'api/v2/indexing', READ),
+            index('GET', 'current', 'api/v2/indexing/current', READ),
+            index('GET', 'inactive', 'api/v2/indexing/get-inactive-index', READ),
+            index('POST', 'hierarchy', 'api/hierarchy', READ),
+            index('POST', 'mappings', 'api/mapping', READ),
+            index('GET', 'embedding/progress', 'api/embedding/progress', READ),
+            index('POST', 'index-items', 'api/v2/indexing/index-items', ITEMS),
+            index('POST', 'update-items', 'api/v2/indexing/update-items', ITEMS),
+            index('POST', 'delete', 'api/v2/indexing/delete', ITEMS),
+            index('POST', 'delete-items', 'api/v2/indexing/delete-items', ITEMS),
+            index('POST', 'add-attributes-to-items', 'api/v2/indexing/add-attributes-to-items', ITEMS),
+            index('POST', 'update-attributes-of-items', 'api/v2/indexing/update-attributes-of-items', ITEMS),
+            index('POST', 'remove-attributes-from-items', 'api/v2/indexing/remove-attributes-from-items', ITEMS),
+            index('POST', 'update-nested', 'api/v2/indexing/update-nested', ITEMS),
+            index('POST', 'remove-nested', 'api/v2/indexing/remove-nested', ITEMS),
+            index('POST', 'bulk-update-nested', 'api/v2/indexing/bulk-update-nested', ITEMS),
+            index('POST', 'bulk-remove-nested', 'api/v2/indexing/bulk-remove-nested', ITEMS),
+            index('POST', 'bulk-item-operations', 'api/v2/indexing/bulk-item-operations', ITEMS),
+            index('POST', 'create', 'api/v2/indexing/create', MANAGE),
+            index('POST', 'set-current', 'api/v2/indexing/set-current', MANAGE),
+            index('POST', 'swap', 'api/v2/indexing/swap', MANAGE),
+            index('POST', 'delete-index', 'api/v2/indexing/delete-index', MANAGE),
+            index('POST', 'rebuild-all', 'api/v2/indexing/rebuild-all', MANAGE),
+            index('POST', 'rebuild-autocomplete', 'api/v2/indexing/rebuild-autocomplete', MANAGE),
+            index('POST', 'rebuild-percolator', 'api/v2/indexing/rebuild-percolator', MANAGE),
+            index('POST', 'rebuild-learning', 'api/v2/indexing/rebuild-learning', MANAGE),
+            index('POST', 'rebuild-related', 'api/v2/indexing/rebuild-related', MANAGE),
+            index('POST', 'rebuild-embedding', 'api/v2/indexing/rebuild-embedding', MANAGE),
+            index('POST', 'hierarchy/upsert', 'api/hierarchy/upsert', MANAGE),
+            index('POST', 'hierarchy/rebuild', 'api/hierarchy/rebuild', MANAGE),
+            index('POST', 'hierarchy/delete-items', 'api/hierarchy/delete-items', MANAGE),
+            index('POST', 'hierarchy/delete-all', 'api/hierarchy/delete-all', MANAGE),
+            index('POST', 'mappings/upsert', 'api/mapping/upsert', MANAGE),
+            index('POST', 'mappings/invalidate-cache', 'api/mapping/invalidate-cache', MANAGE),
+            index('GET', 'embedding/status/{id}', 'api/embedding/status/{id}', READ),
+        ],
+        maxItemsPerCall: 125,
+        maxIdsPerCall: 1000,
+        maxRequestBytes: 5 * 1024 * 1024,
+        itemWritesPerMinute: 120,
+        managePerMinute: 10,
+        rebuildsPerMinute: 2,
+    },
+    analytics: { blockedReports: [] },
+};
+
+/** The platform's answer over the fallback, section by section, so a field it doesn't send keeps its default. */
+function merge(rules) {
+    if (!rules || typeof rules !== 'object' || !(rules.version >= 1)) throw new Error('not a rules document');
+    const merged = { ...FALLBACK };
+    for (const [section, defaults] of Object.entries(FALLBACK)) {
+        if (rules[section] && typeof rules[section] === 'object' && typeof defaults === 'object') merged[section] = { ...defaults, ...rules[section] };
+    }
+    return { ...merged, scopes: rules.scopes, version: rules.version };
+}
+
+async function fetchJson(url) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS), headers: { accept: 'application/json' } });
+    if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+    return response.json();
+}
+
+/**
+ * rules() for the tools: { rules, from } from the platform (cached for a while), else the earlier answer, else
+ * { rules: FALLBACK, from, note } saying why.
+ */
+export function createPlatformRules({ url = PLATFORMS.dev, load = fetchJson, now = Date.now } = {}) {
+    const endpoint = `${url.replace(/\/+$/, '')}/meta/rules`;
+    let cached;
+    return async function rules() {
+        if (cached && now() - cached.at < CACHE_MS) return cached.answer;
+        try {
+            cached = { answer: { rules: merge(await load(endpoint)), from: endpoint }, at: now() };
+            return cached.answer;
+        } catch (error) {
+            if (cached) return { ...cached.answer, note: `(${endpoint} couldn't be read just now: ${error.message}. These are its rules from earlier.)` };
+            // Not cached: the platform is tried again on the next call.
+            return { rules: FALLBACK, from: 'the CLI', note: `(${endpoint} couldn't be read: ${error.message}. These are the platform's default rules, which its configuration can change.)` };
+        }
+    };
+}