@sketchxflow/mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,62 +1,70 @@
 # @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.
+Design, extend, edit, and **implement** websites and apps with
+[SketchxFlow](https://sketchxflow.com) — directly from Claude Code, Codex, Cursor,
+Claude Desktop, Windsurf, or any MCP client.
 
-## Setup
+## Install (one command, all your agents)
 
-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:**
+```bash
+npx @sketchxflow/mcp install
+```
 
-   ```json
-   {
-     "mcpServers": {
-       "sketchxflow": {
-         "command": "npx",
-         "args": ["-y", "@sketchxflow/mcp"],
-         "env": { "SKETCHXFLOW_API_KEY": "sk_live_…" }
-       }
-     }
-   }
-   ```
+An interactive wizard detects your installed MCP clients (Claude Desktop, Claude
+Code, Cursor, VS Code, Windsurf, Codex), lets you pick which to set up, asks for
+your API key once, and writes each client's config. Restart the clients it set up
+and you're done.
 
-   - **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`
+> **API key:** sign in at [sketchxflow.com](https://sketchxflow.com) →
+> **Account → API keys** → *Generate key*.
 
-3. Restart the client. Ask it to *"design a landing page for a coffee subscription startup"* and watch it build.
+### Manual config (any client)
+```json
+{
+  "mcpServers": {
+    "sketchxflow": {
+      "command": "npx",
+      "args": ["-y", "@sketchxflow/mcp"],
+      "env": { "SKETCHXFLOW_API_KEY": "sk_live_…" }
+    }
+  }
+}
+```
+(VS Code uses a `"servers"` key; Codex uses `[mcp_servers.sketchxflow]` in `~/.codex/config.toml` — the wizard handles all of these.)
 
 ## 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.
+| `sketchxflow_clarify` | Interview the user (free) to build the brief before designing — returns the next question + a ready-to-use `design_prompt`. |
+| `sketchxflow_design_page` | Generate one page. Omit `project_id` → new project; pass one → add a brand-consistent page to it. |
+| `sketchxflow_edit` | Natural-language change to one page section/component (brand-locked). |
+| `sketchxflow_get_code` | Return a page's full HTML (Tailwind inline) so the agent can implement/adapt it in your stack. |
+| `sketchxflow_get_project` / `sketchxflow_list_projects` | Status / list. |
+
+### How a coding agent uses it
+1. *(optional)* `sketchxflow_clarify` — ask the user what they want, one question at a time.
+2. `sketchxflow_design_page` — create the project + first page (or add a page).
+3. `sketchxflow_get_code` — pull the HTML and re-implement it in the user's framework.
+4. `sketchxflow_edit` — tweak a section; `get_code` again.
+
+Each project maps to one SketchxFlow project (visible in your dashboard, charged
+to your coin balance, editable/exportable/publishable from the web app). Design
+and edit run as background jobs; the 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). |
+| `SKETCHXFLOW_API_URL` | no | `https://sketchxflow.com` | Override the API base. |
 
 ## Develop
 
 ```bash
-npm install
-npm run build      # tsc → dist/
-node dist/index.js # runs over stdio (expects an MCP client on stdin/stdout)
+npm install && npm run build
+node dist/index.js            # MCP server (stdio)
+node dist/index.js install    # setup wizard
 ```
 
 MIT licensed.

package/dist/client.js

@@ -47,12 +47,14 @@ async function req(path, method, body) {
     }
     return data;
 }
+const enc = encodeURIComponent;
 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"),
+    addPage: (id, b) => req(`/api/mcp/projects/${enc(id)}/pages`, "POST", b),
+    edit: (id, slug, instruction) => req(`/api/mcp/projects/${enc(id)}/pages/${enc(slug)}/edit`, "POST", { instruction }),
+    getCode: (id, slug) => req(`/api/mcp/projects/${enc(id)}/pages/${enc(slug)}/code`, "GET"),
+    clarify: (b) => req("/api/mcp/clarify", "POST", b),
+    job: (id) => req(`/api/mcp/jobs/${enc(id)}`, "GET"),
+    project: (id) => req(`/api/mcp/projects/${enc(id)}`, "GET"),
     listProjects: () => req("/api/mcp/projects", "GET"),
 };

package/dist/index.js

@@ -1,38 +1,40 @@
 #!/usr/bin/env node
 /**
- * SketchxFlow MCP server.
+ * SketchxFlow MCP server + installer.
  *
- * 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.
+ *   npx -y @sketchxflow/mcp            → run the MCP server (stdio)
+ *   npx -y @sketchxflow/mcp install    → interactive setup wizard (all clients)
  *
- * Auth: per-user API key in SKETCHXFLOW_API_KEY (Account → API keys).
+ * As an MCP server it lets coding agents (Claude Code, Codex, Cursor, …) design,
+ * extend, edit, AND implement web/app pages via SketchxFlow. Generation runs as a
+ * background job server-side; this process polls to completion with progress
+ * notifications. Auth: per-user API key in SKETCHXFLOW_API_KEY.
  */
 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";
+// Subcommand dispatch — keep this BEFORE any stdio wiring.
+const argv = process.argv.slice(2);
+if (argv[0] === "install" || argv[0] === "setup" || argv[0] === "init") {
+    const { runInstaller } = await import("./install.js");
+    await runInstaller();
+    process.exit(0);
+}
 // 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). */
+const noKey = () => errorText("SKETCHXFLOW_API_KEY is not set. Generate one at sketchxflow.com → Account → API keys (or run `npx @sketchxflow/mcp install`).");
 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 */
+            await extra.sendNotification({ method: "notifications/progress", params: { progressToken: token, progress, total: total || undefined, message } });
         }
+        catch { /* best-effort */ }
     };
 }
 const POLL_MS = 4000;
@@ -55,169 +57,166 @@ async function pollJob(jobId, onProgress, signal) {
             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.");
+    throw new Error("Timed out after 15 minutes.");
 }
-function formatResult(result, projectId, previewUrl) {
+/** Format a completed job result. Handles both shapes: a fresh design
+ *  ({pages:[…]}) and an add/edit ({slug, html}). Always points the agent at
+ *  get_code to retrieve the HTML to implement. */
+function formatResult(result, projectId, previewUrl, verb) {
     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 lines = [`✅ ${verb}${result?.title ? `: ${result.title}` : result?.name ? `: ${result.name}` : ""}.`, `Preview: ${url}`, `Project ID: ${pid}`];
+    if (Array.isArray(result?.pages) && result.pages.length) {
+        lines.push(`Pages: ${result.pages.map((p) => `${p.name} (${p.slug})`).join(", ")}`);
+        const first = result.pages[0]?.slug || "home";
+        lines.push(`→ Get the code to implement: sketchxflow_get_code(project_id="${pid}", slug="${first}")`);
+    }
+    else if (result?.slug) {
+        lines.push(`Page: ${result.slug}`);
+        lines.push(`→ Get the updated code: sketchxflow_get_code(project_id="${pid}", slug="${result.slug}")`);
+    }
+    return lines.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.",
+const server = new McpServer({ name: "sketchxflow", version: "0.2.0" }, { capabilities: { tools: {} } });
+// ── clarify: interview the user to build the brief ───────────────────────────
+server.registerTool("sketchxflow_clarify", {
+    title: "Ask the user design questions",
+    description: "Use BEFORE designing when the brief is thin. Send the user's latest message (and the running `vision` + `history` from prior turns); get back a reply to relay, the updated `vision` board, `ready` (true when there's enough to design), and `missing` topics. When ready, the response includes `design_prompt` — pass that to sketchxflow_design_page. Free. Loop this with the user one question at a time.",
     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."),
+        message: z.string().describe("The user's latest answer / the initial idea."),
+        history: z.array(z.object({ role: z.string(), content: z.string() })).optional().describe("Prior turns (echo back what you got last call)."),
+        vision: z.any().optional().describe("The `vision` object returned last call — pass it back each turn."),
+        platform: z.enum(["web", "mobile"]).optional(),
     },
-}, async (args, extra) => {
+}, async (args) => {
     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.");
+        return noKey();
     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));
+        const r = await sxf.clarify({ message: args.message, history: args.history, vision: args.vision, platform: args.platform });
+        const out = [r.reply];
+        if (r.missing?.length)
+            out.push(`\nStill needed: ${r.missing.join(", ")}`);
+        out.push(r.ready ? `\n✅ Ready to design.` : `\n(not ready yet — keep asking)`);
+        if (r.design_prompt)
+            out.push(`\nWhen the user confirms, design with this prompt:\n"""${r.design_prompt}"""`);
+        out.push(`\n[state] pass this back next call → vision: ${JSON.stringify(r.vision)}`);
+        return text(out.join("\n"));
     }
     catch (e) {
-        return errorText(`Design failed: ${e.message}`);
+        return errorText(`Clarify 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.",
+// ── design a page: new project OR add to an existing one ──────────────────────
+server.registerTool("sketchxflow_design_page", {
+    title: "Design a page (new project or add to one)",
+    description: "Generate ONE polished page. Omit project_id to start a NEW project (creates the project + its first page). Pass an existing project_id to ADD a page to that project (brand-consistent). Returns a preview URL; call sketchxflow_get_code to pull the HTML to implement. Takes 1–9 min; streams progress.",
     inputSchema: {
-        prompt: z.string().describe("The brief to plan from."),
-        platform: z.enum(["web", "mobile"]).optional().describe("Target surface. Default: web."),
+        prompt: z.string().describe("What this page is — the brief."),
+        project_id: z.string().optional().describe("Existing project to add this page to. Omit to create a new project."),
+        name: z.string().optional().describe("Page name/title (used when adding to a project, e.g. 'Pricing'). Defaults from the prompt."),
+        platform: z.enum(["web", "mobile"]).optional().describe("Only for a new project. Default web."),
+        ai_images: z.boolean().optional(),
+        enable_3d: z.boolean().optional(),
     },
-}, async (args) => {
+}, async (args, extra) => {
     if (!hasKey())
-        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+        return noKey();
     try {
-        const r = await sxf.plan({ prompt: args.prompt, platform: args.platform });
-        return text(formatPlan(r.project_id, r.plan));
+        const onProgress = progressSender(extra);
+        await onProgress(0, 0, args.project_id ? "Adding page…" : "Starting design…");
+        let started;
+        let verb;
+        if (args.project_id) {
+            const name = args.name || args.prompt.split(/[.,\n]/)[0].slice(0, 60) || "New page";
+            started = await sxf.addPage(args.project_id, { name, prompt: args.prompt });
+            verb = "Page added";
+        }
+        else {
+            started = await sxf.design({ prompt: args.prompt, platform: args.platform, ai_images: args.ai_images, enable_3d: args.enable_3d });
+            verb = "Design ready";
+        }
+        const job = await pollJob(started.job_id, onProgress, extra?.signal);
+        return text(formatResult(job.result, started.project_id, started.preview_url, verb));
     }
     catch (e) {
-        return errorText(`Planning failed: ${e.message}`);
+        return errorText(`Design 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'.",
+// ── edit one section/component of a page ──────────────────────────────────────
+server.registerTool("sketchxflow_edit", {
+    title: "Edit a page section/component",
+    description: "Apply a natural-language change to one page — e.g. 'make the hero darker', 'tighten the pricing section', 'swap the testimonial for a logo wall'. Brand-locked: edits stay on-palette/on-type. Returns the updated page; call sketchxflow_get_code for the new HTML.",
     inputSchema: {
-        project_id: z.string().describe("The project_id returned by sketchxflow_plan."),
-        instruction: z.string().describe("How to change the plan."),
+        project_id: z.string(),
+        slug: z.string().describe("Which page (e.g. 'home', 'pricing')."),
+        instruction: z.string().describe("The change to make."),
     },
-}, async (args) => {
+}, async (args, extra) => {
     if (!hasKey())
-        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+        return noKey();
     try {
-        const r = await sxf.planRefine(args.project_id, args.instruction);
-        return text(formatPlan(r.project_id, r.plan));
+        const onProgress = progressSender(extra);
+        await onProgress(0, 0, "Editing…");
+        const started = await sxf.edit(args.project_id, args.slug, args.instruction);
+        const job = await pollJob(started.job_id, onProgress, extra?.signal);
+        return text(formatResult(job.result, started.project_id, started.preview_url, "Edited"));
     }
     catch (e) {
-        return errorText(`Refine failed: ${e.message}`);
+        return errorText(`Edit 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.",
+// ── get the page HTML (to implement) ──────────────────────────────────────────
+server.registerTool("sketchxflow_get_code", {
+    title: "Get a page's HTML to implement",
+    description: "Return the full HTML (Tailwind inline) of a generated page so you can re-implement or adapt it into the user's codebase (React/Next/Vue/plain HTML). Call after sketchxflow_design_page / sketchxflow_edit.",
     inputSchema: {
-        project_id: z.string().describe("The project_id of the planned project."),
+        project_id: z.string(),
+        slug: z.string().describe("Page slug, e.g. 'home'."),
     },
-}, async (args, extra) => {
+}, async (args) => {
     if (!hasKey())
-        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+        return noKey();
     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));
+        const r = await sxf.getCode(args.project_id, args.slug);
+        return text(`Page "${r.slug}" of project ${r.project_id} — preview ${r.preview_url}\n\n\`\`\`html\n${r.html}\n\`\`\``);
     }
     catch (e) {
-        return errorText(`Build failed: ${e.message}`);
+        return errorText(`Get code failed: ${e.message}`);
     }
 });
-// ── Read ─────────────────────────────────────────────────────────────────────
+// ── 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.") },
+    description: "Project status: preview URL + page list (slug/name).",
+    inputSchema: { project_id: z.string() },
 }, async (args) => {
     if (!hasKey())
-        return errorText("SKETCHXFLOW_API_KEY is not set (Account → API keys).");
+        return noKey();
     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"));
+        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.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 () => {
+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).");
+        return noKey();
     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"));
+            return text("No projects yet. Use sketchxflow_design_page to create one.");
+        return text(rows.map((p) => `• ${p.name || p.project_id} [${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);
-});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+if (!hasKey())
+    log("warning: SKETCHXFLOW_API_KEY is not set — tools will return an auth error until it is.");
+log("ready");

package/dist/install.js

@@ -0,0 +1,180 @@
+/**
+ * Interactive setup wizard: `npx @sketchxflow/mcp install`.
+ *
+ * Detects installed MCP clients, lets the user pick which to configure, asks for
+ * the API key once, then writes/merges each client's config in its own format
+ * (JSON `mcpServers`, VS Code `servers`, Codex TOML, or the `claude` CLI).
+ */
+import prompts from "prompts";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+const PLAT = process.platform;
+// Read live (not at module load) so tests can override HOME.
+function home() { return os.homedir(); }
+function appdata() { return process.env.APPDATA || path.join(home(), "AppData", "Roaming"); }
+function p(...segs) { return path.join(...segs); }
+function appSupport(name) {
+    if (PLAT === "darwin")
+        return p(home(), "Library", "Application Support", name);
+    if (PLAT === "win32")
+        return p(appdata(), name);
+    return p(home(), ".config", name);
+}
+export function getClients() {
+    const HOME = home();
+    return [
+        {
+            id: "claude-desktop", name: "Claude Desktop", kind: "json-mcpServers",
+            path: p(appSupport("Claude"), "claude_desktop_config.json"),
+            detectPaths: [appSupport("Claude"), "/Applications/Claude.app"],
+            restart: "Fully quit and reopen Claude Desktop.",
+        },
+        {
+            id: "claude-code", name: "Claude Code (CLI)", kind: "claude-cli",
+            detectPaths: [], // detected via `claude` on PATH below
+            restart: "Already active in new sessions (user scope).",
+        },
+        {
+            id: "cursor", name: "Cursor", kind: "json-mcpServers",
+            path: p(HOME, ".cursor", "mcp.json"),
+            detectPaths: [p(HOME, ".cursor"), "/Applications/Cursor.app"],
+            restart: "Restart Cursor (or toggle the server in Settings → MCP).",
+        },
+        {
+            id: "windsurf", name: "Windsurf", kind: "json-mcpServers",
+            path: p(HOME, ".codeium", "windsurf", "mcp_config.json"),
+            detectPaths: [p(HOME, ".codeium", "windsurf"), "/Applications/Windsurf.app"],
+            restart: "Restart Windsurf.",
+        },
+        {
+            id: "vscode", name: "VS Code (Copilot MCP)", kind: "json-servers",
+            path: p(appSupport("Code"), "User", "mcp.json"),
+            detectPaths: [appSupport("Code"), "/Applications/Visual Studio Code.app"],
+            restart: "Reload VS Code (Cmd/Ctrl+Shift+P → Developer: Reload Window).",
+        },
+        {
+            id: "codex", name: "Codex CLI", kind: "toml-codex",
+            path: p(HOME, ".codex", "config.toml"),
+            detectPaths: [p(HOME, ".codex")],
+            restart: "Active on the next `codex` run.",
+        },
+    ];
+}
+function hasOnPath(bin) {
+    try {
+        execFileSync(PLAT === "win32" ? "where" : "which", [bin], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function detected(c) {
+    if (c.kind === "claude-cli")
+        return hasOnPath("claude");
+    return c.detectPaths.some((x) => { try {
+        return fs.existsSync(x);
+    }
+    catch {
+        return false;
+    } });
+}
+function ensureDir(file) { fs.mkdirSync(path.dirname(file), { recursive: true }); }
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function block(key) {
+    return { command: "npx", args: ["-y", "@sketchxflow/mcp"], env: { SKETCHXFLOW_API_KEY: key } };
+}
+function writeJsonClient(c, key) {
+    const file = c.path;
+    ensureDir(file);
+    const cfg = readJson(file);
+    const root = c.kind === "json-servers" ? "servers" : "mcpServers";
+    cfg[root] = cfg[root] || {};
+    cfg[root].sketchxflow = block(key);
+    fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+    return file;
+}
+function writeCodex(c, key) {
+    const file = c.path;
+    ensureDir(file);
+    let toml = "";
+    try {
+        toml = fs.readFileSync(file, "utf8");
+    }
+    catch { /* new file */ }
+    const blockToml = `[mcp_servers.sketchxflow]\n` +
+        `command = "npx"\n` +
+        `args = ["-y", "@sketchxflow/mcp"]\n` +
+        `env = { SKETCHXFLOW_API_KEY = "${key}" }\n`;
+    const re = /\[mcp_servers\.sketchxflow\][\s\S]*?(?=\n\[|$)/;
+    toml = re.test(toml) ? toml.replace(re, blockToml.trimEnd()) : (toml.trimEnd() + "\n\n" + blockToml);
+    fs.writeFileSync(file, toml.replace(/\n{3,}/g, "\n\n"));
+    return file;
+}
+function writeClaudeCli(key) {
+    try {
+        execFileSync("claude", ["mcp", "remove", "sketchxflow", "-s", "user"], { stdio: "ignore" });
+    }
+    catch { /* not present yet */ }
+    execFileSync("claude", ["mcp", "add", "sketchxflow", "-s", "user", "-e", `SKETCHXFLOW_API_KEY=${key}`, "--", "npx", "-y", "@sketchxflow/mcp"], { stdio: "ignore" });
+    return "claude (user scope)";
+}
+/** Apply the config for one client. Pure (no prompts) → unit-testable. */
+export function applyToClient(c, key) {
+    if (c.kind === "claude-cli")
+        return writeClaudeCli(key);
+    if (c.kind === "toml-codex")
+        return writeCodex(c, key);
+    return writeJsonClient(c, key);
+}
+export { detected };
+export async function runInstaller() {
+    console.log("\n  SketchxFlow MCP — setup\n  Design websites & apps from your AI coding agents.\n");
+    const CLIENTS = getClients();
+    const choices = CLIENTS.map((c) => ({ title: c.name + (detected(c) ? "  ✓ detected" : ""), value: c.id, selected: detected(c) }));
+    const { picked } = await prompts({
+        type: "multiselect", name: "picked", message: "Install into which clients?",
+        choices, hint: "space to toggle, enter to confirm", instructions: false,
+    });
+    if (!picked || !picked.length) {
+        console.log("\n  Nothing selected — exiting.\n");
+        return;
+    }
+    const { key } = await prompts({
+        type: "text", name: "key",
+        message: "Your SketchxFlow API key (sk_live_…)",
+        initial: process.env.SKETCHXFLOW_API_KEY || "",
+        validate: (v) => (v && v.startsWith("sk_")) ? true : "Generate one at sketchxflow.com → Account → API keys",
+    });
+    if (!key) {
+        console.log("\n  No key — exiting. (Get one at sketchxflow.com → Account → API keys.)\n");
+        return;
+    }
+    console.log("");
+    const results = [];
+    for (const id of picked) {
+        const c = CLIENTS.find((x) => x.id === id);
+        try {
+            const where = applyToClient(c, key);
+            results.push({ name: c.name, ok: true, where, restart: c.restart });
+            console.log(`  ✓ ${c.name} → ${where}`);
+        }
+        catch (e) {
+            results.push({ name: c.name, ok: false, where: e.message, restart: c.restart });
+            console.log(`  ✗ ${c.name} — ${e.message}`);
+        }
+    }
+    console.log("\n  Done. To finish, restart the clients you set up:");
+    for (const r of results.filter((x) => x.ok))
+        console.log(`   • ${r.name}: ${r.restart}`);
+    console.log("\n  Then ask your agent: “design a landing page for …”\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sketchxflow/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "SketchxFlow MCP server — design websites and apps from Claude, Cursor, and any MCP client.",
   "type": "module",
   "bin": {
@@ -29,10 +29,12 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "prompts": "^2.4.2",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
+    "@types/prompts": "^2.4.9",
     "typescript": "^6.0.3"
   }
 }