katman-mcp 0.1.0

package/dist/license.js

@@ -0,0 +1,448 @@
+// Katman Pro licensing (docs/07-APP-SPEC.md §6).
+//
+// - KATMAN_KEY comes from the environment (the MCP config). It is sent only to KATMAN_API_URL (default
+//   https://katman.pro), in the JSON body of POST /api/web/mcp/verify and /api/web/mcp/sync, and is never
+//   printed, logged or written anywhere.
+// - Verification runs at most once per `checkAgainAfter` (default 24 h). The answer is cached in
+//   ~/.katman/license.json under the key's SHA-256 hash (never the key).
+// - Offline grace: when katman.pro can't be reached, the last good answer keeps working for 7 days.
+// - Free tools never call into this module's network path; Pro tools go through withPro() at registration.
+// - Tests inject a LicenseProvider (createServer({ license }) / runCli(args, { license })); there is no env
+//   switch that turns the gate off.
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { resolveRoot } from "./context.js";
+import { HOMEPAGE, VERSION } from "./meta.js";
+import { ok } from "./util.js";
+import { proNotice, projectFacts, renderUpsell, statusLine, upsellStructured } from "./tools/account/upsell.js";
+/** License features (spec §6). Trial = Pro. */
+export const PRO_FEATURES = ["plan", "prompts", "briefs", "generate", "lint", "visibility", "manual_check", "indexnow", "report", "monitoring", "sync"];
+/** Tools that never need a key (the free diagnosis). */
+export const FREE_TOOLS = ["katman_start", "katman_research", "katman_scan_code", "katman_audit_site", "katman_keywords", "katman_account"];
+/** Pro tool → license feature. */
+export const PRO_TOOLS = {
+    katman_plan: "plan",
+    katman_prompt: "prompts",
+    katman_page_brief: "briefs",
+    katman_generate: "generate",
+    katman_lint_content: "lint",
+    katman_visibility_run: "visibility",
+    katman_manual_check: "manual_check",
+    katman_indexnow: "indexnow",
+    katman_report: "report",
+    katman_setup_monitoring: "monitoring",
+    katman_sync: "sync",
+};
+/** Appended to every Pro tool's description. */
+export const PRO_NOTE = " (Katman Pro — needs KATMAN_KEY; 7-day free trial at katman.pro/app)";
+export function toolForFeature(feature) {
+    return Object.keys(PRO_TOOLS).find((t) => PRO_TOOLS[t] === feature) ?? `katman_${feature}`;
+}
+export function allows(status, feature) {
+    return status.state === "valid" && status.features.includes(feature);
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Environment
+const KEY_RE = /^km_[a-z]+_[A-Za-z0-9]{16,128}$/;
+export function readKey(env) {
+    const raw = (env.KATMAN_KEY ?? "").trim();
+    if (!raw)
+        return {};
+    // Unfilled config placeholders: ${user_config.katman_key}, ${env:KATMAN_KEY}, ${input:katman_key}.
+    if (/^\$\{[^}]*\}$/.test(raw))
+        return { hint: `KATMAN_KEY has no value (the MCP config passes the placeholder ${raw} unfilled).` };
+    return { key: raw };
+}
+/** "km_live_abcd…" — the same short prefix katman.pro shows in the key list. */
+export function keyHint(key) {
+    const m = /^(km_[a-z]+_)(.{0,4})/.exec(key);
+    return m ? `${m[1]}${m[2]}…` : "(not a km_ key)";
+}
+export function hashKey(key) {
+    return createHash("sha256").update(key, "utf8").digest("hex");
+}
+export function apiBase(env) {
+    const raw = (env.KATMAN_API_URL ?? "").trim() || HOMEPAGE;
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        return { error: `KATMAN_API_URL "${raw}" is not a URL.` };
+    }
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname) || u.hostname.endsWith(".localhost");
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && local)) {
+        return { error: "KATMAN_API_URL must start with https:// (plain http only for localhost), so the key never travels unencrypted." };
+    }
+    return { url: `${u.protocol}//${u.host}${u.pathname.replace(/\/+$/, "")}` };
+}
+/** POST JSON. Redirects are not followed (a 3xx must never carry the key to another host). Never throws. */
+export const postJson = async (url, body, { timeoutMs }) => {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            redirect: "manual",
+            signal: ctrl.signal,
+            headers: {
+                "content-type": "application/json; charset=utf-8",
+                accept: "application/json",
+                "user-agent": `katman-mcp/${VERSION} (+${HOMEPAGE}/mcp)`,
+            },
+            body: JSON.stringify(body),
+        });
+        const text = (await res.text()).slice(0, 100_000);
+        return { status: res.status, body: text };
+    }
+    catch (e) {
+        return { status: 0, body: "", error: e instanceof Error ? (e.name === "AbortError" ? "timeout" : e.message) : String(e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+// ---------------------------------------------------------------------------------------------------------------
+// Cache: ~/.katman/license.json → { version: 1, entries: { <sha256(key)>: CacheEntry } }
+const DAY_S = 86_400;
+const DEFAULT_TTL_S = DAY_S;
+/** How long a rejection (invalid / revoked) is remembered before asking again. */
+const REJECTED_TTL_S = 3_600;
+export const GRACE_MS = 7 * DAY_S * 1000;
+/** After a failed attempt, wait this long before trying the network again while the grace covers us. */
+const RETRY_AFTER_FAILURE_MS = 10 * 60 * 1000;
+const TIMEOUT_MS = 8_000;
+export function defaultCacheFile() {
+    return path.join(os.homedir(), ".katman", "license.json");
+}
+async function readCache(file) {
+    try {
+        const j = JSON.parse(await fs.readFile(file, "utf8"));
+        if (j && j.version === 1 && j.entries && typeof j.entries === "object" && !Array.isArray(j.entries))
+            return { version: 1, entries: j.entries };
+    }
+    catch {
+        // missing or unreadable: start empty
+    }
+    return { version: 1, entries: {} };
+}
+async function writeCache(file, data) {
+    try {
+        await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+        await fs.rename(tmp, file);
+    }
+    catch {
+        // read-only home (CI, sandbox): work without a cache
+    }
+}
+/** Keep the file small: drop entries of other keys not checked for 30 days, at most 20 entries. */
+function prune(entries, keep, now) {
+    const out = Object.entries(entries).filter(([h, e]) => {
+        if (h === keep)
+            return true;
+        const t = Date.parse(e.checkedAt ?? e.failedAt ?? "");
+        return Number.isFinite(t) && now - t < 30 * DAY_S * 1000;
+    });
+    out.sort((a, b) => Date.parse(b[1].checkedAt ?? "") - Date.parse(a[1].checkedAt ?? ""));
+    return Object.fromEntries(out.slice(0, 20));
+}
+function ttlSeconds(x) {
+    const n = Number(x);
+    return Number.isFinite(n) && n > 0 ? Math.min(Math.max(Math.round(n), 60), 7 * DAY_S) : DEFAULT_TTL_S;
+}
+function toIso(x) {
+    if (typeof x === "string" && x.trim()) {
+        const t = Date.parse(x);
+        return Number.isFinite(t) ? new Date(t).toISOString() : undefined;
+    }
+    if (typeof x === "number" && Number.isFinite(x) && x > 0)
+        return new Date(x < 1e12 ? x * 1000 : x).toISOString();
+    return undefined;
+}
+/** Parse a /api/web/mcp/verify response (spec §6). Only a 401 (or an explicit ok:false) is a rejection. */
+export function parseVerify(res) {
+    let j;
+    try {
+        const x = JSON.parse(res.body);
+        if (x && typeof x === "object" && !Array.isArray(x))
+            j = x;
+    }
+    catch {
+        j = undefined;
+    }
+    if (res.status === 200 && j?.ok === true) {
+        const plan = j.plan === "trial" || j.plan === "pro" ? j.plan : "free";
+        const features = Array.isArray(j.features)
+            ? j.features.filter((f) => typeof f === "string").slice(0, 64)
+            : plan === "free"
+                ? []
+                : [...PRO_FEATURES];
+        const account = j.account && typeof j.account === "object" ? j.account : {};
+        const emailMasked = typeof account.emailMasked === "string" ? account.emailMasked.slice(0, 120) : undefined;
+        const trialEndsAt = toIso(j.trialEndsAt);
+        return { kind: "good", good: { plan, features, checkAgainAfter: ttlSeconds(j.checkAgainAfter), ...(trialEndsAt ? { trialEndsAt } : {}), ...(emailMasked ? { emailMasked } : {}) } };
+    }
+    if (res.status === 401 || (j?.ok === false && (j.error === "invalid_key" || j.error === "revoked"))) {
+        return { kind: "rejected", error: j?.error === "revoked" ? "revoked" : "invalid_key" };
+    }
+    if (res.status === 0)
+        return { kind: "failed", error: res.error || "network error" };
+    if (res.status >= 300 && res.status < 400)
+        return { kind: "failed", error: `unexpected redirect (HTTP ${res.status}); check KATMAN_API_URL` };
+    return { kind: "failed", error: `HTTP ${res.status}${res.status === 200 ? " (unexpected answer)" : ""}` };
+}
+export function createLicenseProvider(deps = {}) {
+    const env = () => deps.env ?? process.env;
+    const post = deps.post ?? postJson;
+    const cacheFile = deps.cacheFile ?? defaultCacheFile();
+    const now = deps.now ?? (() => new Date());
+    const version = deps.version ?? VERSION;
+    const timeoutMs = deps.timeoutMs ?? TIMEOUT_MS;
+    const inflight = new Map();
+    /** Never let the key appear in an error string (belt and braces: it's only ever in a request body). */
+    const scrub = (s, key) => (key ? s.split(key).join(keyHint(key)) : s);
+    function fromGood(g, source, at, extra = {}) {
+        // A trial past its end date is free, even if the cached answer still says trial (no offline extension).
+        const ended = g.plan !== "pro" && !!g.trialEndsAt && Date.parse(g.trialEndsAt) <= at;
+        const cutOff = ended && g.plan === "trial";
+        return {
+            state: "valid",
+            plan: cutOff ? "free" : g.plan,
+            features: cutOff ? [] : [...g.features],
+            ...(g.trialEndsAt ? { trialEndsAt: g.trialEndsAt } : {}),
+            ...(ended ? { trialEnded: true } : {}),
+            ...(g.emailMasked ? { emailMasked: g.emailMasked } : {}),
+            checkedAt: g.checkedAt,
+            nextCheckAt: new Date(Date.parse(g.checkedAt) + g.checkAgainAfter * 1000).toISOString(),
+            source,
+            ...extra,
+        };
+    }
+    function rejected(error, source, key) {
+        return { state: error === "revoked" ? "revoked" : "invalid", plan: "free", features: [], source, keyHint: keyHint(key) };
+    }
+    function fresh(e, at) {
+        if (!e.result || !e.checkedAt)
+            return false;
+        const age = at - Date.parse(e.checkedAt);
+        if (!(age >= 0))
+            return false; // unparsable or in the future (clock change): check again
+        if (!e.result.ok)
+            return age < REJECTED_TTL_S * 1000;
+        if (e.result.plan === "trial" && e.result.trialEndsAt && Date.parse(e.result.trialEndsAt) <= at)
+            return false;
+        return age < e.result.checkAgainAfter * 1000;
+    }
+    function withinGrace(e, at) {
+        if (!e.good)
+            return false;
+        const age = at - Date.parse(e.good.checkedAt);
+        return age >= 0 && age <= GRACE_MS;
+    }
+    async function verify(key, hash, refresh) {
+        const at = now().getTime();
+        const base = apiBase(env());
+        const server = base.url ?? HOMEPAGE;
+        const cache = await readCache(cacheFile);
+        const cached = cache.entries[hash];
+        const entry = cached && (cached.base ?? HOMEPAGE) === server ? cached : {};
+        const hint = keyHint(key);
+        if (!refresh && fresh(entry, at)) {
+            const r = entry.result;
+            return r.ok ? { ...fromGood({ ...r, checkedAt: entry.checkedAt }, "cache", at), keyHint: hint } : rejected(r.error, "cache", key);
+        }
+        // Offline and recently failed: don't wait for another timeout on every tool call.
+        const failedAt = Date.parse(entry.failedAt ?? "");
+        if (!refresh && Number.isFinite(failedAt) && at - failedAt >= 0 && at - failedAt < RETRY_AFTER_FAILURE_MS && withinGrace(entry, at)) {
+            return { ...fromGood(entry.good, "offline-grace", at, { graceUntil: new Date(Date.parse(entry.good.checkedAt) + GRACE_MS).toISOString(), error: entry.failure }), keyHint: hint };
+        }
+        const res = base.url
+            ? await post(`${base.url}/api/web/mcp/verify`, { key, mcpVersion: version }, { timeoutMs })
+            : { status: 0, body: "", error: base.error };
+        const parsed = parseVerify(res);
+        const checkedAt = new Date(at).toISOString();
+        let status;
+        if (parsed.kind === "good") {
+            cache.entries[hash] = { base: server, checkedAt, result: { ok: true, ...parsed.good }, good: { ...parsed.good, checkedAt } };
+            status = { ...fromGood({ ...parsed.good, checkedAt }, "network", at), keyHint: hint };
+        }
+        else if (parsed.kind === "rejected") {
+            cache.entries[hash] = { base: server, checkedAt, result: { ok: false, error: parsed.error } };
+            status = rejected(parsed.error, "network", key);
+        }
+        else {
+            const error = scrub(parsed.error, key);
+            cache.entries[hash] = { ...entry, base: server, failedAt: checkedAt, failure: error };
+            status = withinGrace(entry, at)
+                ? { ...fromGood(entry.good, "offline-grace", at, { graceUntil: new Date(Date.parse(entry.good.checkedAt) + GRACE_MS).toISOString(), error }), keyHint: hint }
+                : {
+                    state: "unreachable",
+                    plan: "free",
+                    features: [],
+                    source: "network",
+                    error,
+                    keyHint: hint,
+                    ...(entry.good ? { checkedAt: entry.good.checkedAt } : {}),
+                };
+        }
+        cache.entries = prune(cache.entries, hash, at);
+        await writeCache(cacheFile, cache);
+        return status;
+    }
+    return {
+        hasKey: () => !!readKey(env()).key,
+        baseUrl: () => apiBase(env()).url ?? HOMEPAGE,
+        async status(opts = {}) {
+            const { key, hint } = readKey(env());
+            if (!key)
+                return { state: "no_key", plan: "free", features: [], source: "none", ...(hint ? { hint } : {}) };
+            if (!KEY_RE.test(key)) {
+                return {
+                    state: "invalid",
+                    plan: "free",
+                    features: [],
+                    source: "local",
+                    keyHint: keyHint(key),
+                    hint: "KATMAN_KEY doesn't look like a Katman key: keys start with km_live_ followed by letters and digits (no quotes, spaces or line breaks). It was not sent anywhere.",
+                };
+            }
+            const hash = hashKey(key);
+            const refresh = !!opts.refresh;
+            const flightKey = `${hash}:${refresh ? "r" : ""}`;
+            const running = inflight.get(flightKey);
+            if (running)
+                return running;
+            const p = verify(key, hash, refresh).finally(() => inflight.delete(flightKey));
+            inflight.set(flightKey, p);
+            return p;
+        },
+        async sync(body) {
+            const { key } = readKey(env());
+            if (!key || !KEY_RE.test(key))
+                return { ok: false, status: 0, error: key ? "invalid_key" : "no_key" };
+            const base = apiBase(env());
+            if (!base.url)
+                return { ok: false, status: 0, error: "network", message: base.error };
+            const res = await post(`${base.url}/api/web/mcp/sync`, { key, ...body }, { timeoutMs: 15_000 });
+            let j = {};
+            try {
+                const x = JSON.parse(res.body);
+                if (x && typeof x === "object" && !Array.isArray(x))
+                    j = x;
+            }
+            catch {
+                // not JSON
+            }
+            const message = typeof j.message === "string" ? scrub(j.message.slice(0, 300), key) : undefined;
+            if (res.status >= 200 && res.status < 300 && j.ok !== false) {
+                const project = j.project && typeof j.project === "object" ? j.project : {};
+                const idRaw = j.projectId ?? project.id;
+                const projectId = typeof idRaw === "string" || typeof idRaw === "number" ? String(idRaw) : undefined;
+                return { ok: true, status: res.status, dashboardUrl: dashboardUrl(base.url, j.url ?? j.dashboardUrl, projectId), ...(projectId ? { projectId } : {}), ...(message ? { message } : {}) };
+            }
+            const code = typeof j.error === "string" ? j.error.slice(0, 60) : undefined;
+            const error = res.status === 0 ? "network" : res.status === 401 ? (code === "revoked" ? "revoked" : "invalid_key") : res.status === 402 || res.status === 403 ? code ?? "not_pro" : code ?? `HTTP ${res.status}`;
+            return { ok: false, status: res.status, error, ...(res.status === 0 && res.error ? { message: scrub(res.error, key) } : message ? { message } : {}) };
+        },
+    };
+}
+/** The project page on the dashboard: the server's link when it points at the same host, else /app/projects(?id=). */
+function dashboardUrl(base, given, projectId) {
+    if (typeof given === "string" && given) {
+        try {
+            const u = new URL(given, base + "/");
+            if (u.origin === new URL(base).origin)
+                return u.toString();
+        }
+        catch {
+            // ignore
+        }
+    }
+    return `${base}/app/projects${projectId ? `?id=${encodeURIComponent(projectId)}` : ""}`;
+}
+let processProvider;
+/** The real provider for this process (environment + ~/.katman/license.json). */
+export function defaultLicense() {
+    processProvider ??= createLicenseProvider();
+    return processProvider;
+}
+export function licenseOf(ctx) {
+    return ctx.license ?? defaultLicense();
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Gate
+export async function requirePro(feature, provider) {
+    let status;
+    try {
+        status = await provider.status();
+    }
+    catch (e) {
+        status = { state: "unreachable", plan: "free", features: [], source: "network", error: e instanceof Error ? e.message : String(e) };
+    }
+    return { allowed: allows(status, feature), status };
+}
+/**
+ * Wrap a Pro tool's handler at registration. Without a Pro/trial license it returns a friendly upsell
+ * (not isError, so the agent relays it) instead of running the tool.
+ */
+export function withPro(ctx, feature, handler) {
+    const tool = toolForFeature(feature);
+    return async (args, extra) => {
+        const gate = await requirePro(feature, licenseOf(ctx));
+        if (gate.allowed)
+            return handler(args, extra);
+        let facts;
+        try {
+            const pr = args?.project_root;
+            facts = await projectFacts(await resolveRoot(ctx, typeof pr === "string" ? pr : undefined));
+        }
+        catch {
+            facts = undefined;
+        }
+        const a = (args && typeof args === "object" ? args : {});
+        return ok(renderUpsell({ tool, feature, status: gate.status, facts, args: a, surface: "mcp" }), upsellStructured(tool, feature, gate.status));
+    };
+}
+/**
+ * For katman_start: a one-line plan status when KATMAN_KEY is set (no line and no network without it), and a
+ * notice when the recommended next tool is a Pro tool the license doesn't cover.
+ */
+export async function startLicense(ctx) {
+    const provider = licenseOf(ctx);
+    let status;
+    try {
+        status = await provider.status();
+    }
+    catch (e) {
+        status = { state: "unreachable", plan: "free", features: [], source: "network", error: e instanceof Error ? e.message : String(e) };
+    }
+    const keySet = provider.hasKey();
+    return {
+        ...(keySet || status.hint ? { line: statusLine(status) } : {}),
+        notice: (tool) => {
+            const feature = PRO_TOOLS[tool];
+            return feature && !allows(status, feature) ? proNotice(tool, status) : undefined;
+        },
+        structured: { keySet, state: status.state, plan: status.plan, ...(status.trialEndsAt ? { trialEndsAt: status.trialEndsAt } : {}) },
+    };
+}
+// ---------------------------------------------------------------------------------------------------------------
+// CLI
+/** Exit code of a Pro CLI command without a license. */
+export const EXIT_NEEDS_PRO = 4;
+/** CLI command → feature: plan, report, check, and indexnow only with --submit. */
+export function cliFeature(cmd, rest) {
+    if (rest.includes("--help") || rest.includes("-h"))
+        return undefined;
+    switch (cmd) {
+        case "plan": return "plan";
+        case "report": return "report";
+        case "check": return "visibility";
+        case "indexnow": return rest.includes("--submit") ? "indexnow" : undefined;
+        default: return undefined;
+    }
+}

package/dist/meta.js

@@ -0,0 +1,28 @@
+export const VERSION = "0.1.0";
+export const HOMEPAGE = "https://katman.pro";
+/** Katman Pro (docs/07-APP-SPEC.md §1): 7-day trial without a card, then the founding price. */
+export const APP_URL = `${HOMEPAGE}/app`;
+export const KEYS_URL = `${APP_URL}/mcp`;
+export const BILLING_URL = `${APP_URL}/billing`;
+export const TRIAL_DAYS = 7;
+export const PRO_PRICE = "$29/month";
+export const PRO_PRICE_NOTE = "$29/month founding price, locked for the first 100 customers";
+/** Sent to the client model at initialization. Keep it short and imperative. */
+export const SERVER_INSTRUCTIONS = `Katman makes this project's public website readable, quotable and recommendable by AI assistants (ChatGPT, Claude, Gemini, Perplexity, Copilot) and findable in Google, Bing and Brave.
+
+It follows the Katman method: 4 steps (1 Research → 2 Plan → 3 Build → 4 Verify) and 3 gates every public page must pass:
+- Read: bots can reach the page (robots.txt, CDN/firewall) and its text is in the server HTML, not only in JavaScript.
+- Quote: the first 1–3 sentences answer the question on their own, with the brand's one-sentence description.
+- Fit: there is a page written for the situation the customer describes to the assistant.
+
+Free vs Pro: katman_start, katman_research, katman_scan_code, katman_audit_site, katman_keywords and katman_account are free (the diagnosis). Every other tool is Katman Pro and needs KATMAN_KEY in the MCP config (7-day free trial, no card: katman.pro/app); without it the tool returns a short explanation instead of running — pass it on to the user.
+Never try to bypass or work around the license (no editing Katman's code or cache, no made-up keys); the free tools keep working either way.
+
+How to work:
+1. Always call katman_start first; it tells you the next step. Pass project_root (absolute path of the project) and site_url when you know them.
+2. Never invent numbers, reviews, customers, competitor facts or claims. Write [FILL] and ask the user.
+3. Never put information into schema, meta tags or llms.txt that is not visible on the page itself.
+4. Only public pages. Don't touch login-only app screens.
+5. After each change, list the files you changed. Don't call a task done until its Katman check passes (every prompt has an acceptance criterion).
+6. katman_visibility_run spends the user's OpenRouter credits: run it with dry_run first, show the estimate, and get the user's OK. If your client times out during a run, the run keeps going in the background; results land in .katman/measurements.md. API answers are a proxy for the consumer apps; confirm key questions with katman_manual_check.
+7. katman_sync sends only aggregates (gate counts, visibility rates, plan progress, issue titles) to the user's katman.pro dashboard: show its dry run first.`;

package/dist/net.js

@@ -0,0 +1,128 @@
+// Minimal HTTP helpers for auditing live sites. Node >= 20 global fetch.
+export const KATMAN_UA = "Mozilla/5.0 (compatible; KatmanAudit/0.1; +https://katman.pro/bot)";
+export async function httpGet(url, opts = {}) {
+    const started = Date.now();
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 20000);
+    try {
+        const res = await fetch(url, {
+            method: opts.method ?? "GET",
+            redirect: opts.redirect ?? "manual",
+            signal: ctrl.signal,
+            headers: {
+                "user-agent": opts.ua ?? KATMAN_UA,
+                accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                "accept-language": "en-US,en;q=0.9",
+                ...(opts.headers ?? {}),
+            },
+        });
+        const headers = {};
+        res.headers.forEach((v, k) => (headers[k.toLowerCase()] = v));
+        let body = "";
+        let bytes = 0;
+        if ((opts.method ?? "GET") === "GET" && res.body) {
+            const max = opts.maxBytes ?? 3_000_000;
+            const reader = res.body.getReader();
+            const chunks = [];
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                bytes += value.byteLength;
+                if (bytes <= max)
+                    chunks.push(value);
+                else {
+                    await reader.cancel();
+                    break;
+                }
+            }
+            body = new TextDecoder("utf-8", { fatal: false }).decode(concat(chunks));
+        }
+        return {
+            url,
+            finalUrl: res.url || url,
+            status: res.status,
+            headers,
+            body,
+            bytes,
+            ms: Date.now() - started,
+            location: headers["location"],
+        };
+    }
+    catch (e) {
+        return {
+            url,
+            finalUrl: url,
+            status: 0,
+            headers: {},
+            body: "",
+            bytes: 0,
+            ms: Date.now() - started,
+            error: e instanceof Error ? (e.name === "AbortError" ? "timeout" : e.message) : String(e),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function concat(chunks) {
+    const len = chunks.reduce((n, c) => n + c.byteLength, 0);
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.byteLength;
+    }
+    return out;
+}
+/** Run fn over items with at most `limit` in flight; preserves order. */
+export async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            out[i] = await fn(items[i], i);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/** POST a JSON body (used by IndexNow). Same result shape as httpGet; never throws. */
+export async function httpPostJson(url, data, opts = {}) {
+    const started = Date.now();
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs ?? 20000);
+    try {
+        const res = await fetch(url, {
+            method: "POST",
+            redirect: "follow",
+            signal: ctrl.signal,
+            headers: {
+                "user-agent": opts.ua ?? KATMAN_UA,
+                "content-type": "application/json; charset=utf-8",
+                accept: "application/json,text/plain,*/*",
+                ...(opts.headers ?? {}),
+            },
+            body: JSON.stringify(data),
+        });
+        const headers = {};
+        res.headers.forEach((v, k) => (headers[k.toLowerCase()] = v));
+        const body = (await res.text()).slice(0, opts.maxBytes ?? 100_000);
+        return { url, finalUrl: res.url || url, status: res.status, headers, body, bytes: body.length, ms: Date.now() - started };
+    }
+    catch (e) {
+        return {
+            url, finalUrl: url, status: 0, headers: {}, body: "", bytes: 0, ms: Date.now() - started,
+            error: e instanceof Error ? (e.name === "AbortError" ? "timeout" : e.message) : String(e),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/server.js

@@ -0,0 +1,17 @@
+// The MCP server factory (no side effects on import, so tests can build a server with an injected license).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { VERSION, SERVER_INSTRUCTIONS } from "./meta.js";
+import { defaultLicense } from "./license.js";
+import { registerMethodTools } from "./tools/method/index.js";
+import { registerCrawlTools } from "./tools/crawl/index.js";
+import { registerVisibilityTools } from "./tools/visibility/index.js";
+import { registerAccountTools } from "./tools/account/index.js";
+export function createServer(opts = {}) {
+    const server = new McpServer({ name: "katman", title: "Katman — AI visibility for your site", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    const ctx = { server, version: VERSION, license: opts.license ?? defaultLicense() };
+    registerMethodTools(server, ctx);
+    registerCrawlTools(server, ctx);
+    registerVisibilityTools(server, ctx);
+    registerAccountTools(server, ctx);
+    return server;
+}