@tpsdev-ai/flair-mcp 0.15.0 → 0.16.0

package/README.md

@@ -13,7 +13,7 @@ cat > .mcp.json << 'EOF'
   "mcpServers": {
     "flair": {
       "command": "npx",
-      "args": ["@tpsdev-ai/flair-mcp"],
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
       "env": {
         "FLAIR_AGENT_ID": "my-project"
       }
@@ -23,16 +23,15 @@ cat > .mcp.json << 'EOF'
 EOF
 ```
 
-Or install globally and configure once in `~/.claude/settings.json`.
+`npx -y @tpsdev-ai/flair-mcp` fetches and runs the server on demand — no global install needed. (`flair init` wires this for you automatically; see below.)
 
 ### Prerequisites
 
-You need a running Flair instance:
+You need a running Flair instance. The one-command front door:
 
 ```bash
 npm install -g @tpsdev-ai/flair
-flair init
-flair agent add my-project
+flair init --agent my-project   # installs Harper, creates the agent, wires MCP clients
 ```
 
 ## Tools
@@ -76,7 +75,7 @@ Point to a remote Flair instance:
   "mcpServers": {
     "flair": {
       "command": "npx",
-      "args": ["@tpsdev-ai/flair-mcp"],
+      "args": ["-y", "@tpsdev-ai/flair-mcp"],
       "env": {
         "FLAIR_AGENT_ID": "my-project",
         "FLAIR_URL": "http://your-server:19926"

package/dist/index.d.ts

@@ -14,9 +14,19 @@
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
  *
  * Usage:
- *   npx @tpsdev-ai/flair-mcp
+ *   npx -y @tpsdev-ai/flair-mcp
  *
  * Claude Code .mcp.json:
- *   { "mcpServers": { "flair": { "command": "npx", "args": ["@tpsdev-ai/flair-mcp"] } } }
+ *   { "mcpServers": { "flair": { "command": "npx", "args": ["-y", "@tpsdev-ai/flair-mcp"] } } }
+ *
+ * BIN ENTRY / NODE-VERSION PREFLIGHT
+ * ----------------------------------
+ * The published `flair-mcp` bin is NOT this file — it is the CommonJS preflight
+ * shim (dist/mcp-shim.cjs, compiled from src/mcp-shim.cts). This module is an
+ * ES module: its top-level imports are hoisted and the whole graph is linked +
+ * evaluated before any in-file guard could run, so on an old Node it crashes
+ * during linking (the SDK + flair deps need Node >= 22) before printing anything
+ * — the silent `npx -y @tpsdev-ai/flair-mcp` failure. The shim checks the Node
+ * version FIRST, then dynamically imports this module and calls runMcp().
  */
-export {};
+export declare function runMcp(): Promise<void>;

package/dist/index.js

@@ -14,10 +14,20 @@
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
  *
  * Usage:
- *   npx @tpsdev-ai/flair-mcp
+ *   npx -y @tpsdev-ai/flair-mcp
  *
  * Claude Code .mcp.json:
- *   { "mcpServers": { "flair": { "command": "npx", "args": ["@tpsdev-ai/flair-mcp"] } } }
+ *   { "mcpServers": { "flair": { "command": "npx", "args": ["-y", "@tpsdev-ai/flair-mcp"] } } }
+ *
+ * BIN ENTRY / NODE-VERSION PREFLIGHT
+ * ----------------------------------
+ * The published `flair-mcp` bin is NOT this file — it is the CommonJS preflight
+ * shim (dist/mcp-shim.cjs, compiled from src/mcp-shim.cts). This module is an
+ * ES module: its top-level imports are hoisted and the whole graph is linked +
+ * evaluated before any in-file guard could run, so on an old Node it crashes
+ * during linking (the SDK + flair deps need Node >= 22) before printing anything
+ * — the silent `npx -y @tpsdev-ai/flair-mcp` failure. The shim checks the Node
+ * version FIRST, then dynamically imports this module and calls runMcp().
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -64,277 +74,307 @@ function classifyError(err, flairUrl) {
 function errorResult(err, flairUrl) {
     return { content: [{ type: "text", text: classifyError(err, flairUrl) }], isError: true };
 }
-// ─── Parent-exit watcher ────────────────────────────────────────────────────
-//
-// flair-mcp runs as a child of an MCP host (Claude Code, Cursor, etc) over
-// stdio. When the host exits cleanly it should close stdin/stdout — but in
-// practice we've seen flair-mcp processes orphaned for weeks (PID 1 as
-// parent), holding stale tokens and consuming RAM.
+// ─── Entry point ──────────────────────────────────────────────────────────────
 //
-// Poll process.ppid every 5s. If it drops to 1 (init), the parent died and
-// we got reparented — exit cleanly. Cheap, cross-platform, no native deps.
-// Clamp the poll interval to a safe range. `process.env.FOO ?? 5000` is NOT
-// safe on its own: `??` only falls through on null/undefined, so an empty-string
-// override (`FLAIR_MCP_PARENT_POLL_MS=`) yields `Number("") === 0` and creates
-// a tight CPU-busy loop. Validate explicitly. (Sherlock review on #315.)
-const PARENT_POLL_INTERVAL_MS = (() => {
-    const raw = process.env.FLAIR_MCP_PARENT_POLL_MS;
-    const parsed = raw != null ? Number(raw) : NaN;
-    const FLOOR_MS = 100;
-    const CEILING_MS = 30_000;
-    return Number.isFinite(parsed) && parsed >= FLOOR_MS && parsed <= CEILING_MS
-        ? parsed
-        : 5000;
-})();
-const initialPpid = process.ppid;
-setInterval(() => {
-    // ppid === 1 means init/launchd has adopted us — original parent died.
-    if (process.ppid === 1 && initialPpid !== 1) {
-        console.error("flair-mcp: parent process died (re-parented to init); exiting cleanly.");
+// runMcp() is the real entry point. It is exported so the CommonJS preflight
+// shim (mcp-shim.cts → dist/mcp-shim.cjs, the published bin) can invoke it after
+// its Node-version check passes — the shim imports this module, so a top-level
+// `import.meta.main` guard would be false there. Everything that has runtime
+// side effects (the FLAIR_AGENT_ID check, FlairClient construction, the parent-
+// exit watcher, tool registration, and the stdio connect) lives inside runMcp()
+// so that merely importing this module (e.g. from the shim before the version
+// check, or from a test) does nothing until runMcp() is called.
+export async function runMcp() {
+    // ─── Parent-exit watcher ──────────────────────────────────────────────────
+    //
+    // flair-mcp runs as a child of an MCP host (Claude Code, Cursor, etc) over
+    // stdio. When the host exits cleanly it should close stdin/stdout — but in
+    // practice we've seen flair-mcp processes orphaned for weeks (PID 1 as
+    // parent), holding stale tokens and consuming RAM.
+    //
+    // Poll process.ppid every 5s. If it drops to 1 (init), the parent died and
+    // we got reparented — exit cleanly. Cheap, cross-platform, no native deps.
+    // Clamp the poll interval to a safe range. `process.env.FOO ?? 5000` is NOT
+    // safe on its own: `??` only falls through on null/undefined, so an empty-string
+    // override (`FLAIR_MCP_PARENT_POLL_MS=`) yields `Number("") === 0` and creates
+    // a tight CPU-busy loop. Validate explicitly. (Sherlock review on #315.)
+    const PARENT_POLL_INTERVAL_MS = (() => {
+        const raw = process.env.FLAIR_MCP_PARENT_POLL_MS;
+        const parsed = raw != null ? Number(raw) : NaN;
+        const FLOOR_MS = 100;
+        const CEILING_MS = 30_000;
+        return Number.isFinite(parsed) && parsed >= FLOOR_MS && parsed <= CEILING_MS
+            ? parsed
+            : 5000;
+    })();
+    const initialPpid = process.ppid;
+    setInterval(() => {
+        // ppid === 1 means init/launchd has adopted us — original parent died.
+        if (process.ppid === 1 && initialPpid !== 1) {
+            console.error("flair-mcp: parent process died (re-parented to init); exiting cleanly.");
+            process.exit(0);
+        }
+    }, PARENT_POLL_INTERVAL_MS).unref();
+    // Also handle stdin EOF — MCP host closing the pipe means session ended.
+    // (StdioServerTransport handles this internally for the MCP protocol, but
+    // belt-and-suspenders: if stdin closes we exit, full stop.)
+    process.stdin.on("close", () => {
+        console.error("flair-mcp: stdin closed; exiting cleanly.");
         process.exit(0);
+    });
+    process.stdin.on("end", () => {
+        console.error("flair-mcp: stdin EOF; exiting cleanly.");
+        process.exit(0);
+    });
+    // ─── Client setup ────────────────────────────────────────────────────────────
+    const agentId = process.env.FLAIR_AGENT_ID;
+    if (!agentId) {
+        console.error("FLAIR_AGENT_ID is required. Set it in your .mcp.json env or shell.");
+        process.exit(1);
     }
-}, PARENT_POLL_INTERVAL_MS).unref();
-// Also handle stdin EOF — MCP host closing the pipe means session ended.
-// (StdioServerTransport handles this internally for the MCP protocol, but
-// belt-and-suspenders: if stdin closes we exit, full stop.)
-process.stdin.on("close", () => {
-    console.error("flair-mcp: stdin closed; exiting cleanly.");
-    process.exit(0);
-});
-process.stdin.on("end", () => {
-    console.error("flair-mcp: stdin EOF; exiting cleanly.");
-    process.exit(0);
-});
-// ─── Client setup ────────────────────────────────────────────────────────────
-const agentId = process.env.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,
-});
-// ─── MCP Server ──────────────────────────────────────────────────────────────
-const server = new McpServer({
-    name: "flair",
-    version: "0.1.0",
-});
-// ─── Tools ───────────────────────────────────────────────────────────────────
-server.tool("memory_search", "Search memories by meaning. Understands temporal queries like 'what happened today'.", {
-    query: z.string().describe("Search query — natural language, semantic matching"),
-    limit: z.coerce.number().optional().default(5).describe("Max results (default 5)"),
-}, async ({ query, limit }) => {
-    try {
-        const results = await flair.memory.search(query, { limit });
-        if (results.length === 0) {
-            return { content: [{ type: "text", text: "No relevant memories found." }] };
+    const flair = new FlairClient({
+        agentId,
+        url: process.env.FLAIR_URL,
+        keyPath: process.env.FLAIR_KEY_PATH,
+    });
+    // ─── MCP Server ──────────────────────────────────────────────────────────────
+    const server = new McpServer({
+        name: "flair",
+        version: "0.1.0",
+    });
+    // ─── Tools ───────────────────────────────────────────────────────────────────
+    server.tool("memory_search", "Search memories by meaning. Understands temporal queries like 'what happened today'.", {
+        query: z.string().describe("Search query — natural language, semantic matching"),
+        limit: z.coerce.number().optional().default(5).describe("Max results (default 5)"),
+    }, async ({ query, limit }) => {
+        try {
+            const results = await flair.memory.search(query, { limit });
+            if (results.length === 0) {
+                return { content: [{ type: "text", text: "No relevant memories found." }] };
+            }
+            const text = results
+                .map((r, i) => {
+                const date = r.createdAt ? r.createdAt.slice(0, 10) : "";
+                const idStr = r.id ? `id:${r.id}` : "";
+                const meta = [date, r.type, idStr].filter(Boolean).join(", ");
+                return `${i + 1}. ${r.content}${meta ? ` (${meta})` : ""}`;
+            })
+                .join("\n");
+            return { content: [{ type: "text", text }] };
         }
-        const text = results
-            .map((r, i) => {
-            const date = r.createdAt ? r.createdAt.slice(0, 10) : "";
-            const idStr = r.id ? `id:${r.id}` : "";
-            const meta = [date, r.type, idStr].filter(Boolean).join(", ");
-            return `${i + 1}. ${r.content}${meta ? ` (${meta})` : ""}`;
-        })
-            .join("\n");
-        return { content: [{ type: "text", text }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-server.tool("memory_store", "Save information to persistent memory. Use for lessons, decisions, preferences, facts.", {
-    content: z.string().describe("What to remember"),
-    type: z.enum(["session", "lesson", "decision", "preference", "fact", "goal"]).optional().default("session"),
-    durability: z.enum(["permanent", "persistent", "standard", "ephemeral"]).optional().default("standard")
-        .describe("permanent — inviolable facts, identity, explicit never-forget (e.g., 'my name is Nathan')\n" +
-        "persistent — key decisions and lessons to recall weeks later (e.g., 'PR review process')\n" +
-        "standard — default working memory, recent context (e.g., 'discussed auth flow today')\n" +
-        "ephemeral — scratch state, auto-expires 72h (e.g., 'currently debugging issue #42')"),
-    tags: z.array(z.string()).optional().describe("Array of tag strings"),
-}, async ({ content, type, durability, tags }) => {
-    try {
-        const result = await flair.memory.write(content, {
-            type: type,
-            durability: durability,
-            tags,
-            dedup: true,
-            dedupThreshold: 0.95,
-        });
-        // Dedup path: existing memory matched, NEW content was NOT written.
-        // Emit both prose AND structuredContent so callers can react
-        // programmatically even when LLMs compress prose imprecisely
-        // (see flair#449 — work agent missed dedup signal and lost data).
-        if (result.deduped) {
-            const sc = {
-                deduplicated: true,
-                mergedWith: result.id,
-                existingContent: result.content,
-                written: false,
-            };
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    server.tool("memory_store", "Save information to persistent memory. Use for lessons, decisions, preferences, facts.", {
+        content: z.string().describe("What to remember"),
+        type: z.enum(["session", "lesson", "decision", "preference", "fact", "goal"]).optional().default("session"),
+        durability: z.enum(["permanent", "persistent", "standard", "ephemeral"]).optional().default("standard")
+            .describe("permanent — inviolable facts, identity, explicit never-forget (e.g., 'my name is Nathan')\n" +
+            "persistent — key decisions and lessons to recall weeks later (e.g., 'PR review process')\n" +
+            "standard — default working memory, recent context (e.g., 'discussed auth flow today')\n" +
+            "ephemeral — scratch state, auto-expires 72h (e.g., 'currently debugging issue #42')"),
+        tags: z.array(z.string()).optional().describe("Array of tag strings"),
+    }, async ({ content, type, durability, tags }) => {
+        try {
+            const result = await flair.memory.write(content, {
+                type: type,
+                durability: durability,
+                tags,
+                dedup: true,
+                dedupThreshold: 0.95,
+            });
+            // Dedup path: existing memory matched, NEW content was NOT written.
+            // Emit both prose AND structuredContent so callers can react
+            // programmatically even when LLMs compress prose imprecisely
+            // (see flair#449 — work agent missed dedup signal and lost data).
+            if (result.deduped) {
+                const sc = {
+                    deduplicated: true,
+                    mergedWith: result.id,
+                    existingContent: result.content,
+                    written: false,
+                };
+                return {
+                    content: [{
+                            type: "text",
+                            text: `⚠️ DEDUPLICATED — new content was NOT written. ` +
+                                `Matched existing memory id=${result.id}: ${result.content?.slice(0, 200)}\n\n` +
+                                `If the new content is genuinely distinct, retry with different phrasing ` +
+                                `or call memory_store with the same id to update.`,
+                        }],
+                    structuredContent: sc,
+                };
+            }
+            const preview = content.length > 120 ? content.slice(0, 120) + "..." : content;
+            const tagStr = tags && tags.length > 0 ? tags.join(", ") : "none";
+            const text = [
+                `Memory stored (id: ${result.id})`,
+                `Preview: ${preview}`,
+                `Size: ${content.length} chars`,
+                `Tags: ${tagStr}`,
+                `Type: ${type}, Durability: ${durability}`,
+            ].join("\n");
             return {
-                content: [{
-                        type: "text",
-                        text: `⚠️ DEDUPLICATED — new content was NOT written. ` +
-                            `Matched existing memory id=${result.id}: ${result.content?.slice(0, 200)}\n\n` +
-                            `If the new content is genuinely distinct, retry with different phrasing ` +
-                            `or call memory_store with the same id to update.`,
-                    }],
-                structuredContent: sc,
+                content: [{ type: "text", text }],
+                structuredContent: { deduplicated: false, id: result.id, written: true },
             };
         }
-        const preview = content.length > 120 ? content.slice(0, 120) + "..." : content;
-        const tagStr = tags && tags.length > 0 ? tags.join(", ") : "none";
-        const text = [
-            `Memory stored (id: ${result.id})`,
-            `Preview: ${preview}`,
-            `Size: ${content.length} chars`,
-            `Tags: ${tagStr}`,
-            `Type: ${type}, Durability: ${durability}`,
-        ].join("\n");
-        return {
-            content: [{ type: "text", text }],
-            structuredContent: { deduplicated: false, id: result.id, written: true },
-        };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-server.tool("memory_get", "Retrieve a specific memory by ID.", {
-    id: z.string().describe("Memory ID"),
-}, async ({ id }) => {
-    try {
-        const mem = await flair.memory.get(id);
-        if (!mem)
-            return { content: [{ type: "text", text: `Memory ${id} not found.` }] };
-        return { content: [{ type: "text", text: `${mem.content}\n\n(type: ${mem.type}, durability: ${mem.durability}, created: ${mem.createdAt})` }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-server.tool("memory_delete", "Delete a memory by ID.", {
-    id: z.string().describe("Memory ID to delete"),
-}, async ({ id }) => {
-    try {
-        await flair.memory.delete(id);
-        return { content: [{ type: "text", text: `Memory ${id} deleted.` }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-server.tool("bootstrap", "Get session context: soul + memories + predicted context. Run at session start. Pass subjects for predictive loading.", {
-    maxTokens: z.coerce.number().optional().default(4000).describe("Max tokens in output"),
-    currentTask: z.string().optional().describe("Current task description — enables semantic search for relevant memories"),
-    channel: z.string().optional().describe("Channel name (discord, tps-mail, claude-code) — shapes context prediction"),
-    surface: z.string().optional().describe("Surface name (tps-build, tps-review, cli-session) — narrows prediction"),
-    subjects: z.array(z.string()).optional().describe("Entity names to preload context for (e.g., ['flair', 'auth'])"),
-}, async ({ maxTokens, currentTask, channel, surface, subjects }) => {
-    try {
-        const result = await flair.bootstrap({ maxTokens, currentTask, channel, surface, subjects });
-        if (!result.context) {
-            return { content: [{ type: "text", text: "No context available." }] };
+        catch (err) {
+            return errorResult(err, flair.url);
         }
-        return { content: [{ type: "text", text: result.context }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-server.tool("soul_set", "Set a personality or project context entry. Included in every bootstrap.", {
-    key: z.string().describe("Entry key (e.g., 'role', 'standards', 'project')"),
-    value: z.string().describe("Entry value — personality trait, project context, coding standards, etc."),
-}, async ({ key, value }) => {
-    try {
-        await flair.soul.set(key, value);
-        return { content: [{ type: "text", text: `Soul entry '${key}' set.` }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-server.tool("soul_get", "Get a personality or project context entry.", {
-    key: z.string().describe("Entry key"),
-}, async ({ key }) => {
-    try {
-        const entry = await flair.soul.get(key);
-        if (!entry)
-            return { content: [{ type: "text", text: `No soul entry for '${key}'.` }] };
-        return { content: [{ type: "text", text: entry.value }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-// ─── Coordination write surface ──────────────────────────────────────────────
+    });
+    server.tool("memory_get", "Retrieve a specific memory by ID.", {
+        id: z.string().describe("Memory ID"),
+    }, async ({ id }) => {
+        try {
+            const mem = await flair.memory.get(id);
+            if (!mem)
+                return { content: [{ type: "text", text: `Memory ${id} not found.` }] };
+            return { content: [{ type: "text", text: `${mem.content}\n\n(type: ${mem.type}, durability: ${mem.durability}, created: ${mem.createdAt})` }] };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    server.tool("memory_delete", "Delete a memory by ID.", {
+        id: z.string().describe("Memory ID to delete"),
+    }, async ({ id }) => {
+        try {
+            await flair.memory.delete(id);
+            return { content: [{ type: "text", text: `Memory ${id} deleted.` }] };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    server.tool("bootstrap", "Get session context: soul + memories + predicted context. Run at session start. Pass subjects for predictive loading.", {
+        maxTokens: z.coerce.number().optional().default(4000).describe("Max tokens in output"),
+        currentTask: z.string().optional().describe("Current task description — enables semantic search for relevant memories"),
+        channel: z.string().optional().describe("Channel name (discord, tps-mail, claude-code) — shapes context prediction"),
+        surface: z.string().optional().describe("Surface name (tps-build, tps-review, cli-session) — narrows prediction"),
+        subjects: z.array(z.string()).optional().describe("Entity names to preload context for (e.g., ['flair', 'auth'])"),
+    }, async ({ maxTokens, currentTask, channel, surface, subjects }) => {
+        try {
+            const result = await flair.bootstrap({ maxTokens, currentTask, channel, surface, subjects });
+            if (!result.context) {
+                return { content: [{ type: "text", text: "No context available." }] };
+            }
+            return { content: [{ type: "text", text: result.context }] };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    server.tool("soul_set", "Set a personality or project context entry. Included in every bootstrap.", {
+        key: z.string().describe("Entry key (e.g., 'role', 'standards', 'project')"),
+        value: z.string().describe("Entry value — personality trait, project context, coding standards, etc."),
+    }, async ({ key, value }) => {
+        try {
+            await flair.soul.set(key, value);
+            return { content: [{ type: "text", text: `Soul entry '${key}' set.` }] };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    server.tool("soul_get", "Get a personality or project context entry.", {
+        key: z.string().describe("Entry key"),
+    }, async ({ key }) => {
+        try {
+            const entry = await flair.soul.get(key);
+            if (!entry)
+                return { content: [{ type: "text", text: `No soul entry for '${key}'.` }] };
+            return { content: [{ type: "text", text: entry.value }] };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    // ─── Coordination write surface ──────────────────────────────────────────────
+    //
+    // flair_workspace_set + flair_orgevent let an agent write the Office Space
+    // coordination layer without hand-rolling signed HTTP. Both go through
+    // flair.request(), which signs with the agent's Ed25519 key — so identity
+    // (WorkspaceState.agentId / OrgEvent.authorId) is taken from the SIGNATURE on
+    // the server side, NEVER the body. We deliberately do NOT send agentId/authorId
+    // in the body; the handlers attribute the write to the authenticated agent, so
+    // an agent can only write AS itself (no forging).
+    server.tool("flair_workspace_set", "Set your agent's current workspace state in the Office Space coordination layer (ref/branch, phase, task). Attributed to you from your signed identity — you can only write your own state.", {
+        ref: z.string().describe("Workspace ref — branch, worktree, or task ref"),
+        label: z.string().optional().describe("Human-readable label for this workspace"),
+        provider: z.string().optional().default("mcp").describe("Provider/runtime (e.g. claude-code, openclaw)"),
+        task: z.string().optional().describe("Task/issue id this workspace is attached to"),
+        phase: z.string().optional().describe("Current phase (e.g. design, implement, review)"),
+        summary: z.string().optional().describe("Short summary of current workspace state"),
+    }, async ({ ref, label, provider, task, phase, summary }) => {
+        try {
+            // No agentId in body — the server attributes from the signed identity.
+            const body = {
+                id: `${agentId}:${ref}`,
+                ref,
+                provider: provider ?? "mcp",
+                timestamp: new Date().toISOString(),
+            };
+            if (label)
+                body.label = label;
+            if (task)
+                body.taskId = task;
+            if (phase)
+                body.phase = phase;
+            if (summary)
+                body.summary = summary;
+            await flair.request("POST", "/WorkspaceState", body);
+            return { content: [{ type: "text", text: `Workspace state set: ref=${ref}${phase ? `, phase=${phase}` : ""} (attributed to ${agentId}).` }] };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    server.tool("flair_orgevent", "Publish an org-wide coordination event (claim/release/status) to the Office Space. Attributed to you from your signed identity — you cannot publish as another agent.", {
+        kind: z.string().describe("Event kind (e.g. coord.claim, coord.release, status)"),
+        summary: z.string().describe("Short summary of the event"),
+        detail: z.string().optional().describe("Longer detail payload"),
+        scope: z.string().optional().describe("Scope of the event (e.g. an agent id, repo, or 'org')"),
+        targets: z.array(z.string()).optional().describe("Recipient agent ids"),
+    }, async ({ kind, summary, detail, scope, targets }) => {
+        try {
+            // No authorId in body — the server attributes from the signed identity.
+            const body = { kind, summary };
+            if (detail)
+                body.detail = detail;
+            if (scope)
+                body.scope = scope;
+            if (targets && targets.length > 0)
+                body.targetIds = targets;
+            const result = await flair.request("POST", "/OrgEvent", body);
+            const targetStr = targets && targets.length > 0 ? ` → ${targets.join(", ")}` : "";
+            const idStr = result?.id ? ` (id: ${result.id})` : "";
+            return { content: [{ type: "text", text: `OrgEvent published: kind=${kind}${targetStr} (attributed to ${agentId})${idStr}.` }] };
+        }
+        catch (err) {
+            return errorResult(err, flair.url);
+        }
+    });
+    // ─── Start ───────────────────────────────────────────────────────────────────
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+// ─── Entry point dispatch ──────────────────────────────────────────────────────
 //
-// flair_workspace_set + flair_orgevent let an agent write the Office Space
-// coordination layer without hand-rolling signed HTTP. Both go through
-// flair.request(), which signs with the agent's Ed25519 key — so identity
-// (WorkspaceState.agentId / OrgEvent.authorId) is taken from the SIGNATURE on
-// the server side, NEVER the body. We deliberately do NOT send agentId/authorId
-// in the body; the handlers attribute the write to the authenticated agent, so
-// an agent can only write AS itself (no forging).
-server.tool("flair_workspace_set", "Set your agent's current workspace state in the Office Space coordination layer (ref/branch, phase, task). Attributed to you from your signed identity — you can only write your own state.", {
-    ref: z.string().describe("Workspace ref — branch, worktree, or task ref"),
-    label: z.string().optional().describe("Human-readable label for this workspace"),
-    provider: z.string().optional().default("mcp").describe("Provider/runtime (e.g. claude-code, openclaw)"),
-    task: z.string().optional().describe("Task/issue id this workspace is attached to"),
-    phase: z.string().optional().describe("Current phase (e.g. design, implement, review)"),
-    summary: z.string().optional().describe("Short summary of current workspace state"),
-}, async ({ ref, label, provider, task, phase, summary }) => {
-    try {
-        // No agentId in body — the server attributes from the signed identity.
-        const body = {
-            id: `${agentId}:${ref}`,
-            ref,
-            provider: provider ?? "mcp",
-            timestamp: new Date().toISOString(),
-        };
-        if (label)
-            body.label = label;
-        if (task)
-            body.taskId = task;
-        if (phase)
-            body.phase = phase;
-        if (summary)
-            body.summary = summary;
-        await flair.request("POST", "/WorkspaceState", body);
-        return { content: [{ type: "text", text: `Workspace state set: ref=${ref}${phase ? `, phase=${phase}` : ""} (attributed to ${agentId}).` }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-server.tool("flair_orgevent", "Publish an org-wide coordination event (claim/release/status) to the Office Space. Attributed to you from your signed identity — you cannot publish as another agent.", {
-    kind: z.string().describe("Event kind (e.g. coord.claim, coord.release, status)"),
-    summary: z.string().describe("Short summary of the event"),
-    detail: z.string().optional().describe("Longer detail payload"),
-    scope: z.string().optional().describe("Scope of the event (e.g. an agent id, repo, or 'org')"),
-    targets: z.array(z.string()).optional().describe("Recipient agent ids"),
-}, async ({ kind, summary, detail, scope, targets }) => {
-    try {
-        // No authorId in body — the server attributes from the signed identity.
-        const body = { kind, summary };
-        if (detail)
-            body.detail = detail;
-        if (scope)
-            body.scope = scope;
-        if (targets && targets.length > 0)
-            body.targetIds = targets;
-        const result = await flair.request("POST", "/OrgEvent", body);
-        const targetStr = targets && targets.length > 0 ? ` → ${targets.join(", ")}` : "";
-        const idStr = result?.id ? ` (id: ${result.id})` : "";
-        return { content: [{ type: "text", text: `OrgEvent published: kind=${kind}${targetStr} (attributed to ${agentId})${idStr}.` }] };
-    }
-    catch (err) {
-        return errorResult(err, flair.url);
-    }
-});
-// ─── Start ───────────────────────────────────────────────────────────────────
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// Run directly when this module is the entry point — covers `bun src/index.ts`
+// and `node dist/index.js`. The packaged bin goes through mcp-shim.cjs → runMcp()
+// after its Node-version check, so import.meta.main is false there; without this
+// the server would never start when invoked through the shim. (Matches the
+// session-start-hook + CLI shim entry-point pattern.)
+const importMeta = import.meta;
+const isMain = importMeta.main === true ||
+    (typeof process !== "undefined" &&
+        process.argv[1] != null &&
+        import.meta.url === `file://${process.argv[1]}`);
+if (isMain) {
+    void runMcp().catch((err) => {
+        console.error(err && err.stack ? err.stack : err);
+        process.exit(1);
+    });
+}

package/dist/mcp-shim.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * mcp-shim.cts — Node-version PREFLIGHT for the Flair MCP server.
+ *
+ * THIS IS THE BIN ENTRY (`package.json` "bin": { "flair-mcp": "dist/mcp-shim.cjs" }).
+ *
+ * Why a separate CommonJS file instead of a guard inside index.ts:
+ *   The real MCP server (dist/index.js) is an ES module. In ESM, every top-level
+ *   `import` is HOISTED and the whole module graph is LINKED + EVALUATED before
+ *   the first statement in the file body runs. flair-mcp's deps (@modelcontext-
+ *   protocol/sdk, @tpsdev-ai/flair-client and its transitive deps) require a
+ *   modern engine, so on an older Node the import graph fails to load — and a
+ *   Node-version check placed even at the very top of index.ts never executes:
+ *   the import graph crashes first. That is exactly the silent-failure bug — a
+ *   user wiring `npx -y @tpsdev-ai/flair-mcp` on an old Node gets zero output and
+ *   a dead MCP server, with no actionable signal (the same exposure flair's CLI
+ *   had before #524).
+ *
+ *   CommonJS evaluates top-to-bottom and `require()`/`import()` are evaluated
+ *   lazily — so the version check below runs and prints BEFORE anything tries to
+ *   load the ESM server or any modern dependency. Because every Node since v0.x
+ *   parses and runs CommonJS, this shim is guaranteed to run and print on the
+ *   oldest Node a user could plausibly have.
+ *
+ *   The check itself deliberately uses ONLY ancient-safe syntax — `var`, plain
+ *   functions, string `.split`/`parseInt`, `console.error`, `process.exit`. No
+ *   top-level await, no optional chaining, no template literals reaching
+ *   modern-only APIs — so the guard can never become the thing that fails to
+ *   parse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// ── Node-version preflight (must stay parse-safe + runtime-safe on old Node) ──
+var MIN_NODE_MAJOR = 22;
+function flairMcpCurrentNodeMajor() {
+    // process.versions.node is e.g. "18.20.4"; take the leading integer.
+    var raw = (process && process.versions && process.versions.node) || "0";
+    return parseInt(String(raw).split(".")[0], 10) || 0;
+}
+var flairMcpNodeMajor = flairMcpCurrentNodeMajor();
+if (flairMcpNodeMajor < MIN_NODE_MAJOR) {
+    // Plain string concatenation — no template literals, no chalk, nothing that
+    // could itself trip on an old engine.
+    console.error("");
+    console.error("  flair-mcp requires Node.js >= " + MIN_NODE_MAJOR + ".");
+    console.error("  You are running Node.js " + (process.versions && process.versions.node ? process.versions.node : "(unknown)") + ".");
+    console.error("");
+    console.error("  Please upgrade Node and try again:");
+    console.error("    https://nodejs.org/  (or use nvm / fnm / volta)");
+    console.error("");
+    process.exit(1);
+}
+// Node is new enough — hand off to the real ESM MCP server. Dynamic import()
+// from CommonJS is the supported ESM-from-CJS bridge. We only reach this line on
+// a supported Node, so the import() expression is never evaluated on an engine
+// that can't load the ESM graph.
+import("./index.js")
+    .then(function (mod) {
+    if (mod && typeof mod.runMcp === "function") {
+        return mod.runMcp();
+    }
+    // Older builds auto-ran on import via import.meta.main; nothing to call.
+    return undefined;
+})
+    .catch(function (err) {
+    console.error(err && err.stack ? err.stack : err);
+    process.exit(1);
+});

package/dist/mcp-shim.d.cts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * mcp-shim.cts — Node-version PREFLIGHT for the Flair MCP server.
+ *
+ * THIS IS THE BIN ENTRY (`package.json` "bin": { "flair-mcp": "dist/mcp-shim.cjs" }).
+ *
+ * Why a separate CommonJS file instead of a guard inside index.ts:
+ *   The real MCP server (dist/index.js) is an ES module. In ESM, every top-level
+ *   `import` is HOISTED and the whole module graph is LINKED + EVALUATED before
+ *   the first statement in the file body runs. flair-mcp's deps (@modelcontext-
+ *   protocol/sdk, @tpsdev-ai/flair-client and its transitive deps) require a
+ *   modern engine, so on an older Node the import graph fails to load — and a
+ *   Node-version check placed even at the very top of index.ts never executes:
+ *   the import graph crashes first. That is exactly the silent-failure bug — a
+ *   user wiring `npx -y @tpsdev-ai/flair-mcp` on an old Node gets zero output and
+ *   a dead MCP server, with no actionable signal (the same exposure flair's CLI
+ *   had before #524).
+ *
+ *   CommonJS evaluates top-to-bottom and `require()`/`import()` are evaluated
+ *   lazily — so the version check below runs and prints BEFORE anything tries to
+ *   load the ESM server or any modern dependency. Because every Node since v0.x
+ *   parses and runs CommonJS, this shim is guaranteed to run and print on the
+ *   oldest Node a user could plausibly have.
+ *
+ *   The check itself deliberately uses ONLY ancient-safe syntax — `var`, plain
+ *   functions, string `.split`/`parseInt`, `console.error`, `process.exit`. No
+ *   top-level await, no optional chaining, no template literals reaching
+ *   modern-only APIs — so the guard can never become the thing that fails to
+ *   parse.
+ */
+export {};

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "flair-mcp": "dist/index.js",
+    "flair-mcp": "dist/mcp-shim.cjs",
     "flair-session-start": "dist/session-start-hook.js"
   },
   "files": [
@@ -17,17 +17,17 @@
     "build": "tsc --noCheck",
     "test": "bun test",
     "prepublishOnly": "npm run build",
-    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/index.js','dist/session-start-hook.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair-mcp: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
+    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/mcp-shim.cjs','dist/index.js','dist/session-start-hook.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair-mcp: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.15.0",
+    "@tpsdev-ai/flair-client": "0.16.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",