@cachly-dev/mcp-server 0.9.4 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
   "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",

package/server.json

@@ -6,13 +6,13 @@
     "url": "https://github.com/cachly-dev/cachly",
     "source": "github"
   },
-  "version": "0.9.4",
+  "version": "0.9.5",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.9.4",
+      "version": "0.9.5",
       "transport": {
         "type": "stdio"
       }

package/smithery.yaml

@@ -5,24 +5,23 @@ startCommand:
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Your Cachly API key (free, no credit card). Get it at cachly.dev/setup-ai → Dashboard → API Keys. Looks like: cky_live_... The server auto-detects your Brain instance from this key."
+        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 (optional)"
-        description: "UUID of your Brain instance — only needed if you have multiple instances. Leave blank and the server auto-picks your active instance. Find the ID at cachly.dev/instances."
+        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 blank unless you self-host"
+        description: "Leave blank unless you self-host Cachly."
         default: "https://api.cachly.dev"
-    required:
-      - CACHLY_JWT
+    required: []
   commandFunction: |-
     (config) => ({
       command: "npx",

package/src/index.ts

@@ -53,9 +53,9 @@ 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.4';
+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.
@@ -80,6 +80,101 @@ async function resolveDefaultInstanceId(): Promise<string> {
   } 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                  │
@@ -3875,21 +3970,60 @@ 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');