linkaudit-mcp 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# linkaudit-mcp
+
+MCP server for [LinkAudit](https://linkaudit.app) — scan any website's AI-search visibility (ChatGPT, Perplexity, Gemini) from inside Claude, Cursor, or your CI pipeline.
+
+Perplexity's citation check is **measured**, not estimated: it sends real, unbranded buyer questions to the live Perplexity API and checks whether the domain actually gets cited. Everything else in the scan is clearly labelled measured or estimated — never presented as more certain than it is.
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add linkaudit -- npx -y linkaudit-mcp
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "linkaudit": {
+      "command": "npx",
+      "args": ["-y", "linkaudit-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "linkaudit": {
+      "command": "npx",
+      "args": ["-y", "linkaudit-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `run_scan` | Full AI-visibility scan: SEO/GEO scores, per-engine ChatGPT/Perplexity/Gemini visibility, top-priority fixes. |
+| `get_fix_pack` | Ready-to-paste files: robots.txt, schema, sitemap, llms.txt, agents.json — built only from real data on the page. |
+| `check_citability` | Is this page "citable" by AI engines? Answer-first structure, quotable passages, question-led headings, FAQ schema. |
+| `check_perplexity_citations` | Measured check: does Perplexity actually cite this domain for real buyer questions? |
+
+Anonymous use shares the same free-scan limit as linkaudit.app/scan (it's your own machine's IP). Set `LINKAUDIT_API_KEY` for a higher limit once you have one.
+
+## CI: lint your GEO score
+
+```bash
+npx linkaudit-mcp lint https://example.com --min-geo 70 --min-citability 60
+```
+
+Exits non-zero (and prints the failing checks) if either score is below the threshold — drop it into a GitHub Actions step to gate merges on AI-search visibility the same way you gate on tests.
+
+```yaml
+- name: Check AI-search visibility
+  run: npx linkaudit-mcp lint https://your-site.com --min-geo 70
+```
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `LINKAUDIT_API_BASE` | `https://linkaudit.app` | API base URL |
+| `LINKAUDIT_API_KEY` | *(none)* | Optional bearer token, forwarded as `Authorization` |
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+
+if (args[0] === 'lint') {
+  require('../src/lint')
+    .lint(args.slice(1))
+    .catch((err) => {
+      console.error(err.message);
+      process.exitCode = 1;
+    });
+} else if (args[0] === '--help' || args[0] === '-h') {
+  console.log(`linkaudit-mcp — MCP server + CLI for LinkAudit (linkaudit.app)
+
+Usage:
+  linkaudit-mcp                              Start the MCP server on stdio
+  linkaudit-mcp lint <url> [options]         Run a one-off GEO/citability check
+
+Lint options:
+  --min-geo <N>          Exit non-zero if the GEO score is below N
+  --min-citability <N>   Exit non-zero if the citability score is below N
+
+Env:
+  LINKAUDIT_API_BASE     API base URL (default: https://linkaudit.app)
+  LINKAUDIT_API_KEY      Optional bearer token, forwarded as Authorization
+
+See https://linkaudit.app/learn/mcp.html for setup with Claude Code, Claude
+Desktop, and Cursor.`);
+} else {
+  require('../src/server')
+    .start()
+    .catch((err) => {
+      console.error('LinkAudit MCP server failed to start:', err.message);
+      process.exitCode = 1;
+    });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "linkaudit-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for LinkAudit — scan any website's AI-search visibility (ChatGPT, Perplexity, Gemini), get ready-to-paste fix files, and lint GEO/citability scores in CI.",
+  "type": "commonjs",
+  "bin": {
+    "linkaudit-mcp": "./bin/cli.js"
+  },
+  "main": "src/server.js",
+  "files": ["bin", "src", "README.md"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "seo",
+    "geo",
+    "generative-engine-optimization",
+    "ai-search",
+    "chatgpt",
+    "perplexity",
+    "claude",
+    "linkaudit"
+  ],
+  "homepage": "https://linkaudit.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RohanRatwani/linkaudit_landing",
+    "directory": "mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,60 @@
+/**
+ * Thin client over LinkAudit's public /api/scan endpoint. No scan logic is
+ * duplicated here — every tool in this package calls the same live API a
+ * browser user hits at linkaudit.app/scan.
+ *
+ * Anonymous calls are subject to the same per-IP free-scan limit as the web
+ * UI (this runs from the developer's own machine, so that's the expected,
+ * fair behavior — not a workaround). Setting LINKAUDIT_API_KEY raises that
+ * limit once API-key auth is wired up server-side (not yet — v0.1 tolerates
+ * its absence entirely).
+ */
+
+const API_BASE = process.env.LINKAUDIT_API_BASE || 'https://linkaudit.app';
+const API_KEY = process.env.LINKAUDIT_API_KEY || null;
+
+// Small in-memory cache so a single MCP session calling run_scan, then
+// get_fix_pack, then check_citability on the same URL doesn't pay for three
+// separate scans — each tool independently calls runScan() and slices what
+// it needs from the same result.
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const cache = new Map(); // url -> { result, ts }
+
+/**
+ * @param {string} url
+ * @param {{ roast?: boolean }} [opts] - roast defaults to false: it costs an
+ *   extra AI call and none of the four tools need the joke text.
+ * @returns {Promise<Object>} the full /api/scan response
+ */
+async function runScan(url, { roast = false } = {}) {
+  const cached = cache.get(url);
+  if (cached && Date.now() - cached.ts < CACHE_TTL_MS) return cached.result;
+
+  const headers = { 'Content-Type': 'application/json' };
+  if (API_KEY) headers.Authorization = `Bearer ${API_KEY}`;
+
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/scan`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ url, includeGeo: true, roast }),
+    });
+  } catch (err) {
+    throw new Error(`Could not reach ${API_BASE}: ${err.message}`);
+  }
+
+  const data = await res.json().catch(() => ({}));
+
+  if (!res.ok || data.success === false) {
+    const err = new Error(data.error || `Scan failed (HTTP ${res.status})`);
+    err.rateLimited = !!data.rate_limited;
+    err.status = res.status;
+    throw err;
+  }
+
+  cache.set(url, { result: data, ts: Date.now() });
+  return data;
+}
+
+module.exports = { runScan, API_BASE };

package/src/lint.js

@@ -0,0 +1,66 @@
+/**
+ * `linkaudit-mcp lint <url>` — CI-friendly GEO/citability check. Prints the
+ * top-priority findings and exits non-zero if either score falls below the
+ * given threshold, so a build can gate on AI-search visibility the same way
+ * it gates on tests or lint.
+ */
+
+const { runScan } = require('./client');
+
+function parseArgs(argv) {
+  const url = argv[0];
+  let minGeo = 0;
+  let minCitability = 0;
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === '--min-geo') minGeo = Number(argv[++i]) || 0;
+    if (argv[i] === '--min-citability') minCitability = Number(argv[++i]) || 0;
+  }
+  return { url, minGeo, minCitability };
+}
+
+async function lint(argv) {
+  const { url, minGeo, minCitability } = parseArgs(argv);
+  if (!url) {
+    console.error('Usage: linkaudit-mcp lint <url> [--min-geo N] [--min-citability N]');
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`Scanning ${url} ...`);
+  let r;
+  try {
+    r = await runScan(url);
+  } catch (err) {
+    console.error(`Scan failed: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const geoScore = r.scores?.geo_overall ?? 0;
+  const citabilityScore = r.agents?.geo_citation?.citability?.score ?? 0;
+
+  console.log(`\nGEO score: ${geoScore}/100   Citability: ${citabilityScore}/100\n`);
+  console.log('Fix these first:');
+  const top = (r.top_priorities || []).slice(0, 5);
+  if (!top.length) {
+    console.log('  (none — nothing found, or the scan degraded to defaults)');
+  }
+  top.forEach((rec, i) => {
+    console.log(`  ${i + 1}. [${rec.impact || '?'} impact / ${rec.effort || '?'} effort] ${rec.title || rec.message}`);
+    if (rec.fix) console.log(`     -> ${rec.fix}`);
+  });
+
+  const failures = [];
+  if (minGeo && geoScore < minGeo) failures.push(`GEO score ${geoScore} is below the required ${minGeo}`);
+  if (minCitability && citabilityScore < minCitability) failures.push(`Citability score ${citabilityScore} is below the required ${minCitability}`);
+
+  if (failures.length) {
+    console.error(`\nFAILED:\n  - ${failures.join('\n  - ')}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log('\nOK — thresholds met.');
+}
+
+module.exports = { lint };

package/src/server.js

@@ -0,0 +1,159 @@
+/**
+ * LinkAudit MCP server (stdio). Registers four tools, each a thin slice of
+ * the same /api/scan response — see client.js for the shared fetch + cache.
+ */
+
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod');
+const { runScan, API_BASE } = require('./client');
+
+function attribution(url) {
+  return `\n\nFull report: ${API_BASE}/scan?url=${encodeURIComponent(url)}&utm_source=mcp`;
+}
+
+function textResult(obj, url) {
+  return { content: [{ type: 'text', text: JSON.stringify(obj, null, 2) + attribution(url) }] };
+}
+
+function errorResult(err) {
+  const text = err.rateLimited
+    ? `${err.message} (LinkAudit's free-scan limit was reached for this IP — try again later, or sign in at linkaudit.app for more scans.)`
+    : err.message;
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+function registerTools(server) {
+  server.registerTool(
+    'run_scan',
+    {
+      description:
+        "Scan a website and return its AI-visibility scores: traditional SEO, GEO (Generative Engine Optimization), and per-engine ChatGPT/Perplexity/Gemini visibility. Perplexity's number is MEASURED (a real, unbranded citation check against the live Perplexity API), the others are estimated from page signals and labelled as such. Also returns the top-priority fixes, ranked by impact for least effort.",
+      inputSchema: { url: z.string().url().describe('The URL to scan, e.g. https://example.com') },
+    },
+    async ({ url }) => {
+      try {
+        const r = await runScan(url);
+        return textResult(
+          {
+            url: r.url,
+            domain: r.domain,
+            scan_id: r.scan_id,
+            scores: r.scores,
+            ai_visibility: r.ai_visibility
+              ? {
+                  ai_visibility_score: r.ai_visibility.ai_visibility_score,
+                  grade: r.ai_visibility.grade,
+                  ai_engines: r.ai_visibility.ai_engines,
+                }
+              : null,
+            top_priorities: r.top_priorities,
+          },
+          url,
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'get_fix_pack',
+    {
+      description:
+        'Get ready-to-paste fix files for a website: robots.txt, schema markup, sitemap, llms.txt, and an agents.json manifest that lets AI agents read the business\'s services/hours/FAQ directly. Every file is built only from data actually found on the page — nothing is invented.',
+      inputSchema: { url: z.string().url().describe('The URL to build a fix pack for') },
+    },
+    async ({ url }) => {
+      try {
+        const r = await runScan(url);
+        return textResult(
+          {
+            url: r.url,
+            domain: r.domain,
+            files: (r.fix_pack?.files || []).map((f) => ({
+              id: f.id,
+              filename: f.filename,
+              title: f.title,
+              status: f.status, // 'add' | 'improve' | 'ok'
+              place_at: f.place_at,
+              why: f.why,
+              sop: f.sop,
+              contents: f.contents,
+            })),
+          },
+          url,
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'check_citability',
+    {
+      description:
+        'Check whether a page is "citable" by AI answer engines: does it answer-first, contain self-contained quotable passages, use question-led headings, and carry FAQ schema? Returns a 0-100 sub-score plus the specific failing rules with fixes.',
+      inputSchema: { url: z.string().url() },
+    },
+    async ({ url }) => {
+      try {
+        const r = await runScan(url);
+        return textResult(
+          {
+            url: r.url,
+            geo_score: r.scores?.geo_overall ?? null,
+            citability: r.agents?.geo_citation?.citability || null,
+          },
+          url,
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'check_perplexity_citations',
+    {
+      description:
+        'A MEASURED (not estimated) check of whether Perplexity actually cites this domain: sends real, unbranded buyer questions to the live Perplexity Sonar API and checks whether the domain appears in the citations Perplexity actually returned. Reports cited/not-cited, share of voice, and which competing sources got cited instead.',
+      inputSchema: { url: z.string().url() },
+    },
+    async ({ url }) => {
+      try {
+        const r = await runScan(url);
+        const measured = r.ai_visibility?.ai_engines?.perplexity;
+        const probe = r.ai_probe?.probes?.perplexity_citation;
+        return textResult(
+          {
+            url: r.url,
+            measured: !!measured?.measured,
+            cited: measured?.cited ?? probe?.cited ?? null,
+            share_of_voice: measured?.share_of_voice ?? probe?.share_of_voice ?? null,
+            queries_tested: probe?.queries_tested ?? null,
+            queries_citing: probe?.queries_citing ?? null,
+            sample_query: probe?.sample_query ?? null,
+            sources: probe?.sources || [],
+            reason: measured?.reason || probe?.reason || null,
+          },
+          url,
+        );
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}
+
+async function start() {
+  const server = new McpServer({ name: 'linkaudit', version: '0.1.0' });
+  registerTools(server);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('LinkAudit MCP server running on stdio');
+}
+
+module.exports = { start, registerTools };