@cachly-dev/mcp-server 0.10.76 → 0.10.78

package/dist/src/handlers/share.js

@@ -0,0 +1,256 @@
+import { safeJsonParse } from '../utils.js';
+export const SHARE_TOOL_NAMES = new Set([
+    'brain_share', 'brain_import',
+]);
+async function scanAllLessons(redis, topicFilter) {
+    const keys = [];
+    const stream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+    await new Promise((res, rej) => {
+        stream.on('data', (batch) => keys.push(...batch));
+        stream.on('end', res);
+        stream.on('error', rej);
+    });
+    const lessons = [];
+    for (const key of keys.slice(0, 500)) {
+        const raw = await redis.get(key);
+        if (!raw)
+            continue;
+        const lesson = safeJsonParse(raw, null);
+        if (!lesson || !lesson.topic)
+            continue;
+        if (topicFilter && topicFilter.length > 0) {
+            const matches = topicFilter.some(f => lesson.topic.includes(f));
+            if (!matches)
+                continue;
+        }
+        // Strip fields that should not be shared (internal audit trails, etc.)
+        lessons.push({
+            topic: lesson.topic,
+            outcome: lesson.outcome,
+            ...(lesson.what_worked ? { what_worked: lesson.what_worked } : {}),
+            ...(lesson.what_failed ? { what_failed: lesson.what_failed } : {}),
+            ...(lesson.ctx ? { ctx: lesson.ctx } : {}),
+            ...(lesson.tags?.length ? { tags: lesson.tags } : {}),
+            ...(lesson.author ? { author: lesson.author } : {}),
+            ...(lesson.service ? { service: lesson.service } : {}),
+            confidence: lesson.confidence ?? 1.0,
+            ts: lesson.ts,
+        });
+    }
+    return lessons;
+}
+export async function handleShareTool(name, args, getConnection, apiFetch) {
+    switch (name) {
+        // ── brain_share ────────────────────────────────────────────────────────────
+        case 'brain_share': {
+            const { instance_id, title = 'My Brain Snapshot', description = '', topic_filter, visibility = 'unlisted', max_lessons = 100, dry_run = false, } = args;
+            if (!instance_id)
+                return '⚠️ `brain_share` requires `instance_id`.';
+            const redis = await getConnection(instance_id);
+            const topicFilter = Array.isArray(topic_filter) && topic_filter.length > 0 ? topic_filter : undefined;
+            const allLessons = await scanAllLessons(redis, topicFilter);
+            const lessons = allLessons.slice(0, max_lessons);
+            if (lessons.length === 0) {
+                return [
+                    `📤 **brain_share** — nothing to share yet`,
+                    ``,
+                    `No lessons found in Brain \`${instance_id}\`${topicFilter ? ` matching topics: ${topicFilter.join(', ')}` : ''}.`,
+                    ``,
+                    `Store lessons first with \`learn_from_attempts(topic="...", what_worked="...")\`.`,
+                ].join('\n');
+            }
+            if (dry_run) {
+                const sample = lessons.slice(0, 5).map(l => {
+                    const icon = l.outcome === 'success' ? '✅' : l.outcome === 'failure' ? '❌' : '⚠️';
+                    return `  ${icon} \`${l.topic}\` — ${(l.what_worked ?? l.what_failed ?? '').slice(0, 80)}`;
+                });
+                return [
+                    `📤 **brain_share (DRY RUN)** — would share ${lessons.length} lesson${lessons.length !== 1 ? 's' : ''}`,
+                    ``,
+                    `**Title:** ${title}`,
+                    `**Visibility:** ${visibility}`,
+                    topicFilter ? `**Topic filter:** ${topicFilter.join(', ')}` : '',
+                    ``,
+                    `**Sample lessons (first 5):**`,
+                    ...sample,
+                    lessons.length > 5 ? `  _...and ${lessons.length - 5} more_` : '',
+                    ``,
+                    `_Remove \`dry_run=true\` to create the public share._`,
+                ].filter(l => l !== '').join('\n');
+            }
+            // POST to API
+            let shareId = null;
+            let shareUrl = null;
+            try {
+                const result = await apiFetch('/api/v1/brains/share', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ title, description, visibility, lessons }),
+                });
+                shareId = result.share_id ?? null;
+                if (shareId)
+                    shareUrl = `https://cachly.dev/brain/share/${shareId}`;
+            }
+            catch (e) {
+                // API endpoint may not be live yet — store locally and return JSON
+                const err = e.message ?? '';
+                if (err.includes('404') || err.includes('not found') || err.includes('ECONNREFUSED')) {
+                    const exportJson = JSON.stringify({ title, description, visibility, lessons, exported_at: new Date().toISOString() }, null, 2);
+                    return [
+                        `📤 **brain_share** — exported ${lessons.length} lesson${lessons.length !== 1 ? 's' : ''}`,
+                        ``,
+                        `⚠️ The public share API is not yet available. Here is your portable snapshot:`,
+                        ``,
+                        `\`\`\`json`,
+                        exportJson.slice(0, 3000) + (exportJson.length > 3000 ? '\n... (truncated)' : ''),
+                        `\`\`\``,
+                        ``,
+                        `_To import this on another Brain, use \`brain_import\` with the JSON payload._`,
+                    ].join('\n');
+                }
+                return `❌ brain_share failed: ${e.message}`;
+            }
+            const sample = lessons.slice(0, 5).map(l => {
+                const icon = l.outcome === 'success' ? '✅' : l.outcome === 'failure' ? '❌' : '⚠️';
+                return `  ${icon} \`${l.topic}\``;
+            });
+            // Record provenance
+            try {
+                const prov = JSON.stringify({ share_id: shareId, title, visibility, lesson_count: lessons.length, created_at: new Date().toISOString() });
+                await redis.rpush('cachly:brain:shares', prov);
+                await redis.ltrim('cachly:brain:shares', -20, -1);
+            }
+            catch { /* non-critical */ }
+            return [
+                `📤 **brain_share** — ${lessons.length} lesson${lessons.length !== 1 ? 's' : ''} shared`,
+                ``,
+                `**Share ID:** \`${shareId}\``,
+                `**URL:**      ${shareUrl}`,
+                `**Title:**    ${title}`,
+                `**Visible:**  ${visibility}`,
+                ``,
+                `**Sample lessons:**`,
+                ...sample,
+                lessons.length > 5 ? `  _...and ${lessons.length - 5} more_` : '',
+                ``,
+                `**Anyone can import this Brain with:**`,
+                `\`brain_import(instance_id="<their-id>", share_id="${shareId}")\``,
+                ``,
+                `_To list all your shares, run \`brain_share_list\` (coming soon)._`,
+            ].filter(l => l !== '').join('\n');
+        }
+        // ── brain_import ───────────────────────────────────────────────────────────
+        case 'brain_import': {
+            const { instance_id, share_id, topic_prefix = '', min_confidence = 0.0, dry_run = false, overwrite = false, } = args;
+            if (!instance_id)
+                return '⚠️ `brain_import` requires `instance_id`.';
+            if (!share_id)
+                return '⚠️ `brain_import` requires `share_id`. Get one from `brain_share`.';
+            // Extract share ID from URL if passed as URL
+            const cleanShareId = share_id.replace(/^.*\/brain\/share\//, '').trim();
+            // Fetch the public share
+            let payload;
+            try {
+                payload = await apiFetch(`/api/v1/brains/share/${cleanShareId}`);
+            }
+            catch (e) {
+                const err = e.message ?? '';
+                if (err.includes('404') || err.includes('not found')) {
+                    return [
+                        `❌ **brain_import** — share not found`,
+                        ``,
+                        `Share ID \`${cleanShareId}\` does not exist or has been removed.`,
+                        ``,
+                        `Ask the Brain owner to re-run \`brain_share\` and share the new ID with you.`,
+                    ].join('\n');
+                }
+                return `❌ brain_import failed: ${e.message}`;
+            }
+            const lessons = payload.lessons ?? [];
+            if (lessons.length === 0) {
+                return `⚠️ Share \`${cleanShareId}\` exists but contains no lessons.`;
+            }
+            const redis = await getConnection(instance_id);
+            let imported = 0;
+            let skipped = 0;
+            let conflicts = 0;
+            const importLog = [];
+            for (const lesson of lessons) {
+                if ((lesson.confidence ?? 1.0) < min_confidence) {
+                    skipped++;
+                    continue;
+                }
+                const topic = topic_prefix ? `${topic_prefix}:${lesson.topic}` : lesson.topic;
+                const bestKey = `cachly:lesson:best:${topic}`;
+                // Check for existing lesson
+                if (!overwrite) {
+                    const existing = await redis.get(bestKey);
+                    if (existing) {
+                        conflicts++;
+                        continue;
+                    }
+                }
+                const lessonToStore = JSON.stringify({
+                    ...lesson,
+                    topic,
+                    imported_from: cleanShareId,
+                    imported_at: new Date().toISOString(),
+                });
+                if (!dry_run) {
+                    await redis.set(bestKey, lessonToStore);
+                    const listKey = `cachly:lessons:${topic}`;
+                    await redis.rpush(listKey, lessonToStore);
+                    await redis.ltrim(listKey, -100, -1);
+                    await redis.expire(listKey, 90 * 86400);
+                }
+                imported++;
+                if (importLog.length < 6) {
+                    const icon = lesson.outcome === 'success' ? '✅' : lesson.outcome === 'failure' ? '❌' : '⚠️';
+                    importLog.push(`  ${icon} \`${topic}\` — ${(lesson.what_worked ?? lesson.what_failed ?? '').slice(0, 80)}`);
+                }
+            }
+            // Record import provenance
+            if (!dry_run && imported > 0) {
+                try {
+                    const prov = JSON.stringify({
+                        share_id: cleanShareId, title: payload.title,
+                        imported: imported, skipped, conflicts,
+                        topic_prefix, imported_at: new Date().toISOString(),
+                    });
+                    await redis.rpush('cachly:brain:imports', prov);
+                    await redis.ltrim('cachly:brain:imports', -20, -1);
+                }
+                catch { /* non-critical */ }
+            }
+            const dryTag = dry_run ? ' (DRY RUN — no writes)' : '';
+            const shareTitle = payload.title ?? cleanShareId;
+            const lines = [
+                `📥 **brain_import${dryTag}** — from "${shareTitle}"`,
+                ``,
+                `**Share ID:** \`${cleanShareId}\``,
+                `**Lessons imported:** ${imported}`,
+                ...(skipped > 0 ? [`**Skipped (low confidence):** ${skipped}`] : []),
+                ...(conflicts > 0 ? [`**Skipped (already exist):** ${conflicts}  _(pass \`overwrite=true\` to replace)_`] : []),
+                ``,
+            ];
+            if (importLog.length > 0) {
+                lines.push(`**Sample lessons imported:**`, ...importLog);
+                if (imported > 6)
+                    lines.push(`  _...and ${imported - 6} more_`);
+            }
+            if (imported > 0 && !dry_run) {
+                lines.push(``, `✅ Brain updated — use \`smart_recall(query="...")\` to query the new knowledge.`);
+            }
+            else if (dry_run) {
+                lines.push(``, `_Remove \`dry_run=true\` to actually import these lessons._`);
+            }
+            else if (imported === 0 && conflicts > 0) {
+                lines.push(``, `ℹ️ All lessons already exist in your Brain. Pass \`overwrite=true\` to update them.`);
+            }
+            return lines.join('\n');
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=share.js.map

package/dist/src/handlers/share.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"share.js","sourceRoot":"","sources":["../../../src/handlers/share.ts"],"names":[],"mappings":"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"}

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.76';
+const CURRENT_VERSION = '0.10.78';
 // 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.
@@ -607,6 +609,7 @@ import { handleRoadmapTool } from './handlers/roadmap.js';
 import { handleAdvancedTool } from './handlers/advanced.js';
 import { handleSyndicateTool } from './handlers/syndicate.js';
 import { handleFedbrainTool, _lastBrainFromGitCounts } from './handlers/fedbrain.js';
+import { handleShareTool } from './handlers/share.js';
 // ── Tools (imported from tools.ts) ─────────────────────────────────────────
 import { TOOLS } from './tools.js';
 // ── Handlers ──────────────────────────────────────────────────────────────────
@@ -837,6 +840,9 @@ async function handleTool(name, args) {
         }
         return syndicateResult;
     }
+    const shareResult = await handleShareTool(name, args, getConnection, apiFetch);
+    if (shareResult !== null)
+        return shareResult;
     const fedbrainResult = await handleFedbrainTool(name, args, getConnection, apiFetch);
     if (fedbrainResult !== null) {
         // brain_from_git and brain_predict_failures are in fedbrain handler.
@@ -1110,13 +1116,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 +1147,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 +1159,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 +1170,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 +1577,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 +1944,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 +1970,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 +2134,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 +2158,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 +2306,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) {
@@ -2295,6 +2350,13 @@ if (process.argv[2] === 'setup') {
     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):
@@ -2656,7 +2718,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)`);
@@ -2932,37 +2994,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 {