@abbyseo/mcp-server 0.1.0 → 0.1.1

package/README.md

@@ -10,7 +10,20 @@
 | `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.
+Free API tier returns the top 5 issues by severity; paid customers (one-time $8.99) see all checks plus a prioritized fix guide. Every check also carries a `when_doesnt_apply` field — context for when the rule legitimately doesn't apply to a site type (e.g., link aggregators deliberately omit a visible H1).
+
+## Two ways to use this
+
+1. **Remote MCP** (easier, no install) — point your client at `https://www.abbyseo.com/mcp`. The server runs on our infrastructure; you just configure the URL.
+2. **Local stdio (this npm package)** — the client launches `npx @abbyseo/mcp-server` and talks to it over stdio. Same three tools, runs in your environment, no network call until a scan is submitted.
+
+Pick remote for the lowest-friction install. Pick local if you prefer the client to spawn the server directly or want to override `ABBYSEO_API_BASE` for staging.
+
+## Install — Remote MCP (Claude Code)
+
+```bash
+claude mcp add --transport http abbyseo https://www.abbyseo.com/mcp
+```
 
 ## Install — Claude Desktop
 
@@ -29,7 +42,7 @@ Add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (m
 
 Restart Claude Desktop. You'll see the abbyseo tools appear in the tool list.
 
-## Install — Claude Code
+## Install — Claude Code (local stdio)
 
 ```bash
 claude mcp add abbyseo -- npx -y @abbyseo/mcp-server

package/dist/server.js

@@ -22,7 +22,7 @@ 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 VERSION = "0.1.1";
 const USER_AGENT = process.env.ABBYSEO_USER_AGENT || `abbyseo-mcp-server/${VERSION}`;
 const server = new McpServer({
     name: "abbyseo",
@@ -64,6 +64,7 @@ async function forwardJson(url, init = {}) {
 }
 // ---- Tool 1: submit_scan -------------------------------------------------
 server.registerTool("submit_scan", {
+    title: "Submit SEO 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.",
@@ -77,6 +78,15 @@ server.registerTool("submit_scan", {
             .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."),
     },
+    annotations: {
+        // Side effects: queues a scan job, writes a DB row, sends an email to the
+        // submitter when the scan completes. Not reversible — there's no
+        // unsubmit. Marked destructive so clients confirm before auto-invoking.
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false, // each call queues a NEW scan, even with the same args
+        openWorldHint: true, // fetches an arbitrary user-supplied URL on the public web
+    },
 }, async ({ url, email }) => {
     return forwardJson(`${API_BASE}/api/scan`, {
         method: "POST",
@@ -86,26 +96,41 @@ server.registerTool("submit_scan", {
 });
 // ---- Tool 2: get_scan_status --------------------------------------------
 server.registerTool("get_scan_status", {
+    title: "Get SEO 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."),
     },
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true, // polling: same scan_id always returns same shape
+        openWorldHint: false, // reads only our internal scan-status DB row
+    },
 }, 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. " +
+    title: "Get SEO Scan Results",
+    description: "Fetch the full structured scan findings. Free tier returns the top 5 issues by severity (failed > warned > passed); paid customers see all checks. Each check carries a `when_doesnt_apply` field — surface it for sophisticated users so they can dismiss findings that don't apply to their site type (e.g., link aggregators legitimately omit a visible H1). " +
         "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. " +
+        "(3) note `site_type` ('marketing' or 'not_marketing') and `score_rubric` so the user understands how the score was computed; non-marketing sites get contextual checks at half-weight, " +
+        "(4) if `truncated` is true, surface `truncated_message` so the user knows the API capped the output, " +
+        "(5) 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."),
     },
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true, // same scan_id always returns the same findings
+        openWorldHint: false, // reads only our internal scan-results DB row
+    },
 }, async ({ scan_id }) => {
     return forwardJson(`${API_BASE}/api/scan/${encodeURIComponent(scan_id)}`);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abbyseo/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",
@@ -25,7 +25,7 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@types/node": "^20.14.10",
+    "@types/node": "^20.19.41",
     "typescript": "5.6"
   },
   "keywords": [