zevian-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zevian
+
+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

@@ -0,0 +1,189 @@
+# Zevian for AI coding agents
+
+`zevian-mcp` connects your AI coding agent (Claude Code, Cursor, VS Code) to [Zevian](https://zevian.tech).
+Ask your agent to audit your site, check a page on **localhost** before you deploy it, and fix what it finds,
+all without leaving your editor.
+
+- **Audit** a connected site, or one page of it, and read the issues (errors, warnings and info).
+- **Check a page before you deploy.** Your agent fetches localhost, staging or any unpublished page from
+  *your* machine and Zevian analyzes it. Zevian never fetches your localhost.
+- **Fix it two ways.** Get exact instructions your agent applies in your own repository, or have Zevian's
+  GitHub App open a pull request for you.
+- **See what the fixes achieved** in Search Console and Bing.
+
+## Set up in three minutes
+
+You need Node.js 20 or newer and a Zevian account.
+
+1. **Create an API key.** In the Zevian dashboard, open **Connect to your AI agent** (or go to
+   `app.zevian.tech/settings/api`), name the key, and choose *Read* or *Read + write*. Copy it: it is shown
+   once. *Read + write* is only needed to let the agent open pull requests.
+2. **Add Zevian to your agent.** Replace `zv_live_YOUR_KEY` with your key. The dashboard shows each of these
+   with your key already filled in.
+
+### Claude Code
+
+macOS, Linux and WSL:
+
+```bash
+claude mcp add --env ZEVIAN_API_KEY=zv_live_YOUR_KEY --transport stdio zevian -- npx -y zevian-mcp
+```
+
+Windows (PowerShell or cmd):
+
+```bash
+claude mcp add --env ZEVIAN_API_KEY=zv_live_YOUR_KEY --transport stdio zevian -- cmd /c npx -y zevian-mcp
+```
+
+Then start Claude Code and type /fix-seo, or ask it to audit your site with Zevian.
+
+### Cursor
+
+Save this as `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` to use it everywhere:
+
+```json
+{
+  "mcpServers": {
+    "zevian": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "zevian-mcp"
+      ],
+      "env": {
+        "ZEVIAN_API_KEY": "zv_live_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Add the file to `.gitignore` if it is in your project, so the key is not committed. Then make sure Zevian is
+switched on under Customize in the sidebar.
+
+### VS Code
+
+Save this as `.vscode/mcp.json` in your project, or run **MCP: Open User Configuration** to use it everywhere:
+
+```json
+{
+  "servers": {
+    "zevian": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "zevian-mcp"
+      ],
+      "env": {
+        "ZEVIAN_API_KEY": "zv_live_YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+Add the file to `.gitignore` if it is in your project, so the key is not committed. Then start the server from
+the Zevian entry in the file, trust it when VS Code asks, and ask in the Chat view with an agent, so it can
+call Zevian's tools.
+
+## Try it
+
+Three things to ask your agent:
+
+1. **"Audit my site with Zevian and fix the errors and warnings."** (Or type `/fix-seo`.) The agent finds
+   your site, runs an audit, shows you what is wrong, and applies each fix in your repository.
+2. **"Check http://localhost:3000/pricing with Zevian before I deploy."** The agent fetches the page from your
+   machine, Zevian lists the problems with their fixes, and the agent can apply them.
+3. **"Open a pull request that fixes the schema issues from that audit."** The agent shows you which issues it
+   will fix and waits for your yes, then Zevian's GitHub App opens one pull request.
+
+## Tools
+
+Your agent picks these itself. Each one tells the agent when to use it.
+
+| Tool | Use it to | Reads or changes |
+|---|---|---|
+| `list_sites` | List your connected sites. The agent calls this first, to get a `site_id`. | Reads |
+| `run_audit` | Audit a site (`scope: "full"`) or one page of it (`scope: "page"`, with `url`). Waits about 45 seconds, then returns an `audit_id` to follow up with `get_audit`. | Starts a crawl; changes nothing on your site |
+| `get_audit` | Read an audit: status, scores, and issues worst first, filtered by `severity` (error, warning, info) or `category` (seo, geo, aeo, schema). | Reads |
+| `get_fix` | Get instructions for fixing one issue: the kind of change, which files to look in, exact target values and limits. Instructions, not a diff. | Reads |
+| `open_fix_pr` | Open one pull request that fixes 1 to 20 issues. The agent asks you to confirm first. Waits about 45 seconds, then returns a `pr_id`. Needs a *Read + write* key. | **Changes your repository** |
+| `get_fix_pr` | Check a pull request started by `open_fix_pr`: its status, its URL once open, and why it failed if it did. | Reads |
+| `check_page` | Check one page, including localhost and staging. Returns the page's issues, each with its fix. | Reads |
+| `get_impact` | Search Console and Bing performance, and the before and after of each merged Zevian pull request. Paid plans. | Reads |
+
+And one prompt, **`fix-seo`** (a slash command in Claude Code and similar agents), which audits the site,
+shows you the errors and warnings, applies each fix in the current repository, and summarizes what changed.
+It takes an optional `domain`.
+
+## What `check_page` sends, and what it never does
+
+`check_page` fetches the page **from your machine**, follows redirects, waits up to 15 seconds, and reads at
+most 2 MB of HTML. Then it sends Zevian the page's URL, status, HTML and response headers, so Zevian can
+analyze it. In that step:
+
+- **No cookies, ever.** The request to your page carries no `Cookie` or `Authorization` header, and nothing is
+  stored between calls.
+- **Credentials are removed before anything leaves your machine.** The response headers `Set-Cookie`,
+  `Cookie`, `Authorization` and `Proxy-Authorization` are dropped, and so is any header whose name contains
+  `token`, `secret`, `session` or `key`. Zevian only reads the content type, `X-Robots-Tag` and `Link`.
+- **Zevian never fetches your page.** It reads only what the package sends. It does not follow links in your
+  HTML or load anything your HTML points to.
+- The HTML itself is sent as served. Do not check a page that shows private data you do not want analyzed.
+- Only the HTML as served is checked, so content a browser draws with JavaScript is not visible. The result
+  says so when a page is mostly empty before JavaScript runs.
+
+Your API key goes only to Zevian, in the `Authorization` header, and is never printed or logged.
+
+## Plans and limits
+
+| | Free | Pro and Team |
+|---|---|---|
+| `check_page` | 20 a day | 500 a day |
+| `run_audit` | 3 a day | 50 a day |
+| `get_fix` | 10 a day | 300 a day |
+| `open_fix_pr` | 1 a month, shared with the dashboard | The plan's monthly pull request limit, shared with the dashboard |
+| `get_impact` | Not included | Included |
+
+Daily limits reset at 00:00 UTC. When you hit one, the message says when it resets and where to upgrade.
+
+## Configuration
+
+| Variable | |
+|---|---|
+| `ZEVIAN_API_KEY` | **Required.** Your key, from the dashboard. Without it the server still starts, and every tool tells the agent how to create one. |
+| `ZEVIAN_API_URL` | Optional. Defaults to `https://app.zevian.tech`. Use it to point at staging. It must be `https://`, except for `http://localhost`, so your key is never sent unencrypted. |
+
+Every request carries a `User-Agent` of the form `zevian-mcp/<version>`, so Zevian can tell you when a newer
+version is available.
+
+## Troubleshooting
+
+The messages come from Zevian and say what to do. The common ones:
+
+| Message | What to do |
+|---|---|
+| Zevian API key missing. Create one at zevian.tech/settings/api | Set `ZEVIAN_API_KEY` in your agent's config for Zevian. |
+| This API key is invalid or revoked. Create a new one in the dashboard | Make a new key and replace the old one. |
+| This key is read-only. Create a key with write access to open PRs | Make a *Read + write* key. |
+| Zevian GitHub App isn't installed on this repo. Install it here: … | Open the link and install the app on the repository. |
+| Couldn't reach this URL. If it's localhost, is your dev server running? | Start your dev server and try again. |
+| Plan limit reached for today … | Wait for 00:00 UTC, or upgrade. |
+
+If `claude mcp add` says `Invalid environment variable format`, the server name is directly after `--env`. Keep the
+command as shown, with `--transport stdio` between them: `--env` takes several values and would read the name as one.
+
+On native Windows, older versions of Claude Code could not start `npx` without `cmd /c` in front of it. Current
+versions can, and the Windows command above works on both.
+
+## For developers
+
+```bash
+npm install
+npm test          # builds, then runs the unit and stdio integration tests
+npm run lint
+```
+
+The server speaks MCP over stdio. It writes only protocol messages to stdout; logs go to stderr. Built with
+the official MCP TypeScript SDK (`@modelcontextprotocol/server`).

package/dist/client.js

@@ -0,0 +1,93 @@
+import { userAgent } from "./version.js";
+export const MISSING_KEY_MESSAGE = "Zevian API key missing. Create one at zevian.tech/settings/api";
+/**
+ * An error from Zevian, with the message the API wrote. Those messages are already written for agents (they
+ * say what to do next), so they are passed on unchanged.
+ */
+export class ZevianApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ZevianApiError";
+    }
+}
+/** A small client for the Zevian /v1 API. The key goes only to the API url, in the Authorization header. */
+export class ZevianClient {
+    options;
+    fetchImpl;
+    timeoutMs;
+    agent;
+    constructor(options) {
+        this.options = options;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.agent = options.userAgent ?? userAgent();
+    }
+    /** Throws the missing-key error, for callers that want to fail before doing other work. */
+    requireKey() {
+        if (!this.options.apiKey)
+            throw new ZevianApiError(MISSING_KEY_MESSAGE, 401, "missing_key");
+    }
+    get(path, query) {
+        return this.request("GET", path, undefined, query);
+    }
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    async request(method, path, body, query) {
+        // Checked here, without a request, so a missing key is the same clear message every time.
+        this.requireKey();
+        const url = new URL(`${this.options.apiUrl}${path}`);
+        for (const [name, value] of Object.entries(query ?? {}))
+            if (value !== undefined)
+                url.searchParams.set(name, String(value));
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method,
+                // A redirect would carry the key to wherever it points: refuse to follow one.
+                redirect: "manual",
+                signal: AbortSignal.timeout(this.timeoutMs),
+                headers: {
+                    authorization: `Bearer ${this.options.apiKey}`,
+                    accept: "application/json",
+                    "user-agent": this.agent,
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+                throw new ZevianApiError(`Zevian did not answer within ${Math.round(this.timeoutMs / 1000)} seconds. Try again in a minute.`, 0, "timeout");
+            }
+            throw new ZevianApiError(`Couldn't reach Zevian at ${url.host}. Check your connection, then try again.`, 0, "unreachable");
+        }
+        if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new ZevianApiError("ZEVIAN_API_URL redirected somewhere else, so the request was not sent on. Set it to the final address.", response.status, "redirect");
+        }
+        const text = await response.text().catch(() => "");
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            // Not JSON: a proxy's error page, for instance. Handled below.
+        }
+        if (!response.ok) {
+            const error = parsed?.error;
+            if (typeof error?.message === "string" && error.message) {
+                throw new ZevianApiError(error.message, response.status, typeof error.code === "string" ? error.code : "error");
+            }
+            throw new ZevianApiError(`Zevian returned HTTP ${response.status}. Try again in a minute.`, response.status, "http_error");
+        }
+        if (parsed === null || typeof parsed !== "object") {
+            throw new ZevianApiError("Zevian sent an answer this version of zevian-mcp cannot read. Update the package and try again.", response.status, "bad_response");
+        }
+        return parsed;
+    }
+}

package/dist/config.js

@@ -0,0 +1,29 @@
+export const DEFAULT_API_URL = "https://app.zevian.tech";
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * Reads the environment. ZEVIAN_API_KEY is required to do anything, but a missing key is not a startup
+ * failure: the agent should see a clear tool error, not a server that will not start. ZEVIAN_API_URL is
+ * optional (staging, local development); it must be https, except for localhost, so the key is never sent in
+ * the clear.
+ */
+export function loadConfig(env) {
+    const rawKey = env.ZEVIAN_API_KEY?.trim();
+    const rawUrl = env.ZEVIAN_API_URL?.trim();
+    let apiUrl = DEFAULT_API_URL;
+    if (rawUrl) {
+        let url;
+        try {
+            url = new URL(rawUrl);
+        }
+        catch {
+            return { ok: false, message: "ZEVIAN_API_URL is not a valid URL. Use something like https://app.zevian.tech." };
+        }
+        if (url.protocol !== "https:" && !(url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname))) {
+            return { ok: false, message: "ZEVIAN_API_URL must start with https:// (http:// is only allowed for localhost), so your API key is never sent unencrypted." };
+        }
+        if (url.username || url.password)
+            return { ok: false, message: "ZEVIAN_API_URL must not contain a username or password." };
+        apiUrl = url.origin + url.pathname.replace(/\/+$/, "");
+    }
+    return { ok: true, config: { apiKey: rawKey ? rawKey : null, apiUrl } };
+}

package/dist/headers.js

@@ -0,0 +1,36 @@
+/**
+ * What may leave the machine when a page is sent to Zevian for checking. A response's headers can hold
+ * session cookies and tokens; Zevian needs none of them (it reads only the content type, X-Robots-Tag and
+ * Link), so a header is dropped when its name is one of the credential headers, or contains a word that
+ * suggests a credential. The match is on the name, case-insensitively.
+ */
+const ALWAYS_DROPPED = new Set(["set-cookie", "set-cookie2", "cookie", "authorization", "proxy-authorization"]);
+const SUSPICIOUS_WORDS = ["token", "secret", "session", "key"];
+export function isSensitiveHeader(name) {
+    const lower = name.trim().toLowerCase();
+    return ALWAYS_DROPPED.has(lower) || SUSPICIOUS_WORDS.some((word) => lower.includes(word));
+}
+/** Zevian takes at most 100 headers and 32 KB of them. */
+export const MAX_HEADERS = 100;
+const MAX_VALUE = 2_048;
+const MAX_TOTAL = 30_000;
+/** The response headers that are safe to send: sensitive ones removed, names lower-cased, sizes kept in bounds. */
+export function safeHeaders(headers) {
+    const kept = {};
+    let total = 0;
+    let count = 0;
+    for (const [name, value] of headers) {
+        if (isSensitiveHeader(name))
+            continue;
+        const key = name.trim().toLowerCase();
+        if (!key || count >= MAX_HEADERS)
+            continue;
+        const text = value.length > MAX_VALUE ? value.slice(0, MAX_VALUE) : value;
+        if (total + key.length + text.length > MAX_TOTAL)
+            continue;
+        total += key.length + text.length;
+        count += 1;
+        kept[key] = text;
+    }
+    return kept;
+}

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { ZevianClient } from "./client.js";
+import { loadConfig } from "./config.js";
+import { createServer } from "./server.js";
+import { VERSION } from "./version.js";
+// stdout belongs to the MCP transport: anything else written there would corrupt the protocol. Logs go to
+// stderr, and a stray console.log from any dependency is sent there too.
+console.log = console.error;
+console.info = console.error;
+console.debug = console.error;
+async function main() {
+    const loaded = loadConfig(process.env);
+    if (!loaded.ok) {
+        console.error(`[zevian-mcp] ${loaded.message}`);
+        process.exit(1);
+    }
+    const { apiKey, apiUrl } = loaded.config;
+    if (!apiKey) {
+        console.error("[zevian-mcp] ZEVIAN_API_KEY is not set. The server is running, but every tool will say how to create a key: zevian.tech/settings/api");
+    }
+    const client = new ZevianClient({ apiUrl, apiKey });
+    const server = createServer({ client, secrets: apiKey ? [apiKey] : [] });
+    await server.connect(new StdioServerTransport());
+    console.error(`[zevian-mcp] ${VERSION} ready (${apiUrl})`);
+    const stop = () => {
+        void server.close().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+}
+main().catch((error) => {
+    console.error("[zevian-mcp] failed to start:", error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/page.js

@@ -0,0 +1,95 @@
+import { safeHeaders } from "./headers.js";
+import { userAgent } from "./version.js";
+export const FETCH_TIMEOUT_MS = 15_000;
+export const MAX_PAGE_BYTES = 2 * 1024 * 1024;
+/** A problem fetching the page, with a message written for the agent. */
+export class PageFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PageFetchError";
+    }
+}
+function charsetOf(contentType) {
+    const label = /charset\s*=\s*["']?([\w.:-]+)/i.exec(contentType ?? "")?.[1]?.toLowerCase();
+    if (!label)
+        return "utf-8";
+    try {
+        new TextDecoder(label);
+        return label;
+    }
+    catch {
+        return "utf-8";
+    }
+}
+/**
+ * Fetches a page from this machine, which is how localhost and staging pages get checked. It follows
+ * redirects, gives up after 15 seconds, and stops reading at 2 MB, counted in bytes as the body streams in.
+ * It never sends cookies or credentials: the request carries only a user agent and an Accept header, and the
+ * Zevian API key is not available here. Only http and https are fetched.
+ */
+export async function fetchPage(rawUrl, options = {}) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const maxBytes = options.maxBytes ?? MAX_PAGE_BYTES;
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new PageFetchError("That is not a valid URL. Use a full address such as http://localhost:3000/pricing.");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new PageFetchError("check_page can only fetch http or https URLs, such as http://localhost:3000/pricing.");
+    }
+    if (url.username || url.password) {
+        throw new PageFetchError("Leave the username and password out of the URL. check_page does not send credentials.");
+    }
+    const signal = AbortSignal.timeout(timeoutMs);
+    try {
+        const response = await fetchImpl(url, {
+            method: "GET",
+            redirect: "follow",
+            signal,
+            // Nothing else: no Cookie, no Authorization. Node's fetch has no cookie jar to add one.
+            headers: { "user-agent": userAgent(), accept: "text/html,application/xhtml+xml;q=0.9,*/*;q=0.5" },
+        });
+        const chunks = [];
+        let total = 0;
+        const reader = response.body?.getReader();
+        if (reader) {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    await reader.cancel().catch(() => undefined);
+                    throw new PageFetchError(`This page's HTML is larger than ${Math.round(maxBytes / 1024 / 1024)} MB, so it cannot be checked. Check a smaller page, or one that renders less on the server.`);
+                }
+                chunks.push(value);
+            }
+        }
+        const bytes = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const html = new TextDecoder(charsetOf(response.headers.get("content-type"))).decode(bytes);
+        return {
+            url: url.toString(),
+            finalUrl: response.url || url.toString(),
+            status: response.status,
+            headers: safeHeaders(response.headers),
+            html,
+        };
+    }
+    catch (error) {
+        if (error instanceof PageFetchError)
+            throw error;
+        if (signal.aborted || (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError"))) {
+            throw new PageFetchError(`Timed out after ${Math.round(timeoutMs / 1000)} seconds reading this URL. If it's localhost, is your dev server responding?`);
+        }
+        throw new PageFetchError("Couldn't reach this URL. If it's localhost, is your dev server running?");
+    }
+}

package/dist/prompts.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export const PROMPT_NAME = "fix-seo";
+export const promptArgs = z.object({
+    domain: z.string().optional().describe("The domain to fix, such as example.com. Default: the site connected to this project."),
+});
+/** The instruction the fix-seo slash command gives the agent. It says "errors and warnings", the API's own severity names. */
+export function fixSeoText(domain) {
+    const target = domain?.trim() ? domain.trim() : "the site that belongs to this project";
+    return [
+        `Audit ${target} with Zevian and fix what it finds.`,
+        "",
+        `1. Call list_sites to get the site_id${domain?.trim() ? ` of ${domain.trim()}` : ", and pick the site that matches this project"}.`,
+        '2. Call run_audit for it (scope "full"). If it is still running, call get_audit every minute or so until it is done.',
+        "3. Call get_audit and show me the errors and warnings, worst first: for each one, the page, what is wrong, and why it matters. Leave out info-level items unless I ask.",
+        "4. For each error and warning that has a fix, call get_fix and apply it in this repository. Search for the current value before you edit it, follow the constraints it gives, and write titles, descriptions and alt text from the page's own content: never invent claims.",
+        "5. Run this project's build or tests if it has any. Then summarize what you changed, file by file, and what you left alone and why.",
+        "",
+        "Do not open a pull request unless I ask. If I do, tell me which issues it will fix and wait for my yes before you call open_fix_pr.",
+    ].join("\n");
+}

package/dist/server.js

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { fixSeoText, promptArgs, PROMPT_NAME } from "./prompts.js";
+import { runTool, TOOLS } from "./tools.js";
+import { VERSION } from "./version.js";
+const INSTRUCTIONS = "Zevian audits websites for SEO and AI-search readiness and gives fixes. Call list_sites first to get a site_id. Use check_page for localhost, staging or unpublished pages. Show the user errors and warnings, and ask before opening a pull request.";
+/** The MCP server: the 8 tools and the fix-seo prompt, over the given Zevian client. */
+export function createServer(deps) {
+    const server = new McpServer({ name: "zevian", version: VERSION }, { instructions: INSTRUCTIONS });
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.inputSchema, annotations: tool.annotations }, async (input) => runTool(tool, input, deps));
+    }
+    server.registerPrompt(PROMPT_NAME, { title: "Fix SEO with Zevian", description: "Audit the site with Zevian, show the errors and warnings, and fix them in this repository.", argsSchema: promptArgs }, ({ domain }) => ({ messages: [{ role: "user", content: { type: "text", text: fixSeoText(domain) } }] }));
+    return server;
+}

package/dist/tools.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+import { ZevianApiError } from "./client.js";
+import { fetchPage, PageFetchError } from "./page.js";
+import { DEFAULT_WAIT, pollUntil } from "./wait.js";
+/** Keeps each tool's input typed from its own schema, then stores it with the others. */
+function defineTool(tool) {
+    return tool;
+}
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const pick = (value) => (value && typeof value === "object" ? value : {});
+/** Renames `id` to a name that says what it is, so an agent never has to guess which id this is. */
+function named(value, idName) {
+    const { id, ...rest } = pick(value);
+    return id === undefined ? rest : { [idName]: id, ...rest };
+}
+const AUDIT_DONE = (audit) => audit.status === "done" || audit.status === "failed";
+const PR_DONE = (pr) => ["open", "merged", "closed", "failed", "blocked"].includes(String(pr.status));
+const siteId = z.string().min(1).describe("The site's id, from list_sites.");
+const auditId = z.string().min(1).describe("The audit's id, from run_audit.");
+export const TOOLS = [
+    defineTool({
+        name: "list_sites",
+        title: "List Zevian sites",
+        description: "Call this first, to get the site_id the other tools need. Lists the sites connected to this Zevian account with each site's SEO and AI scores, open issue count, connected GitHub repository, and whether the plan has paused it.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+        run: async (_input, { client }) => client.get("/v1/sites"),
+    }),
+    defineTool({
+        name: "run_audit",
+        title: "Audit a site",
+        description: "Call this to audit a connected site, or one page of it, with Zevian's crawler. Needs a site_id from list_sites. For localhost, staging or any page that is not published on the site's domain, use check_page instead. Waits up to about 45 seconds for the result; if the audit is still running it returns an audit_id, and you should call get_audit with it in a minute. It crawls the site but changes nothing on it.",
+        inputSchema: z.object({
+            site_id: siteId,
+            scope: z.enum(["full", "page"]).optional().describe('"full" audits the whole site (default). "page" audits one page, which needs url.'),
+            url: z.string().optional().describe('The page to audit, on the site\'s own domain. Only with scope "page".'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        run: async (input, { client, wait }) => {
+            const started = pick(await client.post("/v1/audits", { site_id: input.site_id, scope: input.scope ?? "full", ...(input.url ? { url: input.url } : {}) }));
+            const id = String(started.id);
+            const polled = await pollUntil(async () => pick(await client.get(`/v1/audits/${id}`)), AUDIT_DONE, wait ?? DEFAULT_WAIT);
+            const { note: _note, ...audit } = named(polled.value, "audit_id");
+            if (!polled.finished) {
+                return { audit_id: id, site_id: input.site_id, status: audit.status, next: "The audit is still running. Call get_audit with this audit_id in a minute." };
+            }
+            return {
+                ...audit,
+                next: audit.status === "done" ? "Call get_audit with this audit_id to list the issues, then get_fix for each one." : "The audit failed: tell the user why (see error), and do not retry until they have dealt with it.",
+            };
+        },
+    }),
+    defineTool({
+        name: "get_audit",
+        title: "Read an audit",
+        description: "Call this to read an audit started with run_audit: its status, scores and counts, and its issues worst first, each with an issue_id for get_fix. Filter by severity (error, warning, info) or category (seo, geo, aeo, schema). Lists up to 25 issues by default and 100 at most, with the total. If the audit is still running it says so: call it again in a minute.",
+        inputSchema: z.object({
+            audit_id: auditId,
+            severity: z.enum(["error", "warning", "info"]).optional().describe("Only issues of this severity."),
+            category: z.enum(["seo", "geo", "aeo", "schema"]).optional().describe("Only issues in this category."),
+            status: z.enum(["open", "fixed", "ignored", "all"]).optional().describe("Issue status. Default: open."),
+            limit: z.number().int().min(1).max(100).optional().describe("How many issues to return. Default 25."),
+        }),
+        annotations: READ_ONLY,
+        run: async (input, { client }) => {
+            const summary = pick(await client.get(`/v1/audits/${input.audit_id}`));
+            const { note: _note, top_issues: _top, ...audit } = named(summary, "audit_id");
+            if (summary.status !== "done") {
+                return { ...audit, next: summary.status === "failed" ? "The audit failed: tell the user why (see error)." : "The audit is still running. Call get_audit again in a minute." };
+            }
+            const list = pick(await client.get(`/v1/audits/${input.audit_id}/issues`, { severity: input.severity, category: input.category, status: input.status, limit: input.limit }));
+            return { ...audit, issues: { total: list.total, returned: list.returned, items: list.issues } };
+        },
+    }),
+    defineTool({
+        name: "get_fix",
+        title: "Get the fix for an issue",
+        description: "Call this to get instructions for fixing one issue (an issue_id from get_audit or check_page): the kind of change, which files to look in, the exact target values and limits, and why. Apply it in the user's own repository: search for the current value before you edit, and follow the constraints. It returns instructions, not a diff. If the user would rather have Zevian make the change, use open_fix_pr.",
+        inputSchema: z.object({ issue_id: z.string().min(1).describe("The issue's id, from get_audit.") }),
+        annotations: READ_ONLY,
+        run: async (input, { client }) => client.get(`/v1/issues/${input.issue_id}/fix`),
+    }),
+    defineTool({
+        name: "open_fix_pr",
+        title: "Open a pull request with Zevian",
+        description: "Opens one pull request on the user's connected GitHub repository that fixes 1 to 20 issues from the same site, using Zevian's GitHub App. This changes their repository: ask the user to confirm before you call it, and tell them which issues it will fix. It needs a key with write access, and counts against the monthly pull request allowance. Waits up to about 45 seconds; if the pull request is not open by then it returns a pr_id, so call get_fix_pr with it in a minute or two.",
+        inputSchema: z.object({
+            issue_ids: z.array(z.string().min(1)).min(1).max(20).describe("The issues to fix, from get_audit. All from the same site."),
+            title: z.string().max(120).optional().describe("The pull request title. Default: a short summary."),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        run: async (input, { client, wait }) => {
+            const started = pick(await client.post("/v1/fix-prs", { issue_ids: input.issue_ids, ...(input.title ? { title: input.title } : {}) }));
+            const id = String(started.id);
+            const polled = await pollUntil(async () => pick(await client.get(`/v1/fix-prs/${id}`)), PR_DONE, wait ?? DEFAULT_WAIT);
+            const { note: _note, ...pr } = named(polled.value, "pr_id");
+            if (!polled.finished) {
+                return { pr_id: id, status: pr.status, issue_ids: started.issue_ids, next: "Zevian is still writing the fix. Call get_fix_pr with this pr_id in a minute or two." };
+            }
+            return { ...pr, next: pr.status === "open" ? "Give the user the url. They review and merge it on GitHub." : "The pull request did not open: tell the user why (see error)." };
+        },
+    }),
+    defineTool({
+        name: "get_fix_pr",
+        title: "Check a pull request",
+        description: "Call this to check a pull request started with open_fix_pr, when open_fix_pr returned a pr_id instead of a url: its status (queued, running, open, failed), its url once open, and the reason if it failed.",
+        inputSchema: z.object({ pr_id: z.string().min(1).describe("The pr_id from open_fix_pr.") }),
+        annotations: READ_ONLY,
+        run: async (input, { client }) => {
+            const { note: _note, ...pr } = named(await client.get(`/v1/fix-prs/${input.pr_id}`), "pr_id");
+            const status = String(pr.status);
+            return { ...pr, next: status === "open" ? "Give the user the url." : status === "queued" || status === "running" ? "Still running. Call get_fix_pr again in a minute." : undefined };
+        },
+    }),
+    defineTool({
+        name: "check_page",
+        title: "Check a page before you deploy",
+        description: "Call this to check one page's SEO, including pages Zevian cannot reach: localhost, staging, or anything not yet published. The page is fetched from this machine (cookies and credentials are never sent, and sensitive response headers are removed before anything goes to Zevian), then analyzed. Returns the page's issues, each with its fix. It reads the HTML as served, so content a browser draws with JavaScript is not visible; the result says so when a page is mostly empty before JavaScript runs.",
+        inputSchema: z.object({
+            url: z.string().min(1).describe("The page's address, such as http://localhost:3000/pricing."),
+            include_fixes: z.boolean().optional().describe("Include the fix for each issue (default true). Set false for a shorter answer."),
+        }),
+        annotations: READ_ONLY,
+        run: async (input, { client, fetchPageImpl }) => {
+            // Fail on a missing key before fetching anything.
+            client.requireKey();
+            const page = await (fetchPageImpl ?? fetchPage)(input.url);
+            return client.post("/v1/analyze", {
+                url: page.url,
+                final_url: page.finalUrl,
+                status: page.status,
+                headers: page.headers,
+                html: page.html,
+                include_fixes: input.include_fixes ?? true,
+            });
+        },
+    }),
+    defineTool({
+        name: "get_impact",
+        title: "See what the fixes achieved",
+        description: "Call this to see how a site performs in Search Console and Bing over the last N days (7 to 180, default 28), and the before and after of each merged Zevian pull request: clicks, impressions and position, where a positive position_gain means the page moved up. Needs a site_id from list_sites. Paid plans only.",
+        inputSchema: z.object({
+            site_id: siteId,
+            days: z.number().int().min(7).max(180).optional().describe("The period in days. Default 28."),
+        }),
+        annotations: READ_ONLY,
+        run: async (input, { client }) => client.get(`/v1/sites/${input.site_id}/impact`, { days: input.days }),
+    }),
+];
+export const TOOL_NAMES = TOOLS.map((tool) => tool.name);
+/** Text for the agent: compact JSON, because agents pay for every token. */
+export function resultOf(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+export function errorOf(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+function scrub(message, secrets) {
+    return secrets.reduce((text, secret) => (secret ? text.split(secret).join("[key]") : text), message);
+}
+/**
+ * Runs a tool and turns the outcome into a tool result. An error from Zevian, or from fetching the page,
+ * carries a message written for the agent and is passed on unchanged (as a tool error, isError). Anything
+ * else is reported without detail that could matter, and never with the API key.
+ */
+export async function runTool(tool, input, deps) {
+    const secrets = deps.secrets ?? [];
+    try {
+        return resultOf(await tool.run(tool.inputSchema.parse(input), deps));
+    }
+    catch (error) {
+        if (error instanceof ZevianApiError || error instanceof PageFetchError)
+            return errorOf(scrub(error.message, secrets));
+        if (error instanceof z.ZodError)
+            return errorOf(`Invalid input: ${error.issues[0]?.path.join(".") || "input"} ${error.issues[0]?.message ?? "is not valid"}.`);
+        console.error(`[zevian-mcp] ${tool.name} failed:`, scrub(error instanceof Error ? error.message : String(error), secrets));
+        return errorOf("zevian-mcp hit an unexpected error. Try again; if it keeps happening, update the package with npx zevian-mcp@latest.");
+    }
+}

package/dist/version.js

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+/** The package version, read from package.json (one level up from both src/ and dist/). */
+export const VERSION = (() => {
+    try {
+        const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+        const version = JSON.parse(raw).version;
+        return typeof version === "string" ? version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/** Sent with every request to Zevian, so the backend can tell versions apart (and later warn about old ones). */
+export function userAgent(version = VERSION) {
+    return `zevian-mcp/${version} (node ${process.versions.node}; ${process.platform})`;
+}

package/dist/wait.js

@@ -0,0 +1,19 @@
+/** About 45 seconds: some MCP clients time out a tool call that runs longer. */
+export const DEFAULT_WAIT = { timeoutMs: 45_000, intervalMs: 3_000 };
+/**
+ * Polls until `done` says the value is final, or the time is up. It always polls once, never sleeps past the
+ * deadline, and returns the last value either way, so the caller can say where things stand.
+ */
+export async function pollUntil(poll, done, waiter = DEFAULT_WAIT) {
+    const sleep = waiter.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = waiter.now ?? Date.now;
+    const deadline = now() + waiter.timeoutMs;
+    for (;;) {
+        const value = await poll();
+        if (done(value))
+            return { value, finished: true };
+        if (now() + waiter.intervalMs > deadline)
+            return { value, finished: false };
+        await sleep(waiter.intervalMs);
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "zevian-mcp",
+  "version": "0.1.0",
+  "mcpName": "tech.zevian/mcp",
+  "description": "Zevian for AI coding agents: audit your site, check a page on localhost before you deploy, and fix SEO issues from your editor.",
+  "type": "module",
+  "bin": {
+    "zevian-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "seo",
+    "zevian"
+  ],
+  "license": "MIT",
+  "homepage": "https://zevian.tech/mcp",
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit --noUnusedLocals --noUnusedParameters",
+    "test": "vitest run",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.2.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.2.0",
+    "@types/node": "20.19.43",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  }
+}