@tpsdev-ai/flair-mcp 0.53.0 → 0.54.2

package/dist/index.js

@@ -2,7 +2,7 @@
 /**
  * Flair MCP Server — persistent memory for Claude Code and any MCP client.
  *
- * Tools:
+ * Tools (derived from the vendored descriptor module — flair#1580, flair#1683):
  *   - 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,6 +14,7 @@
  *   - 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)
@@ -44,54 +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";
-import { buildSkillSearchBody, buildSkillStoreBody, formatSkillCatalog, isSkillRecord, projectSkillSearchResponse, stripInternalMemoryFields, } from "./skills.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
@@ -220,440 +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 the vendored tool-descriptors module) ────────────
     //
-    // 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);
-        }
-    });
-    // ─── Skills as memory (flair#1575 / #1542 / #1546) ──────────────────────────
-    //
-    // Native `/mcp` already ships skill_store / skill_search / skill_get in the
-    // TOOLS registry. This stdio adapter is the surface Claude Code and Cursor
-    // actually use, and it never wired them — 0.52.0's headline was unreachable.
-    // Same pattern as the other tools: shape the HTTP call via FlairClient,
-    // heartbeat, format the result. Write/recall/scope policy stays server-side.
-    server.tool("skill_store", "Write a skill (a reusable capability/procedure) as a skill-tagged memory. " +
-        "The `trigger` text is what the skill embeds from (the recall signal — 'when to use this'), " +
-        "and `content` is the full procedure. Skills are forced durability=persistent and are " +
-        "SkillScan-gated before the embed (a dangerous shell/network payload is rejected).", {
-        content: z.string().describe("The full procedure (markdown body of the SKILL.md)"),
-        trigger: z.string().optional().describe("The 'when to use' text — the recall signal the skill embeds from"),
-        name: z.string().optional().describe("Skill name (SKILL.md frontmatter; stored in metadata)"),
-        description: z.string().optional().describe("Skill description (SKILL.md frontmatter; stored in metadata)"),
-        tags: z.array(z.string()).optional().describe("Additional tags (the 'skill' tag is added automatically)"),
-    }, async ({ content, trigger, name, description, tags }) => {
-        heartbeat();
-        try {
-            const { id, body } = buildSkillStoreBody({
-                agentId: flair.agentId,
-                content,
-                trigger,
-                name,
-                description,
-                tags,
-                claimedClient: flair.claimedClient,
-            });
-            const result = await flair.request("PUT", `/Memory/${id}`, body);
-            const writtenId = typeof result?.id === "string" && result.id.length > 0 ? result.id : id;
-            const preview = content.length > 120 ? content.slice(0, 120) + "..." : content;
-            const lines = [
-                `Skill stored (id: ${writtenId})`,
-                `Preview: ${preview}`,
-                name ? `Name: ${name}` : undefined,
-                trigger ? `Trigger: ${trigger}` : undefined,
-            ].filter((line) => line != null);
-            return {
-                content: [{ type: "text", text: lines.join("\n") }],
-                structuredContent: { id: writtenId, written: true },
-            };
-        }
-        catch (err) {
-            return errorResult(err, flair.url);
-        }
-    });
-    server.tool("skill_search", "Find skills (reusable capabilities/procedures) that apply to a task. " +
-        "Ranks skill-tagged memories by their `trigger` ('when to use') against your task text. " +
-        "Returns a lightweight CATALOG — id, name, trigger, description, tags, agentId — NOT the full " +
-        "procedure (fetch that with skill_get). Scoped to your own + shared skills; another agent's " +
-        "private skill is never returned.", {
-        task: z.string().describe("The task/context to match skills against — natural language; ranked against each skill's trigger"),
-        limit: z.coerce.number().optional().default(5).describe("Max skills to return (default 5)"),
-    }, async ({ task, limit }) => {
-        heartbeat();
-        try {
-            const raw = await flair.request("POST", "/SemanticSearch", buildSkillSearchBody({ task, limit }));
-            const projected = projectSkillSearchResponse(raw);
-            if (!projected || typeof projected !== "object" || !Array.isArray(projected.results)) {
-                return { content: [{ type: "text", text: "No matching skills found." }] };
-            }
-            const results = projected.results;
-            return {
-                content: [{ type: "text", text: formatSkillCatalog(results) }],
-                structuredContent: { results },
-            };
-        }
-        catch (err) {
-            return errorResult(err, flair.url);
-        }
-    });
-    server.tool("skill_get", "Retrieve a full skill by ID — the complete procedure (`content`) plus trigger and metadata. " +
-        "The disclosure step after skill_search's catalog. Read-scoped: you can only get your own or a " +
-        "shared skill, never another agent's private skill. A non-skill id returns not-found.", {
-        id: z.string().describe("Skill (memory) ID"),
-        includeEmbedding: z.coerce.boolean().optional().default(false)
-            .describe("Include the raw embedding vector (large, rarely useful). Default false."),
-    }, async ({ id, includeEmbedding }) => {
-        heartbeat();
-        try {
-            const mem = await flair.memory.get(id);
-            if (!mem || !isSkillRecord(mem)) {
-                return { content: [{ type: "text", text: `Skill ${id} not found.` }] };
-            }
-            const record = includeEmbedding
-                ? mem
-                : stripInternalMemoryFields(mem);
-            const trigger = typeof record.trigger === "string" && record.trigger.length > 0
-                ? record.trigger
-                : "";
-            const text = [
-                record.content,
-                "",
-                `(id: ${record.id}${trigger ? `, trigger: ${trigger}` : ""}, tags: ${Array.isArray(record.tags) ? record.tags.join(", ") : "skill"}, created: ${record.createdAt ?? ""})`,
-            ].join("\n");
-            return {
-                content: [{ type: "text", text }],
-                structuredContent: record,
-            };
-        }
-        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 "./tool-descriptors/index.js";
+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)}`);
+    }
+}

package/dist/skills.d.ts

@@ -10,7 +10,8 @@
  *
  * Progressive disclosure matches the native contract: skill_search returns
  * catalog cards (never `content` / embedding); skill_get is the disclosure
- * step for the full procedure.
+ * step for the full procedure. skill_get always strips embedding /
+ * embeddingModel (flair#1579) — there is no includeEmbedding opt-in.
  */
 /** The tag that marks a Memory as a skill (resources/skill-write.ts). */
 export declare const SKILL_TAG = "skill";

package/dist/skills.js

@@ -10,7 +10,8 @@
  *
  * Progressive disclosure matches the native contract: skill_search returns
  * catalog cards (never `content` / embedding); skill_get is the disclosure
- * step for the full procedure.
+ * step for the full procedure. skill_get always strips embedding /
+ * embeddingModel (flair#1579) — there is no includeEmbedding opt-in.
  */
 /** The tag that marks a Memory as a skill (resources/skill-write.ts). */
 export const SKILL_TAG = "skill";