katman-mcp 0.1.0

package/dist/tools/method/lib/text.js

@@ -0,0 +1,165 @@
+import { composeOneSentence } from "../../../util.js";
+export const FILL = "[FILL]";
+const PLACEHOLDER_RE = /\[(?:FILL|DOLDUR)\b[^\]]*\]/i;
+export function hasPlaceholder(s) {
+    return typeof s === "string" && PLACEHOLDER_RE.test(s);
+}
+/** A value counts as filled when it is a non-empty string without [FILL]/[DOLDUR]. */
+export function isFilled(s) {
+    return typeof s === "string" && s.trim().length > 0 && !hasPlaceholder(s);
+}
+export function orFill(s, fill = FILL) {
+    return isFilled(s) ? s.trim() : fill;
+}
+/** The not-X note is optional when the brand isn't confused with anything; "none" and friends mean "checked, no confusion". */
+export function hasNotX(notX) {
+    return isFilled(notX) && !/^\s*(none|n\/a|na|-|—|yok|hiçbiri|no confusion)\s*\.?\s*$/i.test(notX);
+}
+const TR_MAP = {
+    ç: "c", Ç: "c", ğ: "g", Ğ: "g", ı: "i", İ: "i", ö: "o", Ö: "o", ş: "s", Ş: "s", ü: "u", Ü: "u",
+};
+/** Turkish-aware ASCII folding (ç→c, ı→i …) plus removal of other diacritics. */
+export function asciiFold(s) {
+    return s
+        .replace(/[çÇğĞıİöÖşŞüÜ]/g, (c) => TR_MAP[c] ?? c)
+        .normalize("NFD")
+        .replace(/[̀-ͯ]/g, "");
+}
+const SLUG_STOP = new Set([
+    "i", "a", "an", "the", "my", "me", "is", "are", "am", "was", "to", "of", "and", "or", "but", "for", "with",
+    "on", "in", "at", "it", "its", "there", "that", "this", "can", "do", "how", "what", "which", "any", "some",
+    "be", "im", "ive", "we", "our", "your", "you", "so", "just", "have", "has", "had", "would", "should", "want",
+    "bir", "ve", "ile", "ama", "icin", "mi", "mu", "bu", "su", "da", "de", "ki", "ben", "benim", "var", "cok",
+]);
+/** URL slug from a sentence: lowercase ASCII, hyphens, stopwords dropped, at most `maxWords` words. */
+export function slugify(s, maxWords = 7) {
+    const words = asciiFold(s.toLowerCase())
+        .replace(/['’]/g, "")
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+    const kept = words.filter((w) => !SLUG_STOP.has(w));
+    const use = (kept.length >= 2 ? kept : words).slice(0, maxWords);
+    return use.join("-").slice(0, 60).replace(/-+$/, "");
+}
+/** Normalise a path: leading slash, no trailing slash (except "/"), lowercase. */
+export function normPath(p) {
+    let s = p.trim();
+    try {
+        if (/^https?:\/\//i.test(s))
+            s = new URL(s).pathname;
+    }
+    catch {
+        // keep as is
+    }
+    s = s.split(/[?#]/)[0] || "/";
+    if (!s.startsWith("/"))
+        s = "/" + s;
+    if (s.length > 1)
+        s = s.replace(/\/+$/, "");
+    return s.toLowerCase();
+}
+const ABBREV_RE = /\b(e\.g|i\.e|vs|etc|dr|mr|mrs|ms|no|ör|vb|bkz|approx|inc|ltd)\./gi;
+/** Rough sentence splitter that keeps common abbreviations together. */
+export function splitSentences(text) {
+    const guarded = text.replace(ABBREV_RE, (m) => m.replace(/\./g, "\u0000"));
+    return guarded
+        .split(/(?<=[.!?…]["”’)]?)\s+(?=["“‘(]?[\p{Lu}\p{N}])/u)
+        .map((p) => p.replace(/\u0000/g, ".").replace(/\s+/g, " ").trim())
+        .filter(Boolean);
+}
+export function countWords(s) {
+    return (s.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) ?? []).length;
+}
+const STOP = new Set([
+    // English
+    "a", "an", "the", "and", "or", "but", "to", "of", "in", "on", "at", "for", "with", "by", "from", "as", "is", "are",
+    "was", "were", "be", "been", "it", "its", "this", "that", "these", "those", "you", "your", "we", "our", "us", "they",
+    "their", "i", "me", "my", "he", "she", "his", "her", "them", "do", "does", "did", "can", "will", "would", "should",
+    "could", "not", "no", "so", "if", "then", "than", "into", "about", "over", "any", "all", "some", "just", "only",
+    "also", "very", "there", "here", "what", "which", "who", "how", "when", "where", "why", "have", "has", "had", "get",
+    // Turkish
+    "ve", "ile", "bir", "bu", "şu", "o", "da", "de", "ki", "mi", "mı", "mu", "mü", "için", "ama", "gibi", "daha", "çok",
+    "en", "her", "hiç", "ne", "nasıl", "var", "yok", "olarak", "olan", "sen", "siz", "biz", "ben", "onu", "bunu",
+]);
+function stem(w) {
+    let x = asciiFold(w);
+    if (x.length > 3 && x.endsWith("s") && !x.endsWith("ss"))
+        x = x.slice(0, -1);
+    return x.length > 5 ? x.slice(0, 5) : x;
+}
+/** Content tokens (stopwords removed, crude stems; Turkish suffixes after an apostrophe dropped). */
+export function stemTokens(s) {
+    const lower = s.replace(/İ/g, "i").toLowerCase().replace(/['’][\p{L}]+/gu, "");
+    return lower
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((w) => w.length > 1 && !STOP.has(w))
+        .map(stem);
+}
+/** Share of the reference sentence's content tokens that also appear in `target` (0–1). */
+export function containment(ref, target) {
+    const a = new Set(stemTokens(ref));
+    if (!a.size)
+        return 0;
+    const b = new Set(stemTokens(target));
+    let hit = 0;
+    for (const x of a)
+        if (b.has(x))
+            hit++;
+    return hit / a.size;
+}
+export function pct(x) {
+    return `${Math.round(x * 100)}%`;
+}
+/** Join the four one-liner parts into one readable sentence (brings → we do → gets → fear is unnecessary). */
+export function composeSentence(o) {
+    return composeOneSentence(o, 4);
+}
+/** The brand's one sentence: the hand-written sentence, else the composed four-part one-liner. */
+export function brandSentence(r) {
+    if (!r)
+        return undefined;
+    if (isFilled(r.brand?.sentence))
+        return r.brand.sentence.trim();
+    return composeSentence(r.brand?.oneLiner);
+}
+export function firstSentence(s) {
+    if (!s)
+        return undefined;
+    return splitSentences(s)[0];
+}
+export function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Whole-word, case-insensitive test (works with spaces and Unicode letters in the needle). */
+export function containsPhrase(haystack, needle) {
+    const n = needle.trim();
+    if (!n)
+        return false;
+    const re = new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRegExp(n)}(?=$|[^\\p{L}\\p{N}])`, "iu");
+    return re.test(haystack);
+}
+export function normKey(s) {
+    return asciiFold(s.toLowerCase()).replace(/[^a-z0-9]+/g, " ").trim();
+}
+export function addDays(d, days) {
+    return new Date(d.getTime() + days * 86_400_000);
+}
+export function isoDay(d) {
+    if (!d)
+        return "";
+    const x = typeof d === "string" ? new Date(d) : d;
+    return Number.isNaN(x.getTime()) ? String(d).slice(0, 10) : x.toISOString().slice(0, 10);
+}
+/** Replace {name} placeholders with known values; unknown or empty values become [FILL]. Other braces stay untouched. */
+export function fillTemplate(text, values, known, fill = FILL) {
+    return text.replace(/\{([a-z_]+)\}/g, (m, name) => {
+        if (!known.includes(name))
+            return m;
+        const v = values[name];
+        return isFilled(v) ? v : fill;
+    });
+}
+export function codeBlock(s, lang = "") {
+    const fence = s.includes("```") ? "````" : "```";
+    return `${fence}${lang}\n${s.replace(/\n+$/, "")}\n${fence}`;
+}

package/dist/tools/method/mcp/prompts.js

@@ -0,0 +1,79 @@
+// MCP prompts (slash commands): katman-start, katman-audit, katman-situation-page, katman-measure.
+// Each returns user-role messages that walk the agent through the tools step by step.
+import { z } from "zod";
+const user = (text) => ({ role: "user", content: { type: "text", text } });
+const RULES = `Rules (Katman method):
+- Don't write or change code until you have summarised .katman/research.md and I have approved the page plan (.katman/plan.md).
+- Never invent numbers, reviews, customers, competitor facts or claims. Write [FILL] and ask me.
+- Never put anything into schema, meta tags or llms.txt that isn't visible on the page.
+- Public pages only; don't touch login-only app screens.
+- Never show bots different content than people (cloaking) and never hide instructions for AI in a page.
+- katman_visibility_run spends my OpenRouter credits (default panel "economy" ≈$2.4 per run, "full" ≈$4.6, "probe" ≈$1.8): dry_run first, show me the estimate, wait for my OK.
+- After every change, list the files you changed. A task is done only when its Katman check passes.`;
+export function startPromptText(siteUrl) {
+    return `You are working on this project's public website with Katman. Goal: get the site read, quoted and recommended by ChatGPT, Claude, Gemini and Perplexity, and found in Google, Bing and Brave.
+
+Do this now:
+1. Call katman_start with project_root = the absolute path of this workspace${siteUrl ? ` and site_url = "${siteUrl}"` : " (add site_url if you know the live address; otherwise ask me for it)"}.
+2. Show me its status table in five lines or fewer.
+3. Do exactly the "Next step" it returns — one step at a time — and call katman_start again after each step.
+4. When research is needed: fill what the codebase already says (README, landing copy, pricing page, footer) and ask me for my customers' own sentences, competitors and anything you'd otherwise have to guess.
+
+${RULES}`;
+}
+export function auditPromptText(siteUrl) {
+    return `Audit this site the way AI crawlers see it (Katman prompt P1). REPORT ONLY: do not create, modify or delete any file in the project.
+
+1. Call katman_start (project_root = the absolute path of this workspace${siteUrl ? `, site_url = "${siteUrl}"` : ""}) to load the state and the site URL. If no site URL is known, ask me for it.
+2. Call katman_scan_code.
+3. Call katman_audit_site with the site URL.
+4. From their output, write the P1 report: one row per public page — URL | SSR/SSG/CSR | title + length | meta description + length | canonical | robots meta | H1 count | images without alt | og:image | JSON-LD types | pages linking to it.
+5. Answer: do robots.txt and sitemap.xml exist and how are they generated? Does /this-page-does-not-exist return 404? Are links <a href> or onClick? Is the site also live at a preview/staging address? Do GPTBot, OAI-SearchBot, ClaudeBot and PerplexityBot get 200?
+6. Finish with the 10 most important problems ranked by traffic impact, each with the file that would change and the Katman prompt (P-code) that fixes it.
+
+Don't fix anything yet. When I approve, call katman_plan.`;
+}
+export function situationPromptText(situation) {
+    const target = situation?.trim() ? `"${situation.trim()}"` : "the next situation in research that has no page yet";
+    return `Write one situation page with Katman (prompt P6). Situation: ${target}.
+
+1. Call katman_research with mode "show" (project_root = the absolute path of this workspace). Find the situation by id (s1, s2…) or by its wording. If it isn't there, add it with katman_research mode "update", data.situations = [{ sentence: "<the customer's own words, no brand name>" }].
+2. Call katman_page_brief with type "situation" and situation_id. Show me the brief. Fill every [FILL] from research or ask me — never invent proof, prices or competitor facts.
+3. Call katman_prompt with id "P6" and the same situation_id, and follow it: create the page file where the brief says, add it to the sitemap, and link to it from at least one related page (the footer works).
+4. Call katman_lint_content with file = the new page file, page_type "situation" and situation_id. Fix every FAIL and run it again.
+5. List the files you changed. After deploy: katman_audit_site with urls = [the page URL] must pass (text visible with JavaScript off, at least 1 internal link in, in the sitemap), then katman_indexnow for this URL only.
+
+Don't: put the brand in the H1 or the URL, claim more than the proof, put us first in the alternatives, write "free" for a paid product, or add schema facts that aren't visible on the page.`;
+}
+export function measurePromptText() {
+    return `Measure whether AI assistants name, recommend and cite this site (Katman book, ch. 15).
+
+1. Call katman_research with mode "show" (project_root = the absolute path of this workspace) and check the question set: 12 unbranded questions + 2 diagnostic ones ("What is <brand>?"). If it's missing, call katman_research with generate_questions: true and show me the questions to review before the first run. After the first run, don't change them: runs are only comparable with the same questions, models and temperature.
+2. If OPENROUTER_API_KEY is set: call katman_visibility_run with dry_run: true, show me the calls and the estimated cost (default panel "economy" ≈$2.4 per run; "full" ≈$4.6; "probe" ≈$1.8 — my own OpenRouter credits), and wait for my OK before running it for real. Then run the 3 most important situation questions again with question_ids + samples: 3 — measure how often we're named, not our rank.
+3. Otherwise (or in addition, to confirm the key questions in the real apps): call katman_manual_check, ask the questions in ChatGPT / Claude / Perplexity logged out with web search on, and paste each answer back.
+4. Report three separate rates — mentioned, recommended first, cited — with the change since the previous run, the competitors named instead, and the domains cited (those are the off-site targets, ch. 14).
+5. Tell me the next re-measure date (+14 days) and call katman_report.
+
+Don't: add branded questions beyond the 2 diagnostics, measure from a logged-in account, or treat a single run as a ranking (it is a low sample).`;
+}
+export function registerMethodPrompts(server) {
+    server.registerPrompt("katman-start", {
+        title: "Katman: start / continue",
+        description: "Start or continue the Katman method on this project: status of the 4 steps and the next step.",
+        argsSchema: { site_url: z.string().optional().describe("The live site URL, if known (e.g. https://example.com)") },
+    }, ({ site_url }) => ({ messages: [user(startPromptText(site_url))] }));
+    server.registerPrompt("katman-audit", {
+        title: "Katman: audit (P1, report only)",
+        description: "Audit the site like AI crawlers see it — codebase scan + live audit — and report the top 10 problems without changing code.",
+        argsSchema: { site_url: z.string().optional().describe("The live site URL, if known") },
+    }, ({ site_url }) => ({ messages: [user(auditPromptText(site_url))] }));
+    server.registerPrompt("katman-situation-page", {
+        title: "Katman: write a situation page (P6)",
+        description: "Brief → write → lint → verify one situation page for a customer situation from research.",
+        argsSchema: { situation: z.string().optional().describe("Situation id (e.g. s1) or the customer's sentence; empty = the next situation without a page") },
+    }, ({ situation }) => ({ messages: [user(situationPromptText(situation))] }));
+    server.registerPrompt("katman-measure", {
+        title: "Katman: measure AI visibility",
+        description: "Run the question set (API dry run first, or manual checks), report mention / recommendation / citation rates and schedule the next run.",
+    }, () => ({ messages: [user(measurePromptText())] }));
+}

package/dist/tools/method/mcp/resources.js

@@ -0,0 +1,50 @@
+// MCP resources: the method, checklists, content rules, raw prompts and the current project's research.md.
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { resolveRoot } from "../../../context.js";
+import { PROMPTS, getPrompt } from "../data/prompts.js";
+import { contentRulesMd, methodOverviewMd, prepublishChecklistMd, rawPromptMd, siteAuditChecklistMd } from "../data/render.js";
+import { loadConfigSafe, loadResearchSafe, loadRuns } from "../lib/state.js";
+import { renderResearchMd } from "../core/research.js";
+import { licenseOf, requirePro } from "../../../license.js";
+const MD = "text/markdown";
+function md(uri, text) {
+    return { contents: [{ uri: uri.href, mimeType: MD, text }] };
+}
+export async function researchResourceText(root) {
+    const research = await loadResearchSafe(root);
+    if (!research) {
+        return `# research.md\n\nNo research yet in ${root}/.katman/. Create it with the tool katman_research (mode "template"), then fill it from the codebase and the user's customer sentences.`;
+    }
+    const [runs, config] = await Promise.all([loadRuns(root), loadConfigSafe(root)]);
+    return renderResearchMd(research, runs, config.lang ?? "en");
+}
+export function registerMethodResources(server, ctx) {
+    server.registerResource("katman-method", "katman://method", { title: "The Katman method", description: "3 gates (Read / Quote / Fit), 4 steps, the evidence, the 6 traps, the prompt book P0–P14, the first 30 days.", mimeType: MD }, async (uri) => md(uri, methodOverviewMd("en")));
+    server.registerResource("katman-checklist-prepublish", "katman://checklist/prepublish", { title: "Pre-publish checklist", description: "The one-page checklist before publishing (book ch. 19), each line with the Katman check that proves it.", mimeType: MD }, async (uri) => md(uri, prepublishChecklistMd("en")));
+    server.registerResource("katman-checklist-site-audit", "katman://checklist/site-audit", { title: "Full site audit checklist", description: "Per-URL and site-wide checks (book appendix E) that katman_audit_site runs.", mimeType: MD }, async (uri) => md(uri, siteAuditChecklistMd("en")));
+    server.registerResource("katman-content-rules", "katman://content-rules", { title: "Content rules", description: "Content rules (appendix D), how content is produced without spam, the 11-block situation page anatomy, and the words katman_lint_content flags.", mimeType: MD }, async (uri) => md(uri, contentRulesMd("en")));
+    server.registerResource("katman-prompt", new ResourceTemplate("katman://prompts/{id}", {
+        list: async () => ({
+            resources: PROMPTS.map((p) => ({ uri: `katman://prompts/${p.id}`, name: `${p.id} ${p.title.en}`, title: `${p.id} · ${p.title.en}`, mimeType: MD })),
+        }),
+        complete: {
+            id: (value) => PROMPTS.map((p) => p.id).filter((id) => id.toLowerCase().startsWith((value ?? "").toLowerCase())),
+        },
+    }), { title: "Katman prompt book (P0–P14)", description: "A raw prompt with its acceptance criterion, reason and the Katman check. Use the tool katman_prompt to get it filled with this project's data.", mimeType: MD }, async (uri, variables) => {
+        const raw = Array.isArray(variables.id) ? variables.id[0] : variables.id;
+        const p = getPrompt(String(raw ?? ""));
+        if (!p)
+            return md(uri, `Unknown prompt "${raw}". Valid ids: ${PROMPTS.map((x) => x.id).join(", ")}.`);
+        // The prompt book is Pro content, like the katman_prompt tool: titles and acceptance criteria stay listed,
+        // the prompt bodies need a Pro or trial license.
+        const gate = await requirePro("prompts", licenseOf(ctx));
+        if (!gate.allowed) {
+            return md(uri, `# ${p.id} · ${p.title.en}\n\nThe prompt text is part of Katman Pro (needs KATMAN_KEY). Start the 7-day free trial at https://katman.pro/app, add the key to your MCP config as KATMAN_KEY, then read this resource again or call katman_prompt {"id": "${p.id}"} to get it filled with this project's data.`);
+        }
+        return md(uri, rawPromptMd(p, "en"));
+    });
+    server.registerResource("katman-research", "katman://research", { title: "This project's research.md", description: "The current project's research (brand, one sentence, not-X, situations, competitors, proof, question set, latest measurement), rendered from .katman/research.json.", mimeType: MD }, async (uri) => {
+        const root = await resolveRoot(ctx);
+        return md(uri, await researchResourceText(root));
+    });
+}