pattern-mcp 0.13.0 → 0.14.1

package/README.md

@@ -15,12 +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.13.0** — `npx pattern-mcp init` now 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
-now tells you it needs a client connected, instead of silently sitting
-there. See
+**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
 [Connect Pattern to your MCP client](#connect-pattern-to-your-mcp-client)
 for more details.
 
@@ -1859,6 +1869,14 @@ are a biased, tiny sample of everyone who installs.
      neither `recommend_component` counts nor `@posthog/mcp`'s handshake
      event below can answer, since both require getting further than a
      bare `npx pattern-mcp` run.
+   - On process exit, as of v0.14.0: a single `pattern_cli_exited` event
+     carrying only a coarse reason (`sigint`, `sigterm`,
+     `uncaught_exception`, `unhandled_rejection`, or
+     `fatal_startup_error`) and, for the two exception cases, the thrown
+     value's constructor name (e.g. `TypeError`) -- never the error
+     message or stack trace. Paired with `pattern_cli_started` so a start
+     with no matching MCP handshake is diagnosable as a crash instead of
+     silent.
 2. Standard MCP tool-call analytics, via
    [`@posthog/mcp`](https://posthog.com/docs/mcp-analytics): which tool
    was called, call duration, and success/failure, so unique installs and

package/dist/index.js

@@ -37,13 +37,80 @@ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statS
 import { homedir } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { captureApiError, captureCliStarted, captureRecommendation, getClient as getPostHogClient, installId, printTelemetryNoticeOnce, shutdownTelemetry, TELEMETRY_ENABLED, } from "./telemetry.js";
+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.
 export const ANTHROPIC_WORKSPACE_ID = process.env.ANTHROPIC_WORKSPACE_ID;
+// Cheap, no-network sanity check on the key's shape, run once at startup.
+// Deliberately NOT a real auth ping against the Anthropic API -- that would
+// spend a real request on every single server boot (every MCP client
+// launch), which is exactly the kind of always-pay-the-API cost this
+// project avoids elsewhere (see the skip-list and ledger-cache-hit designs).
+// This only catches the cheap, common misconfigurations -- unset, empty, or
+// a value that's obviously not an Anthropic key (wrong var pasted, stray
+// quotes) -- surfaced at startup instead of only on the first real tool
+// call's 401. Never blocks startup; recommend_component/extract_requirements
+// still fail with their own clear message if this warning goes unheeded.
+function warnIfAnthropicKeyLooksWrong() {
+    if (!ANTHROPIC_API_KEY) {
+        console.error("Pattern: ANTHROPIC_API_KEY is not set. recommend_component and extract_requirements will fail until it is.");
+        return;
+    }
+    if (!/^sk-ant-/.test(ANTHROPIC_API_KEY)) {
+        console.error("Pattern: ANTHROPIC_API_KEY is set but doesn't look like a real Anthropic key (expected it to start with " +
+            "\"sk-ant-\"). If a tool call fails with a 401, check this value first.");
+    }
+}
 // 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
@@ -395,9 +462,15 @@ function buildMeta(timings, usage) {
 // in a new dependency for what's a small, stable, well-documented event
 // shape (message_start/content_block_start/_delta/_stop/message_delta/
 // message_stop).
-async function streamAnthropicMessage(body) {
-    const requestStartMs = Date.now();
-    const response = await fetch("https://api.anthropic.com/v1/messages", {
+// One retry, not a real backoff loop -- deliberately cost-conscious (see
+// this project's skip-list/ledger-cache-hit reasoning): a 429 that's still
+// rate-limited after respecting the API's own Retry-After is treated as a
+// real failure to surface, not something worth spending a second wait on.
+const RATE_LIMIT_MAX_RETRIES = 1;
+// Fallback only for the rare case the API doesn't send Retry-After at all.
+const RATE_LIMIT_DEFAULT_BACKOFF_MS = 3000;
+function postAnthropicMessages(body) {
+    return fetch("https://api.anthropic.com/v1/messages", {
         method: "POST",
         headers: {
             "content-type": "application/json",
@@ -407,11 +480,28 @@ async function streamAnthropicMessage(body) {
         },
         body: JSON.stringify({ ...body, stream: true }),
     });
+}
+async function streamAnthropicMessage(body) {
+    const requestStartMs = Date.now();
+    let response = await postAnthropicMessages(body);
+    for (let attempt = 0; response.status === 429 && attempt < RATE_LIMIT_MAX_RETRIES; attempt++) {
+        const retryAfterHeader = response.headers.get("retry-after");
+        const retryAfterSeconds = retryAfterHeader ? Number.parseFloat(retryAfterHeader) : NaN;
+        const waitMs = Number.isFinite(retryAfterSeconds)
+            ? Math.max(0, retryAfterSeconds * 1000)
+            : RATE_LIMIT_DEFAULT_BACKOFF_MS;
+        console.error(`Pattern: rate limited by the Anthropic API, retrying in ${(waitMs / 1000).toFixed(1)}s ` +
+            `(${retryAfterHeader ? "per Retry-After" : "default backoff, no Retry-After header"})...`);
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+        response = await postAnthropicMessages(body);
+    }
     if (!response.ok) {
         const errText = await response.text();
         const hint = response.status === 401
             ? " -- check that ANTHROPIC_API_KEY is set to a valid, active key in the environment running this MCP server."
-            : "";
+            : response.status === 429
+                ? " -- still rate limited after retrying once; the caller should wait longer before trying this request again."
+                : "";
         throw new Error(`Anthropic API error ${response.status}: ${errText}${hint}`);
     }
     if (!response.body) {
@@ -3371,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
@@ -3895,13 +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;
+// 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
@@ -3911,7 +4001,8 @@ 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
     // init-enforcement.ts) -- always prints a one-time, non-blocking mention;
@@ -3940,11 +4031,15 @@ async function main() {
     }
     await server.connect(transport);
     // Best-effort telemetry drain on clean shutdown -- no-op when telemetry
-    // was never enabled (see src/telemetry.ts).
+    // was never enabled (see src/telemetry.ts). Also captures which signal
+    // ended the process: a real client's normal disconnect looks the same as
+    // a supervisor repeatedly killing-and-restarting a failing process, and
+    // this is what tells the two apart in the starts-vs-exits comparison.
     for (const signal of ["SIGINT", "SIGTERM"]) {
         process.on(signal, async () => {
             if (idleNudgeTimer)
                 clearTimeout(idleNudgeTimer);
+            captureExitOnce(signal === "SIGINT" ? "sigint" : "sigterm");
             await shutdownTelemetry();
             process.exit(0);
         });
@@ -3957,8 +4052,10 @@ async function main() {
 // entry point, `npx pattern-mcp`) never sets this, so autostart is
 // unaffected.
 if (!process.env.PATTERN_NO_AUTOSTART) {
-    main().catch((err) => {
+    main().catch(async (err) => {
         console.error("Fatal error starting pattern-mcp:", err);
+        captureExitOnce("fatal_startup_error", err);
+        await shutdownTelemetry();
         process.exit(1);
     });
 }

package/dist/telemetry.js

@@ -36,6 +36,15 @@
  * itself are never sent, by either half. See SECURITY.md and README.md for
  * the full disclosure and how to opt out.
  *
+ * Manual/ad-hoc test sessions (a one-off MCP client run by hand while
+ * debugging, not a checked-in script) should set PATTERN_TELEMETRY=0 before
+ * connecting -- there's no way for this file to distinguish that from real
+ * usage on its own, and self-testing was previously showing up as if it
+ * were adoption (see project_pattern_activation_funnel memory: roughly half
+ * of all recorded handshakes turned out to be internal test/smoke-test
+ * clients). Checked-in test scripts (e.g. scripts/test-client.mjs) default
+ * this off already.
+ *
  * Reuses Pattern's existing PostHog project (the same one the marketing
  * site sends browser events to) with its public, write-only project key --
  * safe to embed in a distributed package the same way that key is already
@@ -232,8 +241,31 @@ 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, 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) {
     const { type, status } = classifyApiError(args.message);

package/package.json

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