katman-mcp 0.1.0 → 0.3.0

package/dist/meta.js

@@ -1,12 +1,31 @@
-export const VERSION = "0.1.0";
+export const VERSION = "0.3.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. */
+/**
+ * Plans (docs/07-APP-SPEC.md §1): nothing is free. Katman Pro, 1 site = $49/month (1 site, 5 audits a month); Katman Pro,
+ * 3 sites = $88/month (3 sites, 30 audits a month); both include every tool. The Audit Week ($3 once, 7 days) is no
+ * longer sold; the package still recognises it for accounts that bought it.
+ */
 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";
+/** The billing page opened on one plan (product ids pro_1 / pro_3); signed-out people are asked to log in first. */
+export const BUY_PRO_1_URL = `${BILLING_URL}?buy=pro_1`;
+export const BUY_PRO_3_URL = `${BILLING_URL}?buy=pro_3`;
+export const PRICING_URL = `${HOMEPAGE}/pricing`;
+/** How to add KATMAN_KEY to each editor's MCP config. */
+export const KEY_DOCS_URL = `${HOMEPAGE}/docs/getting-started`;
+export const PRO_1_PRICE = "$49/month";
+export const PRO_3_PRICE = "$88/month";
+/** Katman Pro, 1 site, in one phrase. */
+export const PRO_1_NOTE = "Katman Pro, 1 site $49/month (1 site, 5 audits a month)";
+/** Katman Pro, 3 sites, in one phrase. */
+export const PRO_3_NOTE = "Katman Pro, 3 sites $88/month (3 sites, 30 audits a month)";
+/** Both plans in one phrase. */
+export const PRO_PRICE_NOTE = `${PRO_1_NOTE} or ${PRO_3_NOTE}; both include every tool`;
+export const PRO_PRICE_NOTE_TR = "Katman Pro, 1 site ayda 49 $ (1 site, ayda 5 denetim) ya da Katman Pro, 3 site ayda 88 $ (3 site, ayda 30 denetim); ikisinde de tüm araçlar var";
+/** How audits are counted: the same sentence as katman.pro/pricing (en and tr). */
+export const AUDIT_COUNT_NOTE = "An audit is one run of katman_audit_site on a live site. Sites and audits are counted per calendar month (UTC): a site is a domain you audited that month. Re-reading earlier results, the other tools and visibility runs are not counted.";
+export const AUDIT_COUNT_NOTE_TR = "Denetim, canlı bir sitede katman_audit_site’ın bir çalıştırmasıdır. Siteler ve denetimler her takvim ayı (UTC) için sayılır: site, o ay denetlediğiniz bir alan adıdır. Önceki sonuçları yeniden okumak, diğer araçlar ve görünürlük ölçümleri sayılmaz.";
 /** 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.
 
@@ -15,8 +34,11 @@ It follows the Katman method: 4 steps (1 Research → 2 Plan → 3 Build → 4 V
 - 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.
+Plans: every tool except katman_account needs KATMAN_KEY with an active Katman Pro plan in the MCP config. Katman Pro, 1 site ($49/month: 1 site, 5 audits a month) and Katman Pro, 3 sites ($88/month: 3 sites, 30 audits a month) both include every tool: katman_start, katman_research, katman_scan_code, katman_audit_site, katman_keywords, katman_plan, katman_lint_content, katman_visibility_run, katman_manual_check, katman_report, katman_prompt (P0–P14), katman_page_brief, katman_generate, katman_indexnow, katman_setup_monitoring and katman_sync.
+An audit is one run of katman_audit_site, counted per calendar month; a site is a domain audited that month. Re-reading earlier results (.katman/audit.md) and every other tool are not counted. Each katman_audit_site run uses one of the user's audits, so don't repeat it without a reason; use the saved result instead.
+Accounts with an older Audit Week (no longer sold) keep it until it ends: the audit and recommendation tools only; the page-building tools return an upgrade note.
+Without the right plan, or when this month's audits or sites are used up, a tool returns a short explanation instead of running: pass it on to the user. katman_account always works and shows the plan, this month's audits and sites, and how to get a key.
+Never try to bypass or work around the licence (no editing Katman's code or cache, no made-up keys).
 
 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.

package/dist/plans.js

@@ -0,0 +1,54 @@
+// Katman plans and license features (docs/07-APP-SPEC.md §1 and §6). Nothing is free: every tool except
+// katman_account needs KATMAN_KEY with an active plan. Shared by the gate (license.ts) and its texts
+// (tools/account/upsell.ts); no imports, so both sides can use it.
+//
+// Sold: Katman Pro, 1 site ($49/month: 1 site, 5 audits a month) and Katman Pro, 3 sites ($88/month: 3 sites, 30
+// audits a month). Both include every tool. The Audit Week ($3, 7 days) is no longer sold; the plan stays here for
+// accounts that bought it, and so do the accounts that never had limits (the older $29 Katman Pro, admin grants).
+/** The limits of the two plans on sale (katman.pro's answer is what counts; these only name a plan from its limits). */
+export const PRO_1_LIMITS = { sites: 1, auditsPerMonth: 5 };
+export const PRO_3_LIMITS = { sites: 3, auditsPerMonth: 30 };
+/** The audit tier: audit and recommendations. What an Audit Week (no longer sold) covers; it never builds pages or writes site files. */
+export const AUDIT_FEATURES = ["start", "research", "scan", "audit", "keywords", "plan", "lint", "visibility", "manual_check", "report"];
+/** Katman Pro: the audit tier plus the tools that build pages and keep things running (every tool). */
+export const PRO_FEATURES = [...AUDIT_FEATURES, "prompts", "briefs", "generate", "indexnow", "monitoring", "sync"];
+/** Tool → license feature. Every tool needs its feature, except the OPEN_TOOLS. */
+export const TOOL_FEATURES = {
+    katman_start: "start",
+    katman_research: "research",
+    katman_scan_code: "scan",
+    katman_audit_site: "audit",
+    katman_keywords: "keywords",
+    katman_plan: "plan",
+    katman_lint_content: "lint",
+    katman_visibility_run: "visibility",
+    katman_manual_check: "manual_check",
+    katman_report: "report",
+    katman_prompt: "prompts",
+    katman_page_brief: "briefs",
+    katman_generate: "generate",
+    katman_indexnow: "indexnow",
+    katman_setup_monitoring: "monitoring",
+    katman_sync: "sync",
+};
+/** Tools that always work, even without a key. */
+export const OPEN_TOOLS = ["katman_account"];
+/** Appended to the description of every audit-tier tool. */
+export const AUDIT_NOTE = " (Katman Pro — needs KATMAN_KEY)";
+/** Appended to the description of every Pro-only tool. */
+export const PRO_NOTE = " (Katman Pro — needs KATMAN_KEY)";
+/** True for the features only Katman Pro unlocks (not in the older Audit Week). */
+export function isProOnly(feature) {
+    return !AUDIT_FEATURES.includes(feature);
+}
+/** The description note for a tool's feature. */
+export function tierNote(feature) {
+    return isProOnly(feature) ? PRO_NOTE : AUDIT_NOTE;
+}
+export function toolForFeature(feature) {
+    return Object.keys(TOOL_FEATURES).find((t) => TOOL_FEATURES[t] === feature) ?? `katman_${feature}`;
+}
+/** The tools of one tier: "audit" = the audit tier (what an Audit Week covers; also in Pro), "pro" = the Pro-only tools. */
+export function toolsOf(tier) {
+    return Object.keys(TOOL_FEATURES).filter((t) => isProOnly(TOOL_FEATURES[t]) === (tier === "pro"));
+}

package/dist/tools/account/account.js

@@ -1,64 +1,94 @@
-// katman_account (free): the Katman plan behind KATMAN_KEY, trial days left, Pro features, masked account
-// email, last check, and how to connect or upgrade. Never shows the key.
-import { FREE_TOOLS, PRO_TOOLS, allows } from "../../license.js";
-import { APP_URL, BILLING_URL, PRO_PRICE_NOTE } from "../../meta.js";
-import { fmtDay, fmtWhen, howToText, reasonText, trialDaysLeft } from "./upsell.js";
+// katman_account (always open, even without a key): the Katman plan behind KATMAN_KEY (none, Katman Pro with this
+// month's audits and sites, or an Audit Week bought earlier with the days left), the tools it unlocks, the masked
+// account email, the last check, and how to get a key or upgrade. Never shows the key.
+import { OPEN_TOOLS, TOOL_FEATURES, allows, toolsOf } from "../../license.js";
+import { APP_URL, AUDIT_COUNT_NOTE, BILLING_URL, BUY_PRO_3_URL, KEYS_URL, PRICING_URL, PRO_PRICE_NOTE } from "../../meta.js";
+import { NO_KEY_TEXT, endedPhrase, fmtDay, fmtWhen, howToText, planDaysLeft, proPlanName, reasonText, usageText } from "./upsell.js";
+function planCell(s, left) {
+    if (s.state === "no_key")
+        return s.hint ? "None (KATMAN_KEY placeholder not filled)" : "None (no KATMAN_KEY)";
+    if (s.state !== "valid")
+        return `None (key ${s.state === "unreachable" ? "not verified" : s.state})`;
+    if (s.plan === "audit")
+        return `Audit Week: ${left ?? "?"} day${left === 1 ? "" : "s"} left (ends ${fmtDay(s.planEndsAt)}; no auto-renewal)`;
+    if (s.plan === "pro")
+        return proPlanName(s.limits);
+    return `No active plan${s.planEnded ? ` (${endedPhrase(s)})` : s.auditWeekUsed ? " (Audit Week used)" : ""}`;
+}
+/** "on", "3 of 10 on" or "off". */
+function onText(tools, s) {
+    const on = tools.filter((t) => allows(s, TOOL_FEATURES[t])).length;
+    return on === tools.length ? "on" : on ? `${on} of ${tools.length} on` : "off";
+}
 export async function runAccount(provider, opts = {}) {
     const now = opts.now ?? new Date();
     const s = await provider.status({ refresh: opts.refresh });
-    const left = trialDaysLeft(s, now);
-    const proTools = Object.keys(PRO_TOOLS);
-    const on = proTools.filter((t) => allows(s, PRO_TOOLS[t]));
-    const planCell = s.state === "no_key"
-        ? "Free (no KATMAN_KEY)"
-        : s.state !== "valid"
-            ? `Free (key ${s.state === "unreachable" ? "not verified" : s.state})`
-            : s.plan === "trial"
-                ? `Trial: ${left ?? "?"} day${left === 1 ? "" : "s"} left (ends ${fmtDay(s.trialEndsAt)})`
-                : s.plan === "pro"
-                    ? "Katman Pro"
-                    : `Free${s.trialEnded ? ` (trial ended ${fmtDay(s.trialEndsAt)})` : ""}`;
+    const left = planDaysLeft(s, now);
+    const auditTools = toolsOf("audit");
+    const proTools = toolsOf("pro");
+    const on = Object.keys(TOOL_FEATURES).filter((t) => allows(s, TOOL_FEATURES[t]));
     const source = s.source === "cache" ? "cached answer" : s.source === "network" ? "just checked" : s.source === "offline-grace" ? `offline grace until ${fmtWhen(s.graceUntil)}` : s.source === "local" ? "not sent: malformed key" : "no key";
     const rows = [
-        ["Plan", planCell],
+        ["Plan", planCell(s, left)],
         ["Account", s.emailMasked ?? "–"],
         ["Key", s.state === "no_key" ? (s.hint ? "placeholder, not filled" : "not set (KATMAN_KEY)") : `${s.keyHint ?? "km_…"} (from KATMAN_KEY)`],
-        ["Pro features", s.features.length ? s.features.join(", ") : "none"],
+        ["Features", s.features.length ? s.features.join(", ") : "none"],
         ["Last check", s.checkedAt ? `${fmtWhen(s.checkedAt)} (${source}${s.nextCheckAt && s.source !== "offline-grace" ? `; next check after ${fmtWhen(s.nextCheckAt)}` : ""})` : `– (${source})`],
     ];
+    if (s.state === "valid" && s.plan === "pro" && s.limits)
+        rows.splice(1, 0, ["Usage", usageText(s.limits, s.usage)]);
+    if (s.state === "valid" && s.updateMcpTo)
+        rows.push(["Update", `katman-mcp ${s.updateMcpTo} or newer is needed to count audits against this plan (audits are off until then): npx -y katman-mcp@latest, restart the MCP server, then katman_account with refresh: true`]);
     if (s.error)
         rows.push(["Connection", `couldn't reach katman.pro: ${s.error}`]);
     const L = ["# Katman account", rows.map(([k, v]) => `- **${k}:** ${v}`).join("\n")];
-    L.push(`**Free tools** (no key): ${FREE_TOOLS.join(", ")}.`, `**Pro tools** (${on.length === proTools.length ? "on" : on.length ? `${on.length} of ${proTools.length} on` : "off"}): ${proTools.join(", ")}.`);
+    L.push([
+        `**Audit tools** (${onText(auditTools, s)}; Katman Pro): ${auditTools.join(", ")}.`,
+        `**Page-building tools** (${onText(proTools, s)}; Katman Pro): ${proTools.join(", ")}.`,
+        `**Always open:** ${OPEN_TOOLS.join(", ")}.`,
+    ].join("\n"));
     if (s.state === "valid" && s.plan === "pro") {
+        if (s.limits)
+            L.push(`${AUDIT_COUNT_NOTE}${s.limits.auditsPerMonth === 5 ? ` Katman Pro, 3 sites allows 3 sites and 30 audits a month: ${BUY_PRO_3_URL}.` : ""}`);
         L.push(`Manage the subscription and invoices at ${BILLING_URL}.`);
     }
-    else if (s.state === "valid" && s.plan === "trial") {
-        L.push(`Keep Pro after the trial: ${BILLING_URL} (${PRO_PRICE_NOTE}). The key stays the same.`);
+    else if (s.state === "valid" && s.plan === "audit") {
+        L.push(`Your Audit Week ends on ${fmtDay(s.planEndsAt)} and doesn't renew. Katman Pro builds the pages (the P0–P14 prompts, page briefs, file generation, IndexNow, monitoring and the dashboard sync): ${PRO_PRICE_NOTE}. Upgrade at ${BILLING_URL}; the key stays the same.`);
     }
     else {
-        if (s.state !== "no_key" || s.hint)
-            L.push(`**Why Pro tools are off:** ${reasonText(s)}`);
+        if (s.state === "no_key" && !s.hint)
+            L.push(NO_KEY_TEXT);
+        else
+            L.push(`**Why the tools are off:** ${reasonText(s)}`);
         L.push(howToText(s));
     }
-    L.push(`Network: Katman contacts katman.pro only to check this key (at most once a day, only when KATMAN_KEY is set) and when you call katman_sync. The key is never shown or written to disk; the cache (~/.katman/license.json) stores its SHA-256 hash. Account and keys: ${APP_URL}.`);
+    L.push(`Network: Katman contacts katman.pro only to check this key (at most once a day and when a plan ends, only when KATMAN_KEY is set), to count an audit (right before each katman_audit_site run; it sends the domain being audited) and when you call katman_sync. The key is never shown or written to disk; the cache (~/.katman/license.json) stores its SHA-256 hash. Plans: ${PRICING_URL} · account and keys: ${APP_URL}.`);
     return {
         text: L.join("\n\n"),
         structured: {
             state: s.state,
             plan: s.plan,
-            trialEndsAt: s.trialEndsAt ?? null,
-            trialDaysLeft: left ?? null,
-            trialEnded: !!s.trialEnded,
+            planEndsAt: s.planEndsAt ?? null,
+            planDaysLeft: left ?? null,
+            planEnded: !!s.planEnded,
+            endedPlan: s.endedPlan ?? null,
+            auditWeekUsed: !!s.auditWeekUsed,
+            limits: s.limits ?? null,
+            usage: s.usage ?? null,
+            updateMcpTo: s.updateMcpTo ?? null,
             features: s.features,
             account: { emailMasked: s.emailMasked ?? null },
             checkedAt: s.checkedAt ?? null,
             nextCheckAt: s.nextCheckAt ?? null,
             source: s.source,
             graceUntil: s.graceUntil ?? null,
-            freeTools: [...FREE_TOOLS],
+            auditTools,
             proTools,
-            proToolsOn: on,
+            openTools: [...OPEN_TOOLS],
+            toolsOn: on,
+            pricingUrl: PRICING_URL,
+            upgradeUrl: BILLING_URL,
+            keysUrl: KEYS_URL,
         },
     };
 }

package/dist/tools/account/cli.js

@@ -16,6 +16,9 @@ export const commands = {
     },
 };
 export const help = [
-    "  katman-mcp account [--refresh]  Katman plan behind KATMAN_KEY (free / trial / Pro) and how to connect or upgrade",
-    "                             Pro commands (plan, report, check, indexnow --submit) need KATMAN_KEY; exit code 4 without it",
+    "  katman-mcp account [--refresh]  your Katman plan (none / Katman Pro / an older Audit Week), this month's audits and sites, and how to get a key or upgrade",
+    "",
+    "Every command except account, --help and --version needs KATMAN_KEY with an active Katman Pro plan (1 site $49/month: 5 audits a month;",
+    "3 sites $88/month: 30 audits a month; every command is included). Without it, or when this month's audits or sites are used, a command",
+    "explains why and exits with code 4. `audit` counts as one audit; every other command is not counted. Plans: https://katman.pro/pricing",
 ];

package/dist/tools/account/index.js

@@ -1,17 +1,17 @@
-// Account module: katman_account (free: plan, trial days, features, how to connect/upgrade) and katman_sync
-// (Pro: sends aggregates to the katman.pro dashboard; dry run first).
+// Account module: katman_account (always open: plan, days left, features, how to get a key or upgrade) and
+// katman_sync (Katman Pro: sends aggregates to the katman.pro dashboard; dry run first).
 import { z } from "zod";
 import { resolveRoot, rootWarning } from "../../context.js";
-import { PRO_NOTE, licenseOf, withPro } from "../../license.js";
+import { licenseOf, tierNote, withPlan } from "../../license.js";
 import { fail, ok } from "../../util.js";
 import { runAccount } from "./account.js";
 import { runSync } from "./sync.js";
 export function registerAccountTools(server, ctx) {
     server.registerTool("katman_account", {
         title: "Katman account and plan",
-        description: "Free. Shows the Katman plan behind KATMAN_KEY (free, trial with the days left, or Pro), the Pro features it unlocks, the account email (masked), when the key was last checked, and how to connect or upgrade (7-day free trial at katman.pro/app, with the exact MCP config snippet per editor). Checks the key with katman.pro at most once a day; refresh: true re-checks now (e.g. right after upgrading). Never shows the key.",
+        description: "Always works, even without a key. Shows the Katman plan behind KATMAN_KEY (none, Katman Pro 1 site or 3 sites with this month's audits and sites used, or an older Audit Week with the days left), the tools it unlocks, the account email (masked), when the key was last checked, and how to get a key or upgrade (the plans at katman.pro/pricing, with the exact MCP config snippet per editor). Checks the key with katman.pro at most once a day; refresh: true re-checks now (e.g. right after buying). Never shows the key.",
         inputSchema: {
-            refresh: z.boolean().optional().describe("Re-check the key with katman.pro now instead of using today's cached answer (e.g. right after upgrading)."),
+            refresh: z.boolean().optional().describe("Re-check the key with katman.pro now instead of using today's cached answer (e.g. right after buying or upgrading)."),
         },
         annotations: { title: "Katman account", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async ({ refresh }) => {
@@ -26,13 +26,13 @@ export function registerAccountTools(server, ctx) {
     server.registerTool("katman_sync", {
         title: "Sync progress to the katman.pro dashboard",
         description: "Sends this project's progress to the user's katman.pro dashboard: name and domain, gate pass counts from the latest audit, visibility rates by assistant and language from the latest run, plan progress, the top 10 issue titles, dates and the Katman version. Never code, file contents, AI answers, questions or prompts. dry_run (default true) shows the exact JSON and sends nothing; dry_run: false sends it and returns the dashboard link." +
-            PRO_NOTE,
+            tierNote("sync"),
         inputSchema: {
             project_root: z.string().optional().describe("Absolute path of the project (where .katman/ lives)."),
             dry_run: z.boolean().optional().describe("Default true: show the exact payload, send nothing. false = send it to katman.pro."),
         },
         annotations: { title: "Sync to katman.pro", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-    }, withPro(ctx, "sync", async ({ project_root, dry_run }) => {
+    }, withPlan(ctx, "sync", async ({ project_root, dry_run }) => {
         try {
             const root = await resolveRoot(ctx, project_root);
             const out = await runSync(root, licenseOf(ctx), { dry_run }, { version: ctx.version });

package/dist/tools/account/sync.js

@@ -127,8 +127,8 @@ export async function runSync(root, provider, args, opts) {
     }
     const why = res.error === "invalid_key" || res.error === "revoked" || res.error === "no_key"
         ? `katman.pro did not accept KATMAN_KEY (${res.error}). Create a key at ${KEYS_URL}, put it in the MCP config as KATMAN_KEY and restart the server.`
-        : res.error === "not_pro" || res.status === 402 || res.status === 403
-            ? `katman.pro says this account has no active Katman Pro plan or trial (${res.error}). Upgrade at ${BILLING_URL}, then call katman_account with refresh: true.`
+        : res.error === "pro_required" || res.error === "not_pro" || res.status === 402 || res.status === 403
+            ? `katman.pro says this account has no active Katman Pro plan (${res.error}); the dashboard sync is part of Katman Pro. Upgrade at ${BILLING_URL}, then call katman_account with refresh: true.`
             : res.status === 0
                 ? `Couldn't reach katman.pro (${res.message ?? res.error ?? "network error"}). Nothing was sent; try again later.`
                 : res.status === 429