pattern-mcp 0.14.0 → 0.15.0

package/README.md

@@ -15,17 +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.0** — a crash on startup is now diagnosable
-instead of silent (a new, coarse `pattern_cli_exited` telemetry event),
-Pattern warns at startup if `ANTHROPIC_API_KEY` is missing or clearly
-malformed instead of only surfacing a raw 401 mid-call, and a 429 from
-the Anthropic API now gets one respectful retry (honoring `Retry-After`)
-before it's raised. Previously: 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.
 
@@ -45,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
 
@@ -219,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>
@@ -238,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
@@ -260,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/dist/index.js

@@ -40,6 +40,53 @@ import { fileURLToPath } from "node:url";
 import { captureApiError, captureCliExited, captureCliStarted, captureRecommendation, getClient as getPostHogClient, installId, printTelemetryNoticeOnce, shutdownTelemetry, TELEMETRY_ENABLED, } from "./telemetry.js";
 import { offerEnforcementSetupOnce } from "./init-enforcement.js";
 import { connectInstructionsText, offerClientConnectSetupOnce, runConnect } from "./client-connect.js";
+// Read as early as possible in this file's own module-level code, wrapped
+// so a missing/corrupt package.json can't itself become a new, unguarded
+// crash source -- this is read before the crash handlers below exist to
+// catch anything. Moved up from where it used to live (just above the
+// `server` construction, far later in this file) after a 2026-09-14
+// incident where a caller crashed on every single launch, ~29 times in 4
+// minutes, immediately after a version bump published -- telemetry had no
+// way to say whether the crashing process was the old or new version (see
+// project_pattern_activation_funnel memory). Every pattern_cli_started/
+// pattern_cli_exited event now carries this, closing that gap for next
+// time.
+const PACKAGE_VERSION = (() => {
+    try {
+        return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return "unknown";
+    }
+})();
+// Registered before anything else in this file runs (all the way up here,
+// not down by main() where it used to be) so a throw anywhere in this
+// file's own module-level code -- not just inside main() -- is captured
+// instead of dying silently before these handlers would otherwise have
+// existed. Can't cover a throw during the import statements above this
+// line (nothing can run before those resolve), but this closes the much
+// larger window between "imports finished" and "main() starts," which is
+// most of this file's ~4700 lines of function/constant definitions and
+// tool registrations.
+let exitTelemetryCaptured = false;
+function captureExitOnce(reason, err) {
+    if (exitTelemetryCaptured)
+        return;
+    exitTelemetryCaptured = true;
+    captureCliExited(reason, err, PACKAGE_VERSION);
+}
+process.on("uncaughtException", async (err) => {
+    console.error("Pattern: uncaught exception, exiting.", err);
+    captureExitOnce("uncaught_exception", err);
+    await shutdownTelemetry();
+    process.exit(1);
+});
+process.on("unhandledRejection", async (reason) => {
+    console.error("Pattern: unhandled rejection, exiting.", reason);
+    captureExitOnce("unhandled_rejection", reason);
+    await shutdownTelemetry();
+    process.exit(1);
+});
 export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 // Only required for org-scoped keys (not tied to one workspace); unset for
 // legacy workspace-scoped keys, which don't need it.
@@ -3414,11 +3461,8 @@ export function extractJson(text) {
         return text;
     return text.slice(start, end + 1);
 }
-// Read from package.json rather than hardcoding, so $mcp_server_version in
-// PostHog's MCP tool-call analytics (and any client that reads the MCP
-// initialize response) reflects the version actually installed instead of
-// staying frozen at whatever it was when this line was first written.
-const PACKAGE_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
+// PACKAGE_VERSION is defined near the top of this file now (read as early
+// as possible, before the crash handlers -- see the comment there).
 const server = new Server({ name: "pattern-mcp", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
 // Standard MCP tool-call analytics (tool name, duration, success/failure,
 // unique installs/sessions) via PostHog's own MCP SDK -- separate from
@@ -3938,41 +3982,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 // they're still looking at the terminal, not five minutes after they
 // alt-tabbed away.
 const IDLE_CONNECT_NUDGE_MS = 20_000;
-// Registered once, at module load, so it covers the entire process
-// lifetime -- including a throw during main() itself, before the server
-// ever connects. Without this, a crash-on-start left no telemetry trace at
-// all: captureCliStarted fires, the process dies, and nothing explains why
-// (see project_pattern_activation_funnel memory -- the incident this
-// exists to make diagnosable next time). Both handlers exit(1) after
-// capturing: Node considers the process's state undefined past an uncaught
-// exception, so continuing to run is the wrong default regardless of
-// telemetry.
-let exitTelemetryCaptured = false;
-function captureExitOnce(reason, err) {
-    if (exitTelemetryCaptured)
-        return;
-    exitTelemetryCaptured = true;
-    captureCliExited(reason, err);
-}
-process.on("uncaughtException", async (err) => {
-    console.error("Pattern: uncaught exception, exiting.", err);
-    captureExitOnce("uncaught_exception", err);
-    await shutdownTelemetry();
-    process.exit(1);
-});
-process.on("unhandledRejection", async (reason) => {
-    console.error("Pattern: unhandled rejection, exiting.", reason);
-    captureExitOnce("unhandled_rejection", reason);
-    await shutdownTelemetry();
-    process.exit(1);
-});
+// captureExitOnce and the uncaughtException/unhandledRejection handlers
+// are registered near the top of this file now, before PACKAGE_VERSION's
+// definition -- see the comment there for why.
 async function main() {
     // `npx pattern-mcp init` -- the connect wizard -- exits without ever
     // starting the server. Checked before anything else so it can't be
     // shadowed by a tool name collision later.
     const argv = process.argv.slice(2);
     if (argv[0] === "init") {
-        captureCliStarted("init");
+        captureCliStarted("init", PACKAGE_VERSION);
         await runConnect(PROJECT_ROOT, { yes: argv.includes("--yes") });
         await shutdownTelemetry();
         // Explicit exit, not a bare return -- shutdownTelemetry races a
@@ -3982,7 +4001,7 @@ async function main() {
         // event loop to drain on its own if some other handle is lingering.
         process.exit(0);
     }
-    captureCliStarted("server");
+    captureCliStarted("server", PACKAGE_VERSION);
     warnIfAnthropicKeyLooksWrong();
     printTelemetryNoticeOnce();
     // Piggybacks on this same first-run moment (Option B, see

package/dist/telemetry.js

@@ -241,21 +241,30 @@ export function captureRecommendation(args) {
 // project_pattern_reddit_launch_spike memory for why that gap mattered:
 // a 2026-09-11 download spike showed almost no matching $mcp_initialize
 // growth, and there was no signal at all for the step in between.
-export function captureCliStarted(mode) {
-    capture("pattern_cli_started", { mode });
+// `version` is the running package.json version (see index.ts's
+// PACKAGE_VERSION) -- added 2026-09-14 after an incident where a caller
+// crashed on every launch attempt (~29 times in 4 minutes) in the few
+// minutes right after a version bump published, and telemetry had no way
+// to say whether the crashing process was the old or new version. Without
+// it, "did the fix actually ship before this happened" is unanswerable
+// from telemetry alone.
+export function captureCliStarted(mode, version) {
+    capture("pattern_cli_started", { mode, version });
 }
 // Paired with captureCliStarted so a start with no matching handshake is
 // diagnosable instead of silent -- added after a 2026-09-13 incident where
 // 33 starts in one hour produced exactly 1 successful handshake, and
 // telemetry had no way to say why the other 32 processes ended (see
-// project_pattern_activation_funnel memory). Only a coarse reason and the
-// thrown value's constructor name travel -- never the error message or
-// stack, which could contain a file path, a stray argument value, or other
-// local detail never sent by design (see this file's header).
-export function captureCliExited(reason, err) {
+// project_pattern_activation_funnel memory). Only a coarse reason, the
+// thrown value's constructor name, and the running version travel --
+// never the error message or stack, which could contain a file path, a
+// stray argument value, or other local detail never sent by design (see
+// this file's header).
+export function captureCliExited(reason, err, version) {
     capture("pattern_cli_exited", {
         exit_reason: reason,
         error_name: err instanceof Error ? err.name : null,
+        version,
     });
 }
 export function captureApiError(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.14.0",
+  "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",