pattern-mcp 0.13.0 → 0.14.0

package/README.md

@@ -15,12 +15,17 @@ 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.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
 [Connect Pattern to your MCP client](#connect-pattern-to-your-mcp-client)
 for more details.
 
@@ -1859,6 +1864,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,33 @@ 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";
 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 +415,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 +433,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) {
@@ -3895,6 +3938,34 @@ 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);
+});
 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
@@ -3912,6 +3983,7 @@ async function main() {
         process.exit(0);
     }
     captureCliStarted("server");
+    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 +4012,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 +4033,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
@@ -235,6 +244,20 @@ export function captureRecommendation(args) {
 export function captureCliStarted(mode) {
     capture("pattern_cli_started", { mode });
 }
+// 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) {
+    capture("pattern_cli_exited", {
+        exit_reason: reason,
+        error_name: err instanceof Error ? err.name : null,
+    });
+}
 export function captureApiError(args) {
     const { type, status } = classifyApiError(args.message);
     capture("pattern_cli_api_error", {

package/package.json

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