@tpsdev-ai/flair-mcp 0.52.0 → 0.54.1

package/dist/catchup.js

@@ -0,0 +1,85 @@
+/**
+ * catchup.ts — pure helpers for the flair_catchup stdio binding (flair#1583).
+ *
+ * Owner-scope is enforced BY CONSTRUCTION: the participantId in the request
+ * path is always the caller's own agentId (from `FLAIR_AGENT_ID` / the signed
+ * identity), never a tool argument. The descriptor advertises no `agentId` /
+ * `participantId` property, so there is nothing to name another agent's feed
+ * with — and the server independently refuses a cross-agent read (403). This
+ * module is HTTP-/Harper-free (plain helpers + types) so the flair-mcp
+ * package stays FlairClient-only.
+ */
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * Build the owner-scoped catchup request from tool args. `participantId` is
+ * ALWAYS `agentId` — the args cannot redirect it.
+ */
+export function buildCatchupRequest(agentId, args) {
+    const path = `/OrgEventCatchup/${encodeURIComponent(agentId)}`;
+    const params = new URLSearchParams();
+    const after = nonEmptyString(args.after);
+    if (after)
+        params.set("after", after);
+    if (typeof args.limit === "number" && Number.isFinite(args.limit)) {
+        params.set("limit", String(Math.trunc(args.limit)));
+    }
+    const query = params.toString();
+    return {
+        path,
+        getPath: query ? `${path}?${query}` : path,
+        ackPath: path,
+        ackPosition: nonEmptyString(args.ack),
+    };
+}
+/**
+ * Project a catchup page into the caller-facing text summary plus the
+ * structured echo (the machine-readable payload). Never throws on a
+ * malformed/absent page — it degrades to "no new events".
+ */
+export function summarizeCatchup(page, acked) {
+    const events = Array.isArray(page?.events) ? page?.events : [];
+    const after = page?.after ?? null;
+    const nextAfter = page?.nextAfter ?? after;
+    const watermark = page?.watermark ?? null;
+    const hasMore = page?.hasMore === true;
+    const pageSize = page?.pageSize;
+    const header = events.length === 0
+        ? `Catchup: no new events after ${after ?? "(your watermark)"}.`
+        : `Catchup: ${events.length} event(s) after ${after ?? "(your watermark)"}${hasMore ? " (more available)" : ""}.`;
+    const lines = events.map((event, index) => {
+        const kind = typeof event.kind === "string" ? event.kind : "?";
+        const summary = typeof event.summary === "string" ? event.summary : "";
+        const id = typeof event.id === "string" ? `id:${event.id}` : "";
+        const position = typeof event.position === "string" ? `position:${event.position}` : "";
+        const targets = Array.isArray(event.targetIds) && event.targetIds.length > 0
+            ? `targets:${event.targetIds.join(",")}`
+            : "";
+        const meta = [id, position, targets].filter(Boolean).join(", ");
+        return `${index + 1}. [${kind}] ${summary}${meta ? ` (${meta})` : ""}`;
+    });
+    const cursorLines = [];
+    if (nextAfter)
+        cursorLines.push(`nextAfter: ${nextAfter}`);
+    if (acked)
+        cursorLines.push(`acked: ${acked}`);
+    if (nextAfter) {
+        cursorLines.push(hasMore
+            ? `More available — page again with after="${nextAfter}", then ack="${nextAfter}" once drained.`
+            : `Ack with ack="${nextAfter}" once you have processed these events to advance your watermark.`);
+    }
+    const body = [header, ...lines, ...(cursorLines.length > 0 ? ["", ...cursorLines] : [])].join("\n");
+    const structuredContent = {
+        events,
+        after,
+        nextAfter,
+        watermark,
+        hasMore,
+    };
+    if (typeof pageSize === "number")
+        structuredContent.pageSize = pageSize;
+    if (acked)
+        structuredContent.acked = acked;
+    return { text: body, structuredContent };
+}

package/dist/errors.d.ts

@@ -0,0 +1 @@
+export declare function classifyError(err: unknown, flairUrl: string): string;

package/dist/errors.js

@@ -0,0 +1,39 @@
+import { FlairError, formatKeyLookup, inspectKeyLookup } from "@tpsdev-ai/flair-client";
+import { readEnvOrUnset } from "./env-guard.js";
+export function classifyError(err, flairUrl) {
+    if (err instanceof FlairError) {
+        const { status, body } = err;
+        if (status === 400)
+            return `validation_error: ${body}`;
+        if (status === 401 || status === 403) {
+            // flair#1271: name the agent, the paths that were looked in, and the
+            // remedy. A cached-miss / wrong-HOME 401 is not a daemon-restart hint.
+            const lookup = err.keyLookup ?? {
+                ...inspectKeyLookup(readEnvOrUnset("FLAIR_AGENT_ID") ?? "", readEnvOrUnset("FLAIR_KEY_PATH")),
+                signed: false,
+                authMethod: "none",
+            };
+            return `auth_error: ${body}\n${formatKeyLookup(lookup)}`;
+        }
+        if (status === 413)
+            return `payload_too_large: ${body}`;
+        if (status === 429)
+            return "rate_limited — retry after a moment";
+        if (status >= 500)
+            return `server_error (retriable): ${body}`;
+        return `http_error (${status}): ${body}`;
+    }
+    if (err instanceof Error) {
+        if (err.name.includes("Abort") || err.name.includes("Timeout")) {
+            return "timeout — the server took too long. This often happens with large content that requires embedding. Try shorter content or retry.";
+        }
+        if (err instanceof TypeError && err.message.includes("fetch")) {
+            return `connection_error (retriable): could not reach Flair at ${flairUrl}. Is it running?\n` +
+                `(Diagnostics:\n` +
+                `  - 'curl ${flairUrl}/Health' — if this responds 200 or 401, daemon is up + this is an auth issue not a connection one.\n` +
+                `  - 'launchctl list | grep flair' (macOS) or 'systemctl status flair' (Linux).)`;
+        }
+        return `unexpected_error: ${err.message}`;
+    }
+    return `unexpected_error: ${String(err)}`;
+}

package/dist/index.d.ts

@@ -2,7 +2,7 @@
 /**
  * Flair MCP Server — persistent memory for Claude Code and any MCP client.
  *
- * Tools:
+ * Tools (derived from @tpsdev-ai/flair-tool-descriptors — flair#1580):
  *   - memory_search  — semantic search across memories
  *   - memory_store   — save a memory with type + durability
  *   - memory_update  — update an existing memory by ID (dedup-bypassed)
@@ -14,7 +14,11 @@
  *   - soul_get       — get a personality/context entry
  *   - flair_workspace_set — write own WorkspaceState (Office Space coordination)
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
+ *   - flair_catchup       — drain + ack self's own OrgEventCatchup feed (owner-scoped)
  *   - record_usage        — report that recalled memories were actually used (flair#1147)
+ *   - skill_store         — write a skill-tagged memory (trigger + procedure)
+ *   - skill_search        — catalog skills that apply to a task (not the procedure)
+ *   - skill_get           — retrieve the full skill by id (disclosure after search)
  *
  * Auto-presence (flair#598): every tool call above triggers a fire-and-forget,
  * rate-limited `POST /Presence` heartbeat for the calling agent (see
@@ -39,5 +43,5 @@
  * — 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 declare function classifyError(err: unknown, flairUrl: string): string;
+export { classifyError } from "./errors.js";
 export declare function runMcp(): Promise<void>;

package/dist/index.js

@@ -2,7 +2,7 @@
 /**
  * Flair MCP Server — persistent memory for Claude Code and any MCP client.
  *
- * Tools:
+ * Tools (derived from @tpsdev-ai/flair-tool-descriptors — flair#1580):
  *   - memory_search  — semantic search across memories
  *   - memory_store   — save a memory with type + durability
  *   - memory_update  — update an existing memory by ID (dedup-bypassed)
@@ -14,7 +14,11 @@
  *   - soul_get       — get a personality/context entry
  *   - flair_workspace_set — write own WorkspaceState (Office Space coordination)
  *   - flair_orgevent      — publish an OrgEvent attributed to self (no forging)
+ *   - flair_catchup       — drain + ack self's own OrgEventCatchup feed (owner-scoped)
  *   - record_usage        — report that recalled memories were actually used (flair#1147)
+ *   - skill_store         — write a skill-tagged memory (trigger + procedure)
+ *   - skill_search        — catalog skills that apply to a task (not the procedure)
+ *   - skill_get           — retrieve the full skill by id (disclosure after search)
  *
  * Auto-presence (flair#598): every tool call above triggers a fire-and-forget,
  * rate-limited `POST /Presence` heartbeat for the calling agent (see
@@ -41,53 +45,12 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { FlairClient, FlairError, formatKeyLookup, inspectKeyLookup } from "@tpsdev-ai/flair-client";
-import { z } from "zod";
-import { deriveActivity, postPresenceSafe, resolveHeartbeatIntervalMs, resolvePresenceTimeoutMs, shouldSendHeartbeat, } from "./presence.js";
+import { FlairClient } from "@tpsdev-ai/flair-client";
+import { postPresenceSafe, resolveHeartbeatIntervalMs, resolvePresenceTimeoutMs, shouldSendHeartbeat, } from "./presence.js";
 import { readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
-import { buildRecordUsageBody, citationIds, withCiteNudge, RECORD_USAGE_ID_MERGE_CONTRACT } from "./usage.js";
 import { serverInfo } from "./version.js";
-// ─── Error helpers ──────────────────────────────────────────────────────────
-export function classifyError(err, flairUrl) {
-    if (err instanceof FlairError) {
-        const { status, body } = err;
-        if (status === 400)
-            return `validation_error: ${body}`;
-        if (status === 401 || status === 403) {
-            // flair#1271: name the agent, the paths that were looked in, and the
-            // remedy. A cached-miss / wrong-HOME 401 is not a daemon-restart hint.
-            const lookup = err.keyLookup ?? {
-                ...inspectKeyLookup(readEnvOrUnset("FLAIR_AGENT_ID") ?? "", readEnvOrUnset("FLAIR_KEY_PATH")),
-                signed: false,
-                authMethod: "none",
-            };
-            return `auth_error: ${body}\n${formatKeyLookup(lookup)}`;
-        }
-        if (status === 413)
-            return `payload_too_large: ${body}`;
-        if (status === 429)
-            return "rate_limited — retry after a moment";
-        if (status >= 500)
-            return `server_error (retriable): ${body}`;
-        return `http_error (${status}): ${body}`;
-    }
-    if (err instanceof Error) {
-        if (err.name.includes("Abort") || err.name.includes("Timeout")) {
-            return "timeout — the server took too long. This often happens with large content that requires embedding. Try shorter content or retry.";
-        }
-        if (err instanceof TypeError && err.message.includes("fetch")) {
-            return `connection_error (retriable): could not reach Flair at ${flairUrl}. Is it running?\n` +
-                `(Diagnostics:\n` +
-                `  - 'curl ${flairUrl}/Health' — if this responds 200 or 401, daemon is up + this is an auth issue not a connection one.\n` +
-                `  - 'launchctl list | grep flair' (macOS) or 'systemctl status flair' (Linux).)`;
-        }
-        return `unexpected_error: ${err.message}`;
-    }
-    return `unexpected_error: ${String(err)}`;
-}
-function errorResult(err, flairUrl) {
-    return { content: [{ type: "text", text: classifyError(err, flairUrl) }], isError: true };
-}
+import { registerStdioTools } from "./adapter-tools.js";
+export { classifyError } from "./errors.js";
 // ─── Entry point ──────────────────────────────────────────────────────────────
 //
 // runMcp() is the real entry point. It is exported so the CommonJS preflight
@@ -216,336 +179,19 @@ export async function runMcp() {
     }
     // ─── MCP Server ──────────────────────────────────────────────────────────────
     const server = new McpServer(serverInfo());
-    // ─── 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 }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        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: withCiteNudge(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"),
-        visibility: z.enum(["private", "shared"]).optional().describe("Writer-controlled sharing intent (omit to use the server's durability-keyed default: " +
-            "permanent/persistent -> shared, standard/ephemeral -> private). " +
-            "private -- never visible to another agent, even one with a memory grant. " +
-            "shared -- visible to the owner and any agent holding a read/search grant."),
-        usedMemoryIds: z.array(z.string()).optional().describe("IDs of memories that informed this write (citation-on-write). Credited via the same " +
-            "deduped usage ledger as record_usage. Optional."),
-    }, async ({ content, type, durability, tags, visibility, usedMemoryIds }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        try {
-            const result = await flair.memory.write(content, {
-                type: type,
-                durability: durability,
-                tags,
-                visibility: visibility,
-                dedup: true,
-                dedupThreshold: 0.95,
-                usedMemoryIds: citationIds(usedMemoryIds),
-            });
-            // The server's conservative dedup gate NEVER suppresses a write
-            // (memory-integrity fix, flair#526) — `result.deduplicated` is a
-            // collision SIGNAL, not a "was this dropped" flag. The new content at
-            // `result.id` is ALWAYS written; when flagged, `result.matchedId` names
-            // the similar existing memory (see result.matchConfidence for the
-            // cosine/lexical scores). Emit both prose AND structuredContent so
-            // callers can react programmatically even when LLMs compress prose
-            // imprecisely. (Historical note: this tool used to treat a dedup hit as
-            // "new content was NOT written" — that WAS the flair#449/#526 silent
-            // data-loss bug. The gate is server-side now and never suppresses.)
-            const deduplicated = result.deduplicated === true;
-            const matchedId = result.matchedId;
-            const effectiveVisibility = result.visibility;
-            const preview = content.length > 120 ? content.slice(0, 120) + "..." : content;
-            const tagStr = tags && tags.length > 0 ? tags.join(", ") : "none";
-            const lines = [
-                `Memory stored (id: ${result.id})`,
-                `Preview: ${preview}`,
-                `Size: ${content.length} chars`,
-                `Tags: ${tagStr}`,
-                `Type: ${type}, Durability: ${durability}, Visibility: ${effectiveVisibility ?? "(server default)"}`,
-            ];
-            if (deduplicated && matchedId) {
-                lines.push("", `Note: similar to existing memory id=${matchedId} — both are kept. ` +
-                    `If this was meant to UPDATE that memory rather than add a new one, use memory_update instead.`);
-            }
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-                structuredContent: { deduplicated, id: result.id, written: true, ...(deduplicated ? { matchedId } : {}) },
-            };
-        }
-        catch (err) {
-            return errorResult(err, flair.url);
-        }
-    });
-    server.tool("memory_update", "Update an existing memory by ID. Dedup-bypassed — this is an intentional overwrite/version, not an ambiguous new write. " +
-        "Default: overwrites the same id in place. Pass preserveHistory=true to instead write a new version linked via " +
-        "`supersedes`, closing the old one's validity window (requires owning the memory, or a write grant if it's another agent's).", {
-        id: z.string().describe("ID of the memory to update"),
-        content: z.string().describe("New content"),
-        preserveHistory: z.coerce.boolean().optional().default(false)
-            .describe("Write a new supersedes-linked version instead of overwriting in place (default false)"),
-        usedMemoryIds: z.array(z.string()).optional().describe("IDs of memories that informed this update (citation-on-write). Credited via the same " +
-            "deduped usage ledger as record_usage. Optional."),
-    }, async ({ id, content, preserveHistory, usedMemoryIds }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        try {
-            const result = await flair.memory.update(id, content, {
-                preserveHistory,
-                usedMemoryIds: citationIds(usedMemoryIds),
-            });
-            const text = preserveHistory
-                ? `Memory updated: new version stored (id: ${result.id}), supersedes ${id}.`
-                : `Memory updated (id: ${id}).`;
-            return {
-                content: [{ type: "text", text }],
-                structuredContent: { id: result.id, supersedes: preserveHistory ? id : undefined, 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 }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        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 }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        try {
-            await flair.memory.delete(id);
-            return { content: [{ type: "text", text: `Memory ${id} deleted.` }] };
-        }
-        catch (err) {
-            return errorResult(err, flair.url);
-        }
-    });
-    server.tool("relationship_store", "Record that <subject> <predicate> <object> — an explicit entity-to-entity relationship triple " +
-        "(e.g. 'nathan manages flair', 'flint reviews cli'), distinct from a free-text memory. " +
-        "ASSERT/UPSERT semantics: writing the SAME triple again (same subject/predicate/object) updates the " +
-        "existing row in place (confidence/validTo/source refresh) rather than creating a duplicate — safe to " +
-        "re-assert. Predicate is free text (no fixed enum) but prefer a small, consistent vocabulary so the graph " +
-        "stays queryable: manages, works_on, reviews, depends_on, replaces, owns, reports_to, advises. " +
-        "TO CONTRADICT a prior relationship: (a) re-asserting the identical triple just updates it — fine. " +
-        "(b) changing validTo on the SAME subject/predicate/object overwrites the old validTo (the graph tracks " +
-        "current state, not full history). (c) changing the PREDICATE (e.g. 'nathan manages flair' -> 'nathan " +
-        "advises flair') creates a SEPARATE relationship — it does NOT automatically close the old one. Close it " +
-        "yourself first: re-assert the OLD triple with a validTo set to now (or call relationship's delete), THEN " +
-        "store the new one.", {
-        subject: z.string().describe("Source entity — a person, project, or service (e.g. 'nathan')"),
-        predicate: z.string().describe("Relationship type, free text. Recommended vocabulary: manages, works_on, reviews, depends_on, " +
-            "replaces, owns, reports_to, advises — consistency helps recall, but any short verb phrase works."),
-        object: z.string().describe("Target entity — a person, project, or service (e.g. 'flair')"),
-        confidence: z.coerce.number().optional().describe("0.0-1.0, how certain (default 1.0 = explicitly stated)"),
-        validFrom: z.string().optional().describe("ISO timestamp this relationship became true (default: now)"),
-        validTo: z.string().optional().describe("ISO timestamp this relationship ended. Leave unset for an active relationship; set it (via a re-assert " +
-            "of this SAME subject/predicate/object) to close out a relationship you're contradicting with a new predicate."),
-        source: z.string().optional().describe("Where this was learned from (a memory ID, conversation, etc.)"),
-    }, async ({ subject, predicate, object, confidence, validFrom, validTo, source }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        try {
-            const result = await flair.relationship.write({ subject, predicate, object, confidence, validFrom, validTo, source });
-            const confStr = confidence !== undefined ? ` (confidence: ${confidence})` : "";
-            return {
-                content: [{ type: "text", text: `Relationship recorded: ${subject} → ${predicate} → ${object}${confStr} (id: ${result.id})` }],
-                structuredContent: { id: result.id, subject, predicate, object, written: true },
-            };
-        }
-        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 }) => {
-        // auto-presence (flair#598) — SESSION START. bootstrap() already receives
-        // exactly the payload Presence wants: currentTask is what the agent is
-        // about to work on, channel/surface are what deriveActivity() uses to
-        // pick something more specific than the "coding" default. Routed through
-        // the SAME rate-limited heartbeat() as every other tool, so calling
-        // bootstrap twice in quick succession (session resume/compact) doesn't
-        // double-send — it's still "sets presence once" per session in practice.
-        if (currentTask)
-            lastKnownTask = currentTask;
-        heartbeat(deriveActivity({ channel, surface }));
-        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: withCiteNudge(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 }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        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 }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        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 ──────────────────────────────────────────────
+    // ─── Tools (derived from @tpsdev-ai/flair-tool-descriptors) ───────────────
     //
-    // 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 }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        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;
+    // The advertised set is STDIO_TOOL_DESCRIPTORS. Handlers bind each
+    // descriptor to a FlairClient HTTP call. A new shared descriptor appears
+    // here for free once a FlairClient binding exists — no per-tool literals.
+    registerStdioTools(server, {
+        flair,
+        agentId,
+        heartbeat,
+        rememberTask: (task) => {
             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 }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        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);
-        }
-    });
-    // ─── Usage feedback (flair#1147) ─────────────────────────────────────────────
-    //
-    // POST /RecordUsage already existed; native /mcp already wrapped it. The
-    // stdio package did not, so a Claude Code / Cursor client could not close
-    // the usageCount loop. Identity is taken from the signed request — the body
-    // carries only memory id(s) + optional attribution, never agentId.
-    server.tool("record_usage", "Report that one or more memories were actually USED — cited or relied on to ground an answer or decision. " +
-        "Distinct from search (surfacing a memory is not usage). Dedup'd (you can only count once per memory) and rate-limited. " +
-        RECORD_USAGE_ID_MERGE_CONTRACT, {
-        memoryId: z.string().optional().describe("A single memory id that was used. Merged with memoryIds when both are supplied — not dropped."),
-        memoryIds: z.array(z.string()).optional().describe("IDs of the memories that were used (max 20 per call). Merged with memoryId when both are supplied."),
-        attribution: z.string().optional().describe("Optional one-line note on how it was used (opaque — stored for audit only)"),
-    }, async ({ memoryId, memoryIds, attribution }) => {
-        heartbeat(); // auto-presence (flair#598) — fire-and-forget, rate-limited
-        try {
-            const body = buildRecordUsageBody({ memoryId, memoryIds, attribution });
-            if (!body) {
-                return {
-                    content: [{ type: "text", text: "record_usage requires memoryId or memoryIds." }],
-                    isError: true,
-                };
-            }
-            const result = await flair.request("POST", "/RecordUsage", body);
-            const text = result?.recorded === true ? "Usage recorded." : "Usage request accepted.";
-            return {
-                content: [{ type: "text", text }],
-                structuredContent: { recorded: result?.recorded === true },
-            };
-        }
-        catch (err) {
-            return errorResult(err, flair.url);
-        }
+                lastKnownTask = task;
+        },
     });
     // ─── Start ───────────────────────────────────────────────────────────────────
     const transport = new StdioServerTransport();

package/dist/json-schema-zod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * JSON Schema → Zod raw shape for MCP SDK `server.tool()` (flair#1580).
+ *
+ * Lives in the adapter, not the descriptor module: Zod is an SDK concern.
+ * Number/boolean use `z.coerce` so MCP clients that send stringified scalars
+ * keep working (the previous hand-wired Zod schemas did the same).
+ */
+import { type ZodTypeAny } from "zod";
+import type { JsonSchemaObject } from "@tpsdev-ai/flair-tool-descriptors";
+export declare function jsonSchemaToZodShape(schema: JsonSchemaObject): Record<string, ZodTypeAny>;

package/dist/json-schema-zod.js

@@ -0,0 +1,43 @@
+/**
+ * JSON Schema → Zod raw shape for MCP SDK `server.tool()` (flair#1580).
+ *
+ * Lives in the adapter, not the descriptor module: Zod is an SDK concern.
+ * Number/boolean use `z.coerce` so MCP clients that send stringified scalars
+ * keep working (the previous hand-wired Zod schemas did the same).
+ */
+import { z } from "zod";
+export function jsonSchemaToZodShape(schema) {
+    const required = new Set(schema.required ?? []);
+    const shape = {};
+    for (const [key, prop] of Object.entries(schema.properties ?? {})) {
+        let t = propToZod(prop);
+        if (prop.description)
+            t = t.describe(prop.description);
+        if (!required.has(key))
+            t = t.optional();
+        if (prop.default !== undefined)
+            t = t.default(prop.default);
+        shape[key] = t;
+    }
+    return shape;
+}
+function propToZod(prop) {
+    if (Array.isArray(prop.enum) && prop.enum.length > 0) {
+        const [first, ...rest] = prop.enum;
+        return z.enum([first, ...rest]);
+    }
+    switch (prop.type) {
+        case "string":
+            return z.string();
+        case "number":
+            return z.coerce.number();
+        case "boolean":
+            return z.coerce.boolean();
+        case "array":
+            if (prop.items?.type === "string")
+                return z.array(z.string());
+            throw new Error(`unsupported array items: ${JSON.stringify(prop.items)}`);
+        default:
+            throw new Error(`unsupported json schema type: ${JSON.stringify(prop.type)}`);
+    }
+}