@cachly-dev/mcp-server 0.9.3 → 0.9.5

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
-  "description": "AI memory brain for Claude Code, Cursor, Copilot & Windsurf — persistent sessions, lessons learned, semantic search, Causal Knowledge Graph, team brain. 54 MCP tools.",
+  "description": "Persistent AI memory for Claude Code, Cursor, Copilot & Windsurf — 63 MCP tools. Causal Knowledge Graph, predictive failure detection, continuous learning from git commits + CI, federated knowledge sharing. Your AI learns from every bug fix and never re-researches the same problem.",
   "type": "module",
   "bin": {
     "cachly-mcp": "dist/index.js"
@@ -34,7 +34,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cachly-dev/cachly-mcp.git"
+    "url": "git+https://github.com/cachly-dev/cachly.git"
   },
   "publishConfig": {
     "access": "public",
@@ -51,6 +51,8 @@
     "windsurf",
     "continue",
     "ai-memory",
+    "ai-brain",
+    "persistent-memory",
     "brain",
     "sessions",
     "lessons-learned",
@@ -58,15 +60,22 @@
     "team-knowledge",
     "ambient-git",
     "memory-crystals",
+    "causal-knowledge-graph",
+    "continuous-learning",
+    "predictive-ai",
     "cachly",
     "redis",
     "valkey",
     "cache",
     "ai",
-    "llm"
+    "llm",
+    "knowledge-base",
+    "developer-productivity",
+    "ckg",
+    "mcp-server"
   ],
   "homepage": "https://cachly.dev/docs/mcp",
   "bugs": {
-    "url": "https://github.com/cachly-dev/cachly-mcp/issues"
+    "url": "https://github.com/cachly-dev/cachly/issues"
   }
 }

package/server.json

@@ -1,18 +1,18 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "AI memory brain for Claude Code, Cursor, Copilot & Windsurf — 51 MCP tools. Persistent sessions, lessons learned, semantic search, Team Telepathy, Ambient Git Learning, Memory Crystals.",
+  "description": "Persistent AI memory for Claude Code, Cursor, Copilot & Windsurf. Your AI learns from every bug fix and never re-researches the same problem. 63 MCP tools — Causal Knowledge Graph, predictive failure detection, continuous learning from git commits, federated knowledge sharing.",
   "repository": {
-    "url": "https://github.com/cachly-dev/cachly-mcp",
+    "url": "https://github.com/cachly-dev/cachly",
     "source": "github"
   },
-  "version": "0.8.2",
+  "version": "0.9.5",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.8.2",
+      "version": "0.9.5",
       "transport": {
         "type": "stdio"
       }

package/smithery.yaml

@@ -5,32 +5,32 @@ startCommand:
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Your Cachly API key. Get it free at cachly.dev/setup-ai → Dashboard → API Keys. Looks like: cky_live_..."
+        title: "API Key (optional — sign in via browser on first use)"
+        description: "Leave blank for zero-config: on your first tool call the server opens a browser sign-in (OAuth Device Flow) and auto-provisions your Brain instance. Or pre-fill with your API key from cachly.dev/setup-ai."
         examples:
           - "cky_live_abc123..."
       CACHLY_BRAIN_INSTANCE_ID:
         type: string
-        title: "Brain Instance ID"
-        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"
+        title: "Brain Instance ID (optional)"
+        description: "Only needed if you have multiple Brain instances. Leave blank — the server auto-detects your active instance from the API key."
         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 (optional)"
-        description: "Cachly API endpoint — leave as default unless you self-host"
+        description: "Leave blank unless you self-host Cachly."
         default: "https://api.cachly.dev"
-    required:
-      - CACHLY_JWT
-      - CACHLY_BRAIN_INSTANCE_ID
+    required: []
   commandFunction: |-
     (config) => ({
       command: "npx",
       args: ["-y", "@cachly-dev/mcp-server@latest"],
-      env: {
-        CACHLY_JWT: config.CACHLY_JWT,
-        CACHLY_BRAIN_INSTANCE_ID: config.CACHLY_BRAIN_INSTANCE_ID,
-        CACHLY_API_URL: config.CACHLY_API_URL ?? "https://api.cachly.dev",
-      }
+      env: Object.fromEntries(
+        Object.entries({
+          CACHLY_JWT: config.CACHLY_JWT,
+          CACHLY_BRAIN_INSTANCE_ID: config.CACHLY_BRAIN_INSTANCE_ID,
+          CACHLY_API_URL: config.CACHLY_API_URL ?? "https://api.cachly.dev",
+        }).filter(([, v]) => v != null && v !== "")
+      )
     })

package/src/index.ts

@@ -53,9 +53,128 @@ import { Redis } from 'ioredis';
 // ── Config ────────────────────────────────────────────────────────────────────
 
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
-const JWT = process.env.CACHLY_JWT ?? '';
+let JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.9.3';
+const CURRENT_VERSION = '0.9.5';
+
+// ── Default Instance Resolution (for Smithery & single-credential setups) ────
+// When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
+// When neither is set, we auto-fetch the first running instance once per process.
+let _defaultInstanceId: string = process.env.CACHLY_BRAIN_INSTANCE_ID ?? '';
+let _defaultInstanceFetched = false;
+
+async function resolveDefaultInstanceId(): Promise<string> {
+  if (_defaultInstanceId) return _defaultInstanceId;
+  if (_defaultInstanceFetched) return '';
+  _defaultInstanceFetched = true;
+  if (!JWT) return '';
+  try {
+    const res = await fetch(`${API_URL}/api/v1/instances`, {
+      headers: { Authorization: `Bearer ${JWT}`, Accept: 'application/json' },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return '';
+    const data = await res.json() as { data?: Array<{ id: string; status: string }> };
+    const running = (data?.data ?? []).filter(i => i.status === 'running');
+    if (running.length > 0) { _defaultInstanceId = running[0].id; return _defaultInstanceId; }
+  } catch { /* non-fatal — caller will surface missing instance_id error */ }
+  return '';
+}
+
+// ── Zero-Credential Device Flow (for Smithery & zero-config installs) ─────────
+// When no CACHLY_JWT is set, the server starts an OAuth Device Flow on first tool
+// call. The user visits a short URL, enters a code, and the server polls for the
+// token in the background. After auth, it auto-provisions an instance if needed.
+// State is kept in-memory (works because Smithery keeps one process per session).
+interface DeviceFlowState {
+  deviceCode: string;
+  userCode: string;
+  verifyUrl: string;
+  pollInterval: number; // ms
+  deadline: number;     // epoch ms
+  polling: boolean;
+}
+let _deviceFlow: DeviceFlowState | null = null;
+
+async function startDeviceFlow(): Promise<DeviceFlowState | null> {
+  const AUTH_BASE = 'https://auth.cachly.dev/realms/cachly/protocol/openid-connect';
+  const CLIENT_ID = 'cachly-cli';
+  try {
+    const res = await fetch(`${AUTH_BASE}/auth/device`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: `client_id=${CLIENT_ID}&scope=openid`,
+      signal: AbortSignal.timeout(8000),
+    });
+    if (!res.ok) return null;
+    const data = await res.json() as {
+      device_code: string; user_code: string;
+      verification_uri_complete: string; interval: number;
+    };
+    return {
+      deviceCode: data.device_code,
+      userCode: data.user_code,
+      verifyUrl: data.verification_uri_complete,
+      pollInterval: (data.interval ?? 5) * 1000,
+      deadline: Date.now() + 10 * 60 * 1000, // 10 min
+      polling: false,
+    };
+  } catch { return null; }
+}
+
+async function pollDeviceFlow(flow: DeviceFlowState): Promise<'pending' | 'expired' | 'done'> {
+  if (Date.now() > flow.deadline) return 'expired';
+  const AUTH_BASE = 'https://auth.cachly.dev/realms/cachly/protocol/openid-connect';
+  const CLIENT_ID = 'cachly-cli';
+  try {
+    const res = await fetch(`${AUTH_BASE}/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: `client_id=${CLIENT_ID}&grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=${flow.deviceCode}`,
+      signal: AbortSignal.timeout(8000),
+    });
+    const data = await res.json() as { access_token?: string; error?: string };
+    if (data.access_token) {
+      // Exchange Keycloak JWT → long-lived API key
+      let apiKey = data.access_token;
+      try {
+        const keyRes = await fetch(`${API_URL}/api/v1/api-keys`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+          body: JSON.stringify({ name: 'cachly-mcp-smithery', scope: 'read_write' }),
+          signal: AbortSignal.timeout(8000),
+        });
+        if (keyRes.ok) {
+          const keyBody = await keyRes.json() as { key: string };
+          if (keyBody.key) apiKey = keyBody.key;
+        }
+      } catch { /* use raw JWT as fallback */ }
+      JWT = apiKey;
+      _deviceFlow = null;
+      // Auto-provision instance
+      _defaultInstanceFetched = false;
+      await resolveDefaultInstanceId();
+      if (!_defaultInstanceId) {
+        // Try auto-provision
+        try {
+          const autoRes = await fetch(`${API_URL}/api/v1/instances/auto`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${JWT}`, 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(10000),
+          });
+          if (autoRes.ok) {
+            const body = await autoRes.json() as { instance?: { id: string }; instance_id?: string };
+            const id = body.instance?.id ?? body.instance_id;
+            if (id) _defaultInstanceId = id;
+          }
+        } catch { /* non-fatal */ }
+      }
+      return 'done';
+    }
+    if (data.error === 'slow_down') flow.pollInterval = Math.min(flow.pollInterval + 2000, 15000);
+    return 'pending';
+  } catch { return 'pending'; }
+}
 /**
  * ┌──────────────────────────────────────────────────────────────────────┐
  * │  EMBEDDING PROVIDER — pluggable, client-side first                  │
@@ -3851,26 +3970,71 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
   // Guard: if no JWT, return actionable onboarding message instead of HTTP 401
   if (!JWT) {
     void sendAnonymousTelemetry(name);
+
+    // ── Zero-credential device flow ─────────────────────────────────────
+    // 1st call: start device flow, return code + URL
+    // 2nd+ calls: poll for token; once authenticated, proceed transparently
+    if (_deviceFlow) {
+      const result = await pollDeviceFlow(_deviceFlow);
+      if (result === 'done') {
+        // Auth complete — re-enter handleTool with now-valid JWT
+        return handleTool(name, args);
+      }
+      if (result === 'expired') {
+        _deviceFlow = null;
+        return '⌛ **Authentication timed out.** Please call any tool again to restart the sign-in flow.';
+      }
+      // Still pending
+      return [
+        '⏳ **Waiting for authentication...**',
+        '',
+        `Sign in at: **${_deviceFlow.verifyUrl}**`,
+        `Enter code: **${_deviceFlow.userCode}**`,
+        '',
+        'Once you complete sign-in in your browser, call this tool again and it will proceed automatically.',
+      ].join('\n');
+    }
+
+    // No pending flow — start a new one
+    const flow = await startDeviceFlow();
+    if (flow) {
+      _deviceFlow = flow;
+      return [
+        '🧠 **cachly AI Brain — One-click sign in**',
+        '',
+        '1. Open this URL in your browser (it may open automatically):',
+        `   **${flow.verifyUrl}**`,
+        '',
+        `2. Enter this code if prompted: **${flow.userCode}**`,
+        '',
+        '3. After sign-in, call this tool again — it will proceed automatically.',
+        '',
+        '✨ Free tier includes: 1 Brain instance, persistent memory, 63 MCP tools.',
+        '   No credit card required.',
+      ].join('\n');
+    }
+
+    // Device flow unavailable (network issue) — fall back to manual setup
     return [
       '🧠 **cachly AI Brain — Setup required**',
       '',
-      'You have no API credentials configured. Get started in 30 seconds:',
-      '',
-      '**Step 1:** Register for free (no credit card):',
-      '   👉 https://cachly.dev/setup-ai',
-      '',
-      '**Step 2:** Run the setup wizard in your terminal:',
+      'Run the setup wizard once in your terminal:',
       '   ```',
       '   npx @cachly-dev/mcp-server@latest setup',
       '   ```',
       '',
-      'The wizard auto-detects your editor (Claude Code, Cursor, Copilot, Windsurf)',
-      'and writes the config file with your credentials.',
+      'Or get your API key at: https://cachly.dev/setup-ai',
       '',
       '✨ Free tier includes: 1 Brain instance, persistent memory, semantic search.',
     ].join('\n');
   }
 
+  // Auto-resolve instance_id from env / API when not provided in args
+  if (!args.instance_id) {
+    const defaultId = await resolveDefaultInstanceId();
+    if (defaultId) args = { ...args, instance_id: defaultId };
+  }
+
   // Delegate v0.2 bulk/lock/stream tools first
   const bulkResult = await handleBulkLockStream(name, args);
   if (bulkResult !== null) return bulkResult;