@ammduncan/easel 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to easel. This project adheres to [Semantic Versioning](https://semver.org/).
+
+## 0.2.2 — 2026-05-22
+
+### Fixed
+- **MCP servers wired via `npx -y @ammduncan/easel` now boot the MCP server instead of printing CLI help.** When stdin isn't a TTY (i.e. the process is launched over a pipe by an MCP client), the bin transparently boots the MCP server. Interactive terminal use still shows help. Previously, Claude Desktop, Cursor, and Windsurf saw the CLI's help text on stdout and reported `Unexpected token 'e' is not valid JSON` for every line.
+
+### Added
+- Explicit `easel mcp` subcommand that runs the stdio MCP server in the foreground (used internally by the no-TTY auto-detection; available as an explicit entry point for clients that want it).
+
+### Changed
+- `dist/mcp.js` now exports `main()` and only auto-runs when invoked directly (not when imported), so the CLI can route to it without double-booting.
+
+## 0.2.1 — 2026-05-22
+
+### Added
+- `easel setup --client cursor|claude-desktop|windsurf` writes the MCP entry into each client's config file, merging into any existing `mcpServers` map. Sibling top-level keys are preserved. (`src/client-setup.ts`)
+- README leads with the npx install; per-client install commands documented; generic JSON snippet for any other MCP-speaking client.
+- This `CHANGELOG.md`.
+
+### Notes
+- The Claude Code setup path (bare `easel setup`) is unchanged.
+
+## 0.2.0 — 2026-05-22
+
+### Added
+- Published to npm as [`@ammduncan/easel`](https://www.npmjs.com/package/@ammduncan/easel). Any MCP client can now install with `npx -y @ammduncan/easel` — no clone, no build.
+- `EASEL_SESSION_ID` env var as the highest-priority override for session resolution.
+- Synthetic PPID-derived session id as a final fallback when no Claude Code hook fired and no transcript exists — gives Cursor, Claude Desktop, Windsurf, and any other MCP client a stable session per chat with zero setup beyond the MCP entry.
+- MCP-side auto-open: non-CC clients have no `SessionStart` hook to open the tab, so the MCP server now opens it on the first tool call when no hook file exists for this PPID. One-shot guard avoids re-opening if the user closes the tab. Claude Code behaviour unchanged.
+- `LICENCE` file (MIT).
+
+### Changed
+- `resolveClaudeSessionId()` is now total — always returns a string. Dead "no session id" error branches removed from `cli.ts` and `mcp.ts`.
+- `package.json` reshaped for npm publishing: scoped name `@ammduncan/easel`, MIT licence, repo/homepage/bugs URLs, keywords for discovery, `engines.node >=20`, `files` whitelist (only bin/dist/scripts/skills/README/LICENCE in the tarball), `prepublishOnly` script, `publishConfig.access=public`.
+- Package size: 47 kB tarball, 165 kB unpacked, 3 runtime deps.
+
+## 0.1.0 — internal baseline
+
+The pre-publish baseline. Highlights from the unreleased history:
+
+- Renamed project from `claude-display` to `easel`; data root migrated from `~/.claude-display` to `~/.easel` with one-shot `mv` on first start. Browser localStorage keys (`claude-display:*`) and postMessage events migrated to the `easel:*` namespace with a browser-side migration shim. Internal `__CLAUDE_DISPLAY__` window global renamed to `__EASEL__`. Env vars renamed (`CLAUDE_DISPLAY_PORT` → `EASEL_PORT` with legacy fallback).
+- Dropped `jq` as a runtime dependency. Ported `scripts/easel-session-id.sh` to `scripts/easel-session-id.mjs` (Node stdlib only).
+- Added `easel restart` command.
+- MCP tool names finalised as `push`, `open`, `config`, `label` (invoked as `mcp__easel__*`).
+- Skill folder canonicalised at `skills/using-easel/`.

package/README.md

@@ -1,37 +1,68 @@
 # easel
 
-A live browser tab for every Claude Code session. Agents push HTML — explanations, mockups, diagrams, diffs, comparisons — to a scrolling feed you keep open in split-screen. No more wall-of-text in the terminal.
+A live browser tab for every AI coding session. Agents push HTML — explanations, mockups, diagrams, diffs, comparisons — to a scrolling feed you keep open in split-screen. No more wall-of-text in the terminal.
 
 ```
-┌──────────── Claude Code (left) ────────────┐    ┌────── easel (right) ──────────────┐
+┌──────────── agent (left) ──────────────────┐    ┌────── easel (right) ──────────────┐
 │                                            │    │  s/<session-id>  •  3 pushes • live│
 │  > walk me through the new auth flow       │    │  ───────────────────────────────── │
 │                                            │    │  #1  Auth flow overview            │
-│  pushed to display ↗ — #1                  │    │  ┌────────────────────────────────┐│
+│  pushed to easel ↗ — #1                    │    │  ┌────────────────────────────────┐│
 │                                            │    │  │  Three actors talk to each…    ││
 │  > what could break?                       │    │  └────────────────────────────────┘│
 │                                            │    │                                    │
-│  pushed to display ↗ — #2                  │    │  #2  Failure modes                 │
+│  pushed to easel ↗ — #2                    │    │  #2  Failure modes                 │
 └────────────────────────────────────────────┘    └────────────────────────────────────┘
 ```
 
+Works with **Claude Code**, **Cursor**, **Claude Desktop**, **Windsurf**, and any other MCP-speaking client.
+
 ## Why
 
-Long markdown explanations bury what the agent is actually doing. Visual content (mockups, comparisons, diagrams) is even worse in a TTY. `easel` gives each chat session its own browser tab, and a single MCP tool — `push` — that the agent uses proactively. The terminal stays as a conversation log; the browser carries the substance.
+Long markdown explanations bury what the agent is actually doing. Visual content (mockups, comparisons, diagrams) is even worse in a TTY. easel gives each chat session its own browser tab, and a single MCP tool — `push` — that the agent uses proactively. The terminal stays as a conversation log; the browser carries the substance.
 
 ## Install
 
-Requires Node 20+, `git`, and Claude Code.
+Requires Node 20+.
+
+### Claude Code
+
+```bash
+npx -y @ammduncan/easel setup
+```
+
+That registers the MCP at user scope, installs the `using-easel` skill so the agent knows when to push, and adds the `SessionStart` hooks that resolve session IDs and auto-open the tab. Restart Claude Code and you're done.
+
+### Cursor / Claude Desktop / Windsurf
+
+One command per client:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/AmmDuncan/easel/main/scripts/install.sh | bash
+npx -y @ammduncan/easel setup --client cursor
+npx -y @ammduncan/easel setup --client claude-desktop
+npx -y @ammduncan/easel setup --client windsurf
 ```
 
-The installer clones to `~/.local/share/easel` (override with `EASEL_DIR=…`), runs `npm install && npm run build`, then registers the MCP at user scope and adds two `SessionStart` hooks (session-id capture + auto-open tab). Idempotent — safe to re-run to update.
+Each writes the MCP entry to the client's config file (`~/.cursor/mcp.json`, `~/Library/Application Support/Claude/claude_desktop_config.json`, or `~/.codeium/windsurf/mcp_config.json`). Restart the client to load it.
 
-Restart Claude Code afterwards.
+### Any other MCP client
 
-### Manual install
+Drop this snippet into your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "easel": {
+      "command": "npx",
+      "args": ["-y", "@ammduncan/easel"]
+    }
+  }
+}
+```
+
+The MCP child mints its own session from its parent process ID — no hook required. Set `EASEL_SESSION_ID` in the client's `env` block if you want to pin a specific session.
+
+### From source (for contributors)
 
 ```bash
 git clone https://github.com/AmmDuncan/easel.git ~/work/tools/easel
@@ -56,20 +87,20 @@ Agents invoke them as `mcp__easel__push`, `mcp__easel__open`, etc.
 - **Presets**: `paper` (warm pitstop-style, amber accent — default), `aurora` (deep canvas + violet glow halos), `slate` (cool neutral, cyan accent)
 - **Themes**: light / dark, with sun-moon toggle in the topbar
 - **Density**: `carded` (bordered cards) or `flat` (no chrome, whitespace separates pushes)
-- Three swatches + density toggle live in the topbar; config persists in `~/.easel/config.json` and SSE-broadcasts across all open tabs
+- Three swatches + density toggle live in the topbar; config persists in `~/.easel/config.json` and SSE-broadcasts across all open tabs.
 
 ## Sessions
 
-- Each Claude Code session gets its own URL: `localhost:7878/s/<session-id>`
-- Session IDs come from Claude Code itself (via the pitstop-style SessionStart hook)
-- Sessions auto-rename to `cwd-basename` by default; you can rename them via the click-to-edit label in the topbar, or the agent can via the `label` tool
-- Idle sessions (>24h since last push) are GC'd every 10 minutes
-- Up to 50 pushes per session; oldest evicted from disk first
-- Per-push delete (trash icon on each card) + per-session delete (hover any row in the switcher or index)
+- Each chat session gets its own URL: `localhost:7878/s/<session-id>`
+- Session IDs come from the agent client. Claude Code provides them via a SessionStart hook; other MCP clients fall through to a stable PPID-derived id for the MCP child. Override either via the `EASEL_SESSION_ID` env var.
+- Sessions auto-rename to `cwd-basename` by default; you can rename them via the click-to-edit label in the topbar, or the agent can via the `label` tool.
+- Idle sessions (>24h since last push) are GC'd every 10 minutes.
+- Up to 50 pushes per session; oldest evicted from disk first.
+- Per-push delete (trash icon on each card) + per-session delete (hover any row in the switcher or index).
 
 ## Tool surface
 
-The MCP exposes one server (`display`) with four tools. HTML is rendered in a sandboxed iframe (`sandbox="allow-scripts"`) with a baseline design system injected — off-white / charcoal, Inter, presentation-scale typography — so plain `<h1>/<h2>/<p>` markup looks right without extra CSS. Authors can also write a full `<!DOCTYPE html>` document and take ownership of styling.
+The MCP exposes one server (`easel`) with four tools. HTML is rendered in a sandboxed iframe (`sandbox="allow-scripts"`) with a baseline design system injected — off-white / charcoal, Inter, presentation-scale typography — so plain `<h1>/<h2>/<p>` markup looks right without extra CSS. Authors can also write a full `<!DOCTYPE html>` document and take ownership of styling.
 
 Inside pushed HTML, semantic chips are available out of the box:
 
@@ -84,6 +115,20 @@ Inside pushed HTML, semantic chips are available out of the box:
 
 Each is themed for both light and dark with a soft outer glow.
 
+## CLI
+
+```
+easel open                     ensure server is running, open this session's tab
+easel url                      print this session's URL
+easel config                   print / set { preset, theme, density }
+easel setup                    Claude Code: hooks + MCP + skill
+easel setup --client <name>    register the MCP in another client (cursor, claude-desktop, windsurf)
+easel restart                  kill + respawn the HTTP server (handy after a build)
+easel update                   git pull + build + setup (clone installs only)
+easel server                   run the HTTP server in the foreground (debug)
+easel version
+```
+
 ## Files
 
 ```
@@ -93,10 +138,11 @@ src/
   http-entry.ts       process entry for the HTTP server
   server-manager.ts   lockfile + spawn coordination
   session-store.ts    disk persistence + retention sweep
-  session-id.ts       3-tier resolver (env / hook file / transcript scan)
+  session-id.ts       5-tier resolver (env / hook file / transcript scan / synthetic PPID)
   config-store.ts     preset / theme / density persistence
-  paths.ts            shared constants
-  cli.ts              `easel open|url|setup|config|server|version`
+  client-setup.ts     per-client config writers (cursor, claude-desktop, windsurf)
+  paths.ts            shared constants + legacy-dir migration
+  cli.ts              `easel open|url|setup|config|server|restart|update|version`
   client/
     viewer.html       single-session feed
     index.html        sessions index page
@@ -106,7 +152,7 @@ src/
     index.js          index page client
 scripts/
   easel-session-id.mjs  SessionStart hook (Node, zero deps)
-  install.sh            one-shot installer
+  install.sh            one-shot installer (clone installs)
   copy-client.mjs       build-time copy of client assets
 bin/
   easel                 shebang → dist/cli.js

package/dist/cli.js

@@ -8,6 +8,7 @@ import { ensureHttpServer, readLock } from "./server-manager.js";
 import { resolveClaudeSessionId } from "./session-id.js";
 import { HOOK_DIR, DATA_ROOT } from "./paths.js";
 import { registerSession } from "./session-store.js";
+import { listClients, setupClient, } from "./client-setup.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = resolve(__dirname, "..");
 function help() {
@@ -22,8 +23,12 @@ Usage:
   easel config preset paper       set preset to paper | aurora | slate
   easel config theme dark         set theme to light | dark
   easel config preset aurora theme light   set both at once
-  easel setup           install SessionStart hook + register MCP in ~/.claude/settings.json
+  easel setup                    install Claude Code hook + register MCP in ~/.claude/settings.json
+  easel setup --client cursor    register the MCP in Cursor's config
+  easel setup --client claude-desktop    register the MCP in Claude Desktop's config
+  easel setup --client windsurf  register the MCP in Windsurf's config
   easel update          git pull + npm install + build + setup (re-runs setup to apply new conventions)
+  easel mcp             run the stdio MCP server in the foreground (used by clients)
   easel restart         kill the running HTTP server and respawn it (picks up new builds/paths)
   easel server          run the HTTP server in the foreground (debug)
   easel version
@@ -330,9 +335,32 @@ async function main() {
         case "url":
             await cmdUrl();
             return;
-        case "setup":
+        case "setup": {
+            const clientIdx = rest.indexOf("--client");
+            if (clientIdx !== -1) {
+                const name = rest[clientIdx + 1];
+                if (!name) {
+                    console.error(`[easel] --client requires a name. Available: ${listClients().join(", ")}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (!listClients().includes(name)) {
+                    console.error(`[easel] unknown client "${name}". Available: ${listClients().join(", ")}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                try {
+                    setupClient(name);
+                }
+                catch (err) {
+                    console.error(`[easel] setup --client ${name} failed:`, err.message);
+                    process.exitCode = 1;
+                }
+                return;
+            }
             cmdSetup();
             return;
+        }
         case "server":
             await cmdServer();
             return;
@@ -350,7 +378,23 @@ async function main() {
         case "-v":
             cmdVersion();
             return;
-        case undefined:
+        case "mcp": {
+            const { main: mcpMain } = await import("./mcp.js");
+            await mcpMain();
+            return;
+        }
+        case undefined: {
+            // When invoked over a pipe (no TTY on stdin) — e.g. an MCP client
+            // launching us via `npx -y @ammduncan/easel` — boot the MCP server.
+            // Interactive terminal use still gets the help text.
+            if (!process.stdin.isTTY) {
+                const { main: mcpMain } = await import("./mcp.js");
+                await mcpMain();
+                return;
+            }
+            help();
+            return;
+        }
         case "help":
         case "--help":
         case "-h":

package/dist/client-setup.js

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir, platform } from "node:os";
+const CLIENTS = {
+    "claude-desktop": {
+        name: "claude-desktop",
+        label: "Claude Desktop",
+        configPath: () => {
+            const home = homedir();
+            if (platform() === "darwin") {
+                return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+            }
+            if (platform() === "win32") {
+                const appData = process.env.APPDATA ?? join(home, "AppData", "Roaming");
+                return join(appData, "Claude", "claude_desktop_config.json");
+            }
+            return join(home, ".config", "Claude", "claude_desktop_config.json");
+        },
+        postSetup: "Quit and relaunch Claude Desktop to load the MCP server.",
+    },
+    cursor: {
+        name: "cursor",
+        label: "Cursor",
+        configPath: () => join(homedir(), ".cursor", "mcp.json"),
+        postSetup: "Open Cursor and toggle MCP servers in Settings → Features → MCP, " +
+            "or restart Cursor for the registration to take effect.",
+    },
+    windsurf: {
+        name: "windsurf",
+        label: "Windsurf",
+        configPath: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+        postSetup: "Restart Windsurf to load the MCP server.",
+    },
+};
+export function listClients() {
+    return Object.keys(CLIENTS);
+}
+export function setupClient(name) {
+    const spec = CLIENTS[name];
+    if (!spec) {
+        throw new Error(`unknown client: ${name}`);
+    }
+    const configPath = spec.configPath();
+    const config = readJson(configPath);
+    const mcpServers = config.mcpServers ?? {};
+    mcpServers.easel = {
+        command: "npx",
+        args: ["-y", "@ammduncan/easel"],
+    };
+    config.mcpServers = mcpServers;
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    console.log(`[easel] ${spec.label} configured`);
+    console.log(`  - wrote ${configPath}`);
+    console.log(`  - ${spec.postSetup}`);
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const text = readFileSync(path, "utf-8").trim();
+        if (!text)
+            return {};
+        const parsed = JSON.parse(text);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch (err) {
+        throw new Error(`couldn't parse existing config at ${path}: ${err.message}`);
+    }
+}

package/dist/mcp.js

@@ -79,7 +79,7 @@ async function pushToServer(args) {
     }
     return (await r.json());
 }
-async function main() {
+export async function main() {
     const server = new Server({ name: "easel", version: "0.1.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
@@ -229,7 +229,12 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-main().catch((err) => {
-    console.error("[easel mcp] fatal:", err);
-    process.exit(1);
-});
+// Auto-run when invoked directly (e.g. `node dist/mcp.js`), not when imported.
+const invokedDirectly = import.meta.url === `file://${process.argv[1]}` ||
+    import.meta.url.endsWith("/dist/mcp.js");
+if (invokedDirectly) {
+    main().catch((err) => {
+        console.error("[easel mcp] fatal:", err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ammduncan/easel",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A live browser tab for every Claude Code (and MCP) session. The push MCP tool appends HTML cards to a scrolling feed you keep open in split-screen.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "scripts/easel-session-id.mjs",
     "skills/",
     "README.md",
+    "CHANGELOG.md",
     "LICENCE"
   ],
   "scripts": {