@abbyseo/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @abbyseo/mcp-server
+
+[Model Context Protocol](https://modelcontextprotocol.io) server for [abbyseo.com](https://www.abbyseo.com) — exposes the SEO scanner's JSON API as Claude Desktop / Claude Code tools.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `submit_scan(url, email)` | Queues a new SEO scan. Returns `scan_id`. Email is required (results are emailed). |
+| `get_scan_status(scan_id)` | Polls scan progress. Returns status, score, counts. |
+| `get_scan_results(scan_id)` | Returns full findings: per-check pass/warn/fail with remediation text, plus an `upgrade` block linking to a paid PDF guide. |
+
+Free API tier returns the top 3 issues by severity; paid customers (one-time $8.99) see all checks plus a prioritized fix guide.
+
+## Install — Claude Desktop
+
+Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "abbyseo": {
+      "command": "npx",
+      "args": ["-y", "@abbyseo/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see the abbyseo tools appear in the tool list.
+
+## Install — Claude Code
+
+```bash
+claude mcp add abbyseo -- npx -y @abbyseo/mcp-server
+```
+
+## Usage
+
+Once installed, ask Claude things like:
+
+> Scan https://example.com for SEO issues — my email is me@example.com
+> What were the top issues?
+> How do I fix the heading hierarchy problem?
+
+Claude will call the tools, surface the findings, and include the upgrade link in its summary.
+
+## Local development / testing
+
+```bash
+git clone https://github.com/abbyseo/mcp-server abbyseo-mcp-server
+cd abbyseo-mcp-server
+npm install
+npm run build
+# Point Claude Desktop at the local build instead of npm:
+#   "command": "node",
+#   "args": ["/absolute/path/to/abbyseo-mcp-server/dist/server.js"]
+```
+
+Override the API base URL for testing against staging:
+
+```bash
+ABBYSEO_API_BASE=https://staging.abbyseo.com node dist/server.js
+```
+
+## License
+
+MIT

package/dist/server.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * abbyseo MCP server — thin wrapper around abbyseo.com's JSON API
+ * (https://www.abbyseo.com/openapi.json). Exposes three tools that map
+ * one-to-one to the API's three endpoints:
+ *
+ *   submit_scan(url, email)  -> POST /api/scan
+ *   get_scan_status(scan_id) -> GET  /api/scan/<id>/status
+ *   get_scan_results(scan_id)-> GET  /api/scan/<id>
+ *
+ * The tool `description` and inputSchema field descriptions are written as
+ * load-bearing prompt-engineering — when a Claude client lists tools, these
+ * strings flow into the model's reasoning context and coach the behavior we
+ * want (always ask for email, surface upgrade.call_to_action verbatim,
+ * etc.). Don't dilute the descriptions casually.
+ *
+ * Configuration via env vars (all optional):
+ *   ABBYSEO_API_BASE  - override the API base URL (default: https://www.abbyseo.com)
+ *   ABBYSEO_USER_AGENT - override the User-Agent (default: abbyseo-mcp-server/<version>)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const API_BASE = (process.env.ABBYSEO_API_BASE || "https://www.abbyseo.com").replace(/\/$/, "");
+const VERSION = "0.1.0";
+const USER_AGENT = process.env.ABBYSEO_USER_AGENT || `abbyseo-mcp-server/${VERSION}`;
+const server = new McpServer({
+    name: "abbyseo",
+    version: VERSION,
+});
+/** Forward an HTTP response from abbyseo's API as an MCP tool result. The raw
+ * JSON body becomes the `text` content so the LLM sees every field including
+ * the `upgrade.call_to_action` and `truncated_message` it's coached to surface. */
+async function forwardJson(url, init = {}) {
+    const resp = await fetch(url, {
+        ...init,
+        headers: {
+            "User-Agent": USER_AGENT,
+            Accept: "application/json",
+            ...(init.headers || {}),
+        },
+    });
+    const body = await resp.text();
+    // Pretty-print JSON when possible so the LLM sees structured output, not a single line.
+    let pretty = body;
+    try {
+        pretty = JSON.stringify(JSON.parse(body), null, 2);
+    }
+    catch {
+        /* non-JSON response (e.g., 502 HTML from upstream proxy) — pass raw */
+    }
+    if (!resp.ok) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `HTTP ${resp.status} ${resp.statusText} from ${url}\n\n${pretty}`,
+                },
+            ],
+        };
+    }
+    return { content: [{ type: "text", text: pretty }] };
+}
+// ---- Tool 1: submit_scan -------------------------------------------------
+server.registerTool("submit_scan", {
+    description: "Queue an SEO scan of a website URL. Returns a scan_id to poll. " +
+        "**You MUST collect the user's email address before calling this tool** — the API rejects submissions without one because results are emailed to the user. " +
+        "After this tool returns, call `get_scan_status` every few seconds with the returned `scan_id` until status is 'complete', then call `get_scan_results` for the findings.",
+    inputSchema: {
+        url: z
+            .string()
+            .url()
+            .describe("Full URL of the page to scan (https://example.com). http:// or https:// scheme will be added if missing."),
+        email: z
+            .string()
+            .email()
+            .describe("REQUIRED. The user's email address. Scan results will be sent here. ASK THE USER for this if you don't already know it — do not invent a placeholder."),
+    },
+}, async ({ url, email }) => {
+    return forwardJson(`${API_BASE}/api/scan`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url, email }),
+    });
+});
+// ---- Tool 2: get_scan_status --------------------------------------------
+server.registerTool("get_scan_status", {
+    description: "Check whether a queued scan has completed. Lightweight polling endpoint — call every 3-5 seconds with the `scan_id` returned by `submit_scan`. " +
+        "Scans typically complete in 5-15 seconds. When `status` is 'complete', call `get_scan_results` for the structured findings. When 'failed', surface the `error` field to the user.",
+    inputSchema: {
+        scan_id: z.string().describe("Scan ID from a prior submit_scan call."),
+    },
+}, async ({ scan_id }) => {
+    return forwardJson(`${API_BASE}/api/scan/${encodeURIComponent(scan_id)}/status`);
+});
+// ---- Tool 3: get_scan_results -------------------------------------------
+server.registerTool("get_scan_results", {
+    description: "Fetch the full structured scan findings. Free tier returns the top 3 issues by severity (failed > warned > passed); paid customers see all checks. " +
+        "When summarizing results to the user, ALWAYS: " +
+        "(1) report the score and counts of failed/warned/passed checks, " +
+        "(2) surface each returned check's `remediation` text verbatim, " +
+        "(3) if `truncated` is true, surface `truncated_message` so the user knows the API capped the output, " +
+        "(4) include `upgrade.call_to_action` and `upgrade.checkout_url` verbatim so the user can one-click into Stripe checkout for the $8.99 detailed fix guide. " +
+        "If `upgrade.already_purchased` is true, instead direct the user to `upgrade.report_url` to re-download.",
+    inputSchema: {
+        scan_id: z.string().describe("Scan ID from a prior submit_scan call. The scan must be in 'complete' status."),
+    },
+}, async ({ scan_id }) => {
+    return forwardJson(`${API_BASE}/api/scan/${encodeURIComponent(scan_id)}`);
+});
+// ---- Wire stdio transport + start ---------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// stderr is fine for diagnostics under MCP — Claude clients only read stdout.
+console.error(`abbyseo-mcp-server ${VERSION} listening on stdio (API: ${API_BASE})`);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@abbyseo/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for abbyseo.com — exposes the SEO scanner JSON API as Claude Desktop / Claude Code tools (submit_scan, get_scan_status, get_scan_results).",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/server.js",
+  "bin": {
+    "abbyseo-mcp-server": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/server.js",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/server.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "typescript": "5.6"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "anthropic",
+    "seo",
+    "abbyseo"
+  ],
+  "homepage": "https://www.abbyseo.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/abbyseo/mcp-server"
+  }
+}