@diffui.mcp/install 0.1.0 → 0.2.1

package/README.md

@@ -9,15 +9,26 @@ Thin Node launcher for the diffui MCP server. Cursor (and other MCP hosts) run:
   "args": ["-y", "@diffui.mcp/install@latest"],
   "env": {
     "DIFFUI_API_BASE": "https://diffui.ai",
-    "DIFFUI_API_KEY": "dui_..."
+    "DIFFUI_API_KEY": "dui_...",
+    "npm_config_prefix": "",
+    "NPM_CONFIG_PREFIX": "",
+    "PATH": "/opt/homebrew/bin:/opt/homebrew/opt/node@22/bin:/opt/homebrew/opt/node@20/bin:/usr/local/bin:/usr/bin:/bin"
   }
 }
 ```
 
-On first start, the launcher downloads the platform `diffui-mcp` binary from
-`{DIFFUI_API_BASE}/mcp/` into `~/.diffui/bin/diffui-mcp`, then execs it with
-inherited stdio. Credentials can also come from the MCP `authenticate` tool
-(`~/.diffui/credentials`).
+Cursor injects `npm_config_prefix` inside its app bundle (`…/Cursor.app/…/resources/lib`).
+That path does not exist, so `npx` fails with `ENOENT` unless those vars are cleared.
+The diffui install deeplink sets empty prefix values and prepends common system paths to `PATH`.
+
+On first start, the launcher:
+
+1. Copies the bundled design-first skill to `~/.cursor/skills/diffui/SKILL.md` (updates when
+   the launcher npm version changes; set `DIFFUI_SKIP_SKILL_INSTALL=1` to skip).
+2. Downloads the platform `diffui-mcp` binary from `{DIFFUI_API_BASE}/mcp/` into
+   `~/.diffui/bin/diffui-mcp`, then execs it with inherited stdio.
+
+Credentials can also come from the MCP `authenticate` tool (`~/.diffui/credentials`).
 
 ## Publish to npm
 
@@ -28,8 +39,14 @@ Prerequisites:
 2. npm account in the [@diffui.mcp](https://www.npmjs.com/org/diffui.mcp) org.
 
 ```bash
+./scripts/publish-mcp-install.sh
+```
+
+This syncs `skills/diffui/SKILL.md` into the package, then publishes. Or manually:
+
+```bash
+./scripts/sync-mcp-skill.sh
 cd packages/mcp-install
-npm login
 npm publish --access public
 ```
 
@@ -59,5 +76,5 @@ npm link
 
 ## Cursor deeplink
 
-The diffui app builds install links with `command: npx` and
-`args: ["-y", "@diffui.mcp/install@latest"]` plus env for API base and key.
+The diffui app builds install links with `command: npx`,
+`args: ["-y", "@diffui.mcp/install@latest"]`, npm prefix overrides, and env for API base and key.

package/launcher.mjs

@@ -1,20 +1,41 @@
 #!/usr/bin/env node
 /**
  * diffui MCP launcher for Cursor / Claude / npx.
- * Ensures ~/.diffui/bin/diffui-mcp exists, then execs it with inherited stdio.
+ * Ensures ~/.diffui/bin/diffui-mcp exists, installs the Cursor skill to
+ * ~/.cursor/skills/diffui on first start (or when the launcher version changes),
+ * then execs the MCP binary with inherited stdio.
  *
  * Env (from Cursor mcp.json or shell):
  *   DIFFUI_API_BASE — API origin (default https://diffui.ai)
  *   DIFFUI_API_KEY  — optional; authenticate tool can store ~/.diffui/credentials
+ *   DIFFUI_SKIP_SKILL_INSTALL — set to 1 to skip copying SKILL.md
  */
 import { spawn, spawnSync } from "node:child_process";
-import { chmodSync, createWriteStream, existsSync, mkdirSync } from "node:fs";
+import {
+  chmodSync,
+  copyFileSync,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { arch, homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { pipeline } from "node:stream/promises";
 import { get as httpsGet } from "node:https";
 import { get as httpGet } from "node:http";
 
+// Cursor MCP may inherit npm prefix inside the app bundle; drop it before any child spawns.
+for (const key of ["npm_config_prefix", "NPM_CONFIG_PREFIX"]) {
+  const value = process.env[key];
+  if (value && /Cursor\.app/i.test(value)) {
+    delete process.env[key];
+  }
+}
+
+const launcherDir = dirname(fileURLToPath(import.meta.url));
 const base = String(process.env.DIFFUI_API_BASE || "https://diffui.ai").replace(/\/+$/, "");
 const dest = join(homedir(), ".diffui", "bin", "diffui-mcp");
 
@@ -31,6 +52,43 @@ function binaryName() {
   throw new Error(`diffui-mcp: unsupported platform ${platform()}-${arch()}`);
 }
 
+function launcherVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(launcherDir, "package.json"), "utf8"));
+    return String(pkg.version || "0.0.0");
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function ensureCursorSkill() {
+  if (process.env.DIFFUI_SKIP_SKILL_INSTALL === "1") return;
+
+  const skillSrc = join(launcherDir, "skill", "SKILL.md");
+  if (!existsSync(skillSrc)) return;
+
+  const skillDir = join(homedir(), ".cursor", "skills", "diffui");
+  const skillDest = join(skillDir, "SKILL.md");
+  const versionStamp = join(skillDir, ".diffui-install-version");
+  const version = launcherVersion();
+
+  let installed = "";
+  if (existsSync(versionStamp)) {
+    try {
+      installed = readFileSync(versionStamp, "utf8").trim();
+    } catch {
+      installed = "";
+    }
+  }
+
+  if (installed === version && existsSync(skillDest)) return;
+
+  mkdirSync(skillDir, { recursive: true });
+  copyFileSync(skillSrc, skillDest);
+  writeFileSync(versionStamp, `${version}\n`, "utf8");
+  process.stderr.write(`diffui-mcp: installed Cursor skill at ${skillDest}\n`);
+}
+
 async function download(url, path) {
   const getter = url.startsWith("https:") ? httpsGet : httpGet;
   await new Promise((resolve, reject) => {
@@ -72,6 +130,7 @@ async function ensureBinary() {
   return dest;
 }
 
+ensureCursorSkill();
 const bin = await ensureBinary();
 const child = spawn(bin, [], {
   stdio: "inherit",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@diffui.mcp/install",
-  "version": "0.1.0",
-  "description": "Launcher for the diffui MCP server (stdio). Used by Cursor Add to Cursor.",
+  "version": "0.2.1",
+  "description": "Launcher for the diffui MCP server (stdio). Installs the Cursor skill on first start.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   },
   "files": [
     "launcher.mjs",
-    "README.md"
+    "README.md",
+    "skill/SKILL.md"
   ],
   "engines": {
     "node": ">=18"

package/skill/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: diffui-designer
+description: >-
+  Runs the diffui MCP workflow before any HTML/CSS/JS is written: create_project,
+  generate_options (4 variants), generate_page, create_build_link, then implement
+  code from the build markdown. Auth (whoami/authenticate) only on tool errors —
+  installs usually include DIFFUI_API_KEY already. REQUIRED when the user asks to
+  create, build, or design a webpage, website, landing page, app screen, dashboard,
+  or UI — including "create a webpage for …", "design first then build/create in …",
+  themed sites (jungle, arctic, etc.), and output paths like demoBuild/. Do NOT
+  skip diffui and design manually in prose or jump straight to coding when the
+  diffui MCP server is available. Also use when the user mentions diffui.
+---
+
+# Diffui designer
+
+You orchestrate diffui (an AI design-generation canvas) through its **MCP tools**.
+The user sees all option images inline in the tool result. Follow this choreography.
+
+## When this skill applies (required)
+
+If the **diffui MCP server** is enabled and the user wants a new webpage or UI
+look — even when they also name an output folder (`demoBuild/bongo`,
+`demoBuild/svalbardLan`, etc.) — you **must** use diffui for the design phase.
+Treat these as the same class of request:
+
+- "Create a webpage for …"
+- "Design a landing page …"
+- "Design first, then create/build it in …"
+- "Build a website for …" (when no existing diffui designs are referenced)
+
+**Two phases — never merge them:**
+
+1. **Design (diffui MCP)** — `create_project` →
+   `generate_options` → pick/iterate → (optional `generate_page` for multi-page) →
+   `create_build_link`.
+2. **Implementation (code)** — write HTML/CSS/JS only **after** phase 1, following
+   the build markdown from `create_build_link` into the user's target path.
+
+**Minimal path (single landing page):** `generate_options` → user picks →
+`create_build_link` → code. Do not require brand creation or extra `generate_page`
+calls for a one-page request.
+
+**Forbidden before `generate_options`:**
+
+- Creating `index.html`, stylesheets, or app UI files
+- Choosing colors, typography, and layout entirely from scratch
+- "Designing conceptually" in prose instead of calling `generate_options`
+
+**After `generate_options`:**
+
+- Present options as **Option A–D** with short visual descriptions only
+- Do NOT include imageIds, UUIDs, or other internal metadata in user-facing text
+- Keep the imageId ledger from the assistant-only tool result block in your reasoning
+- User present → ask which to build
+- User said "surprise me" / full trust → pick the strongest fit and say why
+- User unavailable mid-run → wait; do not proceed to code without a pick
+
+**Auth (reactive only):** Do not call `whoami` or `authenticate` before starting — the MCP
+install usually includes credentials. If any tool returns not-authenticated, call
+`authenticate` once, then retry. Do not silently fall back to hand-designed UI.
+
+**Prompt writing:** Turn the user's request into a visual design prompt for
+`generate_options` (audience, tone, sections, layout, color/mood). For
+`generate_page`, use the shortest prompt that fits — page name plus any
+user-requested specifics only.
+
+**Do not:**
+
+- Skip diffui because you can write vanilla HTML/CSS/JS directly.
+- "Design" in chain-of-thought or bullet lists instead of calling `generate_options`.
+- Read `generate_options` tool docs and then decide to design manually.
+- Start creating files in the target directory before diffui options exist.
+
+**Only skip diffui** when the user explicitly says not to ("skip design", "no diffui",
+"just code it"), for pure backend tasks, small non-visual edits, or they point you at
+finished diffui designs / a build link with no new design work. If you skip, say so in
+one sentence.
+
+### Example triggers
+
+| User says | You do first |
+|---|---|
+| Create a jungle-themed coffee shop page in `demoBuild/bongo` | diffui `generate_options`; code goes in `demoBuild/bongo` after build link |
+| Design the page first, then create it in `demoBuild/svalbardLan` | diffui design phase — "design first" means MCP, not manual concept art |
+| Build me a SaaS pricing page | diffui options → pages → build link → code |
+
+## 0. Setup
+
+1. For a new design session, call `create_project`. Reuse the same `project_id` for the
+   whole session. Do **not** call `open_canvas` by default — inline tool images are enough
+   inside Cursor/Claude/Codex. Only open the browser canvas if the user asks to watch there.
+2. **Auth only on error.** Do not proactively call `whoami`. If a tool fails with
+   not-authenticated, call `authenticate` — a browser window opens for one-click
+   connect, or pass an API key from diffui → Settings → API as `api_key`. Then
+   retry the failed call.
+
+## 1. New design → 4 options
+
+When the user describes a design they want:
+
+- Call `generate_options` with `count: 4` and **no** `brand_id` (a fresh
+  canvas auto-diversifies styles across the options, which is what you want).
+- The tool returns all four images inline plus an assistant-only ledger JSON.
+  Keep the `option → imageId` mapping in your reasoning — never paste ids into
+  user-facing messages.
+- Offer three paths: pick one, see more options (`generate_options` again,
+  passing the same `prompt_node_id` to append), or mix elements of options
+  (see "Generating with inputs").
+
+## 2. Generating with inputs
+
+`generate_with_inputs` handles any request where existing images should
+shape the result. Canvas-generated options (`image_id`) are wired from the
+original prompt stack — never re-uploaded. Only `file_path` / `asset_id`
+add new nodes.
+
+Use `@label` in the prompt **only when combining specific parts** across
+inputs. Otherwise keep the prompt short and omit `@` mentions — diffui
+preserves style from the wired reference automatically.
+
+Examples:
+
+- **Combine options** — `inputs: [{image_id: <opt1>, label: "option-1"}, {image_id: <opt2>, label: "option-2"}]`, prompt "Use the header from @option-1 and the footer from @option-2."
+- **Local file** — `inputs: [{file_path: "/path/to/logo.png", label: "logo"}]`, prompt "Landing page with @logo in the top right of the header."
+- **Uploaded asset** — `inputs: [{asset_id: <id>, label: "screenshot"}]`, prompt "Settings page matching @screenshot's visual style."
+
+Use `upload_reference` first when a file will be reused across several
+generations; pass `file_path` directly for one-offs.
+
+## 3. Chosen option → build out the rest of the site
+
+When the user settles on an option, **do not lock anything** — the chosen
+option's imageId (from your ledger) is the only handle you need. Immediately:
+
+1. **Read the header to find the pages.** Look at the chosen design and read
+   the navigation links in its header — those *are* the site's page list. A nav
+   reading "Menu · Our Story · Visit · Contact" means those are the pages to
+   build. Add any obvious page the design implies but the nav omits (a cart /
+   checkout behind a cart icon, a sign-up behind a "Get started" button). List
+   the pages you inferred and confirm or adjust with the user before generating.
+2. **Generate all pages in one parallel call.** Call `generate_pages` with `input_image_id` set to the
+   **chosen option's imageId** and a `pages` array — one entry per screen with a short prompt
+   (e.g. `{name: "Features", prompt: "Create the features page"}`). Do **not** call `generate_page`
+   repeatedly in a loop; that runs sequentially and is much slower.
+3. **Track page name → imageId** in your ledger as each page returns. No lock
+   step is involved; the imageId is the durable handle for brands and the build.
+
+If the header nav is missing or ambiguous, fall back to domain conventions:
+
+- e-commerce: product listing, product detail, cart, checkout
+- SaaS: pricing, features, sign-up, dashboard, settings
+- restaurant: menu, reservations, about, contact
+
+## 4. Auto-create a brand (≥5 screens)
+
+Track the screens kept this session. When **five or more visually consistent
+screens** exist and the conversation suggests more screens are coming,
+proactively offer to create a brand:
+
+> "You now have N screens in a consistent style. Want me to create a brand
+> from them? Future screens will then match automatically."
+
+On yes: `create_brand_from_images` with those imageIds and a name derived
+from the project. After the brand exists:
+
+- Pass `brand_id` on every `generate_options` / `generate_page` call and
+  **stop** manual input rigging — diffui auto-selects the best brand
+  references per prompt via embedding matching.
+- After each new screen the user keeps that fits the brand, call
+  `add_image_to_brand`.
+
+## 5. Brands by name
+
+- If the user names a brand ("use the Acme brand"), call `list_brands`,
+  match by name, and pass its id.
+- If a new request clearly resembles an existing brand (same product,
+  company, or style), proactively suggest using it: check `list_brands`
+  early in a session when the user's intent hints at existing work.
+
+## 6. Convert to code
+
+When the user named an output folder up front (e.g. `demoBuild/bongo`), you still
+complete the diffui design phase first. Remember that path; use it when writing
+files after `create_build_link`.
+
+When the design flow feels complete (pages generated, user satisfied), ask:
+**"Ready to convert these designs to code?"** On yes:
+
+1. Call `create_build_link` with every page you kept — the imageIds in your
+   ledger — (`image_id`, `name`, `original_prompt`, and `brand_id` if one
+   exists) and `include_markdown: true`.
+2. Follow the returned build instructions markdown exactly — it is the
+   source of truth for implementation.
+3. For **all** asset needs during the build, use the diffui build API
+   endpoints documented in the markdown with its `authToken`:
+   - `POST /api/build/generate-image` for photos/illustrations
+   - `POST /api/build/generate-svg` for icons and vector art
+   - `POST /api/build/remove-background` for cutouts
+   - `POST /api/build/create-texture` for seamless background textures
+   Never hotlink canvas/preview URLs into the built code; download assets
+   locally as the markdown instructs.
+4. If you cannot write code in the current environment (e.g. chat-only),
+   give the user the `handoff` string from the tool result to paste into
+   their coding agent.
+
+## Ground rules
+
+- **Design before code.** If you have not called `generate_options` this session,
+  you are not allowed to create webpage files yet.
+- All option images are returned inline by the tool — rely on those, not the browser canvas.
+- Keep a running ledger of option letters → imageIds → page names in your reasoning only;
+  never restate UUIDs to the user.
+- Generations block for the whole render (up to a few minutes) and stream
+  progress updates. A quiet call is working, not stuck — **never re-issue a
+  generation to "retry" a slow one.** A duplicate run desyncs the canvas and
+  leaves you holding imageIds that aren't in committed state. If you truly need
+  longer, raise `timeout_seconds` on a fresh call, don't fire a second one
+  alongside the first.
+- Generation costs the user wallet credits per image. Use the defaults
+  (4 options for explorations, 1 for pages); confirm before unusually large
+  batches or regenerating many screens at once.
+- If a generation fails with a billing error, tell the user their diffui
+  wallet needs funds.
+- If a tool errors with authentication problems, call `authenticate` once and
+  retry — do not open with a proactive whoami check.