sitezen-mcp 1.0.0

package/dist/validate.js

@@ -0,0 +1,114 @@
+/**
+ * SiteZen HTML validator — strict enforcement, NO invented values.
+ *
+ * Runs server-side inside the MCP before any HTML is pushed to WordPress.
+ * The model (Claude in Desktop) generates HTML using REAL Figma data;
+ * this validator catches violations of the universal rules and REFUSES
+ * the push, returning a clear list of what's wrong so the model can
+ * regenerate using the Figma values it already has.
+ *
+ * What this does NOT do:
+ *   - Invent font-sizes, padding values, colors, or any other design value
+ *   - Auto-rewrite HTML with formulas the validator made up
+ *   - Modify the model's intent in any way
+ *
+ * What this DOES do:
+ *   - Check that emitted HTML obeys the structural rules (section root,
+ *     scoped id, responsive clamp on large values, mobile breakpoint)
+ *   - Return a list of violations with specific instructions for the
+ *     model to fix using its existing Figma data
+ *
+ * Rule philosophy: the model has the Figma data (text content, hex
+ * colors, font sizes, layout values). The validator's job is to make
+ * sure the model USES that data correctly — not to second-guess it.
+ */
+/**
+ * Validate HTML against the SiteZen universal rules. Returns ok=false
+ * with a list of specific violations if any rule is broken. On ok=true,
+ * the HTML passes and can be pushed verbatim.
+ *
+ * The HTML is NEVER modified by this function. If the model emitted
+ * something wrong, the model must regenerate using the Figma values
+ * it fetched.
+ */
+export function validateHtml(html) {
+    const errors = [];
+    // ── Rule 1: No markdown code fences ───────────────────────────────
+    if (/^```/m.test(html) || /```\s*$/m.test(html)) {
+        errors.push("Markdown code fences detected (``` ... ```). Strip them — the output must be raw HTML starting with '<'.");
+    }
+    // ── Rule 2: Must have a <section> tag ─────────────────────────────
+    const sectionMatch = html.match(/<section\b([^>]*)>/i);
+    if (!sectionMatch) {
+        errors.push("No <section> tag found. SiteZen wraps each push as one section-per-block; the outermost element must be <section>.");
+        // Without a section, the remaining rules can't meaningfully run.
+        return { ok: false, errors };
+    }
+    // ── Rule 3: <section> must have id=\"sz-...\" for CSS scoping ─────
+    const sectionAttrs = sectionMatch[1] || "";
+    const idMatch = sectionAttrs.match(/\bid="(sz-[a-zA-Z0-9_-]+)"/);
+    if (!idMatch) {
+        errors.push("<section> is missing id=\"sz-something\". Add an id like id=\"sz-hero\" and scope all CSS in this section under that id (e.g. #sz-hero h1 { ... }).");
+    }
+    // ── Rule 4: Font sizes > 18px must use clamp() ────────────────────
+    // The values inside clamp() come from Figma — never from this validator.
+    const rawLargeFonts = [];
+    const fontSizeRegex = /font-size:\s*(\d+(?:\.\d+)?)px\s*;/gi;
+    let match;
+    while ((match = fontSizeRegex.exec(html)) !== null) {
+        const size = parseFloat(match[1]);
+        if (size > 18)
+            rawLargeFonts.push(size);
+    }
+    if (rawLargeFonts.length > 0) {
+        errors.push(`Found ${rawLargeFonts.length} raw font-size value(s) > 18px (${rawLargeFonts.join("px, ")}px). ` +
+            "Per universal rule §0.2, every font-size > 18px must use clamp() for responsive scaling. " +
+            "Use the EXACT values from your Figma data — do not invent them. Pattern: " +
+            "font-size: clamp(<mobile-min-from-Figma-or-design-judgment>, <preferred-vw-derived-from-Figma-px>, <Figma-desktop-px>px). " +
+            "Regenerate the affected styles using your Figma text node fontSize values.");
+    }
+    // ── Rule 5: Padding/margin > 40px must use clamp() ────────────────
+    const rawLargeSpacing = [];
+    const spacingRegex = /\b(padding|margin):\s*([^;]+);/gi;
+    while ((match = spacingRegex.exec(html)) !== null) {
+        const prop = match[1];
+        const value = match[2];
+        const largeValues = value
+            .trim()
+            .split(/\s+/)
+            .map((part) => {
+            const m = part.match(/^(\d+(?:\.\d+)?)px$/);
+            return m ? parseFloat(m[1]) : null;
+        })
+            .filter((n) => n !== null && n > 40);
+        if (largeValues.length > 0) {
+            rawLargeSpacing.push({ property: prop, values: largeValues });
+        }
+    }
+    if (rawLargeSpacing.length > 0) {
+        const summary = rawLargeSpacing
+            .map((s) => `${s.property}: ${s.values.join("px, ")}px`)
+            .join(" | ");
+        errors.push(`Found raw spacing values > 40px (${summary}). ` +
+            "Per universal rule §0.2, padding/margin > 32px must use clamp() for responsive scaling. " +
+            "Use the EXACT padding/margin values from your Figma layout — do not invent them. Pattern: " +
+            "padding: clamp(<small-mobile-px>, <vw-derived-from-design-px>, <Figma-desktop-px>px). " +
+            "Regenerate the affected styles using your Figma frame paddingTop/Right/Bottom/Left values.");
+    }
+    // ── Rule 6: Must include mobile breakpoint @media query ───────────
+    if (!/@media\s*\(\s*max-width:\s*768px\s*\)/i.test(html)) {
+        errors.push("No @media (max-width: 768px) block found. Per universal rule §0.2, every section must include a mobile breakpoint with: " +
+            "stacked layouts (flex-direction: column for previously horizontal flex), shrunk font sizes, " +
+            "reduced padding, and any decoration repositioning needed. The values come from how the design " +
+            "should adapt — not formulas. Add a real @media block with rules derived from the Figma design intent.");
+    }
+    // ── Rule 7: white-space: nowrap on headings causes overflow ───────
+    if (/(<h[1-6][^>]*style="[^"]*?white-space:\s*nowrap)/i.test(html)) {
+        errors.push("Detected white-space: nowrap on a heading element. This causes horizontal overflow on mobile " +
+            "when the headline is long. Remove white-space: nowrap from headings; let them wrap naturally.");
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+    };
+}

package/dist/wp-client.js

@@ -0,0 +1,130 @@
+/**
+ * Thin HTTP client wrapping the SiteZen plugin's REST API.
+ *
+ * The plugin exposes /wp-json/sitezen/v1/* endpoints authenticated by an
+ * X-SiteZen-Key header (the per-site connection key the user generates
+ * from WP Admin → SiteZen → Connection).
+ *
+ * All MCP tools go through this client — kept deliberately tiny so any
+ * SiteZen REST endpoint can be hit by passing the path + method, without
+ * needing a per-endpoint wrapper.
+ */
+/**
+ * Reads + validates the env vars the operator set in their Claude Desktop
+ * MCP server config. Throws if either is missing so the first tool call
+ * fails fast with a clear message instead of mysteriously 401'ing later.
+ */
+export function getConfig() {
+    const siteUrl = process.env.SITEZEN_SITE_URL;
+    const connectionKey = process.env.SITEZEN_CONNECTION_KEY;
+    if (!siteUrl) {
+        throw new Error("SITEZEN_SITE_URL env var is required. Add it to your Claude Desktop MCP " +
+            "server config (e.g. \"env\": {\"SITEZEN_SITE_URL\": \"https://yoursite.com\"}).");
+    }
+    if (!connectionKey) {
+        throw new Error("SITEZEN_CONNECTION_KEY env var is required. Get it from WP Admin → SiteZen → " +
+            "Connection, then add to Claude Desktop MCP server config.");
+    }
+    return {
+        // Strip a trailing slash so we can naively concatenate paths.
+        siteUrl: siteUrl.replace(/\/+$/, ""),
+        connectionKey,
+    };
+}
+/**
+ * Make an authenticated request to the SiteZen REST API.
+ *
+ * `path` is relative to /wp-json/sitezen/v1 (so pass `/pages`, not
+ * `/wp-json/sitezen/v1/pages`).
+ *
+ * On non-2xx the response body is included in the thrown Error so MCP
+ * tool errors carry the real WP/SiteZen complaint instead of just a
+ * status code.
+ */
+export async function wpRequest(path, init = {}) {
+    const config = (init.siteUrl && init.connectionKey)
+        ? { siteUrl: init.siteUrl.replace(/\/+$/, ""), connectionKey: init.connectionKey }
+        : getConfig();
+    let url = `${config.siteUrl}/wp-json/sitezen/v1${path}`;
+    if (init.query) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(init.query)) {
+            if (value === undefined)
+                continue;
+            params.set(key, String(value));
+        }
+        const queryString = params.toString();
+        if (queryString)
+            url += `?${queryString}`;
+    }
+    const headers = {
+        "X-SiteZen-Key": config.connectionKey,
+    };
+    let body;
+    if (init.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        body = JSON.stringify(init.body);
+    }
+    const response = await fetch(url, {
+        method: init.method || "GET",
+        headers,
+        body,
+    });
+    const responseText = await response.text();
+    if (!response.ok) {
+        // WP REST errors are usually JSON {code, message, data}. Include the
+        // raw body so the model can read the actual reason in its tool result.
+        throw new Error(`SiteZen REST ${init.method || "GET"} ${path} → ${response.status}: ${responseText.slice(0, 500)}`);
+    }
+    // Some endpoints return empty body on success; handle that gracefully.
+    if (!responseText)
+        return undefined;
+    try {
+        return JSON.parse(responseText);
+    }
+    catch {
+        // Endpoint returned non-JSON success body — return as-is so caller can use it.
+        return responseText;
+    }
+}
+/**
+ * Tool-result helper: wraps any JSON-serializable value as the MCP
+ * `{ content: [{type: "text", text: ...}] }` shape, with a couple of
+ * MCP-client-friendly conveniences:
+ *   - errors are flagged with isError: true so the client surfaces them
+ *   - everything is JSON-stringified with 2-space indent for readability
+ */
+export function ok(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+/**
+ * Resolve a site URL into the connection info from state.json. Returns the
+ * single saved site when only one exists (so the user doesn't have to specify
+ * site_url every call). Returns null when no sites are saved or the requested
+ * URL isn't connected — caller surfaces the appropriate Errors.* response.
+ */
+export function resolveSiteFromState(state, siteUrl) {
+    if (state.sites.length === 0)
+        return null;
+    if (!siteUrl && state.sites.length === 1) {
+        return { siteUrl: state.sites[0].url, connectionKey: state.sites[0].connection_key };
+    }
+    if (!siteUrl)
+        return null; // ambiguous — caller must ask the user
+    const canon = siteUrl.trim().replace(/\/+$/, "").toLowerCase();
+    const match = state.sites.find((s) => s.url.trim().replace(/\/+$/, "").toLowerCase() === canon);
+    return match ? { siteUrl: match.url, connectionKey: match.connection_key } : null;
+}
+export function err(message, extra) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ error: message, ...extra }, null, 2),
+            },
+        ],
+        isError: true,
+    };
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "sitezen-mcp",
+  "version": "1.0.0",
+  "description": "SiteZen MCP server — lets Claude Desktop (or any MCP client) drive a SiteZen-enabled WordPress site directly. No Vercel, no platform API, no API-credit burn for the operator. The end user's Claude subscription pays for LLM tokens.",
+  "type": "module",
+  "bin": {
+    "sitezen-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').copyFileSync('src/conversion-rules.md','dist/conversion-rules.md')\"",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "cheerio": "^1.2.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}