@sketchxflow/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KriyaX Labs
+
+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,62 @@
+# @sketchxflow/mcp
+
+Design websites and mobile apps with [SketchxFlow](https://sketchxflow.com) from
+Claude, Cursor, or any MCP client — by prompt, or by planning the structure first.
+
+## Setup
+
+1. **Get an API key:** sign in at [sketchxflow.com](https://sketchxflow.com) →
+   **Account → API keys** → *Generate key*. Copy it (shown once).
+
+2. **Add the server to your MCP client config:**
+
+   ```json
+   {
+     "mcpServers": {
+       "sketchxflow": {
+         "command": "npx",
+         "args": ["-y", "@sketchxflow/mcp"],
+         "env": { "SKETCHXFLOW_API_KEY": "sk_live_…" }
+       }
+     }
+   }
+   ```
+
+   - **Claude Desktop:** `claude_desktop_config.json`
+   - **Claude Code:** `claude mcp add sketchxflow -e SKETCHXFLOW_API_KEY=sk_live_… -- npx -y @sketchxflow/mcp`
+   - **Cursor:** `.cursor/mcp.json`
+
+3. Restart the client. Ask it to *"design a landing page for a coffee subscription startup"* and watch it build.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `sketchxflow_design` | One-shot: prompt → full multi-page design → preview URL. |
+| `sketchxflow_plan` | Create a site **plan** (pages + purpose) to review before building. |
+| `sketchxflow_plan_refine` | Adjust a plan ("add a pricing page", "merge About and Team"). |
+| `sketchxflow_generate_from_plan` | Build the approved plan into a design. |
+| `sketchxflow_get_project` | Status + preview URL + page list for a project. |
+| `sketchxflow_list_projects` | List your projects. |
+
+Designs are created in **your** SketchxFlow account — they appear in your
+dashboard, charge your own coin balance, and you can edit, export, or publish
+them from the web app. Generation takes ~1–9 minutes; the design/build tools
+stream progress and return when ready.
+
+## Configuration
+
+| Env var | Required | Default | Notes |
+|---------|----------|---------|-------|
+| `SKETCHXFLOW_API_KEY` | yes | — | Your `sk_live_…` key. |
+| `SKETCHXFLOW_API_URL` | no | `https://sketchxflow.com` | Override the API base (e.g. self-host / staging). |
+
+## Develop
+
+```bash
+npm install
+npm run build      # tsc → dist/
+node dist/index.js # runs over stdio (expects an MCP client on stdin/stdout)
+```
+
+MIT licensed.

package/dist/client.js

@@ -0,0 +1,58 @@
+/**
+ * Thin REST client for the SketchxFlow MCP API (/api/mcp/*).
+ *
+ * Auth: a per-user API key (`sk_live_…`) from the SketchxFlow dashboard
+ * (Account → API keys), passed as a Bearer token. Configure via env:
+ *   SKETCHXFLOW_API_KEY  (required)
+ *   SKETCHXFLOW_API_URL  (optional, default https://sketchxflow.com)
+ */
+const BASE = (process.env.SKETCHXFLOW_API_URL || "https://sketchxflow.com").replace(/\/+$/, "");
+const KEY = process.env.SKETCHXFLOW_API_KEY || "";
+export function hasKey() {
+    return Boolean(KEY);
+}
+async function req(path, method, body) {
+    let res;
+    try {
+        res = await fetch(`${BASE}${path}`, {
+            method,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${KEY}`,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+    }
+    catch (e) {
+        throw new Error(`Couldn't reach SketchxFlow (${BASE}): ${e.message}`);
+    }
+    const text = await res.text();
+    let data = {};
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = { detail: text };
+    }
+    if (!res.ok) {
+        const detail = data?.detail;
+        const msg = typeof detail === "string" ? detail : detail ? JSON.stringify(detail) : `HTTP ${res.status}`;
+        if (res.status === 401) {
+            throw new Error(`${msg}. Check SKETCHXFLOW_API_KEY (generate one at sketchxflow.com → Account → API keys).`);
+        }
+        if (res.status === 402) {
+            throw new Error(`${msg}. You're out of coins — top up at sketchxflow.com → Account → Coins.`);
+        }
+        throw new Error(msg);
+    }
+    return data;
+}
+export const sxf = {
+    design: (b) => req("/api/mcp/design", "POST", b),
+    plan: (b) => req("/api/mcp/plan", "POST", b),
+    planRefine: (id, instruction) => req(`/api/mcp/plan/${encodeURIComponent(id)}/refine`, "POST", { instruction }),
+    planGenerate: (id) => req(`/api/mcp/plan/${encodeURIComponent(id)}/generate`, "POST"),
+    job: (id) => req(`/api/mcp/jobs/${encodeURIComponent(id)}`, "GET"),
+    project: (id) => req(`/api/mcp/projects/${encodeURIComponent(id)}`, "GET"),
+    listProjects: () => req("/api/mcp/projects", "GET"),
+};

package/dist/index.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * SketchxFlow MCP server.
+ *
+ * Lets an MCP client (Claude Desktop/Code, Cursor, …) design websites and apps
+ * via SketchxFlow — direct prompt→design AND a plan→refine→build flow. Generation
+ * runs as a background job on the server; this process polls it to completion and
+ * emits MCP progress notifications, so one tool call returns the finished preview
+ * URL.
+ *
+ * Auth: per-user API key in SKETCHXFLOW_API_KEY (Account → API keys).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { sxf, hasKey } from "./client.js";
+// IMPORTANT: stdout is the JSON-RPC channel — only ever log to stderr.
+const log = (...a) => console.error("[sketchxflow-mcp]", ...a);
+const text = (s) => ({ content: [{ type: "text", text: s }] });
+const errorText = (s) => ({ content: [{ type: "text", text: s }], isError: true });
+/** A progress emitter bound to the current request's progressToken (if any). */
+function progressSender(extra) {
+    const token = extra?._meta?.progressToken;
+    return async (progress, total, message) => {
+        if (token === undefined || typeof extra?.sendNotification !== "function")
+            return;
+        try {
+            await extra.sendNotification({
+                method: "notifications/progress",
+                params: { progressToken: token, progress, total: total || undefined, message },
+            });
+        }
+        catch {
+            /* progress is best-effort */
+        }
+    };
+}
+const POLL_MS = 4000;
+const MAX_WAIT_MS = 15 * 60 * 1000;
+async function pollJob(jobId, onProgress, signal) {
+    const deadline = Date.now() + MAX_WAIT_MS;
+    let lastMsg = "";
+    while (Date.now() < deadline) {
+        if (signal?.aborted)
+            throw new Error("Cancelled.");
+        const job = await sxf.job(jobId);
+        const p = job.progress;
+        if (p?.message && p.message !== lastMsg) {
+            lastMsg = p.message;
+            await onProgress(p.done || 0, p.total || 0, p.message);
+        }
+        if (job.status === "completed")
+            return job;
+        if (job.status === "failed")
+            throw new Error(job.error || "Generation failed.");
+        await new Promise((r) => setTimeout(r, POLL_MS));
+    }
+    throw new Error("Timed out after 15 minutes waiting for the design.");
+}
+function formatResult(result, projectId, previewUrl) {
+    const pid = result?.project_id || projectId;
+    const url = result?.preview_url || previewUrl;
+    const pages = (result?.pages || []).map((p) => p.name || p.slug);
+    return [
+        `✅ Design ready${result?.title ? `: ${result.title}` : ""}.`,
+        `Preview: ${url}`,
+        pages.length ? `Pages (${pages.length}): ${pages.join(", ")}` : "",
+        `Project ID: ${pid} — open it in the SketchxFlow dashboard to edit, export, or publish.`,
+    ].filter(Boolean).join("\n");
+}
+function formatPlan(projectId, plan) {
+    const brand = plan?.brand_name || plan?.brand?.name || "";
+    const pages = plan?.pages || [];
+    const lines = pages.map((p, i) => `  ${i + 1}. ${p.name || p.slug}${p.purpose ? ` — ${p.purpose}` : ""}`);
+    return [
+        `📋 Plan created${brand ? ` for ${brand}` : ""}.`,
+        `Project ID: ${projectId}`,
+        `Pages (${pages.length}):`,
+        ...lines,
+        "",
+        `Next: refine with sketchxflow_plan_refine (project_id "${projectId}"), or build it now with sketchxflow_generate_from_plan (project_id "${projectId}").`,
+    ].join("\n");
+}
+const server = new McpServer({ name: "sketchxflow", version: "0.1.0" }, { capabilities: { tools: {} } });
+// ── Direct design ────────────────────────────────────────────────────────────
+server.registerTool("sketchxflow_design", {
+    title: "Design a website or app",
+    description: "Generate a complete multi-page website or mobile-app design from a single prompt and return a live preview URL. Use this for a direct, one-shot design. If the user wants to review and shape the page structure FIRST, use sketchxflow_plan instead. Takes 1–9 minutes; this call streams progress and returns when the design is ready.",
+    inputSchema: {
+        prompt: z.string().describe("The design brief — what to build, for whom, and the desired feel."),
+        platform: z.enum(["web", "mobile"]).optional().describe("Target surface. Default: web."),
+        ai_images: z.boolean().optional().describe("Generate AI images (default true). false keeps placeholders and saves coins."),
+        enable_3d: z.boolean().optional().describe("Opt into a real interactive 3D hero (web only). Default false."),
+        inspiration_url: z.string().optional().describe("A website URL to take visual inspiration from."),
+    },
+}, async (args, extra) => {
+    if (!hasKey())
+        return errorText("SKETCHXFLOW_API_KEY is not set. Generate a key at sketchxflow.com → Account → API keys and add it to your MCP config.");
+    try {
+        const onProgress = progressSender(extra);
+        await onProgress(0, 0, "Starting design…");
+        const started = await sxf.design({
+            prompt: args.prompt,
+            platform: args.platform,
+            ai_images: args.ai_images,
+            enable_3d: args.enable_3d,
+            inspiration_url: args.inspiration_url,
+        });
+        const job = await pollJob(started.job_id, onProgress, extra?.signal);
+        return text(formatResult(job.result, started.project_id, started.preview_url));
+    }
+    catch (e) {
+        return errorText(`Design failed: ${e.message}`);
+    }
+});
+// ── Plan → refine → build ────────────────────────────────────────────────────
+server.registerTool("sketchxflow_plan", {
+    title: "Plan a site before building",
+    description: "Create a structured site PLAN (the pages and what each is for) from a brief, WITHOUT building it yet. Show the returned plan to the user; refine it with sketchxflow_plan_refine; then build it with sketchxflow_generate_from_plan. Use this when the user wants to agree on structure before designing.",
+    inputSchema: {
+        prompt: z.string().describe("The brief to plan from."),
+        platform: z.enum(["web", "mobile"]).optional().describe("Target surface. Default: web."),
+    },
+}, async (args) => {
+    if (!hasKey())
+        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+    try {
+        const r = await sxf.plan({ prompt: args.prompt, platform: args.platform });
+        return text(formatPlan(r.project_id, r.plan));
+    }
+    catch (e) {
+        return errorText(`Planning failed: ${e.message}`);
+    }
+});
+server.registerTool("sketchxflow_plan_refine", {
+    title: "Refine a site plan",
+    description: "Apply a change to an existing plan (created by sketchxflow_plan) and return the updated plan. E.g. 'add a pricing page', 'merge About and Team', 'make it 5 pages max'.",
+    inputSchema: {
+        project_id: z.string().describe("The project_id returned by sketchxflow_plan."),
+        instruction: z.string().describe("How to change the plan."),
+    },
+}, async (args) => {
+    if (!hasKey())
+        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+    try {
+        const r = await sxf.planRefine(args.project_id, args.instruction);
+        return text(formatPlan(r.project_id, r.plan));
+    }
+    catch (e) {
+        return errorText(`Refine failed: ${e.message}`);
+    }
+});
+server.registerTool("sketchxflow_generate_from_plan", {
+    title: "Build the site from its plan",
+    description: "Build the full design from a plan the user has approved (created via sketchxflow_plan / refined via sketchxflow_plan_refine). Returns a live preview URL. Takes 1–9 minutes; streams progress.",
+    inputSchema: {
+        project_id: z.string().describe("The project_id of the planned project."),
+    },
+}, async (args, extra) => {
+    if (!hasKey())
+        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+    try {
+        const onProgress = progressSender(extra);
+        await onProgress(0, 0, "Starting build…");
+        const started = await sxf.planGenerate(args.project_id);
+        const job = await pollJob(started.job_id, onProgress, extra?.signal);
+        return text(formatResult(job.result, started.project_id, started.preview_url));
+    }
+    catch (e) {
+        return errorText(`Build failed: ${e.message}`);
+    }
+});
+// ── Read ─────────────────────────────────────────────────────────────────────
+server.registerTool("sketchxflow_get_project", {
+    title: "Get a project's status",
+    description: "Return a project's status, preview URL, and page list by project_id.",
+    inputSchema: { project_id: z.string().describe("The project_id.") },
+}, async (args) => {
+    if (!hasKey())
+        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+    try {
+        const p = await sxf.project(args.project_id);
+        const pages = (p.pages || []).map((x) => x.name || x.slug);
+        return text([
+            `${p.name || "Project"}${p.title ? ` — ${p.title}` : ""}`,
+            `Status: ${p.has_html ? "built" : "not built yet"}`,
+            `Preview: ${p.preview_url}`,
+            pages.length ? `Pages (${pages.length}): ${pages.join(", ")}` : "",
+        ].filter(Boolean).join("\n"));
+    }
+    catch (e) {
+        return errorText(`Lookup failed: ${e.message}`);
+    }
+});
+server.registerTool("sketchxflow_list_projects", {
+    title: "List your projects",
+    description: "List the projects in your SketchxFlow account (most recent first).",
+    inputSchema: {},
+}, async () => {
+    if (!hasKey())
+        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+    try {
+        const r = await sxf.listProjects();
+        const rows = (r.projects || []).slice(0, 50);
+        if (!rows.length)
+            return text("No projects yet. Use sketchxflow_design or sketchxflow_plan to create one.");
+        return text(rows.map((p) => `• ${p.name || p.project_id} — ${p.preview_url}`).join("\n"));
+    }
+    catch (e) {
+        return errorText(`List failed: ${e.message}`);
+    }
+});
+async function main() {
+    if (!hasKey())
+        log("warning: SKETCHXFLOW_API_KEY is not set — tools will return an auth error until it is.");
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log("ready");
+}
+main().catch((e) => {
+    log("fatal:", e.message);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@sketchxflow/mcp",
+  "version": "0.1.0",
+  "description": "SketchxFlow MCP server — design websites and apps from Claude, Cursor, and any MCP client.",
+  "type": "module",
+  "bin": {
+    "sketchxflow-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "sketchxflow",
+    "ai",
+    "design",
+    "website-builder",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3"
+  }
+}