katman-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026 Rnify Limited. All rights reserved.
+
+Katman MCP ("katman-mcp") is proprietary software. You may install and run the
+published npm package to use Katman with your own projects. The free tools work
+without a key; Katman Pro features require a valid Katman key and are subject to
+the terms at https://katman.pro/terms.
+
+You may not copy, modify, redistribute, sublicense or sell the software, or
+remove or bypass its licence checks, except as allowed by those terms or by law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# Katman MCP
+
+**Get your vibe-coded site recommended by ChatGPT.**
+
+Point Katman at your vibe-coded site. It reads your code and your live pages the way ChatGPT's crawler does, then tells your AI coding tool exactly what to fix and which pages to write, so assistants can read, quote and recommend you. No SEO background needed.
+
+Katman is an MCP server that works inside your AI coding tool (Cursor, Claude Code, VS Code, Windsurf, Codex, Gemini CLI, Zed, Cline). It is not an SEO agency or a rank tracker.
+
+- Website and docs: https://katman.pro/mcp
+- The method behind it: https://katman.pro/method
+
+## Pricing
+
+| Plan | Price | What you get |
+|---|---|---|
+| **Free** | $0, no account, no key | The diagnosis: `katman_start`, `katman_research`, `katman_scan_code`, `katman_audit_site`, `katman_keywords`, `katman_account`. Katman shows what keeps assistants from reading, quoting and recommending your site. |
+| **7-day trial** | $0, no card | Everything in Katman Pro. Starts when you create your account at https://katman.pro/app. |
+| **Katman Pro** | **$29/month founding price** (first 100 customers, locked in) | The treatment: the plan, prompts P0–P14 with acceptance checks, page briefs, generators, content lint, AI-visibility runs, manual checks, IndexNow, reports, monitoring and the katman.pro dashboard sync. |
+
+Pro tools need `KATMAN_KEY` in your MCP config: sign in at https://katman.pro/app → **MCP → Create key**. Without a key, a Pro tool tells you what it would do for your project and how to start the trial, instead of running. `katman_account` shows your plan at any time.
+
+---
+
+## Why
+
+AI assistants recommend a site only when three gates are open:
+
+| Gate | What it means | What usually breaks it |
+|---|---|---|
+| **Read** | Bots can reach the page and the text is in the server HTML | Cloudflare blocking AI bots, text rendered only by JavaScript (Lovable/Bolt/Vite SPAs), soft 404s |
+| **Quote** | The first 1–3 sentences answer the question on their own, with the same one sentence everywhere | Pages that open with "Welcome to…", llms.txt contradicting the pricing page |
+| **Fit** | There's a page for the situation the customer describes to the assistant | Pages named after the product instead of the customer's problem |
+
+Our own sample site, an AI-powered consumer web app we launched on 21 September 2026, went through these gates in its first week. It got **333 real ChatGPT visitors in 7 days**, and **11 of its 17 paying customers** came from ChatGPT. Source: the site's own analytics, human sessions only. The site is our own product, not a client. The full story is at https://katman.pro/case-studies/sample-site-first-7-days.
+
+## Install
+
+Katman runs locally with `npx`. Both keys are optional:
+
+- `KATMAN_KEY` (`km_live_…`) unlocks the Pro tools. Get it at https://katman.pro/app → **MCP → Create key** (7-day free trial, no card). The free tools work without it.
+- `OPENROUTER_API_KEY` is only for AI-visibility runs through APIs, paid with your own OpenRouter credits.
+
+**Claude Code**
+```bash
+claude mcp add katman --scope user -e KATMAN_KEY=km_live_... -e OPENROUTER_API_KEY=sk-or-... -- npx -y katman-mcp
+```
+Already added without a key? Run `claude mcp remove katman --scope user` first. With the Katman Claude Code plugin, set its `katman_key` and `openrouter_api_key` options instead.
+
+**Cursor**: add this to `~/.cursor/mcp.json` (your user file, so the key never lands in a repository), or use the "Add to Cursor" button on https://katman.pro/mcp.
+```json
+{ "mcpServers": { "katman": { "command": "npx", "args": ["-y", "katman-mcp"], "env": { "KATMAN_KEY": "km_live_...", "OPENROUTER_API_KEY": "${env:OPENROUTER_API_KEY}" } } } }
+```
+
+**VS Code (Copilot)**: add this to `.vscode/mcp.json`. VS Code asks for the keys once and keeps them in its secret storage.
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "katman_key", "description": "Katman key from katman.pro/app (optional)", "password": true },
+    { "type": "promptString", "id": "openrouter_api_key", "description": "OpenRouter API key (optional)", "password": true }
+  ],
+  "servers": { "katman": { "type": "stdio", "command": "npx", "args": ["-y", "katman-mcp"], "env": { "KATMAN_KEY": "${input:katman_key}", "OPENROUTER_API_KEY": "${input:openrouter_api_key}" } } }
+}
+```
+
+**Codex CLI**
+```bash
+codex mcp add katman --env KATMAN_KEY=km_live_... --env OPENROUTER_API_KEY=sk-or-... -- npx -y katman-mcp
+```
+
+**Gemini CLI**: Gemini strips inherited `*KEY*` variables, so pass the keys explicitly.
+```bash
+gemini mcp add -s user -e KATMAN_KEY=km_live_... -e OPENROUTER_API_KEY=sk-or-... katman npx -- -y katman-mcp
+```
+
+**Claude Desktop, Windsurf/Devin Desktop, Zed, Cline**: use the same `mcpServers` block as for Cursor, with `command: "npx"`, `args: ["-y", "katman-mcp"]` and the keys under `env`.
+
+After adding or changing a key, restart the Katman server (or reload the editor window) and call `katman_account` to check the plan.
+
+## First session
+
+Open your project in your editor and tell your AI:
+
+> Use Katman to make this site recommendable by ChatGPT. Start with katman_start.
+
+Katman then walks your agent through four steps. Step 1 and the diagnosis in step 2 (scan and audit) are free; the rest is Katman Pro:
+
+1. **Research** (`katman_research`): your one sentence (what the customer brings, what you do, what they get, which fear is unnecessary), a not-X note, 10–12 customer situations written without your brand name, competitors (with source and date), proof and a question set.
+2. **Plan** (`katman_scan_code`, `katman_audit_site`, `katman_plan`): a report of what's broken, with no code changes. Then a page plan and a task list ordered like a 30-day plan.
+3. **Build** (`katman_prompt` P0–P14, `katman_page_brief`, `katman_generate`): exact prompts for your AI, each with an acceptance criterion, plus generated robots.txt, llms.txt, JSON-LD and analytics snippets.
+4. **Verify** (`katman_audit_site`, `katman_lint_content`, `katman_indexnow`): Katman checks that each acceptance criterion is really met, then notifies search engines about new or changed URLs only.
+
+Measure every 14 days with `katman_visibility_run` (API) or `katman_manual_check` (answers you paste from the ChatGPT/Claude/Perplexity apps).
+
+## Tools
+
+| Tool | Plan | What it does | Writes |
+|---|---|---|---|
+| `katman_start` | Free | Shows where you are in the method and the exact next call (plus a one-line plan status when `KATMAN_KEY` is set) | `config.json` (site URL) |
+| `katman_research` | Free | Research template, merge and validation, 12+2 question set | `research.json`, `research.md` |
+| `katman_keywords` | Free | Google autocomplete expansion into situation and single-question page ideas (≤40 throttled requests) | `research.json` (optional) |
+| `katman_scan_code` | Free | Framework, rendering (SSR/SSG/CSR), routes, head tags, robots/sitemap/llms.txt, JSON-LD, links, images, analytics | `scan.json` |
+| `katman_audit_site` | Free | Live audit as AI crawlers see it: bot access through your CDN, JS-off text, 404s, canonicals, sitemap, hreflang, JSON-LD, internal links | `audits/`, `audit.md` |
+| `katman_account` | Free | Your plan (free, trial days left, Pro), features, masked account email, last key check, how to connect or upgrade | — |
+| `katman_plan` | Pro | Page plan and task list with P-codes and acceptance criteria (keeps your checkboxes) | `plan.json`, `plan.md` |
+| `katman_prompt` | Pro | Prompt P0–P14 filled with your data, plus Accept / Why / How Katman verifies | — |
+| `katman_page_brief` | Pro | Brief for a situation, comparison, pricing, FAQ or about page, and where the file goes in your framework | — |
+| `katman_generate` | Pro | robots.txt, llms.txt, Organization/WebSite/SoftwareApplication/FAQ/Breadcrumb JSON-LD, AI-channel analytics snippet, server-side bot counter, IndexNow key | only with `write: true`, never overwrites without `overwrite: true` |
+| `katman_lint_content` | Pro | Checks a page against the content rules: answer-first, same one sentence, no hype, sourced numbers, FAQ, not-for, links | — |
+| `katman_visibility_run` | Pro | Asks your question set to ChatGPT, Claude, Gemini, Perplexity and Grok models with live web search via OpenRouter (API answers are a proxy for the consumer apps). Dry run and cost estimate first; presets economy/full/probe; `samples` for stability | `runs/`, `measurements.md` |
+| `katman_manual_check` | Pro | Records an answer you paste from a consumer app (logged out, search on); no API cost | `runs/`, `measurements.md` |
+| `katman_indexnow` | Pro | Submits only new or changed URLs to IndexNow, plus a Search Console / Bing / Brave checklist | `indexnow.json` |
+| `katman_setup_monitoring` | Pro | GitHub Actions workflow that re-measures weekly with your own keys | `.github/workflows/katman.yml` only with `write: true` |
+| `katman_report` | Pro | Shareable report: gates, visibility deltas, competitors, cited domains, next 7 days | `report.md` |
+| `katman_sync` | Pro | Sends your progress to your katman.pro dashboard: gate pass counts, visibility rates by assistant and language, plan progress, top 10 issue titles, dates, Katman version. Never code, file contents, answers, questions or prompts. Dry run (the exact JSON) by default | — |
+
+Slash-command prompts: `katman-start`, `katman-audit`, `katman-situation-page`, `katman-measure`.
+
+## What Katman can and can't do
+
+- **Reads** files in your project, but skips `node_modules`, `.git` and build output, and **never** reads `.env*`, `.dev.vars*`, keys, certificates or credential files.
+- **Writes** only to `.katman/` in your project, except `katman_generate` and `katman_setup_monitoring` when you pass `write: true`.
+- **Network**: your own site (audits), `openrouter.ai` (visibility runs, with your key, after a dry run), `api.indexnow.org` (only when you submit), `suggestqueries.google.com` (only `katman_keywords`), and `katman.pro` only for two things: checking your `KATMAN_KEY` (at most once a day, only when the key is set) and `katman_sync` (only with `dry_run: false`). **No telemetry**: without a key, nothing is sent to Katman; the key check sends only the key and the Katman version.
+- **Your keys** (`KATMAN_KEY`, `OPENROUTER_API_KEY`) are read from the environment and are never printed or written to disk. The license check is cached in `~/.katman/license.json` under the key's SHA-256 hash (never the key); if katman.pro can't be reached, Pro keeps working for 7 days after the last successful check.
+- **No automation of consumer chat apps.** Katman doesn't drive chatgpt.com, claude.ai or perplexity.ai with a headless browser: their terms forbid programmatic extraction, and it gets accounts banned. It uses the providers' own web-search models through OpenRouter. For the consumer apps, you paste answers into `katman_manual_check`.
+- **No ranking guarantees.** A single measurement run is a small sample, so re-run the same questions every 14 days.
+
+## Costs
+
+Katman itself: the diagnosis is free; Katman Pro is $29/month (founding price) after a 7-day free trial. On top of that, API visibility runs use your own OpenRouter credits; search results are billed as input tokens, so they're not pennies:
+
+| Panel | What | Typical cost per run (14 questions) |
+|---|---|---|
+| `economy` (default) | ChatGPT, Claude, Gemini, Perplexity, Grok — smaller models, native search | ≈ $2.4 (range $1.2–3.7) |
+| `full` | the same five with flagship models | ≈ $4.6 (range $2.2–6.9) |
+| `probe` | ChatGPT + Perplexity only | ≈ $1.8 (range $0.7–2.8) |
+
+The exact estimate is shown before anything runs, and `max_cost_usd` (default $3) refuses runs that would cost more. Checking the consumer apps by hand with `katman_manual_check` costs no API credits.
+
+## CLI
+
+```bash
+npx -y katman-mcp scan [path]                             # free
+npx -y katman-mcp audit https://your.site --max 50        # free
+npx -y katman-mcp keywords "invoice software" --lang en   # free
+npx -y katman-mcp account [--refresh]                     # free: your plan
+npx -y katman-mcp indexnow --root . [--submit]            # dry run free; --submit is Pro
+npx -y katman-mcp check --root . [--yes] [--max-cost 2]   # Pro: visibility run; dry run without --yes
+npx -y katman-mcp plan --root .                           # Pro
+npx -y katman-mcp report --root .                         # Pro
+```
+
+Pro commands read `KATMAN_KEY` from the environment (`KATMAN_KEY=km_live_... npx -y katman-mcp report --root .`; in GitHub Actions, a repository secret) and exit with code 4 and a short explanation without it.
+
+## Files
+
+Everything Katman learns about your project lives in `.katman/`: `research.json`/`.md`, `scan.json`, `audits/`, `runs/`, `measurements.md`, `plan.md`, `report.md`, `log.md`. It contains no secrets, and it's worth committing, because it's the history of what you changed and what happened. The only file outside the project is the license cache `~/.katman/license.json` (key hash, plan, last check).
+
+---
+
+Made by the Katman team · https://katman.pro · hello@katman.pro

package/dist/cli.js

@@ -0,0 +1,71 @@
+// CLI dispatcher. Each module contributes commands via its cli.ts.
+import path from "node:path";
+import { VERSION } from "./meta.js";
+import * as method from "./tools/method/cli.js";
+import * as crawl from "./tools/crawl/cli.js";
+import * as visibility from "./tools/visibility/cli.js";
+import * as account from "./tools/account/cli.js";
+import { EXIT_NEEDS_PRO, cliFeature, defaultLicense, requirePro, toolForFeature } from "./license.js";
+import { projectFacts, renderUpsell } from "./tools/account/upsell.js";
+export async function runCli(args, deps = {}) {
+    const [cmd, ...rest] = args;
+    if (cmd === "--version" || cmd === "-v" || cmd === "version") {
+        console.log(VERSION);
+        return 0;
+    }
+    const all = { ...method.commands, ...crawl.commands, ...visibility.commands, ...account.commands };
+    const fn = all[cmd];
+    if (!fn) {
+        printHelp();
+        return cmd === "help" || cmd === "--help" || cmd === "-h" ? 0 : 1;
+    }
+    // Katman Pro commands (plan, report, check, indexnow --submit): same gate as the MCP tools.
+    const feature = cliFeature(cmd, rest);
+    if (feature) {
+        const gate = await requirePro(feature, deps.license ?? defaultLicense());
+        if (!gate.allowed) {
+            const { _, flags } = parseArgs(rest);
+            const root = path.resolve(typeof flags.root === "string" ? flags.root : cmd === "plan" || cmd === "report" ? (_[0] ?? process.cwd()) : process.cwd());
+            const facts = await projectFacts(root).catch(() => undefined);
+            const command = `katman-mcp ${cmd}${cmd === "indexnow" ? " --submit" : ""}`;
+            console.error(renderUpsell({ tool: toolForFeature(feature), feature, status: gate.status, facts, surface: "cli", command }));
+            return EXIT_NEEDS_PRO;
+        }
+    }
+    return fn(rest, deps);
+}
+function printHelp() {
+    const lines = [
+        `katman-mcp ${VERSION} — make your site readable, quotable and recommendable by AI assistants`,
+        "",
+        "Usage:",
+        "  katman-mcp                 start the MCP server (stdio) — add it to Cursor, Claude Code, VS Code…",
+        ...method.help,
+        ...crawl.help,
+        ...visibility.help,
+        ...account.help,
+        "",
+        "Docs: https://katman.pro/docs",
+    ];
+    console.log(lines.join("\n"));
+}
+/** Tiny flag parser: --key value, --flag, positional args. */
+export function parseArgs(args) {
+    const out = { _: [], flags: {} };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = args[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                out.flags[key] = next;
+                i++;
+            }
+            else
+                out.flags[key] = true;
+        }
+        else
+            out._.push(a);
+    }
+    return out;
+}

package/dist/context.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import os from "node:os";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * Resolve the project root: explicit argument → KATMAN_PROJECT_ROOT → first MCP root
+ * advertised by the client → process.cwd().
+ */
+export async function resolveRoot(ctx, explicit) {
+    if (explicit && explicit.trim())
+        return path.resolve(explicit.trim());
+    if (process.env.KATMAN_PROJECT_ROOT)
+        return path.resolve(process.env.KATMAN_PROJECT_ROOT);
+    try {
+        const caps = ctx.server?.server.getClientCapabilities();
+        if (caps?.roots && ctx.server) {
+            const res = await ctx.server.server.listRoots();
+            const first = res.roots.find((r) => r.uri.startsWith("file://"));
+            if (first)
+                return fileURLToPath(first.uri);
+        }
+    }
+    catch {
+        // client doesn't support roots; fall through
+    }
+    return process.cwd();
+}
+const PROJECT_MARKERS = [
+    "package.json", "index.html", "astro.config.mjs", "astro.config.ts", "next.config.js",
+    "next.config.mjs", "next.config.ts", "nuxt.config.ts", "svelte.config.js", "vite.config.ts",
+    "vite.config.js", "wrangler.toml", "wrangler.jsonc", "hugo.toml", "_config.yml", "Gemfile",
+    "requirements.txt", "pyproject.toml", "composer.json", "go.mod",
+];
+/** Returns a warning when the root doesn't look like a web project (e.g. the home directory). */
+export function rootWarning(root) {
+    if (root === "/" || root === os.homedir()) {
+        return `Project root resolved to ${root}, which is not a project folder. Pass project_root with the absolute path of the website's codebase.`;
+    }
+    if (!PROJECT_MARKERS.some((m) => existsSync(path.join(root, m)))) {
+        return `No project files (package.json, index.html, framework config…) found in ${root}. If this is wrong, pass project_root.`;
+    }
+    return undefined;
+}

package/dist/crawlers.js

@@ -0,0 +1,86 @@
+export const CRAWLERS = [
+    // OpenAI
+    { token: "GPTBot", org: "OpenAI", purpose: "training", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.4; +https://openai.com/gptbot",
+        note: "Training only. OpenAI: blocking GPTBot does not affect ChatGPT search." },
+    { token: "OAI-SearchBot", org: "OpenAI", purpose: "search", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36; compatible; OAI-SearchBot/1.4; +https://openai.com/searchbot",
+        note: "Fills ChatGPT's search index. Blocking it removes you from ChatGPT search answers." },
+    { token: "ChatGPT-User", org: "OpenAI", purpose: "user", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot",
+        note: "Opens a page when a ChatGPT user asks for it; OpenAI says robots.txt may not apply." },
+    // Anthropic
+    { token: "ClaudeBot", org: "Anthropic", purpose: "training", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)" },
+    { token: "Claude-SearchBot", org: "Anthropic", purpose: "search", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Claude-SearchBot/1.0; +searchbot@anthropic.com)" },
+    { token: "Claude-User", org: "Anthropic", purpose: "user", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Claude-User/1.0; +claude-user@anthropic.com)" },
+    // Perplexity
+    { token: "PerplexityBot", org: "Perplexity", purpose: "search", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)" },
+    { token: "Perplexity-User", org: "Perplexity", purpose: "user", rendersJs: false, testAccess: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Perplexity-User/1.0; +https://perplexity.ai/perplexity-user)",
+        note: "Perplexity: this fetcher generally ignores robots.txt." },
+    // Search engines (they render JavaScript; CDNs verify them by IP)
+    { token: "Googlebot", org: "Google", purpose: "search+training", rendersJs: true, testAccess: true, ipVerified: true,
+        ua: "Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.7339.207 Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)",
+        note: "Feeds Google Search, AI Overviews and AI Mode. Google verifies Googlebot by IP; check real access in Search Console → Crawl stats." },
+    { token: "Bingbot", org: "Microsoft", purpose: "search+training", rendersJs: true, testAccess: true, ipVerified: true,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm) Chrome/140.0.7339.207 Safari/537.36",
+        note: "Copilot, ChatGPT search and DuckDuckGo draw on Bing's index." },
+    { token: "Applebot", org: "Apple", purpose: "search+training", rendersJs: true, testAccess: true, ipVerified: true,
+        ua: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15 (Applebot/0.1; +http://www.apple.com/go/applebot)" },
+    { token: "CCBot", org: "Common Crawl", purpose: "training", rendersJs: false, testAccess: true,
+        ua: "CCBot/2.0 (https://commoncrawl.org/faq/)" },
+    // Not access-tested (smaller, user-triggered or to-be-blocked), but known for robots.txt analysis.
+    { token: "Bytespider", org: "ByteDance", purpose: "training", rendersJs: false, testAccess: false,
+        ua: "Mozilla/5.0 (Linux; Android 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Mobile Safari/537.36 (compatible; Bytespider; spider-feedback@bytedance.com)",
+        note: "Widely reported to ignore robots.txt; block it with a WAF rule if you don't want it." },
+    { token: "Google-Agent", org: "Google", purpose: "user", rendersJs: true, testAccess: false,
+        ua: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko; compatible; Google-Agent; +https://developers.google.com/crawling/docs/crawlers-fetchers/google-agent) Chrome/140.0.7339.207 Safari/537.36",
+        note: "User-triggered browser agent; generally ignores robots.txt." },
+    { token: "Amazonbot", org: "Amazon", purpose: "search+training", rendersJs: false, testAccess: false,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Amazonbot/0.1; +https://developer.amazon.com/support/amazonbot) Chrome/119.0.6045.214 Safari/537.36" },
+    { token: "Amzn-SearchBot", org: "Amazon", purpose: "search", rendersJs: false, testAccess: false,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Amzn-SearchBot/0.1; +https://developer.amazon.com/amazonbot) Chrome/119.0.6045.214 Safari/537.36",
+        note: "Alexa / Amazon search answers." },
+    { token: "Amzn-User", org: "Amazon", purpose: "user", rendersJs: false, testAccess: false,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Amzn-User/0.1; +https://developer.amazon.com/amazonbot) Chrome/119.0.6045.214 Safari/537.36" },
+    { token: "meta-externalagent", org: "Meta", purpose: "training", rendersJs: false, testAccess: false,
+        ua: "meta-externalagent/1.1 (+https://developers.facebook.com/docs/sharing/webmasters/crawler)" },
+    { token: "meta-webindexer", org: "Meta", purpose: "search", rendersJs: false, testAccess: false,
+        ua: "meta-webindexer/1.1 (+https://developers.facebook.com/docs/sharing/webmasters/web-crawlers)",
+        note: "Meta AI search answers (new in 2026)." },
+    { token: "meta-externalfetcher", org: "Meta", purpose: "user", rendersJs: false, testAccess: false,
+        ua: "meta-externalfetcher/1.1 (+https://developers.facebook.com/docs/sharing/webmasters/web-crawlers)" },
+    { token: "DuckAssistBot", org: "DuckDuckGo", purpose: "user", rendersJs: false, testAccess: false,
+        ua: "DuckAssistBot/1.2; (+http://duckduckgo.com/duckassistbot.html)" },
+    { token: "MistralAI-User", org: "Mistral", purpose: "user", rendersJs: false, testAccess: false,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; MistralAI-User/1.0; +https://docs.mistral.ai/robots)" },
+    { token: "MistralAI-Index", org: "Mistral", purpose: "search", rendersJs: false, testAccess: false,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; MistralAI-Index/1.0; +https://docs.mistral.ai/robots)" },
+    { token: "MistralAI-Training", org: "Mistral", purpose: "training", rendersJs: false, testAccess: false,
+        ua: "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; MistralAI-Training/1.0; +https://docs.mistral.ai/robots)" },
+];
+/** robots.txt permission tokens that are not separate crawlers (no UA to test). */
+export const PERMISSION_TOKENS = ["Google-Extended", "Applebot-Extended"];
+/** Tokens to name explicitly in a GEO-friendly robots.txt (book appendix A order, then 2026 search/agent tokens). */
+export const ROBOTS_TOKENS = [
+    "Googlebot", "Bingbot", "OAI-SearchBot", "ChatGPT-User", "GPTBot", "ClaudeBot", "Claude-User",
+    "Claude-SearchBot", "PerplexityBot", "Perplexity-User", "Google-Extended", "Applebot",
+    "Applebot-Extended", "DuckAssistBot", "meta-externalagent", "Amazonbot",
+    "meta-webindexer", "meta-externalfetcher", "MistralAI-Index", "MistralAI-User", "Amzn-SearchBot", "Amzn-User",
+];
+/** A normal desktop browser, used as the baseline when comparing what bots receive. */
+export const BROWSER_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36";
+export function crawlerByToken(token) {
+    const t = token.toLowerCase();
+    return CRAWLERS.find((c) => c.token.toLowerCase() === t);
+}
+/** Purpose of a robots.txt token, including permission-only tokens (Google-Extended → training). */
+export function tokenPurpose(token) {
+    if (PERMISSION_TOKENS.some((p) => p.toLowerCase() === token.toLowerCase()))
+        return "training";
+    return crawlerByToken(token)?.purpose ?? "search";
+}

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Katman MCP entry point.
+//   npx -y katman-mcp          → MCP server on stdio
+//   npx -y katman-mcp <cmd>    → CLI (audit, scan, check, report, account…); see `katman-mcp help`
+// Tools are registered in server.ts (method, crawl, visibility and account modules).
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { VERSION } from "./meta.js";
+import { createServer } from "./server.js";
+import { runCli } from "./cli.js";
+export { createServer };
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length && args[0] !== "mcp" && args[0] !== "serve") {
+        process.exitCode = await runCli(args);
+        return;
+    }
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    // stdout belongs to the protocol; log to stderr only.
+    console.error(`katman-mcp ${VERSION} ready (stdio)`);
+}
+main().catch((e) => {
+    console.error(e);
+    process.exit(1);
+});