@unclick/mcp-server 0.2.5 → 0.3.0

package/README.md

@@ -1,139 +1,139 @@
-# @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.**
+
+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

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"}

package/dist/catalog.js

@@ -1852,6 +1852,267 @@ export const CATALOG = [
             },
         ],
     },
+    // ─── MEMORY (persistent cross-session memory) ────────────────────────
+    // Handled by the local memory module — no HTTP call is made. The 5 most
+    // important tools (get_startup_context, write_session_summary, add_fact,
+    // search_memory, set_business_context) are also registered as direct
+    // MCP tools so agents discover the session protocol.
+    {
+        slug: "memory",
+        name: "UnClick Memory",
+        description: "Persistent cross-session memory for AI agents. 6-layer architecture: business context, knowledge library, session summaries, extracted facts, conversation log, code dumps. Zero-config local mode or Supabase cloud sync.",
+        category: "storage",
+        scope: "memory:use",
+        endpoints: [
+            {
+                id: "memory.get_startup_context",
+                name: "Get Startup Context",
+                description: "Load business context, recent sessions, and hot facts. Call FIRST in every new session.",
+                method: "POST",
+                path: "/v1/memory/startup",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: { num_sessions: { type: "number", minimum: 1, maximum: 20, default: 5 } },
+                },
+            },
+            {
+                id: "memory.search_memory",
+                name: "Search Memory",
+                description: "Full-text search across conversation logs.",
+                method: "POST",
+                path: "/v1/memory/search",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string" },
+                        max_results: { type: "number", minimum: 1, maximum: 50, default: 10 },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                id: "memory.search_facts",
+                name: "Search Facts",
+                description: "Search active (non-superseded) extracted facts.",
+                method: "POST",
+                path: "/v1/memory/facts/search",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: { query: { type: "string" } },
+                    required: ["query"],
+                },
+            },
+            {
+                id: "memory.search_library",
+                name: "Search Library",
+                description: "Search versioned reference documents in the Knowledge Library.",
+                method: "POST",
+                path: "/v1/memory/library/search",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: { query: { type: "string" } },
+                    required: ["query"],
+                },
+            },
+            {
+                id: "memory.get_library_doc",
+                name: "Get Library Doc",
+                description: "Get the full content of a library doc by slug.",
+                method: "POST",
+                path: "/v1/memory/library/get",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: { slug: { type: "string" } },
+                    required: ["slug"],
+                },
+            },
+            {
+                id: "memory.list_library",
+                name: "List Library",
+                description: "List all documents in the Knowledge Library.",
+                method: "POST",
+                path: "/v1/memory/library/list",
+                requiresAuth: false,
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                id: "memory.write_session_summary",
+                name: "Write Session Summary",
+                description: "Save an end-of-session summary. Call BEFORE session ends.",
+                method: "POST",
+                path: "/v1/memory/session/write",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string" },
+                        summary: { type: "string" },
+                        topics: { type: "array", items: { type: "string" } },
+                        open_loops: { type: "array", items: { type: "string" } },
+                        decisions: { type: "array", items: { type: "string" } },
+                        platform: { type: "string", default: "claude-code" },
+                        duration_minutes: { type: "number" },
+                    },
+                    required: ["session_id", "summary"],
+                },
+            },
+            {
+                id: "memory.add_fact",
+                name: "Add Fact",
+                description: "Add an atomic fact. One fact = one statement.",
+                method: "POST",
+                path: "/v1/memory/facts/add",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        fact: { type: "string" },
+                        category: { type: "string", default: "general" },
+                        confidence: { type: "number", minimum: 0, maximum: 1, default: 0.9 },
+                        source_session_id: { type: "string" },
+                    },
+                    required: ["fact"],
+                },
+            },
+            {
+                id: "memory.supersede_fact",
+                name: "Supersede Fact",
+                description: "Replace an outdated fact with a new version (old one marked superseded, never deleted).",
+                method: "POST",
+                path: "/v1/memory/facts/supersede",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        old_fact_id: { type: "string" },
+                        new_fact_text: { type: "string" },
+                        new_category: { type: "string" },
+                        new_confidence: { type: "number", minimum: 0, maximum: 1 },
+                    },
+                    required: ["old_fact_id", "new_fact_text"],
+                },
+            },
+            {
+                id: "memory.log_conversation",
+                name: "Log Conversation",
+                description: "Log a conversation exchange for later search.",
+                method: "POST",
+                path: "/v1/memory/conversation/log",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string" },
+                        role: { type: "string", enum: ["user", "assistant", "system", "tool"] },
+                        content: { type: "string" },
+                        has_code: { type: "boolean", default: false },
+                    },
+                    required: ["session_id", "role", "content"],
+                },
+            },
+            {
+                id: "memory.get_conversation_detail",
+                name: "Get Conversation Detail",
+                description: "Retrieve the full conversation log for a session.",
+                method: "POST",
+                path: "/v1/memory/conversation/get",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: { session_id: { type: "string" } },
+                    required: ["session_id"],
+                },
+            },
+            {
+                id: "memory.store_code",
+                name: "Store Code",
+                description: "Store a code block in the code dump layer.",
+                method: "POST",
+                path: "/v1/memory/code/store",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        session_id: { type: "string" },
+                        language: { type: "string", default: "typescript" },
+                        filename: { type: "string" },
+                        code: { type: "string" },
+                        description: { type: "string" },
+                    },
+                    required: ["session_id", "code"],
+                },
+            },
+            {
+                id: "memory.get_business_context",
+                name: "Get Business Context",
+                description: "Get all business context entries (standing rules).",
+                method: "POST",
+                path: "/v1/memory/context/get",
+                requiresAuth: false,
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                id: "memory.set_business_context",
+                name: "Set Business Context",
+                description: "Add or update a business context entry (always loaded at session start).",
+                method: "POST",
+                path: "/v1/memory/context/set",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        category: { type: "string" },
+                        key: { type: "string" },
+                        value: { type: "string" },
+                        priority: { type: "number" },
+                    },
+                    required: ["category", "key", "value"],
+                },
+            },
+            {
+                id: "memory.upsert_library_doc",
+                name: "Upsert Library Doc",
+                description: "Create or update a Knowledge Library document (auto-versioned).",
+                method: "POST",
+                path: "/v1/memory/library/upsert",
+                requiresAuth: false,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        slug: { type: "string" },
+                        title: { type: "string" },
+                        category: { type: "string", default: "reference" },
+                        content: { type: "string" },
+                        tags: { type: "array", items: { type: "string" } },
+                    },
+                    required: ["slug", "title", "content"],
+                },
+            },
+            {
+                id: "memory.manage_decay",
+                name: "Manage Decay",
+                description: "Run the memory decay manager. Promotes/demotes items between hot/warm/cold tiers.",
+                method: "POST",
+                path: "/v1/memory/decay",
+                requiresAuth: false,
+                inputSchema: { type: "object", properties: {} },
+            },
+            {
+                id: "memory.memory_status",
+                name: "Memory Status",
+                description: "Get memory usage stats: storage mode, counts per layer, decay tier distribution.",
+                method: "POST",
+                path: "/v1/memory/status",
+                requiresAuth: false,
+                inputSchema: { type: "object", properties: {} },
+            },
+        ],
+    },
 ];
 /** Flat map of all endpoints keyed by endpoint id */
 export const ENDPOINT_MAP = new Map();