@rankcli/mcp-server 0.0.8 → 0.0.9

package/dist/{chunk-JSSECRCS.js → chunk-FJ2K7KRV.js}

@@ -5,15 +5,122 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { analyzers } from "@rankcli/agent-runtime";
-async function fetchHtml(url) {
-  const res = await fetch(url, {
-    headers: { "User-Agent": "RankCLI/1.0 (+https://rankcli.dev)" }
-  });
+
+// src/fetch-guard.ts
+import { lookup } from "dns/promises";
+import { isIP } from "net";
+var USER_AGENT = "RankCLI/1.0 (+https://rankcli.dev)";
+var MAX_REDIRECTS = 5;
+var TIMEOUT_MS = 15e3;
+function ipv4ToInt(ip) {
+  return ip.split(".").reduce((acc, part) => (acc << 8) + Number(part), 0) >>> 0;
+}
+function inV4(ip, cidr) {
+  const [base, bits] = cidr.split("/");
+  const mask = Number(bits) === 0 ? 0 : ~0 << 32 - Number(bits) >>> 0;
+  return (ipv4ToInt(ip) & mask) === (ipv4ToInt(base) & mask);
+}
+var BLOCKED_V4 = [
+  "0.0.0.0/8",
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "127.0.0.0/8",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.0.0.0/24",
+  "192.168.0.0/16",
+  "198.18.0.0/15",
+  "224.0.0.0/4",
+  "240.0.0.0/4"
+];
+function isPrivateAddress(ip) {
+  const version = isIP(ip);
+  if (version === 4) return BLOCKED_V4.some((cidr) => inV4(ip, cidr));
+  if (version === 6) {
+    const v6 = ip.toLowerCase();
+    const mapped = v6.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mapped) return isPrivateAddress(mapped[1]);
+    if (v6 === "::" || v6 === "::1") return true;
+    const first = parseInt(v6.split(":")[0] || "0", 16);
+    if ((first & 65024) === 64512) return true;
+    if ((first & 65472) === 65152) return true;
+    if ((first & 65280) === 65280) return true;
+    return false;
+  }
+  return true;
+}
+async function assertPublicUrl(url) {
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".internal") || host.endsWith(".local")) {
+    throw new Error(`Refusing to fetch ${url.origin}: private network address`);
+  }
+  const addresses = isIP(host) ? [{ address: host }] : await lookup(host, { all: true, verbatim: true });
+  if (addresses.length === 0 || addresses.some((a) => isPrivateAddress(a.address))) {
+    throw new Error(`Refusing to fetch ${url.origin}: private network address`);
+  }
+}
+async function guardedFetch(rawUrl, options = {}) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    throw new Error(`Invalid URL: ${rawUrl}`);
+  }
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new Error(`Refusing to fetch ${url.protocol} URL - only http(s) is supported`);
+    }
+    if (options.blockPrivateNetworks) await assertPublicUrl(url);
+    const response = await fetch(url, {
+      headers: { "User-Agent": USER_AGENT },
+      redirect: options.blockPrivateNetworks ? "manual" : "follow",
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+    const location = response.headers.get("location");
+    if (options.blockPrivateNetworks && response.status >= 300 && response.status < 400 && location) {
+      url = new URL(location, url);
+      continue;
+    }
+    return response;
+  }
+  throw new Error(`Too many redirects fetching ${rawUrl}`);
+}
+
+// src/server.ts
+async function fetchHtml(url, options = {}) {
+  const res = await guardedFetch(url, options);
   if (!res.ok) {
     throw new Error(`Fetching ${url} returned ${res.status} ${res.statusText}`);
   }
   return res.text();
 }
+async function fetchRobotsTxt(pageUrl, options = {}) {
+  let robotsUrl;
+  try {
+    robotsUrl = new URL("/robots.txt", pageUrl).href;
+  } catch {
+    return { note: "robots.txt not checked: invalid URL." };
+  }
+  try {
+    const res = await guardedFetch(robotsUrl, options);
+    if (res.ok) {
+      return { content: await res.text(), note: `robots.txt fetched from ${robotsUrl}.` };
+    }
+    if (res.status >= 500 || res.status === 429) {
+      return {
+        unknown: true,
+        note: `robots.txt returned HTTP ${res.status}, so crawler access is unknown - Google treats a 5xx robots.txt as "disallow everything" until it answers.`
+      };
+    }
+    return { note: `No robots.txt (HTTP ${res.status}) - every crawler is allowed by default.` };
+  } catch (error) {
+    return { unknown: true, note: `robots.txt could not be fetched (${error instanceof Error ? error.message : String(error)}), so crawler access is unknown.` };
+  }
+}
+async function resolveRobotsTxt(url, provided, options) {
+  if (provided !== void 0) return { content: provided, note: "robots.txt as provided." };
+  return fetchRobotsTxt(url, options);
+}
 var ANALYSIS_TOOLS = [
   {
     name: "seo_analyze",
@@ -40,7 +147,7 @@ Use this for a complete SEO audit.`,
         },
         robotsTxt: {
           type: "string",
-          description: "robots.txt content for AI crawler analysis (optional)"
+          description: "robots.txt content (optional - fetched from the site when omitted)"
         }
       },
       required: ["url"]
@@ -68,11 +175,11 @@ Critical for visibility in ChatGPT, Perplexity, Claude, and Gemini responses.`,
         },
         html: {
           type: "string",
-          description: "HTML content of the page"
+          description: "HTML content of the page (optional - fetched from the URL when omitted)"
         },
         robotsTxt: {
           type: "string",
-          description: "robots.txt content"
+          description: "robots.txt content (optional - fetched from the site when omitted)"
         }
       },
       required: ["url"]
@@ -318,7 +425,9 @@ ${result.prioritizedRecommendations.map((r, i) => `${i + 1}. ${r}`).join("\n")}
 ${BRIDGE_FOOTER}
 `;
 }
-function formatGEOResult(result) {
+function formatGEOResult(result, robots) {
+  const access = robots.unknown ? `| \u2754 Unknown | ${robots.note} |` : `| \u2705 Allowed | ${result.aiCrawlerAccess.allowedCrawlers.join(", ") || "None"} |
+| \u274C Blocked | ${result.aiCrawlerAccess.blockedCrawlers.join(", ") || "None"} |`;
   return `# GEO Analysis (AI Search Optimization)
 
 **Score:** ${result.score}/100
@@ -327,8 +436,9 @@ function formatGEOResult(result) {
 
 | Status | Crawlers |
 |--------|----------|
-| \u2705 Allowed | ${result.aiCrawlerAccess.allowedCrawlers.join(", ") || "None"} |
-| \u274C Blocked | ${result.aiCrawlerAccess.blockedCrawlers.join(", ") || "None"} |
+${access}
+
+_${robots.note}_
 
 **Server-Side Rendered:** ${result.aiCrawlerAccess.serverSideRendered ? "\u2705 Yes" : "\u274C No"}
 **JS Rendering Required:** ${result.aiCrawlerAccess.jsRenderingRequired ? "\u26A0\uFE0F Yes (AI crawlers may not see content)" : "\u2705 No"}
@@ -539,19 +649,27 @@ Allow: /
 \`\`\`
 `;
 }
-async function handleAnalysisTool(name, args) {
+async function handleAnalysisTool(name, args, options = {}) {
   switch (name) {
     case "seo_analyze": {
       const { url, html: providedHtml, robotsTxt } = args;
-      const html = providedHtml ?? await fetchHtml(url);
-      const result = await analyzers.analyzeComprehensive(html, url, { robotsTxt });
-      return { content: [{ type: "text", text: formatComprehensiveResult(result) }] };
+      const [html, robots] = await Promise.all([
+        providedHtml ?? fetchHtml(url, options),
+        resolveRobotsTxt(url, robotsTxt, options)
+      ]);
+      const result = await analyzers.analyzeComprehensive(html, url, { robotsTxt: robots.content });
+      return { content: [{ type: "text", text: `${formatComprehensiveResult(result)}
+_${robots.note}_
+` }] };
     }
     case "seo_geo_check": {
       const { url, html: providedHtml, robotsTxt } = args;
-      const html = providedHtml ?? await fetchHtml(url);
-      const result = await analyzers.analyzeGEO(html, url, robotsTxt);
-      return { content: [{ type: "text", text: formatGEOResult(result) }] };
+      const [html, robots] = await Promise.all([
+        providedHtml ?? fetchHtml(url, options),
+        resolveRobotsTxt(url, robotsTxt, options)
+      ]);
+      const result = await analyzers.analyzeGEO(html, url, robots.content);
+      return { content: [{ type: "text", text: formatGEOResult(result, robots) }] };
     }
     case "seo_robots_ai": {
       const { robotsTxt } = args;
@@ -652,7 +770,7 @@ ${Object.entries(headers).map(([k, v]) => `**${k}:**
       return void 0;
   }
 }
-function createAnalysisServer() {
+function createAnalysisServer(options = {}) {
   const server = new Server(
     { name: "rankcli", version: "0.0.1" },
     { capabilities: { tools: {} } }
@@ -663,7 +781,7 @@ function createAnalysisServer() {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-      const result = await handleAnalysisTool(name, args);
+      const result = await handleAnalysisTool(name, args, options);
       if (result) return result;
       return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
     } catch (error) {
@@ -677,7 +795,9 @@ function createAnalysisServer() {
 }
 
 export {
+  isPrivateAddress,
   fetchHtml,
+  fetchRobotsTxt,
   ANALYSIS_TOOLS,
   handleAnalysisTool,
   createAnalysisServer

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   ANALYSIS_TOOLS,
   handleAnalysisTool
-} from "./chunk-JSSECRCS.js";
+} from "./chunk-FJ2K7KRV.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -118,6 +118,12 @@ function clearPendingConnect() {
   localConfig.delete("pendingConnectId");
   localConfig.delete("pendingConnectUrl");
   localConfig.delete("pendingConnectExpiresAt");
+  localConfig.delete("pendingConnectCode");
+}
+function codeLine(userCode) {
+  return userCode ? `
+
+Approve only if the page shows this code: ${userCode}` : "";
 }
 async function connectToRankCLI() {
   const existingKey = localConfig.get("apiKey");
@@ -144,7 +150,7 @@ async function connectToRankCLI() {
       return {
         text: `Still waiting for approval. Open this link if you haven't yet, then run rankcli_connect again:
 
-${pendingUrl}
+${pendingUrl}${codeLine(localConfig.get("pendingConnectCode"))}
 
 Expires in ${minutesLeft} minute${minutesLeft === 1 ? "" : "s"}.`
       };
@@ -161,17 +167,18 @@ Expires in ${minutesLeft} minute${minutesLeft === 1 ? "" : "s"}.`
       isError: true
     };
   }
-  const { connectId, url, expiresInSeconds } = startData;
+  const { connectId, userCode, url, expiresInSeconds } = startData;
   const expiresMinutes = Math.round(expiresInSeconds / 60);
   localConfig.set("pendingConnectId", connectId);
   localConfig.set("pendingConnectUrl", url);
   localConfig.set("pendingConnectExpiresAt", Date.now() + expiresInSeconds * 1e3);
+  if (userCode) localConfig.set("pendingConnectCode", userCode);
   const supportsUrlElicitation = !!server.getClientCapabilities()?.elicitation?.url;
   if (supportsUrlElicitation) {
     try {
       const result = await server.elicitInput({
         mode: "url",
-        message: "Connect your RankCLI account to enable GitHub auto-fix PRs, scheduled monitoring, and a dashboard with audit history.",
+        message: `Connect your RankCLI account to enable GitHub auto-fix PRs, scheduled monitoring, and a dashboard with audit history.${codeLine(userCode)}`,
         url,
         elicitationId: connectId
       });
@@ -195,7 +202,7 @@ Expires in ${minutesLeft} minute${minutesLeft === 1 ? "" : "s"}.`
   return {
     text: `Open this link to connect your RankCLI account:
 
-${url}
+${url}${codeLine(userCode)}
 
 Then run rankcli_connect again to finish (link expires in ${expiresMinutes} minutes).`
   };

package/dist/server.d.ts

@@ -1,6 +1,13 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 
+interface FetchGuardOptions {
+    /** Refuse loopback, private, link-local, CGNAT and metadata addresses. */
+    blockPrivateNetworks?: boolean;
+}
+/** Loopback, private, link-local, CGNAT, multicast/reserved - anything not on the public internet. */
+declare function isPrivateAddress(ip: string): boolean;
+
 /**
  * Shared, stateless SEO/GEO analysis tools - the part of the RankCLI MCP
  * server that's safe to run anywhere, local stdio process or a shared
@@ -11,19 +18,39 @@ import { Tool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
  * via local file storage.
  */
 
-declare function fetchHtml(url: string): Promise<string>;
+/** Options for the analysis tools. Everything defaults off, for local stdio use. */
+type AnalysisServerOptions = FetchGuardOptions;
+declare function fetchHtml(url: string, options?: AnalysisServerOptions): Promise<string>;
+interface RobotsTxtResult {
+    /** robots.txt body when the site served one (2xx). */
+    content?: string;
+    /** One line for the report: what was found, or why crawler access is unknown. */
+    note: string;
+    /** robots.txt couldn't be read (5xx, 429, network) - access is not known. */
+    unknown?: boolean;
+}
+/**
+ * The site's own robots.txt. seo_geo_check / seo_analyze used to skip this
+ * unless the caller pasted robots.txt in, and then reported every AI
+ * crawler as "allowed" - even on sites that block them all.
+ */
+declare function fetchRobotsTxt(pageUrl: string, options?: AnalysisServerOptions): Promise<RobotsTxtResult>;
 declare const ANALYSIS_TOOLS: Tool[];
 /**
  * Handles a single analysis tool call. Returns undefined if `name` isn't
  * one of ANALYSIS_TOOLS, so callers (index.ts's stdio server) can fall
  * through to their own additional tools.
  */
-declare function handleAnalysisTool(name: string, args: Record<string, unknown> | undefined): Promise<CallToolResult | undefined>;
+declare function handleAnalysisTool(name: string, args: Record<string, unknown> | undefined, options?: AnalysisServerOptions): Promise<CallToolResult | undefined>;
 /**
  * A fresh Server exposing only the stateless analysis tools - used by the
  * remote HTTP endpoint, one instance per request (see packages/audit-worker),
  * matching the MCP SDK's own stateless-server example.
+ *
+ * A shared deployment should pass { blockPrivateNetworks: true } so callers
+ * can't point the fetching tools at internal addresses. Off by default: the
+ * local stdio server auditing http://localhost:3000 is a feature.
  */
-declare function createAnalysisServer(): Server;
+declare function createAnalysisServer(options?: AnalysisServerOptions): Server;
 
-export { ANALYSIS_TOOLS, createAnalysisServer, fetchHtml, handleAnalysisTool };
+export { ANALYSIS_TOOLS, type AnalysisServerOptions, type FetchGuardOptions, type RobotsTxtResult, createAnalysisServer, fetchHtml, fetchRobotsTxt, handleAnalysisTool, isPrivateAddress };

package/dist/server.js

@@ -2,11 +2,15 @@ import {
   ANALYSIS_TOOLS,
   createAnalysisServer,
   fetchHtml,
-  handleAnalysisTool
-} from "./chunk-JSSECRCS.js";
+  fetchRobotsTxt,
+  handleAnalysisTool,
+  isPrivateAddress
+} from "./chunk-FJ2K7KRV.js";
 export {
   ANALYSIS_TOOLS,
   createAnalysisServer,
   fetchHtml,
-  handleAnalysisTool
+  fetchRobotsTxt,
+  handleAnalysisTool,
+  isPrivateAddress
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rankcli/mcp-server",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "mcpName": "io.github.integrallis/rankcli-mcp-server",
   "description": "Free, local SEO + GEO (AI-search-citation) analysis for AI assistants - audits GEO/AI-crawler access, Core Web Vitals, structured data, security headers, mobile, and images with no signup or API key.",
   "type": "module",
@@ -23,7 +23,7 @@
     "build": "tsup src/index.ts src/server.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts src/server.ts --format esm --watch",
     "typecheck": "tsc --noEmit",
-    "test": "echo 'No tests yet'",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -51,12 +51,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@rankcli/agent-runtime": "^0.0.20",
+    "@rankcli/agent-runtime": "^0.0.21",
     "conf": "^12.0.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
   },
   "files": [
     "dist"