seolint-mcp 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# seolint-mcp
+
+MCP server for [SEOLint](https://seolint.dev) — scan any website for SEO issues directly from Claude.
+
+## Setup
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "seolint": {
+      "command": "npx",
+      "args": ["-y", "seolint-mcp"],
+      "env": {
+        "SEOLINT_API_KEY": "sl_your_key"
+      }
+    }
+  }
+}
+```
+
+Get your API key at [seolint.dev/dashboard](https://seolint.dev/dashboard).
+
+## Tools
+
+### scan_website
+
+Scan a URL for SEO, performance, accessibility, and AI search issues.
+
+```
+"Scan https://mysite.com for SEO issues"
+```
+
+### get_scan
+
+Retrieve results of a previous scan by ID.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+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.SEOLINT_API_URL ?? "https://seolint.dev";
+const API_KEY = process.env.SEOLINT_API_KEY ?? "";
+function headers() {
+    const h = { "Content-Type": "application/json" };
+    if (API_KEY)
+        h["Authorization"] = `Bearer ${API_KEY}`;
+    return h;
+}
+async function pollScan(scanId, maxWaitMs = 60_000) {
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        const res = await fetch(`${API_BASE}/api/v1/scan/${scanId}`, { headers: headers() });
+        if (!res.ok)
+            throw new Error(`Poll failed: ${res.status}`);
+        const data = await res.json();
+        if (data.status === "complete")
+            return data;
+        if (data.status === "error")
+            throw new Error(data.error_message ?? "Scan failed");
+        await new Promise(r => setTimeout(r, 3000));
+    }
+    throw new Error("Scan timed out after 60 seconds");
+}
+const server = new McpServer({
+    name: "seolint",
+    version: "0.1.0",
+});
+// Tool: scan a website
+server.tool("scan_website", "Scan a website for SEO, performance, accessibility, and AI search issues. Returns structured issues with LLM-ready fix instructions.", { url: z.string().describe("The full URL to scan, e.g. https://example.com") }, async ({ url }) => {
+    // Start scan
+    const startRes = await fetch(`${API_BASE}/api/v1/scan`, {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify({ url }),
+    });
+    if (!startRes.ok) {
+        const err = await startRes.json().catch(() => ({}));
+        return {
+            content: [{ type: "text", text: `Failed to start scan: ${err.error ?? startRes.statusText}` }],
+            isError: true,
+        };
+    }
+    const { scanId } = await startRes.json();
+    // Poll until complete
+    try {
+        const result = await pollScan(scanId);
+        const issues = (result.issues ?? []);
+        if (issues.length === 0) {
+            return {
+                content: [{ type: "text", text: `No issues found for ${url}. The site looks good!` }],
+            };
+        }
+        // Format as readable text with fix prompts
+        const lines = issues.map((issue, i) => {
+            return [
+                `## ${i + 1}. [${issue.severity.toUpperCase()}] ${issue.title}`,
+                `**Category:** ${issue.category}`,
+                issue.description,
+                `**Fix:** ${issue.fix}`,
+            ].join("\n");
+        });
+        const summary = `# SEO Audit: ${url}\n\n${issues.length} issues found.\n\n${lines.join("\n\n---\n\n")}`;
+        return {
+            content: [{ type: "text", text: summary }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Scan failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+// Tool: get an existing scan result
+server.tool("get_scan", "Get the results of a previous SEOLint scan by its ID.", { scanId: z.string().describe("The scan ID (UUID)") }, async ({ scanId }) => {
+    const res = await fetch(`${API_BASE}/api/v1/scan/${scanId}`, { headers: headers() });
+    if (!res.ok) {
+        return {
+            content: [{ type: "text", text: `Scan not found: ${scanId}` }],
+            isError: true,
+        };
+    }
+    const data = await res.json();
+    if (data.status === "pending") {
+        return {
+            content: [{ type: "text", text: `Scan ${scanId} is still running. Try again in a few seconds.` }],
+        };
+    }
+    if (data.status === "error") {
+        return {
+            content: [{ type: "text", text: `Scan failed: ${data.error_message ?? "Unknown error"}` }],
+            isError: true,
+        };
+    }
+    const markdown = data.markdown ?? JSON.stringify(data.issues, null, 2);
+    return {
+        content: [{ type: "text", text: markdown }],
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("SEOLint MCP server failed to start:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "seolint-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for SEOLint — scan any site for SEO issues from Claude Desktop or Claude Code",
+  "type": "module",
+  "bin": {
+    "seolint-mcp": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "seo", "claude", "seolint", "audit", "ai"],
+  "author": "Random Code",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0"
+  }
+}