@diffui.mcp/install 0.2.0 → 0.2.1

package/README.md

@@ -9,11 +9,18 @@ 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"
   }
 }
 ```
 
+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
@@ -69,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

@@ -27,6 +27,14 @@ 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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffui.mcp/install",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Launcher for the diffui MCP server (stdio). Installs the Cursor skill on first start.",
   "license": "MIT",
   "type": "module",

package/skill/SKILL.md

@@ -15,8 +15,7 @@ description: >-
 # Diffui designer
 
 You orchestrate diffui (an AI design-generation canvas) through its **MCP tools**.
-The user sees the images you return inline, and can also watch the canvas live
-in their browser. Follow this choreography.
+The user sees all option images inline in the tool result. Follow this choreography.
 
 ## When this skill applies (required)
 
@@ -32,7 +31,7 @@ Treat these as the same class of request:
 
 **Two phases — never merge them:**
 
-1. **Design (diffui MCP)** — `create_project` → `open_canvas` →
+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
@@ -50,7 +49,9 @@ calls for a one-page request.
 
 **After `generate_options`:**
 
-- Present options as Option A–D with imageIds
+- 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
@@ -59,8 +60,10 @@ calls for a one-page request.
 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 (audience, tone,
-sections, layout, color/mood). Do not substitute concept bullets for `generate_options`.
+**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:**
 
@@ -84,9 +87,9 @@ one sentence.
 
 ## 0. Setup
 
-1. For a new design session, call `create_project`, then `open_canvas` so the
-   user can watch generations stream in. Reuse the same `project_id` for the
-   whole session.
+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
@@ -98,10 +101,9 @@ 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).
-- Present the four images labeled **Option 1–4** and keep the
-  `option → imageId` ledger from the tool result. You will need those
-  imageIds for every later step — always carry the ledger forward in your
-  reasoning.
+- 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").
@@ -109,27 +111,21 @@ When the user describes a design they want:
 ## 2. Generating with inputs
 
 `generate_with_inputs` handles any request where existing images should
-shape the result. Each input gets a short label; write the prompt
-referencing the labels with `@` — diffui rigs the labeled images as named
-references. Inputs can come from three sources, mixed freely:
-
-- **Earlier options** (`image_id` from your ledger) — "combine the top of
-  the first option and the bottom of the second":
-  `inputs: [{image_id: <opt1>, label: "option-1"}, {image_id: <opt2>,
-  label: "option-2"}]`, prompt "Use the top section of @option-1 and the
-  bottom section of @option-2, merged into one cohesive page."
-- **Local files** (`file_path`, uploaded automatically) — "use logo.png and
-  create a landing page with it in the top right":
-  `inputs: [{file_path: "/path/to/logo.png", label: "logo"}]`, prompt
-  "Landing page for ... with @logo placed in the top right of the header."
-- **Uploaded assets** (`asset_id` from an earlier `upload_reference`) —
-  e.g. a screenshot of the user's current app: "generate a settings page
-  matching @screenshot's visual style."
-
-Keep spatial phrases tied to their labels ("the header from @option-4",
-"@logo in the top right") — diffui resolves positions per named reference.
-Present the results as new numbered options and update your ledger. Use
-`upload_reference` first when a file will be reused across several
+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
@@ -143,11 +139,10 @@ option's imageId (from your ledger) is the only handle you need. Immediately:
    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 each page from the chosen image.** For every accepted page, call
-   `generate_page` with `input_image_id` set to the **chosen option's imageId**
-   so the header, footer, palette, and type carry over. In the prompt, mention
-   `@reference` for what must stay consistent and describe what changes (the
-   page's own content and layout).
+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.
 
@@ -213,9 +208,9 @@ When the design flow feels complete (pages generated, user satisfied), ask:
 
 - **Design before code.** If you have not called `generate_options` this session,
   you are not allowed to create webpage files yet.
-- Always show generated images inline right after each tool call returns.
-- Keep a running ledger of option numbers → imageIds → page names; restate
-  it briefly when the user refers to options by number.
+- 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