@rankcli/mcp-server 0.0.1 → 0.0.3

package/README.md

@@ -1,24 +1,12 @@
 # @rankcli/mcp-server
 
-**MCP Server for AI Assistants to perform SEO analysis.**
-
-The industry's first SEO tool accessible via Model Context Protocol. Let Claude, GPT, and other AI assistants run comprehensive SEO audits directly.
-
-## What is MCP?
-
-[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is Anthropic's standard for connecting AI assistants to external tools. This server exposes RankCLI's full SEO analysis capabilities to AI.
-
-## Installation
+Free, local SEO + GEO (AI-search-citation) analysis as an MCP tool. No signup, no API key, nothing sent to RankCLI's servers — it runs entirely inside your MCP host (Claude Code, Claude Desktop, Cursor, etc.) against HTML you already have or that your host fetches for you.
 
 ```bash
-npm install -g @rankcli/mcp-server
+npx @rankcli/mcp-server
 ```
 
-## Configuration
-
-### Claude Desktop
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+**Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
@@ -31,90 +19,53 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
-Restart Claude Desktop. You'll now have SEO tools available.
-
-### Other MCP Clients
-
-Run the server directly:
-
-```bash
-npx @rankcli/mcp-server
-```
-
-The server communicates via stdio using JSON-RPC.
-
 ## Available Tools
 
-### `seo_analyze`
-**Full comprehensive SEO audit.** Returns scores for GEO, Core Web Vitals, Security, Structured Data, Images, Links, and Mobile.
-
-### `seo_geo_check`
-**GEO (Generative Engine Optimization).** Check AI crawler access, JS rendering, LLM signals, citation readiness.
-
-### `seo_robots_ai`
-**Analyze robots.txt for AI crawlers.** Shows which AI crawlers (GPTBot, ClaudeBot, PerplexityBot) are allowed/blocked.
-
-### `seo_generate_robots`
-**Generate AI-friendly robots.txt.** Creates rules allowing all major AI crawlers.
-
-### `seo_core_web_vitals`
-**Estimate Core Web Vitals.** LCP, CLS, INP, TTFB from HTML analysis.
-
-### `seo_structured_data`
-**Validate JSON-LD schemas.** Check Article, Product, FAQ, HowTo, LocalBusiness, BreadcrumbList.
+| Tool | Description |
+|------|-------------|
+| `seo_analyze` | Full SEO analysis: GEO, Core Web Vitals, structured data, security headers, mobile, images, internal linking |
+| `seo_geo_check` | AI search visibility (GEO) — crawler access, LLM content signals, citation readiness |
+| `seo_robots_ai` | Which AI crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.) your robots.txt allows or blocks |
+| `seo_generate_robots` | Generate an AI-crawler-friendly robots.txt |
+| `seo_core_web_vitals` | Estimate LCP, CLS, INP, TTFB from HTML |
+| `seo_structured_data` | Validate JSON-LD / Schema.org markup |
+| `seo_generate_schema` | Generate a JSON-LD template for a page type |
+| `seo_security_headers` | Grade HTTPS, HSTS, CSP, and related headers |
+| `seo_generate_security_headers` | Generate recommended security header config |
+| `seo_images` | Alt text, dimensions, formats, lazy loading |
+| `seo_internal_links` | Anchor text quality, orphan-page risk |
+| `seo_mobile` | Viewport, touch targets, PWA readiness |
+| `seo_ai_crawlers` | Reference list of known AI crawler user agents |
 
-### `seo_generate_schema`
-**Generate schema templates.** For article, product, faq, local-business, website.
+## Example
 
-### `seo_security_headers`
-**Analyze security headers.** HTTPS, HSTS, CSP with A+ to F grading.
+Just ask Claude:
 
-### `seo_generate_security_headers`
-**Generate recommended security headers.**
+> "Run an SEO audit on https://example.com"
 
-### `seo_images`
-**Image optimization analysis.** Alt text, dimensions, formats, lazy loading.
+Your MCP host fetches the page and Claude calls these tools directly — nothing round-trips through RankCLI.
 
-### `seo_internal_links`
-**Internal linking analysis.** Anchor text quality, orphan detection.
+## Want more?
 
-### `seo_mobile`
-**Mobile SEO analysis.** Viewport, touch targets, PWA readiness.
+This local server works from HTML/robots.txt you or your MCP host supply. For **URL-only tools that fetch and crawl for you** (`seo_audit`, `seo_geo_check`, `seo_robots_check`, `seo_compare`), plus the newer Cloudflare AI-crawler-gating compliance check, CI/CD scheduling, and auto-fix PRs, see the hosted endpoint and paid tiers:
 
-### `seo_ai_crawlers`
-**AI crawler reference.** Information about all known AI crawlers.
-
-## Example Usage
-
-Once configured, ask Claude:
-
-> "Run a comprehensive SEO audit on https://example.com"
-
-> "Check if my site is visible to ChatGPT and other AI search engines"
-
-> "Generate an AI-friendly robots.txt for my domain"
-
-> "What structured data should I add to my blog posts?"
-
-Claude will use the appropriate tools to analyze and respond.
-
-## Why This Matters
-
-1. **AI doing SEO**: Your AI assistant can now audit sites, generate fixes, and monitor SEO.
-2. **Meta-optimization**: Make sure YOUR site is visible to AI crawlers—checked by AI.
-3. **Developer workflow**: Ask Claude to audit during code review or deployment.
-
-## Requirements
-
-- Node.js 18+
-- An MCP-compatible AI assistant (Claude Desktop, etc.)
-
-## Related
+```json
+{
+  "mcpServers": {
+    "rankcli-hosted": {
+      "url": "https://rankcli-audit-worker.fly.dev/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
 
-- [RankCLI CLI](https://www.npmjs.com/package/@rankcli/cli) - Command-line SEO tool
-- [RankCLI Website](https://rankcli.dev) - Full documentation
-- [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol
+Get a free API key at [rankcli.dev/dashboard](https://rankcli.dev/dashboard).
 
-## License
+## Links
 
-MIT
+- **Main package**: [@rankcli/cli](https://www.npmjs.com/package/@rankcli/cli)
+- **Docs**: [rankcli.dev/docs](https://rankcli.dev/docs)
+- **Dashboard**: [rankcli.dev/dashboard](https://rankcli.dev/dashboard)

package/dist/index.js

@@ -7,7 +7,10 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
+import Conf from "conf";
 import { analyzers } from "@rankcli/agent-runtime";
+var SUPABASE_URL = process.env.RANKCLI_SUPABASE_URL || "https://bspljbxwbjiqueeyzyat.supabase.co";
+var localConfig = new Conf({ projectName: "rankcli" });
 var TOOLS = [
   {
     name: "seo_analyze",
@@ -269,6 +272,22 @@ Critical for visibility in ChatGPT, Perplexity, Claude, and Gemini responses.`,
       type: "object",
       properties: {}
     }
+  },
+  {
+    name: "rankcli_connect",
+    description: `Link this AI assistant to a RankCLI account (rankcli.dev). This is the only tool in this server that contacts rankcli.dev, and only when you call it - every other tool runs fully locally. Connecting unlocks GitHub auto-fix PRs, scheduled monitoring, and a dashboard with history across audits; it does not change how the other tools work. Opens a browser tab for the user to approve (or reuses an existing session if already logged in). Safe to call anytime - if already connected, it just reports who's connected.`,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "rankcli_disconnect",
+    description: `Unlink this AI assistant from its RankCLI account. Only affects this local connection - does not delete the RankCLI account or revoke other API keys.`,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
   }
 ];
 var server = new Server(
@@ -442,6 +461,27 @@ ${Object.entries(headers).map(([k, v]) => `**${k}:**
           ]
         };
       }
+      case "rankcli_connect": {
+        const result = await connectToRankCLI();
+        return {
+          content: [{ type: "text", text: result.text }],
+          ...result.isError ? { isError: true } : {}
+        };
+      }
+      case "rankcli_disconnect": {
+        const wasConnected = !!localConfig.get("apiKey");
+        localConfig.delete("apiKey");
+        localConfig.delete("apiKeyName");
+        localConfig.delete("email");
+        return {
+          content: [
+            {
+              type: "text",
+              text: wasConnected ? "Disconnected. This assistant no longer has access to your RankCLI dashboard." : "Not connected - nothing to do."
+            }
+          ]
+        };
+      }
       default:
         return {
           content: [{ type: "text", text: `Unknown tool: ${name}` }],
@@ -460,6 +500,124 @@ ${Object.entries(headers).map(([k, v]) => `**${k}:**
     };
   }
 });
+var BRIDGE_FOOTER = `
+---
+*This ran locally with no signup. For GitHub auto-fix PRs, scheduled monitoring, and a dashboard with history across audits, call the rankcli_connect tool or create a free account at [rankcli.dev](https://rankcli.dev).*`;
+async function pollConnectStatus(connectId, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 2e3));
+    try {
+      const res = await fetch(`${SUPABASE_URL}/functions/v1/mcp-connect-status`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ connectId })
+      });
+      const data = await res.json();
+      if (data.status === "claimed") {
+        return { email: data.email, apiKey: data.apiKey, apiKeyName: data.apiKeyName };
+      }
+      if (data.status === "expired" || data.status === "not_found") {
+        return null;
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function backgroundAwaitConnect(connectId) {
+  pollConnectStatus(connectId, 5 * 6e4).then(async (claimed) => {
+    if (claimed) {
+      localConfig.set("apiKey", claimed.apiKey);
+      localConfig.set("apiKeyName", claimed.apiKeyName);
+      localConfig.set("email", claimed.email);
+      if (localConfig.get("pendingConnectId") === connectId) clearPendingConnect();
+    }
+    await server.createElicitationCompletionNotifier(connectId)().catch(() => {
+    });
+  }).catch((err) => {
+    console.error("rankcli_connect: background poll failed:", err);
+  });
+}
+function clearPendingConnect() {
+  localConfig.delete("pendingConnectId");
+  localConfig.delete("pendingConnectUrl");
+  localConfig.delete("pendingConnectExpiresAt");
+}
+async function connectToRankCLI() {
+  const existingKey = localConfig.get("apiKey");
+  if (existingKey) {
+    const email = localConfig.get("email") || "your account";
+    return { text: `Already connected as ${email}. Run rankcli_disconnect first to switch accounts.` };
+  }
+  const pendingId = localConfig.get("pendingConnectId");
+  const pendingUrl = localConfig.get("pendingConnectUrl");
+  const pendingExpiresAt = localConfig.get("pendingConnectExpiresAt");
+  if (pendingId && pendingUrl && pendingExpiresAt) {
+    if (Date.now() >= pendingExpiresAt) {
+      clearPendingConnect();
+    } else {
+      const claimed = await pollConnectStatus(pendingId, 3e3);
+      if (claimed) {
+        localConfig.set("apiKey", claimed.apiKey);
+        localConfig.set("apiKeyName", claimed.apiKeyName);
+        localConfig.set("email", claimed.email);
+        clearPendingConnect();
+        return { text: `Connected as ${claimed.email}! Your dashboard, GitHub auto-fix PRs, and audit history are now linked to this AI assistant.` };
+      }
+      const minutesLeft = Math.max(1, Math.round((pendingExpiresAt - Date.now()) / 6e4));
+      return {
+        text: `Still waiting for approval. Open this link if you haven't yet, then run rankcli_connect again:
+
+${pendingUrl}
+
+Expires in ${minutesLeft} minute${minutesLeft === 1 ? "" : "s"}.`
+      };
+    }
+  }
+  let startData;
+  try {
+    const startRes = await fetch(`${SUPABASE_URL}/functions/v1/mcp-connect-start`, { method: "POST" });
+    if (!startRes.ok) throw new Error(`status ${startRes.status}`);
+    startData = await startRes.json();
+  } catch (err) {
+    return {
+      text: `Could not reach rankcli.dev to start the connection (${err instanceof Error ? err.message : "network error"}). Try again in a moment.`,
+      isError: true
+    };
+  }
+  const { connectId, url, expiresInSeconds } = startData;
+  const expiresMinutes = Math.round(expiresInSeconds / 60);
+  localConfig.set("pendingConnectId", connectId);
+  localConfig.set("pendingConnectUrl", url);
+  localConfig.set("pendingConnectExpiresAt", Date.now() + expiresInSeconds * 1e3);
+  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.",
+        url,
+        elicitationId: connectId
+      });
+      if (result.action === "accept") {
+        backgroundAwaitConnect(connectId);
+        return { text: "Opening rankcli.dev to connect your account - I'll let you know as soon as it's done." };
+      }
+      clearPendingConnect();
+      return { text: "Connection cancelled." };
+    } catch (err) {
+      console.error("rankcli_connect: elicitation failed, falling back to link:", err);
+    }
+  }
+  return {
+    text: `Open this link to connect your RankCLI account:
+
+${url}
+
+Then run rankcli_connect again to finish (link expires in ${expiresMinutes} minutes).`
+  };
+}
 function formatComprehensiveResult(result) {
   const criticalIssues = result.allIssues.filter((i) => i.severity === "critical");
   const warnings = result.allIssues.filter((i) => i.severity === "warning");
@@ -495,6 +653,7 @@ ${warnings.slice(0, 5).map((i) => `- **${i.title}:** ${i.description}`).join("\n
 ## Priority Recommendations
 
 ${result.prioritizedRecommendations.map((r, i) => `${i + 1}. ${r}`).join("\n")}
+${BRIDGE_FOOTER}
 `;
 }
 function formatGEOResult(result) {
@@ -535,6 +694,7 @@ Trust Signals: ${result.citationReadiness.trustSignals.join(", ") || "None detec
 ## Recommendations
 
 ${result.recommendations.map((r) => `- ${r}`).join("\n")}
+${BRIDGE_FOOTER}
 `;
 }
 function formatCWVResult(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rankcli/mcp-server",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "MCP (Model Context Protocol) server for RankCLI SEO analysis",
   "type": "module",
   "main": "dist/index.js",
@@ -26,8 +26,9 @@
   "author": "Integrallis",
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "@rankcli/agent-runtime": "^0.0.11"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@rankcli/agent-runtime": "^0.0.17",
+    "conf": "^12.0.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",