sitezen-mcp 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# SiteZen MCP
+
+An MCP server that lets **Claude Desktop** (or any MCP client) drive a SiteZen-enabled WordPress site directly — no Vercel platform, no API key burning on your end, full editor v2 (Style Studio) compatibility.
+
+## Why this exists
+
+The SiteZen platform conversion engine works, but it lives behind Vercel's 60-second function limit. On Hobby tier, complex Figma sections time out. The MCP path solves that completely:
+
+- **No Vercel** → no 60s timeout
+- **No platform API key** → the user's Claude subscription pays for tokens, not yours
+- **Same plugin, same editor** → all the v2 Style Studio panels work on output from this MCP exactly as they do on platform-generated output
+- **Faster iteration** → Claude generates HTML in chat, pushes to WP via tools, user sees result instantly
+
+The MCP is a **thin set of hands** — Claude is the brain (it generates the HTML); the MCP just gives Claude the verbs to ship that HTML to WordPress.
+
+## Tools (12 total)
+
+| Tool | What it does |
+|---|---|
+| `check_config` | Verify connection to the WP site. **Always call first.** |
+| `list_pages` | List all WP pages with id, title, slug, URL. |
+| `list_templates` | List existing SiteZen templates. |
+| `create_page` | Create a new WP page wrapping HTML as a SiteZen Section. |
+| `push_section_to_page` | Append or replace a section on an existing page. |
+| `get_page_html` | Read the current HTML of a page (for editing). |
+| `create_header_footer` | Create a site-wide header or footer template. |
+| `create_template` | Create any other template type (archive, single-post, listing). |
+| `set_site_branding` | Set primary color, accent color, fonts, logo URL. |
+| `get_site_globals` | Read current brand defaults. |
+| `detect_section_kind` | Dry-run the SiteZen detector to see what specialized blocks the editor will recognize. |
+| `editor_v2_capabilities` | Read-only manifest of Style Studio panels — informs Claude how to author HTML for best post-push editability. |
+
+## Install
+
+### Prerequisites
+
+- Node.js 18 or newer
+- A WordPress site with the SiteZen plugin installed and activated
+- The site's **Connection Key** from WP Admin → SiteZen → Connection
+
+### Local build
+
+```bash
+cd sitezen-mcp
+npm install
+npm run build
+```
+
+This produces `dist/index.js` — that's the MCP server binary.
+
+### Wire to Claude Desktop
+
+See [INSTALL.md](./INSTALL.md) for the exact JSON snippet to add to your Claude Desktop config.
+
+## Typical workflow
+
+1. Open Claude Desktop with this MCP server connected
+2. Say: *"Check my SiteZen connection."* → Claude calls `check_config`
+3. Say: *"Look at this Figma design [paste URL + screenshot] and build a hero section for my homepage. Match my site's brand."* → Claude calls `get_site_globals`, generates HTML, calls `create_page` with the result
+4. Open the returned `edit_url` in your browser → edit in WP with the v2 Style Studio panels
+5. Say: *"Now add a pricing section below the hero."* → Claude calls `push_section_to_page` with new HTML
+
+No platform conversion, no Vercel timeout, no Anthropic API spend on your side — your end user's Claude subscription covers the LLM cost.
+
+## Architecture
+
+```
+Claude Desktop
+     │
+     │ MCP protocol over stdio
+     ▼
+sitezen-mcp (this server)
+     │
+     │ HTTPS + X-SiteZen-Key
+     ▼
+WordPress site / SiteZen plugin REST API
+     │
+     │ wp_insert_post / wp_update_post / etc.
+     ▼
+WordPress database
+```
+
+The MCP server is stateless — every tool call reads the env-var config, hits the plugin REST endpoint, returns the result. No local DB, no cache, no background work.
+
+## Editor v2 compatibility
+
+Everything pushed through this MCP becomes a SiteZen Section block in WP. That block is rendered by the v2 editor JS (in `plugin-v2/assets/js/editor.js`) which gives the user 13+ collapsible Style Studio panels: Layers, Tag, Image, Spacing per-side, Border, Border Radius, Background (with gradient palette), Effects (shadow + opacity + filter), Layout, Size, Flex, Transform (with quick presets), Hover State (writes per-element :hover rules), Alignment & Text Style, Classes.
+
+The MCP doesn't apply edits itself — it just pushes HTML, and the editor wraps that HTML in the v2 editing UX automatically. To get the most editing power, have Claude:
+
+- Wrap text in semantic tags (h1/h2/h3, not div) → Tag panel can swap freely
+- Add `data-sz-id="hero-cta"` on important elements → Layers panel labels them readably
+- Use inline styles → per-element panels (Spacing, Border, etc.) edit them directly
+- Skip linking external stylesheets that may not exist on the target site
+
+The `editor_v2_capabilities` tool returns the full panel manifest plus authoring tips Claude can reference.
+
+## When to use this vs the platform
+
+| Use the MCP | Use the platform |
+|---|---|
+| Solo / agency workflow with you in the loop | Self-serve, no operator in the chat |
+| You're testing / iterating on Figma → WP | Bulk conversion runs you don't want to babysit |
+| You want to avoid Vercel costs while validating | You've validated and have funding for Pro |
+| Complex sections that time out on Hobby | Simple sections under 60s |
+
+Both produce HTML that's edited by the same plugin — pick the input path that fits the situation.

package/dist/conversion-log.js

@@ -0,0 +1,67 @@
+// Conversion logging — every successful push is recorded so we can later
+// analyse what designs users convert (popular section types, common failure
+// modes, common Figma file shapes, etc.).
+//
+// Storage today: append-only JSON Lines file at ~/.sitezen/conversions.jsonl
+// — one line per conversion, easy to grep / pipe into anything. Persists
+// across Claude Desktop restarts.
+//
+// Once sitezen.app is live, the same record is ALSO POSTed to
+// /api/license/log_conversion so the dashboard can show stats. The local
+// file stays as the source-of-truth + offline buffer (network failures
+// never lose a record).
+//
+// Per the product decision, we capture "maximum" data: timestamp, license
+// key fingerprint, site URL, Figma URL, page name + id, section type if
+// known, success/fail, error code if failed, full generated HTML.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+const STATE_DIR = path.join(os.homedir(), ".sitezen");
+const LOG_FILE = path.join(STATE_DIR, "conversions.jsonl");
+function fingerprint(licenseKey) {
+    if (!licenseKey)
+        return "anonymous";
+    return crypto.createHash("sha256")
+        .update(licenseKey.trim())
+        .digest("hex")
+        .slice(-8);
+}
+export function logConversion(rec) {
+    try {
+        if (!fs.existsSync(STATE_DIR)) {
+            fs.mkdirSync(STATE_DIR, { recursive: true });
+        }
+        const full = {
+            ts: new Date().toISOString(),
+            license_fingerprint: fingerprint(rec.license_key || process.env.SITEZEN_LICENSE_KEY),
+            site_url: rec.site_url,
+            page_name: rec.page_name,
+            page_id: rec.page_id,
+            figma_url: rec.figma_url,
+            section_type: rec.section_type,
+            section_bbox: rec.section_bbox,
+            success: rec.success,
+            error_code: rec.error_code,
+            html: rec.html,
+            detection: rec.detection,
+        };
+        fs.appendFileSync(LOG_FILE, JSON.stringify(full) + "\n", "utf8");
+        // Fire-and-forget POST to dashboard when available — never blocks
+        // the conversion result. Failures are silent; the .jsonl file keeps
+        // the authoritative record either way.
+        if (process.env.SITEZEN_LICENSE_API_URL) {
+            const url = process.env.SITEZEN_LICENSE_API_URL.replace(/\/+$/, "") + "/log_conversion";
+            fetch(url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(full),
+            }).catch(() => { });
+        }
+    }
+    catch {
+        // Logging must never break a conversion. Swallow all errors.
+    }
+}
+export const LOG_FILE_PATH_FOR_DISPLAY = LOG_FILE;