@tpsdev-ai/flair-mcp 0.50.0 → 0.51.1

package/dist/index.js

@@ -45,7 +45,7 @@ import { FlairClient, FlairError, formatKeyLookup, inspectKeyLookup } from "@tps
 import { z } from "zod";
 import { deriveActivity, postPresenceSafe, resolveHeartbeatIntervalMs, resolvePresenceTimeoutMs, shouldSendHeartbeat, } from "./presence.js";
 import { readEnvOrUnset, stripInterpolationLiteralsFromEnv } from "./env-guard.js";
-import { buildRecordUsageBody, citationIds, withCiteNudge } from "./usage.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) {
@@ -521,9 +521,10 @@ export async function runMcp() {
     // 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.", {
-        memoryId: z.string().optional().describe("A single memory id that was used"),
-        memoryIds: z.array(z.string()).optional().describe("IDs of the memories that were used (max 20 per call)"),
+        "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

package/dist/usage.d.ts

@@ -13,30 +13,19 @@
 /** One-line instruction on recalled ids (issue ask #3). Search/bootstrap hits are not usage. */
 export declare const CITE_USAGE_NUDGE = "Cite memories you actually use via record_usage (or memory_store.usedMemoryIds). A search or bootstrap hit is not usage.";
 export declare function withCiteNudge(text: string): string;
+/** Stated on the stdio `record_usage` schema so a caller can predict the merge without reading source. */
+export declare const RECORD_USAGE_ID_MERGE_CONTRACT = "When both memoryId and memoryIds are supplied they are merged (union, then deduped) \u2014 a caller who passes both means both.";
 /**
  * Build the POST /RecordUsage body from the MCP tool args.
  * Accepts singular `memoryId` and/or `memoryIds`. Returns null when there is
  * nothing to send (the tool should fail locally rather than POST an empty list).
  * Never includes agentId — the server attributes from the signature.
  *
- * MERGE vs PREFER (deliberate, named — Sherlock/Kern #1404):
- * This helper MERGES `memoryId` + `memoryIds`, then dedupes. Native `/mcp`
- * `recordUsage` (resources/mcp-tools.ts) PREFERS `memoryIds` and drops
- * `memoryId` when both are supplied. The HTTP endpoint does the same:
- * `RecordUsage.post()` is `data?.memoryIds ?? [data?.memoryId]` — PREFER,
- * not union. If `memoryIds` is present (even `[]`, which is truthy),
- * `memoryId` is never read.
- *
- * The stdio merge is load-bearing because it flattens first: we send only
- * a single `memoryIds` array, so the server's prefer is never exercised
- * on two fields. A future path that POSTs both fields through to
- * `/RecordUsage` without flattening would silently drop `memoryId`
- * (delivered-but-uncounted; empty `memoryIds: []` alongside a real
- * `memoryId` would 400 rather than fall through).
- *
- * Native prefer is a pre-existing delivered-but-uncounted bug on a
- * different surface, tracked in flair#1410 — not a regression from this
- * PR, and not a blocker for #1147. Do not "align" this helper to prefer.
+ * MERGE (flair#1410): this helper unions `memoryId` + `memoryIds`, then
+ * dedupes. Native `/mcp` and `POST /RecordUsage` do the same — a caller
+ * who passes both means both. Do not "align" this helper to prefer
+ * `memoryIds` and drop `memoryId`; that is the delivered-but-uncounted
+ * bug #1410 closed.
  */
 export declare function buildRecordUsageBody(args: {
     memoryId?: string;

package/dist/usage.js

@@ -17,30 +17,19 @@ export function withCiteNudge(text) {
         return text;
     return `${text}\n\n${CITE_USAGE_NUDGE}`;
 }
+/** Stated on the stdio `record_usage` schema so a caller can predict the merge without reading source. */
+export const RECORD_USAGE_ID_MERGE_CONTRACT = "When both memoryId and memoryIds are supplied they are merged (union, then deduped) — a caller who passes both means both.";
 /**
  * Build the POST /RecordUsage body from the MCP tool args.
  * Accepts singular `memoryId` and/or `memoryIds`. Returns null when there is
  * nothing to send (the tool should fail locally rather than POST an empty list).
  * Never includes agentId — the server attributes from the signature.
  *
- * MERGE vs PREFER (deliberate, named — Sherlock/Kern #1404):
- * This helper MERGES `memoryId` + `memoryIds`, then dedupes. Native `/mcp`
- * `recordUsage` (resources/mcp-tools.ts) PREFERS `memoryIds` and drops
- * `memoryId` when both are supplied. The HTTP endpoint does the same:
- * `RecordUsage.post()` is `data?.memoryIds ?? [data?.memoryId]` — PREFER,
- * not union. If `memoryIds` is present (even `[]`, which is truthy),
- * `memoryId` is never read.
- *
- * The stdio merge is load-bearing because it flattens first: we send only
- * a single `memoryIds` array, so the server's prefer is never exercised
- * on two fields. A future path that POSTs both fields through to
- * `/RecordUsage` without flattening would silently drop `memoryId`
- * (delivered-but-uncounted; empty `memoryIds: []` alongside a real
- * `memoryId` would 400 rather than fall through).
- *
- * Native prefer is a pre-existing delivered-but-uncounted bug on a
- * different surface, tracked in flair#1410 — not a regression from this
- * PR, and not a blocker for #1147. Do not "align" this helper to prefer.
+ * MERGE (flair#1410): this helper unions `memoryId` + `memoryIds`, then
+ * dedupes. Native `/mcp` and `POST /RecordUsage` do the same — a caller
+ * who passes both means both. Do not "align" this helper to prefer
+ * `memoryIds` and drop `memoryId`; that is the delivered-but-uncounted
+ * bug #1410 closed.
  */
 export function buildRecordUsageBody(args) {
     const ids = [];

package/package.json

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