crawlmark-mcp 0.1.0 → 0.1.1

package/dist/setup/vendor-mcp-step.js

@@ -0,0 +1,339 @@
+/**
+ * The `vendor-mcp` step: add Semrush's and Ahrefs' own remote MCP servers to the user's AI apps, for ad-hoc questions.
+ * crawlmark never calls these servers and never writes a key for them: sign-in is OAuth in the app. Every change is
+ * previewed, asked about and backed up the same way as the crawlmark registration (src/setup/apps.ts), other servers are
+ * never touched, and an existing entry with the same URL is "already". A different entry with the same name is replaced
+ * only on an explicit yes (the default is no, so --yes never replaces one).
+ */
+import { existsSync } from "node:fs";
+import { backupFile, mergeMcpServersJson, readIfExists, writeConfigWithBackup } from "../lib/claude-config.js";
+import { claudeCodeVendorArgs, codexVendorArgs, codexVendorSnippet, cursorVendorEntry, desktopConnectorSteps, parseClaudeVendorGet, parseCodexVendorGet, planCodexVendorTomlEdit, readCodexVendorToml, VENDOR_IDS, VENDORS, } from "../lib/vendor-mcp.js";
+import { APP_LABELS, cmdLine, detectApps, runApp } from "./apps.js";
+import { PromptAbortedError } from "./prompter.js";
+import { uiFor } from "./ui.js";
+import { works } from "./wizard.js";
+const OAUTH_NEXT = {
+    "claude-code": "In Claude Code, run /mcp and sign in to {label}.",
+    "claude-desktop": "",
+    cursor: "Restart Cursor (or reload its MCP servers), then sign in to {label} when it asks.",
+    codex: "If Codex needs it, sign in with `codex mcp login {name}`.",
+};
+function signInNote(app, v) {
+    return OAUTH_NEXT[app].replace("{label}", v.label).replace("{name}", v.name);
+}
+/** What an existing entry is, for display: its URL or command only (never headers, env or keys). */
+function describeExisting(r) {
+    return `${r.url ? `url ${r.url}` : r.command ? `command ${r.command}` : "unknown"}${r.scope ? `  [scope: ${r.scope}]` : ""}`;
+}
+async function addClaudeCode(ctx, probe, v, notes) {
+    const addArgs = claudeCodeVendorArgs(v);
+    if (!probe.detected) {
+        notes.push({ kind: "warn", text: `Claude Code isn't installed (no working \`claude\` command). To add ${v.label} later: ${cmdLine("claude", addArgs)}` });
+        return "manual";
+    }
+    const existing = await ctx.exec("claude", ["mcp", "get", v.name]);
+    const add = async () => {
+        const r = await runApp(ctx, "claude", addArgs);
+        notes.push(r.code === 0 ? { kind: "success", text: `Added ${v.label} to Claude Code. ${signInNote("claude-code", v)}` } : { kind: "fail", text: `\`claude mcp add\` for ${v.label} failed (exit ${r.code}).` });
+        return r.code === 0 ? "registered" : "failed";
+    };
+    if (existing.code !== 0) {
+        ctx.out(`This adds ${v.label} to Claude Code for all your projects:`);
+        ctx.out(`  ${cmdLine("claude", addArgs)}`);
+        if (!(await ctx.prompt.confirm(`Add ${v.label}'s MCP server to Claude Code?`, true))) {
+            notes.push({ kind: "info", text: `Skipped ${v.label} in Claude Code.` });
+            return "skipped";
+        }
+        if (ctx.dryRun) {
+            notes.push({ kind: "info", text: `Dry run: ${v.label} not added to Claude Code.` });
+            return "dry-run";
+        }
+        return add();
+    }
+    const current = parseClaudeVendorGet(existing.stdout);
+    if (!current) {
+        ctx.out(`Claude Code has a ${v.name} entry the wizard can't read; leaving it alone.`);
+        notes.push({ kind: "warn", text: `To replace it yourself: claude mcp remove ${v.name} -s <scope>, then ${cmdLine("claude", addArgs)}` });
+        return "manual";
+    }
+    if (current.url === v.url) {
+        notes.push({ kind: "success", text: `Claude Code: ${v.label} is already added.` });
+        return "already";
+    }
+    const scope = current.scope ?? "user";
+    ctx.out(`Claude Code already has a ${v.name} server, with a different setting:`);
+    ctx.out(`  current: ${describeExisting(current)}`);
+    ctx.out(`  new:     url ${v.url}  [scope: user]`);
+    if (!(await ctx.prompt.confirm(`Replace it (claude mcp remove ${v.name} -s ${scope}, then add)?`, false))) {
+        notes.push({ kind: "info", text: `Kept the existing ${v.name} entry in Claude Code.` });
+        return "skipped";
+    }
+    if (ctx.dryRun) {
+        notes.push({ kind: "info", text: `Dry run: Claude Code's ${v.name} entry not replaced.` });
+        return "dry-run";
+    }
+    const removed = await runApp(ctx, "claude", ["mcp", "remove", v.name, "-s", scope]);
+    if (removed.code !== 0) {
+        notes.push({ kind: "fail", text: `\`claude mcp remove ${v.name} -s ${scope}\` failed (exit ${removed.code}); nothing was added.` });
+        return "failed";
+    }
+    return add();
+}
+async function addCursor(ctx, v, notes) {
+    const app = APP_LABELS.cursor;
+    const path = ctx.paths.cursorConfig;
+    if (!path)
+        return "manual";
+    const entry = cursorVendorEntry(v);
+    try {
+        const merge = mergeMcpServersJson(readIfExists(path), entry, { app, name: v.name });
+        if (!merge.changed) {
+            notes.push({ kind: "success", text: `${app} already has ${v.label} (${path}).` });
+            return "already";
+        }
+        const prev = merge.previous;
+        const lines = [
+            merge.otherServers.length ? `Other servers kept unchanged: ${merge.otherServers.join(", ")}` : "No other servers in the file.",
+            ...(merge.replaced ? [`Current ${v.name} entry (replaced): ${describeExisting({ url: typeof prev?.url === "string" ? prev.url : undefined, command: typeof prev?.command === "string" ? prev.command : undefined })}`] : []),
+            merge.replaced ? `New ${v.name} entry:` : `Adds this ${v.name} entry:`,
+            ...JSON.stringify(entry, null, 2).split("\n").map((l) => `    ${l}`),
+        ];
+        uiFor(ctx).preview(`${app} config: ${path}`, lines);
+        const question = merge.replaced ? `Replace the existing ${v.name} entry? (the current file is kept as .bak)` : "Write this change? (the current file is kept as .bak)";
+        if (!(await ctx.prompt.confirm(question, !merge.replaced))) {
+            notes.push({ kind: "info", text: `Skipped ${v.label} in ${app}.` });
+            return "skipped";
+        }
+        if (ctx.dryRun) {
+            notes.push({ kind: "info", text: `Dry run: ${app} config not written.` });
+            return "dry-run";
+        }
+        const backup = writeConfigWithBackup(path, merge.text);
+        notes.push({ kind: "success", text: `Added ${v.label} to ${app}'s config${backup ? ` (backup: ${backup})` : ""}. ${signInNote("cursor", v)}` });
+        return "registered";
+    }
+    catch (err) {
+        if (err instanceof PromptAbortedError)
+            throw err;
+        notes.push({ kind: "fail", text: `Couldn't update ${app}'s config: ${err.message}` });
+        return "failed";
+    }
+}
+/** Claude Desktop's JSON config only takes local servers; remote ones are added in its Connectors settings. */
+function addDesktop(ctx, v, notes) {
+    ctx.out(`Claude Desktop adds remote servers in its own settings, not in claude_desktop_config.json. To add ${v.label}:`);
+    for (const l of desktopConnectorSteps(v))
+        ctx.out(`  ${l}`);
+    notes.push({ kind: "info", text: `Claude Desktop: add ${v.label} yourself in Settings > Connectors > Add custom connector (URL ${v.url}).` });
+    return "manual";
+}
+function codexRegistrationFor(ctx, v, get) {
+    if (get.code === 0) {
+        const parsed = parseCodexVendorGet(get.stdout);
+        if (parsed)
+            return { kind: "entry", ...parsed };
+        return { kind: "unreadable" };
+    }
+    // A failed get proves nothing by itself: the config file (read, never written here) decides.
+    try {
+        return readCodexVendorToml(ctx.paths.codexConfig ? readIfExists(ctx.paths.codexConfig) : undefined, v.name);
+    }
+    catch {
+        return { kind: "unreadable" };
+    }
+}
+async function addCodexCli(ctx, v, notes) {
+    const addArgs = codexVendorArgs(v);
+    const state = codexRegistrationFor(ctx, v, await ctx.exec("codex", ["mcp", "get", v.name, "--json"]));
+    const backupConfig = () => (ctx.paths.codexConfig && existsSync(ctx.paths.codexConfig) ? backupFile(ctx.paths.codexConfig) : undefined);
+    const add = async (backup) => {
+        const b = backup ?? backupConfig();
+        const r = await runApp(ctx, "codex", addArgs);
+        notes.push(r.code === 0
+            ? { kind: "success", text: `Added ${v.label} to Codex${b ? ` (backup: ${b})` : ""}. ${signInNote("codex", v)}` }
+            : { kind: "fail", text: `\`codex mcp add\` for ${v.label} failed (exit ${r.code}).` });
+        return r.code === 0 ? "registered" : "failed";
+    };
+    if (state.kind === "absent") {
+        ctx.out(`This adds ${v.label} to Codex:`);
+        ctx.out(`  ${cmdLine("codex", addArgs)}`);
+        if (!(await ctx.prompt.confirm(`Add ${v.label}'s MCP server to Codex?`, true))) {
+            notes.push({ kind: "info", text: `Skipped ${v.label} in Codex.` });
+            return "skipped";
+        }
+        if (ctx.dryRun) {
+            notes.push({ kind: "info", text: `Dry run: ${v.label} not added to Codex.` });
+            return "dry-run";
+        }
+        return add();
+    }
+    if (state.kind === "unreadable") {
+        ctx.out(`Codex has a ${v.name} entry the wizard can't read; leaving it alone.`);
+        notes.push({ kind: "warn", text: `To replace it yourself: codex mcp remove ${v.name}, then ${cmdLine("codex", addArgs)}` });
+        return "manual";
+    }
+    if (state.url === v.url) {
+        notes.push({ kind: "success", text: `Codex: ${v.label} is already added.` });
+        return "already";
+    }
+    ctx.out(`Codex already has a ${v.name} server, with a different setting:`);
+    ctx.out(`  current: ${describeExisting(state)}`);
+    ctx.out(`  new:     url ${v.url}`);
+    if (!(await ctx.prompt.confirm(`Replace it (codex mcp remove ${v.name}, then add)?`, false))) {
+        notes.push({ kind: "info", text: `Kept the existing ${v.name} entry in Codex.` });
+        return "skipped";
+    }
+    if (ctx.dryRun) {
+        notes.push({ kind: "info", text: `Dry run: Codex's ${v.name} entry not replaced.` });
+        return "dry-run";
+    }
+    const backup = backupConfig();
+    const removed = await runApp(ctx, "codex", ["mcp", "remove", v.name]);
+    if (removed.code !== 0) {
+        notes.push({ kind: "fail", text: `\`codex mcp remove ${v.name}\` failed (exit ${removed.code}); nothing was added.` });
+        return "failed";
+    }
+    return add(backup);
+}
+/** Codex without a working CLI: append the entry to config.toml. A different existing entry is left for the user. */
+async function addCodexToml(ctx, v, notes) {
+    const path = ctx.paths.codexConfig;
+    if (!path)
+        return "manual";
+    let before;
+    try {
+        before = readIfExists(path);
+    }
+    catch (err) {
+        notes.push({ kind: "fail", text: `Couldn't read Codex's config: ${err.message}` });
+        return "failed";
+    }
+    const plan = planCodexVendorTomlEdit(before, v);
+    if (!plan.ok) {
+        notes.push({ kind: "warn", text: `Couldn't update Codex's config (${path}): ${plan.reason} To add ${v.label} yourself, paste this into that file:\n${codexVendorSnippet(v).split("\n").map((l) => `    ${l}`).join("\n")}` });
+        return "manual";
+    }
+    if (!plan.changed) {
+        notes.push({ kind: "success", text: `Codex already has ${v.label} (${path}).` });
+        return "already";
+    }
+    uiFor(ctx).preview(`Codex config: ${path}`, [
+        plan.otherServers.length ? `Other servers kept unchanged: ${plan.otherServers.join(", ")}` : "No other servers in the file.",
+        `Adds this ${v.name} entry:`,
+        ...codexVendorSnippet(v).split("\n").map((l) => `    ${l}`),
+    ]);
+    if (!(await ctx.prompt.confirm("Write this change? (the current file is kept as .bak)", true))) {
+        notes.push({ kind: "info", text: `Skipped ${v.label} in Codex.` });
+        return "skipped";
+    }
+    if (ctx.dryRun) {
+        notes.push({ kind: "info", text: "Dry run: Codex config not written." });
+        return "dry-run";
+    }
+    try {
+        const backup = writeConfigWithBackup(path, plan.text);
+        notes.push({ kind: "success", text: `Added ${v.label} to Codex's config${backup ? ` (backup: ${backup})` : ""}. Restart Codex. ${signInNote("codex", v)}` });
+        return "registered";
+    }
+    catch (err) {
+        notes.push({ kind: "fail", text: `Couldn't write Codex's config: ${err.message}` });
+        return "failed";
+    }
+}
+/** Vendors whose crawlmark integration works, for pre-ticking when the step is run on its own. */
+async function configuredVendors(ctx) {
+    try {
+        const report = await ctx.status(["ahrefs", "semrush"]);
+        return VENDOR_IDS.filter((id) => works(id, report.integrations.find((i) => i.id === id)));
+    }
+    catch {
+        return [];
+    }
+}
+const names = (ids) => ids.map((id) => VENDORS[id].label).join(" and ");
+export async function stepVendorMcp(ctx, opts = {}) {
+    const step = "vendor-mcp";
+    const ui = uiFor(ctx);
+    const later = `To add them later: ${ctx.cliDisplay} setup --step vendor-mcp`;
+    const selectedProviders = VENDOR_IDS.filter((id) => ctx.providers?.selected?.has(id));
+    let vendorIds;
+    let noticed = false;
+    if (!opts.asked) {
+        if (ctx.yes)
+            return { step, outcome: "skipped", message: `Not added (--yes). ${later}` };
+        // Plain and CI runs never get this extra question.
+        // The register step set up no apps: nothing to add these to, so don't ask.
+        if (opts.apps && opts.apps.length === 0)
+            return { step, outcome: "skipped", message: `No apps were set up to add them to. ${later}` };
+        if (!ui.fancy || selectedProviders.length === 0)
+            return { step, outcome: "skipped", message: selectedProviders.length ? `Not asked in plain mode. ${later}` : "Not needed (no Semrush or Ahrefs picked)." };
+        for (const id of selectedProviders)
+            ctx.out(VENDORS[id].notice);
+        noticed = true;
+        if (!(await ctx.prompt.confirm(`Also add ${names(selectedProviders)}'s own MCP server to these apps? (optional)`, false))) {
+            return { step, outcome: "skipped", message: `Not added. ${later}` };
+        }
+        vendorIds = selectedProviders;
+    }
+    else {
+        if (ctx.yes)
+            return { step, outcome: "skipped", message: `--yes adds no vendor MCP servers; run ${ctx.cliDisplay} setup --step vendor-mcp without it.` };
+        const defaults = selectedProviders.length ? selectedProviders : await configuredVendors(ctx);
+        const choices = VENDOR_IDS.map((id) => ({ value: id, label: VENDORS[id].label, hint: id === "semrush" ? "OAuth, spends your Semrush API units" : "OAuth, spends your Ahrefs API units" }));
+        ctx.out("Semrush and Ahrefs each run their own MCP server. Adding one lets your AI app ask it ad-hoc questions. crawlmark's own Semrush and Ahrefs support (API key, caps, reports) is separate and unchanged.");
+        vendorIds = ctx.prompt.multiselect
+            ? await ctx.prompt.multiselect("Add which vendor MCP servers?", choices, defaults, { summary: `Add: ${defaults.length ? names(defaults) : "none"}. Use these?` })
+            : defaults;
+        if (!vendorIds.length)
+            return { step, outcome: "skipped", message: "No vendor MCP servers picked." };
+    }
+    const probes = await ui.spin("Looking for AI apps...", () => detectApps(ctx), { plain: false });
+    let apps;
+    if (opts.apps)
+        apps = probes.filter((p) => opts.apps.includes(p.id));
+    else {
+        const detected = probes.filter((p) => p.detected).map((p) => p.id);
+        const choices = probes.map((p) => ({ value: p.id, label: p.label, ...(p.hint ? { hint: p.hint } : {}) }));
+        const picked = ctx.prompt.multiselect
+            ? await ctx.prompt.multiselect("Add them to which apps?", choices, detected, { summary: `Add to: ${probes.filter((p) => p.detected).map((p) => p.label).join(", ") || "none"} (detected). Use these?` })
+            : detected;
+        apps = probes.filter((p) => picked.includes(p.id));
+    }
+    if (!apps.length)
+        return { step, outcome: "skipped", message: "No apps to add them to." };
+    const notes = [];
+    const outcomes = [];
+    for (const id of vendorIds) {
+        const v = VENDORS[id];
+        if (!noticed) {
+            ctx.out("");
+            ctx.out(v.notice);
+        }
+        for (const probe of apps) {
+            let status;
+            if (probe.id === "claude-code")
+                status = await addClaudeCode(ctx, probe, v, notes);
+            else if (probe.id === "claude-desktop")
+                status = addDesktop(ctx, v, notes);
+            else if (probe.id === "cursor")
+                status = await addCursor(ctx, v, notes);
+            else
+                status = probe.codexCli ? await addCodexCli(ctx, v, notes) : await addCodexToml(ctx, v, notes);
+            outcomes.push({ vendor: id, app: probe.id, status });
+        }
+    }
+    for (const n of notes) {
+        if (!ui.fancy)
+            ctx.out(n.text);
+        else
+            ui[n.kind](n.text);
+    }
+    const failed = outcomes.some((o) => o.status === "failed");
+    const added = outcomes.some((o) => o.status === "registered" || o.status === "already");
+    return {
+        step,
+        outcome: failed ? "failed" : added ? "done" : "skipped",
+        message: outcomes.map((o) => `${VENDORS[o.vendor].label} in ${APP_LABELS[o.app]}: ${o.status}.`).join(" "),
+    };
+}
+//# sourceMappingURL=vendor-mcp-step.js.map

package/dist/setup/wizard.js

@@ -9,13 +9,13 @@
 import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { APP_LABELS, registerApps } from "./apps.js";
+import { stepVendorMcp } from "./vendor-mcp-step.js";
 import { copyFileAtomic } from "../lib/atomic-file.js";
 import { readEnvFile, writeEnvFile } from "../lib/env-file.js";
 import { expandPath, sourceCheckoutMarker } from "../lib/home.js";
 import { checkAhrefsKey } from "../providers/ahrefs.js";
 import { describeAhrefsAccount } from "../providers/ahrefs-shape.js";
 import { checkDataForSeoCredentials } from "../providers/dataforseo.js";
-import { checkSemrushKey } from "../providers/semrush.js";
 import { displayProviderValue, PROVIDER_LABELS, quoteProviderValue } from "../lib/provider-ids.js";
 import { checkPsiKey } from "./checks.js";
 import { checkCruxKey } from "../providers/crux.js";
@@ -26,7 +26,7 @@ import { uiFor } from "./ui.js";
 import { tryAskingExamples } from "./try-asking.js";
 import { DFS_LIVE_URL, DFS_SANDBOX_URL } from "../lib/env.js";
 import { LINKS } from "./status.js";
-export const STEP_NAMES = ["node", "provider", "dataforseo", "ahrefs", "semrush", "google", "psi", "discovery", "register"];
+export const STEP_NAMES = ["node", "provider", "dataforseo", "ahrefs", "semrush", "google", "psi", "discovery", "register", "vendor-mcp"];
 /**
  * Phase 12: steps run only with --step (branding is also "Set up report branding" in the returning-user menu).
  * They are not in the default flow or the step lists the wizard prints, so plain installer output is unchanged.
@@ -61,15 +61,17 @@ async function showStatus(ctx, only, opts = {}) {
     return map;
 }
 /** Write keys to <home>/.env (0600), or say what would be written in a dry run. Values are never printed. */
-function saveEnv(ctx, updates) {
+function saveEnv(ctx, updates, remove = []) {
     const keys = Object.keys(updates).join(", ");
     const ui = uiFor(ctx);
     if (ctx.dryRun) {
-        ui.info(`Dry run: would set ${keys} in ${ctx.paths.envFile} (mode 0600).`);
+        ui.info(`Dry run: would set ${keys}${remove.length ? ` and remove ${remove.join(", ")}` : ""} in ${ctx.paths.envFile} (mode 0600).`);
         return;
     }
-    const r = writeEnvFile(ctx.paths.envFile, updates);
+    const r = writeEnvFile(ctx.paths.envFile, updates, remove);
     const changed = [...r.updated, ...r.added];
+    if (r.removed.length)
+        ui.info(`Removed ${r.removed.join(", ")} from ${ctx.paths.envFile}.`);
     ui.success(changed.length ? `Saved ${changed.join(", ")} to ${ctx.paths.envFile} (mode 0600).` : `${ctx.paths.envFile} already had these values.`);
     const shadowed = Object.keys(updates).filter((k) => ctx.shellEnvKeys.has(k));
     if (shadowed.length) {
@@ -252,7 +254,6 @@ export async function stepAhrefs(ctx, opts = {}) {
     }
     return { step, outcome: "failed", message: `No working Ahrefs key after ${MAX_ATTEMPTS} attempts.` };
 }
-const SEMRUSH_API_UNITS = "https://www.semrush.com/accounts/subscription-info/api-units/";
 const GOOGLE_SERVICE_ACCOUNTS = "https://console.cloud.google.com/iam-admin/serviceaccounts";
 const GOOGLE_AUTH_OVERVIEW = "https://console.cloud.google.com/auth/overview";
 export async function stepSemrush(ctx, opts = {}) {
@@ -263,69 +264,38 @@ export async function stepSemrush(ctx, opts = {}) {
     if (!opts.ticked && !(await ctx.prompt.confirm(working ? "Change the Semrush API key?" : "Set up Semrush now?", !working))) {
         return { step, outcome: "skipped", message: working ? "Kept the current Semrush key." : "Semrush not set up." };
     }
-    ctx.out("Semrush: keyword, ranking, competitor and backlink data (needs an SEO Business plan plus an API unit package).");
-    ctx.out(`Find the v3 API key under Subscription info > API units (${SEMRUSH_API_UNITS}).`);
-    await offerOpen(ctx, "Semrush API units", SEMRUSH_API_UNITS);
-    const env = existingEnv(ctx);
-    const current = env.SEMRUSH_API_KEY;
+    ctx.out("Semrush: keyword volume and backlinks (needs a Semrush plan with API units: 50,000 come with SEO Classic Pro and Guru, and Semrush One Starter and Pro+).");
+    ctx.out("Create a v4 API key under your profile > API keys. Semrush's older v3 keys aren't supported; create a v4 key.");
+    const saved = existingEnv(ctx);
+    // In 0.1.0 SEMRUSH_API_KEY was the old v3 key and SEMRUSH_V4_API_KEY the v4 key, so the alias wins when both are set.
+    // Keeping it saves it as SEMRUSH_API_KEY and removes the alias.
+    const current = saved.SEMRUSH_V4_API_KEY || saved.SEMRUSH_API_KEY;
     for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
         let key;
         try {
-            key = await ctx.prompt.secret(current ? "Semrush API key, v3 (Enter keeps the current one)" : "Semrush API key (v3)");
+            key = await ctx.prompt.secret(current ? "Semrush API key (v4, from your profile > API keys; Enter keeps the current one)" : "Semrush API key (v4, from your profile > API keys)");
         }
         catch (err) {
             if (err instanceof NeedsInputError) {
                 const keySet = Boolean(current) || st?.data?.keySet === true;
-                return { step, outcome: "skipped", message: keySet ? `Semrush key is set but untested; run ${ctx.cliDisplay} setup --step semrush` : `Semrush needs a key; run ${ctx.cliDisplay} setup --step semrush` };
+                return { step, outcome: "skipped", message: keySet ? `Semrush key is set; run ${ctx.cliDisplay} setup --step semrush to change it` : `Semrush needs a key; run ${ctx.cliDisplay} setup --step semrush` };
             }
             throw err;
         }
+        // A key pasted with its quotes from a .env line or a doc.
+        key = key.trim().replace(/^(["'])(.*)\1$/, "$2").trim();
         if (!key && current)
             key = current;
         if (!key) {
             ui.fail("No key entered.");
             continue;
         }
-        const check = await ui.spin("Checking with Semrush (free API units balance call)...", () => checkSemrushKey(key, ctx.fetch));
-        if (check.works === true) {
-            if (check.unitsLeft === 0)
-                ui.warn("Key accepted but the balance is 0 units; Semrush API needs an SEO Business plan and a unit package.");
-            else
-                ui.success(`Semrush key accepted  ${check.unitsLeft.toLocaleString("en-US")} API units left`);
-            saveEnv(ctx, { SEMRUSH_API_KEY: key });
-            markWorking(ctx, "semrush");
-            await semrushV4(ctx);
-            return { step, outcome: "done", message: `Semrush key accepted (${check.unitsLeft.toLocaleString("en-US")} API units left).` };
-        }
-        if (check.works === false) {
-            ui.fail(`Semrush rejected that key${"errorCode" in check && check.errorCode ? ` (ERROR ${check.errorCode})` : ""}. Find the v3 key under Subscription info > API units.`);
-            continue;
-        }
-        ui.warn(`Couldn't reach Semrush's balance check, so the key is untested: ${check.error}`);
-        if (await ctx.prompt.confirm("Save it anyway?", false)) {
-            saveEnv(ctx, { SEMRUSH_API_KEY: key });
-            await semrushV4(ctx);
-            return { step, outcome: "done", message: `Saved an untested Semrush key; check later with \`${ctx.cliDisplay} setup --step semrush\`.` };
-        }
-        return { step, outcome: "failed", message: "Semrush unreachable; nothing saved." };
+        saveEnv(ctx, { SEMRUSH_API_KEY: key }, ["SEMRUSH_V4_API_KEY"]);
+        markWorking(ctx, "semrush");
+        ui.info("Saved. Semrush has no free key check, so the key is checked on the first paid call (keyword volume or backlinks).");
+        return { step, outcome: "done", message: "Semrush key saved (v4). Semrush has no free key check, so it is checked on the first paid call (keyword volume or backlinks)." };
     }
-    return { step, outcome: "failed", message: `No accepted Semrush key after ${MAX_ATTEMPTS} attempts.` };
-}
-/** The optional v4 key (backlinks): saved untested, since Semrush has no free check for it (N15). Skipped under --yes. */
-async function semrushV4(ctx) {
-    if (ctx.yes)
-        return;
-    if (!(await ctx.prompt.confirm("Add a Semrush v4 key too? (backlinks use the v4 overview; without it they use the older v3 report)", false)))
-        return;
-    const v4 = await ctx.prompt.secret("Semrush API key (v4, from your profile > API keys)");
-    if (!v4) {
-        uiFor(ctx).info("No v4 key entered; backlinks keep using the v3 report.");
-        return;
-    }
-    saveEnv(ctx, { SEMRUSH_V4_API_KEY: v4 });
-    uiFor(ctx).info(ctx.dryRun
-        ? "Semrush has no free check for v4 keys, so it would be checked the first time backlinks_summary runs."
-        : "Saved; Semrush has no free check for v4 keys, so it's checked the first time backlinks_summary runs.");
+    return { step, outcome: "failed", message: `No Semrush key entered after ${MAX_ATTEMPTS} attempts.` };
 }
 const GOOGLE_OPTIONS = [
     { value: "A", label: "A. OAuth with Google Workspace: sign in once, sees every property you can open, sign-ins don't expire" },
@@ -625,7 +595,7 @@ const PROVIDER_ORDER = ["dataforseo", "ahrefs", "semrush"];
 const PROVIDER_HINTS = {
     dataforseo: "pay per call; free sandbox; also live SERPs, on-page, crawls",
     ahrefs: "API v3, Lite plan or higher",
-    semrush: "Business plan + API unit package",
+    semrush: "v4 API key; keyword volume and backlinks",
 };
 /** What the wizard says when a provider isn't set up and --yes can't ask for its key. */
 const NEEDS_KEY = {
@@ -637,7 +607,7 @@ const NEEDS_KEY = {
 const KEY_VARS = {
     dataforseo: "DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD",
     ahrefs: "AHREFS_API_KEY",
-    semrush: "SEMRUSH_API_KEY (and SEMRUSH_V4_API_KEY)",
+    semrush: "SEMRUSH_API_KEY",
 };
 const STATE_WORD = { working: "working", configured: "set, untested", error: "error", missing: "not set up" };
 /** Read status rows without printing them (under a spinner in fancy mode). */
@@ -656,8 +626,8 @@ async function readStatus(ctx, only) {
 const providerIds = () => PROVIDER_ORDER.filter((id) => PROVIDER_STEPS.includes(id));
 /** A provider's setup_status row id (every provider with a credential step has one). */
 const rowId = (id) => id;
-/** A provider counts as working: its row is working, or (Semrush) its key was accepted with units left and only the v4 key is untested. */
-export const works = (id, s) => s?.state === "working" || (id === "semrush" && s?.state === "configured" && typeof s.data?.unitsLeft === "number" && s.data.unitsLeft > 0);
+/** A provider counts as working: its row is working, or (Semrush, which has no free key check) its key is set. */
+export const works = (id, s) => s?.state === "working" || (id === "semrush" && s?.state === "configured" && s.data?.keySet === true);
 const hasKey = (id, s) => (id === "dataforseo" ? s !== undefined && s.state !== "missing" : s?.data?.keySet === true);
 function describeDefault(seo) {
     const d = seo?.data;
@@ -762,13 +732,14 @@ const STEPS = {
     branding: { title: "Report branding", run: stepBranding },
     discovery: { title: "Clients", run: stepDiscovery },
     register: { title: "Register with Claude", run: stepRegister },
+    "vendor-mcp": { title: "Semrush and Ahrefs MCP servers (optional)", run: (ctx, opts) => stepVendorMcp(ctx, opts ?? {}) },
 };
 const isProviderStep = (p) => PROVIDER_STEPS.includes(p);
 /** The run plan (spec 9.6) for a full run or one --step. */
 export function runPlan(step) {
     const creds = PROVIDER_STEPS;
     if (!step)
-        return ["node", "provider:pick", ...creds, "provider:default", "google", "psi", "discovery", "register"];
+        return ["node", "provider:pick", ...creds, "provider:default", "google", "psi", "discovery", "register", "vendor-mcp"];
     if (step === "provider")
         return ["provider:pick", ...creds, "provider:default"];
     if (isProviderStep(step))
@@ -787,6 +758,7 @@ const SUMMARY_LABELS = {
     bing: "Bing",
     branding: "Branding",
     discovery: "Clients",
+    "vendor-mcp": "Vendor MCP",
 };
 const APP_OUTCOME = {
     registered: "done",
@@ -888,11 +860,15 @@ export async function runWizard(ctx, opts = {}) {
     // The returning-user menu (src/setup/menu.ts) shows the intro itself before it runs a step.
     if (!opts.introShown)
         ui.intro({ command: ctx.command ?? "setup", version: ctx.version ?? "", home: ctx.paths.home, dryRun: ctx.dryRun });
-    const phases = runPlan(opts.step);
+    let phases = runPlan(opts.step);
+    // The vendor MCP question exists only in a fancy, interactive full run; plain, CI and --yes output is unchanged.
+    if (!opts.step && (ctx.yes || !ui.fancy))
+        phases = phases.filter((p) => p !== "vendor-mcp");
     const results = [];
     let picked;
     let index = 0;
-    for (const name of phases) {
+    for (let pi = 0; pi < phases.length; pi++) {
+        const name = phases[pi];
         let result;
         let record = true;
         const run = async (title, fn) => {
@@ -914,6 +890,9 @@ export async function runWizard(ctx, opts = {}) {
                 picked = r.statuses;
                 return r.result;
             });
+            // No Semrush or Ahrefs picked: the vendor MCP question has nothing to ask.
+            if (!opts.step && !(ctx.providers?.selected?.has("semrush") || ctx.providers?.selected?.has("ahrefs")))
+                phases = phases.filter((p) => p !== "vendor-mcp");
             // The pick's line is shown; the summary's "provider" entry is the default phase's result.
             record = false;
         }
@@ -936,6 +915,10 @@ export async function runWizard(ctx, opts = {}) {
                 result = await run(STEPS[name].title, () => STEPS[name].run(ctx, { ticked: true }));
             }
         }
+        else if (name === "vendor-mcp") {
+            const apps = results.find((r) => r.step === "register")?.apps?.filter((a) => a.status === "registered" || a.status === "already").map((a) => a.id);
+            result = await run(STEPS[name].title, () => STEPS[name].run(ctx, opts.step ? { asked: true } : { apps: apps ?? [] }));
+        }
         else {
             const step = name;
             result = await run(STEPS[step].title, () => STEPS[step].run(ctx));

package/dist/tools/competitors.js

@@ -172,7 +172,7 @@ export function registerCompetitorTools(server) {
         "Through the client's data provider only (no fallback to another provider). Call with estimateOnly: true first, state the provider, cost and what's left, and run it only after the user agrees.";
     server.registerTool("organic_visibility", {
         title: "Organic visibility",
-        description: "A domain's organic search visibility from the client's data provider: ranking keywords (top 100), keywords by position band (top 3, 4-10, 11-20, 21-100; not available from Semrush) and estimated organic traffic, labelled by provider (never compare traffic across providers). " +
+        description: "A domain's organic search visibility from the client's data provider: ranking keywords (top 100), keywords by position band (top 3, 4-10, 11-20, 21-100; Semrush's API has no visibility data, so a Semrush client is served by DataForSEO) and estimated organic traffic, labelled by provider (never compare traffic across providers). " +
             "Comparisons with a month and a year ago appear only when stored snapshots (or, with history: true, the provider's own history, paid) have them. " +
             SNAPSHOTS,
         inputSchema: {

package/dist/tools/raw.js

@@ -188,13 +188,12 @@ export function registerRawTools(server) {
     }, handler("ahrefs_status", () => ahrefsStatus()));
     server.registerTool("semrush_status", {
         title: "Semrush status",
-        description: "Check the Semrush v3 API key with Semrush's free balance call: whether the key is accepted and how many API units are left, whether a v4 key " +
-            "(used for backlinks) is set, plus the units crawlmark recorded this calendar month against its own cap. Accepted proves the key exists, not that the " +
-            "plan includes the API (that shows on the first paid call). The v4 key has no free check. Free, never cached, records no spend, never shows a key. " +
-            "A missing or rejected key is reported in the result, not as a tool error. Change keys in a terminal (setup --step semrush), never through chat.",
+        description: "Whether a Semrush API key (v4, from the profile > API keys page) is set, what Semrush serves in crawlmark (keyword volume and backlinks; its v4 API has no rankings, " +
+            "competitors, visibility or Site Audit), and the units crawlmark recorded this calendar month against its own cap. Semrush has no free key check, so a rejected key shows " +
+            "on the first paid call. Free, never cached, records no spend, never shows a key. Change the key in a terminal (setup --step semrush), never through chat.",
         inputSchema: {},
         annotations: READ_ONLY,
-    }, handler("semrush_status", () => semrushStatus()));
+    }, handler("semrush_status", async () => semrushStatus()));
     // ---------------------------------------------------- browser checks (free)
     server.registerTool("lighthouse", {
         title: "Lighthouse",

package/dist/tools/reports.js

@@ -261,17 +261,17 @@ export function registerReportTools(server) {
             "The same problem found by two sources is one item, listing both sources with their own severity; `affected` is the largest page count any one source reports. " +
             "`changes` compares with the newest snapshot older than 24 hours: new, persistent, resolved (only when the source that reported it ran again) and unverified (not re-checked, never counted as fixed); null on the first run. " +
             "Each call saves a snapshot (local). Never starts a crawl or audit; stale sources (older than maxAgeDays) are shown with their date. " +
-            "Free by default. The ahrefs_site_audit and semrush_site_audit sources read the client's existing Site Audit project (clients.yaml ahrefsSiteAuditProject / semrushProject, else matched by domain) and spend units " +
-            "(Ahrefs: 50 for the issues, plus 50 per issueUrls call; Semrush: about 100 per call, up to 400 with the project list and titles): they need allowPaid: true, read only (never start a crawl or create a project). " +
+            "Free by default. The ahrefs_site_audit source reads the client's existing Ahrefs Site Audit project (clients.yaml ahrefsSiteAuditProject, else matched by domain) and spends units " +
+            "(50 for the issues, plus 50 per issueUrls call): it needs allowPaid: true and is read only (never starts a crawl or creates a project). Semrush's API has no Site Audit. " +
             "Call with estimateOnly: true first, state the units and ask before passing allowPaid.",
         inputSchema: {
             client: clientArg,
             sources: z.array(z.enum(ISSUE_SOURCES)).min(1).max(ISSUE_SOURCES.length).optional().describe("Default: every free source (audit, local_crawl, site_hygiene, dataforseo_crawl, gsc_inspection)."),
             minSeverity: z.enum(["critical", "high", "medium", "low"]).optional().describe("Leave out issues below this severity. Default low (everything)."),
             limit: z.number().int().min(1).max(200).optional().describe("Issues listed (counts cover all). Default 50."),
-            issueUrls: z.number().int().min(0).max(5).optional().describe("Top issues to fetch up to 3 example URLs for from a provider Site Audit source (paid: one call each). Default 0."),
+            issueUrls: z.number().int().min(0).max(5).optional().describe("Top issues to fetch up to 3 example URLs for from the Ahrefs Site Audit source (paid: one call each). Default 0."),
             maxAgeDays: z.number().int().min(7).max(120).optional().describe("Sources older than this are flagged stale. Default 45."),
-            allowPaid: z.boolean().optional().describe("Needed for the Ahrefs / Semrush Site Audit sources (they spend provider units); set only after the user agreed to the estimate."),
+            allowPaid: z.boolean().optional().describe("Needed for the Ahrefs Site Audit source (it spends Ahrefs units); set only after the user agreed to the estimate."),
             estimateOnly: z.boolean().optional().describe("Return the provider units this would spend, read nothing and save nothing."),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
@@ -279,11 +279,11 @@ export function registerReportTools(server) {
         const c = await resolveClient(client);
         const sources = o.sources ?? [...FREE_ISSUE_SOURCES];
         if ((o.issueUrls ?? 0) > 0 && !sources.some((x) => PAID_ISSUE_SOURCES.has(x)))
-            throw new Error("issueUrls needs an ahrefs_site_audit or semrush_site_audit source.");
+            throw new Error("issueUrls needs the ahrefs_site_audit source.");
         const ti = await import("../reports/technical-issues.js");
         if (estimateOnly) {
             const paid = await ti.planPaidIssueSources(c, sources, o.issueUrls ?? 0);
-            const units = { ahrefs: paid.filter((p) => p.provider === "ahrefs").reduce((a, p) => a + p.units, 0), semrush: paid.filter((p) => p.provider === "semrush").reduce((a, p) => a + p.units, 0) };
+            const units = { ahrefs: paid.reduce((a, p) => a + p.units, 0), semrush: 0 };
             return {
                 estimateOnly: true,
                 sources,