glippy-mcp 0.1.0 → 0.3.0

package/src/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * Glippy MCP Server
@@ -36,6 +36,27 @@ import {
   parseSitemapUrls,
   aggregatePageScores,
 } from "./geo-checker.js";
+import { chromeFetch } from "./chrome-fetcher.js";
+
+// Render-mode: how to fetch HTML for scoring.
+//   'static' (default for tools that don't specify) - raw Node fetch, fastest
+//   'chrome'                                        - always render via headless Chrome
+//   'auto'                                          - static first, Chrome fallback on bot-block
+//
+// Chrome modes require a local Chrome/Chromium binary. Auto-resolves from
+// CHROME_PATH / PUPPETEER_EXECUTABLE_PATH / common install locations, or
+// attaches to an already-running Chrome when CHROME_REMOTE_URL is set
+// (e.g. "http://localhost:9222" after launching Chrome with
+// --remote-debugging-port=9222).
+const RENDER_MODES = ["static", "chrome", "auto"];
+
+function looksBotBlockedResponse(res) {
+  if (!res) return true;
+  if (res.statusCode == null) return true;
+  if ([401, 403, 407, 429, 503].includes(res.statusCode)) return true;
+  if (res.statusCode >= 200 && res.statusCode < 300 && !res.body) return true;
+  return false;
+}
 
 // ---------------------------------------------------------------------------
 // License validation
@@ -1597,10 +1618,15 @@ const server = new McpServer({
 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. " +
+    "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 (16 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.",
+    "The response includes a 'Trust Signal Evidence' section (htmlLang, hreflangs, nav/footer link anchor text + href). " +
+    "IMPORTANT: the Entity & Authority heuristic for about/contact/legal/imprint/cookies uses a pattern fallback. " +
+    "When the site is not in English (htmlLang != 'en' or hreflangs indicate otherwise), you (the calling LLM) should " +
+    "inspect navLinks/footerLinks semantically and override the heuristic classification in your final explanation - " +
+    "the anchor text tells you what each link is regardless of URL patterns. " +
+    "Use output_format='json' to get the full raw result (includes homepage.analysis.evidence) for programmatic use.",
   {
     domain: z
       .string()
@@ -1616,6 +1642,14 @@ server.tool(
       .describe(
         "Maximum pages to crawl (1 = homepage only, up to 10 for multi-page analysis). Defaults to 10."
       ),
+    render_mode: z
+      .enum(RENDER_MODES)
+      .optional()
+      .describe(
+        'How to fetch HTML. "static" (fast, plain Node fetch) is default for this tool. ' +
+        '"auto" tries static first and falls back to a local headless Chrome for bot-blocked responses (401/403/407/429/503 or empty 2xx). ' +
+        '"chrome" always renders via Chrome. Chrome modes need a local Chrome binary (CHROME_PATH) or an attached instance (CHROME_REMOTE_URL).'
+      ),
     output_format: z
       .enum(["text", "json"])
       .optional()
@@ -1624,10 +1658,11 @@ server.tool(
         '"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 }) => {
+  withLicense(async ({ domain, max_pages, render_mode, output_format }) => {
     try {
       const result = await checkGEO(domain, {
         maxPages: max_pages ?? 10,
+        renderMode: render_mode ?? "static",
       });
 
       if (result.error) {
@@ -1678,6 +1713,36 @@ server.tool(
           }
         }
         lines.push("");
+
+        // Trust Signal Evidence - language-agnostic raw data for LLM reclassification
+        const ev = analysis.evidence;
+        if (ev) {
+          lines.push("## Trust Signal Evidence");
+          lines.push(`htmlLang: ${ev.htmlLang || "(none)"}`);
+          if (ev.hreflangs && ev.hreflangs.length > 0) {
+            lines.push(`hreflangs: ${ev.hreflangs.slice(0, 20).join(", ")}${ev.hreflangs.length > 20 ? ` (+${ev.hreflangs.length - 20} more)` : ""}`);
+          }
+          const isNonEnglish = ev.htmlLang && !/^en(-|$)/i.test(ev.htmlLang);
+          if (isNonEnglish) {
+            lines.push(
+              `NOTE: Site is in '${ev.htmlLang}'. If the Entity & Authority category flagged missing about/contact/legal/imprint/cookies links, ` +
+              `verify against the footerLinks below - anchor text like 'Über uns', '会社概要', 'Impressum', 'Politique de confidentialité' count as trust signals ` +
+              `regardless of URL patterns. Override the heuristic if links are clearly present.`
+            );
+          }
+          const formatLink = (l) => `  - ${l.text || "(no text)"} -> ${l.href}`;
+          if (ev.footerLinks && ev.footerLinks.length > 0) {
+            lines.push(`footerLinks (${ev.footerLinks.length}):`);
+            ev.footerLinks.slice(0, 40).forEach((l) => lines.push(formatLink(l)));
+            if (ev.footerLinks.length > 40) lines.push(`  ... (+${ev.footerLinks.length - 40} more)`);
+          }
+          if (ev.navLinks && ev.navLinks.length > 0) {
+            lines.push(`navLinks (${ev.navLinks.length}):`);
+            ev.navLinks.slice(0, 30).forEach((l) => lines.push(formatLink(l)));
+            if (ev.navLinks.length > 30) lines.push(`  ... (+${ev.navLinks.length - 30} more)`);
+          }
+          lines.push("");
+        }
       }
 
       // robots.txt
@@ -1941,17 +2006,28 @@ server.tool(
 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.",
+    "Use this for a quick overview; use analyze_domain for full details including the Trust Signal Evidence payload " +
+    "(raw nav/footer links for LLM-driven semantic classification on non-English sites).",
   {
     domain: z
       .string()
       .describe(
         'The domain to check, e.g. "example.com". Do not include https:// prefix.'
       ),
+    render_mode: z
+      .enum(RENDER_MODES)
+      .optional()
+      .describe(
+        'How to fetch the homepage. "static" (default), "auto" (static with Chrome fallback on bot-block), ' +
+        'or "chrome" (always render via local headless Chrome).'
+      ),
   },
-  withLicense(async ({ domain }) => {
+  withLicense(async ({ domain, render_mode }) => {
     try {
-      const result = await checkGEO(domain, { maxPages: 1 });
+      const result = await checkGEO(domain, {
+        maxPages: 1,
+        renderMode: render_mode ?? "static",
+      });
 
       if (result.error) {
         return {
@@ -1987,6 +2063,15 @@ server.tool(
       lines.push(`# GEO Summary: ${result.domain}`);
       lines.push(`Overall Score: ${analysis.overallScore}% (${grade})`);
       lines.push(`Page Type: ${analysis.pageType}`);
+      const evLang = analysis.evidence?.htmlLang;
+      if (evLang) {
+        lines.push(`Site Language: ${evLang}`);
+        if (!/^en(-|$)/i.test(evLang)) {
+          lines.push(
+            `(Non-English site - use analyze_domain for the footerLinks evidence payload to reclassify trust signals semantically.)`
+          );
+        }
+      }
       lines.push("");
 
       // Sort categories by score
@@ -2071,6 +2156,13 @@ server.tool(
       .describe(
         "Maximum pages to crawl per domain (1 = homepage only). Defaults to 10."
       ),
+    render_mode: z
+      .enum(RENDER_MODES)
+      .optional()
+      .describe(
+        'How to fetch HTML for each domain. "static" (default), "auto" (static with Chrome fallback on bot-block), ' +
+        'or "chrome" (always render via local headless Chrome).'
+      ),
     output_format: z
       .enum(["text", "json"])
       .optional()
@@ -2082,13 +2174,14 @@ server.tool(
   withTierFeature(
     "compareDomains",
     "Domain comparison requires a Pro or Agency license.",
-    async ({ domains, max_pages, output_format }) => {
+    async ({ domains, max_pages, render_mode, output_format }) => {
     const maxPages = max_pages ?? 10;
+    const renderMode = render_mode ?? "static";
 
     // Run all analyses in parallel
     const results = await Promise.allSettled(
       domains.map((domain) =>
-        checkGEO(domain, { maxPages }).then((result) => ({
+        checkGEO(domain, { maxPages, renderMode }).then((result) => ({
           domain,
           result,
         }))
@@ -2240,7 +2333,7 @@ const DEFAULT_RATE_LIMIT = parseInt(process.env.GLIPPY_RATE_LIMIT, 10) || 5;
  * @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) {
+async function analyseUrls(urls, concurrency = 3, domainRateLimit = DEFAULT_RATE_LIMIT, renderMode = "static") {
   // Group URLs by domain
   const domainMap = new Map(); // domain → [urls]
   for (const url of urls) {
@@ -2318,13 +2411,34 @@ async function analyseUrls(urls, concurrency = 3, domainRateLimit = DEFAULT_RATE
           try {
             const pathname = new URL(url).pathname;
             const meta = domainMeta.get(domain);
-            const res = await throttledFetchUrl(url, 15000);
+            let res;
+            let rendered = "static";
+            if (renderMode === "chrome") {
+              res = await chromeFetch(url, 30000);
+              rendered = "chrome";
+            } else {
+              res = await throttledFetchUrl(url, 15000);
+              if (renderMode === "auto" && looksBotBlockedResponse(res)) {
+                const chromeRes = await chromeFetch(url, 30000).catch(() => null);
+                if (
+                  chromeRes &&
+                  typeof chromeRes.statusCode === "number" &&
+                  chromeRes.statusCode >= 200 &&
+                  chromeRes.statusCode < 300 &&
+                  chromeRes.body
+                ) {
+                  res = chromeRes;
+                  rendered = "chrome-fallback";
+                }
+              }
+            }
 
-            if (res.statusCode !== 200 || !res.body) {
+            if (!res || res.statusCode == null || res.statusCode < 200 || res.statusCode >= 300 || !res.body) {
               return {
                 url,
                 analysis: null,
-                error: res.statusCode ? `HTTP ${res.statusCode}` : "Failed to fetch",
+                error: res && res.statusCode ? `HTTP ${res.statusCode}` : "Failed to fetch",
+                renderMode: rendered,
               };
             }
 
@@ -2337,7 +2451,7 @@ async function analyseUrls(urls, concurrency = 3, domainRateLimit = DEFAULT_RATE
               pathname
             );
 
-            return { url, analysis, error: null };
+            return { url, analysis, error: null, renderMode: rendered };
           } catch (err) {
             return { url, analysis: null, error: err.message };
           }
@@ -2453,6 +2567,13 @@ server.tool(
         "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."
       ),
+    render_mode: z
+      .enum(RENDER_MODES)
+      .optional()
+      .describe(
+        'How to fetch each URL. "static" (default), "auto" (static with Chrome fallback on bot-block), ' +
+        'or "chrome" (always render via local headless Chrome).'
+      ),
     output_format: z
       .enum(["text", "json", "summary"])
       .optional()
@@ -2480,7 +2601,7 @@ server.tool(
         "Recommended: 10-20 for detailed results to stay within output limits."
       ),
   },
-  withLicense(async ({ sitemap_url, max_urls, rate_limit, output_format, offset, limit }) => {
+  withLicense(async ({ sitemap_url, max_urls, rate_limit, render_mode, output_format, offset, limit }) => {
     const features = getFeatures();
 
     // Check if sitemap analysis is available for this tier
@@ -2555,7 +2676,7 @@ server.tool(
 
       // Analyse all URLs with rate limiting
       const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
-      const { pageResults } = await analyseUrls(urlsToAnalyse, 3, rateLimit);
+      const { pageResults } = await analyseUrls(urlsToAnalyse, 3, rateLimit, render_mode ?? "static");
       const aggregated = aggregatePageScores(pageResults);
 
       // Summary output mode - compact JSON with minimal page info (ideal for large sitemaps)
@@ -2665,6 +2786,13 @@ server.tool(
         "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."
       ),
+    render_mode: z
+      .enum(RENDER_MODES)
+      .optional()
+      .describe(
+        'How to fetch each URL. "static" (default), "auto" (static with Chrome fallback on bot-block), ' +
+        'or "chrome" (always render via local headless Chrome).'
+      ),
     output_format: z
       .enum(["text", "json", "summary"])
       .optional()
@@ -2692,7 +2820,7 @@ server.tool(
         "Recommended: 10-20 for detailed results to stay within output limits."
       ),
   },
-  withLicense(async ({ urls, rate_limit, output_format, offset, limit }) => {
+  withLicense(async ({ urls, rate_limit, render_mode, output_format, offset, limit }) => {
     const features = getFeatures();
 
     // Check if batch analysis is available for this tier
@@ -2721,7 +2849,7 @@ server.tool(
 
     try {
       const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
-      const { pageResults } = await analyseUrls(urls, 3, rateLimit);
+      const { pageResults } = await analyseUrls(urls, 3, rateLimit, render_mode ?? "static");
       const aggregated = aggregatePageScores(pageResults);
 
       // Summary output mode - compact JSON with minimal page info (ideal for large batches)
@@ -2834,6 +2962,13 @@ server.tool(
         "Maximum pages to crawl (1 = homepage only, up to 10 for multi-page analysis). Defaults to 10. " +
         "Ignored if analysis_result is provided."
       ),
+    render_mode: z
+      .enum(RENDER_MODES)
+      .optional()
+      .describe(
+        'How to fetch HTML. "static" (default), "auto" (static with Chrome fallback on bot-block), ' +
+        'or "chrome" (always render via local headless Chrome). Ignored if analysis_result is provided.'
+      ),
     analysis_result: z
       .object({})
       .passthrough()
@@ -2844,7 +2979,7 @@ server.tool(
         "and export in multiple formats without redundant crawling."
       ),
   },
-  withLicense(async ({ domain, format, max_pages, analysis_result }) => {
+  withLicense(async ({ domain, format, max_pages, render_mode, analysis_result }) => {
     try {
       let result;
 
@@ -2866,6 +3001,7 @@ server.tool(
         // Run fresh analysis (may use cache automatically)
         result = await checkGEO(domain, {
           maxPages: max_pages ?? 10,
+          renderMode: render_mode ?? "static",
         });
       } else {
         return {
@@ -3003,11 +3139,19 @@ server.tool(
       .describe(
         "Max requests/second per domain for URL/sitemap modes. Defaults to 5. Ignored if analysis_results provided."
       ),
+    render_mode: z
+      .enum(RENDER_MODES)
+      .optional()
+      .describe(
+        'How to fetch HTML. "static" (default), "auto" (static with Chrome fallback on bot-block), ' +
+        'or "chrome" (always render via local headless Chrome). 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 }) => {
+    async ({ format, domains, urls, sitemap_url, analysis_results, max_pages, max_urls, rate_limit, render_mode }) => {
+    const renderMode = render_mode ?? "static";
     // Validate: exactly one input mode
     const modes = [domains, urls, sitemap_url, analysis_results].filter(Boolean).length;
     if (modes !== 1) {
@@ -3116,7 +3260,7 @@ server.tool(
         const maxPages = max_pages ?? 10;
         const results = await Promise.allSettled(
           domains.map((domain) =>
-            checkGEO(domain, { maxPages }).then((result) => ({
+            checkGEO(domain, { maxPages, renderMode }).then((result) => ({
               domain,
               result,
             }))
@@ -3173,7 +3317,7 @@ server.tool(
       // ------------------------------------------------------------------
       if (urls) {
         const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
-        const { pageResults } = await analyseUrls(urls, 3, rateLimit);
+        const { pageResults } = await analyseUrls(urls, 3, rateLimit, renderMode);
         const aggregated = aggregatePageScores(pageResults);
         const title = `${urls.length} URLs`;
 
@@ -3239,7 +3383,7 @@ server.tool(
 
         const urlsToAnalyse = allUrls.slice(0, max_urls ?? 50000);
         const rateLimit = rate_limit ?? DEFAULT_RATE_LIMIT;
-        const { pageResults } = await analyseUrls(urlsToAnalyse, 3, rateLimit);
+        const { pageResults } = await analyseUrls(urlsToAnalyse, 3, rateLimit, renderMode);
         const aggregated = aggregatePageScores(pageResults);
         const title = `Sitemap: ${sitemap_url} (${urlsToAnalyse.length} of ${allUrls.length} URLs)`;