glippy-mcp 0.1.0

package/src/index.js

@@ -0,0 +1,3318 @@
+#!/usr/bin/env node
+
+/**
+ * Glippy MCP Server
+ *
+ * Exposes Glippy's GEO (Generative Engine Optimization) analysis as MCP tools
+ * so that AI models can check any domain's AI-readiness directly.
+ *
+ * Tools:
+ *   - analyze_domain:   Full GEO analysis of a domain (robots.txt, llms.txt, HTML, sitemap, etc.)
+ *   - check_robots_txt: Check a domain's robots.txt for AI crawler access rules
+ *   - check_llms_txt:   Check if a domain has an llms.txt file
+ *   - get_geo_summary:  Get a concise summary of a domain's GEO score and top issues
+ *   - compare_domains:  Analyse multiple domains in parallel and compare scores side by side
+ *   - analyze_sitemap:  Fetch a sitemap XML, extract URLs, and analyse each page
+ *   - analyze_urls:     Analyse a list of specific URLs across any domains
+ *   - export_report:    Generate a styled Markdown or HTML report (matches extension export)
+ *   - export_bulk_report: Generate a styled report for multi-domain, multi-URL, or sitemap analysis
+ *
+ * Transport: stdio (JSON-RPC over stdin/stdout)
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  checkGEO,
+  analyseHTML,
+  analyseRobotsTxt,
+  throttledFetchUrl,
+  parseSitemapUrls,
+  aggregatePageScores,
+} from "./geo-checker.js";
+
+// ---------------------------------------------------------------------------
+// License validation
+// ---------------------------------------------------------------------------
+
+const API_BASE =
+  process.env.GLIPPY_API_URL || "https://glippy-mcp-api.info-8cb.workers.dev";
+
+/** Unique instance ID for this MCP server process (used for activation tracking). */
+const INSTANCE_ID = randomUUID();
+
+/** Cached license validation result. */
+let licenseCache = null; // { valid, tier, validUntil }
+
+/** Cached feature limits from license. */
+let licensedFeatures = null;
+
+/** Default features for trial/unlicensed users (Personal tier equivalent). */
+const DEFAULT_FEATURES = {
+  maxSitemapUrls: 50000,
+  maxBatchUrls: 100,
+  compareDomains: true,
+  bulkExport: true,
+};
+
+/** Number of free trial runs before license is required. */
+const FREE_TRIAL_RUNS = 11;
+
+/** Get the path to the usage tracking file. */
+function getUsageFilePath() {
+  const configDir = join(homedir(), ".glippy");
+  return join(configDir, "mcp-usage.json");
+}
+
+/** Read the current usage count from the tracking file. */
+function getUsageCount() {
+  const filePath = getUsageFilePath();
+  try {
+    if (existsSync(filePath)) {
+      const data = JSON.parse(readFileSync(filePath, "utf8"));
+      return data.count || 0;
+    }
+  } catch {
+    // If file is corrupted, start fresh
+  }
+  return 0;
+}
+
+/** Increment and persist the usage count. Returns the new count. */
+function incrementUsageCount() {
+  const filePath = getUsageFilePath();
+  const configDir = join(homedir(), ".glippy");
+
+  // Ensure config directory exists
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+
+  const currentCount = getUsageCount();
+  const newCount = currentCount + 1;
+
+  writeFileSync(filePath, JSON.stringify({ count: newCount }, null, 2), "utf8");
+  return newCount;
+}
+
+/**
+ * Validate the license key against the Glippy API.
+ * Caches a successful result for 24 hours (server-controlled TTL).
+ * Returns { valid: true, tier } on success or { valid: false, error } on failure.
+ */
+async function validateLicense() {
+  // Return cached result if still valid
+  if (licenseCache && new Date(licenseCache.validUntil) > new Date()) {
+    return { valid: true, tier: licenseCache.tier };
+  }
+
+  const licenseKey = process.env.GLIPPY_LICENSE_KEY;
+  if (!licenseKey) {
+    return {
+      valid: false,
+      error:
+        "No license key configured. Set GLIPPY_LICENSE_KEY in your environment. " +
+        "Get a key at https://www.glippy.dev/mcp",
+    };
+  }
+
+  try {
+    const res = await fetch(`${API_BASE}/api/mcp/verify-license`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ licenseKey, instanceId: INSTANCE_ID }),
+    });
+
+    const data = await res.json();
+
+    if (!data.valid) {
+      licenseCache = null;
+      licensedFeatures = null;
+      return {
+        valid: false,
+        error: data.error || "License validation failed",
+      };
+    }
+
+    // Cache the successful validation and features
+    licenseCache = {
+      valid: true,
+      tier: data.tier,
+      validUntil: data.validUntil,
+    };
+    licensedFeatures = data.features || DEFAULT_FEATURES;
+
+    console.error(`License validated (tier: ${data.tier}, valid until: ${data.validUntil})`);
+    console.error(`Features: ${JSON.stringify(licensedFeatures)}`);
+    return { valid: true, tier: data.tier, features: licensedFeatures };
+  } catch (err) {
+    // If the server is unreachable but we have a recent cache, allow a grace period
+    if (licenseCache && licenseCache.valid) {
+      console.error(
+        `License server unreachable, using cached validation (expires: ${licenseCache.validUntil})`
+      );
+      return { valid: true, tier: licenseCache.tier };
+    }
+
+    return {
+      valid: false,
+      error: `Could not reach license server: ${err.message}. Check your internet connection.`,
+    };
+  }
+}
+
+/**
+ * Wraps a tool handler with license validation.
+ * Allows FREE_TRIAL_RUNS free uses before requiring a license.
+ * Returns a license error to the AI model if the key is invalid and trial is exhausted.
+ */
+function withLicense(handler) {
+  return async (args) => {
+    const license = await validateLicense();
+
+    // If license is valid, just run the handler
+    if (license.valid) {
+      return handler(args);
+    }
+
+    // No valid license - check if we're still within free trial
+    const usageCount = getUsageCount();
+
+    if (usageCount >= FREE_TRIAL_RUNS) {
+      // Trial exhausted
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Trial expired: You've used all ${FREE_TRIAL_RUNS} free runs. ` +
+              `Set GLIPPY_LICENSE_KEY in your environment to continue. ` +
+              `Get a key at https://www.glippy.dev/mcp`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Still within trial - increment counter and run
+    const newCount = incrementUsageCount();
+    const remaining = FREE_TRIAL_RUNS - newCount;
+
+    console.error(
+      `Trial run ${newCount}/${FREE_TRIAL_RUNS} (${remaining} remaining). ` +
+        `Get a license at https://www.glippy.dev/mcp`
+    );
+
+    return handler(args);
+  };
+}
+
+/**
+ * Get the current feature limits (from license or defaults).
+ */
+function getFeatures() {
+  return licensedFeatures || DEFAULT_FEATURES;
+}
+
+/**
+ * Wraps a tool handler with tier-based feature gating.
+ * First validates the license (with trial support), then checks if the required
+ * feature is enabled for the user's tier.
+ *
+ * @param {string} featureName - The feature to check (e.g., "compareDomains", "bulkExport")
+ * @param {string} upgradeMessage - Message to show if feature is not available
+ * @param {Function} handler - The tool handler function
+ */
+function withTierFeature(featureName, upgradeMessage, handler) {
+  return withLicense(async (args) => {
+    const features = getFeatures();
+
+    // Check if feature is enabled
+    if (!features[featureName]) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${upgradeMessage}\n\nUpgrade your license at https://www.glippy.dev/mcp`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    return handler(args, features);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Convert a numeric score (0-100) to a letter grade. */
+function scoreToGrade(score) {
+  if (score >= 90) return "A+";
+  if (score >= 80) return "A";
+  if (score >= 70) return "B";
+  if (score >= 60) return "C";
+  if (score >= 50) return "D";
+  return "F";
+}
+
+/** Format a category result into a readable string. */
+function formatCategory(cat) {
+  const grade = scoreToGrade(cat.score);
+  let text = `[${grade}] ${cat.category}: ${cat.score}%`;
+  if (cat.checks) {
+    const fails = cat.checks.filter((c) => c.status === "fail");
+    const warns = cat.checks.filter((c) => c.status === "warn");
+    if (fails.length > 0) {
+      text += `\n    Issues: ${fails.map((f) => f.label).join("; ")}`;
+    }
+    if (warns.length > 0) {
+      text += `\n    Warnings: ${warns.map((w) => w.label).join("; ")}`;
+    }
+  }
+  return text;
+}
+
+/** Escape HTML special characters to prevent XSS. */
+function escapeHTML(str) {
+  if (str == null) return "";
+  return String(str)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+/** Strip HTML tags for plain-text output. */
+function htmlToPlainText(str) {
+  if (str == null) return "";
+  return String(str).replace(/<[^>]*>/g, "");
+}
+
+/** Map numeric score to a colour hex string. */
+function getScoreColor(score) {
+  if (score >= 80) return "#34d399";
+  if (score >= 60) return "#fbbf24";
+  if (score >= 40) return "#fb923c";
+  return "#f87171";
+}
+
+/** Map numeric score to a grade object { letter, label }. */
+function getGrade(score) {
+  if (score >= 90) return { letter: "A+", label: "Excellent agent readiness!" };
+  if (score >= 80) return { letter: "A", label: "Great! Minor improvements possible." };
+  if (score >= 70) return { letter: "B", label: "Good, but room to improve." };
+  if (score >= 60) return { letter: "C", label: "Needs work for agent readiness." };
+  if (score >= 40) return { letter: "D", label: "Significant issues found." };
+  return { letter: "F", label: "Major GEO gaps — let's fix this!" };
+}
+
+/** Category → emoji mapping (matches extension). */
+const CATEGORY_ICONS = {
+  "Structured Data & Schema": "\u{1F9EC}",
+  "Semantic HTML": "\u{1F3D7}\uFE0F",
+  "Accessibility for Agents": "\u267F",
+  "Internal Linking": "\u{1F517}",
+  "Meta & Discoverability": "\u{1F50D}",
+  "Machine Readability": "\u{1F916}",
+  "Entity & Authority": "\u{1F3DB}\uFE0F",
+  "Citability & Answer-Readiness": "\u{1F4AC}",
+  "Performance & Crawlability": "\u26A1",
+  "Agent Interactivity": "\u{1F50C}",
+};
+
+/** Categories whose issues are always low priority. */
+const LOW_PRIORITY_CATEGORIES = [
+  "Performance & Crawlability",
+  "Agent Interactivity",
+];
+
+/** Format robots.txt crawler analysis into a readable string. */
+function formatCrawlerAccess(blocksCrawlers) {
+  const lines = [];
+  for (const [crawler, blocked] of Object.entries(blocksCrawlers)) {
+    lines.push(`  ${crawler}: ${blocked ? "BLOCKED" : "allowed"}`);
+  }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Report generators (Markdown & HTML)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a Markdown report from a GEO analysis result.
+ *
+ * @param {object} result - The full checkGEO result object.
+ * @param {boolean} fullExport - If true, include every category and check.
+ *   If false (default), output recommendations only (fail/warn checks).
+ * @returns {string} Markdown string.
+ */
+function generateMarkdownReport(result, fullExport = false) {
+  const analysis = result.homepage?.analysis;
+  const score = analysis?.overallScore ?? 0;
+  const grade = getGrade(score);
+  const url = `https://${result.domain}`;
+
+  let md = `# Glippy GEO Agent-Readiness Report\n\n`;
+  md += `**URL:** ${url}\n`;
+  md += `**Date:** ${result.timestamp}\n`;
+  md += `**Overall Score:** ${score}/100 (Grade: ${grade.letter})\n`;
+  md += `\n---\n\n`;
+
+  const categories = analysis?.categories || [];
+
+  if (fullExport) {
+    // Full export: all categories and checks
+    for (const cat of categories) {
+      const icon = CATEGORY_ICONS[cat.category] || "\u{1F4CB}";
+      md += `## ${icon} ${cat.category} (${cat.score}/100)\n\n`;
+
+      for (const check of cat.checks || []) {
+        const emoji =
+          check.status === "pass"
+            ? "\u2705"
+            : check.status === "fail"
+              ? "\u274C"
+              : check.status === "warn"
+                ? "\u26A0\uFE0F"
+                : "\u2139\uFE0F";
+        md += `- ${emoji} **${htmlToPlainText(check.label)}**`;
+        if (check.detail) {
+          md += `\n  - ${htmlToPlainText(check.detail)}`;
+        }
+        if (check.found && check.found.length > 0) {
+          md += `\n  - Found:`;
+          for (const item of check.found) {
+            md += `\n    - ${htmlToPlainText(item)}`;
+          }
+        }
+        md += `\n`;
+      }
+      md += `\n`;
+    }
+
+    // robots.txt summary
+    md += `## robots.txt\n\n`;
+    md += `- **Exists:** ${result.robotsTxt?.exists ? "Yes" : "No"}\n`;
+    if (result.robotsTxt?.exists) {
+      const blocked = Object.entries(result.robotsTxt.blocksCrawlers || {})
+        .filter(([, b]) => b)
+        .map(([name]) => name);
+      const allowed = Object.entries(result.robotsTxt.blocksCrawlers || {})
+        .filter(([, b]) => !b)
+        .map(([name]) => name);
+      if (blocked.length > 0) md += `- **Blocked crawlers:** ${blocked.join(", ")}\n`;
+      if (allowed.length > 0) md += `- **Allowed crawlers:** ${allowed.join(", ")}\n`;
+    }
+    md += `\n`;
+
+    // llms.txt summary
+    md += `## llms.txt\n\n`;
+    md += `- **Exists:** ${result.llmsTxt?.exists ? "Yes" : "No"}\n`;
+    md += `- *Note: llms.txt is not currently supported by major AI models or crawlers — having one cannot hurt but is not a meaningful optimization.*\n`;
+    md += `\n`;
+
+    // Sitemap summary
+    md += `## Sitemap\n\n`;
+    md += `- **Exists:** ${result.sitemap?.exists ? "Yes" : "No"}\n`;
+    if (result.sitemap?.urlsDiscovered > 0) {
+      md += `- **URLs discovered:** ${result.sitemap.urlsDiscovered}\n`;
+    }
+    md += `\n`;
+  } else {
+    // Recommendations only: fail and warn checks
+    md += `## Recommended Changes\n\n`;
+
+    const recommendations = [];
+    for (const cat of categories) {
+      for (const check of cat.checks || []) {
+        if (check.status === "fail" || check.status === "warn") {
+          const isLow = LOW_PRIORITY_CATEGORIES.includes(cat.category);
+          const priority = isLow ? "Low" : check.status === "fail" ? "High" : "Medium";
+          recommendations.push({
+            priority,
+            category: cat.category,
+            label: htmlToPlainText(check.label),
+            detail: check.detail ? htmlToPlainText(check.detail) : null,
+          });
+        }
+      }
+    }
+
+    if (recommendations.length === 0) {
+      md += `\u2705 **No issues found!** This page passes all checks.\n`;
+    } else {
+      const high = recommendations.filter((r) => r.priority === "High");
+      const medium = recommendations.filter((r) => r.priority === "Medium");
+      const low = recommendations.filter((r) => r.priority === "Low");
+
+      if (high.length > 0) {
+        md += `### \u{1F534} High Priority\n\n`;
+        for (const rec of high) {
+          md += `- **${rec.category}:** ${rec.label}`;
+          if (rec.detail) md += `\n  - ${rec.detail}`;
+          md += `\n`;
+        }
+        md += `\n`;
+      }
+
+      if (medium.length > 0) {
+        md += `### \u{1F7E1} Medium Priority\n\n`;
+        for (const rec of medium) {
+          md += `- **${rec.category}:** ${rec.label}`;
+          if (rec.detail) md += `\n  - ${rec.detail}`;
+          md += `\n`;
+        }
+        md += `\n`;
+      }
+
+      if (low.length > 0) {
+        md += `### \u{1F535} Low Priority\n\n`;
+        for (const rec of low) {
+          md += `- **${rec.category}:** ${rec.label}`;
+          if (rec.detail) md += `\n  - ${rec.detail}`;
+          md += `\n`;
+        }
+        md += `\n`;
+      }
+    }
+  }
+
+  md += `---\n\n`;
+  md += `*Generated by [Glippy](https://www.glippy.dev) — GEO Agent-Readiness Checker*\n`;
+  return md;
+}
+
+/**
+ * Generate a standalone HTML report from a GEO analysis result.
+ * Matches the browser extension's export styling (dark/light toggle, score
+ * ring, category accordion, recommendations table).
+ *
+ * @param {object} result - The full checkGEO result object.
+ * @returns {string} Complete HTML document string.
+ */
+function generateHTMLReport(result) {
+  const analysis = result.homepage?.analysis;
+  const score = analysis?.overallScore ?? 0;
+  const color = getScoreColor(score);
+  const grade = getGrade(score);
+  const url = `https://${result.domain}`;
+  const circumference = 2 * Math.PI * 34;
+  const offset = circumference - (score / 100) * circumference;
+
+  let origin = "";
+  try {
+    origin = new URL(url).origin;
+  } catch {}
+
+  const STATUS_CLASSES = { pass: "pass", warn: "warn", fail: "fail", info: "info" };
+  const STATUS_ICONS_HTML = { pass: "\u2713", warn: "!", fail: "\u2715", info: "i" };
+
+  function linkifyText(text) {
+    if (!text) return "";
+    let r = escapeHTML(htmlToPlainText(text));
+    r = r.replace(
+      /\b(robots\.txt)\b/gi,
+      `<a href="${origin}/robots.txt" target="_blank" rel="noopener">$1</a>`
+    );
+    r = r.replace(
+      /\b(llms-full\.txt)\b/gi,
+      `<a href="${origin}/llms-full.txt" target="_blank" rel="noopener">$1</a>`
+    );
+    r = r.replace(
+      /\b(llms\.txt)\b/gi,
+      `<a href="${origin}/llms.txt" target="_blank" rel="noopener">$1</a>`
+    );
+    r = r.replace(
+      /\b(sitemap\.xml)\b/gi,
+      `<a href="${origin}/sitemap.xml" target="_blank" rel="noopener">$1</a>`
+    );
+    r = r.replace(
+      /(\/?\.well-known\/ucp)\b/g,
+      `<a href="${origin}/.well-known/ucp" target="_blank" rel="noopener">$1</a>`
+    );
+    return r;
+  }
+
+  // Build categories HTML
+  const categories = analysis?.categories || [];
+  let categoriesHTML = "";
+  categories.forEach((cat, idx) => {
+    const catColor = getScoreColor(cat.score);
+    const icon = CATEGORY_ICONS[cat.category] || "\u{1F4CB}";
+
+    let checksHTML = "";
+    for (const check of cat.checks || []) {
+      const statusIcon = STATUS_ICONS_HTML[check.status] || "\u2022";
+      let foundHTML = "";
+      if (check.found && check.found.length > 0) {
+        foundHTML = `<ul class="check-found">${check.found.map((item) => `<li>${linkifyText(item)}</li>`).join("")}</ul>`;
+      }
+      checksHTML += `
+        <div class="check-item">
+          <div class="check-status ${STATUS_CLASSES[check.status] || ""}">${statusIcon}</div>
+          <div class="check-content">
+            <div class="check-label">${linkifyText(check.label)}</div>
+            ${check.detail ? `<div class="check-detail">${linkifyText(check.detail)}</div>` : ""}
+            ${foundHTML}
+          </div>
+        </div>`;
+    }
+
+    categoriesHTML += `
+      <div class="category" data-idx="${idx}">
+        <div class="category-header" onclick="this.parentElement.classList.toggle('open')">
+          <span class="category-icon">${icon}</span>
+          <span class="category-name">${escapeHTML(cat.category)}</span>
+          <span class="category-score" style="color: ${catColor}">${cat.score}</span>
+          <div class="category-bar">
+            <div class="category-bar-fill" style="width: ${cat.score}%; background: ${catColor};"></div>
+          </div>
+          <span class="category-chevron">\u203A</span>
+        </div>
+        <div class="category-details">
+          ${checksHTML}
+        </div>
+      </div>`;
+  });
+
+  // Build recommendations
+  const recommendations = [];
+  for (const cat of categories) {
+    for (const check of cat.checks || []) {
+      if (check.status === "fail" || check.status === "warn") {
+        recommendations.push({
+          category: cat.category,
+          status: check.status,
+          label: htmlToPlainText(check.label),
+          detail: check.detail ? htmlToPlainText(check.detail) : null,
+        });
+      }
+    }
+  }
+
+  let recommendationsHTML = "";
+  if (recommendations.length > 0) {
+    const failCount = recommendations.filter((r) => r.status === "fail").length;
+    const warnCount = recommendations.filter((r) => r.status === "warn").length;
+
+    const recommendationsText = recommendations
+      .map((rec) => {
+        const isLow = LOW_PRIORITY_CATEGORIES.includes(rec.category);
+        const priority = isLow ? "[LOW]" : rec.status === "fail" ? "[HIGH]" : "[MEDIUM]";
+        const detail = rec.detail ? ` - ${rec.detail}` : "";
+        return `${priority} ${rec.category}: ${rec.label}${detail}`;
+      })
+      .join("\n");
+
+    const rowsHTML = recommendations
+      .map((rec) => {
+        const isLow = LOW_PRIORITY_CATEGORIES.includes(rec.category);
+        const priorityClass = isLow ? "low" : rec.status;
+        const priorityLabel = isLow ? "Low" : rec.status === "fail" ? "High" : "Medium";
+        return `
+            <tr class="${priorityClass}">
+              <td><span class="priority-badge ${priorityClass}">${priorityLabel}</span></td>
+              <td>${escapeHTML(rec.category)}</td>
+              <td>${linkifyText(rec.label)}</td>
+              <td>${rec.detail ? linkifyText(rec.detail) : "-"}</td>
+            </tr>`;
+      })
+      .join("");
+
+    recommendationsHTML = `
+    <div class="recommendations">
+      <div class="recommendations-header">
+        <div>
+          <h2>Recommended Changes</h2>
+          <p class="recommendations-summary">${failCount} critical issue${failCount !== 1 ? "s" : ""}, ${warnCount} warning${warnCount !== 1 ? "s" : ""}</p>
+        </div>
+        <button class="copy-btn" onclick="copyRecommendations(this)" data-text="${escapeHTML(recommendationsText).replace(/"/g, "&quot;")}">
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+          </svg>
+          Copy
+        </button>
+      </div>
+      <table class="recommendations-table">
+        <thead>
+          <tr><th>Priority</th><th>Category</th><th>Issue</th><th>Recommendation</th></tr>
+        </thead>
+        <tbody>${rowsHTML}</tbody>
+      </table>
+    </div>`;
+  } else {
+    recommendationsHTML = `
+    <div class="recommendations success">
+      <h2>\u2713 No Issues Found</h2>
+      <p>Great job! This page passes all checks.</p>
+    </div>`;
+  }
+
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Glippy Report - ${escapeHTML(result.domain)}</title>
+  <style>
+    :root {
+      --bg-primary: #181b24;
+      --bg-secondary: #1e222d;
+      --bg-tertiary: #252a37;
+      --text-primary: #e4e6eb;
+      --text-secondary: #b0b3b8;
+      --text-muted: #6b7280;
+      --accent-purple: #a78bfa;
+      --accent-green: #34d399;
+      --status-pass: #34d399;
+      --status-warn: #fbbf24;
+      --status-fail: #f87171;
+      --status-info: #60a5fa;
+      --border-color: #2d3341;
+    }
+    [data-theme="light"] {
+      --bg-primary: #f8f9fc;
+      --bg-secondary: #ffffff;
+      --bg-tertiary: #f0f2f5;
+      --text-primary: #1a1d26;
+      --text-secondary: #5a5f70;
+      --text-muted: #8a8f9f;
+      --accent-purple: #7c3aed;
+      --accent-green: #16a34a;
+      --status-pass: #16a34a;
+      --status-warn: #ca8a04;
+      --status-fail: #dc2626;
+      --status-info: #2563eb;
+      --border-color: #dce0e8;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: var(--bg-primary);
+      color: var(--text-primary);
+      line-height: 1.5;
+      padding: 24px;
+      max-width: 800px;
+      margin: 0 auto;
+    }
+    @media (min-width: 1200px) { body { max-width: 1400px; } }
+    .header {
+      text-align: center;
+      margin-bottom: 24px;
+      padding-bottom: 16px;
+      border-bottom: 1px solid var(--border-color);
+      position: relative;
+    }
+    .header h1 {
+      font-size: 24px;
+      font-weight: 600;
+      background: linear-gradient(135deg, var(--accent-purple), var(--accent-green));
+      -webkit-background-clip: text;
+      -webkit-text-fill-color: transparent;
+      background-clip: text;
+    }
+    .header .meta { color: var(--text-muted); font-size: 13px; margin-top: 8px; }
+    .header .url { color: var(--text-secondary); font-size: 14px; word-break: break-all; margin-top: 4px; }
+    .theme-toggle {
+      position: absolute; top: 0; right: 0;
+      width: 36px; height: 36px;
+      border: 1px solid var(--border-color);
+      border-radius: 8px;
+      background: var(--bg-secondary);
+      color: var(--text-secondary);
+      cursor: pointer;
+      display: flex; align-items: center; justify-content: center;
+      transition: all 0.2s;
+    }
+    .theme-toggle:hover { background: var(--bg-tertiary); border-color: var(--accent-purple); color: var(--accent-purple); }
+    .theme-toggle svg { width: 18px; height: 18px; }
+    .theme-toggle .icon-sun { display: none; }
+    .theme-toggle .icon-moon { display: none; }
+    [data-theme="dark"] .theme-toggle .icon-sun { display: block; }
+    [data-theme="light"] .theme-toggle .icon-moon { display: block; }
+    .score-section {
+      display: flex; align-items: center; gap: 20px;
+      background: var(--bg-secondary);
+      border-radius: 12px; padding: 20px; margin-bottom: 20px;
+    }
+    .score-ring { position: relative; width: 100px; height: 100px; flex-shrink: 0; }
+    .score-ring svg { width: 100%; height: 100%; transform: rotate(-90deg); }
+    .score-ring-bg { fill: none; stroke: var(--bg-tertiary); stroke-width: 6; }
+    .score-ring-fill { fill: none; stroke-width: 6; stroke-linecap: round; transition: stroke-dashoffset 0.5s ease; }
+    .score-text { position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%); font-size: 28px; font-weight: 700; }
+    .score-meta { flex: 1; }
+    .score-grade { font-size: 20px; font-weight: 600; }
+    .score-summary { color: var(--text-secondary); font-size: 14px; }
+    .main-content { display: flex; flex-direction: column; gap: 24px; }
+    @media (min-width: 1200px) {
+      .main-content { flex-direction: row; align-items: flex-start; }
+      .main-content > .categories { flex: 1; min-width: 0; }
+      .main-content > .recommendations { flex: 1; min-width: 0; margin-top: 0; position: sticky; top: 24px; max-height: calc(100vh - 48px); overflow-y: auto; }
+    }
+    .categories { display: flex; flex-direction: column; gap: 8px; }
+    .category { background: var(--bg-secondary); border-radius: 10px; overflow: hidden; }
+    .category-header { display: flex; align-items: center; gap: 10px; padding: 14px 16px; cursor: pointer; user-select: none; transition: background 0.15s; }
+    .category-header:hover { background: var(--bg-tertiary); }
+    .category-icon { font-size: 18px; }
+    .category-name { font-weight: 500; font-size: 14px; flex: 1; }
+    .category-score { font-weight: 600; font-size: 14px; min-width: 28px; text-align: right; }
+    .category-bar { width: 60px; height: 6px; background: var(--bg-tertiary); border-radius: 3px; overflow: hidden; }
+    .category-bar-fill { height: 100%; border-radius: 3px; transition: width 0.3s ease; }
+    .category-chevron { color: var(--text-muted); font-size: 16px; transition: transform 0.2s; }
+    .category.open .category-chevron { transform: rotate(90deg); }
+    .category-details { display: none; padding: 0 16px 14px 16px; border-top: 1px solid var(--border-color); }
+    .category.open .category-details { display: block; }
+    .check-item { display: flex; gap: 10px; padding: 10px 0; border-bottom: 1px solid var(--border-color); }
+    .check-item:last-child { border-bottom: none; }
+    .check-status { width: 20px; height: 20px; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 11px; font-weight: 700; flex-shrink: 0; }
+    .check-status.pass { background: rgba(52,211,153,0.15); color: var(--status-pass); }
+    .check-status.warn { background: rgba(251,191,36,0.15); color: var(--status-warn); }
+    .check-status.fail { background: rgba(248,113,113,0.15); color: var(--status-fail); }
+    .check-status.info { background: rgba(96,165,250,0.15); color: var(--status-info); }
+    .check-content { flex: 1; min-width: 0; }
+    .check-label { font-size: 13px; font-weight: 500; color: var(--text-primary); }
+    .check-detail { font-size: 12px; color: var(--text-muted); margin-top: 2px; }
+    .check-found { margin-top: 6px; padding-left: 16px; font-size: 12px; color: var(--text-secondary); }
+    .check-found li { margin: 2px 0; }
+    .footer { margin-top: 24px; padding-top: 16px; border-top: 1px solid var(--border-color); text-align: center; color: var(--text-muted); font-size: 12px; }
+    .footer a { color: var(--accent-purple); text-decoration: none; }
+    .footer a:hover { text-decoration: underline; }
+    .recommendations { margin-top: 24px; background: var(--bg-secondary); border-radius: 12px; padding: 20px; }
+    .recommendations-header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 16px; }
+    .recommendations h2 { font-size: 18px; font-weight: 600; margin-bottom: 4px; color: var(--text-primary); }
+    .copy-btn { display: flex; align-items: center; gap: 6px; padding: 8px 12px; background: var(--bg-tertiary); border: 1px solid var(--border-color); border-radius: 6px; color: var(--text-secondary); font-size: 13px; cursor: pointer; transition: all 0.15s; }
+    .copy-btn:hover { background: var(--bg-primary); color: var(--text-primary); border-color: var(--accent-purple); }
+    .copy-btn.copied { background: rgba(52,211,153,0.15); border-color: var(--status-pass); color: var(--status-pass); }
+    .recommendations.success { text-align: center; color: var(--status-pass); }
+    .recommendations.success p { color: var(--text-secondary); }
+    .recommendations-summary { color: var(--text-muted); font-size: 13px; margin-bottom: 16px; }
+    .recommendations-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    .recommendations-table th, .recommendations-table td { padding: 10px 12px; text-align: left; border-bottom: 1px solid var(--border-color); }
+    .recommendations-table th { font-weight: 600; color: var(--text-muted); font-size: 11px; text-transform: uppercase; letter-spacing: 0.5px; }
+    .recommendations-table tr.fail { background: rgba(248,113,113,0.05); }
+    .recommendations-table tr.warn { background: rgba(251,191,36,0.03); }
+    .recommendations-table tr.low { background: rgba(148,163,184,0.03); }
+    .priority-badge { display: inline-block; padding: 3px 8px; border-radius: 4px; font-size: 11px; font-weight: 600; }
+    .priority-badge.fail { background: rgba(248,113,113,0.15); color: var(--status-fail); }
+    .priority-badge.warn { background: rgba(251,191,36,0.15); color: var(--status-warn); }
+    .priority-badge.low { background: rgba(148,163,184,0.15); color: var(--text-muted); }
+    .recommendations-table a, .check-content a { color: var(--accent-purple); text-decoration: none; }
+    .recommendations-table a:hover, .check-content a:hover { text-decoration: underline; }
+    @media print {
+      :root { --bg-primary:#fff;--bg-secondary:#fff;--bg-tertiary:#f5f5f5;--text-primary:#1a1a1a;--text-secondary:#4a4a4a;--text-muted:#6a6a6a;--border-color:#e0e0e0; }
+      body { background: white; color: #1a1a1a; }
+      .category-details { display: block !important; }
+      .category-header { cursor: default; }
+      .category-header:hover { background: transparent; }
+      .theme-toggle, .copy-btn { display: none; }
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <button class="theme-toggle" onclick="toggleTheme()" title="Toggle light/dark mode">
+      <svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <circle cx="12" cy="12" r="5"/>
+        <line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/>
+        <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/>
+        <line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/>
+        <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/>
+      </svg>
+      <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+      </svg>
+    </button>
+    <h1>Glippy GEO Agent-Readiness Report</h1>
+    <div class="url">${escapeHTML(url)}</div>
+    <div class="meta">Generated ${escapeHTML(result.timestamp)}</div>
+  </div>
+
+  <div class="score-section">
+    <div class="score-ring">
+      <svg viewBox="0 0 80 80">
+        <circle class="score-ring-bg" cx="40" cy="40" r="34"/>
+        <circle class="score-ring-fill" cx="40" cy="40" r="34"
+          stroke="${color}"
+          stroke-dasharray="${circumference}"
+          stroke-dashoffset="${offset}"/>
+      </svg>
+      <div class="score-text" style="color: ${color}">${score}</div>
+    </div>
+    <div class="score-meta">
+      <div class="score-grade" style="color: ${color}">Grade: ${escapeHTML(grade.letter)}</div>
+      <div class="score-summary">${escapeHTML(grade.label)}</div>
+    </div>
+  </div>
+
+  <div class="main-content">
+    <div class="categories">${categoriesHTML}</div>
+    ${recommendationsHTML}
+  </div>
+
+  <div class="footer">
+    Generated by <a href="https://www.glippy.dev" target="_blank" rel="noopener">Glippy</a> — GEO Agent-Readiness Checker
+  </div>
+  <script>
+    function copyRecommendations(btn) {
+      const text = btn.dataset.text;
+      navigator.clipboard.writeText(text).then(() => {
+        const orig = btn.innerHTML;
+        btn.innerHTML = '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"></polyline></svg> Copied!';
+        btn.classList.add('copied');
+        setTimeout(() => { btn.innerHTML = orig; btn.classList.remove('copied'); }, 2000);
+      });
+    }
+    function toggleTheme() {
+      const html = document.documentElement;
+      const cur = html.getAttribute('data-theme');
+      const next = cur === 'dark' ? 'light' : 'dark';
+      html.setAttribute('data-theme', next);
+      localStorage.setItem('glippy-report-theme', next);
+    }
+    (function() {
+      const saved = localStorage.getItem('glippy-report-theme');
+      if (saved) { document.documentElement.setAttribute('data-theme', saved); }
+      else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches) {
+        document.documentElement.setAttribute('data-theme', 'light');
+      }
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Bulk report generators (multi-domain comparison & multi-URL/sitemap)
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalised entry for a single domain in a comparison report.
+ * Built from the raw checkGEO result by the export_bulk_report handler.
+ *
+ * @typedef {object} DomainEntry
+ * @property {string}   domain
+ * @property {number|null} score
+ * @property {string}   grade
+ * @property {object[]} categories
+ * @property {boolean}  robotsTxt
+ * @property {boolean}  llmsTxt
+ * @property {boolean}  sitemap
+ * @property {string[]} blockedCrawlers
+ * @property {string|null} error
+ */
+
+/**
+ * Generate a Markdown report for a multi-domain comparison.
+ *
+ * @param {DomainEntry[]} entries
+ * @returns {string}
+ */
+function generateComparisonMarkdownReport(entries) {
+  const scored = entries.filter((e) => !e.error && e.score !== null);
+  const ranked = [...scored].sort((a, b) => b.score - a.score);
+  const errored = entries.filter((e) => e.error);
+
+  let md = `# Glippy GEO Bulk Comparison Report\n\n`;
+  md += `**Domains analysed:** ${entries.length}\n`;
+  md += `**Date:** ${new Date().toISOString()}\n`;
+  if (scored.length > 0) {
+    const avg = Math.round(scored.reduce((s, e) => s + e.score, 0) / scored.length);
+    md += `**Average score:** ${avg}/100 (${getGrade(avg).letter})\n`;
+  }
+  md += `\n---\n\n`;
+
+  // Rankings
+  md += `## Rankings\n\n`;
+  for (let i = 0; i < ranked.length; i++) {
+    const e = ranked[i];
+    const g = getGrade(e.score);
+    md += `${i + 1}. **${e.domain}** — ${e.score}/100 (${g.letter})\n`;
+  }
+  if (errored.length > 0) {
+    md += `\n`;
+    for (const e of errored) {
+      md += `- **${e.domain}** — Error: ${e.error}\n`;
+    }
+  }
+  md += `\n`;
+
+  // Category comparison table
+  if (scored.length >= 2) {
+    const catNames = [
+      ...new Set(scored.flatMap((e) => e.categories.map((c) => c.category))),
+    ];
+    md += `## Category Comparison\n\n`;
+    md += `| Category | ${scored.map((e) => e.domain).join(" | ")} |\n`;
+    md += `|---|${scored.map(() => "---").join("|")}|\n`;
+    for (const catName of catNames) {
+      const scores = scored.map((e) => {
+        const cat = e.categories.find((c) => c.category === catName);
+        return cat ? `${cat.score}%` : "\u2014";
+      });
+      md += `| ${catName} | ${scores.join(" | ")} |\n`;
+    }
+    md += `| **Overall** | ${scored.map((e) => `**${e.score}%**`).join(" | ")} |\n`;
+    md += `\n`;
+  }
+
+  // Quick facts
+  md += `## Quick Facts\n\n`;
+  md += `| | ${scored.map((e) => e.domain).join(" | ")} |\n`;
+  md += `|---|${scored.map(() => "---").join("|")}|\n`;
+  md += `| robots.txt | ${scored.map((e) => (e.robotsTxt ? "Yes" : "No")).join(" | ")} |\n`;
+  md += `| llms.txt | ${scored.map((e) => (e.llmsTxt ? "Yes" : "No")).join(" | ")} |\n`;
+  md += `| Sitemap | ${scored.map((e) => (e.sitemap ? "Yes" : "No")).join(" | ")} |\n`;
+  md += `| AI crawlers blocked | ${scored.map((e) => (e.blockedCrawlers.length > 0 ? e.blockedCrawlers.join(", ") : "None")).join(" | ")} |\n`;
+  md += `\n`;
+
+  // Per-domain recommendations
+  md += `## Recommendations by Domain\n\n`;
+  for (const entry of scored) {
+    const recommendations = [];
+    for (const cat of entry.categories) {
+      for (const check of cat.checks || []) {
+        if (check.status === "fail" || check.status === "warn") {
+          const isLow = LOW_PRIORITY_CATEGORIES.includes(cat.category);
+          const priority = isLow ? "Low" : check.status === "fail" ? "High" : "Medium";
+          recommendations.push({
+            priority,
+            category: cat.category,
+            label: htmlToPlainText(check.label),
+            detail: check.detail ? htmlToPlainText(check.detail) : null,
+          });
+        }
+      }
+    }
+    const g = getGrade(entry.score);
+    md += `### ${entry.domain} (${entry.score}% \u2014 ${g.letter})\n\n`;
+    if (recommendations.length === 0) {
+      md += `\u2705 No issues found.\n\n`;
+    } else {
+      for (const rec of recommendations) {
+        const badge = rec.priority === "High" ? "\u{1F534}" : rec.priority === "Medium" ? "\u{1F7E1}" : "\u{1F535}";
+        md += `- ${badge} **${rec.category}:** ${rec.label}`;
+        if (rec.detail) md += `\n  - ${rec.detail}`;
+        md += `\n`;
+      }
+      md += `\n`;
+    }
+  }
+
+  md += `---\n\n`;
+  md += `*Generated by [Glippy](https://www.glippy.dev) \u2014 GEO Agent-Readiness Checker*\n`;
+  return md;
+}
+
+/**
+ * Generate a Markdown report for multi-URL / sitemap analysis.
+ *
+ * @param {string} title - Report title (e.g. sitemap URL or "URL Analysis").
+ * @param {object[]} pageResults - Per-URL analysis results from analyseUrls.
+ * @param {object} aggregated - Output of aggregatePageScores.
+ * @returns {string}
+ */
+function generateUrlsMarkdownReport(title, pageResults, aggregated) {
+  let md = `# Glippy GEO Bulk URL Report\n\n`;
+  md += `**Source:** ${title}\n`;
+  md += `**Date:** ${new Date().toISOString()}\n`;
+  md += `**Pages analysed:** ${aggregated.pagesAnalysed}\n`;
+  if (aggregated.pagesFailed > 0) {
+    md += `**Pages failed:** ${aggregated.pagesFailed}\n`;
+  }
+  if (aggregated.pagesAnalysed > 0) {
+    md += `**Average score:** ${aggregated.averageScore}/100 (${getGrade(aggregated.averageScore).letter})\n`;
+  }
+  md += `\n---\n\n`;
+
+  // Per-page results table
+  md += `## Per-Page Results\n\n`;
+  md += `| URL | Score | Grade | Page Type |\n`;
+  md += `|-----|-------|-------|----------|\n`;
+  for (const page of pageResults) {
+    if (page.error) {
+      md += `| ${page.url} | \u2014 | \u2014 | Error: ${page.error} |\n`;
+    } else {
+      const score = page.analysis?.overallScore ?? 0;
+      md += `| ${page.url} | ${score}% | ${scoreToGrade(score)} | ${page.analysis?.pageType || "unknown"} |\n`;
+    }
+  }
+  md += `\n`;
+
+  // Category averages
+  if (aggregated.categoryAverages && Object.keys(aggregated.categoryAverages).length > 0) {
+    md += `## Category Averages\n\n`;
+    const sorted = Object.entries(aggregated.categoryAverages).sort((a, b) => b[1] - a[1]);
+    for (const [cat, avg] of sorted) {
+      const icon = CATEGORY_ICONS[cat] || "\u{1F4CB}";
+      md += `- ${icon} **${cat}:** ${avg}% (${scoreToGrade(avg)})\n`;
+    }
+    md += `\n`;
+  }
+
+  // Weakest pages
+  const scored = pageResults
+    .filter((p) => !p.error && p.analysis?.overallScore != null)
+    .sort((a, b) => a.analysis.overallScore - b.analysis.overallScore);
+
+  if (scored.length > 2) {
+    md += `## Weakest Pages\n\n`;
+    for (const p of scored.slice(0, 5)) {
+      const fails = (p.analysis.categories || [])
+        .filter((c) => c.score < 50)
+        .map((c) => c.category);
+      md += `- **${p.url}:** ${p.analysis.overallScore}%`;
+      if (fails.length > 0) md += ` \u2014 weak in: ${fails.join(", ")}`;
+      md += `\n`;
+    }
+    md += `\n`;
+  }
+
+  // Strongest pages
+  if (scored.length > 2) {
+    md += `## Strongest Pages\n\n`;
+    const strongest = [...scored].reverse();
+    for (const p of strongest.slice(0, 5)) {
+      md += `- **${p.url}:** ${p.analysis.overallScore}% (${scoreToGrade(p.analysis.overallScore)})\n`;
+    }
+    md += `\n`;
+  }
+
+  // Common issues across pages
+  const issueCounts = new Map(); // "category: label" → count
+  for (const page of pageResults) {
+    if (page.error || !page.analysis?.categories) continue;
+    for (const cat of page.analysis.categories) {
+      for (const check of cat.checks || []) {
+        if (check.status === "fail" || check.status === "warn") {
+          const key = `${cat.category}: ${htmlToPlainText(check.label)}`;
+          issueCounts.set(key, (issueCounts.get(key) || 0) + 1);
+        }
+      }
+    }
+  }
+  const commonIssues = [...issueCounts.entries()]
+    .filter(([, count]) => count > 1)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+
+  if (commonIssues.length > 0) {
+    md += `## Most Common Issues\n\n`;
+    for (const [issue, count] of commonIssues) {
+      md += `- **${issue}** \u2014 affects ${count}/${aggregated.pagesAnalysed} pages\n`;
+    }
+    md += `\n`;
+  }
+
+  md += `---\n\n`;
+  md += `*Generated by [Glippy](https://www.glippy.dev) \u2014 GEO Agent-Readiness Checker*\n`;
+  return md;
+}
+
+/**
+ * Generate a standalone HTML report for a multi-domain comparison.
+ *
+ * @param {DomainEntry[]} entries
+ * @returns {string}
+ */
+function generateComparisonHTMLReport(entries) {
+  const scored = entries.filter((e) => !e.error && e.score !== null);
+  const ranked = [...scored].sort((a, b) => b.score - a.score);
+  const errored = entries.filter((e) => e.error);
+  const avgScore = scored.length > 0
+    ? Math.round(scored.reduce((s, e) => s + e.score, 0) / scored.length)
+    : 0;
+  const avgGrade = getGrade(avgScore);
+  const timestamp = new Date().toISOString();
+
+  // Build ranking rows
+  const rankingRows = ranked
+    .map((e, i) => {
+      const color = getScoreColor(e.score);
+      const g = getGrade(e.score);
+      return `<tr>
+        <td class="rank">${i + 1}</td>
+        <td class="domain">${escapeHTML(e.domain)}</td>
+        <td><span class="score-badge" style="background: ${color}20; color: ${color};">${e.score}%</span></td>
+        <td><span class="grade-badge" style="color: ${color};">${g.letter}</span></td>
+        <td>${e.robotsTxt ? '<span class="badge yes">Yes</span>' : '<span class="badge no">No</span>'}</td>
+        <td>${e.llmsTxt ? '<span class="badge yes">Yes</span>' : '<span class="badge no">No</span>'}</td>
+        <td>${e.sitemap ? '<span class="badge yes">Yes</span>' : '<span class="badge no">No</span>'}</td>
+        <td>${e.blockedCrawlers.length > 0 ? escapeHTML(e.blockedCrawlers.join(", ")) : '<span style="color:var(--status-pass)">None</span>'}</td>
+      </tr>`;
+    })
+    .join("");
+
+  const errorRows = errored
+    .map(
+      (e) =>
+        `<tr class="error-row"><td>\u2014</td><td class="domain">${escapeHTML(e.domain)}</td><td colspan="6" class="error-msg">Error: ${escapeHTML(e.error)}</td></tr>`
+    )
+    .join("");
+
+  // Category comparison table (if 2+ scored domains)
+  let categoryHTML = "";
+  if (scored.length >= 2) {
+    const catNames = [
+      ...new Set(scored.flatMap((e) => e.categories.map((c) => c.category))),
+    ];
+    const catHeaderCells = scored
+      .map((e) => `<th>${escapeHTML(e.domain)}</th>`)
+      .join("");
+    const catRows = catNames
+      .map((catName) => {
+        const icon = CATEGORY_ICONS[catName] || "\u{1F4CB}";
+        const cells = scored
+          .map((e) => {
+            const cat = e.categories.find((c) => c.category === catName);
+            if (!cat) return `<td>\u2014</td>`;
+            const c = getScoreColor(cat.score);
+            return `<td><span class="score-badge" style="background:${c}20;color:${c};">${cat.score}%</span></td>`;
+          })
+          .join("");
+        return `<tr><td>${icon} ${escapeHTML(catName)}</td>${cells}</tr>`;
+      })
+      .join("");
+
+    categoryHTML = `
+    <div class="section">
+      <h2>Category Comparison</h2>
+      <div class="table-wrap">
+        <table class="data-table">
+          <thead><tr><th>Category</th>${catHeaderCells}</tr></thead>
+          <tbody>${catRows}</tbody>
+        </table>
+      </div>
+    </div>`;
+  }
+
+  // Per-domain recommendations
+  let recsHTML = "";
+  for (const entry of scored) {
+    const recs = [];
+    for (const cat of entry.categories) {
+      for (const check of cat.checks || []) {
+        if (check.status === "fail" || check.status === "warn") {
+          const isLow = LOW_PRIORITY_CATEGORIES.includes(cat.category);
+          recs.push({
+            priority: isLow ? "low" : check.status,
+            priorityLabel: isLow ? "Low" : check.status === "fail" ? "High" : "Medium",
+            category: cat.category,
+            label: htmlToPlainText(check.label),
+            detail: check.detail ? htmlToPlainText(check.detail) : null,
+          });
+        }
+      }
+    }
+    const g = getGrade(entry.score);
+    const color = getScoreColor(entry.score);
+    let recRows = "";
+    if (recs.length === 0) {
+      recRows = `<tr><td colspan="4" class="no-issues">\u2713 No issues found</td></tr>`;
+    } else {
+      recRows = recs
+        .map(
+          (r) =>
+            `<tr class="${r.priority}"><td><span class="priority-badge ${r.priority}">${r.priorityLabel}</span></td><td>${escapeHTML(r.category)}</td><td>${escapeHTML(r.label)}</td><td>${r.detail ? escapeHTML(r.detail) : "\u2014"}</td></tr>`
+        )
+        .join("");
+    }
+    recsHTML += `
+    <div class="domain-recs">
+      <h3><span class="score-badge" style="background:${color}20;color:${color};">${entry.score}% ${g.letter}</span> ${escapeHTML(entry.domain)}</h3>
+      <table class="recommendations-table">
+        <thead><tr><th>Priority</th><th>Category</th><th>Issue</th><th>Recommendation</th></tr></thead>
+        <tbody>${recRows}</tbody>
+      </table>
+    </div>`;
+  }
+
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Glippy Bulk Comparison Report</title>
+  <style>
+    ${bulkHTMLStyles()}
+  </style>
+</head>
+<body>
+  <div class="header">
+    <button class="theme-toggle" onclick="toggleTheme()" title="Toggle light/dark mode">
+      ${themeToggleSVG()}
+    </button>
+    <h1>Glippy GEO Bulk Comparison Report</h1>
+    <div class="meta">${entries.length} domains analysed \u2022 Generated ${escapeHTML(timestamp)}</div>
+  </div>
+
+  <div class="summary-cards">
+    <div class="card">
+      <div class="card-label">Domains</div>
+      <div class="card-value">${entries.length}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Average Score</div>
+      <div class="card-value" style="color:${getScoreColor(avgScore)}">${avgScore}%</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Average Grade</div>
+      <div class="card-value" style="color:${getScoreColor(avgScore)}">${avgGrade.letter}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Failed</div>
+      <div class="card-value">${errored.length}</div>
+    </div>
+  </div>
+
+  <div class="section">
+    <h2>Rankings</h2>
+    <div class="table-wrap">
+      <table class="data-table">
+        <thead>
+          <tr><th>#</th><th>Domain</th><th>Score</th><th>Grade</th><th>robots.txt</th><th>llms.txt</th><th>Sitemap</th><th>AI Crawlers Blocked</th></tr>
+        </thead>
+        <tbody>${rankingRows}${errorRows}</tbody>
+      </table>
+    </div>
+  </div>
+
+  ${categoryHTML}
+
+  <div class="section">
+    <h2>Recommendations by Domain</h2>
+    ${recsHTML}
+  </div>
+
+  <div class="footer">
+    Generated by <a href="https://www.glippy.dev" target="_blank" rel="noopener">Glippy</a> \u2014 GEO Agent-Readiness Checker
+  </div>
+  <script>
+    ${bulkHTMLScript()}
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * Generate a standalone HTML report for multi-URL / sitemap analysis.
+ *
+ * @param {string} title
+ * @param {object[]} pageResults
+ * @param {object} aggregated
+ * @returns {string}
+ */
+function generateUrlsHTMLReport(title, pageResults, aggregated) {
+  const timestamp = new Date().toISOString();
+  const avgScore = aggregated.averageScore ?? 0;
+
+  // Per-page result rows
+  const scored = pageResults
+    .filter((p) => !p.error && p.analysis?.overallScore != null)
+    .sort((a, b) => b.analysis.overallScore - a.analysis.overallScore);
+  const errored = pageResults.filter((p) => p.error);
+
+  const pageRows = pageResults
+    .map((page) => {
+      if (page.error) {
+        return `<tr class="error-row"><td class="domain">${escapeHTML(page.url)}</td><td>\u2014</td><td>\u2014</td><td>\u2014</td><td class="error-msg">${escapeHTML(page.error)}</td></tr>`;
+      }
+      const s = page.analysis?.overallScore ?? 0;
+      const c = getScoreColor(s);
+      return `<tr>
+        <td class="domain">${escapeHTML(page.url)}</td>
+        <td><span class="score-badge" style="background:${c}20;color:${c};">${s}%</span></td>
+        <td><span class="grade-badge" style="color:${c};">${scoreToGrade(s)}</span></td>
+        <td>${escapeHTML(page.analysis?.pageType || "unknown")}</td>
+        <td>\u2014</td>
+      </tr>`;
+    })
+    .join("");
+
+  // Category averages
+  let categoryAvgHTML = "";
+  if (aggregated.categoryAverages && Object.keys(aggregated.categoryAverages).length > 0) {
+    const sortedCats = Object.entries(aggregated.categoryAverages).sort((a, b) => b[1] - a[1]);
+    const catBars = sortedCats
+      .map(([cat, avg]) => {
+        const icon = CATEGORY_ICONS[cat] || "\u{1F4CB}";
+        const c = getScoreColor(avg);
+        return `<div class="cat-avg-row">
+          <span class="cat-avg-name">${icon} ${escapeHTML(cat)}</span>
+          <div class="cat-avg-bar-wrap">
+            <div class="cat-avg-bar" style="width:${avg}%;background:${c};"></div>
+          </div>
+          <span class="cat-avg-score" style="color:${c};">${avg}%</span>
+        </div>`;
+      })
+      .join("");
+    categoryAvgHTML = `
+    <div class="section">
+      <h2>Category Averages</h2>
+      <div class="cat-avg-container">${catBars}</div>
+    </div>`;
+  }
+
+  // Common issues
+  const issueCounts = new Map();
+  for (const page of pageResults) {
+    if (page.error || !page.analysis?.categories) continue;
+    for (const cat of page.analysis.categories) {
+      for (const check of cat.checks || []) {
+        if (check.status === "fail" || check.status === "warn") {
+          const key = `${cat.category}|||${htmlToPlainText(check.label)}`;
+          issueCounts.set(key, (issueCounts.get(key) || 0) + 1);
+        }
+      }
+    }
+  }
+  const commonIssues = [...issueCounts.entries()]
+    .filter(([, count]) => count > 1)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10);
+
+  let commonIssuesHTML = "";
+  if (commonIssues.length > 0) {
+    const issueRows = commonIssues
+      .map(([key, count]) => {
+        const [category, label] = key.split("|||");
+        const pct = Math.round((count / aggregated.pagesAnalysed) * 100);
+        return `<tr>
+          <td>${escapeHTML(category)}</td>
+          <td>${escapeHTML(label)}</td>
+          <td>${count}/${aggregated.pagesAnalysed}</td>
+          <td><div class="issue-bar-wrap"><div class="issue-bar" style="width:${pct}%;"></div></div></td>
+        </tr>`;
+      })
+      .join("");
+    commonIssuesHTML = `
+    <div class="section">
+      <h2>Most Common Issues</h2>
+      <div class="table-wrap">
+        <table class="data-table">
+          <thead><tr><th>Category</th><th>Issue</th><th>Affected</th><th></th></tr></thead>
+          <tbody>${issueRows}</tbody>
+        </table>
+      </div>
+    </div>`;
+  }
+
+  return `<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Glippy Bulk URL Report</title>
+  <style>
+    ${bulkHTMLStyles()}
+    .cat-avg-container { display: flex; flex-direction: column; gap: 10px; }
+    .cat-avg-row { display: flex; align-items: center; gap: 12px; }
+    .cat-avg-name { font-size: 13px; font-weight: 500; min-width: 220px; }
+    .cat-avg-bar-wrap { flex: 1; height: 8px; background: var(--bg-tertiary); border-radius: 4px; overflow: hidden; }
+    .cat-avg-bar { height: 100%; border-radius: 4px; transition: width 0.3s ease; }
+    .cat-avg-score { font-weight: 600; font-size: 13px; min-width: 45px; text-align: right; }
+    .issue-bar-wrap { width: 80px; height: 6px; background: var(--bg-tertiary); border-radius: 3px; overflow: hidden; }
+    .issue-bar { height: 100%; background: var(--status-fail); border-radius: 3px; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <button class="theme-toggle" onclick="toggleTheme()" title="Toggle light/dark mode">
+      ${themeToggleSVG()}
+    </button>
+    <h1>Glippy GEO Bulk URL Report</h1>
+    <div class="url">${escapeHTML(title)}</div>
+    <div class="meta">Generated ${escapeHTML(timestamp)}</div>
+  </div>
+
+  <div class="summary-cards">
+    <div class="card">
+      <div class="card-label">Pages Analysed</div>
+      <div class="card-value">${aggregated.pagesAnalysed}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Average Score</div>
+      <div class="card-value" style="color:${getScoreColor(avgScore)}">${avgScore}%</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Average Grade</div>
+      <div class="card-value" style="color:${getScoreColor(avgScore)}">${scoreToGrade(avgScore)}</div>
+    </div>
+    <div class="card">
+      <div class="card-label">Failed</div>
+      <div class="card-value">${errored.length}</div>
+    </div>
+  </div>
+
+  <div class="section">
+    <h2>Per-Page Results</h2>
+    <div class="table-wrap">
+      <table class="data-table">
+        <thead><tr><th>URL</th><th>Score</th><th>Grade</th><th>Page Type</th><th></th></tr></thead>
+        <tbody>${pageRows}</tbody>
+      </table>
+    </div>
+  </div>
+
+  ${categoryAvgHTML}
+  ${commonIssuesHTML}
+
+  <div class="footer">
+    Generated by <a href="https://www.glippy.dev" target="_blank" rel="noopener">Glippy</a> \u2014 GEO Agent-Readiness Checker
+  </div>
+  <script>
+    ${bulkHTMLScript()}
+  </script>
+</body>
+</html>`;
+}
+
+/** Shared CSS styles for bulk HTML reports. */
+function bulkHTMLStyles() {
+  return `
+    :root {
+      --bg-primary: #181b24; --bg-secondary: #1e222d; --bg-tertiary: #252a37;
+      --text-primary: #e4e6eb; --text-secondary: #b0b3b8; --text-muted: #6b7280;
+      --accent-purple: #a78bfa; --accent-green: #34d399;
+      --status-pass: #34d399; --status-warn: #fbbf24; --status-fail: #f87171; --status-info: #60a5fa;
+      --border-color: #2d3341;
+    }
+    [data-theme="light"] {
+      --bg-primary: #f8f9fc; --bg-secondary: #ffffff; --bg-tertiary: #f0f2f5;
+      --text-primary: #1a1d26; --text-secondary: #5a5f70; --text-muted: #8a8f9f;
+      --accent-purple: #7c3aed; --accent-green: #16a34a;
+      --status-pass: #16a34a; --status-warn: #ca8a04; --status-fail: #dc2626; --status-info: #2563eb;
+      --border-color: #dce0e8;
+    }
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: var(--bg-primary); color: var(--text-primary); line-height: 1.5; padding: 24px; max-width: 1200px; margin: 0 auto; }
+    .header { text-align: center; margin-bottom: 24px; padding-bottom: 16px; border-bottom: 1px solid var(--border-color); position: relative; }
+    .header h1 { font-size: 24px; font-weight: 600; background: linear-gradient(135deg, var(--accent-purple), var(--accent-green)); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; }
+    .header .meta { color: var(--text-muted); font-size: 13px; margin-top: 8px; }
+    .header .url { color: var(--text-secondary); font-size: 14px; word-break: break-all; margin-top: 4px; }
+    .theme-toggle { position: absolute; top: 0; right: 0; width: 36px; height: 36px; border: 1px solid var(--border-color); border-radius: 8px; background: var(--bg-secondary); color: var(--text-secondary); cursor: pointer; display: flex; align-items: center; justify-content: center; transition: all 0.2s; }
+    .theme-toggle:hover { background: var(--bg-tertiary); border-color: var(--accent-purple); color: var(--accent-purple); }
+    .theme-toggle svg { width: 18px; height: 18px; }
+    .theme-toggle .icon-sun { display: none; } .theme-toggle .icon-moon { display: none; }
+    [data-theme="dark"] .theme-toggle .icon-sun { display: block; }
+    [data-theme="light"] .theme-toggle .icon-moon { display: block; }
+    .summary-cards { display: flex; gap: 16px; margin-bottom: 24px; flex-wrap: wrap; }
+    .card { flex: 1; min-width: 120px; background: var(--bg-secondary); border-radius: 10px; padding: 16px 20px; text-align: center; }
+    .card-label { font-size: 12px; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.5px; margin-bottom: 4px; }
+    .card-value { font-size: 28px; font-weight: 700; }
+    .section { background: var(--bg-secondary); border-radius: 12px; padding: 20px; margin-bottom: 20px; }
+    .section h2 { font-size: 18px; font-weight: 600; margin-bottom: 16px; color: var(--text-primary); }
+    .table-wrap { overflow-x: auto; }
+    .data-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    .data-table th, .data-table td { padding: 10px 12px; text-align: left; border-bottom: 1px solid var(--border-color); }
+    .data-table th { font-weight: 600; color: var(--text-muted); font-size: 11px; text-transform: uppercase; letter-spacing: 0.5px; }
+    .data-table tr:hover { background: var(--bg-tertiary); }
+    .data-table td.domain { font-weight: 500; color: var(--accent-purple); max-width: 300px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .data-table td.rank { font-weight: 700; color: var(--text-muted); width: 40px; }
+    .data-table td.error-msg { color: var(--status-fail); }
+    .data-table tr.error-row { opacity: 0.7; }
+    .score-badge { display: inline-block; padding: 3px 8px; border-radius: 4px; font-size: 12px; font-weight: 600; }
+    .grade-badge { font-weight: 700; font-size: 14px; }
+    .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 11px; font-weight: 600; }
+    .badge.yes { background: rgba(52,211,153,0.15); color: var(--status-pass); }
+    .badge.no { background: rgba(248,113,113,0.15); color: var(--status-fail); }
+    .domain-recs { margin-bottom: 20px; }
+    .domain-recs h3 { font-size: 15px; font-weight: 600; margin-bottom: 10px; display: flex; align-items: center; gap: 8px; }
+    .recommendations-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    .recommendations-table th, .recommendations-table td { padding: 8px 10px; text-align: left; border-bottom: 1px solid var(--border-color); }
+    .recommendations-table th { font-weight: 600; color: var(--text-muted); font-size: 11px; text-transform: uppercase; }
+    .recommendations-table tr.fail { background: rgba(248,113,113,0.05); }
+    .recommendations-table tr.warn { background: rgba(251,191,36,0.03); }
+    .recommendations-table tr.low { background: rgba(148,163,184,0.03); }
+    .recommendations-table td.no-issues { text-align: center; color: var(--status-pass); font-weight: 500; padding: 16px; }
+    .priority-badge { display: inline-block; padding: 3px 8px; border-radius: 4px; font-size: 11px; font-weight: 600; }
+    .priority-badge.fail { background: rgba(248,113,113,0.15); color: var(--status-fail); }
+    .priority-badge.warn { background: rgba(251,191,36,0.15); color: var(--status-warn); }
+    .priority-badge.low { background: rgba(148,163,184,0.15); color: var(--text-muted); }
+    .footer { margin-top: 24px; padding-top: 16px; border-top: 1px solid var(--border-color); text-align: center; color: var(--text-muted); font-size: 12px; }
+    .footer a { color: var(--accent-purple); text-decoration: none; }
+    .footer a:hover { text-decoration: underline; }
+    @media print {
+      :root { --bg-primary:#fff;--bg-secondary:#fff;--bg-tertiary:#f5f5f5;--text-primary:#1a1a1a;--text-secondary:#4a4a4a;--text-muted:#6a6a6a;--border-color:#e0e0e0; }
+      body { background: white; color: #1a1a1a; }
+      .theme-toggle { display: none; }
+    }`;
+}
+
+/** Shared theme toggle SVG icons. */
+function themeToggleSVG() {
+  return `<svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="12" cy="12" r="5"/>
+    <line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/>
+    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/>
+    <line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/>
+    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/>
+  </svg>
+  <svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+  </svg>`;
+}
+
+/** Shared JS for bulk HTML reports. */
+function bulkHTMLScript() {
+  return `
+    function toggleTheme() {
+      var html = document.documentElement;
+      var cur = html.getAttribute('data-theme');
+      var next = cur === 'dark' ? 'light' : 'dark';
+      html.setAttribute('data-theme', next);
+      localStorage.setItem('glippy-report-theme', next);
+    }
+    (function() {
+      var saved = localStorage.getItem('glippy-report-theme');
+      if (saved) { document.documentElement.setAttribute('data-theme', saved); }
+      else if (window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches) {
+        document.documentElement.setAttribute('data-theme', 'light');
+      }
+    })();`;
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+  name: "glippy-geo",
+  version: "0.1.0",
+});
+
+// ---------------------------------------------------------------------------
+// Tool: analyze_domain
+// ---------------------------------------------------------------------------
+server.tool(
+  "analyze_domain",
+  "Run a comprehensive GEO (Generative Engine Optimization) readiness analysis on a domain. " +
+    "Checks robots.txt, llms.txt (note: llms.txt is not currently supported by major AI models — having one cannot hurt but is not a meaningful optimization), " +
+    "homepage HTML (10 scoring categories), sitemap.xml, and security headers. " +
+    "Returns an overall weighted score (0-100) with per-category breakdowns and actionable recommendations. " +
+    "Use output_format='json' to get raw results that can be passed to export_report.",
+  {
+    domain: z
+      .string()
+      .describe(
+        'The domain to analyse, e.g. "example.com". Do not include https:// prefix.'
+      ),
+    max_pages: z
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe(
+        "Maximum pages to crawl (1 = homepage only, up to 10 for multi-page analysis). Defaults to 10."
+      ),
+    output_format: z
+      .enum(["text", "json"])
+      .optional()
+      .describe(
+        'Output format. "text" (default) returns a human-readable report. ' +
+        '"json" returns the raw analysis result object that can be passed to export_report\'s analysis_result parameter.'
+      ),
+  },
+  withLicense(async ({ domain, max_pages, output_format }) => {
+    try {
+      const result = await checkGEO(domain, {
+        maxPages: max_pages ?? 10,
+      });
+
+      if (result.error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error analysing ${domain}: ${result.error}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // JSON output mode - return raw result for use with export_report
+      if (output_format === "json") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      // Build a structured text report
+      const lines = [];
+      lines.push(`# GEO Analysis: ${result.domain}`);
+      lines.push(`Timestamp: ${result.timestamp}`);
+      lines.push("");
+
+      // Overall score
+      const analysis = result.homepage?.analysis;
+      if (analysis) {
+        const grade = scoreToGrade(analysis.overallScore);
+        lines.push(
+          `## Overall GEO Score: ${analysis.overallScore}% (${grade})`
+        );
+        lines.push(`Page type detected: ${analysis.pageType}`);
+        lines.push("");
+
+        // Category breakdown
+        lines.push("## Category Scores");
+        if (analysis.categories) {
+          for (const cat of analysis.categories) {
+            lines.push(formatCategory(cat));
+          }
+        }
+        lines.push("");
+      }
+
+      // robots.txt
+      lines.push("## robots.txt");
+      lines.push(`Exists: ${result.robotsTxt.exists ? "Yes" : "No"}`);
+      if (result.robotsTxt.exists) {
+        lines.push(
+          `Wildcard disallow: ${result.robotsTxt.hasWildcardDisallow ? "Yes" : "No"}`
+        );
+        lines.push("AI Crawler Access:");
+        lines.push(formatCrawlerAccess(result.robotsTxt.blocksCrawlers));
+        if (result.robotsTxt.sitemapReferences.length > 0) {
+          lines.push(
+            `Sitemaps referenced: ${result.robotsTxt.sitemapReferences.join(", ")}`
+          );
+        }
+      }
+      lines.push("");
+
+      // llms.txt
+      lines.push("## llms.txt");
+      lines.push(`Exists: ${result.llmsTxt.exists ? "Yes" : "No"}`);
+      lines.push(
+        "(Note: llms.txt is not currently supported by major AI models or crawlers — having one cannot hurt but is not a meaningful optimization.)"
+      );
+      if (result.llmsTxt.exists && result.llmsTxt.content) {
+        const preview = result.llmsTxt.content.substring(0, 500);
+        lines.push(`Content preview:\n${preview}`);
+      }
+      lines.push("");
+
+      // Sitemap
+      lines.push("## Sitemap");
+      lines.push(`Exists: ${result.sitemap.exists ? "Yes" : "No"}`);
+      lines.push(
+        `Referenced in robots.txt: ${result.sitemap.referencedInRobotsTxt ? "Yes" : "No"}`
+      );
+      if (result.sitemap.urlsDiscovered > 0) {
+        lines.push(`URLs discovered: ${result.sitemap.urlsDiscovered}`);
+      }
+      lines.push("");
+
+      // GEO score breakdown
+      if (result.geoScore) {
+        lines.push("## GEO Score Breakdown");
+        lines.push(
+          `Total: ${result.geoScore.total}/${result.geoScore.maxPossible}`
+        );
+        if (result.geoScore.breakdown) {
+          for (const [key, val] of Object.entries(result.geoScore.breakdown)) {
+            lines.push(`  ${key}: ${val.score}/${val.max} - ${val.detail}`);
+          }
+        }
+      }
+
+      // Multi-page results
+      if (result.multiPageCrawl?.pagesAnalysed > 1) {
+        lines.push("");
+        lines.push("## Multi-Page Analysis");
+        lines.push(
+          `Pages analysed: ${result.multiPageCrawl.pagesAnalysed}`
+        );
+        lines.push(
+          `Average score: ${result.multiPageCrawl.averageScore}%`
+        );
+        if (result.multiPageCrawl.categoryAverages) {
+          lines.push("Category averages:");
+          for (const [cat, avg] of Object.entries(
+            result.multiPageCrawl.categoryAverages
+          )) {
+            lines.push(`  ${cat}: ${avg}%`);
+          }
+        }
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to analyse ${domain}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Tool: check_robots_txt
+// ---------------------------------------------------------------------------
+server.tool(
+  "check_robots_txt",
+  "Check a domain's robots.txt file specifically for AI crawler access rules. " +
+    "Reports which AI crawlers (GPTBot, ClaudeBot, etc.) are blocked or allowed.",
+  {
+    domain: z
+      .string()
+      .describe(
+        'The domain to check, e.g. "example.com". Do not include https:// prefix.'
+      ),
+  },
+  withLicense(async ({ domain }) => {
+    try {
+      const result = await checkGEO(domain, { maxPages: 1 });
+
+      if (result.error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error checking ${domain}: ${result.error}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const lines = [];
+      lines.push(`# robots.txt Analysis: ${result.domain}`);
+      lines.push("");
+      lines.push(`URL: ${result.robotsTxt.url}`);
+      lines.push(`Exists: ${result.robotsTxt.exists ? "Yes" : "No"}`);
+
+      if (!result.robotsTxt.exists) {
+        lines.push("");
+        lines.push(
+          "No robots.txt found. This means all crawlers have unrestricted access."
+        );
+        lines.push(
+          "Consider adding a robots.txt to explicitly manage crawler access."
+        );
+      } else {
+        lines.push(
+          `Wildcard disallow (Disallow: /): ${result.robotsTxt.hasWildcardDisallow ? "Yes - blocks all bots by default" : "No"}`
+        );
+        lines.push("");
+        lines.push("## AI Crawler Access");
+        lines.push(formatCrawlerAccess(result.robotsTxt.blocksCrawlers));
+
+        const blockedCount = Object.values(
+          result.robotsTxt.blocksCrawlers
+        ).filter(Boolean).length;
+        const totalCrawlers = Object.keys(
+          result.robotsTxt.blocksCrawlers
+        ).length;
+        lines.push("");
+        lines.push(
+          `Summary: ${blockedCount}/${totalCrawlers} AI crawlers are blocked.`
+        );
+
+        if (blockedCount > 0) {
+          lines.push(
+            "Blocked crawlers cannot index this site's content for AI features."
+          );
+        }
+
+        if (result.robotsTxt.sitemapReferences.length > 0) {
+          lines.push("");
+          lines.push("## Sitemaps Referenced");
+          for (const url of result.robotsTxt.sitemapReferences) {
+            lines.push(`  - ${url}`);
+          }
+        }
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to check robots.txt for ${domain}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Tool: check_llms_txt
+// ---------------------------------------------------------------------------
+server.tool(
+  "check_llms_txt",
+  "Check if a domain has an llms.txt file. " +
+    "Note: llms.txt is an emerging proposal but is NOT currently supported or consumed by any major AI model, crawler, or MCP client. " +
+    "It should not be treated as a relevant optimization for GEO readiness — it will not meaningfully improve AI discoverability today. " +
+    "That said, having one cannot hurt. Returns the file contents if found.",
+  {
+    domain: z
+      .string()
+      .describe(
+        'The domain to check, e.g. "example.com". Do not include https:// prefix.'
+      ),
+  },
+  withLicense(async ({ domain }) => {
+    try {
+      const result = await checkGEO(domain, { maxPages: 1 });
+
+      if (result.error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error checking ${domain}: ${result.error}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const lines = [];
+      lines.push(`# llms.txt Check: ${result.domain}`);
+      lines.push("");
+      lines.push(`URL: ${result.llmsTxt.url}`);
+      lines.push(`Exists: ${result.llmsTxt.exists ? "Yes" : "No"}`);
+
+      if (!result.llmsTxt.exists) {
+        lines.push("");
+        lines.push(
+          "No llms.txt found. Note: llms.txt is an emerging proposal but is not currently supported or consumed by any major AI model or crawler. " +
+          "Adding one is not a meaningful optimization for GEO readiness today, but it cannot hurt to have one."
+        );
+        lines.push(
+          "See https://llmstxt.org for the specification."
+        );
+      } else {
+        lines.push("");
+        lines.push("## Contents");
+        lines.push(result.llmsTxt.content);
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to check llms.txt for ${domain}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Tool: get_geo_summary
+// ---------------------------------------------------------------------------
+server.tool(
+  "get_geo_summary",
+  "Get a concise GEO readiness summary for a domain: overall score, grade, top 3 strengths, and top 3 issues to fix. " +
+    "Use this for a quick overview; use analyze_domain for full details.",
+  {
+    domain: z
+      .string()
+      .describe(
+        'The domain to check, e.g. "example.com". Do not include https:// prefix.'
+      ),
+  },
+  withLicense(async ({ domain }) => {
+    try {
+      const result = await checkGEO(domain, { maxPages: 1 });
+
+      if (result.error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error analysing ${domain}: ${result.error}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const analysis = result.homepage?.analysis;
+      if (!analysis) {
+        const statusCode = result.homepage?.statusCode;
+        const statusMsg = statusCode === null
+          ? "connection failed (no response)"
+          : `HTTP status: ${statusCode}`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Could not analyse homepage for ${domain}. ${statusMsg}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const grade = scoreToGrade(analysis.overallScore);
+      const lines = [];
+      lines.push(`# GEO Summary: ${result.domain}`);
+      lines.push(`Overall Score: ${analysis.overallScore}% (${grade})`);
+      lines.push(`Page Type: ${analysis.pageType}`);
+      lines.push("");
+
+      // Sort categories by score
+      const cats = [...(analysis.categories || [])];
+      const sorted = cats.sort((a, b) => b.score - a.score);
+
+      // Top 3 strengths
+      lines.push("## Top Strengths");
+      for (const cat of sorted.slice(0, 3)) {
+        lines.push(`  + ${cat.category}: ${cat.score}%`);
+      }
+
+      // Top 3 areas to improve
+      lines.push("");
+      lines.push("## Top Areas to Improve");
+      const weakest = sorted.slice(-3).reverse();
+      for (const cat of weakest) {
+        const fails = (cat.checks || []).filter((c) => c.status === "fail");
+        const topIssue = fails[0]?.label || "Review this category";
+        lines.push(`  - ${cat.category}: ${cat.score}% — ${topIssue}`);
+      }
+
+      // Quick facts
+      lines.push("");
+      lines.push("## Quick Facts");
+      lines.push(`  robots.txt: ${result.robotsTxt.exists ? "Present" : "Missing"}`);
+      lines.push(`  llms.txt: ${result.llmsTxt.exists ? "Present" : "Missing"}`);
+      lines.push(`  Sitemap: ${result.sitemap.exists ? "Present" : "Missing"}`);
+
+      const blockedCrawlers = Object.entries(
+        result.robotsTxt.blocksCrawlers || {}
+      ).filter(([, blocked]) => blocked);
+      if (blockedCrawlers.length > 0) {
+        lines.push(
+          `  AI crawlers blocked: ${blockedCrawlers.map(([name]) => name).join(", ")}`
+        );
+      } else {
+        lines.push("  AI crawlers blocked: None");
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to get summary for ${domain}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Tool: compare_domains
+// ---------------------------------------------------------------------------
+server.tool(
+  "compare_domains",
+  "Analyse multiple domains in parallel and compare their GEO scores side by side. " +
+    "Returns a comparison table with overall scores, per-category breakdowns, and a ranked summary. " +
+    "Useful for competitive analysis or auditing a portfolio of sites. " +
+    "Requires Pro or Agency tier. " +
+    "Use output_format='json' to get raw results that can be passed to export_bulk_report.",
+  {
+    domains: z
+      .array(z.string())
+      .min(2)
+      .max(10)
+      .describe(
+        'List of domains to compare, e.g. ["example.com", "competitor.com"]. Do not include https:// prefix.'
+      ),
+    max_pages: z
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe(
+        "Maximum pages to crawl per domain (1 = homepage only). Defaults to 10."
+      ),
+    output_format: z
+      .enum(["text", "json"])
+      .optional()
+      .describe(
+        'Output format. "text" (default) returns a human-readable comparison table. ' +
+        '"json" returns the raw analysis results that can be passed to export_bulk_report.'
+      ),
+  },
+  withTierFeature(
+    "compareDomains",
+    "Domain comparison requires a Pro or Agency license.",
+    async ({ domains, max_pages, output_format }) => {
+    const maxPages = max_pages ?? 10;
+
+    // Run all analyses in parallel
+    const results = await Promise.allSettled(
+      domains.map((domain) =>
+        checkGEO(domain, { maxPages }).then((result) => ({
+          domain,
+          result,
+        }))
+      )
+    );
+
+    // JSON output mode - return raw results for use with export_bulk_report
+    if (output_format === "json") {
+      const rawResults = results.map((r) => {
+        if (r.status === "rejected") {
+          return { domain: "unknown", error: r.reason?.message || "Analysis failed" };
+        }
+        return r.value.result;
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(rawResults, null, 2),
+          },
+        ],
+      };
+    }
+
+    const lines = [];
+    lines.push(`# GEO Comparison: ${domains.length} domains`);
+    lines.push("");
+
+    // Build comparison data
+    const entries = [];
+    for (const r of results) {
+      if (r.status === "rejected") {
+        entries.push({ domain: "unknown", error: r.reason?.message || "Analysis failed" });
+        continue;
+      }
+      const { domain, result } = r.value;
+      if (result.error) {
+        entries.push({ domain, error: result.error });
+        continue;
+      }
+      const analysis = result.homepage?.analysis;
+      entries.push({
+        domain: result.domain,
+        score: analysis?.overallScore ?? null,
+        grade: analysis ? scoreToGrade(analysis.overallScore) : "N/A",
+        categories: analysis?.categories || [],
+        robotsTxt: result.robotsTxt?.exists ?? false,
+        llmsTxt: result.llmsTxt?.exists ?? false,
+        sitemap: result.sitemap?.exists ?? false,
+        blockedCrawlers: Object.entries(result.robotsTxt?.blocksCrawlers || {})
+          .filter(([, blocked]) => blocked)
+          .map(([name]) => name),
+        error: null,
+      });
+    }
+
+    // Ranking table
+    const scored = entries.filter((e) => !e.error && e.score !== null);
+    const ranked = [...scored].sort((a, b) => b.score - a.score);
+
+    lines.push("## Rankings");
+    lines.push("");
+    for (let i = 0; i < ranked.length; i++) {
+      const e = ranked[i];
+      lines.push(`${i + 1}. **${e.domain}**: ${e.score}% (${e.grade})`);
+    }
+
+    // Errors
+    const errored = entries.filter((e) => e.error);
+    if (errored.length > 0) {
+      lines.push("");
+      for (const e of errored) {
+        lines.push(`- **${e.domain}**: Error — ${e.error}`);
+      }
+    }
+
+    // Category comparison table
+    if (scored.length >= 2) {
+      // Collect all unique category names
+      const catNames = [
+        ...new Set(scored.flatMap((e) => e.categories.map((c) => c.category))),
+      ];
+
+      lines.push("");
+      lines.push("## Category Comparison");
+      lines.push("");
+
+      // Header
+      const header = `| Category | ${scored.map((e) => e.domain).join(" | ")} |`;
+      const separator = `|---|${scored.map(() => "---").join("|")}|`;
+      lines.push(header);
+      lines.push(separator);
+
+      for (const catName of catNames) {
+        const scores = scored.map((e) => {
+          const cat = e.categories.find((c) => c.category === catName);
+          return cat ? `${cat.score}%` : "—";
+        });
+        lines.push(`| ${catName} | ${scores.join(" | ")} |`);
+      }
+
+      // Overall row
+      lines.push(
+        `| **Overall** | ${scored.map((e) => `**${e.score}%**`).join(" | ")} |`
+      );
+    }
+
+    // Quick facts comparison
+    lines.push("");
+    lines.push("## Quick Facts");
+    lines.push("");
+    const factsHeader = `| | ${scored.map((e) => e.domain).join(" | ")} |`;
+    const factsSep = `|---|${scored.map(() => "---").join("|")}|`;
+    lines.push(factsHeader);
+    lines.push(factsSep);
+    lines.push(
+      `| robots.txt | ${scored.map((e) => (e.robotsTxt ? "Yes" : "No")).join(" | ")} |`
+    );
+    lines.push(
+      `| llms.txt | ${scored.map((e) => (e.llmsTxt ? "Yes" : "No")).join(" | ")} |`
+    );
+    lines.push(
+      `| Sitemap | ${scored.map((e) => (e.sitemap ? "Yes" : "No")).join(" | ")} |`
+    );
+    lines.push(
+      `| AI crawlers blocked | ${scored.map((e) => e.blockedCrawlers.length > 0 ? e.blockedCrawlers.join(", ") : "None").join(" | ")} |`
+    );
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+    };
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Shared: per-URL analysis helper
+// ---------------------------------------------------------------------------
+
+/** Default per-domain requests/second (overridable via GLIPPY_RATE_LIMIT env). */
+const DEFAULT_RATE_LIMIT = parseInt(process.env.GLIPPY_RATE_LIMIT, 10) || 5;
+
+/**
+ * Analyse a batch of full URLs. Groups by domain so robots.txt / llms.txt
+ * is fetched once per domain. Enforces per-domain rate limiting to avoid
+ * overwhelming target servers.
+ *
+ * @param {string[]} urls - Full URLs (https://example.com/page)
+ * @param {number} concurrency - Max pages fetched at a time across all domains
+ * @param {number} domainRateLimit - Max requests/second per domain (0 = unlimited)
+ * @returns {Promise<{pageResults: object[], domainMeta: Map}>}
+ */
+async function analyseUrls(urls, concurrency = 3, domainRateLimit = DEFAULT_RATE_LIMIT) {
+  // Group URLs by domain
+  const domainMap = new Map(); // domain → [urls]
+  for (const url of urls) {
+    try {
+      const parsed = new URL(url);
+      const domain = parsed.hostname;
+      if (!domainMap.has(domain)) domainMap.set(domain, []);
+      domainMap.get(domain).push(url);
+    } catch {
+      // skip invalid URLs
+    }
+  }
+
+  // Fetch robots.txt + llms.txt once per domain
+  const domainMeta = new Map(); // domain → { robotsTxtData, llmsTxtData }
+  await Promise.all(
+    [...domainMap.keys()].map(async (domain) => {
+      const [robotsRes, llmsRes] = await Promise.all([
+        throttledFetchUrl(`https://${domain}/robots.txt`, 10000, 512 * 1024).catch(() => ({
+          body: null,
+        })),
+        throttledFetchUrl(`https://${domain}/llms.txt`, 10000, 512 * 1024).catch(() => ({
+          body: null,
+        })),
+      ]);
+
+      const robotsTxtData =
+        robotsRes.statusCode === 200 && robotsRes.body
+          ? analyseRobotsTxt(robotsRes.body)
+          : { blocksCrawlers: {}, hasWildcardDisallow: false, sitemapUrls: [] };
+
+      const llmsTxtData = {
+        exists: llmsRes.statusCode === 200 && !!llmsRes.body,
+        content: llmsRes.body || null,
+      };
+
+      domainMeta.set(domain, { robotsTxtData, llmsTxtData });
+    })
+  );
+
+  // Per-domain rate limiter: serialises requests to each domain with a
+  // minimum interval between them, while still allowing cross-domain
+  // concurrency within the batch window.
+  const minInterval = domainRateLimit > 0 ? 1000 / domainRateLimit : 0;
+  const domainQueues = new Map(); // domain → Promise (chain)
+
+  function withDomainRate(domain, fn) {
+    const prev = domainQueues.get(domain) || Promise.resolve();
+    const next = prev.then(async () => {
+      const result = await fn();
+      if (minInterval > 0) {
+        await new Promise((r) => setTimeout(r, minInterval));
+      }
+      return result;
+    });
+    // Prevent a single failure from breaking the chain for subsequent URLs
+    domainQueues.set(domain, next.catch(() => {}));
+    return next;
+  }
+
+  // Analyse each URL in batches, with per-domain rate limiting
+  const pageResults = [];
+  for (let i = 0; i < urls.length; i += concurrency) {
+    const batch = urls.slice(i, i + concurrency);
+    const batchResults = await Promise.all(
+      batch.map(async (url) => {
+        let domain;
+        try {
+          domain = new URL(url).hostname;
+        } catch {
+          return { url, analysis: null, error: "Invalid URL" };
+        }
+
+        return withDomainRate(domain, async () => {
+          try {
+            const pathname = new URL(url).pathname;
+            const meta = domainMeta.get(domain);
+            const res = await throttledFetchUrl(url, 15000);
+
+            if (res.statusCode !== 200 || !res.body) {
+              return {
+                url,
+                analysis: null,
+                error: res.statusCode ? `HTTP ${res.statusCode}` : "Failed to fetch",
+              };
+            }
+
+            const analysis = analyseHTML(
+              res.body,
+              domain,
+              meta.robotsTxtData,
+              meta.llmsTxtData,
+              res.headers || {},
+              pathname
+            );
+
+            return { url, analysis, error: null };
+          } catch (err) {
+            return { url, analysis: null, error: err.message };
+          }
+        });
+      })
+    );
+    pageResults.push(...batchResults);
+  }
+
+  return { pageResults, domainMeta };
+}
+
+/** Format per-page results into a readable report. */
+function formatUrlResults(pageResults, domainMeta) {
+  const lines = [];
+
+  // Aggregate
+  const aggregated = aggregatePageScores(pageResults);
+
+  if (aggregated.pagesAnalysed > 0) {
+    lines.push(
+      `**${aggregated.pagesAnalysed} pages analysed** | Average score: ${aggregated.averageScore}% (${scoreToGrade(aggregated.averageScore)})`
+    );
+    if (aggregated.pagesFailed > 0) {
+      lines.push(`${aggregated.pagesFailed} pages failed`);
+    }
+    lines.push("");
+  }
+
+  // Per-page results
+  lines.push("## Per-Page Results");
+  lines.push("");
+
+  // Table header
+  lines.push("| URL | Score | Grade | Page Type |");
+  lines.push("|-----|-------|-------|-----------|");
+
+  for (const page of pageResults) {
+    if (page.error) {
+      lines.push(`| ${page.url} | — | — | Error: ${page.error} |`);
+    } else {
+      const score = page.analysis?.overallScore ?? 0;
+      lines.push(
+        `| ${page.url} | ${score}% | ${scoreToGrade(score)} | ${page.analysis?.pageType || "unknown"} |`
+      );
+    }
+  }
+
+  // Category averages
+  if (aggregated.categoryAverages && Object.keys(aggregated.categoryAverages).length > 0) {
+    lines.push("");
+    lines.push("## Category Averages");
+    lines.push("");
+    for (const [cat, avg] of Object.entries(aggregated.categoryAverages)) {
+      lines.push(`- ${cat}: ${avg}% (${scoreToGrade(avg)})`);
+    }
+  }
+
+  // Weakest pages
+  const scored = pageResults
+    .filter((p) => !p.error && p.analysis?.overallScore != null)
+    .sort((a, b) => a.analysis.overallScore - b.analysis.overallScore);
+
+  if (scored.length > 2) {
+    lines.push("");
+    lines.push("## Weakest Pages");
+    for (const p of scored.slice(0, 3)) {
+      const fails = (p.analysis.categories || [])
+        .filter((c) => c.score < 50)
+        .map((c) => c.category);
+      lines.push(
+        `- ${p.url}: ${p.analysis.overallScore}%${fails.length > 0 ? ` — weak in: ${fails.join(", ")}` : ""}`
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Tool: analyze_sitemap
+// ---------------------------------------------------------------------------
+server.tool(
+  "analyze_sitemap",
+  "Fetch a sitemap XML (or sitemap index), extract page URLs, and run GEO analysis on each page. " +
+    "Returns per-page scores, category averages, and weakest pages. " +
+    "Supports both regular sitemaps and sitemap index files. " +
+    "Requires Pro or Agency tier. " +
+    "Use output_format='json' to get raw results that can be passed to export_bulk_report. " +
+    "For large sitemaps, use 'summary' format or pagination (offset/limit) to avoid exceeding output limits.",
+  {
+    sitemap_url: z
+      .string()
+      .describe(
+        'Full URL to a sitemap.xml file, e.g. "https://example.com/sitemap.xml"'
+      ),
+    max_urls: z
+      .number()
+      .int()
+      .min(1)
+      .max(50000)
+      .optional()
+      .describe(
+        "Maximum number of URLs to analyse from the sitemap. Defaults to all URLs found (up to 50,000). Set a limit for large sitemaps."
+      ),
+    rate_limit: z
+      .number()
+      .min(0.1)
+      .max(100)
+      .optional()
+      .describe(
+        "Maximum requests per second per domain. Prevents overwhelming target servers. " +
+        "Defaults to 5 req/s (or GLIPPY_RATE_LIMIT env var). Set lower for polite crawling, higher if you control the target server. " +
+        "Use 0.5 for 1 request every 2 seconds, 10 for aggressive crawling."
+      ),
+    output_format: z
+      .enum(["text", "json", "summary"])
+      .optional()
+      .describe(
+        'Output format. "text" (default) returns a human-readable report. ' +
+        '"json" returns the raw page results and aggregated scores that can be passed to export_bulk_report. ' +
+        '"summary" returns a compact JSON with only aggregated stats and minimal page info (url, score, error) - ideal for large sitemaps.'
+      ),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "For JSON output: skip the first N page results. Use with limit for pagination of large result sets."
+      ),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe(
+        "For JSON output: return at most N page results (default: all). Use with offset for pagination. " +
+        "Recommended: 10-20 for detailed results to stay within output limits."
+      ),
+  },
+  withLicense(async ({ sitemap_url, max_urls, rate_limit, output_format, offset, limit }) => {
+    const features = getFeatures();
+
+    // Check if sitemap analysis is available for this tier
+    if (features.maxSitemapUrls === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Sitemap analysis requires a Pro or Agency license.\n\nUpgrade at https://www.glippy.dev/mcp",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    // Enforce tier URL limit
+    const tierMaxUrls = features.maxSitemapUrls || 50000;
+    const maxUrls = Math.min(max_urls ?? tierMaxUrls, tierMaxUrls);
+
+    try {
+      // Fetch the sitemap
+      const sitemapRes = await throttledFetchUrl(sitemap_url, 15000, 512 * 1024);
+
+      if (sitemapRes.statusCode !== 200 || !sitemapRes.body) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Failed to fetch sitemap: ${sitemap_url} (HTTP ${sitemapRes.statusCode || "error"})`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      // Extract domain from sitemap URL for parsing
+      let domain;
+      try {
+        domain = new URL(sitemap_url).hostname;
+      } catch {
+        return {
+          content: [
+            { type: "text", text: `Invalid sitemap URL: ${sitemap_url}` },
+          ],
+          isError: true,
+        };
+      }
+
+      // Parse URLs from the sitemap
+      const allUrls = await parseSitemapUrls(sitemapRes.body, domain, 50000);
+
+      if (allUrls.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No URLs found in sitemap: ${sitemap_url}. Ensure it contains <loc> entries.`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      const urlsToAnalyse = allUrls.slice(0, maxUrls);
+
+      const lines = [];
+      lines.push(`# Sitemap Analysis: ${sitemap_url}`);
+      lines.push(
+        `Found ${allUrls.length} URLs in sitemap, analysing ${urlsToAnalyse.length}`
+      );
+      lines.push("");
+
+      // Analyse all URLs with rate limiting
+      const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
+      const { pageResults } = await analyseUrls(urlsToAnalyse, 3, rateLimit);
+      const aggregated = aggregatePageScores(pageResults);
+
+      // Summary output mode - compact JSON with minimal page info (ideal for large sitemaps)
+      if (output_format === "summary") {
+        const compactPages = pageResults.map(p => ({
+          url: p.url,
+          score: p.analysis?.overallScore ?? null,
+          pageType: p.analysis?.pageType ?? null,
+          error: p.error || null,
+        }));
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                sitemap_url,
+                urls_found: allUrls.length,
+                urls_analysed: urlsToAnalyse.length,
+                aggregated,
+                pages: compactPages,
+              }, null, 2),
+            },
+          ],
+        };
+      }
+
+      // JSON output mode - return raw results for use with export_bulk_report
+      if (output_format === "json") {
+        // Apply pagination if specified
+        const paginationOffset = offset ?? 0;
+        const paginationLimit = limit ?? pageResults.length;
+        const paginatedResults = pageResults.slice(paginationOffset, paginationOffset + paginationLimit);
+        const hasMore = paginationOffset + paginationLimit < pageResults.length;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                sitemap_url,
+                urls_found: allUrls.length,
+                urls_analysed: urlsToAnalyse.length,
+                // Pagination metadata
+                pagination: {
+                  total: pageResults.length,
+                  offset: paginationOffset,
+                  limit: paginationLimit,
+                  returned: paginatedResults.length,
+                  hasMore,
+                  nextOffset: hasMore ? paginationOffset + paginationLimit : null,
+                },
+                // Always include aggregated stats (computed from ALL results)
+                aggregated,
+                // Paginated page results
+                pageResults: paginatedResults,
+              }, null, 2),
+            },
+          ],
+        };
+      }
+
+      lines.push(formatUrlResults(pageResults));
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to analyse sitemap ${sitemap_url}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Tool: analyze_urls
+// ---------------------------------------------------------------------------
+server.tool(
+  "analyze_urls",
+  "Run GEO analysis on a list of specific URLs. " +
+    "Fetches each page, scores it across 10 categories, and returns per-page results with aggregated averages. " +
+    "URLs can span multiple domains. " +
+    "Batch analysis (multiple URLs) requires Pro or Agency tier. " +
+    "Use output_format='json' to get raw results that can be passed to export_bulk_report. " +
+    "For large batches, use 'summary' format or pagination (offset/limit) to avoid exceeding output limits.",
+  {
+    urls: z
+      .array(z.string())
+      .min(1)
+      .max(50000)
+      .describe(
+        'List of full URLs to analyse, e.g. ["https://example.com/about", "https://example.com/pricing"]. Include https:// prefix.'
+      ),
+    rate_limit: z
+      .number()
+      .min(0.1)
+      .max(100)
+      .optional()
+      .describe(
+        "Maximum requests per second per domain. Prevents overwhelming target servers. " +
+        "Defaults to 5 req/s (or GLIPPY_RATE_LIMIT env var). Set lower for polite crawling, higher if you control the target server. " +
+        "Use 0.5 for 1 request every 2 seconds, 10 for aggressive crawling."
+      ),
+    output_format: z
+      .enum(["text", "json", "summary"])
+      .optional()
+      .describe(
+        'Output format. "text" (default) returns a human-readable report. ' +
+        '"json" returns the raw page results and aggregated scores that can be passed to export_bulk_report. ' +
+        '"summary" returns a compact JSON with only aggregated stats and minimal page info (url, score, error) - ideal for large batches.'
+      ),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "For JSON output: skip the first N page results. Use with limit for pagination of large result sets."
+      ),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe(
+        "For JSON output: return at most N page results (default: all). Use with offset for pagination. " +
+        "Recommended: 10-20 for detailed results to stay within output limits."
+      ),
+  },
+  withLicense(async ({ urls, rate_limit, output_format, offset, limit }) => {
+    const features = getFeatures();
+
+    // Check if batch analysis is available for this tier
+    if (urls.length > features.maxBatchUrls) {
+      if (features.maxBatchUrls === 1) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Batch URL analysis requires a Pro or Agency license. Your Personal license allows 1 URL at a time.\n\nUpgrade at https://www.glippy.dev/mcp`,
+            },
+          ],
+          isError: true,
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Your license allows up to ${features.maxBatchUrls} URLs per batch. You requested ${urls.length}.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
+      const { pageResults } = await analyseUrls(urls, 3, rateLimit);
+      const aggregated = aggregatePageScores(pageResults);
+
+      // Summary output mode - compact JSON with minimal page info (ideal for large batches)
+      if (output_format === "summary") {
+        const compactPages = pageResults.map(p => ({
+          url: p.url,
+          score: p.analysis?.overallScore ?? null,
+          pageType: p.analysis?.pageType ?? null,
+          error: p.error || null,
+        }));
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                urls_analysed: urls.length,
+                aggregated,
+                pages: compactPages,
+              }, null, 2),
+            },
+          ],
+        };
+      }
+
+      // JSON output mode - return raw results for use with export_bulk_report
+      if (output_format === "json") {
+        // Apply pagination if specified
+        const paginationOffset = offset ?? 0;
+        const paginationLimit = limit ?? pageResults.length;
+        const paginatedResults = pageResults.slice(paginationOffset, paginationOffset + paginationLimit);
+        const hasMore = paginationOffset + paginationLimit < pageResults.length;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                urls_analysed: urls.length,
+                // Pagination metadata
+                pagination: {
+                  total: pageResults.length,
+                  offset: paginationOffset,
+                  limit: paginationLimit,
+                  returned: paginatedResults.length,
+                  hasMore,
+                  nextOffset: hasMore ? paginationOffset + paginationLimit : null,
+                },
+                // Always include aggregated stats (computed from ALL results)
+                aggregated,
+                // Paginated page results
+                pageResults: paginatedResults,
+              }, null, 2),
+            },
+          ],
+        };
+      }
+
+      const lines = [];
+      lines.push(`# URL Analysis: ${urls.length} pages`);
+      lines.push("");
+      lines.push(formatUrlResults(pageResults));
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to analyse URLs: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Tool: export_report
+// ---------------------------------------------------------------------------
+server.tool(
+  "export_report",
+  "Run a GEO analysis on a domain and return the results as a styled, self-contained report " +
+    "in Markdown or HTML format — matching the Glippy browser extension's export output. " +
+    "Use this when the user wants a shareable or saveable report file rather than inline text. " +
+    "You can optionally pass pre-computed analysis results from analyze_domain (with output_format='json') " +
+    "to avoid re-crawling the domain.",
+  {
+    domain: z
+      .string()
+      .optional()
+      .describe(
+        'The domain to analyse, e.g. "example.com". Do not include https:// prefix. ' +
+        'Required unless analysis_result is provided.'
+      ),
+    format: z
+      .enum(["markdown", "markdown_full", "html"])
+      .describe(
+        'Report format. "markdown" = recommendations only, "markdown_full" = full report with all categories and checks, "html" = standalone styled HTML page.'
+      ),
+    max_pages: z
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe(
+        "Maximum pages to crawl (1 = homepage only, up to 10 for multi-page analysis). Defaults to 10. " +
+        "Ignored if analysis_result is provided."
+      ),
+    analysis_result: z
+      .object({})
+      .passthrough()
+      .optional()
+      .describe(
+        "Pre-computed analysis result from analyze_domain (with output_format='json'). " +
+        "If provided, the domain will not be re-crawled. This allows you to run analysis once " +
+        "and export in multiple formats without redundant crawling."
+      ),
+  },
+  withLicense(async ({ domain, format, max_pages, analysis_result }) => {
+    try {
+      let result;
+
+      if (analysis_result) {
+        // Use pre-computed results
+        result = analysis_result;
+        if (!result.domain) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Invalid analysis_result: missing 'domain' field. Please provide a valid result from analyze_domain.",
+              },
+            ],
+            isError: true,
+          };
+        }
+      } else if (domain) {
+        // Run fresh analysis (may use cache automatically)
+        result = await checkGEO(domain, {
+          maxPages: max_pages ?? 10,
+        });
+      } else {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "Either 'domain' or 'analysis_result' must be provided.",
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      if (result.error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error analysing ${result.domain || domain}: ${result.error}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      let reportContent;
+      let mimeDescription;
+
+      if (format === "html") {
+        reportContent = generateHTMLReport(result);
+        mimeDescription = "HTML";
+      } else {
+        const fullExport = format === "markdown_full";
+        reportContent = generateMarkdownReport(result, fullExport);
+        mimeDescription = fullExport ? "Markdown (full)" : "Markdown (recommendations)";
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `<!-- ${mimeDescription} report for ${result.domain} -->\n` +
+              `<!-- Save this content to a .${format === "html" ? "html" : "md"} file -->\n\n` +
+              reportContent,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to generate report for ${domain}: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Tool: export_bulk_report
+// ---------------------------------------------------------------------------
+server.tool(
+  "export_bulk_report",
+  "Generate a styled Markdown or HTML report for bulk analysis: compare multiple domains, " +
+    "analyse a list of URLs, or crawl a sitemap. Returns a self-contained report with rankings, " +
+    "category breakdowns, and per-domain/page recommendations. " +
+    "Provide exactly one of: domains, urls, sitemap_url, or analysis_results. " +
+    "You can pass pre-computed results from compare_domains, analyze_urls, or analyze_sitemap " +
+    "(with output_format='json') to avoid re-crawling. " +
+    "Requires Pro or Agency tier.",
+  {
+    format: z
+      .enum(["markdown", "html"])
+      .describe(
+        'Report format. "markdown" = Markdown report, "html" = standalone styled HTML page.'
+      ),
+    domains: z
+      .array(z.string())
+      .min(2)
+      .max(10)
+      .optional()
+      .describe(
+        'Compare multiple domains. E.g. ["example.com", "competitor.com"]. Do not include https://.'
+      ),
+    urls: z
+      .array(z.string())
+      .min(1)
+      .max(50000)
+      .optional()
+      .describe(
+        'Analyse specific URLs. E.g. ["https://example.com/about", "https://example.com/pricing"]. Include https://.'
+      ),
+    sitemap_url: z
+      .string()
+      .optional()
+      .describe(
+        'Sitemap URL to crawl. E.g. "https://example.com/sitemap.xml".'
+      ),
+    analysis_results: z
+      .object({})
+      .passthrough()
+      .optional()
+      .describe(
+        "Pre-computed analysis results from compare_domains, analyze_urls, or analyze_sitemap " +
+        "(with output_format='json'). If provided, no crawling will be performed. " +
+        "The type of report generated depends on the structure of the results."
+      ),
+    max_pages: z
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe(
+        "For domain comparison: max pages to crawl per domain (default 10). Ignored for urls/sitemap/analysis_results."
+      ),
+    max_urls: z
+      .number()
+      .int()
+      .min(1)
+      .max(50000)
+      .optional()
+      .describe(
+        "For sitemap mode: max URLs to analyse from the sitemap. Defaults to all. Ignored if analysis_results provided."
+      ),
+    rate_limit: z
+      .number()
+      .min(0.1)
+      .max(100)
+      .optional()
+      .describe(
+        "Max requests/second per domain for URL/sitemap modes. Defaults to 5. Ignored if analysis_results provided."
+      ),
+  },
+  withTierFeature(
+    "bulkExport",
+    "Bulk report exports require a Pro or Agency license.",
+    async ({ format, domains, urls, sitemap_url, analysis_results, max_pages, max_urls, rate_limit }) => {
+    // Validate: exactly one input mode
+    const modes = [domains, urls, sitemap_url, analysis_results].filter(Boolean).length;
+    if (modes !== 1) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Provide exactly one of: domains, urls, sitemap_url, or analysis_results.",
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      // ------------------------------------------------------------------
+      // Mode 0: Pre-computed analysis results
+      // ------------------------------------------------------------------
+      if (analysis_results) {
+        // Detect the type of results based on structure
+        // Domain comparison: array of checkGEO results
+        // URL/Sitemap analysis: { pageResults, aggregated } or { sitemap_url, pageResults, aggregated }
+
+        if (Array.isArray(analysis_results)) {
+          // Domain comparison results (array of checkGEO results)
+          const entries = [];
+          for (const result of analysis_results) {
+            if (result.error && !result.homepage) {
+              entries.push({ domain: result.domain || "unknown", error: result.error });
+              continue;
+            }
+            const analysis = result.homepage?.analysis;
+            entries.push({
+              domain: result.domain,
+              score: analysis?.overallScore ?? null,
+              grade: analysis ? scoreToGrade(analysis.overallScore) : "N/A",
+              categories: analysis?.categories || [],
+              robotsTxt: result.robotsTxt?.exists ?? false,
+              llmsTxt: result.llmsTxt?.exists ?? false,
+              sitemap: result.sitemap?.exists ?? false,
+              blockedCrawlers: Object.entries(result.robotsTxt?.blocksCrawlers || {})
+                .filter(([, blocked]) => blocked)
+                .map(([name]) => name),
+              error: null,
+            });
+          }
+
+          const reportContent =
+            format === "html"
+              ? generateComparisonHTMLReport(entries)
+              : generateComparisonMarkdownReport(entries);
+
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `<!-- Bulk comparison report (${format}) from pre-computed results -->\n` +
+                  `<!-- Save this content to a .${format === "html" ? "html" : "md"} file -->\n\n` +
+                  reportContent,
+              },
+            ],
+          };
+        } else if (analysis_results.pageResults && analysis_results.aggregated) {
+          // URL or sitemap analysis results
+          const { pageResults, aggregated } = analysis_results;
+          const title = analysis_results.sitemap_url
+            ? `Sitemap: ${analysis_results.sitemap_url}`
+            : `${analysis_results.urls_analysed || pageResults.length} URLs`;
+
+          const reportContent =
+            format === "html"
+              ? generateUrlsHTMLReport(title, pageResults, aggregated)
+              : generateUrlsMarkdownReport(title, pageResults, aggregated);
+
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `<!-- Bulk URL report (${format}) from pre-computed results -->\n` +
+                  `<!-- Save this content to a .${format === "html" ? "html" : "md"} file -->\n\n` +
+                  reportContent,
+              },
+            ],
+          };
+        } else {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Invalid analysis_results structure. Expected either:\n" +
+                  "- Array of checkGEO results (from compare_domains with output_format='json')\n" +
+                  "- Object with { pageResults, aggregated } (from analyze_urls or analyze_sitemap with output_format='json')",
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+
+      // ------------------------------------------------------------------
+      // Mode 1: Multi-domain comparison
+      // ------------------------------------------------------------------
+      if (domains) {
+        const maxPages = max_pages ?? 10;
+        const results = await Promise.allSettled(
+          domains.map((domain) =>
+            checkGEO(domain, { maxPages }).then((result) => ({
+              domain,
+              result,
+            }))
+          )
+        );
+
+        const entries = [];
+        for (const r of results) {
+          if (r.status === "rejected") {
+            entries.push({ domain: "unknown", error: r.reason?.message || "Analysis failed" });
+            continue;
+          }
+          const { domain, result } = r.value;
+          if (result.error) {
+            entries.push({ domain, error: result.error });
+            continue;
+          }
+          const analysis = result.homepage?.analysis;
+          entries.push({
+            domain: result.domain,
+            score: analysis?.overallScore ?? null,
+            grade: analysis ? scoreToGrade(analysis.overallScore) : "N/A",
+            categories: analysis?.categories || [],
+            robotsTxt: result.robotsTxt?.exists ?? false,
+            llmsTxt: result.llmsTxt?.exists ?? false,
+            sitemap: result.sitemap?.exists ?? false,
+            blockedCrawlers: Object.entries(result.robotsTxt?.blocksCrawlers || {})
+              .filter(([, blocked]) => blocked)
+              .map(([name]) => name),
+            error: null,
+          });
+        }
+
+        const reportContent =
+          format === "html"
+            ? generateComparisonHTMLReport(entries)
+            : generateComparisonMarkdownReport(entries);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `<!-- Bulk comparison report (${format}) for ${domains.length} domains -->\n` +
+                `<!-- Save this content to a .${format === "html" ? "html" : "md"} file -->\n\n` +
+                reportContent,
+            },
+          ],
+        };
+      }
+
+      // ------------------------------------------------------------------
+      // Mode 2: URL list analysis
+      // ------------------------------------------------------------------
+      if (urls) {
+        const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
+        const { pageResults } = await analyseUrls(urls, 3, rateLimit);
+        const aggregated = aggregatePageScores(pageResults);
+        const title = `${urls.length} URLs`;
+
+        const reportContent =
+          format === "html"
+            ? generateUrlsHTMLReport(title, pageResults, aggregated)
+            : generateUrlsMarkdownReport(title, pageResults, aggregated);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `<!-- Bulk URL report (${format}) for ${urls.length} URLs -->\n` +
+                `<!-- Save this content to a .${format === "html" ? "html" : "md"} file -->\n\n` +
+                reportContent,
+            },
+          ],
+        };
+      }
+
+      // ------------------------------------------------------------------
+      // Mode 3: Sitemap analysis
+      // ------------------------------------------------------------------
+      if (sitemap_url) {
+        const sitemapRes = await throttledFetchUrl(sitemap_url, 15000, 512 * 1024);
+        if (sitemapRes.statusCode !== 200 || !sitemapRes.body) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Failed to fetch sitemap: ${sitemap_url} (HTTP ${sitemapRes.statusCode || "error"})`,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        let domain;
+        try {
+          domain = new URL(sitemap_url).hostname;
+        } catch {
+          return {
+            content: [
+              { type: "text", text: `Invalid sitemap URL: ${sitemap_url}` },
+            ],
+            isError: true,
+          };
+        }
+
+        const allUrls = await parseSitemapUrls(sitemapRes.body, domain, 50000);
+        if (allUrls.length === 0) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No URLs found in sitemap: ${sitemap_url}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        const urlsToAnalyse = allUrls.slice(0, max_urls ?? 50000);
+        const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
+        const { pageResults } = await analyseUrls(urlsToAnalyse, 3, rateLimit);
+        const aggregated = aggregatePageScores(pageResults);
+        const title = `Sitemap: ${sitemap_url} (${urlsToAnalyse.length} of ${allUrls.length} URLs)`;
+
+        const reportContent =
+          format === "html"
+            ? generateUrlsHTMLReport(title, pageResults, aggregated)
+            : generateUrlsMarkdownReport(title, pageResults, aggregated);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text:
+                `<!-- Sitemap report (${format}) for ${sitemap_url} -->\n` +
+                `<!-- Save this content to a .${format === "html" ? "html" : "md"} file -->\n\n` +
+                reportContent,
+            },
+          ],
+        };
+      }
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Failed to generate bulk report: ${err.message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  })
+);
+
+// ---------------------------------------------------------------------------
+// Graceful deactivation on shutdown
+// ---------------------------------------------------------------------------
+
+async function deactivateInstance() {
+  const licenseKey = process.env.GLIPPY_LICENSE_KEY;
+  if (!licenseKey) return;
+  try {
+    await fetch(`${API_BASE}/api/mcp/deactivate-instance`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ licenseKey, instanceId: INSTANCE_ID }),
+    });
+  } catch {
+    // Best-effort — stale pruning will clean up if this fails
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Start the server
+// ---------------------------------------------------------------------------
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Server is now running on stdio — log to stderr only
+  console.error("Glippy GEO MCP server running on stdio");
+
+  // Register graceful shutdown handlers
+  process.on("SIGTERM", async () => {
+    await deactivateInstance();
+    process.exit(0);
+  });
+  process.on("SIGINT", async () => {
+    await deactivateInstance();
+    process.exit(0);
+  });
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});