@cachly-dev/mcp-server 0.9.10 → 0.9.12

package/dist/index.js

@@ -2434,7 +2434,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: {
@@ -2447,11 +2451,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)' },
@@ -2499,12 +2507,15 @@ 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'],
         },
@@ -2542,13 +2553,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',
@@ -2680,7 +2695,11 @@ const TOOLS = [
         name: 'cache_mset',
         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: {
@@ -2763,8 +2782,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: {
@@ -3300,9 +3322,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: {
@@ -3336,7 +3361,11 @@ const TOOLS = [
         name: 'publish_lesson',
         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: {
@@ -3633,7 +3662,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: {