katman-mcp 0.1.0

package/dist/tools/visibility/summary.js

@@ -0,0 +1,164 @@
+import { foldKey, sameSite } from "./analyze.js";
+export const emptyBucket = () => ({ answered: 0, mentioned: 0, recommendedFirst: 0, cited: 0 });
+function addTo(b, a) {
+    b.answered++;
+    if (a.mentioned)
+        b.mentioned++;
+    if (a.recommendedFirst)
+        b.recommendedFirst++;
+    if (a.cited)
+        b.cited++;
+}
+export const ratio = (k, n) => (n > 0 ? Math.round((k / n) * 10000) / 10000 : 0);
+/** Counts toward the rates: answered, not diagnostic, not a question that names the brand. */
+export function isScored(a, branded = new Set()) {
+    return !a.error && a.questionType !== "diagnostic" && !branded.has(a.questionId);
+}
+export function summarize(answers, o) {
+    const branded = o.branded ?? new Set();
+    const scored = answers.filter((a) => isScored(a, branded));
+    const all = emptyBucket();
+    const byFamily = {};
+    const byLanguage = {};
+    for (const a of scored) {
+        addTo(all, a);
+        addTo((byFamily[a.family] ??= emptyBucket()), a);
+        addTo((byLanguage[a.lang ?? "?"] ??= emptyBucket()), a);
+    }
+    const reporters = new Set(answers.filter((a) => !a.error && a.citations.length > 0).map((a) => a.family));
+    const citationScored = scored.filter((a) => reporters.has(a.family));
+    const citedCount = citationScored.filter((a) => a.cited).length;
+    const citationBlind = [...new Set(scored.map((a) => a.family))].filter((f) => !reporters.has(f));
+    // Competitors: who is named instead (per answer, deduped), research names are canonical.
+    const comp = new Map();
+    for (const a of scored) {
+        const seen = new Set();
+        const names = [...a.namedProducts, ...a.competitorsNamed];
+        for (const raw of names) {
+            if (!raw || o.isBrand(raw))
+                continue;
+            const canonical = o.canonicalCompetitor?.(raw);
+            const display = canonical ?? raw.trim();
+            const key = foldKey(display);
+            if (!key || seen.has(key))
+                continue;
+            seen.add(key);
+            const e = comp.get(key) ?? { count: 0, spellings: new Map(), canonical };
+            e.count++;
+            e.spellings.set(display, (e.spellings.get(display) ?? 0) + 1);
+            if (canonical)
+                e.canonical = canonical;
+            comp.set(key, e);
+        }
+    }
+    const topCompetitors = [...comp.values()]
+        .map((e) => ({
+        name: e.canonical ?? [...e.spellings.entries()].sort((x, y) => y[1] - x[1] || x[0].localeCompare(y[0]))[0][0],
+        count: e.count,
+        known: !!e.canonical,
+    }))
+        .sort((x, y) => y.count - x.count || x.name.localeCompare(y.name));
+    const domains = new Map();
+    for (const a of scored) {
+        const ds = new Set(a.citations.map((c) => c.domain).filter((d) => d && !o.ownDomains.some((own) => sameSite(d, own))));
+        for (const d of ds)
+            domains.set(d, (domains.get(d) ?? 0) + 1);
+    }
+    const topCitedDomains = [...domains.entries()]
+        .map(([domain, count]) => ({ domain, count }))
+        .sort((x, y) => y.count - x.count || x.domain.localeCompare(y.domain))
+        .slice(0, 15);
+    const diag = answers.filter((a) => !a.error && a.questionType === "diagnostic");
+    const stabilityMap = new Map();
+    for (const a of scored) {
+        const k = `${a.questionId}\u0000${a.family}`;
+        const s = stabilityMap.get(k) ?? { questionId: a.questionId, family: a.family, samples: 0, mentioned: 0, cited: 0 };
+        s.samples++;
+        if (a.mentioned)
+            s.mentioned++;
+        if (a.cited)
+            s.cited++;
+        stabilityMap.set(k, s);
+    }
+    const stability = [...stabilityMap.values()].some((s) => s.samples > 1) ? [...stabilityMap.values()] : [];
+    return {
+        summary: {
+            answered: all.answered,
+            mentionRate: ratio(all.mentioned, all.answered),
+            recommendedFirstRate: ratio(all.recommendedFirst, all.answered),
+            citationRate: ratio(citedCount, citationScored.length),
+            byFamily,
+            topCompetitors: topCompetitors.slice(0, 10).map(({ name, count }) => ({ name, count })),
+            topCitedDomains,
+        },
+        extras: {
+            citationBlind,
+            citationDenominator: citationScored.length,
+            citedCount,
+            byLanguage,
+            errors: answers.filter((a) => a.error && !/^(skipped|not run)/i.test(a.error)).length,
+            skipped: answers.filter((a) => a.error && /^(skipped|not run)/i.test(a.error)).length,
+            unsearched: answers.filter((a) => !a.error && a.searched === false).length,
+            diagnostics: {
+                answered: diag.length,
+                mentioned: diag.filter((a) => a.mentioned).length,
+                identityCorrect: diag.filter((a) => a.identityCorrect === true).length,
+                identityWrong: diag.filter((a) => a.identityCorrect === false).length,
+                identityUnknown: diag.filter((a) => a.identityCorrect === null || a.identityCorrect === undefined).length,
+                cited: diag.filter((a) => a.cited).length,
+            },
+            stability,
+            newCompetitors: topCompetitors.filter((c) => !c.known).slice(0, 10).map((c) => c.name),
+        },
+    };
+}
+export function diffRuns(prev, curr, branded = new Set()) {
+    const key = (a) => `${a.questionId}\u0000${a.family}`;
+    const group = (run) => {
+        const m = new Map();
+        for (const a of run.answers)
+            if (isScored(a, branded))
+                m.set(key(a), [...(m.get(key(a)) ?? []), a]);
+        return m;
+    };
+    const p = group(prev);
+    const c = group(curr);
+    const common = [...c.keys()].filter((k) => p.has(k));
+    const rates = (m, keys) => {
+        const r = { answered: 0, mentioned: 0, recommendedFirst: 0, cited: 0 };
+        for (const k of keys)
+            for (const a of m.get(k) ?? [])
+                addTo(r, a);
+        return r;
+    };
+    const byFamily = {};
+    for (const fam of new Set(common.map((k) => k.split("\u0000")[1]))) {
+        const ks = common.filter((k) => k.split("\u0000")[1] === fam);
+        byFamily[fam] = { before: rates(p, ks), after: rates(c, ks) };
+    }
+    const anyMentioned = (xs) => (xs ?? []).some((a) => a.mentioned);
+    const split = (k) => {
+        const [questionId, family] = k.split("\u0000");
+        return { questionId, family };
+    };
+    const ids = (run) => new Set(run.models.map((m) => m.id));
+    const qs = (run) => new Set(run.answers.map((a) => a.questionId));
+    const sameSet = (a, b) => a.size === b.size && [...a].every((x) => b.has(x));
+    return {
+        previousId: prev.id,
+        previousTs: prev.ts,
+        pairs: common.length,
+        sameModels: sameSet(ids(prev), ids(curr)),
+        sameQuestions: sameSet(qs(prev), qs(curr)),
+        before: rates(p, common),
+        after: rates(c, common),
+        byFamily,
+        gained: common.filter((k) => !anyMentioned(p.get(k)) && anyMentioned(c.get(k))).map(split),
+        lost: common.filter((k) => anyMentioned(p.get(k)) && !anyMentioned(c.get(k))).map(split),
+    };
+}
+export function addDays(iso, days) {
+    const d = new Date(iso);
+    d.setUTCDate(d.getUTCDate() + days);
+    return d.toISOString().slice(0, 10);
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Shared data contracts for all Katman modules. Keep this file stable:
+// method/, crawl/ and visibility/ all read and write these shapes.
+export {};

package/dist/util.js

@@ -0,0 +1,92 @@
+/** Standard successful tool result: markdown for the model + optional structured data. */
+export function ok(text, structured) {
+    return {
+        content: [{ type: "text", text }],
+        ...(structured ? { structuredContent: structured } : {}),
+    };
+}
+export function fail(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+export function mdTable(headers, rows) {
+    const esc = (v) => String(v ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
+    return [
+        `| ${headers.map(esc).join(" | ")} |`,
+        `| ${headers.map(() => "---").join(" | ")} |`,
+        ...rows.map((r) => `| ${r.map(esc).join(" | ")} |`),
+    ].join("\n");
+}
+export function truncate(s, n) {
+    return s.length <= n ? s : s.slice(0, Math.max(0, n - 1)) + "…";
+}
+export function domainOf(url) {
+    try {
+        return new URL(url).hostname.replace(/^www\./, "").toLowerCase();
+    }
+    catch {
+        return url.replace(/^https?:\/\//, "").replace(/^www\./, "").split(/[/?#]/)[0].toLowerCase();
+    }
+}
+/** Normalise a user-supplied site URL to https://host (no trailing slash). */
+export function normalizeSiteUrl(input) {
+    let s = input.trim();
+    if (!/^https?:\/\//i.test(s))
+        s = "https://" + s;
+    const u = new URL(s);
+    return `${u.protocol}//${u.host}`;
+}
+const SEV_ORDER = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+export function sortFindings(fs) {
+    return [...fs].sort((a, b) => SEV_ORDER[a.severity] - SEV_ORDER[b.severity]);
+}
+export function findingsToMarkdown(fs, limit = 50) {
+    if (!fs.length)
+        return "No issues found.";
+    return sortFindings(fs)
+        .slice(0, limit)
+        .map((f, i) => {
+        const lines = [`${i + 1}. **[${f.severity.toUpperCase()}] ${f.title}** (gate: ${f.gate}${f.prompt ? `, fix with ${f.prompt}` : ""})`, `   ${f.detail}`];
+        if (f.files?.length)
+            lines.push(`   Files: ${f.files.slice(0, 8).join(", ")}`);
+        if (f.urls?.length)
+            lines.push(`   URLs: ${f.urls.slice(0, 8).join(", ")}`);
+        if (f.fix)
+            lines.push(`   Fix: ${f.fix}`);
+        if (f.accept)
+            lines.push(`   Accept when: ${f.accept}`);
+        return lines.join("\n");
+    })
+        .join("\n");
+}
+/**
+ * The brand's one sentence from its four parts (brings → we do → gets → fear is unnecessary),
+ * written the way the book does: "Upload your invoice. We move the line items … Your document is never stored."
+ * A part that starts with a continuation word ("and", "so", "ve", ",") continues the previous sentence;
+ * otherwise the previous part is closed with a period and the next one is capitalised.
+ * Parts still holding [FILL]/[DOLDUR] are skipped; returns undefined when fewer than `minParts` remain.
+ */
+export function composeOneSentence(o, minParts = 2) {
+    if (!o)
+        return undefined;
+    const parts = [o.brings, o.weDo, o.gets, o.fear]
+        .map((x) => (x ?? "").trim())
+        .filter((x) => x && !/\[(FILL|DOLDUR)\]/i.test(x));
+    if (parts.length < minParts)
+        return undefined;
+    const CONTINUES = /^(?:[,;:–—-]|(?:and|so|then|but|or|while|which|that|plus|ve|ama|sonra|ya da|veya|böylece)\b)/iu;
+    const cap = (x) => x.charAt(0).toLocaleUpperCase() + x.slice(1);
+    let out = cap(parts[0]);
+    for (const next of parts.slice(1)) {
+        if (CONTINUES.test(next) && !/[.!?…]$/.test(out)) {
+            out += /^[,;:]/.test(next) ? next : ` ${next}`;
+        }
+        else {
+            if (!/[.!?…]$/.test(out))
+                out += ".";
+            out += ` ${cap(next)}`;
+        }
+    }
+    if (!/[.!?…]$/.test(out))
+        out += ".";
+    return out;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "katman-mcp",
+  "version": "0.1.0",
+  "description": "Katman MCP: makes your vibe-coded site readable, quotable and recommendable by ChatGPT, Claude, Gemini and Perplexity. Scans your codebase, audits your live site like AI crawlers do, measures AI visibility with your own OpenRouter key.",
+  "type": "module",
+  "bin": {
+    "katman-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/postbuild.mjs",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "geo",
+    "aeo",
+    "seo",
+    "llm-seo",
+    "ai-visibility",
+    "chatgpt",
+    "vibe-coding",
+    "cursor",
+    "claude-code"
+  ],
+  "homepage": "https://katman.pro",
+  "license": "UNLICENSED",
+  "author": "Rnify Limited",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "node-html-parser": "^9.0.4",
+    "robots-parser": "^3.0.1",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "mcpName": "pro.katman/mcp"
+}

package/server.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "pro.katman/mcp",
+  "title": "Katman",
+  "description": "Get your vibe-coded site read, quoted and recommended by ChatGPT, Claude, Gemini and Perplexity.",
+  "version": "0.1.0",
+  "websiteUrl": "https://katman.pro/mcp",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "katman-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "npx",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "KATMAN_KEY",
+          "description": "Optional. Your Katman Pro key from katman.pro/app (7-day free trial, no card). Unlocks the Pro tools; the free diagnosis tools work without it.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "OPENROUTER_API_KEY",
+          "description": "Optional. Your own OpenRouter key, used only for AI-visibility runs.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}