@cachly-dev/mcp-server 0.5.2 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "MCP server – manage cachly.dev instances from any AI assistant (Copilot, Claude, Cursor, Windsurf)",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "main": "./dist/index.js",
   "scripts": {
     "build": "tsc",
+    "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "test": "vitest run",

package/scripts/postinstall.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// Shown once after: npm install @cachly-dev/mcp-server
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  violet: "\x1b[35m",
+  green: "\x1b[32m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+const line = `${c.dim}─────────────────────────────────────────────────────${c.reset}`;
+
+console.log(`
+${line}
+  ${c.bold}${c.violet}🧠 Cachly Brain MCP Server${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
+
+  ${c.bold}Give your AI assistant persistent memory in 30 seconds:${c.reset}
+
+  ${c.cyan}1.${c.reset} Get a free Brain instance at ${c.bold}cachly.dev/setup-ai${c.reset}
+  ${c.cyan}2.${c.reset} Add to Claude Code / Cursor / Copilot:
+     ${c.dim}npx @cachly-dev/mcp-server --key cky_live_... --instance <uuid>${c.reset}
+
+  ${c.green}✅ Free tier · GDPR · German servers · No credit card${c.reset}
+
+${line}`);

package/src/index.ts

@@ -4114,8 +4114,75 @@ const server = new Server(
 
 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: string | null = null;
+let _autoSessionStarted = false;
+let _autoSessionToolCount = 0;
+
+async function autoStartSession(instanceId: string): Promise<void> {
+  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(): Promise<void> {
+  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 as Record<string, unknown>)?.instance_id as string | undefined;
+    if (instanceId) {
+      await autoStartSession(instanceId).catch(() => undefined);
+    }
+  }
+  if (!sessionTools.has(name)) _autoSessionToolCount++;
+
   try {
     const text = await handleTool(name, (args ?? {}) as Record<string, unknown>);
     return { content: [{ type: 'text', text }] };
@@ -4125,8 +4192,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
-// 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);
 });
@@ -4179,26 +4253,26 @@ function buildClaudeMdBlock(instanceId: string): string {
 ## 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}",
@@ -4209,9 +4283,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}`;
 }