@cachly-dev/mcp-server 0.5.2 → 0.5.4

package/README.md

@@ -1,124 +1,94 @@
-# cachly MCP Server
+# Your AI Assistant Has Amnesia. cachly Fixes That.
 
-> Manage your [cachly.dev](https://cachly.dev) cache instances directly from **GitHub Copilot, Claude, Cursor, Windsurf** and any other MCP-compatible AI assistant.
+> **cachly MCP Server** — Give GitHub Copilot, Claude Code, Cursor, and Windsurf a persistent brain that remembers every lesson, every decision, every bug you've ever fixed.
 
-## 🚀 Zero-Touch Setup — One Command
+[![npm](https://img.shields.io/npm/v/@cachly-dev/mcp-server?color=red&logo=npm)](https://www.npmjs.com/package/@cachly-dev/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+[![GDPR: EU-only](https://img.shields.io/badge/GDPR-EU%20only-green)](https://cachly.dev/legal)
 
-Stop your AI from re-reading your entire codebase every time. One command enables **context memory** and configures all your editors automatically:
+---
 
-```bash
-CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
-```
+## The Pain
 
-The interactive wizard will:
-1. Authenticate with your cachly account (or prompt for JWT)
-2. Let you pick which cache instance to use as your AI Brain
-3. **Auto-detect** Cursor, Windsurf, VS Code, Claude Code, and Continue.dev
-4. Write the correct MCP config for every detected editor
-5. Create/update `CLAUDE.md` (idempotent — safe to re-run)
+Every morning, you open your AI coding assistant. It doesn't remember yesterday. You explain your architecture. You explain the deployment process. You explain the bug you fixed last week. You paste the same context files over and over.
 
-**Result:** 60% fewer file reads, instant context across sessions, zero re-discovery.
+**The average developer wastes 45 minutes per day on context re-establishment.** That's €15,000+ in lost productivity per engineer per year.
 
-### Non-interactive (CI / scripted setup)
+---
+
+## The Fix — One Command
 
 ```bash
-CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server init \
-  --instance-id your-instance-id \
-  --editor vscode
+CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
 ```
 
-## What you can do
+The wizard:
+1. Authenticates with your cachly account
+2. Lets you pick which instance to use as your AI Brain
+3. **Auto-detects** Cursor, Windsurf, VS Code, Claude Code, Continue.dev
+4. Writes the correct MCP config for every detected editor
+5. Creates `CLAUDE.md` / `.github/copilot-instructions.md` with the memory rules
 
-Once connected, just talk to your AI assistant:
+**Result:** Your AI assistant remembers everything. Always.
 
-```
-"Create a free cachly instance called my-app-cache"
-"List all my cache instances"
-"Get the connection string for instance abc-123"
-"Delete my test-cache instance"
-```
+---
+
+## With vs. Without cachly Brain
+
+| Situation | Without cachly | With cachly |
+|-----------|----------------|-------------|
+| Session start | "What's your architecture?" | "Ready. 23 lessons, last session: deployed API." |
+| Known bug hits again | Re-researches from scratch | "You fixed this on March 12, here's the exact command" |
+| After holiday / team handoff | Context dead | Fully briefed in < 10 seconds |
+| Repeated LLM patterns | Pays for each re-discovery | Recalls from cache, ~1,200 tokens saved per hit |
+| Architecture decisions | Lost in chat history | Permanently stored, searchable |
+| New team member | Weeks to onboard | Session start gives full context instantly |
+
+---
 
-## Available Tools
+## How It Works
 
-### 🧠 AI Brain — Session & Memory
+The MCP server gives your AI 30+ tools backed by your cachly Valkey instance:
 
-| Tool | Description |
-|---|---|
-| **`session_start`** | Single call returning full briefing: last session, relevant lessons, open failures, brain health. Call at the start of every session. |
-| **`session_end`** | Save session summary, files changed, duration. Call at the end of every session. |
-| **`learn_from_attempts`** | Store structured lessons after any bug fix or deploy. Supports severity, file_paths, commands, tags. Deduplicates by topic. |
+### 🧠 Session & Memory
+| Tool | What it does |
+|------|-------------|
+| **`session_start`** | Full briefing: last session, lessons, open failures, brain health. Call at the start of every session. |
+| **`session_end`** | Save summary, files changed, duration. Auto-extracts lessons. |
+| **`learn_from_attempts`** | Store structured lessons after any fix or deploy. Deduplicates by topic. |
 | **`recall_best_solution`** | Retrieve the best known solution for a topic (increments recall count). |
-| **`remember_context`** | Cache any analysis or architecture finding for future sessions. |
-| **`recall_context`** | Retrieve cached context by exact key (supports glob: `"file:*"`). |
-| **`smart_recall`** | BM25+ keyword search across all cached context. Works **without any embedding provider**. Optionally adds semantic vector search if an API key is configured. |
-| **`list_remembered`** | List all cached context entries. |
-| **`forget_context`** | Delete stale context. |
+| **`remember_context`** | Cache architecture findings, decisions, file summaries. |
+| **`smart_recall`** | BM25+ search across all brain data — no embedding needed. |
 
 ### ⚙️ Instance Management
-
-| Tool | Description |
-|---|---|
+| Tool | What it does |
+|------|-------------|
 | `list_instances` | List all your cache instances |
-| `create_instance` | Create a new instance (free or paid tier) |
-| `get_instance` | Get details for a specific instance |
-| `get_connection_string` | Get the `redis://` connection URL |
-| `delete_instance` | Permanently delete an instance |
+| `create_instance` | Spin up a new instance (free or paid) |
+| `get_connection_string` | Get the `redis://` URL |
+| `delete_instance` | Remove an instance |
 
 ### 🗄️ Cache Operations
-
-| Tool | Description |
-|---|---|
+| Tool | What it does |
+|------|-------------|
 | `cache_get` / `cache_set` / `cache_delete` | Live cache operations |
-| `cache_exists` / `cache_ttl` / `cache_keys` | Key inspection |
-| `cache_stats` | Memory, hit rate, ops/sec |
 | `cache_mget` / `cache_mset` | Bulk pipeline operations |
-| `cache_lock_acquire` / `cache_lock_release` | Distributed locks (Redlock-lite) |
+| `cache_lock_acquire` / `cache_lock_release` | Distributed locks |
 | `cache_stream_set` / `cache_stream_get` | LLM token streaming cache |
+| `cache_stats` | Memory, hit rate, ops/sec |
 
 ### 🔍 Semantic & AI
+| Tool | What it does |
+|------|-------------|
+| `semantic_search` | Find cached entries by meaning (requires embedding provider) |
+| `cache_warmup` | Pre-warm the cache with prompt/response pairs |
+| `detect_namespace` | Classify a prompt into semantic namespace |
 
-| Tool | Description |
-|---|---|
-| `semantic_search` | Vector similarity search (Speed/Business tier) |
-| `detect_namespace` | Auto-classify prompt into semantic namespace |
-| `cache_warmup` | Pre-warm semantic cache with known Q&A pairs |
-| `index_project` | Index local source files for AI semantic search |
-| `get_api_status` | Check API health + JWT auth info |
-
-## Setup
-
-### Recommended: Zero-Touch via npx
-
-```bash
-CACHLY_JWT=your-jwt npx @cachly-dev/mcp-server setup
-```
-
-No install, no build step. The wizard auto-detects your editors and writes all config files.
-
-### Manual configuration
-
-Get your JWT token at **[cachly.dev/settings](https://cachly.dev/settings)** → API Tokens.
-
-#### Claude Code / Claude Desktop
-
-```json
-{
-  "mcpServers": {
-    "cachly": {
-      "command": "npx",
-      "args": ["-y", "@cachly-dev/mcp-server"],
-      "env": { "CACHLY_JWT": "your-jwt-token-here" }
-    }
-  }
-}
-```
-
-- **Claude Code:** add to `.claude/mcp.json` in your project
-- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
+---
 
-#### GitHub Copilot (VS Code)
+## Manual Setup (without wizard)
 
-Add to `.vscode/mcp.json`:
+Add to `~/.vscode/mcp.json`, `.cursor/mcp.json`, or `.mcp.json`:
 
 ```json
 {
@@ -127,189 +97,39 @@ Add to `.vscode/mcp.json`:
       "type": "stdio",
       "command": "npx",
       "args": ["-y", "@cachly-dev/mcp-server"],
-      "env": { "CACHLY_JWT": "your-jwt-token-here" }
+      "env": { "CACHLY_JWT": "your-jwt-token" }
     }
   }
 }
 ```
 
-Then: **Ctrl/Cmd+Shift+P → "MCP: List Servers"** → start `cachly`.
-
-#### Cursor
-
-Add to `.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "cachly": {
-      "command": "npx",
-      "args": ["-y", "@cachly-dev/mcp-server"],
-      "env": { "CACHLY_JWT": "your-jwt-token-here" }
-    }
-  }
-}
-```
-
-#### Windsurf / Continue.dev
-
-Same `stdio`/`mcpServers` format — add to their respective MCP config file.
-
-## Environment Variables
-
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| `CACHLY_JWT` | ✅ | – | Your Keycloak JWT from cachly.dev/settings |
-| `CACHLY_API_URL` | ❌ | `https://api.cachly.dev` | Override for local dev |
-
-## Example Session
-
-```
-User: Create a free cache instance for my OpenAI project
-
-Copilot: I'll create a free cachly instance for you.
-[calls create_instance(name="openai-cache", tier="free")]
-
-✅ Instance **openai-cache** (FREE) created and provisioning started!
-   ID: `a1b2c3d4-...`
-   Status: provisioning
-
-Use `get_connection_string` to get your Redis URL in ~30 seconds.
-
-User: Get the connection string
-
-Copilot: [calls get_connection_string(instance_id="a1b2c3d4-...")]
-
-Connection string for openai-cache:
-  redis://:password@my-node.cachly.dev:30101
-
-Environment variable:
-  REDIS_URL="redis://:password@my-node.cachly.dev:30101"
-```
-
-## Local Development
-
-```bash
-# Run against local API
-CACHLY_JWT=your-token CACHLY_API_URL=http://localhost:3001 npm run dev
+Add to `CLAUDE.md` / `.github/copilot-instructions.md`:
+```markdown
+## AI Brain Rules (cachly)
+- Call session_start BEFORE reading any files or making changes
+- Call learn_from_attempts AFTER every fix, deploy, or discovery
+- Call session_end when closing the window
 ```
 
 ---
 
-## Real-World Use Cases
-
-### 🧠 Stop Re-Reading Your Codebase — "Thinking Cache"
-
-**The Problem:** Every time you ask Copilot about your codebase, it runs "Ich verschaffe mir einen Überblick über die Codebasis" and re-reads hundreds of files.
-
-**The Solution:** Cache your AI's "thinking" results:
-
-```
-You: "Analyze the authentication architecture"
-AI:  [reads 47 files, takes 30 seconds]
-     The auth uses Keycloak with JWT tokens. The flow is:
-     1. User hits /sign-in → NextAuth redirect
-     2. Keycloak validates credentials
-     3. JWT returned, stored in session
-     
-     [calls remember_context("auth_architecture", "The auth uses Keycloak...")]
-     🧠 Context saved for future sessions.
-
---- Next day, new session ---
-
-You: "How does auth work?"
-AI:  [calls smart_recall("auth")]
-     🧠 Found cached context:
-     The auth uses Keycloak with JWT tokens...
-     
-     (No file reading needed — instant answer!)
-```
-
-The `setup` wizard (see top of this README) writes the session instructions automatically into your `CLAUDE.md` / `.github/copilot-instructions.md` — **no manual editing needed.** Just run `npx @cachly-dev/mcp-server setup` once and your AI assistant calls `session_start` at the start of every session automatically.
-
-### 1. AI-Assisted Development — "Which caches am I using?"
+## Pricing
 
-You're building a microservice that uses multiple cachly instances. Ask your AI assistant directly:
+| Tier | RAM | Price | Best for |
+|------|-----|-------|----------|
+| **Free** | 25 MB | €0/mo | Dev & side projects |
+| **Dev** | 200 MB | €9/mo | Individual developers |
+| **Pro** | 900 MB | €29/mo | Teams |
+| **Speed** | 900 MB Dragonfly + Semantic Cache | €79/mo | AI-heavy workloads |
+| **Business** | 7 GB | €199/mo | Scale-ups |
 
-```
-You: "List all my cachly instances and their status"
-AI:  Using cachly_list_instances...
-     
-     You have 3 instances:
-     1. prod-api (Pro, running) — redis://:***@prod.cachly.dev:30101
-     2. staging (Dev, running) — redis://:***@staging.cachly.dev:30102  
-     3. ml-pipeline (Speed, running) — redis://:***@ml.cachly.dev:30103
-     
-     Total MRR: €72/month
-```
-
-### 2. Cache Debugging — "Why is my hit rate dropping?"
-
-Your semantic cache hit rate dropped overnight. Debug it without leaving your editor:
-
-```
-You: "Check the analytics for my prod-api instance"
-AI:  Using cachly_semantic_stats...
-     
-     ⚠️ Hit rate dropped 23% in the last 24h (82% → 63%)
-     
-     Anomaly detected: near-miss spike (+140%)
-     → 47 queries are hitting similarity 0.80-0.84 (just below your 0.85 threshold)
-     
-     Recommendation: Lower threshold to 0.82 to capture these near-misses.
-     
-You: "Do it"
-AI:  Using cachly_set_threshold... ✅ Threshold set to 0.82 for namespace cachly:sem
-```
-
-### 3. Deployment Cache Warmup — "Pre-fill the cache for the new release"
-
-After deploying a new version, warm the semantic cache with common queries:
-
-```
-You: "Warm up the staging cache with our top 50 support questions"
-AI:  Using cachly_batch_index with your FAQ embeddings...
-     
-     ✅ Indexed 50 entries in 340ms (batch pipeline)
-     Namespace: cachly:sem:qa
-     
-     Your cache is ready — first users will get instant responses.
-```
-
-### 4. Cost Monitoring — "How much am I saving?"
-
-Track your LLM cost savings directly in your IDE:
-
-```
-You: "How much has cachly saved me this month?"
-AI:  Using cachly_semantic_stats...
-     
-     📊 This month's savings:
-     - Total cache hits: 12,847
-     - Estimated savings: $384.21 (vs. direct LLM calls)
-     - Efficiency score: 84/100 (Grade: A)
-     - Best namespace: cachly:sem:qa (94% hit rate)
-```
-
-### 5. CI Pipeline Integration — "Check cache health before deploy"
-
-Add cache health checks to your deployment workflow:
-
-```
-You: "Check if any cache anomalies would block a deploy"
-AI:  Using cachly_analytics_anomalies...
-     
-     ✅ No critical anomalies detected.
-     1 info-level notice: stale cache in namespace "translations" 
-     (12 near-misses/24h, 0 new entries)
-     
-     Recommendation: Run warmup after deploy for translations namespace.
-     Deploy is safe to proceed.
-```
+All plans: **German servers · GDPR-compliant · No US data transfer · 99.9% SLA**
 
 ---
 
-## License
-
-MIT © [cachly.dev](https://cachly.dev)
+## Links
 
+- [cachly.dev](https://cachly.dev) — Dashboard & free signup
+- [AI Brain docs](https://cachly.dev/docs/ai-memory) — Full documentation
+- [npm](https://www.npmjs.com/package/@cachly-dev/mcp-server) — Package
+- [GitHub](https://github.com/cachly-dev/mcp-server)

package/dist/index.js

@@ -3606,8 +3606,74 @@ async function handleBulkLockStream(name, args) {
 // ── Server setup ──────────────────────────────────────────────────────────────
 const server = new Server({ name: 'cachly-mcp', version: '0.4.0' }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+// ── Auto-session management ───────────────────────────────────────────────────
+// Transparently starts a Brain session on the first tool call of a process
+// and saves a session_end summary on SIGTERM/exit so users never have to call
+// session_start/session_end manually.
+let _autoSessionInstanceId = null;
+let _autoSessionStarted = false;
+let _autoSessionToolCount = 0;
+async function autoStartSession(instanceId) {
+    if (_autoSessionStarted)
+        return;
+    _autoSessionStarted = true;
+    _autoSessionInstanceId = instanceId;
+    try {
+        await handleTool('session_start', { instance_id: instanceId, focus: 'auto (MCP session)' });
+    }
+    catch { /* non-fatal — session tracking is a best-effort feature */ }
+    // Auto-index the project if it hasn't been indexed in the last 24h.
+    // This is the main lever for growing token savings: more indexed code →
+    // more semantic cache hits → fewer LLM calls for repeated questions.
+    if (process.env.CACHLY_AUTO_INDEX !== 'false') {
+        try {
+            const redis = await getConnection(instanceId);
+            const lastIndexed = await redis.get(`cachly:index:last_indexed:${instanceId}`);
+            const staleMs = 24 * 60 * 60 * 1000;
+            const isStale = !lastIndexed || (Date.now() - parseInt(lastIndexed, 10)) > staleMs;
+            if (isStale) {
+                // Mark as indexing now to prevent concurrent re-runs.
+                await redis.set(`cachly:index:last_indexed:${instanceId}`, String(Date.now()), 'EX', 90000);
+                // Run in background — don't block the first tool call.
+                handleTool('index_project', {
+                    instance_id: instanceId,
+                    dir: process.cwd(),
+                    max_files: 150,
+                    ttl: 86400 * 7, // cache for 7 days
+                    namespace: 'cachly:sem:code',
+                }).catch(() => undefined);
+            }
+        }
+        catch { /* never block the session on indexing errors */ }
+    }
+}
+async function autoEndSession() {
+    if (!_autoSessionStarted || !_autoSessionInstanceId)
+        return;
+    _autoSessionStarted = false;
+    try {
+        await handleTool('session_end', {
+            instance_id: _autoSessionInstanceId,
+            summary: `Auto-ended after ${_autoSessionToolCount} tool call(s). Session was started automatically.`,
+            files_changed: [],
+            lessons_learned: 0,
+        });
+    }
+    catch { /* non-fatal */ }
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    // Auto-start brain session on first tool call that has an instance_id.
+    // Skip session management tools to avoid recursion.
+    const sessionTools = new Set(['session_start', 'session_end', 'auto_learn_session']);
+    if (!sessionTools.has(name) && !_autoSessionStarted) {
+        const instanceId = args?.instance_id;
+        if (instanceId) {
+            await autoStartSession(instanceId).catch(() => undefined);
+        }
+    }
+    if (!sessionTools.has(name))
+        _autoSessionToolCount++;
     try {
         const text = await handleTool(name, (args ?? {}));
         return { content: [{ type: 'text', text }] };
@@ -3618,8 +3684,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new McpError(ErrorCode.InternalError, err.message);
     }
 });
-// Graceful shutdown – close all Redis connections
+// Graceful shutdown – close all Redis connections + auto-end brain session
 process.on('SIGTERM', async () => {
+    await autoEndSession().catch(() => undefined);
+    for (const [, client] of pool)
+        await client.quit().catch(() => undefined);
+    process.exit(0);
+});
+process.on('SIGINT', async () => {
+    await autoEndSession().catch(() => undefined);
     for (const [, client] of pool)
         await client.quit().catch(() => undefined);
     process.exit(0);
@@ -3667,26 +3740,26 @@ function buildClaudeMdBlock(instanceId) {
 ## Cachly AI Brain
 
 The Cachly MCP server is available as tool \`cachly\`.
+Your instance ID: \`${instanceId}\`
 
-### At the START of every session (one call):
-\`\`\`
-session_start(
-  instance_id = "${instanceId}",
-  focus       = "<what you plan to work on today>",
-)
-\`\`\`
+> **Sessions are fully automatic** (MCP ≥ 0.5.3).
+> The Brain starts tracking when you call any tool for the first time and saves a summary when your editor closes. You never need to call \`session_start\` or \`session_end\` manually.
+
+---
 
-### At the END of every session:
+### Before editing any file — WIP-registry (prevents half-finished code across sessions):
 \`\`\`
-session_end(
-  instance_id     = "${instanceId}",
-  summary         = "What was accomplished (2-3 sentences)",
-  files_changed   = ["src/..."],
-  lessons_learned = 1,
+remember_context(
+  instance_id = "${instanceId}",
+  key         = "wip-registry",
+  content     = "EDITING: <file:line> — goal: <what you are implementing>",
+  category    = "bug",
+  ttl         = 86400,
 )
 \`\`\`
+After the edit is complete, update \`content\` to \`"DONE: <file> — <what was completed>"\`.
 
-### After fixing any bug or learning something new:
+### After fixing any bug or solving a tricky problem:
 \`\`\`
 learn_from_attempts(
   instance_id = "${instanceId}",
@@ -3697,9 +3770,21 @@ learn_from_attempts(
   severity    = "critical" | "major" | "minor",
   file_paths  = ["path/to/file"],
   commands    = ["the command that worked"],
-  tags        = ["tag1", "tag2"],
+  tags        = ["tag1"],
+)
+\`\`\`
+
+### Before starting any task — recall relevant lessons first:
+\`\`\`
+smart_recall(
+  instance_id = "${instanceId}",
+  query       = "<describe what you are about to do>",
 )
 \`\`\`
+
+### Half-finished code rule:
+Never commit code that does not compile. Run \`tsc --noEmit\` / \`go build ./...\` before every commit.
+If a session ends mid-task, save the WIP-registry entry so the next session picks up exactly where you left off.
 ${CLAUDE_MD_MARKER_END}`;
 }
 async function writeClaudeMd(projectDir, instanceId) {