@cachly-dev/mcp-server 0.5.33 → 0.5.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.5.33",
+  "version": "0.5.35",
   "mcpName": "io.github.cachly-dev/mcp-server",
   "description": "AI memory brain for Claude Code, Cursor, Copilot & Windsurf — persistent sessions, lessons learned, semantic search, team brain. 51 MCP tools.",
   "type": "module",

package/smithery.yaml

@@ -5,16 +5,21 @@ startCommand:
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key (JWT)"
-        description: "Your Cachly API key from cachly.dev/dashboard → API Keys"
+        title: "API Key"
+        description: "Your Cachly API key. Get it free at cachly.dev/setup-ai → Dashboard → API Keys. Looks like: cky_live_..."
+        examples:
+          - "cky_live_abc123..."
       CACHLY_BRAIN_INSTANCE_ID:
         type: string
         title: "Brain Instance ID"
-        description: "UUID of your Cachly Brain instance (e.g. 9d4077aa-bfa2-468b-89cd-0a8d8f3ec483)"
+        description: "UUID of your Cachly Brain instance. Find it at cachly.dev/instances — click your instance and copy the ID from the URL or details panel. Looks like: 9d4077aa-bfa2-468b-89cd-0a8d8f3ec483"
+        pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        examples:
+          - "9d4077aa-bfa2-468b-89cd-0a8d8f3ec483"
       CACHLY_API_URL:
         type: string
-        title: "API URL"
-        description: "Cachly API endpoint — leave as default"
+        title: "API URL (optional)"
+        description: "Cachly API endpoint — leave as default unless you self-host"
         default: "https://api.cachly.dev"
     required:
       - CACHLY_JWT

package/src/index.ts

@@ -41,6 +41,7 @@ import { join, relative, extname } from 'node:path';
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import {
   CallToolRequestSchema,
   ErrorCode,
@@ -300,13 +301,15 @@ function embedProviderHint(): string {
 //   • Recency boost — newer entries rank higher (exponential decay, 7-day half-life)
 //   • Multi-query splitting — numbered lists, semicolons, conjunctions
 //   • Fuzzy matching with Levenshtein distance ≤ 2
-//   • Multilingual stopwords (EN, DE, FR, ES, IT, PT)
+//   • Multilingual stopwords (EN, DE, FR, ES, IT, PT, ZH, JA, KO)
+//   • CJK character bigram extraction — handles Chinese, Japanese, Korean
 //   • Pipeline Redis reads for performance
 //
 
 /**
  * Stopwords — filtered out during tokenization.
- * Covers: English, German, French, Spanish, Italian, Portuguese.
+ * Covers: English, German, French, Spanish, Italian, Portuguese,
+ *         Chinese (Simplified + Traditional), Japanese, Korean.
  * Keeps the index small and scores meaningful.
  */
 const STOPWORDS = new Set([
@@ -380,15 +383,63 @@ const STOPWORDS = new Set([
   'eu', 'tu', 'ele', 'ela', 'nós', 'eles', 'elas', 'você', 'vocês',
   'não', 'já', 'sim', 'bem', 'muito', 'também', 'ainda', 'sempre',
   'todo', 'toda', 'todos', 'cada', 'outro', 'outra', 'quando', 'porque',
+  // ── Chinese (Simplified + Traditional) — high-frequency function characters ──
+  '的', '了', '是', '在', '不', '和', '我', '他', '这', '中', '大', '为',
+  '上', '个', '国', '以', '要', '就', '出', '说', '们', '有', '来', '到',
+  '时', '地', '年', '得', '着', '那', '过', '后', '还', '与', '也', '可',
+  '于', '从', '但', '而', '被', '把', '让', '使', '对', '很', '都', '一',
+  '会', '没', '人', '它', '这个', '那个', '什么', '如果', '因为', '所以',
+  '已经', '可以', '这些', '那些', '我们', '他们', '她们', '它们',
+  // ── Japanese — common hiragana particles and auxiliary verbs ──
+  'の', 'は', 'が', 'を', 'に', 'で', 'と', 'も', 'や', 'か', 'な', 'ね',
+  'よ', 'わ', 'て', 'い', 'う', 'え', 'お', 'き', 'く', 'け', 'こ', 'さ',
+  'し', 'す', 'せ', 'そ', 'た', 'ち', 'つ', 'ぬ', 'ん', 'から', 'まで',
+  'より', 'へ', 'です', 'ます', 'ない', 'ある', 'いる', 'する', 'こと',
+  'もの', 'ので', 'では', 'には', 'との', 'への', 'から', 'まで',
+  // ── Korean — common particles and auxiliary forms ──
+  '이', '가', '은', '는', '을', '를', '의', '에', '와', '과', '도',
+  '로', '에서', '한', '하', '있', '없', '것', '수', '않', '들',
+  '이다', '하다', '이고', '이며', '라고', '에게', '에서', '으로',
 ]);
 
-/** Tokenize text into meaningful keywords. Handles unicode (accented chars). */
+// CJK Unicode ranges used for bigram extraction
+const CJK_RE = /[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]/;
+const SEGMENT_RE = /([\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]+|[^\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff\uac00-\ud7af]+)/g;
+
+/**
+ * Tokenize text into meaningful keywords.
+ * Handles accented Latin characters and CJK (Chinese, Japanese, Korean).
+ * CJK text is split into character bigrams (the standard for indexing logographic languages).
+ */
 function tokenize(text: string): string[] {
-  return text
-    .toLowerCase()
-    .replace(/[^a-záàâãäåæçéèêëíìîïñóòôõöúùûüýÿßœ0-9:_\-./]/g, ' ')
-    .split(/\s+/)
-    .filter(w => w.length > 1 && !STOPWORDS.has(w));
+  const tokens: string[] = [];
+  const lower = text.toLowerCase();
+
+  for (const [seg] of lower.matchAll(SEGMENT_RE)) {
+    if (CJK_RE.test(seg)) {
+      // CJK segment — extract overlapping character bigrams
+      for (let i = 0; i < seg.length - 1; i++) {
+        const bigram = seg[i] + seg[i + 1];
+        if (!STOPWORDS.has(seg[i]) && !STOPWORDS.has(bigram)) {
+          tokens.push(bigram);
+        }
+      }
+      // Trailing single character (for 1-char CJK terms)
+      if (seg.length >= 1) {
+        const last = seg[seg.length - 1];
+        if (!STOPWORDS.has(last)) tokens.push(last);
+      }
+    } else {
+      // Latin / other — existing logic
+      const words = seg
+        .replace(/[^a-záàâãäåæçéèêëíìîïñóòôõöúùûüýÿßœ0-9:_\-./]/g, ' ')
+        .split(/\s+/)
+        .filter(w => w.length > 1 && !STOPWORDS.has(w));
+      tokens.push(...words);
+    }
+  }
+
+  return tokens;
 }
 
 /**
@@ -5207,6 +5258,8 @@ const EDITOR_FILES: Record<string, string> = {
   windsurf: '.windsurf/mcp.json',
   copilot:  '.vscode/mcp.json',
   continue: '.continue/config.json',
+  cline:    '.vscode/mcp.json',              // Cline respects VS Code project MCP config
+  zed:      '.zed/settings.json',            // Zed project-level context_servers
 };
 
 const CLAUDE_MD_MARKER_START = '<!-- cachly-brain-start -->';
@@ -5223,6 +5276,20 @@ function buildMcpConfig(apiKey: string, instanceId: string, editor: string): str
       },
     }, null, 2);
   }
+  if (editor === 'zed') {
+    return JSON.stringify({
+      context_servers: {
+        cachly: {
+          command: {
+            path: 'npx',
+            args: ['-y', '@cachly-dev/mcp-server@latest'],
+            env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+          },
+          settings: {},
+        },
+      },
+    }, null, 2);
+  }
   return JSON.stringify({
     mcpServers: {
       cachly: {
@@ -5555,15 +5622,28 @@ if (process.argv[2] === 'setup') {
   // ── Step 3: Detect editors ────────────────────────────────────────────────
   const cwd = process.cwd();
   const detected: string[] = [];
+  const { homedir } = await import('node:os');
+  const home = homedir();
   // Claude Code: always include (CLAUDE.md is universal)
   detected.push('claude');
   if (existsSync(resolve(cwd, '.cursor')))   detected.push('cursor');
   if (existsSync(resolve(cwd, '.windsurf'))) detected.push('windsurf');
   if (existsSync(resolve(cwd, '.vscode')))   detected.push('copilot');
   if (existsSync(resolve(cwd, '.continue'))) detected.push('continue');
+  // Cline: VS Code extension — detect via globalStorage on the machine
+  const clineGlobalDir = process.platform === 'darwin'
+    ? resolve(home, 'Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev')
+    : resolve(home, '.vscode/extensions');
+  if (existsSync(clineGlobalDir) && !detected.includes('copilot')) detected.push('cline');
+  else if (existsSync(clineGlobalDir)) detected.push('cline'); // both copilot + cline share .vscode/mcp.json — fine
+  // Zed editor — detect via app data dir
+  const zedDir = process.platform === 'darwin'
+    ? resolve(home, 'Library/Application Support/Zed')
+    : resolve(home, '.config/zed');
+  if (existsSync(zedDir)) detected.push('zed');
 
   const editorLabel = (e: string) =>
-    ({ claude: 'Claude Code', cursor: 'Cursor', windsurf: 'Windsurf', copilot: 'GitHub Copilot', continue: 'Continue.dev' })[e] ?? e;
+    ({ claude: 'Claude Code', cursor: 'Cursor', windsurf: 'Windsurf', copilot: 'GitHub Copilot', continue: 'Continue.dev', cline: 'Cline (VSCode)', zed: 'Zed' })[e] ?? e;
 
   console.log(`Step 3: Detected editors: ${detected.map(editorLabel).join(', ')}`);
   const editorsRaw = await ask(`   Configure for which? [all / ${detected.join('/')}] (Enter = all): `);
@@ -5603,6 +5683,92 @@ if (process.argv[2] === 'setup') {
   rl.close();
   console.log(`\n🧠  Done! Restart your editor — the \`cachly\` MCP tools will appear.`);
   console.log(`    Your AI now has persistent memory across every session.\n`);
+
+  // ── Step 7: Show first session_start preview (Aha moment) ────────────────
+  // Fetch brain health from the API to show the user what their agent will see.
+  process.stdout.write('\n⏳ Fetching your Brain health preview...');
+  try {
+    const brainRes = await fetch(`${API_URL}/api/v1/instances/${instance.id}/brain/stats`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(6000),
+    });
+    if (brainRes.ok) {
+      const brainData = await brainRes.json() as {
+        lesson_count?: number; context_count?: number;
+        open_failures?: number; quality_score?: number;
+      };
+      const lessons = brainData.lesson_count ?? 0;
+      const contexts = brainData.context_count ?? 0;
+      const score = brainData.quality_score ?? 0;
+      const level = lessons === 0 ? 'Intern 🌱' :
+        lessons < 10  ? 'Junior Dev 🔧' :
+        lessons < 30  ? 'Mid Dev ⚡' :
+        lessons < 60  ? 'Senior Dev 🧠' :
+        lessons < 100 ? 'Staff Eng 🚀' : 'Principal Eng 🏆';
+      console.log(' ✓\n');
+      console.log('┌──────────────────────────────────────────────────────┐');
+      console.log(`│  🧠  Brain Health Report                            │`);
+      console.log('├──────────────────────────────────────────────────────┤');
+      console.log(`│  Lessons stored    : ${String(lessons).padEnd(6)} │  Level: ${level.padEnd(20)}│`);
+      console.log(`│  Context entries   : ${String(contexts).padEnd(6)} │  Quality score: ${String(Math.round(score * 100)).padEnd(3)}%       │`);
+      if (lessons === 0) {
+        console.log('├──────────────────────────────────────────────────────┤');
+        console.log('│  Your Brain is empty and ready to learn.            │');
+        console.log('│  After your first coding session it will contain:   │');
+        console.log('│    • Lessons from every bug you fixed               │');
+        console.log('│    • Your project\'s indexed files                   │');
+        console.log('│    • A session summary for next time                │');
+      }
+      console.log('└──────────────────────────────────────────────────────┘');
+    } else {
+      console.log(' (skipped)');
+    }
+  } catch { console.log(' (skipped)'); }
+
+  console.log(`\n   Your AI will call session_start automatically when it uses the first tool.`);
+  console.log(`   To see your Brain at any time: https://cachly.dev/instances/${instance.id}\n`);
+  process.exit(0);
+}
+
+// ── CLI: cachly index <dir> ───────────────────────────────────────────────────
+// Usage: npx @cachly-dev/mcp-server@latest index [./path/to/project]
+// Indexes the project directory into the Brain — perfect for CI/CD cron jobs.
+
+if (process.argv[2] === 'index') {
+  const { resolve } = await import('node:path');
+  const argv = process.argv.slice(3);
+  const flag = (name: string) => { const i = argv.indexOf(`--${name}`); return i !== -1 ? argv[i + 1] : undefined; };
+
+  const dir        = resolve(flag('dir') ?? argv.find(a => !a.startsWith('--')) ?? '.');
+  const instanceId = flag('instance-id') ?? process.env.CACHLY_BRAIN_INSTANCE_ID;
+  const maxFiles   = parseInt(flag('max-files') ?? '500', 10);
+  const namespace  = flag('namespace') ?? 'cachly:sem:code';
+
+  if (!instanceId || !JWT) {
+    console.error('\n❌  CACHLY_BRAIN_INSTANCE_ID and CACHLY_JWT must be set\n');
+    console.error('   export CACHLY_BRAIN_INSTANCE_ID=<uuid>');
+    console.error('   export CACHLY_JWT=<cky_live_...>');
+    console.error('   npx @cachly-dev/mcp-server@latest index ./my-project\n');
+    process.exit(1);
+  }
+
+  console.log(`\n📂  Indexing: ${dir}`);
+  console.log(`    Instance: ${instanceId.slice(0, 8)}…  Max files: ${maxFiles}\n`);
+
+  try {
+    const result = await handleTool('index_project', {
+      instance_id: instanceId,
+      dir,
+      max_files: maxFiles,
+      ttl: 86400 * 7,
+      namespace,
+    });
+    console.log(result);
+    console.log('\n✅  Indexing complete.\n');
+  } catch (err) {
+    console.error(`\n❌  Indexing failed: ${(err as Error).message}\n`);
+    process.exit(1);
+  }
   process.exit(0);
 }
 
@@ -5655,6 +5821,34 @@ if (!process.env.CACHLY_NO_UPDATE_CHECK) {
   })();
 }
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
+const httpPort = process.env.PORT ? parseInt(process.env.PORT, 10) : undefined;
+
+if (httpPort) {
+  // ── HTTP mode (Streamable HTTP transport) ───────────────────────────────
+  // Used for Smithery URL deployment: PORT=3000 node dist/index.js
+  const { createServer } = await import('node:http');
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  await server.connect(transport);
+  const httpServer = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', `http://localhost:${httpPort}`);
+    if (url.pathname === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: 'ok', version: CURRENT_VERSION }));
+      return;
+    }
+    if (url.pathname === '/mcp' || url.pathname === '/') {
+      transport.handleRequest(req, res);
+      return;
+    }
+    res.writeHead(404);
+    res.end('not found');
+  });
+  httpServer.listen(httpPort, () => {
+    process.stderr.write(`cachly-mcp HTTP server listening on :${httpPort}\n`);
+  });
+} else {
+  // ── stdio mode (default for local editor use) ───────────────────────────
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}