@crawlseo/mcp 0.0.0-stage → 0.3.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crawlseo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @crawlseo/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP (Model Context Protocol) server for [crawlseo](https://github.com/crawlseo/crawlseo), the open-source SEO monitoring app. It lets an AI agent such as Claude Code read your sites' Search Console data, crawl issues, Core Web Vitals and SEO opportunities.
+
+**Read-only.** Every tool reads through your crawlseo instance's API (`/api/v1`) with an access key, and only sends GET requests. No tool writes, queues or triggers anything: there is no tool to start a crawl or a sync. The server never connects to a database, and the key sees the sites of its own account only.
+
+## Get a key
+
+In crawlseo, open **Settings > MCP**, turn MCP on, and create a key. The key is shown once; copy it then. Revoke it there when you no longer need it.
+
+## Claude Code
+
+Over stdio, against your own instance:
+
+```bash
+claude mcp add crawlseo -e CRAWLSEO_URL=http://localhost:3000 -e CRAWLSEO_API_KEY=<key> -- npx -y @crawlseo/mcp
+```
+
+A crawlseo instance also serves MCP itself at `/mcp`, so you may not need this package at all:
+
+```bash
+claude mcp add --transport http crawlseo https://seo.example.com/mcp --header "Authorization: Bearer <key>"
+```
+
+## Environment
+
+| Variable | Meaning |
+|---|---|
+| `CRAWLSEO_URL` | Your crawlseo instance (default `http://localhost:3000`) |
+| `CRAWLSEO_API_KEY` | An access key from Settings > MCP (stdio mode) |
+
+## HTTP mode
+
+```bash
+CRAWLSEO_URL=http://localhost:3000 npx -y @crawlseo/mcp --http --port 3333
+```
+
+Serves streamable HTTP on `http://127.0.0.1:3333/mcp` and a health check on `/health`. The server holds no key: each client sends its own as `Authorization: Bearer <key>`, and a request without a key, or with a key the instance refuses, gets 401 (403 while MCP is off for that account). `--host` changes the address it listens on (default `127.0.0.1`).
+
+## Tools
+
+| Tool | What it reads |
+|---|---|
+| `list_sites` | Your sites with their IDs and Search Console properties |
+| `get_site_overview` | Clicks, impressions, position and CTR over 28 days against the 28 before, the latest crawl and vitals |
+| `get_keywords` | Top Search Console queries, for the last N days or a date range |
+| `get_pages` | Top pages, for the last N days or a date range |
+| `get_traffic` | Daily clicks and impressions, for the last N days or a date range |
+| `list_crawls` | The latest crawls with status, pages, issues and health score |
+| `get_crawl_issues` | Issues of a crawl (the latest completed one by default), by severity |
+| `get_vitals` | Core Web Vitals reports: performance score, LCP, CLS, INP, TTFB |
+| `get_opportunities` | Striking distance, low CTR, content decay and cannibalization |
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,598 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// package.json
+var version = "0.3.5";
+
+// src/api-client.ts
+var ApiRequestError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+};
+function createApiClient(opts) {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const send2 = opts.fetch ?? ((req) => fetch(req));
+  return {
+    async get(path, query = {}) {
+      const url = new URL(`${base}/api/v1${path}`);
+      for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== "") url.searchParams.set(k, String(v));
+      let res;
+      try {
+        res = await send2(
+          new Request(url, {
+            method: "GET",
+            headers: {
+              Authorization: `Bearer ${opts.apiKey}`,
+              Accept: "application/json",
+              ...opts.userAgent && { "User-Agent": opts.userAgent }
+            },
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 3e4)
+          })
+        );
+      } catch (err) {
+        throw new ApiRequestError(0, `Could not reach crawlseo at ${base}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      const body = await res.json().catch(() => null);
+      if (!res.ok) {
+        const reason = typeof body?.error === "string" ? body.error : `HTTP ${res.status}`;
+        throw new ApiRequestError(res.status, explain(res.status, reason));
+      }
+      if (body === null) throw new ApiRequestError(res.status, `crawlseo at ${base} did not answer with JSON`);
+      return body;
+    }
+  };
+}
+function explain(status, reason) {
+  if (status === 401) return `${reason}. Check the key, or create a new one in crawlseo under Settings > MCP.`;
+  if (status === 404 && reason === "Not found") return `${reason}. Is this a crawlseo instance with the /api/v1 API?`;
+  return reason;
+}
+
+// src/http.ts
+import { createHash } from "crypto";
+import { createServer } from "http";
+
+// src/streamable.ts
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+
+// src/tools.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/formatters.ts
+function formatTable(headers, rows) {
+  const widths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
+  const sep = widths.map((w) => "-".repeat(w)).join(" | ");
+  const headerLine = headers.map((h, i) => pad(h, widths[i])).join(" | ");
+  const dataLines = rows.map(
+    (row) => row.map((cell, i) => pad(cell, widths[i])).join(" | ")
+  );
+  return [headerLine, sep, ...dataLines].join("\n");
+}
+function num(n) {
+  return n.toLocaleString("en-US");
+}
+function pct(n) {
+  return `${(n * 100).toFixed(1)}%`;
+}
+function pos(n) {
+  if (!Number.isFinite(n) || n <= 0) return "-";
+  return n.toFixed(1);
+}
+function minute(d) {
+  return d ? new Date(d).toISOString().slice(0, 16).replace("T", " ") : "-";
+}
+function period(p) {
+  return `${p.startDate} to ${p.endDate}`;
+}
+function formatSiteOverview(site) {
+  const lines = [];
+  lines.push(`Site: ${site.domain}`);
+  lines.push(`ID: ${site.id}`);
+  if (site.gscProperty) lines.push(`GSC Property: ${site.gscProperty}`);
+  lines.push("");
+  if (site.metrics) {
+    const m = site.metrics;
+    lines.push(`-- Last ${site.metricsDays ?? 28} days vs the ${site.metricsDays ?? 28} days before --`);
+    lines.push(`Clicks:      ${num(m.current.clicks)} (${m.deltas.clicks > 0 ? "+" : ""}${m.deltas.clicks}%)`);
+    lines.push(`Impressions: ${num(m.current.impressions)} (${m.deltas.impressions > 0 ? "+" : ""}${m.deltas.impressions}%)`);
+    lines.push(`Avg Position: ${pos(m.current.avgPosition)} (${m.deltas.avgPosition > 0 ? "+" : ""}${m.deltas.avgPosition.toFixed(1)} improvement)`);
+    lines.push(`Avg CTR:     ${pct(m.current.avgCtr)} (${m.deltas.avgCtr > 0 ? "+" : ""}${m.deltas.avgCtr}%)`);
+    lines.push(`Keywords:    ${num(m.current.uniqueKeywords)}`);
+  }
+  if (site.latestCrawl) {
+    const c = site.latestCrawl;
+    lines.push("");
+    lines.push("-- Latest Crawl --");
+    lines.push(`ID: ${c.id}`);
+    lines.push(`Status: ${c.status}  |  Health: ${c.healthScore ?? "-"}/100`);
+    if (c.status === "FAILED" && c.error) lines.push(`Error: ${c.error}`);
+    lines.push(`Pages: ${num(c.pagesFound)}  |  Issues: ${num(c.issuesFound)}`);
+    if (c.finishedAt) lines.push(`Finished: ${minute(c.finishedAt)}`);
+  }
+  if (site.latestVitals) {
+    const v = site.latestVitals;
+    lines.push("");
+    lines.push("-- Latest Vitals --");
+    lines.push(`Perf Score: ${v.perfScore ?? "-"}/100  |  Device: ${v.device}`);
+    if (v.lcp != null) lines.push(`LCP: ${v.lcp.toFixed(2)}s`);
+    if (v.cls != null) lines.push(`CLS: ${v.cls.toFixed(3)}`);
+    if (v.inp != null) lines.push(`INP: ${v.inp.toFixed(0)}ms`);
+    if (v.ttfb != null) lines.push(`TTFB: ${v.ttfb.toFixed(2)}s`);
+  }
+  return lines.join("\n");
+}
+function formatKeywords(keywords, p) {
+  if (keywords.length === 0) return `No keywords found for ${period(p)}.`;
+  const headers = ["Keyword", "Clicks", "Impressions", "Position", "CTR"];
+  const rows = keywords.map((k) => [
+    k.query.length > 50 ? k.query.slice(0, 47) + "..." : k.query,
+    num(k.clicks),
+    num(k.impressions),
+    pos(k.position),
+    pct(k.ctr)
+  ]);
+  return `Top ${keywords.length} keywords, ${period(p)}:
+
+` + formatTable(headers, rows);
+}
+function formatPages(pages, p) {
+  if (pages.length === 0) return `No pages found for ${period(p)}.`;
+  const headers = ["URL", "Clicks", "Impressions", "Position", "CTR"];
+  const rows = pages.map((p2) => {
+    let url = p2.url;
+    try {
+      url = new URL(p2.url).pathname;
+    } catch {
+    }
+    if (url.length > 60) url = url.slice(0, 57) + "...";
+    return [url, num(p2.clicks), num(p2.impressions), pos(p2.position), pct(p2.ctr)];
+  });
+  return `Top ${pages.length} pages, ${period(p)}:
+
+` + formatTable(headers, rows);
+}
+function formatTraffic(traffic, p) {
+  if (traffic.length === 0) return `No traffic data found for ${period(p)}.`;
+  const headers = ["Date", "Clicks", "Impressions"];
+  const rows = traffic.map((t) => [t.date, num(t.clicks), num(t.impressions)]);
+  const totalClicks = traffic.reduce((s, t) => s + t.clicks, 0);
+  const totalImpressions = traffic.reduce((s, t) => s + t.impressions, 0);
+  return `Daily traffic, ${period(p)} (${traffic.length} days with data):
+Total: ${num(totalClicks)} clicks, ${num(totalImpressions)} impressions
+
+` + formatTable(headers, rows);
+}
+function formatCrawls(crawls) {
+  if (crawls.length === 0) return "No crawls yet.";
+  const headers = ["Crawl ID", "Status", "Started", "Finished", "Pages", "Issues", "Health"];
+  const rows = crawls.map((c) => [
+    c.id,
+    c.status,
+    minute(c.startedAt),
+    minute(c.finishedAt),
+    num(c.pagesFound),
+    num(c.issuesFound),
+    c.healthScore != null ? `${c.healthScore}/100` : "-"
+  ]);
+  const failed = crawls.filter((c) => c.status === "FAILED" && c.error).map((c) => `${c.id}: ${c.error}`);
+  return `${crawls.length} crawl(s), newest first:
+
+` + formatTable(headers, rows) + (failed.length ? `
+
+Failed:
+${failed.join("\n")}` : "");
+}
+function formatCrawlIssues(result) {
+  const { crawl, total, bySeverity, noindexPages, noindexWarning, issues } = result;
+  const noindex = (noindexWarning?.message ? `WARNING: ${noindexWarning.message} The health score leaves them out.
+` : "") + (noindexPages ? `${num(noindexPages)} noindex pages crawled but not scored (no issues, not in the health score)
+` : "");
+  const head = `Crawl ${crawl.id} (${crawl.status}, finished ${minute(crawl.finishedAt)}, health ${crawl.healthScore ?? "-"}/100)
+${num(total)} issues: ${num(bySeverity.CRITICAL ?? 0)} critical, ${num(bySeverity.WARNING ?? 0)} warning, ${num(bySeverity.INFO ?? 0)} info
+` + noindex + "\n";
+  if (issues.length === 0) return head + "No crawl issues found.";
+  const headers = ["Severity", "Type", "URL", "Message"];
+  const rows = issues.map((i) => [
+    i.severity,
+    i.type,
+    i.url.length > 40 ? i.url.slice(0, 37) + "..." : i.url,
+    i.message.length > 50 ? i.message.slice(0, 47) + "..." : i.message
+  ]);
+  return head + `Showing ${issues.length}:
+
+` + formatTable(headers, rows);
+}
+function formatVitals(vitals) {
+  if (vitals.length === 0) return "No vitals reports found.";
+  const headers = ["Date", "Device", "Perf", "LCP", "CLS", "INP", "TTFB"];
+  const rows = vitals.map((v) => [
+    new Date(v.date).toISOString().slice(0, 10),
+    v.device,
+    v.perfScore != null ? String(v.perfScore) : "-",
+    v.lcp != null ? `${v.lcp.toFixed(2)}s` : "-",
+    v.cls != null ? v.cls.toFixed(3) : "-",
+    v.inp != null ? `${v.inp.toFixed(0)}ms` : "-",
+    v.ttfb != null ? `${v.ttfb.toFixed(2)}s` : "-"
+  ]);
+  return `${vitals.length} vitals reports:
+
+` + formatTable(headers, rows);
+}
+function formatOpportunities(opportunities) {
+  const lines = [];
+  const s = opportunities.summary;
+  lines.push("SEO Opportunities Summary");
+  lines.push(`Striking distance: ${s.strikingDistance} | Low CTR: ${s.lowCtr} | Content decay: ${s.contentDecay} | Cannibalization: ${s.cannibalization}`);
+  lines.push("");
+  if (opportunities.feed && opportunities.feed.length > 0) {
+    const headers = ["Type", "Severity", "Title", "Detail"];
+    const rows = opportunities.feed.map((o) => [
+      o.type,
+      o.severity,
+      (o.title || "").length > 35 ? (o.title || "").slice(0, 32) + "..." : o.title || "",
+      (o.detail || "").length > 55 ? (o.detail || "").slice(0, 52) + "..." : o.detail || ""
+    ]);
+    lines.push(formatTable(headers, rows));
+  } else {
+    lines.push("No actionable opportunities found.");
+  }
+  return lines.join("\n");
+}
+
+// src/tools.ts
+var READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var siteId = z.string().describe("The site ID, from list_sites");
+var date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "YYYY-MM-DD");
+var periodShape = {
+  days: z.number().int().min(1).max(490).optional().describe("The last N days. Ignored when startDate and endDate are set"),
+  startDate: date.optional().describe("First day, YYYY-MM-DD. Use with endDate"),
+  endDate: date.optional().describe("Last day, YYYY-MM-DD, included. Use with startDate")
+};
+function periodQuery(p) {
+  return p.startDate || p.endDate ? { startDate: p.startDate, endDate: p.endDate } : { days: p.days };
+}
+function text(t) {
+  return { content: [{ type: "text", text: t }] };
+}
+async function run(fn) {
+  try {
+    return text(await fn());
+  } catch (err) {
+    if (err instanceof ApiRequestError) return { ...text(err.message), isError: true };
+    throw err;
+  }
+}
+function registerTools(server, api) {
+  server.registerTool(
+    "list_sites",
+    {
+      title: "List sites",
+      description: "List your monitored sites with their IDs, domains and Search Console properties.",
+      inputSchema: {},
+      annotations: READ_ONLY
+    },
+    () => run(async () => {
+      const { sites } = await api.get("/sites");
+      if (sites.length === 0) return "No sites found.";
+      const lines = sites.map(
+        (s) => `${s.domain}  (id: ${s.id})
+  GSC: ${s.gscProperty ?? "not connected"}  |  Crawls: ${s.crawls}  |  Vitals reports: ${s.vitalsReports}
+  Added: ${s.createdAt.slice(0, 10)}`
+      );
+      return `${sites.length} site(s):
+
+${lines.join("\n\n")}`;
+    })
+  );
+  server.registerTool(
+    "get_site_overview",
+    {
+      title: "Site overview",
+      description: "Overview of a site: clicks, impressions, average position and CTR over the last 28 days against the 28 days before, the latest crawl with its health score, and the latest Core Web Vitals.",
+      inputSchema: { siteId },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2 }) => run(async () => {
+      const o = await api.get(`/sites/${encodeURIComponent(siteId2)}`);
+      return formatSiteOverview({ ...o.site, metricsDays: o.metricsDays, metrics: o.metrics, latestCrawl: o.latestCrawl, latestVitals: o.latestVitals });
+    })
+  );
+  server.registerTool(
+    "get_keywords",
+    {
+      title: "Search Console keywords",
+      description: "Top Google Search Console queries for a site, by clicks: clicks, impressions, average position and CTR. Default period: the last 28 days.",
+      inputSchema: {
+        siteId,
+        ...periodShape,
+        limit: z.number().int().min(1).max(1e3).optional().default(25).describe("Most keywords to return (default 25)")
+      },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2, limit, ...p }) => run(async () => {
+      const r = await api.get(
+        `/sites/${encodeURIComponent(siteId2)}/keywords`,
+        { ...periodQuery(p), limit }
+      );
+      return formatKeywords(r.keywords, r);
+    })
+  );
+  server.registerTool(
+    "get_pages",
+    {
+      title: "Search Console pages",
+      description: "Top pages of a site in Google Search Console, by clicks: clicks, impressions, average position and CTR. Default period: the last 28 days.",
+      inputSchema: {
+        siteId,
+        ...periodShape,
+        limit: z.number().int().min(1).max(1e3).optional().default(25).describe("Most pages to return (default 25)")
+      },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2, limit, ...p }) => run(async () => {
+      const r = await api.get(
+        `/sites/${encodeURIComponent(siteId2)}/pages`,
+        { ...periodQuery(p), limit }
+      );
+      return formatPages(r.pages, r);
+    })
+  );
+  server.registerTool(
+    "get_traffic",
+    {
+      title: "Daily traffic",
+      description: "Daily Search Console clicks and impressions for a site. Default period: the last 90 days.",
+      inputSchema: { siteId, ...periodShape },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2, ...p }) => run(async () => {
+      const r = await api.get(
+        `/sites/${encodeURIComponent(siteId2)}/traffic`,
+        periodQuery(p)
+      );
+      return formatTraffic(r.days, r);
+    })
+  );
+  server.registerTool(
+    "list_crawls",
+    {
+      title: "List crawls",
+      description: "The latest crawls of a site, newest first: status, pages, issues and health score. Crawls are started in crawlseo, not here.",
+      inputSchema: {
+        siteId,
+        limit: z.number().int().min(1).max(100).optional().default(10).describe("Most crawls to return (default 10)")
+      },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2, limit }) => run(async () => {
+      const r = await api.get(`/sites/${encodeURIComponent(siteId2)}/crawls`, { limit });
+      return formatCrawls(r.crawls);
+    })
+  );
+  server.registerTool(
+    "get_crawl_issues",
+    {
+      title: "Crawl issues",
+      description: "Issues a crawl found on a site (broken links, missing titles, slow pages and more), with counts per severity. noindex pages are crawled but have no issues and do not count toward the health score; the result says how many there were. Defaults to the latest completed crawl.",
+      inputSchema: {
+        siteId,
+        crawlId: z.string().optional().describe("A crawl ID from list_crawls. Default: the latest completed crawl"),
+        severity: z.enum(["CRITICAL", "WARNING", "INFO"]).optional().describe("Only this severity"),
+        limit: z.number().int().min(1).max(500).optional().default(50).describe("Most issues to return (default 50)")
+      },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2, crawlId, severity, limit }) => run(async () => {
+      const r = await api.get(
+        `/sites/${encodeURIComponent(siteId2)}/crawls/${encodeURIComponent(crawlId || "latest")}/issues`,
+        { severity, limit }
+      );
+      return formatCrawlIssues(r);
+    })
+  );
+  server.registerTool(
+    "get_vitals",
+    {
+      title: "Core Web Vitals",
+      description: "Core Web Vitals reports for a site, newest first: performance score, LCP, CLS, INP and TTFB.",
+      inputSchema: {
+        siteId,
+        device: z.enum(["MOBILE", "DESKTOP"]).optional().describe("Only this device"),
+        limit: z.number().int().min(1).max(100).optional().default(10).describe("Most reports to return (default 10)")
+      },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2, device, limit }) => run(async () => {
+      const r = await api.get(
+        `/sites/${encodeURIComponent(siteId2)}/vitals`,
+        { device, limit }
+      );
+      return formatVitals(r.reports);
+    })
+  );
+  server.registerTool(
+    "get_opportunities",
+    {
+      title: "SEO opportunities",
+      description: "SEO opportunities for a site from its Search Console data: striking-distance keywords, low-CTR keywords, content decay and keyword cannibalization.",
+      inputSchema: { siteId },
+      annotations: READ_ONLY
+    },
+    ({ siteId: siteId2 }) => run(async () => {
+      const r = await api.get(`/sites/${encodeURIComponent(siteId2)}/opportunities`);
+      return formatOpportunities(r);
+    })
+  );
+}
+function createMcpServer(api, version2) {
+  const server = new McpServer({ name: "crawlseo", version: version2 });
+  registerTools(server, api);
+  return server;
+}
+
+// src/streamable.ts
+function jsonRpcError(status, message, headers = {}) {
+  return Response.json({ jsonrpc: "2.0", error: { code: -32e3, message }, id: null }, { status, headers });
+}
+function refuseKey(status, message, headers = {}) {
+  return jsonRpcError(status, message, headers);
+}
+async function handleMcpRequest(req, api, version2) {
+  if (req.method !== "POST") return jsonRpcError(405, "Method not allowed: use POST", { Allow: "POST" });
+  const server = createMcpServer(api, version2);
+  const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: void 0, enableJsonResponse: true });
+  await server.connect(transport);
+  try {
+    return await transport.handleRequest(req);
+  } finally {
+    await server.close();
+  }
+}
+
+// src/http.ts
+var MAX_BODY_BYTES = 1e6;
+var KEY_PREFIX = "crawlseo_";
+var KEY_CACHE_MS = 6e4;
+function bearer(header) {
+  const match = header?.match(/^Bearer\s+(\S+)\s*$/i);
+  return match ? match[1] : null;
+}
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size <= MAX_BODY_BYTES) chunks.push(chunk);
+  }
+  return size > MAX_BODY_BYTES ? null : Buffer.concat(chunks);
+}
+async function send(res, response) {
+  const headers = {};
+  response.headers.forEach((value, key) => headers[key] = value);
+  res.writeHead(response.status, headers);
+  res.end(Buffer.from(await response.arrayBuffer()));
+}
+function startHttpServer(opts) {
+  const accepted = /* @__PURE__ */ new Map();
+  const userAgent = `crawlseo-mcp/${opts.version}`;
+  async function checkKey(key) {
+    if (!key.startsWith(KEY_PREFIX)) return refuseKey(401, "Invalid API key", { "WWW-Authenticate": 'Bearer error="invalid_token"' });
+    const id = createHash("sha256").update(key).digest("hex");
+    if ((accepted.get(id) ?? 0) > Date.now()) return null;
+    try {
+      await createApiClient({ baseUrl: opts.baseUrl, apiKey: key, userAgent }).get("/key");
+      if (accepted.size > 1e3) accepted.clear();
+      accepted.set(id, Date.now() + KEY_CACHE_MS);
+      return null;
+    } catch (err) {
+      accepted.delete(id);
+      if (err instanceof ApiRequestError && (err.status === 401 || err.status === 403 || err.status === 429)) {
+        return refuseKey(err.status, err.message);
+      }
+      console.error("[crawlseo-mcp] key check failed:", err instanceof Error ? err.message : err);
+      return refuseKey(502, "crawlseo could not be reached");
+    }
+  }
+  async function handle(req, res) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (url.pathname === "/health") {
+      return send(res, Response.json({ status: "ok", version: opts.version }));
+    }
+    if (url.pathname !== "/mcp") return send(res, Response.json({ error: "Not found" }, { status: 404 }));
+    const key = bearer(req.headers.authorization);
+    if (!key) return send(res, refuseKey(401, "Missing API key", { "WWW-Authenticate": "Bearer" }));
+    const refusal = await checkKey(key);
+    if (refusal) return send(res, refusal);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+      if (typeof value === "string") headers.set(name, value);
+      else if (Array.isArray(value)) headers.set(name, value.join(", "));
+    }
+    const body = req.method === "POST" ? await readBody(req) : void 0;
+    if (body === null) return send(res, refuseKey(413, "Request body too large"));
+    const webReq = new Request(new URL(url.pathname + url.search, "http://localhost"), {
+      method: req.method,
+      headers,
+      body: body ? new Uint8Array(body) : void 0
+    });
+    const api = createApiClient({ baseUrl: opts.baseUrl, apiKey: key, userAgent });
+    return send(res, await handleMcpRequest(webReq, api, opts.version));
+  }
+  const server = createServer((req, res) => {
+    handle(req, res).catch((err) => {
+      console.error("[crawlseo-mcp]", err);
+      if (!res.headersSent) res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Internal error" }));
+    });
+  });
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(opts.port, opts.host, () => resolve(server));
+  });
+}
+
+// src/cli.ts
+var USAGE = `crawlseo-mcp ${version}: read-only MCP server for crawlseo
+
+Usage:
+  crawlseo-mcp                 stdio, for an MCP client that starts the server
+  crawlseo-mcp --http          streamable HTTP on /mcp, plus /health
+
+Options (HTTP mode):
+  --port <n>                   default 3333
+  --host <address>             default 127.0.0.1
+
+Environment:
+  CRAWLSEO_URL                 your crawlseo instance (default http://localhost:3000)
+  CRAWLSEO_API_KEY             an access key from Settings > MCP (stdio mode; in HTTP
+                               mode each client sends its own key as a Bearer token)
+`;
+function option(args, name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : void 0;
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.includes("--version")) {
+    process.stdout.write(`${version}
+`);
+    return;
+  }
+  const baseUrl = process.env.CRAWLSEO_URL?.trim() || "http://localhost:3000";
+  if (args.includes("--http")) {
+    const port = Number(option(args, "--port") ?? 3333);
+    const host = option(args, "--host") ?? "127.0.0.1";
+    if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error(`Invalid --port: ${option(args, "--port")}`);
+    const server = await startHttpServer({ baseUrl, host, port, version });
+    const { port: bound } = server.address();
+    console.error(`CrawlSEO MCP server on http://${host}:${bound}/mcp, reading from ${baseUrl}`);
+    const stop = () => server.close(() => process.exit(0));
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    return;
+  }
+  const apiKey = process.env.CRAWLSEO_API_KEY?.trim();
+  if (!apiKey) {
+    console.error("CRAWLSEO_API_KEY is not set. Create an access key in crawlseo under Settings > MCP.");
+    process.exit(1);
+  }
+  const api = createApiClient({ baseUrl, apiKey, userAgent: `crawlseo-mcp/${version}` });
+  await createMcpServer(api, version).connect(new StdioServerTransport());
+  console.error(`CrawlSEO MCP server running on stdio, reading from ${baseUrl}`);
+}
+main().catch((err) => {
+  console.error("Failed to start the crawlseo MCP server:", err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@crawlseo/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.5",
+  "description": "Read-only MCP server for crawlseo: your Search Console data, crawl issues, Core Web Vitals and SEO opportunities for AI agents, through your own instance's API.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "seo",
+    "google-search-console",
+    "crawlseo"
+  ],
+  "homepage": "https://github.com/crawlseo/crawlseo#mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crawlseo/crawlseo.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "crawlseo-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "node build.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}