@tpsdev-ai/flair-mcp 0.44.12 → 0.45.0

package/dist/env-guard.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Interpolation-literal env guard (flair#1250).
+ *
+ * An MCP host config template often forwards env like
+ *   "env": { "FLAIR_URL": "${FLAIR_URL}" }
+ * expecting the host to substitute `${FLAIR_URL}` with the real value. When the
+ * variable is unset and the host does NOT substitute (Cursor's plugin `mcp.json`
+ * is exactly this shape — see packages/cursor-flair/mcp.json), flair-mcp is
+ * handed the LITERAL string `"${FLAIR_URL}"`. That literal is truthy, so it wins
+ * every `value ?? default` / `value || default` chain and the sensible default
+ * (flair-client's `http://localhost:19926`) never applies — the connection then
+ * fails in a way that points nowhere near the real cause.
+ *
+ * This module treats such a literal as "unset" so the default applies instead.
+ */
+/**
+ * True iff `value` is an unsubstituted interpolation literal like `${FLAIR_URL}`
+ * — i.e. the whole (trimmed) value is a single `${...}` placeholder the host
+ * never expanded. A value that merely CONTAINS a `${...}` (e.g. a real URL with
+ * a fragment) is left alone: only a wholesale placeholder is treated as unset.
+ */
+export declare function isUnsubstitutedInterpolation(value: string): boolean;
+/**
+ * Read an env var, treating an unsubstituted `${...}` interpolation literal as
+ * unset: returns `undefined` for such a literal (and for a genuinely absent
+ * var) so a downstream default applies instead of the literal being used
+ * verbatim. A real value is returned unchanged (NOT trimmed — only the
+ * placeholder check trims).
+ */
+export declare function readEnvOrUnset(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Connection env vars that flair-client's OWN constructor reads straight from
+ * `process.env` as a fallback (see flair-client/src/client.ts:
+ * `this.url = config.url ?? readEnvOrUnset("FLAIR_URL") ?? DEFAULT_URL`). For
+ * these, skipping the literal only at flair-mcp's call site was NOT enough:
+ * flair-client re-read `process.env` and resurrected the `${...}` literal,
+ * defeating its own default. As of flair#1254 flair-client's env fallbacks
+ * apply this same literal-as-unset guard themselves, so the strip below is
+ * defense-in-depth rather than the only line — kept deliberately (an older
+ * flair-client on a consumer's disk does not have #1254).
+ *
+ * Only FLAIR_URL qualifies today: it is re-read by flair-client AND flair-mcp
+ * still constructs a client when it is a literal. FLAIR_AGENT_ID is also re-read
+ * by flair-client, but flair-mcp's `if (!agentId)` guard (using readEnvOrUnset)
+ * short-circuits before any client is built, so no strip is needed. FLAIR_KEY_PATH
+ * flair-client never reads from env, so guarding it at the call site suffices.
+ */
+export declare const ENV_RESURRECTED_BY_FLAIR_CLIENT: readonly ["FLAIR_URL"];
+/**
+ * Delete any of `names` whose value is an unsubstituted `${...}` interpolation
+ * literal from `env`, so downstream readers — flair-mcp's own reads AND
+ * flair-client's internal `process.env` fallback — see the var as unset and
+ * apply their default. Idempotent; mutates the live process env by default and
+ * accepts an injectable env for tests. Real (substituted) values are untouched.
+ */
+export declare function stripInterpolationLiteralsFromEnv(env?: NodeJS.ProcessEnv, names?: readonly string[]): void;

package/dist/env-guard.js

@@ -0,0 +1,70 @@
+/**
+ * Interpolation-literal env guard (flair#1250).
+ *
+ * An MCP host config template often forwards env like
+ *   "env": { "FLAIR_URL": "${FLAIR_URL}" }
+ * expecting the host to substitute `${FLAIR_URL}` with the real value. When the
+ * variable is unset and the host does NOT substitute (Cursor's plugin `mcp.json`
+ * is exactly this shape — see packages/cursor-flair/mcp.json), flair-mcp is
+ * handed the LITERAL string `"${FLAIR_URL}"`. That literal is truthy, so it wins
+ * every `value ?? default` / `value || default` chain and the sensible default
+ * (flair-client's `http://localhost:19926`) never applies — the connection then
+ * fails in a way that points nowhere near the real cause.
+ *
+ * This module treats such a literal as "unset" so the default applies instead.
+ */
+/**
+ * True iff `value` is an unsubstituted interpolation literal like `${FLAIR_URL}`
+ * — i.e. the whole (trimmed) value is a single `${...}` placeholder the host
+ * never expanded. A value that merely CONTAINS a `${...}` (e.g. a real URL with
+ * a fragment) is left alone: only a wholesale placeholder is treated as unset.
+ */
+export function isUnsubstitutedInterpolation(value) {
+    return /^\$\{.*\}$/.test(value.trim());
+}
+/**
+ * Read an env var, treating an unsubstituted `${...}` interpolation literal as
+ * unset: returns `undefined` for such a literal (and for a genuinely absent
+ * var) so a downstream default applies instead of the literal being used
+ * verbatim. A real value is returned unchanged (NOT trimmed — only the
+ * placeholder check trims).
+ */
+export function readEnvOrUnset(name, env = process.env) {
+    const v = env[name];
+    if (v === undefined)
+        return undefined;
+    return isUnsubstitutedInterpolation(v) ? undefined : v;
+}
+/**
+ * Connection env vars that flair-client's OWN constructor reads straight from
+ * `process.env` as a fallback (see flair-client/src/client.ts:
+ * `this.url = config.url ?? readEnvOrUnset("FLAIR_URL") ?? DEFAULT_URL`). For
+ * these, skipping the literal only at flair-mcp's call site was NOT enough:
+ * flair-client re-read `process.env` and resurrected the `${...}` literal,
+ * defeating its own default. As of flair#1254 flair-client's env fallbacks
+ * apply this same literal-as-unset guard themselves, so the strip below is
+ * defense-in-depth rather than the only line — kept deliberately (an older
+ * flair-client on a consumer's disk does not have #1254).
+ *
+ * Only FLAIR_URL qualifies today: it is re-read by flair-client AND flair-mcp
+ * still constructs a client when it is a literal. FLAIR_AGENT_ID is also re-read
+ * by flair-client, but flair-mcp's `if (!agentId)` guard (using readEnvOrUnset)
+ * short-circuits before any client is built, so no strip is needed. FLAIR_KEY_PATH
+ * flair-client never reads from env, so guarding it at the call site suffices.
+ */
+export const ENV_RESURRECTED_BY_FLAIR_CLIENT = ["FLAIR_URL"];
+/**
+ * Delete any of `names` whose value is an unsubstituted `${...}` interpolation
+ * literal from `env`, so downstream readers — flair-mcp's own reads AND
+ * flair-client's internal `process.env` fallback — see the var as unset and
+ * apply their default. Idempotent; mutates the live process env by default and
+ * accepts an injectable env for tests. Real (substituted) values are untouched.
+ */
+export function stripInterpolationLiteralsFromEnv(env = process.env, names = ENV_RESURRECTED_BY_FLAIR_CLIENT) {
+    for (const name of names) {
+        const v = env[name];
+        if (typeof v === "string" && isUnsubstitutedInterpolation(v)) {
+            delete env[name];
+        }
+    }
+}

package/dist/index.js

@@ -43,6 +43,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { FlairClient, FlairError } from "@tpsdev-ai/flair-client";
 import { z } from "zod";
 import { deriveActivity, postPresenceSafe, resolveHeartbeatIntervalMs, resolvePresenceTimeoutMs, shouldSendHeartbeat, } from "./presence.js";
+import { readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
 // ─── Error helpers ──────────────────────────────────────────────────────────
 function classifyError(err, flairUrl) {
     if (err instanceof FlairError) {
@@ -137,15 +138,21 @@ export async function runMcp() {
         process.exit(0);
     });
     // ─── Client setup ────────────────────────────────────────────────────────────
-    const agentId = process.env.FLAIR_AGENT_ID;
+    // flair#1250: an MCP host that forwards `"FLAIR_URL": "${FLAIR_URL}"` without
+    // substituting hands us the literal `${FLAIR_URL}`. Remove such literals from
+    // the process env first, because flair-client's constructor ALSO reads
+    // process.env.FLAIR_URL as a fallback — guarding only our own reads below
+    // would be silently defeated when flair-client re-reads the raw env.
+    stripInterpolationLiteralsFromEnv();
+    const agentId = readEnvOrUnset("FLAIR_AGENT_ID");
     if (!agentId) {
         console.error("FLAIR_AGENT_ID is required. Set it in your .mcp.json env or shell.");
         process.exit(1);
     }
     const flair = new FlairClient({
         agentId,
-        url: process.env.FLAIR_URL,
-        keyPath: process.env.FLAIR_KEY_PATH,
+        url: readEnvOrUnset("FLAIR_URL"),
+        keyPath: readEnvOrUnset("FLAIR_KEY_PATH"),
         // flair#718 authorship-provenance: forward this stdio proxy's own
         // FLAIR_CLIENT env (set by `flair init`'s per-client wiring, e.g.
         // "claude-code"/"codex"/"gemini"/"cursor") into the client it constructs
@@ -172,8 +179,8 @@ export async function runMcp() {
     // whatever timeout the main client is configured with.
     const presenceFlair = new FlairClient({
         agentId,
-        url: process.env.FLAIR_URL,
-        keyPath: process.env.FLAIR_KEY_PATH,
+        url: readEnvOrUnset("FLAIR_URL"),
+        keyPath: readEnvOrUnset("FLAIR_KEY_PATH"),
         timeoutMs: resolvePresenceTimeoutMs(),
     });
     // Rate-limit clock + last-known task, in-process only (no persistence —

package/dist/session-start-hook.js

@@ -76,6 +76,7 @@
 import { FlairClient } from "@tpsdev-ai/flair-client";
 import { basename } from "node:path";
 import { deriveActivity, postPresenceSafe, resolvePresenceTimeoutMs } from "./presence.js";
+import { readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
 /** Claude Code SessionStart additionalContext hard limit (chars). */
 const MAX_CHARS = 10_000;
 /** Token budget for the bootstrap call — matches the proven prototype. */
@@ -148,7 +149,13 @@ function hookOutput(context) {
  * @param makeClient factory for the bootstrap client (defaults to FlairClient)
  */
 export async function runHook(rawInput, makeClient = defaultClientFactory) {
-    const agentId = process.env.FLAIR_AGENT_ID;
+    // flair#1250: drop any unsubstituted `${...}` interpolation literal from the
+    // env before the client is built, so flair-client's own process.env fallback
+    // (e.g. FLAIR_URL) can't resurrect the literal and defeat its default. See
+    // ./env-guard.ts. Runs here (not just at the call site) because the default
+    // client factory below reads process.env directly.
+    stripInterpolationLiteralsFromEnv();
+    const agentId = readEnvOrUnset("FLAIR_AGENT_ID");
     if (!agentId)
         return NOOP_OUTPUT; // no identity → no-op, never break the session
     let input = {};
@@ -200,8 +207,8 @@ export async function runHook(rawInput, makeClient = defaultClientFactory) {
 function defaultClientFactory(agentId) {
     return new FlairClient({
         agentId,
-        url: process.env.FLAIR_URL,
-        keyPath: process.env.FLAIR_KEY_PATH,
+        url: readEnvOrUnset("FLAIR_URL"),
+        keyPath: readEnvOrUnset("FLAIR_KEY_PATH"),
     });
 }
 /** Entry point. Reads stdin, runs the hook, prints the result, exits 0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.44.12",
+  "version": "0.45.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.44.12",
+    "@tpsdev-ai/flair-client": "0.45.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",