@cachly-dev/mcp-server 0.10.75 → 0.10.77

package/dist/src/index.js

@@ -60,10 +60,12 @@ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { Redis } from 'ioredis';
 // ── Config ────────────────────────────────────────────────────────────────────
-const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
+// Mutable so the `setup`/`init` CLI can honor a `--api-url` flag for self-hosting.
+// Reassigned (if at all) before any network call is made.
+let API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const _EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.10.75';
+const CURRENT_VERSION = '0.10.77';
 // Max time to wait for a freshly-provisioned instance to become "running" before
 // giving up. Free-tier provisioning in high-latency regions can take 45–90s, so the
 // old hard-coded 25s caused spurious "instance_not_reachable" on first run.
@@ -1110,13 +1112,26 @@ const EDITOR_FILES = {
 };
 const CLAUDE_MD_MARKER_START = '<!-- cachly-brain-start -->';
 const CLAUDE_MD_MARKER_END = '<!-- cachly-brain-end -->';
+const DEFAULT_API_URL = 'https://api.cachly.dev';
+// Build the env block written into an editor's MCP config. Self-hosting is
+// first-class: if the operator runs setup/init against their own backend
+// (CACHLY_API_URL set to a non-default URL), that URL is baked into the config so
+// the editor-launched server talks to the self-hosted instance — not api.cachly.dev.
+// For the default cloud backend we OMIT CACHLY_API_URL to keep configs clean (the
+// binary already defaults to it).
+function buildServerEnv(apiKey, instanceId) {
+    const env = { CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId };
+    if (API_URL && API_URL !== DEFAULT_API_URL)
+        env.CACHLY_API_URL = API_URL;
+    return env;
+}
 function buildMcpConfig(apiKey, instanceId, editor) {
     if (editor === 'continue') {
         return JSON.stringify({
             experimental: {
                 modelContextProtocolServers: [{
                         transport: { type: 'stdio', command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'] },
-                        env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+                        env: buildServerEnv(apiKey, instanceId),
                     }],
             },
         }, null, 2);
@@ -1128,7 +1143,7 @@ function buildMcpConfig(apiKey, instanceId, editor) {
                     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 },
+                        env: buildServerEnv(apiKey, instanceId),
                     },
                     settings: {},
                 },
@@ -1140,7 +1155,7 @@ function buildMcpConfig(apiKey, instanceId, editor) {
             cachly: {
                 command: 'npx',
                 args: ['-y', '@cachly-dev/mcp-server@latest'],
-                env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+                env: buildServerEnv(apiKey, instanceId),
             },
         },
     }, null, 2);
@@ -1151,7 +1166,7 @@ async function mergeMcpConfig(configPath, apiKey, instanceId, editor, fsOps) {
     const cachlyEntry = {
         command: 'npx',
         args: ['-y', '@cachly-dev/mcp-server@latest'],
-        env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: apiKey, CACHLY_BRAIN_INSTANCE_ID: instanceId },
+        env: buildServerEnv(apiKey, instanceId),
     };
     if (!fsOps.existsSync(configPath))
         return buildMcpConfig(apiKey, instanceId, editor);
@@ -1558,7 +1573,9 @@ if (process.argv[2] === 'join') {
             env['CACHLY_BRAIN_INSTANCE_ID'] = instance_id;
             if (joinJwt && !env['CACHLY_JWT'])
                 env['CACHLY_JWT'] = joinJwt;
-            env['CACHLY_API_URL'] ??= 'https://api.cachly.dev';
+            // Only persist a self-hosted backend URL; leave default-cloud configs clean.
+            if (API_URL !== DEFAULT_API_URL)
+                env['CACHLY_API_URL'] = API_URL;
             servers['cachly'] = { ...existing, command: 'npx', args: ['-y', '@cachly-dev/mcp-server@latest'], env };
             cfg['mcpServers'] = servers;
             await wfJ(ePath, JSON.stringify(cfg, null, 2), 'utf-8');
@@ -1923,6 +1940,11 @@ if (process.argv[2] === 'init') {
     let apiKey = flag('api-key') ?? process.env.CACHLY_JWT;
     const editor = (flag('editor') ?? 'claude').toLowerCase();
     const projectDir = resolve(flag('project-dir') ?? '.');
+    // Self-hosting: --api-url overrides the backend baked into the written config.
+    const apiUrlFlag = flag('api-url');
+    if (apiUrlFlag) {
+        API_URL = apiUrlFlag.replace(/\/+$/, '');
+    }
     // Zero-arg path: fall back to credentials saved by a previous `setup`
     // (~/.claude/mcp.json). Makes `init` a fast, idempotent re-configuration command
     // you can run in any project without copy-pasting tokens.
@@ -1944,7 +1966,7 @@ if (process.argv[2] === 'init') {
         catch { /* fall through to the usage error below */ }
     }
     if (!instanceId || !apiKey) {
-        console.error('\nUsage: npx @cachly-dev/mcp-server@latest init --instance-id <uuid> --api-key <cky_live_...> [--editor claude|cursor|windsurf|copilot|continue] [--project-dir /path]\n');
+        console.error('\nUsage: npx @cachly-dev/mcp-server@latest init --instance-id <uuid> --api-key <cky_live_...> [--editor claude|cursor|windsurf|copilot|continue] [--project-dir /path] [--api-url https://your-self-hosted-backend]\n');
         console.error('First time? Run the zero-config wizard (signs you in, auto-provisions): npx @cachly-dev/mcp-server@latest setup\n');
         console.error('Get your credentials from: https://cachly.dev/setup-ai\n');
         process.exit(1);
@@ -2108,6 +2130,11 @@ if (process.argv[2] === 'health') {
     if (!jwt) {
         fail('CACHLY_JWT not set — run: npx @cachly-dev/mcp-server@latest setup');
     }
+    else if (jwt.startsWith('cky_')) {
+        // Long-lived API key (the credential `setup` provisions). It is not a JWT and
+        // never expires client-side — treat a well-formed key as healthy.
+        ok('Long-lived API key set (cky_…) — no client-side expiry');
+    }
     else {
         try {
             const parts = jwt.split('.');
@@ -2127,7 +2154,7 @@ if (process.argv[2] === 'health') {
             }
         }
         catch {
-            fail('CACHLY_JWT format invalid (expected JWT with 3 parts)');
+            fail('CACHLY_JWT format invalid (expected a cky_ API key or a 3-part JWT)');
         }
     }
     // ── 2. Brain API reachability ───────────────────────────────────────────────
@@ -2275,6 +2302,30 @@ if (process.argv[2] === 'health') {
     else {
         warn('.git/hooks/post-commit not found — run: npx @cachly-dev/mcp-server@latest setup');
     }
+    // ── 6. Embedding provider (BYOK) ─────────────────────────────────────────────
+    console.log('\n🧬 Embedding provider (semantic search)');
+    {
+        const providerKeys = [
+            ['OPENAI_API_KEY', 'openai'], ['GEMINI_API_KEY', 'gemini'],
+            ['MISTRAL_API_KEY', 'mistral'], ['COHERE_API_KEY', 'cohere'],
+            ['OLLAMA_BASE_URL', 'ollama'],
+        ];
+        const explicit = (process.env.CACHLY_EMBED_PROVIDER ?? '').toLowerCase();
+        const byok = providerKeys.find(([envVar]) => process.env[envVar]);
+        if (explicit && explicit !== 'cachly') {
+            const envVar = providerKeys.find(([, p]) => p === explicit)?.[0];
+            if (envVar && process.env[envVar])
+                ok(`BYOK: ${explicit} (key present in ${envVar})`);
+            else
+                warn(`CACHLY_EMBED_PROVIDER=${explicit} but its key env var is not set — semantic search will fail`);
+        }
+        else if (byok) {
+            ok(`BYOK: ${byok[1]} auto-detected (${byok[0]} present)`);
+        }
+        else {
+            ok('Server-side embeddings (cachly) — no key needed, uses your JWT');
+        }
+    }
     // ── Summary ─────────────────────────────────────────────────────────────────
     console.log(`\n${'─'.repeat(40)}`);
     if (failed === 0) {
@@ -2294,6 +2345,14 @@ if (process.argv[2] === 'setup') {
     const { existsSync } = await import('node:fs');
     const { resolve, dirname } = await import('node:path');
     const { createInterface } = await import('node:readline');
+    const setupStartMs = Date.now();
+    // Self-hosting: `setup --api-url https://cachly.mycorp.internal` points the whole
+    // wizard (auth, provisioning, config writes) at a private backend.
+    const _apiUrlIdx = process.argv.indexOf('--api-url');
+    if (_apiUrlIdx !== -1 && process.argv[_apiUrlIdx + 1]) {
+        API_URL = process.argv[_apiUrlIdx + 1].replace(/\/+$/, '');
+        console.log(`ℹ️  Using self-hosted backend: ${API_URL}\n`);
+    }
     sendFunnelEvent('setup_started');
     // --yes / -y → non-interactive mode (skips all prompts, picks defaults).
     // Also auto-detect a non-interactive stdin (VSCode tasks, CI, piped input):
@@ -2655,7 +2714,7 @@ if (process.argv[2] === 'setup') {
         globalConfig.mcpServers['cachly'] = {
             command: 'npx',
             args: ['-y', '@cachly-dev/mcp-server@latest'],
-            env: { CACHLY_API_URL: 'https://api.cachly.dev', CACHLY_JWT: token, CACHLY_BRAIN_INSTANCE_ID: instance.id },
+            env: buildServerEnv(token, instance.id),
         };
         await writeFile(globalClaudePath, JSON.stringify(globalConfig, null, 2), 'utf-8');
         console.log(`✅ Written: ~/.claude/mcp.json  (global — works in every project)`);
@@ -2843,7 +2902,13 @@ if (process.argv[2] === 'setup') {
     catch { /* non-critical */ }
     // Setup reached the end successfully — close the funnel.
     JWT = token;
-    sendFunnelEvent('setup_completed', { instance_id: instance.id });
+    const setupElapsedS = Math.round((Date.now() - setupStartMs) / 1000);
+    sendFunnelEvent('setup_completed', { instance_id: instance.id, elapsed_s: setupElapsedS });
+    console.log('\n╔══════════════════════════════════════════════════════╗');
+    console.log('║  🚀  Brain is ready.                                 ║');
+    console.log(`║  ⏱️   Setup completed in ${String(setupElapsedS + 's').padEnd(5)} — restart your editor  ║`);
+    console.log('║      and your AI arrives pre-briefed every session.  ║');
+    console.log('╚══════════════════════════════════════════════════════╝\n');
     rl.close();
     // Give the fire-and-forget telemetry a moment to flush before exit.
     await new Promise(r => setTimeout(r, 300));
@@ -2925,37 +2990,45 @@ if (process.argv[2] === 'learn-git') {
     process.exit(0);
 }
 // ── Start ─────────────────────────────────────────────────────────────────────
-// Warn on stderr when credentials are missing so the user sees a clear
-// actionable message in their editor's MCP log instead of silent failures.
-// Skip for CLI commands that intentionally run without credentials.
+// Credential-missing handling at startup. The critical distinction is HOW we were
+// launched, because writing anything to stdout in stdio-MCP mode corrupts the
+// JSON-RPC stream and exiting kills the zero-credential device-flow onboarding.
+//   • Human in a real terminal (TTY), no args  → show the setup banner, exit 0.
+//   • Editor as an MCP stdio server (non-TTY)  → ONE stderr hint, then KEEP RUNNING
+//     so tools/list works and the first tool call starts the browser sign-in.
+// Skip entirely for CLI subcommands that intentionally run without credentials.
 const _cliNoAuthCommands = ['demo', 'share', 'health', 'setup', 'init', 'digest', 'invite', 'badge', 'join', 'upgrade'];
-if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '') && !(!process.argv[2] && process.stdout.isTTY)) {
-    // No args + no JWT in a non-TTY context = running as MCP server without credentials.
-    // Print actionable setup banner to stdout so it's captured by callers/tests.
-    const banner = '\n' +
-        '╔══════════════════════════════════════════════════════════════════╗\n' +
-        '║  🧠  cachly AI Brain — Setup required                           ║\n' +
-        '╠══════════════════════════════════════════════════════════════════╣\n' +
-        '║                                                                  ║\n' +
-        '║  CACHLY_JWT is not set. Get your free credentials at:           ║\n' +
-        '║                                                                  ║\n' +
-        '║    👉  https://cachly.dev/setup-ai                              ║\n' +
-        '║                                                                  ║\n' +
-        '║  Then run the interactive setup wizard:                         ║\n' +
-        '║                                                                  ║\n' +
-        '║    npx @cachly-dev/mcp-server@latest setup                      ║\n' +
-        '║                                                                  ║\n' +
-        '║  Free tier — no credit card required.                           ║\n' +
-        '╚══════════════════════════════════════════════════════════════════╝\n' +
-        '\n';
-    // When invoked with no args as the main entry point, write to stdout + exit cleanly.
-    // When used as MCP server (args present), write to stderr so editors see it.
-    if (!process.argv[2] && _isMain) {
+if (!JWT && !_cliNoAuthCommands.includes(process.argv[2] ?? '')) {
+    const runningInTerminal = !process.argv[2] && process.stdout.isTTY === true && _isMain;
+    if (runningInTerminal) {
+        // A human ran `npx @cachly-dev/mcp-server` directly with no credentials.
+        // Show them how to set up, then exit cleanly.
+        const banner = '\n' +
+            '╔══════════════════════════════════════════════════════════════════╗\n' +
+            '║  🧠  cachly AI Brain — Setup required                           ║\n' +
+            '╠══════════════════════════════════════════════════════════════════╣\n' +
+            '║                                                                  ║\n' +
+            '║  CACHLY_JWT is not set. Get your free credentials at:           ║\n' +
+            '║                                                                  ║\n' +
+            '║    👉  https://cachly.dev/setup-ai                              ║\n' +
+            '║                                                                  ║\n' +
+            '║  Then run the interactive setup wizard:                         ║\n' +
+            '║                                                                  ║\n' +
+            '║    npx @cachly-dev/mcp-server@latest setup                      ║\n' +
+            '║                                                                  ║\n' +
+            '║  Free tier — no credit card required.                           ║\n' +
+            '╚══════════════════════════════════════════════════════════════════╝\n' +
+            '\n';
         process.stdout.write(banner);
         process.exit(0);
     }
     else {
-        process.stderr.write(banner);
+        // Launched as an MCP stdio server (or HTTP) without credentials. NEVER touch
+        // stdout here — it carries the JSON-RPC protocol. Emit a single actionable
+        // hint to stderr (shown in the editor's MCP log) and fall through so the
+        // server starts and the zero-credential device flow can run on first tool call.
+        process.stderr.write('\n🧠 cachly: no CACHLY_JWT set yet — call any cachly tool and a 10-second browser sign-in starts automatically.\n' +
+            '   (Or run once: npx @cachly-dev/mcp-server@latest setup)\n\n');
     }
 }
 else {