create-merlin-brain 3.4.6 → 3.4.8

package/dist/server/server.js

@@ -6,7 +6,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { getClient } from './api/client.js';
+import { getClient, AuthError } from './api/client.js';
 import { detectRepository } from './utils/git.js';
 import { readMerlinManifest, extractSightId, writeMerlinManifest, buildManifest, injectSightIntoClaudeMd, MERLIN_SIGHTS_BASE } from './utils/merlin-manifest.js';
 import { existsSync, readFileSync } from 'fs';
@@ -152,6 +152,33 @@ export function createServer() {
         }
         return false;
     }
+    // Helper to check if an error is an auth failure and build a graceful response
+    function isAuthError(error) {
+        return error instanceof AuthError;
+    }
+    function buildAuthErrorResponse() {
+        const apiKey = process.env.MERLIN_API_KEY || '';
+        const maskedKey = apiKey.length > 10
+            ? `${apiKey.slice(0, 8)}...${apiKey.slice(-4)} (${apiKey.length} chars)`
+            : apiKey ? '(key too short)' : '(no key set)';
+        let msg = `⚠️ **Authentication Failed**\n\n`;
+        msg += `Your Merlin API key is invalid, expired, or not configured.\n\n`;
+        msg += `**Current key:** ${maskedKey}\n\n`;
+        msg += `**To fix this:**\n\n`;
+        msg += `1. Get a new API key at: **https://merlin.build/settings**\n`;
+        msg += `2. Update your installation:\n`;
+        msg += `   \`\`\`\n   npx create-merlin-brain@latest\n   \`\`\`\n`;
+        msg += `   Or manually edit \`~/.claude/settings.json\` → \`mcpServers.merlin.env.MERLIN_API_KEY\`\n\n`;
+        msg += `3. Restart Claude Code after updating the key.\n\n`;
+        msg += `**Note:** Merlin still works without Sights — agents, workflows, and loop are fully local.\n`;
+        msg += `The API key is only needed for cloud features (codebase context, search, etc.).\n`;
+        return {
+            content: [{
+                    type: 'text',
+                    text: msg,
+                }],
+        };
+    }
     // Helper to build an AGGRESSIVE "repo selector" response
     // This is shown when there's any repo-related error - it MUST be impossible to miss
     async function buildRepoSelectorResponse(options = {}) {
@@ -342,6 +369,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: brief }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             // Check if this is a "repo not found" type error - show the selector!
             if (isRepoNotFoundError(error)) {
                 selectedRepoId = null;
@@ -531,6 +560,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             // Check if this is a "repo not found" type error - show the selector!
             if (isRepoNotFoundError(error)) {
                 // Clear the stale selected repo ID so user can select fresh
@@ -629,6 +660,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: findResult }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             // Check if this is a "repo not found" type error - show the selector!
             if (isRepoNotFoundError(error)) {
                 selectedRepoId = null;
@@ -722,6 +755,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: result }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             // Check if this is a "repo not found" type error - show the selector!
             if (isRepoNotFoundError(error)) {
                 selectedRepoId = null;
@@ -777,6 +812,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: quickstart }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             // Check if this is a "repo not found" type error - show the selector!
             if (isRepoNotFoundError(error)) {
                 selectedRepoId = null;
@@ -826,6 +863,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: results }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             // Check if this is a "repo not found" type error - show the selector!
             if (isRepoNotFoundError(error)) {
                 selectedRepoId = null;
@@ -899,6 +938,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: result }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -987,6 +1028,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1005,56 +1048,31 @@ export function createServer() {
         const maskedKey = apiKey.length > 10
             ? `${apiKey.slice(0, 8)}...${apiKey.slice(-4)} (${apiKey.length} chars)`
             : apiKey ? '(key too short)' : '(no key)';
-        // Get repo root path - CRITICAL for file operations with paths containing spaces
-        const repoRoot = await getRepoRootPath();
-        if (selectedRepoId && selectedRepoName) {
-            // Build Merlin Sights dashboard URL
-            const sightsUrl = `https://merlin.build/sights/${selectedRepoId}`;
-            const stats = getStats();
-            let response = `**🔮 Merlin MCP v${VERSION}**\n\n`;
-            response += `**API Key:** ${maskedKey}\n`;
-            response += `**Connected to:** ${selectedRepoName}\n`;
-            response += `**GitHub:** ${selectedRepoUrl}\n`;
-            response += `**Merlin Sights:** ${sightsUrl}\n`;
-            if (repoRoot) {
-                response += `**Local path:** \`${repoRoot}\`\n`;
-                response += `\n**IMPORTANT for file operations:** Use this full absolute path with Glob tool.\n`;
-                response += `Example: \`Glob(pattern: "**/*.ts", path: "${repoRoot}")\`\n`;
-            }
-            response += `\nAll Merlin queries are using this repository.`;
-            // Add session stats if there have been queries
-            if (stats.queries > 0) {
-                const compactStats = getCompactStats();
-                if (compactStats) {
-                    response += `\n\n${compactStats}`;
-                }
-            }
-            return {
-                content: [{
-                        type: 'text',
-                        text: response,
-                    }],
-            };
-        }
-        // Check if auto-detect would work
-        const detected = await detectRepository();
-        if (detected) {
-            // Cache the root path
-            cachedRepoRootPath = detected.rootDir;
-            const repo = await client.findRepoByUrl(detected.url);
-            if (repo) {
+        try {
+            // Get repo root path - CRITICAL for file operations with paths containing spaces
+            const repoRoot = await getRepoRootPath();
+            if (selectedRepoId && selectedRepoName) {
                 // Build Merlin Sights dashboard URL
-                const sightsUrl = `https://merlin.build/sights/${repo.id}`;
+                const sightsUrl = `https://merlin.build/sights/${selectedRepoId}`;
+                const stats = getStats();
                 let response = `**🔮 Merlin MCP v${VERSION}**\n\n`;
                 response += `**API Key:** ${maskedKey}\n`;
-                response += `Auto-detecting from git remote.\n\n`;
-                response += `**Detected:** ${repo.fullName || repo.name}\n`;
-                response += `**GitHub:** ${repo.url}\n`;
+                response += `**Connected to:** ${selectedRepoName}\n`;
+                response += `**GitHub:** ${selectedRepoUrl}\n`;
                 response += `**Merlin Sights:** ${sightsUrl}\n`;
-                response += `**Local path:** \`${detected.rootDir}\`\n`;
-                response += `\n**IMPORTANT for file operations:** Use this full absolute path with Glob tool.\n`;
-                response += `Example: \`Glob(pattern: "**/*.ts", path: "${detected.rootDir}")\`\n`;
-                response += `\n**Tip:** Use \`merlin_select_repo\` to explicitly select a Sight.`;
+                if (repoRoot) {
+                    response += `**Local path:** \`${repoRoot}\`\n`;
+                    response += `\n**IMPORTANT for file operations:** Use this full absolute path with Glob tool.\n`;
+                    response += `Example: \`Glob(pattern: "**/*.ts", path: "${repoRoot}")\`\n`;
+                }
+                response += `\nAll Merlin queries are using this repository.`;
+                // Add session stats if there have been queries
+                if (stats.queries > 0) {
+                    const compactStats = getCompactStats();
+                    if (compactStats) {
+                        response += `\n\n${compactStats}`;
+                    }
+                }
                 return {
                     content: [{
                             type: 'text',
@@ -1062,35 +1080,80 @@ export function createServer() {
                         }],
                 };
             }
-            // Fallback: Check for .merlin.json before giving up
-            const manifest = readMerlinManifest(detected.rootDir);
-            if (manifest) {
-                const manifestSightId = extractSightId(manifest.sight);
-                if (manifestSightId) {
-                    selectedRepoId = manifestSightId;
-                    selectedRepoUrl = `https://${manifest.repo}`;
-                    selectedRepoName = manifest.repo;
-                    repoIdCache.delete('auto');
-                    console.error(`[merlin] Auto-selected from .merlin.json: ${manifest.repo}`);
-                    const sightsUrl = `https://merlin.build/sights/${manifestSightId}`;
-                    let mResponse = `**🔮 Merlin MCP v${VERSION}**\n\n`;
-                    mResponse += `**API Key:** ${maskedKey}\n`;
-                    mResponse += `🔮 **Auto-connected from .merlin.json**\n\n`;
-                    mResponse += `**Repository:** ${manifest.repo}\n`;
-                    mResponse += `**Merlin Sights:** ${sightsUrl}\n`;
-                    mResponse += `**Local path:** \`${detected.rootDir}\`\n`;
-                    mResponse += `\n**IMPORTANT for file operations:** Use this full absolute path with Glob tool.\n`;
-                    mResponse += `Example: \`Glob(pattern: "**/*.ts", path: "${detected.rootDir}")\`\n`;
+            // Check if auto-detect would work
+            const detected = await detectRepository();
+            if (detected) {
+                // Cache the root path
+                cachedRepoRootPath = detected.rootDir;
+                const repo = await client.findRepoByUrl(detected.url);
+                if (repo) {
+                    // Build Merlin Sights dashboard URL
+                    const sightsUrl = `https://merlin.build/sights/${repo.id}`;
+                    let response = `**🔮 Merlin MCP v${VERSION}**\n\n`;
+                    response += `**API Key:** ${maskedKey}\n`;
+                    response += `Auto-detecting from git remote.\n\n`;
+                    response += `**Detected:** ${repo.fullName || repo.name}\n`;
+                    response += `**GitHub:** ${repo.url}\n`;
+                    response += `**Merlin Sights:** ${sightsUrl}\n`;
+                    response += `**Local path:** \`${detected.rootDir}\`\n`;
+                    response += `\n**IMPORTANT for file operations:** Use this full absolute path with Glob tool.\n`;
+                    response += `Example: \`Glob(pattern: "**/*.ts", path: "${detected.rootDir}")\`\n`;
+                    response += `\n**Tip:** Use \`merlin_select_repo\` to explicitly select a Sight.`;
                     return {
                         content: [{
                                 type: 'text',
-                                text: mResponse,
+                                text: response,
                             }],
                     };
                 }
+                // Fallback: Check for .merlin.json before giving up
+                const manifest = readMerlinManifest(detected.rootDir);
+                if (manifest) {
+                    const manifestSightId = extractSightId(manifest.sight);
+                    if (manifestSightId) {
+                        selectedRepoId = manifestSightId;
+                        selectedRepoUrl = `https://${manifest.repo}`;
+                        selectedRepoName = manifest.repo;
+                        repoIdCache.delete('auto');
+                        console.error(`[merlin] Auto-selected from .merlin.json: ${manifest.repo}`);
+                        const sightsUrl = `https://merlin.build/sights/${manifestSightId}`;
+                        let mResponse = `**🔮 Merlin MCP v${VERSION}**\n\n`;
+                        mResponse += `**API Key:** ${maskedKey}\n`;
+                        mResponse += `🔮 **Auto-connected from .merlin.json**\n\n`;
+                        mResponse += `**Repository:** ${manifest.repo}\n`;
+                        mResponse += `**Merlin Sights:** ${sightsUrl}\n`;
+                        mResponse += `**Local path:** \`${detected.rootDir}\`\n`;
+                        mResponse += `\n**IMPORTANT for file operations:** Use this full absolute path with Glob tool.\n`;
+                        mResponse += `Example: \`Glob(pattern: "**/*.ts", path: "${detected.rootDir}")\`\n`;
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: mResponse,
+                                }],
+                        };
+                    }
+                }
+                // GitHub detected but not in Sights - show available Sights and offer to connect
+                const notFoundResponse = await buildRepoNotFoundResponse(detected.url);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: notFoundResponse,
+                        }],
+                };
             }
-            // GitHub detected but not in Sights - show available Sights and offer to connect
-            const notFoundResponse = await buildRepoNotFoundResponse(detected.url);
+            // Check if we're watching a directory for GitHub connection
+            const config = loadSavedConfig();
+            if (config?.watchingDir) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Watching for GitHub connection.**\n\n**Directory:** ${config.watchingDir}\n\nThis project isn't on GitHub yet. When you add a GitHub remote, Merlin will detect it automatically.\n\n**To connect to GitHub:**\n\`\`\`\ngit remote add origin https://github.com/you/repo\ngit push -u origin main\n\`\`\`\n\nThen restart Claude Code or run \`merlin_get_selected_repo\` again.`,
+                        }],
+                };
+            }
+            // No repo detected at all - show available Sights
+            const notFoundResponse = await buildRepoNotFoundResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1098,24 +1161,13 @@ export function createServer() {
                     }],
             };
         }
-        // Check if we're watching a directory for GitHub connection
-        const config = loadSavedConfig();
-        if (config?.watchingDir) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: `**Watching for GitHub connection.**\n\n**Directory:** ${config.watchingDir}\n\nThis project isn't on GitHub yet. When you add a GitHub remote, Merlin will detect it automatically.\n\n**To connect to GitHub:**\n\`\`\`\ngit remote add origin https://github.com/you/repo\ngit push -u origin main\n\`\`\`\n\nThen restart Claude Code or run \`merlin_get_selected_repo\` again.`,
-                    }],
-            };
+        catch (error) {
+            if (isAuthError(error)) {
+                return buildAuthErrorResponse();
+            }
+            // Re-throw non-auth errors (MCP SDK handles them)
+            throw error;
         }
-        // No repo detected at all - show available Sights
-        const notFoundResponse = await buildRepoNotFoundResponse();
-        return {
-            content: [{
-                    type: 'text',
-                    text: notFoundResponse,
-                }],
-        };
     });
     // Tool: merlin_check_repo_status
     server.tool('merlin_check_repo_status', 'Check if a repository analysis is complete. Use after merlin_connect_repo to poll for completion. Returns status: pending, analyzing, completed, or failed.', {
@@ -1207,6 +1259,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: response }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1379,6 +1433,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1407,6 +1463,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: impact }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1435,6 +1493,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: similar }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1463,6 +1523,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: examples }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1526,6 +1588,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: result }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1585,6 +1649,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1626,6 +1692,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1669,6 +1737,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: response }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1715,6 +1785,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1779,6 +1851,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1839,6 +1913,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: response }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1889,6 +1965,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1938,6 +2016,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: response }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -1994,6 +2074,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -2086,6 +2168,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: response }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -2144,6 +2228,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -2205,6 +2291,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -2251,6 +2339,8 @@ export function createServer() {
             return { content: [{ type: 'text', text: response }] };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',
@@ -2312,6 +2402,8 @@ export function createServer() {
             };
         }
         catch (error) {
+            if (isAuthError(error))
+                return buildAuthErrorResponse();
             return {
                 content: [{
                         type: 'text',