@houtini/seo-audit-console 0.9.0 → 0.9.1

package/dist/server.js

@@ -18,15 +18,10 @@ import { fetchCompetitorContent, routeFor } from './core/reconResearch.js';
 import { fetchOwnPage } from './core/reconFetch.js';
 import { parseSerpForRecon, reconVerdict } from './core/serpRecon.js';
 import { selectReconTargets, deterministicTodos, persistReconPage, insertTodos, pageState, crawlRealityOverride, clusterCannibalisation, opportunityBasis } from './audit/recon.js';
-/** A clickable browser-dashboard link appended to tool outputs — the user should always
- * know the full interactive report is one click away (or one serve_dashboard call away). */
 function browserLink(siteUrl) {
     const base = dashboardServerUrl();
     if (base)
         return `\n\n📊 Browser dashboard: ${base}/dashboard${siteUrl ? `?siteUrl=${encodeURIComponent(siteUrl)}` : ''}`;
-    // No live server: point at the dashboard surfaces that always work. get_dashboard renders the
-    // interactive dashboard in chat (works through the Docker gateway where a served port would not);
-    // serve_dashboard opens a browser tab locally; export_report writes a shareable HTML file.
     return `\n\n📊 See it in the dashboard — run get_dashboard${siteUrl ? ` for ${siteUrl}` : ''} (interactive, in chat), serve_dashboard (browser tab), or export_report (shareable HTML).`;
 }
 import { runAudit, runSingleCheck, listChecks } from './audit/engine.js';
@@ -62,9 +57,6 @@ import { gscFreshness } from './core/gscFreshness.js';
 import { clusterKeywordList } from './audit/keywordList.js';
 const SERVER_NAME = 'seo-audit-console';
 const SERVER_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-// Where per-property crawl/audit DBs live. Resolution order (computed once per run):
-//   SAC_DATA_DIR env  >  persisted choice (~/.seo-audit-console.json)  >  Documents default.
-// The user can set the persisted choice through the `data_location` tool (no JSON editing).
 const CONFIG_PATH = path.join(homedir(), '.seo-audit-console.json');
 const DEFAULT_DATA_DIR = path.join(homedir(), 'Documents', 'seo-audit-console');
 function readConfigDataDir() {
@@ -82,21 +74,14 @@ export function dataDir() {
     return RESOLVED_DATA_DIR;
 }
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// Version the widget URIs: hosts may cache ui:// resources by URI indefinitely, so an
-// unversioned URI can pin users to a stale (or broken) cached bundle across releases.
 const DASHBOARD_URI = `ui://dashboard/main-${SERVER_VERSION}.html`;
 const SYNC_PROGRESS_URI = `ui://sync-progress/main-${SERVER_VERSION}.html`;
-// Must match the categories actually used by CHECKS (src/audit/checks.ts) so category
-// filters never silently return empty. (Was listing performance/agentic/integrity/war-stories
-// which no check uses, and omitting content/security which checks do use.)
 const CHECK_CATEGORIES = [
     'crawlability', 'indexation', 'onpage', 'content', 'schema', 'security', 'performance', 'merged',
 ];
 function isoDaysAgo(days) {
     return new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
 }
-// Server-level instructions (MCP `initialize` result): teach the assistant how the data
-// sources JOIN so it can COMPOSE bespoke multi-source analyses, not just run presets.
 const SERVER_INSTRUCTIONS = `SEO Audit Console fuses four data sources into one SQLite database per property: Google Search Console history, a first-party site crawl, GSC URL Inspection, and on-demand DataForSEO (SERP/Labs/Backlinks). Its real power is COMPOSITION — joining sources to answer questions no single tool answers.
 
 JOIN KEYS (memorise these):
@@ -185,8 +170,6 @@ Raw access: query_audit runs any single check with full evidence; every table ab
 - **Cost rule of thumb:** an entire competitive read (visibility + footprint + gaps for 4 domains) is a handful of cached Labs calls - under a dollar. If a plan involves looping SERP calls over a keyword list, it is the wrong plan; a Labs endpoint already has that answer top-down.
 
 Plan the join first (url_key / query / domain), state the grain of each side, then run the fewest paid calls that answer it.`;
-// The check catalogue rendered as markdown — single source of truth is listChecks();
-// shared by the seo-audit://checks-reference resource (and buildable for any category subset).
 function buildChecksMarkdown(checks) {
     const byCategory = new Map();
     for (const c of checks) {
@@ -255,7 +238,7 @@ export function createServer() {
     const gsc = credPath ? new GscClient(credPath) : null;
     const sync = gsc ? new GscSync(gsc, dataDir()) : null;
     const inspector = gsc ? new UrlInspector(gsc, dataDir()) : null;
-    const crawler = new Crawler(dataDir()); // no GSC credentials required
+    const crawler = new Crawler(dataDir());
     const dfsUser = process.env.DATAFORSEO_USERNAME;
     const dfsPass = process.env.DATAFORSEO_PASSWORD;
     const dfsCacheDays = Number(process.env.DATAFORSEO_CACHE_DAYS) || 7;
@@ -264,16 +247,12 @@ export function createServer() {
         : null;
     const rankTracker = dfs ? new RankTracker(dfs, dataDir()) : null;
     const linkIntersect = dfs ? new LinkIntersect(dfs, dataDir()) : null;
-    // Majestic (Trust Flow / Topical Trust Flow) — optional link_intersect + trapped-authority tier.
     const majesticKey = process.env.MAJESTIC_API_KEY;
     const majesticCacheDays = Number(process.env.MAJESTIC_CACHE_DAYS) || 30;
     const majestic = majesticKey ? new MajesticClient(majesticKey, path.join(dataDir(), 'majestic-cache.db'), majesticCacheDays) : null;
-    // Backlinks after Majestic, so pull_backlinks can enrich per-URL pages with Trust Flow.
     const backlinks = dfs ? new Backlinks(dfs, dataDir(), majestic) : null;
-    // Firecrawl (competitor-page scraping for content recon) — optional; degrades gracefully.
     const firecrawlKey = process.env.FIRECRAWL_API_KEY;
     const firecrawl = firecrawlKey ? new FirecrawlClient(firecrawlKey, path.join(dataDir(), 'firecrawl-cache.db')) : null;
-    // Supadata (transcribes the ranking videos for content recon) — optional; degrades gracefully.
     const supadataKey = process.env.SUPADATA_API_KEY;
     const supadata = supadataKey ? new SupadataClient(supadataKey, path.join(dataDir(), 'supadata-cache.db')) : null;
     const entities = new Entities(new WikidataClient(path.join(dataDir(), 'wikidata-cache.db')), dataDir());
@@ -288,33 +267,21 @@ export function createServer() {
             throw new Error('DATAFORSEO_USERNAME / DATAFORSEO_PASSWORD not set — required for DataForSEO.');
         return v;
     };
-    // Which optional integrations have a key set — drives the dashboard's key-gated tabs
-    // (Links, Content research) and their affiliate-linked upsell states. The data layer has
-    // no env access, so it's injected here onto every dashboard payload surface.
     const apiKeysStatus = () => ({ dataforseo: !!dfs, majestic: !!majestic, firecrawl: !!firecrawl, supadata: !!supadata });
-    // The dashboard webserver's options — one definition shared by serve_dashboard AND the
-    // auto-start at the end of refresh_property / run_audit, so a populated property always has
-    // a live browser link (browserLink() surfaces dashboardServerUrl() once this is running).
     const buildWebOpts = (port) => ({
         dataDir,
         uiHtml: () => readFileSync(path.join(__dirname, 'src', 'ui', 'dashboard.html'), 'utf8'),
         call: buildWebCallHandlers({ dataDir, dfs, apiKeys: apiKeysStatus }),
         ...(port != null ? { port } : {}),
     });
-    // Idempotent auto-start used by refresh_property / run_audit. Best-effort: a served port that
-    // can't bind (e.g. Docker without a published port) must never fail the populate/audit — the
-    // in-chat get_dashboard and export_report still work, and browserLink() falls back to those.
-    // Opt-out with SAC_AUTOSERVE=0 for headless/CI/sandboxed runs where binding a localhost port
-    // is unwanted (default: on, since the whole point is to hand the user a link).
     const autoServeDashboard = async () => {
         if (/^(0|false|no|off)$/i.test(process.env.SAC_AUTOSERVE ?? ''))
             return;
         try {
             await startDashboardServer(buildWebOpts());
         }
-        catch { /* dashboard is a convenience, not a dependency */ }
+        catch { }
     };
-    // ── Introspection (no data / creds required) ────────────────────────────
     server.registerTool('seo_audit_help', {
         title: 'Help — what this audit can do',
         description: 'Overview of every tool/feature with an example prompt for each. Start here.',
@@ -358,8 +325,6 @@ export function createServer() {
         inputSchema: { path: z.string().optional() },
     }, async ({ path: newPath }) => {
         if (newPath) {
-            // Persist an ABSOLUTE path — a relative one resolves against the host process's
-            // cwd, which differs across Claude Desktop launches, so DBs would "disappear".
             newPath = path.resolve(newPath);
             mkdirSync(newPath, { recursive: true });
             writeFileSync(CONFIG_PATH, JSON.stringify({ dataDir: newPath }, null, 2));
@@ -405,10 +370,6 @@ export function createServer() {
         }
         const rows = s.properties.map(p => `| ${p.siteUrl ?? p.file} | ${fmtBytes(p.bytes)} | ${p.searchAnalytics.toLocaleString('en-US')} | ${p.pages.toLocaleString('en-US')} | ${p.links.toLocaleString('en-US')} | ${p.pageSnapshots.toLocaleString('en-US')} | ${p.findings.toLocaleString('en-US')} | ${p.lastSynced?.slice(0, 10) ?? '—'} | ${p.lastCrawl?.slice(0, 10) ?? '—'} |`).join('\n');
         const cacheLines = s.caches.map(c => `- ${c.file}: ${fmtBytes(c.bytes)}`).join('\n');
-        // Link-intersect freshness: prospect data ages as competitors keep earning links, so
-        // flag properties that HAVE link_prospects and roughly how stale it is — a re-run of
-        // link_intersect updates it. (The DataForSEO call is 20-day cached; older than that a
-        // re-run genuinely refetches.)
         const nowMs = Date.now();
         const liProps = s.properties.filter(p => (p.linkProspects ?? 0) > 0);
         const liLines = liProps.map(p => {
@@ -425,7 +386,6 @@ export function createServer() {
             `Prune with data_storage prune:{siteUrl, action:"vacuum" | "clear-crawl-history" | "delete-property"} (destructive actions need confirm:true).`;
         return { content: [{ type: 'text', text: md }], structuredContent: s };
     });
-    // ── Audit engine ────────────────────────────────────────────────────────
     server.registerTool('run_audit', {
         title: 'Run SEO audit',
         description: 'Run the technical-SEO checks against synced data and return scored findings, ranked by expected clicks per dev-hour — Priority = (T × Y × C) / E (T = clicks at stake from real GSC data, Y = expected yield, C = certainty, E = effort hours). Crawl + GSC + URL-inspection checks. Set includeJudgement=true to include heuristic (N) checks.',
@@ -437,7 +397,7 @@ export function createServer() {
         },
     }, async ({ siteUrl, scope, categories, includeJudgement }) => {
         const result = runAudit(dataDir(), siteUrl, { scope, categories, includeJudgement });
-        await autoServeDashboard(); // spin up the browser dashboard so browserLink() hands over a live URL
+        await autoServeDashboard();
         return {
             content: [{ type: 'text', text: buildAuditMarkdown(result, siteUrl) + browserLink(siteUrl) }],
             structuredContent: { ...result, dashboardUrl: dashboardServerUrl() },
@@ -455,8 +415,6 @@ export function createServer() {
         },
     }, async ({ siteUrl, check, limit, offset, columns }) => {
         const r = runSingleCheck(dataDir(), siteUrl, check, limit, offset ?? 0);
-        // Token discipline (mirrors query_data): optional evidence-column selection + loud
-        // 120-char cell truncation, and an explicit offset/total footer.
         const shape = (f) => {
             const src = (f.evidence ?? {});
             const keys = columns?.length ? columns.filter(k => k in src) : Object.keys(src);
@@ -467,9 +425,6 @@ export function createServer() {
         };
         let sc = { ...r, findingsTotal: r.total };
         let findings = r.findings.map(shape);
-        // Hosts cap the model-facing result (~60k chars). On evidence-heavy checks a large
-        // `limit` can blow that ceiling and error the whole call — trim findings (keeping the
-        // true total) instead of failing. Same guard pattern as detect_changes.
         while (findings.length > 25 && JSON.stringify({ ...sc, findings }).length > 45000) {
             findings = findings.slice(0, Math.floor(findings.length / 2));
         }
@@ -540,7 +495,6 @@ export function createServer() {
         const text = `WRITING BRIEF — ${r.url}\nTarget query: “${r.topQuery ?? '(unknown)'}”\nGap: ${r.gap}\n\nTASK\n${r.brief}\n\nVOICE (match this — the page's own writing):\n${voice || '  (no substantial passages)'}\n\nFACTS (ground in these — the page's most query-relevant content; invent nothing beyond them):\n${facts || '  (none)'}`;
         return { content: [{ type: 'text', text }], structuredContent: r };
     });
-    // detect_changes — change-detection / drift: what changed on the site since the last crawl.
     server.registerTool('detect_changes', {
         title: 'Detect changes since the last crawl',
         description: 'Compare the two most recent crawls and report what changed per URL — status code, indexability, canonical, robots/noindex, title, meta, H1, schema, large content swings — each classified by severity (critical → info). This is the monitor: run refresh_property on different days to build history, then this surfaces regressions (a page that went noindex, a canonical that flipped, a 200 that became a 404). Needs at least two crawls.',
@@ -549,9 +503,6 @@ export function createServer() {
         const adb = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
         try {
             const d = diffLatest(adb.db);
-            // Cap the changes array in structuredContent to `limit` — the full diff can be tens of
-            // thousands of rows (e.g. a crawl-methodology change) and blow the MCP token ceiling. The
-            // summary keeps the TRUE totals; markdown is already limited.
             const lim = limit ?? 50;
             const sc = { ...d, changes: d.changes.slice(0, lim), changesReturned: Math.min(lim, d.changes.length), changesTotal: d.changes.length };
             return {
@@ -563,14 +514,12 @@ export function createServer() {
             adb.close();
         }
     });
-    // check_agent_readiness — is the site ready for AI agents? (the agentic-SEO / GEO frontier)
     server.registerTool('check_agent_readiness', {
         title: 'Check agent readiness (AI-agent / GEO signals)',
         description: 'Probe a site for AI-agent readiness — the signals agents use to discover and use it: robots.txt AI-bot rules + Content Signals, sitemap, Link headers, llms.txt, agents.md, Markdown content negotiation, Web Bot Auth, MCP server card, Agent Skills, API Catalog, OAuth discovery. Returns a 0–100 score, a level (Basic web presence → Agent-native), and a per-check checklist with copy-paste fixes. Live HTTP probes of the property origin (no crawl/GSC needed). Modelled on Cloudflare\'s isitagentready.com.',
         inputSchema: { siteUrl: z.string() },
     }, async ({ siteUrl }) => {
         const r = await checkAgentReadiness(siteUrl);
-        // Persist so the dashboard/export can show it (live probe, not crawl-derived).
         try {
             const adb = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
             try {
@@ -582,13 +531,12 @@ export function createServer() {
                 adb.close();
             }
         }
-        catch { /* persistence is best-effort */ }
+        catch { }
         return {
             content: [{ type: 'text', text: buildAgentReadinessMarkdown(r) }],
             structuredContent: r,
         };
     });
-    // fix_finding — the moat: turn a finding into a concrete, paste-ready remediation.
     server.registerTool('fix_finding', {
         title: 'Generate a fix for a finding',
         description: 'Turn an audit finding into a concrete, paste-ready remediation: JSON-LD for missing structured data, a 301 rule for broken / redirecting internal links, or internal-link suggestions for orphan / striking-distance pages. Other checks return their deterministic fix guidance. Dry-run — returns artifacts, never writes to your site. Identify the finding by findingId (from run_audit) or by check + url.',
@@ -602,7 +550,6 @@ export function createServer() {
     }, async ({ siteUrl, findingId, check, url, redirectFormat }) => {
         const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
         try {
-            // Resolve the finding → checkId, affected url_key, evidence.
             let checkId = check;
             let affectedKey = null;
             let evidence = {};
@@ -641,14 +588,12 @@ export function createServer() {
                     break;
                 }
                 case 'redirect-chain': {
-                    // The finding's url_key IS the chain's final page — its row holds the recorded
-                    // hops. Collapse each hop straight to the final URL; never fuzzy-match here.
                     const page = db.db.prepare('SELECT url, redirects FROM pages WHERE url_key = ?').get(affectedKey);
                     let hops = [];
                     try {
                         hops = page?.redirects ? JSON.parse(page.redirects) : [];
                     }
-                    catch { /* malformed chain */ }
+                    catch { }
                     kind = 'redirect';
                     fix = page && hops.length
                         ? { ...collapseChainRules(page.url, hops, redirectFormat ?? 'htaccess'), chain: hops }
@@ -656,8 +601,6 @@ export function createServer() {
                     break;
                 }
                 case 'internal-links-to-redirects': {
-                    // The flagged key is a redirect SOURCE; the crawler recorded where it actually
-                    // goes — find the chain containing it and use that real destination.
                     const hostForm = hostFormForProperty(siteUrl) ?? 'asis';
                     let knownTarget = null;
                     for (const row of db.db.prepare(`SELECT url, redirects FROM pages WHERE redirects IS NOT NULL AND redirects <> ''`).iterate()) {
@@ -668,15 +611,13 @@ export function createServer() {
                                 break;
                             }
                         }
-                        catch { /* skip malformed */ }
+                        catch { }
                     }
                     kind = 'redirect';
                     fix = suggestRedirect(affectedKey ?? '', [], redirectFormat ?? 'htaccess', knownTarget);
                     break;
                 }
                 case 'broken-internal-links': {
-                    // Genuinely dead target (4xx/5xx) — no recorded destination exists, so fall back
-                    // to token-overlap fuzzy matching against live pages.
                     const livePages = db.db
                         .prepare('SELECT url FROM pages WHERE status_code = 200 AND indexable = 1')
                         .all();
@@ -687,11 +628,8 @@ export function createServer() {
                 case 'orphan-with-impressions':
                 case 'striking-distance': {
                     const page = db.db.prepare('SELECT h1, title FROM pages WHERE url_key = ?').get(affectedKey);
-                    // Prefer the GSC query as anchor, but fall back to H1/title when it's a
-                    // boolean/over-long search string (common on job boards) — not usable anchor text.
                     const q = evidence.query;
                     const cleanQuery = q && q.length <= 60 && !/["()]|\bor\b|\bnot\b|\s-\w/i.test(q) ? q : undefined;
-                    // Never fall back to the raw q — it was just rejected as unusable anchor text.
                     const anchor = cleanQuery ?? page?.h1 ?? page?.title ?? '';
                     kind = 'internal-links';
                     fix = suggestInternalLinks(db.db, affectedKey ?? '', anchor);
@@ -721,7 +659,6 @@ export function createServer() {
         const key = urlKey(url, { hostForm });
         return { content: [{ type: 'text', text: key }], structuredContent: { url, key, hostForm } };
     });
-    // ── GSC ─────────────────────────────────────────────────────────────────
     server.registerTool('list_properties', {
         title: 'List GSC properties',
         description: 'List Google Search Console properties accessible to the service account.',
@@ -733,8 +670,6 @@ export function createServer() {
             structuredContent: { properties },
         };
     });
-    // refresh_property — the "sync everything" verb (GSC + crawl + inspection in one job).
-    // Skip flags let the same tool do "just update X".
     registerAppTool(server, 'refresh_property', {
         title: 'Refresh a property (sync + crawl + inspect)',
         description: 'Full refresh for a property in one async job: GSC sync → site crawl → URL inspection → DataForSEO rank history. Opens a live progress widget (phases + counts). Set gsc/crawl/inspect/ranks=false to run just part. GSC sync is "lite" (date×query×page) by default — set segments=true to also pull device/country breakdowns (much heavier on large sites). GSC sync is INCREMENTAL: the first sync pulls the window (default last 90 days; pass startDate to go deeper), later syncs only fetch new days — set full=true to force a full re-pull. Use this for "sync everything"; use the single-purpose tools to update just one thing.',
@@ -756,8 +691,6 @@ export function createServer() {
     }, async ({ siteUrl, gsc: doGsc, crawl, inspect, ranks, segments, full, location, startDate, endDate, maxPages, inspectLimit }) => {
         const jobId = jobs.start('refresh', async (update, signal) => {
             const r = await refresh.run(siteUrl, { gsc: doGsc, crawl, inspect, ranks, segments, full, location, startDate, endDate, maxPages, inspectLimit }, update, signal);
-            // Property is now populated — spin up the browser dashboard and hand back its URL so the
-            // finished job (polled via check_sync_status) carries a one-click link, no extra tool call.
             await autoServeDashboard();
             const dashboardUrl = dashboardServerUrl();
             return dashboardUrl ? { ...r, dashboardUrl, dashboard: `${dashboardUrl}/dashboard?siteUrl=${encodeURIComponent(siteUrl)}` } : r;
@@ -820,7 +753,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // ── Crawl ─────────────────────────────────────────────────────────────────
     server.registerTool('start_crawl', {
         title: 'Crawl a site (just the crawl)',
         description: 'Update just the crawl: fetch the site into the local database (async job — poll with check_crawl_status). HTTP crawl; respects robots.txt; asset file-types are HEAD-only (no body download); internal-search / cart / wp-json / builder junk URLs are skipped by default. For a full refresh use refresh_property. excludePatterns adds extra URL regexes to skip (e.g. ["/author/","/tag/","/page/"]) to keep big crawls light. Grain: one row per url_key, latest crawl. Joins: url_key → GSC/inspection/backlinks.',
@@ -854,7 +786,6 @@ export function createServer() {
         const all = jobs.list();
         return { content: [{ type: 'text', text: `${all.length} jobs` }], structuredContent: { jobs: all } };
     });
-    // ── DataForSEO (cached 20 days, single-worker) ──────────────────────────
     server.registerTool('keyword_volume', {
         title: 'Keyword search volume (DataForSEO)',
         description: '[Paid: Keywords API, cheap, cached 20d | Use for: demand sizing] True monthly search volume + CPC + competition for keywords (DataForSEO KEYWORDS_DATA). Served from a 20-day cache; live calls are serialised. Default location: United States (2840).',
@@ -924,7 +855,6 @@ export function createServer() {
             articles.push(a);
         } };
         let cost = 0, cached = true, googleCount = 0, dfsCount = 0, googleError = null;
-        // Free Google News RSS.
         if (src === 'google' || src === 'both') {
             try {
                 const g = await fetchGoogleNews(keyword, { limit: n });
@@ -936,7 +866,6 @@ export function createServer() {
                 googleError = e instanceof Error ? e.message : 'failed';
             }
         }
-        // Paid DataForSEO Google News SERP (only when explicitly asked, or 'both' AND a key is set).
         if (src === 'dataforseo' || (src === 'both' && !!dfs)) {
             const r = await requireDfs(dfs).serpNews(keyword, location, languageCode, n);
             cost += r.cost;
@@ -945,8 +874,6 @@ export function createServer() {
             for (const a of r.articles)
                 add({ ...a, via: 'dataforseo' });
         }
-        // Top sources: which publishers are covering this topic, ranked by article count — the
-        // "who is talking about X" read. Powers "trending news + sources for X" in one call.
         const sourceCount = new Map();
         for (const a of articles) {
             const s = String(a.source ?? '').trim();
@@ -1010,8 +937,6 @@ export function createServer() {
             db.close();
         }
     });
-    // content_opportunities — the content marketer's report: everything the stored data
-    // says about what to WRITE, REFRESH and REWRITE, in one free composition.
     server.registerTool('content_opportunities', {
         title: 'Content opportunity report (write / refresh / rewrite)',
         description: 'The content marketer\'s report, composed entirely from stored data - NO paid calls. Four sections: WRITE NEXT (new pages proposed from queries you already earn impressions for but have no winning page - suggest_pages), REFRESH NOW (pages that lost 20%+ of their clicks vs the prior period - content decay), REWRITE SNIPPETS (page-1 rankings earning far below expected CTR - title/meta rewrites, the fastest wins), and STRENGTHEN (keyword clusters where you rank 4-20 - one push from the money positions). Every line traces to real Search Console data. Chain into draft_content for a brief, or keyword_volume to size a cluster against the market.',
@@ -1063,7 +988,6 @@ export function createServer() {
             },
         };
     });
-    // ── Content recon (recon_targets) — the data-intensive "why are we losing, what to do" mission ──
     server.registerTool('recon_targets', {
         title: 'Content recon: why a page is losing, and what to do about it',
         description: '[Paid: DataForSEO SERP per page (~$0.004 each, plus a small refundable surcharge for loading async AI Overviews), bounded to the batch | Use for: the deep "why are we behind and what to add" recon] For each of your worst declining / striking-distance pages (auto-selected by impressions x decline, position 3-15; or pass explicit urls), this fetches OUR live page with the crawler, pulls the live Google SERP (DataForSEO SERP-advanced, depth 20 organic), and classifies WHY we are behind using the organic-rank x AI-Overview-citation matrix: defend-and-deepen (cited + strong), accuracy-or-freshness (rank but the AIO will not quote us - the sharpest, most actionable class), consolidate-weak-page, competitive-gap, or page-cannot-rank (the crawl says the URL is noindex/canonicalised away, so its GSC history is legacy and the SERP read belongs to another page). Honesty rules baked in: every GSC figure carries its 28-day window; organicRank:null means "absent from the top 20 ORGANIC results", never a position; and an AI Overview whose citations could not be resolved reports aioCitesUs:null (UNKNOWN) rather than "not cited". To-dos are prioritised by OPPORTUNITY (impressions x the CTR gap between where you rank and a realistic target, damped by the verdict), not by raw impressions, and cannibalisation is counted across the whole query cluster. Set scrapeCompetitors:true to also pull the top competitors as content, routed by host: YouTube/video → Supadata transcript (SUPADATA_API_KEY), Reddit → its .json, other pages → Firecrawl (FIRECRAWL_API_KEY) with a free HTTP fallback; competitorLimit (default 5) caps how many are fetched and everything above the cap is listed as skipped. Cloudflare-challenge sites (e.g. PCMag) still can\'t be fetched from a server and come back as a per-URL error — the SERP still tells you they rank; if one matters, ask the user to paste its copy or supply a text file and diff that in. Transcribe the videos (usually what wins these SERPs) and use the reachable pages. Then write findings back with save_recon_todo; track with recon_todos. **Async job:** returns a jobId immediately - poll check_sync_status; the finished job carries the per-page verdicts, to-dos and a summary. (Each page is persisted to the ledger as it completes, so recon_todos shows results even mid-run.)',
@@ -1078,10 +1002,8 @@ export function createServer() {
             crawlAs: z.enum(['browser', 'googlebot']).optional().describe('UA for the free HTTP fetch: browser (default, mimics a visit from Google — gets Reddit + mid-tier) or googlebot'),
         },
     }, async ({ siteUrl, limit, minImpressions, location, urls, scrapeCompetitors, competitorLimit, crawlAs }) => {
-        const client = requireDfs(dfs); // fail fast if no DataForSEO creds, before starting the job
+        const client = requireDfs(dfs);
         const count = urls?.length ?? limit ?? 5;
-        // Async job: N live page-fetches + N serialised SERP calls exceed the ~60s MCP ceiling
-        // past a handful of pages, so return a jobId and poll (like refresh_property).
         const jobId = jobs.start('recon', async (update, signal) => {
             const db = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
             try {
@@ -1092,8 +1014,6 @@ export function createServer() {
                 const ownDomain = dfsHost(siteUrl);
                 const hostForm = hostFormForProperty(siteUrl) ?? 'asis';
                 const SERP_DEPTH = 20;
-                // Every GSC number below is this window and only this window. Undeclared, a 28-day figure
-                // read against an all-time baseline looks exactly like a decline.
                 const windowStart = db.db.prepare(`SELECT date(?, '-27 days') d`).get(fresh.effectiveMax);
                 const gscWindow = { start: windowStart.d, end: fresh.effectiveMax, days: 28, metric: 'Search Console, last 28 days of synced data (not all-time)' };
                 let targets;
@@ -1124,12 +1044,10 @@ export function createServer() {
                     try {
                         own = await fetchOwnPage(t.urlKey, hostForm === 'asis' ? 'asis' : hostForm);
                     }
-                    catch { /* page unreachable — classify on SERP alone */ }
+                    catch { }
                     const serpResp = await client.serpOrganic(t.query, location, 'en', SERP_DEPTH, { loadAsyncAiOverview: true });
                     cost += serpResp.cost;
                     const serp = parseSerpForRecon(serpResp, ownDomain, SERP_DEPTH);
-                    // The crawl row overrides the SERP/GSC read: GSC keeps reporting impressions for URLs
-                    // that have since been canonicalised away or set noindex.
                     const state = pageState(db.db, t.urlKey);
                     const serpVerdict = reconVerdict(serp);
                     const verdict = crawlRealityOverride(serpVerdict, state) ?? serpVerdict;
@@ -1148,10 +1066,6 @@ export function createServer() {
                     let competitorContent = undefined;
                     let competitorFetch = undefined;
                     if (scrapeCompetitors && (firecrawl || supadata)) {
-                        // Build a routed candidate set: organic-above + AI-Overview references + one ranking
-                        // video, deduped, our own domain removed. Each URL routes by HOST (YouTube→supadata,
-                        // Reddit→.json, else→firecrawl). What we don't fetch is REPORTED, not silently dropped
-                        // — an undeclared cap of 3 is what made this look like it returned nothing.
                         const seen = new Set();
                         const candidates = [];
                         const add = (url, from) => {
@@ -1164,8 +1078,6 @@ export function createServer() {
                         serp.aioReferences.slice(0, 6).forEach(r => add(r.url, 'aio-reference'));
                         serp.videoItems.slice(0, 2).forEach(v => add(v.url, 'video-pack'));
                         const lim = competitorLimit ?? 5;
-                        // Organic-above first (the editorial pages actually worth diffing), but keep one slot
-                        // for a ranking video — video is usually what wins these SERPs.
                         const video = candidates.find(c => c.route === 'video');
                         const rest = candidates.filter(c => c !== video);
                         const reserve = video && lim >= 3 ? 1 : 0;
@@ -1235,12 +1147,6 @@ export function createServer() {
                         return note;
                     })() +
                     `\n\nNext: research the competitors (transcribe the videos, read the reachable pages), write gaps back with save_recon_todo, and track with recon_todos.` + browserLink(siteUrl);
-                // The poll (check_sync_status) injects this result into the model's context, which the
-                // host caps (~25k tokens). The full per-page detail (heading lists, competitor URL arrays,
-                // full to-do objects, cannibalisation clusters) is already persisted to the ledger and read
-                // back via recon_todos, so the job result returns the readable `summary` plus a SLIM per-page
-                // view — verdict, ranks, opportunity — and keeps only competitorContent (the scraped research
-                // payload, which lives nowhere else). This keeps a 10-page poll well under the cap.
                 const slimTargets = results.map(r => ({
                     urlKey: r.urlKey, query: r.query, window: r.window,
                     impressions: r.impressions, gscPosition: r.gscPosition, priorPosition: r.priorPosition, slipped: r.slipped,
@@ -1262,8 +1168,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // save_recon_todo — the research session writes its content-gap / originality findings back
-    // into the ledger against a page (source: 'research').
     server.registerTool('save_recon_todo', {
         title: 'Save content-recon to-dos (research writeback)',
         description: 'Write content-recon findings back into the trackable ledger for a page — the gaps and originality the research session found by diffing competitors (firecrawl) and videos (supadata) against our content. Each to-do is an action with a type (content-gap / originality / schema / freshness / format), rationale and evidence. Snapshots the page baseline so the fix\'s effect on rank/AIO-citation is measurable later. Run recon_targets first (it classifies the page and seeds the deterministic to-dos); this adds the judgement ones. Track everything with recon_todos.',
@@ -1283,11 +1187,7 @@ export function createServer() {
         try {
             const key = urlKey(rawUrl, { hostForm: hostFormForProperty(siteUrl) ?? 'asis' });
             const page = db.db.prepare(`SELECT query, organic_rank, aio_cites_us, gsc_position, gsc_impressions, verdict FROM recon_page WHERE url_key=?`).get(key);
-            // aio_cites_us is NULL when the AI Overview never resolved — keep that as unknown rather
-            // than coercing it to false, or the outcome diff reads "no → yes" off a missing fetch.
             const baseline = page ? { organicRank: page.organic_rank, aioCitesUs: page.aio_cites_us == null ? null : !!page.aio_cites_us, gscPosition: page.gsc_position, at: new Date().toISOString().slice(0, 10) } : {};
-            // Default priority to the PAGE's opportunity so research to-dos sort on the same scale as
-            // the deterministic ones (a default of 0 buried every judgement finding at the bottom).
             const basis = page ? opportunityBasis(page.gsc_impressions ?? 0, page.organic_rank, page.gsc_position ?? 20, page.verdict) : null;
             const fallbackPriority = basis ? Math.max(1, Math.round(basis.opportunityClicks * basis.verdictFactor)) : 0;
             const drafts = todos.map(t => ({ action: t.action, type: t.type ?? 'content-gap', rationale: t.rationale ?? '', evidence: t.evidence ?? {}, priority: t.priority ?? fallbackPriority }));
@@ -1298,8 +1198,6 @@ export function createServer() {
             db.close();
         }
     });
-    // recon_todos — list, track and annotate the ledger. No id → list (optionally filtered);
-    // id → update status and/or append a dated annotation, and optionally re-measure the outcome.
     server.registerTool('recon_todos', {
         title: 'List, track and annotate content-recon to-dos',
         description: 'The content-recon to-do board. With no id: list to-dos (optionally filter by page or status), grouped by page with each page\'s verdict — the pick-a-page-to-work-on surface, and the hand-off to content-machine. With id: update one to-do — set status (open → researching → drafted → shipped → dismissed) and/or append a dated annotation note (your own observations, the history). On status:shipped with remeasure:true it re-fetches the SERP and records the outcome, so you can see whether the fix moved you from AIO-uncited to cited, or up the organic ranks.',
@@ -1325,7 +1223,6 @@ export function createServer() {
                 let outcome = row.outcome;
                 let outcomeNote = '';
                 if (status === 'shipped' && remeasure && dfs) {
-                    // Same depth + async-AIO handling as recon_targets, so before/after are comparable.
                     const serpResp = await dfs.serpOrganic(row.query, location, 'en', 20, { loadAsyncAiOverview: true });
                     const serp = parseSerpForRecon(serpResp, dfsHost(siteUrl), 20);
                     const cited = (v) => (v == null ? 'unknown' : v ? 'yes' : 'no');
@@ -1371,8 +1268,6 @@ export function createServer() {
             db.close();
         }
     });
-    // keyword_list — demand-first clustering ("list mode"): a keyword list becomes topics
-    // with own/weak/absent verdicts, clustered by the URL Google already answers them with.
     server.registerTool('keyword_list', {
         title: 'Cluster a keyword list into topics with own/weak/absent verdicts',
         description: 'Demand-first keyword clustering from stored data - NO paid calls. Give it a keyword list (or omit keywords to use your top 500 GSC queries) and it clusters them by the page Google ALREADY answers them with (two keywords that rank via the same URL belong together - the strongest clustering signal, free from your own GSC data), then groups non-ranking keywords lexically. Each cluster gets a deterministic verdict: OWN (best position <=3), WEAK (4-20), ABSENT (no ranking page), plus the ranking URL, summed 90-day impressions and clicks. The keyword-research workhorse: paste a client keyword list, get the topic map and where you stand. Chain with keyword_volume for market volumes on the interesting clusters, or draft_content for the absent ones.',
@@ -1501,7 +1396,7 @@ export function createServer() {
         const cleaned = target.replace(/^sc-domain:/, '').replace(/^https?:\/\//, '').replace(/^www\./, '').replace(/\/+$/, '');
         const r = await client.competitorsDomain(cleaned, location, languageCode, limit ?? 20);
         const items = (r.tasks[0]?.result?.[0]?.items ?? [])
-            .filter((it) => it.domain && it.domain.replace(/^www\./, '') !== cleaned) // drop the target itself
+            .filter((it) => it.domain && it.domain.replace(/^www\./, '') !== cleaned)
             .map((it) => ({
             domain: it.domain,
             intersections: it.intersections ?? null,
@@ -1529,7 +1424,7 @@ export function createServer() {
         const r = await client.pageIntersection(competitorUrls, excludePages ?? [], location, languageCode, limit ?? 100);
         const items = (r.tasks[0]?.result?.[0]?.items ?? [])
             .map((it) => {
-            const kd = it.keyword_data ?? {}; // actual shape: item.keyword_data.{keyword,keyword_info}
+            const kd = it.keyword_data ?? {};
             return {
                 keyword: kd.keyword ?? null,
                 searchVolume: kd.keyword_info?.search_volume ?? null,
@@ -1540,16 +1435,13 @@ export function createServer() {
                 })),
             };
         })
-            .sort((a, b) => (b.searchVolume ?? 0) - (a.searchVolume ?? 0)); // order_by unsupported on this endpoint
+            .sort((a, b) => (b.searchVolume ?? 0) - (a.searchVolume ?? 0));
         return {
             content: [{ type: 'text', text: `${items.length} gap keywords${r.cached ? ' (cached)' : ` (live, $${r.cost.toFixed(4)})`}` }],
             structuredContent: { gaps: items, cached: r.cached, cost: r.cost },
         };
     });
-    // Strip any scheme/sc-domain:/path down to a bare host for Labs domain targets.
-    // Always strips leading www. — Labs treats www.example.com as a subdomain, not the domain.
     const dfsHost = (t) => t.replace(/^sc-domain:/, '').replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '').trim();
-    // Cap a markdown table well under the ~40k model-facing ceiling: keep whole rows, note the rest.
     const capMdRows = (header, rows, footer = '', maxChars = 30000) => {
         let out = header;
         let used = 0;
@@ -1581,7 +1473,6 @@ export function createServer() {
         const r = await client.historicalRankOverview(cleaned, location, 'en', languageName);
         const items = r.tasks[0]?.result?.[0]?.items ?? [];
         const n = (v) => Number(v) || 0;
-        // Guard year/month — a malformed item would emit an "undefined-NaN" period row.
         const series = items
             .filter((it) => Number.isInteger(it?.year) && Number.isInteger(it?.month))
             .map((it) => {
@@ -1641,7 +1532,7 @@ export function createServer() {
             .map((it) => {
             const page = it.page_address ?? it.relative_url ?? null;
             if (!page)
-                return null; // skip malformed rows
+                return null;
             const o = it.metrics?.organic ?? {};
             const top3 = n(o.pos_1) + n(o.pos_2_3);
             return {
@@ -1698,14 +1589,9 @@ export function createServer() {
         const folderPath = mode === 'folder'
             ? (folder.trim().startsWith('/') ? folder.trim() : '/' + folder.trim())
             : null;
-        // aioOnly: only rows where the target's ranked element is an AI Overview citation —
-        // expressed as a serp_item.type filter (item_types is invalid on this Labs endpoint).
         const clauses = [];
         if (folderPath)
             clauses.push(['ranked_serp_element.serp_item.relative_url', 'like', `${folderPath}%`]);
-        // Exposure, not citation: Labs ranked_keywords carries no citation fields (verified via
-        // available_filters) — this filters to keywords whose SERP CONTAINS an AI Overview.
-        // Per-keyword citation checking (are WE a reference?) is the SERP-advanced recipe.
         if (aioOnly)
             clauses.push(['keyword_data.serp_info.serp_item_types', 'has', 'ai_overview']);
         const filters = clauses.length === 0 ? undefined : clauses.length === 1 ? clauses : [clauses[0], 'and', clauses[1]];
@@ -1717,7 +1603,7 @@ export function createServer() {
             const kd = it.keyword_data ?? {};
             const serp = it.ranked_serp_element?.serp_item ?? {};
             if (!kd.keyword)
-                return null; // skip malformed rows
+                return null;
             const serpFeatures = Array.isArray(kd.serp_info?.serp_item_types) ? kd.serp_info.serp_item_types : null;
             return {
                 keyword: kd.keyword,
@@ -1725,7 +1611,6 @@ export function createServer() {
                 searchVolume: kd.keyword_info?.search_volume ?? null,
                 etv: serp.etv != null ? Math.round(Number(serp.etv) * 100) / 100 : null,
                 url: serp.relative_url ?? serp.url ?? null,
-                // Fields we already pay for but previously dropped (plan/data-utilisation.md Part 2 §4):
                 keywordDifficulty: kd.keyword_properties?.keyword_difficulty ?? null,
                 intent: kd.search_intent_info?.main_intent ?? null,
                 serpFeatures,
@@ -1744,7 +1629,6 @@ export function createServer() {
         }
         const totalCount = Number(result.total_count) || kws.length;
         const sumEtv = kws.reduce((s, k) => s + (k.etv ?? 0), 0);
-        // Optional columns — only where the response actually carries the field (older cache entries won't).
         const hasKd = kws.some(k => k.keywordDifficulty != null);
         const hasIntent = kws.some(k => k.intent != null);
         const hasFeatures = kws.some(k => (k.serpFeatures && k.serpFeatures.length) || k.isFeaturedSnippet);
@@ -1767,9 +1651,6 @@ export function createServer() {
             structuredContent: { target: dfsTarget, scope: mode, aioOnly: aioOnly ?? false, totalCount, rowsTotal: kws.length, keywords: kws.slice(0, 100), cached: r.cached, cost: r.cost },
         };
     });
-    // serp_features — the SERP-feature footprint: "how much of my market do AI Overviews,
-    // snippets and other features sit on, and do I already rank page 1 there?" One cached
-    // Labs pull, volume-weighted; persisted so the dashboard can chart it.
     server.registerTool('serp_features', {
         title: 'SERP-feature footprint (AI Overviews, snippets, PAA)',
         description: '[Paid: Labs, ONE cached call | Use for: AI-Overview / zero-click exposure with real numbers] How much of your keyword universe carries each SERP feature - AI Overviews, featured snippets, People Also Ask, shopping, video - weighted by search volume, and how much of that volume you already rank page 1 for. ONE DataForSEO Labs ranked_keywords pull (top-volume sample, cached 20 days, never per-keyword SERP loops). Answers "how exposed are we to AI Overviews / zero-click?" with real numbers. Deterministic: feature PRESENCE (from the Labs index). Judgement proxy: page-1 rank stands in for feature ownership - true ownership needs per-keyword SERP calls (see ranked_keywords aioOnly + the cookbook). Persists to the property DB so the dashboard charts it.',
@@ -1814,8 +1695,6 @@ export function createServer() {
             structuredContent: fp,
         };
     });
-    // market_sizing — Market Sizing and Prioritisation: the organic market read that opens
-    // an engagement. Top-down Labs pulls only (client + <=4 rivals), cached, ~$0.65 worst case.
     server.registerTool('market_sizing', {
         title: 'Market Sizing and Prioritisation (share of voice vs competitors)',
         description: '[Paid: Labs, one cached call per domain (<=5) | Use for: sizing the organic market and who owns it] Build the organic market map: your domain plus up to 4 named competitors, ONE cached Labs ranked_keywords pull each, unioned into a keyword universe. Returns total monthly demand (deduplicated search volume), each domain\'s share of voice (ETV share) overall and per topic cluster, and the leader per cluster - the "here is the market, here is who owns it, here is where to attack" table that opens an engagement. Deterministic: the competitor set and ranked keywords (Labs index). Judgement: ETV is DataForSEO\'s CTR-curve traffic estimate - the SoV percentages inherit that. Persists to the property DB for the dashboard chart. Get the competitor set from competitors_domain first if unsure.',
@@ -1833,7 +1712,7 @@ export function createServer() {
         const inputs = [];
         let cost = 0;
         let cachedAll = true;
-        for (const domain of domains) { // sequential - the client serialises anyway
+        for (const domain of domains) {
             const r = await client.rankedKeywords(domain, location, languageCode ?? 'en', limitPerDomain ?? 1000, 'keyword_data.keyword_info.search_volume,desc');
             cost += r.cost;
             cachedAll = cachedAll && r.cached;
@@ -1899,8 +1778,6 @@ export function createServer() {
             const ourHost = dfsHost(siteUrl);
             let totalCost = 0, liveCalls = 0, cachedCalls = 0;
             const tally = (r) => { totalCost += r.cost; r.cached ? cachedCalls++ : liveCalls++; };
-            // Competitors: explicit (≤3) or derived top-2 by keyword overlap. Total Labs
-            // budget stays ≤4 calls: at most 1 discovery + at most 3 footprint pulls.
             let comps = [...new Set((competitors ?? []).map(dfsHost).filter(c => c && c !== ourHost))].slice(0, 3);
             let derived = false;
             if (!comps.length) {
@@ -1919,7 +1796,6 @@ export function createServer() {
                     };
                 }
             }
-            // One ranked_keywords pull per competitor (top 1000 rows by ETV — their money keywords).
             const rows = [];
             const perCompetitor = {};
             for (const c of comps) {
@@ -1968,8 +1844,6 @@ export function createServer() {
                 `${res.competitorKeywords} distinct competitor keywords → ${res.afterSubtraction} survive subtraction of your footprint (${fmtVol(res.ourQueryCount)} GSC queries + page titles/H1s) → top ${res.clusters.length} topic clusters by volume × competitor coverage.\n\n` +
                 sections.join('\n\n') +
                 `\n\n_${costLine} Competitor rows: ${comps.map(c => `${c} ${perCompetitor[c] ?? 0}`).join(', ')}._`;
-            // structuredContent: keyword lists capped at 10 per cluster with explicit totals
-            // (host ~60k model-facing ceiling) — the counts always state the true size.
             const scClusters = res.clusters.map(c => ({
                 ...c,
                 keywords: c.keywords.slice(0, 10),
@@ -1989,16 +1863,12 @@ export function createServer() {
             db.close();
         }
     });
-    // ── Dashboard (MCP App UI — houtini design + ECharts) ───────────────────
     registerAppTool(server, 'get_dashboard', {
         title: 'SEO dashboard',
         description: 'Interactive dashboard for a property: summary metrics, rank & clicks over time, and top-keyword performance (click a keyword for related terms). Needs synced GSC data — run refresh_property first.',
         inputSchema: { siteUrl: z.string() },
         _meta: { ui: { resourceUri: DASHBOARD_URI } },
     }, async ({ siteUrl }) => {
-        // Return only a TINY model-facing result + the siteUrl; the widget fetches the full
-        // (large) dataset itself via the app-only get_dashboard_data tool, which keeps the
-        // big payload OUT of the model's context/token limit (per the MCP Apps large-data pattern).
         const data = getDashboardData(dataDir(), siteUrl);
         if (data.empty) {
             return { content: [{ type: 'text', text: `No synced data for ${siteUrl} yet — run refresh_property.` }], structuredContent: { siteUrl, empty: true } };
@@ -2008,9 +1878,6 @@ export function createServer() {
             `${data.findings ? `, ${data.findings.total} audit findings` : ''}. Interactive charts + findings render in the widget.` + browserLink(siteUrl);
         return { content: [{ type: 'text', text: summary }], structuredContent: { siteUrl } };
     });
-    // App-only data tool: the dashboard widget calls this via app.callServerTool to fetch its
-    // full dataset. visibility:['app'] hides it from the model; results route to the iframe,
-    // bypassing the model token cap that a large model-facing result would hit.
     registerAppTool(server, 'get_dashboard_data', {
         title: 'Dashboard data (internal)',
         description: 'Full dashboard dataset for the UI widget. App-only — not for direct use.',
@@ -2020,9 +1887,6 @@ export function createServer() {
         const data = { ...getDashboardData(dataDir(), siteUrl), apiKeys: apiKeysStatus() };
         return { content: [{ type: 'text', text: 'ok' }], structuredContent: data };
     });
-    // export_report — the dependable deliverable: a self-contained interactive dashboard
-    // HTML (data inlined) the user opens in any browser / emails to a client. Works
-    // regardless of whether the host renders MCP-App widgets inline.
     server.registerTool('export_report', {
         title: 'Export a shareable dashboard report (HTML)',
         description: 'Write a self-contained, interactive dashboard HTML for a property (all data + charts inlined) to the reports folder, and return the file path. Open it in any browser or send it to a client — no server, no MCP-App host support needed. Run refresh_property (+ run_audit for findings) first.',
@@ -2033,10 +1897,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: `No synced data for ${siteUrl} — run refresh_property first.` }], structuredContent: { error: 'empty', siteUrl } };
         }
         const tpl = readFileSync(path.join(__dirname, 'src', 'ui', 'dashboard.html'), 'utf8');
-        const json = JSON.stringify(data).replace(/</g, '\\u003c'); // prevent </script> breakout
+        const json = JSON.stringify(data).replace(/</g, '\\u003c');
         const inject = `<script>window.__DASH_FIXTURE__=${json};window.__DASH_THEME__=${JSON.stringify(theme ?? 'light')};</script>`;
-        // Replacement FUNCTION, not string — crawl data containing $& / $' would otherwise
-        // be interpreted as String.replace substitution patterns and corrupt the report.
         const html = tpl.replace(/<head([^>]*)>/i, (_m, attrs) => `<head${attrs}>${inject}`);
         const dir = path.join(dataDir(), 'reports');
         mkdirSync(dir, { recursive: true });
@@ -2047,8 +1909,6 @@ export function createServer() {
             structuredContent: { path: file, siteUrl, findings: data.findings?.total ?? 0, bytes: html.length },
         };
     });
-    // serve_dashboard — the local webserver delivery surface: the full dashboard in a real
-    // browser tab (live data, property switcher, native downloads), no MCP-App host needed.
     server.registerTool('serve_dashboard', {
         title: 'Serve the dashboard on a local webserver',
         description: 'Start a localhost-only webserver and return a URL that opens the full interactive dashboard in your browser — live data straight from the local database (always current, unlike export_report snapshots), a property switcher, working CSV downloads, and no host widget limits. The server stays up while the MCP server runs; call again with stop=true to shut it down. Localhost only — nothing is exposed to the network.',
@@ -2072,8 +1932,6 @@ export function createServer() {
             structuredContent: { url: open, base: url },
         };
     });
-    // pull_backlinks — on-demand backlink profile (DataForSEO, paid + 20-day cached). Powers
-    // backlinks-to-404 (the big quick win), top-linked pages, and true-orphan detection.
     server.registerTool('pull_backlinks', {
         title: 'Pull backlink profile (DataForSEO)',
         description: '[Paid: Backlinks subscription (separate - 40204 = not activated), cached 20d | Use for: authority + dead-backlink recovery] Fetch the property’s backlink profile (overall summary — total backlinks, referring domains, Domain Rank, broken backlinks/pages, nofollow share — plus per-page backlink/referring-domain counts) into page_backlinks, and resolve each backlinked page’s live HTTP status so run_audit can flag external backlinks pointing to dead (4xx/5xx) pages. Paid DataForSEO call, 20-day cached, on-demand only. Async job — poll check_sync_status. Grain: one row per backlinked URL. Joins: url_key → pages/GSC; domain → Labs tools.',
@@ -2086,9 +1944,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // link_intersect — "what links do our competitors have that we don't?". One DataForSEO
-    // backlinks/domain_intersection call (paid, ~$0.024, 20-day cached), aggregated + prioritised
-    // client-side. Default sort = the link-builder's: followed links first, then domain trust.
     server.registerTool('link_intersect', {
         title: 'Link intersect — links your competitors have that you don’t (DataForSEO + Majestic)',
         description: '[Paid: Backlinks subscription (separate - 40204 = not activated), one cached call ~$0.024 | Use for: prospect list for link outreach] Answers "what links do our competitors have that we don’t?" - and for a SINGLE company, "what links does company X have that we don’t?" (pass competitors:["companyx.com"]). One DataForSEO domain_intersection call over the target set (excluding your domain), aggregated per prospect domain: how many of the targets it links to, its DataForSEO domain trust (rank 0-1000), worst spam score, whether the link is followed, the anchor/link-type mix. Default sort is the link-builder’s view - FOLLOWED links first, then domain trust - with spam filtered out. When MAJESTIC_API_KEY is set, prospects are enriched with Majestic Trust Flow + Topical Trust Flow and RE-SORTED by Trust Flow (the directory-killer: a DataForSEO rank-227 domain is often Trust Flow 0). Results persist to link_prospects. Pass targets explicitly (max 20) or let it derive the top few via competitors_domain. Grain: one row per prospect domain. Join: domain.',
@@ -2107,8 +1962,6 @@ export function createServer() {
     }, async ({ siteUrl, competitors, location, poolLimit, minIntersections, maxSpamScore, dofollowOnly, topN, sort, enrichLimit }) => {
         const li = requireDfs(linkIntersect);
         const ownHost = dfsHost(siteUrl);
-        // Prior-run awareness: if this property already has link_prospects, frame the run as an
-        // update (the previous set ages as competitors keep earning links). Read-only, cheap.
         let priorNote = '';
         {
             const d = new AuditDatabase(dbPathFor(dataDir(), siteUrl));
@@ -2119,12 +1972,11 @@ export function createServer() {
                     priorNote = ` _(updating a prior intersect of ${prior.n} prospects from ${prior.t.slice(0, 10)}, ${ageDays}d ago)_`;
                 }
             }
-            catch { /* pre-link_intersect DB */ }
+            catch { }
             finally {
                 d.close();
             }
         }
-        // Competitors: explicit (deduped, minus self) or derived top few by keyword overlap.
         let comps = [...new Set((competitors ?? []).map(dfsHost).filter(c => c && c !== ownHost))];
         let derived = false;
         let deriveCost = 0;
@@ -2161,7 +2013,6 @@ export function createServer() {
             ...(enrichLimit != null ? { enrichLimit } : {}),
         }, majestic);
         const enriched = result.majesticEnriched > 0;
-        // With Majestic: show Trust Flow (0-100) + the domain's top topic. Without: DataForSEO domain rank.
         const trustHead = enriched ? 'Trust Flow' : 'Domain trust';
         const rows = result.prospects.map(p => {
             const trust = enriched ? (p.trustFlow ?? '–') : (p.domainTrust ?? '–');
@@ -2193,7 +2044,6 @@ export function createServer() {
             structuredContent: { jobId, status: 'running', siteUrl },
         };
     });
-    // ── Static reference resources (same content the tools return — one source of truth) ──
     server.registerResource('checks-reference', 'seo-audit://checks-reference', {
         title: 'Check registry reference',
         description: 'The full audit check catalogue (the list_checks data) rendered as markdown: every check with category, severity, labels, certainty, fix type and its one-line fix.',