pattern-mcp 0.14.1 → 0.15.0

package/README.md

@@ -15,22 +15,22 @@ design reference.
 
 [Website](https://usepattern.sh) · [npm](https://www.npmjs.com/package/pattern-mcp) · [Report an issue](https://github.com/donaldrichard19-LVD/pattern-mcp/issues/new/choose)
 
-**Current release: v0.14.1** — the crash/exit telemetry added in
-v0.14.0 (`pattern_cli_exited`) is now registered before any of this
-file's own module-level code runs, instead of near `main()`, so it
-catches more of what can go wrong on startup; both `pattern_cli_started`
-and `pattern_cli_exited` now also carry the running package version, so
-a crash right around a release can be tied to the old or new binary
-instead of staying ambiguous. Previously: v0.14.0 made a crash on
-startup diagnosable instead of silent, warned at startup if
-`ANTHROPIC_API_KEY` is missing or clearly malformed instead of only
-surfacing a raw 401 mid-call, and added one respectful retry on a 429
-(honoring `Retry-After`). Before that: v0.13.0 added `npx pattern-mcp init`,
-which sets up the connection to your MCP client for you (Claude Code,
-Claude Desktop, Cursor detected and configured automatically; Codex CLI
-gets manual instructions). Running `npx pattern-mcp` bare in your own
-terminal also tells you it needs a client connected, instead of silently
-sitting there. See
+**Current release: v0.15.0** — `npx pattern-mcp init` is now the first
+and only command shown for getting started, everywhere (this README
+and the website); bare `npx pattern-mcp` is documented as the server
+command your client uses, not something to run yourself. The connect
+wizard also no longer asks just once: if you run Pattern bare in your
+own terminal and skip or miss it, it keeps offering on every later run
+until it can actually confirm a client is connected, instead of going
+silent forever after the first try. Previously: v0.14.1 made the
+crash/exit telemetry added in v0.14.0 (`pattern_cli_exited`) register
+before any of this file's own module-level code runs, and tagged both
+it and `pattern_cli_started` with the running package version, so a
+crash right around a release can be tied to the old or new binary. Before
+that: v0.14.0 made a crash on startup diagnosable instead of silent,
+warned at startup if `ANTHROPIC_API_KEY` is missing or clearly
+malformed instead of only surfacing a raw 401 mid-call, and added one
+respectful retry on a 429 (honoring `Retry-After`). See
 [Connect Pattern to your MCP client](#connect-pattern-to-your-mcp-client)
 for more details.
 
@@ -50,11 +50,22 @@ for more details.
 ## Install
 
 ```bash
-npx pattern-mcp
+npx pattern-mcp init
 ```
 
-See [Quick Start](#quick-start) below to add your Anthropic API key and connect
-Pattern to your MCP client.
+This is the only command you run yourself. It downloads Pattern,
+detects which MCP client(s) you have (Claude Code, Claude Desktop,
+Cursor, or Codex CLI), connects each one for you, and offers to add
+your Anthropic API key. See [Quick Start](#quick-start) below for what it
+does step by step, or
+[Connect Pattern to your MCP client](#connect-pattern-to-your-mcp-client)
+if you'd rather connect a client by hand.
+
+`npx pattern-mcp` on its own (no `init`) is the server command your MCP
+client will use once connected -- running it yourself in a bare
+terminal starts a real process that just sits there waiting for a
+client, since nothing has told it to connect to one yet. Prefer `init`
+above for getting started.
 
 ## What Pattern Does
 
@@ -224,14 +235,40 @@ threshold.
 
 ## Quick Start
 
-### 1. Install
+### 1. Install and connect
 
 ```bash
-npx pattern-mcp
+npx pattern-mcp init
 ```
 
-`npx` runs the `pattern-mcp` command on demand without a separate install
-step, used in the client configs below.
+This is the only command you need to run yourself -- `npx` downloads
+`pattern-mcp` on demand, then `init` detects which clients you have
+installed and offers to connect each one:
+
+- **Claude Code** -- runs `claude mcp add` for you (asks whether to make
+  Pattern available in every project or just this one); skips if already
+  connected (`claude mcp list` already shows it).
+- **Claude Desktop** and **Cursor** -- merges a `pattern` entry into the
+  client's own config file, showing the exact change before writing it
+  and never touching any other server already configured there.
+- **Codex CLI** -- prints the config snippet to add by hand (Codex's
+  config is TOML; this doesn't auto-edit it).
+
+Optionally pastes your `ANTHROPIC_API_KEY` into whichever configs you set
+up (visible in plain text as you type it, and in the files it writes) --
+press Enter to skip and add it yourself later, see
+[step 2](#2-add-your-anthropic-api-key) below. Run non-interactively with
+`--yes` (skips the API key prompt entirely, accepts every detected
+client).
+
+If `init` doesn't detect your client, or you'd rather set it up by
+hand, see [Connect Pattern to your MCP client](#connect-pattern-to-your-mcp-client)
+below for the same configs, per client, done manually. The server
+command either way is `npx pattern-mcp` -- this is what your client's
+config launches; you shouldn't need to run it yourself. If you do run
+it bare in your own terminal (e.g. to double check the install), it
+will just sit there waiting for a client and periodically remind you
+to run `init` -- that's expected, not a hang.
 
 <details>
 <summary>Build from source instead</summary>
@@ -243,14 +280,15 @@ npm install
 npm run build
 ```
 
-Use `node /absolute/path/to/pattern-mcp/dist/index.js` as the server
-command in place of `npx pattern-mcp` in the examples below.
+Use `node /absolute/path/to/pattern-mcp/dist/index.js` in place of
+`npx pattern-mcp` everywhere in this README, including inside `init`'s
+own generated client configs.
 
 </details>
 
 ### 2. Add your Anthropic API key
 
-Pattern requires:
+Skipped it above, or want to change it? Pattern requires:
 
 ```
 ANTHROPIC_API_KEY
@@ -265,40 +303,10 @@ Claude Pro or Max subscription does not include API usage.
 
 ### Connect Pattern to your MCP client
 
-Pattern is a standard MCP server, so it works with MCP-compatible
-clients.
-
-The server command is:
-
-```
-npx pattern-mcp
-```
-
-#### Automatic setup
-
-```bash
-npx pattern-mcp init
-```
-
-Detects which clients are installed and offers to connect each one:
-
-- **Claude Code** -- runs `claude mcp add` for you (asks whether to make
-  Pattern available in every project or just this one); skips if already
-  connected (`claude mcp list` already shows it).
-- **Claude Desktop** and **Cursor** -- merges a `pattern` entry into the
-  client's own config file, showing the exact change before writing it
-  and never touching any other server already configured there.
-- **Codex CLI** -- prints the config snippet to add by hand (Codex's
-  config is TOML; this doesn't auto-edit it).
-
-Optionally pastes your `ANTHROPIC_API_KEY` into whichever configs you set
-up (visible in plain text as you type it, and in the files it writes) --
-press Enter to skip and add it yourself later instead. Run
-non-interactively with `--yes` (skips the API key prompt entirely,
-accepts every detected client).
-
-If you'd rather do it by hand, or `init` didn't detect your client, the
-per-client instructions below cover the same configs manually.
+[Step 1](#1-install-and-connect) above (`npx pattern-mcp init`) does
+this automatically for every client it detects -- the sections below
+are the same configs done by hand, for a client `init` didn't detect,
+or if you'd simply rather edit the config yourself.
 
 #### Claude Code
 

package/dist/client-connect.js

@@ -127,6 +127,28 @@ async function mergeServerConfig(label, path, apiKey, options) {
     writeFileSync(path, JSON.stringify(merged, null, 2) + "\n", "utf8");
     console.log(`Written. Restart ${label} to pick it up.`);
 }
+function clientConfigHasPattern(path) {
+    if (!path)
+        return false;
+    const { config } = readJsonConfig(path);
+    return Boolean(config.mcpServers?.pattern);
+}
+// Best-effort, read-only check across every client Pattern knows how to
+// detect a prior successful setup for -- used to decide whether to keep
+// offering the connect wizard on a later bare run (see
+// offerClientConnectSetupOnce below), instead of asking only once ever
+// regardless of outcome. Codex is deliberately excluded: its config is
+// TOML, which this project never parses or writes (see
+// offerCodexInstructions), so there's no way to confirm a Codex-only
+// setup from here. That means a Codex-only user keeps getting offered
+// the wizard -- a false negative, which is the safe failure mode (asks
+// again when already connected) rather than a false positive (goes quiet
+// when it isn't).
+export function isAnyClientConnected(root) {
+    return (claudeCodeAlreadyConnected() ||
+        clientConfigHasPattern(claudeDesktopConfigPath()) ||
+        clientConfigHasPattern(join(root, ".cursor", "mcp.json")));
+}
 // Claude Desktop isn't shipped on Linux -- there's no config path to
 // even guess at there, so this target is simply not offered on that
 // platform rather than writing a file no client will ever read.
@@ -225,36 +247,53 @@ export async function runConnect(root, options) {
 // Option 1/#1 from the activation-funnel discussion: piggybacks on the
 // same first-run moment as the telemetry and enforcement-boundary
 // notices (see telemetry.ts's printTelemetryNoticeOnce, which states the
-// stdin constraint first). Always prints a one-time, non-blocking
-// mention -- including when a real MCP client has spawned this as a
-// subprocess, where it's genuinely irrelevant but harmless, since the
-// notice is gated on a marker file the same as the others. Only offers
-// the actual interactive "set it up now?" prompt when stdin is a real
-// TTY, i.e. a human ran `npx pattern-mcp` bare in their own shell.
+// stdin constraint first). Always prints the full notice once, ever --
+// including when a real MCP client has spawned this as a subprocess,
+// where it's genuinely irrelevant but harmless, since the notice is
+// gated on a marker file the same as the others.
+//
+// The interactive "set it up now?" prompt is different: it used to be
+// gated on that same one-time marker, so a human who ignored or missed
+// it on the very first bare run never saw it again -- a permanent
+// drop-off with no second chance, found while mapping the new-install
+// journey (see project_pattern_activation_funnel memory). It now keeps
+// reappearing on every bare TTY run -- a human running `npx pattern-mcp`
+// in their own shell, never a real client's spawned subprocess -- for as
+// long as isAnyClientConnected() can't confirm a real connection exists
+// yet. This is the concrete fix for "don't rely on the user to figure
+// out how to connect": Pattern keeps offering, not just once, until it
+// can verify success, or until PATTERN_NO_CONNECT_NOTICE opts out.
 const CONNECT_NOTICE_PATH = process.env.PATTERN_CONNECT_NOTICE_PATH ?? join(homedir(), ".pattern", "connect_notice_shown");
 export async function offerClientConnectSetupOnce(root) {
     if (process.env.PATTERN_NO_CONNECT_NOTICE)
         return;
+    let noticeAlreadyShown = true;
     try {
         readFileSync(CONNECT_NOTICE_PATH, "utf8");
-        return;
     }
     catch {
-        // No marker yet -- fall through and show it.
+        noticeAlreadyShown = false;
     }
-    console.error(["", "Pattern -- one-time setup notice (this will not print again)", connectInstructionsText(), ""].join("\n"));
-    try {
-        mkdirSync(dirname(CONNECT_NOTICE_PATH), { recursive: true });
-        writeFileSync(CONNECT_NOTICE_PATH, new Date().toISOString(), "utf8");
-    }
-    catch {
-        // Couldn't persist the marker -- worst case this prints again next
-        // run. Never blocks startup over it, same as the other notices.
+    if (!noticeAlreadyShown) {
+        console.error(["", "Pattern -- one-time setup notice (this will not print again)", connectInstructionsText(), ""].join("\n"));
+        try {
+            mkdirSync(dirname(CONNECT_NOTICE_PATH), { recursive: true });
+            writeFileSync(CONNECT_NOTICE_PATH, new Date().toISOString(), "utf8");
+        }
+        catch {
+            // Couldn't persist the marker -- worst case this prints again next
+            // run. Never blocks startup over it, same as the other notices.
+        }
     }
     if (!process.stdin.isTTY)
         return;
+    if (isAnyClientConnected(root))
+        return;
     try {
-        const setUpNow = await confirm("Run the connect wizard now?", { yes: false }, true);
+        const question = noticeAlreadyShown
+            ? "No MCP client is connected to Pattern yet -- run the connect wizard now?"
+            : "Run the connect wizard now?";
+        const setUpNow = await confirm(question, { yes: false }, true);
         if (setUpNow) {
             await runConnect(root, { yes: false }); // closes the shared readline itself
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "MCP server that turns your design guidance into a checkable process -- evaluates UI components from external libraries (shadcn/ui, 21st.dev, ReUI) or your own registered design system against a requirements checklist, then tells the agent whether to reuse an existing component or build one from a concrete design reference.",
   "type": "module",
   "main": "dist/index.js",