pattern-mcp 0.14.1 → 0.16.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.16.0** — a component request that's on the
+skip-list (`button`, `input`, ...) now succeeds with no
+`ANTHROPIC_API_KEY` at all, instead of failing before it ever reached
+that free, local check. When a real call does fail for a missing key,
+the error now names two concrete fixes (re-run `init`, or export the
+key directly) instead of just naming the problem. Codex CLI's connect
+instructions also now carry whatever API key you entered in the
+wizard, as a ready-to-run shell export, instead of silently dropping
+it. Previously: v0.15.0 made `npx pattern-mcp init` the first and only
+command shown for getting started, everywhere (this README and the
+website), and the connect wizard stopped asking just once -- it now
+keeps offering on later bare runs until it can confirm a client is
+actually connected. Before that: 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 it and
+`pattern_cli_started` with the running package version. 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.
@@ -170,10 +192,21 @@ async function setupCursor(root, apiKey, options) {
 // existing config is worse than just telling them what to add. Detected
 // the same way as the other targets (evidence it's actually used), but
 // only ever prints instructions.
-function offerCodexInstructions() {
+//
+// Deliberately does NOT print a per-server `env = {...}` TOML snippet for
+// the API key, unlike the command/args lines above -- checked directly
+// (openai/codex#7521, open as of 2026-09): Codex's own maintainers hadn't
+// settled which env-var syntax their TOML config actually supports at the
+// time this was written. Printing a guessed snippet risked giving
+// confidently wrong instructions, worse than the honest "it depends on
+// your version, here's what works regardless" below. A plain shell
+// export is the one method that works the same way across every Codex
+// version and every other client here, since it never depends on a
+// client-specific config format at all.
+function offerCodexInstructions(apiKey) {
     if (!existsSync(join(homedir(), ".codex")))
         return;
-    console.log([
+    const lines = [
         "\nCodex CLI detected (~/.codex exists). Pattern doesn't auto-write Codex's",
         "TOML config -- add this to ~/.codex/config.toml (or .codex/config.json for",
         "this project only):",
@@ -181,7 +214,15 @@ function offerCodexInstructions() {
         '  [mcp_servers.pattern]',
         '  command = "npx"',
         '  args = ["pattern-mcp"]',
-    ].join("\n"));
+        "",
+    ];
+    if (apiKey) {
+        lines.push("You entered an API key above. Codex's own per-server TOML env syntax isn't", "reliably documented across versions, so the safest way to get it to Codex", "is exporting it in the shell you launch Codex from:", "", `  export ANTHROPIC_API_KEY="${apiKey}"`);
+    }
+    else {
+        lines.push("Codex also needs ANTHROPIC_API_KEY available in its own environment.", "Export it in the shell you launch Codex from:", "", "  export ANTHROPIC_API_KEY=sk-ant-...");
+    }
+    console.log(lines.join("\n"));
 }
 async function promptApiKey(options) {
     if (options.yes)
@@ -211,7 +252,7 @@ export async function runConnect(root, options) {
         }
         if (existsSync(join(homedir(), ".codex"))) {
             anyDetected = true;
-            offerCodexInstructions();
+            offerCodexInstructions(apiKey);
         }
         if (!anyDetected) {
             console.log("\nNo supported MCP client was detected on this machine automatically.\n" + connectInstructionsText());
@@ -225,36 +266,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.
-    }
-    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");
+        noticeAlreadyShown = false;
     }
-    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

@@ -111,6 +111,19 @@ function warnIfAnthropicKeyLooksWrong() {
             "\"sk-ant-\"). If a tool call fails with a 401, check this value first.");
     }
 }
+// Thrown by recommend_component/extract_requirements when they actually
+// need the API and no key is present -- this is what the calling agent
+// sees as the tool's error result, so unlike warnIfAnthropicKeyLooksWrong's
+// stderr line (invisible in most real clients -- see
+// project_pattern_activation_funnel memory), this is the message a real
+// user is actually likely to see. Gives two concrete fixes rather than
+// just naming the problem: re-running `init` (which already offers to
+// write the key into every client it detects), or exporting it directly --
+// the one method that works the same way across every client, since it
+// doesn't depend on any client-specific config format.
+const MISSING_API_KEY_MESSAGE = "Pattern: ANTHROPIC_API_KEY is not set, so this call can't reach the Anthropic API. Fix it one of two ways: " +
+    "re-run `npx pattern-mcp init` to add it to your MCP client's config, or export it directly -- " +
+    "`export ANTHROPIC_API_KEY=sk-ant-...` in the shell your client launches Pattern from, then restart the client.";
 // Configurable so Sonnet vs. Haiku can be A/B tested without a code change.
 // Defaults to Sonnet 5. Try MODEL=claude-haiku-4-5-20251001 to test the
 // cheaper tier -- re-run the 5 validated test cases from the product brief
@@ -1173,14 +1186,15 @@ export function estimateExtractionConfidence(componentNeed) {
     return "high";
 }
 async function runSinglePass(input) {
-    if (!ANTHROPIC_API_KEY) {
-        throw new Error("ANTHROPIC_API_KEY is not set. Export it in the environment running this MCP server.");
-    }
     const passStartMs = Date.now();
     const checklistSource = input.checklist && input.checklist.length > 0 ? "provided" : "extracted";
     // Fast path: skip-list check happens locally too, so trivial primitives
     // never spend a real API call. The system prompt also enforces this, but
-    // checking here avoids the round-trip entirely for the common case.
+    // checking here avoids the round-trip entirely for the common case. The
+    // ANTHROPIC_API_KEY check used to run before this, unconditionally --
+    // meaning a keyless install couldn't get even this free, local path.
+    // Moved below the skip-list return so a missing/invalid key only ever
+    // blocks the cases that actually need the API.
     if (isSkipListMatch(input.component_need)) {
         const skipListElapsedMs = Math.max(1, Date.now() - passStartMs);
         return {
@@ -1213,6 +1227,9 @@ async function runSinglePass(input) {
             },
         };
     }
+    if (!ANTHROPIC_API_KEY) {
+        throw new Error(MISSING_API_KEY_MESSAGE);
+    }
     // Coverage still computes fresh below regardless of what this finds --
     // memory (MEMORY_PATH/record_component_decision) only ever adds context
     // to the user message, it never short-circuits search/scoring or gets
@@ -1526,9 +1543,6 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
 // for the same reason (trivial primitives shouldn't cost an API call here
 // either).
 async function runExtraction(input) {
-    if (!ANTHROPIC_API_KEY) {
-        throw new Error("ANTHROPIC_API_KEY is not set. Export it in the environment running this MCP server.");
-    }
     const startMs = Date.now();
     if (isSkipListMatch(input.component_need)) {
         const elapsedMs = Math.max(1, Date.now() - startMs);
@@ -1546,6 +1560,9 @@ async function runExtraction(input) {
             },
         };
     }
+    if (!ANTHROPIC_API_KEY) {
+        throw new Error(MISSING_API_KEY_MESSAGE);
+    }
     const userMessage = `component_need: ${input.component_need}\ndomain: ${input.domain}`;
     const data = await streamAnthropicMessage({
         model: MODEL,

package/package.json

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