@rankcli/mcp-server 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @rankcli/mcp-server
 
-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.
+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. The one exception is `rankcli_connect`, an explicit opt-in tool that links this server to a RankCLI account.
 
 ```bash
 npx @rankcli/mcp-server
@@ -36,6 +36,12 @@ npx @rankcli/mcp-server
 | `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 |
+| `rankcli_connect` | Link this server to a RankCLI account for GitHub auto-fix PRs, scheduled monitoring, and a dashboard with audit history. Opens a browser tab to approve; the only tool here that contacts rankcli.dev |
+| `rankcli_disconnect` | Unlink this server from your RankCLI account (local only — doesn't touch the account itself) |
+
+## Connecting your account
+
+Ask Claude to "connect my RankCLI account," or call `rankcli_connect` directly. It opens rankcli.dev in your browser to approve (or asks for permission first, on MCP hosts that support that inline) - once approved, this server and the `rankcli` CLI on the same machine both use the connection, with nothing further to configure. It works the same on the free plan: connect a BYOK AI provider key at [rankcli.dev/account?tab=ai-provider](https://rankcli.dev/account?tab=ai-provider) and auto-fix PRs run on your own key at no cost, including several providers with genuinely free tiers.
 
 ## Example
 

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}` }],
@@ -462,7 +502,122 @@ ${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, create a free account at [rankcli.dev](https://rankcli.dev).*`;
+*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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rankcli/mcp-server",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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.17"
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@rankcli/agent-runtime": "^0.0.17",
+    "conf": "^12.0.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",