@unclick/mcp-server 0.2.5 → 0.3.1

package/README.md

@@ -1,139 +1,160 @@
-# @unclick/mcp-server
-
-**MCP server for the [UnClick](https://unclick.world) tool marketplace.**
-
-Lets any MCP-compatible AI agent (Claude, Cursor, etc.) discover and use every tool in the UnClick marketplace — URL shortening, QR codes, image processing, hashing, CSV/JSON, regex, cron, color utilities, key-value storage, and more.
-
-## Quick Start
-
-### Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
-
-```json
-{
-  "mcpServers": {
-    "unclick": {
-      "command": "npx",
-      "args": ["-y", "@unclick/mcp-server"],
-      "env": {
-        "UNCLICK_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
-```
-
-Get your API key at [unclick.world](https://unclick.world).
-
-### Local / Development
-
-```bash
-UNCLICK_API_KEY=unck_... npx @unclick/mcp-server
-```
-
-## Configuration
-
-| Environment Variable | Default | Description |
-|---|---|---|
-| `UNCLICK_API_KEY` | *(required)* | Your UnClick API key |
-| `UNCLICK_BASE_URL` | `https://api.unclick.world` | Override API base URL (for self-hosted) |
-
-## Tools Exposed
-
-### Discovery (Meta Tools)
-
-These tools let agents explore the full marketplace dynamically.
-
-| Tool | Description |
-|---|---|
-| `unclick_search` | Search for tools by keyword. "I need to resize an image" → returns the image tool with endpoints and schemas. |
-| `unclick_browse` | Browse all tools, optionally filtered by category (text, data, media, time, network, generation, storage). |
-| `unclick_tool_info` | Get full details on a specific tool: all endpoints, required params, and response shapes. |
-| `unclick_call` | Universal caller — specify any `endpoint_id` and `params`, the server routes the call. |
-
-**Discovery flow for an agent:**
-1. `unclick_search` → "what tool handles X?"
-2. `unclick_tool_info` → "what are the exact params for that tool?"
-3. `unclick_call` → call it
-
-### Direct Tools (Zero Friction)
-
-The most-used tools are exposed as first-class MCP tools for immediate use without discovery:
-
-| Tool | What it does |
-|---|---|
-| `unclick_shorten_url` | Shorten a URL |
-| `unclick_generate_qr` | Generate a QR code (PNG/SVG) |
-| `unclick_hash` | Hash text with MD5/SHA1/SHA256/SHA512 |
-| `unclick_transform_text` | Change text case (camel, snake, kebab, title, etc.) |
-| `unclick_validate_email` | Validate an email address |
-| `unclick_validate_url` | Validate a URL (+ optional reachability check) |
-| `unclick_resize_image` | Resize a base64-encoded image |
-| `unclick_parse_csv` | Parse CSV to JSON |
-| `unclick_json_format` | Pretty-print JSON |
-| `unclick_encode` | Encode/decode base64, URL, HTML, or hex |
-| `unclick_generate_uuid` | Generate UUIDs |
-| `unclick_random_password` | Generate a secure password |
-| `unclick_cron_parse` | Parse a cron expression + show next occurrences |
-| `unclick_ip_parse` | Parse an IP address |
-| `unclick_color_convert` | Convert color between hex/RGB/HSL/HSV |
-| `unclick_regex_test` | Test a regex and get all matches |
-| `unclick_timestamp_convert` | Convert timestamps between formats |
-| `unclick_diff_text` | Line-by-line diff of two strings |
-| `unclick_kv_set` | Store a value in the key-value store |
-| `unclick_kv_get` | Retrieve a value from the key-value store |
-
-## Full Tool Catalog
-
-The marketplace currently includes 23 tool groups spanning:
-
-- **Text** — transform (case, slug, count), encode/decode (base64, URL, HTML, hex), hash/HMAC, regex, markdown, diff
-- **Data** — JSON utilities, CSV processing, input validation (email, URL, phone, credit card, IP, color)
-- **Media** — image processing (resize, convert, crop, rotate, compress, grayscale), QR code generation, color utilities
-- **Time** — timestamp conversion, cron parsing/building
-- **Network** — URL shortening, IP utilities (parse, subnet, CIDR)
-- **Generation** — UUID v4, random (numbers, strings, passwords, picks, shuffles, colors)
-- **Storage** — key-value store (with TTL), webhook bins
-
-All tools are accessible via `unclick_call` with the appropriate `endpoint_id`.
-
-## Example Usage
-
-**Agent discovers and uses a tool:**
-```
-Agent: I need to hash a password before storing it.
-
-1. unclick_search({ query: "hash password" })
-   → Returns: hash tool (slug: hash, endpoints: hash.compute, hash.verify, hash.hmac)
-
-2. unclick_call({ endpoint_id: "hash.compute", params: { text: "my-secret", algorithm: "sha256" } })
-   → { algorithm: "sha256", hash: "abc123...", length: 64 }
-```
-
-**Direct tool usage:**
-```
-Agent: unclick_generate_qr({ text: "https://example.com", format: "png", size: 400 })
-→ { binary: true, content_type: "image/png", data: "<base64>" }
-```
-
-## Development
-
-```bash
-# Run locally with tsx (no build step)
-UNCLICK_API_KEY=unck_... npm run dev
-
-# Build
-npm run build
-
-# Run built output
-npm start
-```
-
-## MCP Registry
-
-This server is published to npm as `@unclick/mcp-server` and can be added to any MCP registry that supports npx-based servers.
-
-## License
-
-MIT
+# @unclick/mcp-server
+
+**MCP server for the [UnClick](https://unclick.world) tool marketplace.**
+
+One install gives any MCP-compatible AI agent (Claude, Cursor, etc.) access to:
+- **450+ callable endpoints** across 60+ integrations (social, e-commerce, accounting, messaging, and more)
+- **Persistent cross-session memory** — the agent remembers you across sessions, zero config
+
+## Quick Start
+
+### Claude Desktop / Claude Code
+
+Add to your MCP config (Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`, or run `claude mcp add` in Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "unclick": {
+      "command": "npx",
+      "args": ["-y", "@unclick/mcp-server"],
+      "env": {
+        "UNCLICK_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Get your API key at [unclick.world](https://unclick.world).
+
+> **Install codes.** The `UNCLICK_API_KEY` can also be a short-lived install code like `unclick-ember-falcon-2847` (good for 24 hours). On first boot the server exchanges it for the real key and caches it at `~/.unclick/credentials.json`. This means install snippets shared in chat look like project slugs rather than credentials.
+
+### Cursor
+
+Same config snippet as above — Cursor uses the same MCP format.
+
+### Local / Development
+
+```bash
+UNCLICK_API_KEY=unck_... npx @unclick/mcp-server
+```
+
+## Memory (built in, zero config)
+
+Memory works out of the box. No setup needed — data is stored as JSON files in `~/.unclick/memory/`.
+
+**Want cross-machine sync?** Add Supabase env vars to your config:
+
+```json
+"env": {
+  "UNCLICK_API_KEY": "your_api_key_here",
+  "SUPABASE_URL": "https://your-project.supabase.co",
+  "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key"
+}
+```
+
+Memory tools exposed at session level: `load_memory`, `save_session`, `save_fact`, `search_memory`, `save_identity`. Full 17 operations available via `unclick_call` with `endpoint_id: "memory.*"`. The prior names (`get_startup_context`, `write_session_summary`, `add_fact`, `set_business_context`) still work as backward-compatible aliases.
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `UNCLICK_API_KEY` | *(required)* | Your UnClick API key |
+| `UNCLICK_BASE_URL` | `https://api.unclick.world` | Override API base URL (for self-hosted) |
+
+## Tools Exposed
+
+### Discovery
+
+| Tool | Description |
+|---|---|
+| `unclick_search` | Search for tools by keyword. "I need to resize an image" returns the image tool with endpoints and schemas. |
+
+`unclick_browse`, `unclick_tool_info`, and `unclick_call` remain callable for backward compatibility but are hidden from the advertised tool list so end users are not shown internal machinery.
+
+**Discovery flow for an agent:**
+1. `unclick_search` to find relevant tools
+2. Inspect the returned endpoint schemas
+3. Invoke the matching endpoint via the raw call interface
+
+### Direct Tools (Zero Friction)
+
+The most-used tools are exposed as first-class MCP tools for immediate use without discovery:
+
+| Tool | What it does |
+|---|---|
+| `unclick_shorten_url` | Shorten a URL |
+| `unclick_generate_qr` | Generate a QR code (PNG/SVG) |
+| `unclick_hash` | Hash text with MD5/SHA1/SHA256/SHA512 |
+| `unclick_transform_text` | Change text case (camel, snake, kebab, title, etc.) |
+| `unclick_validate_email` | Validate an email address |
+| `unclick_validate_url` | Validate a URL (+ optional reachability check) |
+| `unclick_resize_image` | Resize a base64-encoded image |
+| `unclick_parse_csv` | Parse CSV to JSON |
+| `unclick_json_format` | Pretty-print JSON |
+| `unclick_encode` | Encode/decode base64, URL, HTML, or hex |
+| `unclick_generate_uuid` | Generate UUIDs |
+| `unclick_random_password` | Generate a secure password |
+| `unclick_cron_parse` | Parse a cron expression + show next occurrences |
+| `unclick_ip_parse` | Parse an IP address |
+| `unclick_color_convert` | Convert color between hex/RGB/HSL/HSV |
+| `unclick_regex_test` | Test a regex and get all matches |
+| `unclick_timestamp_convert` | Convert timestamps between formats |
+| `unclick_diff_text` | Line-by-line diff of two strings |
+| `unclick_kv_set` | Store a value in the key-value store |
+| `unclick_kv_get` | Retrieve a value from the key-value store |
+
+## Full Tool Catalog
+
+The marketplace currently includes 23 tool groups spanning:
+
+- **Text** — transform (case, slug, count), encode/decode (base64, URL, HTML, hex), hash/HMAC, regex, markdown, diff
+- **Data** — JSON utilities, CSV processing, input validation (email, URL, phone, credit card, IP, color)
+- **Media** — image processing (resize, convert, crop, rotate, compress, grayscale), QR code generation, color utilities
+- **Time** — timestamp conversion, cron parsing/building
+- **Network** — URL shortening, IP utilities (parse, subnet, CIDR)
+- **Generation** — UUID v4, random (numbers, strings, passwords, picks, shuffles, colors)
+- **Storage** — key-value store (with TTL), webhook bins
+
+All tools are accessible via `unclick_call` with the appropriate `endpoint_id`.
+
+## Example Usage
+
+**Agent discovers and uses a tool:**
+```
+Agent: I need to hash a password before storing it.
+
+1. unclick_search({ query: "hash password" })
+   → Returns: hash tool (slug: hash, endpoints: hash.compute, hash.verify, hash.hmac)
+
+2. unclick_call({ endpoint_id: "hash.compute", params: { text: "my-secret", algorithm: "sha256" } })
+   → { algorithm: "sha256", hash: "abc123...", length: 64 }
+```
+
+**Direct tool usage:**
+```
+Agent: unclick_generate_qr({ text: "https://example.com", format: "png", size: 400 })
+→ { binary: true, content_type: "image/png", data: "<base64>" }
+```
+
+## Development
+
+```bash
+# Run locally with tsx (no build step)
+UNCLICK_API_KEY=unck_... npm run dev
+
+# Build
+npm run build
+
+# Run built output
+npm start
+```
+
+## MCP Registry
+
+This server is published to npm as `@unclick/mcp-server` and can be added to any MCP registry that supports npx-based servers.
+
+## License
+
+MIT

package/dist/abn-tool.js

@@ -1,5 +1,5 @@
 // Australian Business Registry (ABN Lookup) integration.
-// Uses the free ABR JSONP API — no authentication required.
+// Uses the free ABR JSONP API - no authentication required.
 // Base URL: https://abr.business.gov.au/json/
 const ABN_BASE = "https://abr.business.gov.au/json";
 // ─── JSONP helper ─────────────────────────────────────────────────────────────

package/dist/bgg-tool.js

@@ -187,7 +187,7 @@ export async function bggUserCollection(args) {
     };
 }
 // ─── bgg_top_games ────────────────────────────────────────────────────────────
-// GET /hot?type=boardgame — returns BGG's "Hotness" list (top 50)
+// GET /hot?type=boardgame - returns BGG's "Hotness" list (top 50)
 export async function bggTopGames(args) {
     const limit = Math.min(Number(args.limit ?? 20), 50);
     const data = await bggFetch("/hot?type=boardgame");

package/dist/carboninterface-tool.js

@@ -34,7 +34,7 @@ export async function estimateFlightEmissions(args) {
     const legs = args.legs;
     const passengers = Number(args.passengers ?? 1);
     if (!Array.isArray(legs) || legs.length === 0) {
-        throw new Error("legs is required — array of { departure_airport, destination_airport } " +
+        throw new Error("legs is required - array of { departure_airport, destination_airport } " +
             "(IATA codes, e.g. [{departure_airport:'SFO', destination_airport:'LAX'}]).");
     }
     const mappedLegs = legs.map((leg) => {

package/dist/cards/card.d.ts

@@ -0,0 +1,9 @@
+export interface ConversationalCard {
+    headline: string;
+    summary: string;
+    keyFacts: string[];
+    nextActions: string[];
+    deepLink?: string;
+}
+export declare function buildCard(fields: ConversationalCard): ConversationalCard;
+//# sourceMappingURL=card.d.ts.map

package/dist/cards/card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.d.ts","sourceRoot":"","sources":["../../src/cards/card.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAExE"}

package/dist/cards/card.js

@@ -0,0 +1,4 @@
+export function buildCard(fields) {
+    return fields;
+}
+//# sourceMappingURL=card.js.map

package/dist/cards/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../src/cards/card.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,SAAS,CAAC,MAA0B;IAClD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cards/search-memory-card.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Phase 1 example wrap. Builds a ConversationalCard summarising a
+ * search_memory result list. Only invoked when the caller opts in via
+ * include_card=true on search_memory; the legacy raw-array response is the
+ * default so existing agents keep working unchanged.
+ *
+ * Type imported from the new @unclick/wizard package (Phase 1 deliverable).
+ */
+import type { ConversationalCard } from "@unclick/wizard";
+export declare function buildSearchMemoryCard(query: string, results: unknown): ConversationalCard;
+//# sourceMappingURL=search-memory-card.d.ts.map

package/dist/cards/search-memory-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-memory-card.d.ts","sourceRoot":"","sources":["../../src/cards/search-memory-card.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAqB1D,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,kBAAkB,CA6DpB"}

package/dist/cards/search-memory-card.js

@@ -0,0 +1,75 @@
+/**
+ * Phase 1 example wrap. Builds a ConversationalCard summarising a
+ * search_memory result list. Only invoked when the caller opts in via
+ * include_card=true on search_memory; the legacy raw-array response is the
+ * default so existing agents keep working unchanged.
+ *
+ * Type imported from the new @unclick/wizard package (Phase 1 deliverable).
+ */
+const MAX_PREVIEW_RESULTS = 5;
+const MAX_PREVIEW_LENGTH = 140;
+function rowText(row) {
+    const raw = row.fact ?? row.content ?? "";
+    const trimmed = raw.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= MAX_PREVIEW_LENGTH)
+        return trimmed;
+    return `${trimmed.slice(0, MAX_PREVIEW_LENGTH - 1)}…`;
+}
+export function buildSearchMemoryCard(query, results) {
+    const rows = Array.isArray(results) ? results : [];
+    const total = rows.length;
+    const safeQuery = query.trim() || "(empty query)";
+    if (total === 0) {
+        return {
+            title: `No memories found for "${safeQuery}"`,
+            summary: "Memory was searched but nothing matched. Try a broader query or save a new fact if this is novel context.",
+            severity: "info",
+            followUps: [
+                { label: "Refine the search query and try again" },
+                {
+                    label: "Save this as a new fact",
+                    action: {
+                        tool: "save_fact",
+                        args: { fact: "", category: "general" },
+                        confirmation: "confirm",
+                    },
+                },
+            ],
+            meta: { tool: "search_memory", query: safeQuery, result_count: 0 },
+        };
+    }
+    const preview = rows.slice(0, MAX_PREVIEW_RESULTS).map(rowText).filter(Boolean);
+    const shownCount = preview.length;
+    const hiddenCount = Math.max(0, total - shownCount);
+    return {
+        title: `Found ${total} memor${total === 1 ? "y" : "ies"} matching "${safeQuery}"`,
+        summary: hiddenCount > 0
+            ? `Showing the top ${shownCount} of ${total}. The rest are in the raw results payload.`
+            : `Showing all ${total}.`,
+        severity: "success",
+        body: [
+            {
+                kind: "list",
+                heading: "Top matches",
+                items: preview,
+            },
+        ],
+        followUps: [
+            { label: "Refine the search query and try again" },
+            {
+                label: "Save a new fact related to this query",
+                action: {
+                    tool: "save_fact",
+                    args: { fact: "", category: "general" },
+                    confirmation: "confirm",
+                },
+            },
+        ],
+        meta: {
+            tool: "search_memory",
+            query: safeQuery,
+            result_count: total,
+        },
+    };
+}
+//# sourceMappingURL=search-memory-card.js.map

package/dist/cards/search-memory-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-memory-card.js","sourceRoot":"","sources":["../../src/cards/search-memory-card.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAC9B,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAW/B,SAAS,OAAO,CAAC,GAAkB;IACjC,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,IAAI,OAAO,CAAC,MAAM,IAAI,kBAAkB;QAAE,OAAO,OAAO,CAAC;IACzD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,GAAG,CAAC,CAAC,GAAG,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,KAAa,EACb,OAAgB;IAEhB,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,OAA2B,CAAC,CAAC,CAAC,EAAE,CAAC;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;IAC1B,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,EAAE,IAAI,eAAe,CAAC;IAElD,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAChB,OAAO;YACL,KAAK,EAAE,0BAA0B,SAAS,GAAG;YAC7C,OAAO,EACL,2GAA2G;YAC7G,QAAQ,EAAE,MAAM;YAChB,SAAS,EAAE;gBACT,EAAE,KAAK,EAAE,uCAAuC,EAAE;gBAClD;oBACE,KAAK,EAAE,yBAAyB;oBAChC,MAAM,EAAE;wBACN,IAAI,EAAE,WAAW;wBACjB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE;wBACvC,YAAY,EAAE,SAAS;qBACxB;iBACF;aACF;YACD,IAAI,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,EAAE;SACnE,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChF,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAClC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC,CAAC;IAEpD,OAAO;QACL,KAAK,EAAE,SAAS,KAAK,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,cAAc,SAAS,GAAG;QACjF,OAAO,EACL,WAAW,GAAG,CAAC;YACb,CAAC,CAAC,mBAAmB,UAAU,OAAO,KAAK,4CAA4C;YACvF,CAAC,CAAC,eAAe,KAAK,GAAG;QAC7B,QAAQ,EAAE,SAAS;QACnB,IAAI,EAAE;YACJ;gBACE,IAAI,EAAE,MAAM;gBACZ,OAAO,EAAE,aAAa;gBACtB,KAAK,EAAE,OAAO;aACf;SACF;QACD,SAAS,EAAE;YACT,EAAE,KAAK,EAAE,uCAAuC,EAAE;YAClD;gBACE,KAAK,EAAE,uCAAuC;gBAC9C,MAAM,EAAE;oBACN,IAAI,EAAE,WAAW;oBACjB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE;oBACvC,YAAY,EAAE,SAAS;iBACxB;aACF;SACF;QACD,IAAI,EAAE;YACJ,IAAI,EAAE,eAAe;YACrB,KAAK,EAAE,SAAS;YAChB,YAAY,EAAE,KAAK;SACpB;KACF,CAAC;AACJ,CAAC"}

package/dist/cards/search-memory-card.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search-memory-card.test.d.ts.map

package/dist/cards/search-memory-card.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-memory-card.test.d.ts","sourceRoot":"","sources":["../../src/cards/search-memory-card.test.ts"],"names":[],"mappings":""}

package/dist/cards/search-memory-card.test.js

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { buildSearchMemoryCard } from "./search-memory-card.js";
+describe("buildSearchMemoryCard - Phase 1 Wizard wrap", () => {
+    it("renders an empty-state card when no results match", () => {
+        const card = buildSearchMemoryCard("functional programming", []);
+        expect(card.title).toContain("No memories found");
+        expect(card.title).toContain("functional programming");
+        expect(card.severity).toBe("info");
+        expect(card.followUps?.length ?? 0).toBeGreaterThanOrEqual(2);
+        expect(card.meta?.result_count).toBe(0);
+    });
+    it("renders a results card with truncated previews when matches exist", () => {
+        const results = [
+            { id: "1", fact: "Chris prefers TypeScript over JavaScript", confidence: 0.95 },
+            { id: "2", fact: "Chris's timezone is Australia/Melbourne", confidence: 0.9 },
+            { id: "3", fact: "Bailey reviews and merges Phase 1 wizard PRs", confidence: 0.85 },
+        ];
+        const card = buildSearchMemoryCard("Chris", results);
+        expect(card.title).toBe('Found 3 memories matching "Chris"');
+        expect(card.severity).toBe("success");
+        expect(card.body?.[0]?.kind).toBe("list");
+        if (card.body?.[0]?.kind === "list") {
+            expect(card.body[0].items).toHaveLength(3);
+            expect(card.body[0].items[0]).toContain("TypeScript");
+        }
+        expect(card.meta?.result_count).toBe(3);
+    });
+    it("singular wording when exactly one match is returned", () => {
+        const card = buildSearchMemoryCard("timezone", [{ fact: "Australia/Melbourne" }]);
+        expect(card.title).toBe('Found 1 memory matching "timezone"');
+    });
+    it("truncates long fact previews to keep cards renderable", () => {
+        const longFact = "x".repeat(500);
+        const card = buildSearchMemoryCard("noisy", [{ fact: longFact }]);
+        if (card.body?.[0]?.kind === "list") {
+            expect(card.body[0].items[0].length).toBeLessThanOrEqual(140);
+            expect(card.body[0].items[0].endsWith("…")).toBe(true);
+        }
+        else {
+            throw new Error("expected list section");
+        }
+    });
+    it("caps the preview list at five entries even with more matches", () => {
+        const results = Array.from({ length: 12 }, (_, i) => ({ fact: `fact ${i}` }));
+        const card = buildSearchMemoryCard("many", results);
+        expect(card.title).toBe('Found 12 memories matching "many"');
+        expect(card.summary).toContain("Showing the top 5 of 12");
+        if (card.body?.[0]?.kind === "list") {
+            expect(card.body[0].items).toHaveLength(5);
+        }
+    });
+    it("includes a save_fact follow-up wired with confirmation", () => {
+        const card = buildSearchMemoryCard("anything", [{ fact: "x" }]);
+        const saveFollowUp = card.followUps?.find((f) => f.action?.tool === "save_fact");
+        expect(saveFollowUp).toBeDefined();
+        expect(saveFollowUp?.action?.confirmation).toBe("confirm");
+    });
+});
+//# sourceMappingURL=search-memory-card.test.js.map

package/dist/cards/search-memory-card.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-memory-card.test.js","sourceRoot":"","sources":["../../src/cards/search-memory-card.test.ts"],"names":[],"mappings":"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"}

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;IACtB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,UAAU,4FASb,CAAC;AAEX,eAAO,MAAM,OAAO,EAAE,OAAO,EAi1D5B,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,YAAY;UAA2B,OAAO;cAAY,WAAW;EAAK,CAAC;AAOxF,iCAAiC;AACjC,eAAO,MAAM,QAAQ,sBAEpB,CAAC"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;IACtB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,UAAU,4FASb,CAAC;AAEX,eAAO,MAAM,OAAO,EAAE,OAAO,EAulE5B,CAAC;AAEF,qDAAqD;AACrD,eAAO,MAAM,YAAY;UAA2B,OAAO;cAAY,WAAW;EAAK,CAAC;AAOxF,iCAAiC;AACjC,eAAO,MAAM,QAAQ,sBAEpB,CAAC"}