@cachly-dev/mcp-server 0.9.10 → 0.9.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
   "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 63 MCP tools · Claude Code · Cursor · GitHub Copilot · Windsurf · Free tier · EU servers.",
   "type": "module",

package/src/index.ts

@@ -2486,7 +2486,11 @@ const TOOLS = [
     name: 'cache_get',
     description:
       'Get a value from a running cache instance by key. ' +
-      'Returns the value (string or JSON) or null if the key does not exist.',
+      'Returns the stored value (string or deserialized JSON object) or null if the key does not exist or has expired. ' +
+      'Read-only — no side effects. ' +
+      'Use cache_mget when you need multiple keys in one round-trip. ' +
+      'Use cache_exists to check existence without retrieving the value. ' +
+      'Use semantic_search when you need fuzzy/vector search across stored values.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -2500,11 +2504,15 @@ const TOOLS = [
     name: 'cache_set',
     description:
       'Set a key-value pair in a running cache instance. ' +
-      'Value can be a string or a JSON-serialized object. Optionally set a TTL in seconds.',
+      'Overwrites any existing value at the key — not idempotent for new data. ' +
+      'Returns "OK" on success; returns an error if the instance_id is invalid or the instance is paused. ' +
+      'Value can be a string or a JSON-serialized object. Optionally set a TTL in seconds (omit for no expiry). ' +
+      'Use cache_mset instead for setting multiple keys in a single pipeline round-trip. ' +
+      'Use cache_stream_set instead for caching LLM token streams (ordered string chunks).',
     inputSchema: {
       type: 'object',
       properties: {
-        instance_id: { type: 'string' },
+        instance_id: { type: 'string', description: 'UUID of the cache instance (from list_instances)' },
         key: { type: 'string', description: 'Cache key' },
         value: { type: 'string', description: 'Value to store (string or JSON)' },
         ttl: { type: 'number', description: 'Time-to-live in seconds (optional, omit for no expiry)' },
@@ -2554,12 +2562,16 @@ const TOOLS = [
   },
   {
     name: 'cache_ttl',
-    description: 'Get the remaining time-to-live (TTL) of a key in seconds. Returns -1 if no TTL, -2 if the key does not exist.',
+    description:
+      'Get the remaining time-to-live (TTL) of a key in seconds. ' +
+      'Returns -1 if the key exists but has no expiry, -2 if the key does not exist. ' +
+      'Read-only — no side effects. ' +
+      'Use cache_set with a ttl parameter to set or update the expiry.',
     inputSchema: {
       type: 'object',
       properties: {
-        instance_id: { type: 'string' },
-        key: { type: 'string' },
+        instance_id: { type: 'string', description: 'UUID of the cache instance (from list_instances)' },
+        key: { type: 'string', description: 'Cache key to inspect' },
       },
       required: ['instance_id', 'key'],
     },
@@ -2600,13 +2612,17 @@ const TOOLS = [
     name: 'semantic_search',
     description:
       'Find cached entries that are semantically similar to a natural-language query. ' +
-      'Powered by pgvector HNSW index on cachly infrastructure — embeddings never leave Germany. ' +
-      'Requires OPENAI_API_KEY (or compatible) and the Speed/Business tier with CACHLY_VECTOR_URL. ' +
-      'Example: "find all cached responses about password reset" or "what did we answer about pricing?"',
+      'Read-only — no side effects. ' +
+      'Returns an array of objects, each with: key, value, similarity_score (0–1), and namespace. ' +
+      'Returns an empty array if no entries meet the similarity threshold. ' +
+      'Requires OPENAI_API_KEY (or compatible provider) and the Speed/Business tier with CACHLY_VECTOR_URL. ' +
+      'Embeddings are computed server-side and never leave Germany (pgvector HNSW index). ' +
+      'Example: "find all cached responses about password reset" or "what did we answer about pricing?". ' +
+      'Use cache_get for exact key lookup; use smart_recall for brain lessons.',
     inputSchema: {
       type: 'object',
       properties: {
-        instance_id: { type: 'string' },
+        instance_id: { type: 'string', description: 'UUID of the cache instance (from list_instances)' },
         query: { type: 'string', description: 'Natural-language query to find similar cached content' },
         threshold: {
           type: 'number',
@@ -2745,7 +2761,11 @@ const TOOLS = [
     description:
       'Set multiple key-value pairs in a single pipeline round-trip. ' +
       'Supports per-key TTL – unlike native MSET. ' +
-      'Uses one TCP round-trip for N keys via Redis pipeline.',
+      'Uses one TCP round-trip for N keys via Redis pipeline. ' +
+      'Each item overwrites any existing value for that key. ' +
+      'On partial failure the successfully pipelined keys are committed; a per-key error list is returned for any that failed. ' +
+      'Returns a summary: { set: N, errors: [...] }. ' +
+      'Use cache_set for a single key; use cache_stream_set for large streaming payloads.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -2833,8 +2853,11 @@ const TOOLS = [
       'Perfect for caching: codebase overviews, file summaries, project structure, ' +
       'frequently-accessed data, or "thinking" results like dependency analysis. ' +
       'The AI assistant can use this to avoid re-reading the entire codebase every time. ' +
+      'Overwrites any existing value stored under the same key. ' +
+      'Returns { key, stored_at, ttl } confirming the saved context. ' +
       'Example: remember_context("project overview", "This is a Next.js app with...") ' +
-      'then later: recall_context("project overview")',
+      'then later: recall_context("project overview"). ' +
+      'Use recall_context to retrieve; use list_remembered to see all stored keys.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -3392,9 +3415,12 @@ const TOOLS = [
     name: 'global_learn',
     description:
       'Store a lesson that applies across ALL your projects (cross-project knowledge). ' +
+      'Idempotent: if a lesson with the same topic already exists, it is updated in place — no duplicates are created. ' +
+      'Returns a confirmation with the stored lesson key. No rate limits. ' +
       'Global lessons are stored with the prefix cachly:global:lesson: and recalled from any instance via global_recall. ' +
       'Use for tool preferences, personal workflows, platform quirks, and universal gotchas. ' +
-      'Example: global_learn(topic="bash:macos-arrays", lesson="Arrays work differently on macOS bash 3.2")',
+      'Example: global_learn(topic="bash:macos-arrays", lesson="Arrays work differently on macOS bash 3.2"). ' +
+      'Use learn_from_attempts for project-specific session lessons; use team_learn to share lessons with your team.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -3430,7 +3456,11 @@ const TOOLS = [
     description:
       'Publish a lesson to the Cachly Public Brain (anonymized community knowledge base). ' +
       'Published lessons can be imported by other developers via import_public_brain. ' +
-      'PII is stripped automatically. Visible under the framework/category tag.',
+      'PII is stripped automatically. Visible under the framework/category tag. ' +
+      'Returns { lesson_id, topic, framework, published_at } confirming the publish. ' +
+      'Irreversible — once published to the public brain, lessons cannot be deleted via the MCP interface. ' +
+      'Use learn_from_attempts or global_learn for private lessons; ' +
+      'use syndicate for anonymized global sharing without framework tagging.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -3746,7 +3776,10 @@ const TOOLS = [
       'This is how individual knowledge becomes collective intelligence. ' +
       'Call this AFTER every learn_from_attempts that is worth sharing universally ' +
       '(critical bugs, deployment gotchas, architecture discoveries). ' +
-      'Use scope="org" to keep the lesson private to your organisation.',
+      'If a lesson with the same topic already exists in the commons, it is updated in place (idempotent). ' +
+      'Returns { key, confirm_count, scope } confirming the stored lesson. ' +
+      'Use scope="org" to keep the lesson private to your organisation. ' +
+      'Do NOT use for secrets or PII — content is stored in a shared knowledge base.',
     inputSchema: {
       type: 'object',
       properties: {