codeseeker 1.4.4 → 1.7.0

package/dist/mcp/mcp-server.js

@@ -66,6 +66,7 @@ const semantic_search_orchestrator_1 = require("../cli/commands/services/semanti
 const indexing_service_1 = require("./indexing-service");
 const coding_standards_generator_1 = require("../cli/services/analysis/coding-standards-generator");
 const language_support_service_1 = require("../cli/services/project/language-support-service");
+const query_cache_service_1 = require("./query-cache-service");
 // Version from package.json
 const VERSION = '2.0.0';
 /**
@@ -76,6 +77,25 @@ class CodeSeekerMcpServer {
     searchOrchestrator;
     indexingService;
     languageSupportService;
+    queryCache;
+    // Background indexing state
+    indexingJobs = new Map();
+    // Mutex for concurrent indexing protection
+    indexingMutex = new Set();
+    // Cancellation tokens for running indexing jobs
+    cancellationTokens = new Map();
+    // Job cleanup interval (clean completed/failed jobs after 1 hour)
+    JOB_TTL_MS = 60 * 60 * 1000; // 1 hour
+    cleanupTimer = null;
+    // Dangerous paths that should never be indexed (security)
+    DANGEROUS_PATHS = [
+        // System directories
+        '/etc', '/var', '/usr', '/bin', '/sbin', '/lib', '/boot', '/root', '/proc', '/sys', '/dev',
+        // Windows system directories
+        'C:\\Windows', 'C:\\Program Files', 'C:\\Program Files (x86)', 'C:\\ProgramData',
+        // User sensitive directories
+        '.ssh', '.gnupg', '.aws', '.azure', '.config',
+    ];
     constructor() {
         this.server = new mcp_js_1.McpServer({
             name: 'codeseeker',
@@ -84,7 +104,191 @@ class CodeSeekerMcpServer {
         this.searchOrchestrator = new semantic_search_orchestrator_1.SemanticSearchOrchestrator();
         this.indexingService = new indexing_service_1.IndexingService();
         this.languageSupportService = new language_support_service_1.LanguageSupportService();
+        this.queryCache = (0, query_cache_service_1.getQueryCacheService)();
         this.registerTools();
+        // Start cleanup timer for old indexing jobs
+        this.startJobCleanupTimer();
+    }
+    /**
+     * Start periodic cleanup of completed/failed indexing jobs
+     */
+    startJobCleanupTimer() {
+        // Clean up every 10 minutes
+        this.cleanupTimer = setInterval(() => {
+            this.cleanupOldJobs();
+        }, 10 * 60 * 1000);
+        // Ensure timer doesn't prevent process exit
+        if (this.cleanupTimer.unref) {
+            this.cleanupTimer.unref();
+        }
+    }
+    /**
+     * Clean up completed/failed jobs older than TTL
+     */
+    cleanupOldJobs() {
+        const now = Date.now();
+        const jobsToDelete = [];
+        for (const [projectId, job] of this.indexingJobs) {
+            // Only clean up non-running jobs
+            if (job.status !== 'running' && job.completedAt) {
+                const age = now - job.completedAt.getTime();
+                if (age > this.JOB_TTL_MS) {
+                    jobsToDelete.push(projectId);
+                }
+            }
+        }
+        for (const projectId of jobsToDelete) {
+            this.indexingJobs.delete(projectId);
+        }
+    }
+    /**
+     * Validate that a path is safe to index (security)
+     * Returns error message if unsafe, null if safe
+     */
+    validateProjectPath(projectPath) {
+        const normalizedPath = path.normalize(projectPath);
+        // Check for path traversal attempts
+        if (normalizedPath.includes('..')) {
+            return 'Path traversal detected: paths with ".." are not allowed';
+        }
+        // Check for dangerous system directories
+        const lowerPath = normalizedPath.toLowerCase();
+        for (const dangerous of this.DANGEROUS_PATHS) {
+            const lowerDangerous = dangerous.toLowerCase();
+            if (lowerPath === lowerDangerous || lowerPath.startsWith(lowerDangerous + path.sep)) {
+                return `Security: cannot index system directory "${dangerous}"`;
+            }
+        }
+        // Check path components for sensitive directories
+        const pathParts = normalizedPath.split(path.sep);
+        for (const part of pathParts) {
+            const lowerPart = part.toLowerCase();
+            if (lowerPart === '.ssh' || lowerPart === '.gnupg' || lowerPart === '.aws') {
+                return `Security: cannot index sensitive directory "${part}"`;
+            }
+        }
+        return null; // Path is safe
+    }
+    /**
+     * Start background indexing for a project
+     * Returns immediately, indexing happens asynchronously
+     */
+    startBackgroundIndexing(projectId, projectName, projectPath, clearExisting = true) {
+        // Create cancellation token
+        const cancellationToken = { cancelled: false };
+        this.cancellationTokens.set(projectId, cancellationToken);
+        // Create job entry
+        const job = {
+            projectId,
+            projectName,
+            projectPath,
+            status: 'running',
+            startedAt: new Date(),
+            progress: {
+                phase: 'starting',
+                filesProcessed: 0,
+                filesTotal: 0,
+                chunksCreated: 0,
+            },
+        };
+        this.indexingJobs.set(projectId, job);
+        // Release mutex once job is registered (actual indexing is tracked by job status)
+        this.indexingMutex.delete(projectId);
+        // Start indexing in background (don't await)
+        this.runBackgroundIndexing(job, clearExisting, cancellationToken).catch((error) => {
+            job.status = 'failed';
+            job.error = error instanceof Error ? error.message : String(error);
+            job.completedAt = new Date();
+            this.cancellationTokens.delete(projectId);
+        });
+    }
+    /**
+     * Cancel a running indexing job
+     */
+    cancelIndexing(projectId) {
+        const token = this.cancellationTokens.get(projectId);
+        if (token) {
+            token.cancelled = true;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Run the actual indexing (called asynchronously)
+     */
+    async runBackgroundIndexing(job, clearExisting, cancellationToken) {
+        try {
+            const storageManager = await (0, storage_1.getStorageManager)();
+            const vectorStore = storageManager.getVectorStore();
+            const graphStore = storageManager.getGraphStore();
+            // Clear existing data if requested
+            if (clearExisting) {
+                await vectorStore.deleteByProject(job.projectId);
+                await graphStore.deleteByProject(job.projectId);
+            }
+            // Check for cancellation before starting
+            if (cancellationToken.cancelled) {
+                job.status = 'failed';
+                job.error = 'Indexing cancelled by user';
+                job.completedAt = new Date();
+                this.cancellationTokens.delete(job.projectId);
+                return;
+            }
+            // Run indexing with progress tracking
+            const result = await this.indexingService.indexProject(job.projectPath, job.projectId, (progress) => {
+                // Check for cancellation during indexing
+                if (cancellationToken.cancelled) {
+                    throw new Error('Indexing cancelled by user');
+                }
+                job.progress = {
+                    phase: progress.phase,
+                    filesProcessed: progress.filesProcessed,
+                    filesTotal: progress.filesTotal,
+                    chunksCreated: progress.chunksCreated,
+                };
+            });
+            // Update job with results
+            job.status = 'completed';
+            job.completedAt = new Date();
+            job.result = {
+                filesIndexed: result.filesIndexed,
+                chunksCreated: result.chunksCreated,
+                nodesCreated: result.nodesCreated,
+                edgesCreated: result.edgesCreated,
+                durationMs: result.durationMs,
+            };
+            // Generate coding standards after indexing (if not cancelled)
+            if (!cancellationToken.cancelled) {
+                try {
+                    const generator = new coding_standards_generator_1.CodingStandardsGenerator(vectorStore);
+                    await generator.generateStandards(job.projectId, job.projectPath);
+                }
+                catch {
+                    // Non-fatal - standards generation is optional
+                }
+            }
+            // Invalidate query cache for this project (full reindex)
+            try {
+                await this.queryCache.invalidateProject(job.projectId);
+            }
+            catch {
+                // Non-fatal - cache invalidation is optional
+            }
+            // Clean up cancellation token
+            this.cancellationTokens.delete(job.projectId);
+        }
+        catch (error) {
+            job.status = 'failed';
+            job.error = error instanceof Error ? error.message : String(error);
+            job.completedAt = new Date();
+            this.cancellationTokens.delete(job.projectId);
+        }
+    }
+    /**
+     * Get indexing status for a project
+     */
+    getIndexingStatus(projectId) {
+        return this.indexingJobs.get(projectId);
     }
     /**
      * Find CodeSeeker project by walking up directory tree from startPath
@@ -107,28 +311,28 @@ class CodeSeekerMcpServer {
      * Register all MCP tools
      */
     registerTools() {
-        this.registerSearchCodeTool();
-        this.registerFindAndReadTool();
-        this.registerGetFileContextTool();
-        this.registerGetCodeRelationshipsTool();
-        this.registerListProjectsTool();
-        this.registerIndexProjectTool();
-        this.registerNotifyFileChangesTool();
-        this.registerInstallLanguageSupportTool();
-        this.registerManageIndexTool();
+        this.registerSearchTool();
+        this.registerSearchAndReadTool();
+        this.registerReadWithContextTool();
+        this.registerShowDependenciesTool();
+        this.registerProjectsTool();
+        this.registerIndexTool();
+        this.registerSyncTool();
+        this.registerInstallParsersTool();
+        this.registerExcludeTool();
     }
     /**
      * Tool 1: Semantic search across indexed projects
      */
-    registerSearchCodeTool() {
-        this.server.registerTool('search_code', {
+    registerSearchTool() {
+        this.server.registerTool('search', {
             description: '**DEFAULT TOOL FOR CODE DISCOVERY** - Use this BEFORE grep/glob for any code search. ' +
                 'This semantic search finds code by meaning, not just text patterns. ' +
                 'ALWAYS use for: "Where is X handled?", "Find the auth logic", "How does Y work?", "What calls Z?" ' +
                 'Only fall back to grep when: you need exact literal strings, regex patterns, or already know the exact file. ' +
                 'Why better than grep: finds "user authentication" even if code says "login", "session", "credentials". ' +
-                'Examples: ❌ grep -r "damage.*ship" → ✅ search_code("how ships take damage"). ' +
-                'Returns absolute file paths ready for the Read tool. If not indexed, call index_project first.',
+                'Examples: ❌ grep -r "damage.*ship" → ✅ search("how ships take damage"). ' +
+                'Returns absolute file paths ready for the Read tool. If not indexed, call index first.',
             inputSchema: {
                 query: zod_1.z.string().describe('Natural language query or code snippet (e.g., "validation logic", "error handling")'),
                 project: zod_1.z.string().optional().describe('Project path (optional - auto-detects from indexed projects if omitted)'),
@@ -180,7 +384,7 @@ class CodeSeekerMcpServer {
                         return {
                             content: [{
                                     type: 'text',
-                                    text: `No indexed projects found. Use index_project to index a project first.`,
+                                    text: `No indexed projects found. Use index to index a project first.`,
                                 }],
                             isError: true,
                         };
@@ -200,7 +404,7 @@ class CodeSeekerMcpServer {
                                 content: [{
                                         type: 'text',
                                         text: `⚠️  Project "${path.basename(projectPath)}" found but not indexed.\n\n` +
-                                            `ACTION REQUIRED: Call index_project({path: "${projectPath}"}) then retry this search.`,
+                                            `ACTION REQUIRED: Call index({path: "${projectPath}"}) then retry this search.`,
                                     }],
                                 isError: true,
                             };
@@ -212,14 +416,35 @@ class CodeSeekerMcpServer {
                             content: [{
                                     type: 'text',
                                     text: `⚠️  Project "${path.basename(projectPath)}" needs indexing.\n\n` +
-                                        `ACTION REQUIRED: Call index_project({path: "${projectPath}"}) then retry this search.`,
+                                        `ACTION REQUIRED: Call index({path: "${projectPath}"}) then retry this search.`,
                                 }],
                             isError: true,
                         };
                     }
                 }
-                // Perform search
-                const results = await this.searchOrchestrator.performSemanticSearch(query, projectPath);
+                // Check cache first (only for 'full' mode - exists mode is fast enough)
+                let results;
+                let fromCache = false;
+                const cacheProjectId = projectRecord?.id || this.generateProjectId(projectPath);
+                if (mode === 'full') {
+                    const cached = await this.queryCache.get(query, cacheProjectId, search_type);
+                    if (cached) {
+                        results = cached.results;
+                        fromCache = true;
+                    }
+                    else {
+                        // Perform actual search
+                        results = await this.searchOrchestrator.performSemanticSearch(query, projectPath);
+                        // Cache results for future queries
+                        if (results.length > 0) {
+                            await this.queryCache.set(query, cacheProjectId, results, search_type);
+                        }
+                    }
+                }
+                else {
+                    // exists mode - always search fresh (it's fast)
+                    results = await this.searchOrchestrator.performSemanticSearch(query, projectPath);
+                }
                 const limitedResults = results.slice(0, mode === 'exists' ? 5 : limit);
                 if (limitedResults.length === 0) {
                     // For exists mode, return structured response
@@ -294,6 +519,10 @@ class CodeSeekerMcpServer {
                     search_type,
                     results: formattedResults,
                 };
+                // Add cache indicator
+                if (fromCache) {
+                    response.cached = true;
+                }
                 // Add truncation warning when results were limited
                 if (wasLimited) {
                     response.truncated = true;
@@ -308,11 +537,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Search failed: ${message}`,
+                            text: this.formatErrorMessage('Search', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
@@ -322,15 +550,15 @@ class CodeSeekerMcpServer {
     /**
      * Tool 2: Find and read - combined search + read in one call
      */
-    registerFindAndReadTool() {
-        this.server.registerTool('find_and_read', {
+    registerSearchAndReadTool() {
+        this.server.registerTool('search_and_read', {
             description: '**SEARCH + READ IN ONE STEP** - Use when you need to see actual code, not just file paths. ' +
-                'Combines search_code + Read into a single call. Saves a round-trip when you know you\'ll need to read results. ' +
-                'Use this instead of search_code when: implementing something similar, understanding HOW code works, ' +
+                'Combines search + Read into a single call. Saves a round-trip when you know you\'ll need to read results. ' +
+                'Use this instead of search when: implementing something similar, understanding HOW code works, ' +
                 'user asks "show me the X code", or you need full context to make changes. ' +
-                'Examples: "Show me how damage is calculated" → find_and_read("damage calculation"). ' +
-                '"I need to add validation like login" → find_and_read("login form validation"). ' +
-                'Use search_code instead when: you only need file paths, checking if something exists (mode="exists"), ' +
+                'Examples: "Show me how damage is calculated" → search_and_read("damage calculation"). ' +
+                '"I need to add validation like login" → search_and_read("login form validation"). ' +
+                'Use search instead when: you only need file paths, checking if something exists (mode="exists"), ' +
                 'or want to see many results before picking one. Returns full file content with line numbers.',
             inputSchema: {
                 query: zod_1.z.string().describe('Natural language query or code snippet (e.g., "validation logic", "error handling")'),
@@ -382,7 +610,7 @@ class CodeSeekerMcpServer {
                         return {
                             content: [{
                                     type: 'text',
-                                    text: `No indexed projects found. Use index_project to index a project first.`,
+                                    text: `No indexed projects found. Use index to index a project first.`,
                                 }],
                             isError: true,
                         };
@@ -401,7 +629,7 @@ class CodeSeekerMcpServer {
                                 content: [{
                                         type: 'text',
                                         text: `⚠️  Project "${path.basename(projectPath)}" found but not indexed.\n\n` +
-                                            `ACTION REQUIRED: Call index_project({path: "${projectPath}"}) then retry.`,
+                                            `ACTION REQUIRED: Call index({path: "${projectPath}"}) then retry.`,
                                     }],
                                 isError: true,
                             };
@@ -412,7 +640,7 @@ class CodeSeekerMcpServer {
                             content: [{
                                     type: 'text',
                                     text: `⚠️  Project "${path.basename(projectPath)}" needs indexing.\n\n` +
-                                        `ACTION REQUIRED: Call index_project({path: "${projectPath}"}) then retry.`,
+                                        `ACTION REQUIRED: Call index({path: "${projectPath}"}) then retry.`,
                                 }],
                             isError: true,
                         };
@@ -507,11 +735,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Find and read failed: ${message}`,
+                            text: this.formatErrorMessage('Find and read', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
@@ -521,13 +748,13 @@ class CodeSeekerMcpServer {
     /**
      * Tool 3: Get file with semantic context
      */
-    registerGetFileContextTool() {
-        this.server.registerTool('get_file_context', {
+    registerReadWithContextTool() {
+        this.server.registerTool('read_with_context', {
             description: '**READ FILE WITH RELATED CODE** - Enhanced Read that includes semantically similar code. ' +
                 'Use instead of basic Read when: reading a file for the first time, the file references other modules, ' +
                 'or you want to discover patterns used elsewhere in the codebase. ' +
-                'Examples: Understanding a component → get_file_context("src/Button.tsx") returns Button + similar patterns. ' +
-                'Reading a service → get_file_context("src/api.ts") returns api.ts + related implementations. ' +
+                'Examples: Understanding a component → read_with_context("src/Button.tsx") returns Button + similar patterns. ' +
+                'Reading a service → read_with_context("src/api.ts") returns api.ts + related implementations. ' +
                 'Use basic Read instead when: you just need file contents, already understand the codebase, or making quick edits. ' +
                 'Set include_related=false to get just the file without related chunks.',
             inputSchema: {
@@ -621,11 +848,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to get file context: ${message}`,
+                            text: this.formatErrorMessage('Get file context', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
@@ -636,19 +862,19 @@ class CodeSeekerMcpServer {
      * Tool 3: Get code relationships from the knowledge graph
      * Uses "Seed + Expand" strategy like the CLI's GraphAnalysisService
      */
-    registerGetCodeRelationshipsTool() {
-        this.server.registerTool('get_code_relationships', {
-            description: '**UNDERSTAND CODE CONNECTIONS** - Use after search_code to explore how files relate. ' +
+    registerShowDependenciesTool() {
+        this.server.registerTool('show_dependencies', {
+            description: '**UNDERSTAND CODE CONNECTIONS** - Use after search to explore how files relate. ' +
                 'Maps imports, class hierarchies, function calls, dependencies. Essential for understanding impact of changes. ' +
                 'Use when: planning refactors ("what breaks if I change this?"), understanding architecture ("what depends on this?"), ' +
                 'tracing data flow ("where does this come from?"), before changing shared code. ' +
-                'WORKFLOW: 1) search_code to find files, 2) pass those paths here via filepaths parameter. ' +
+                'WORKFLOW: 1) search to find files, 2) pass those paths here via filepaths parameter. ' +
                 'Filter with relationship_types: ["imports"], ["calls"], ["extends"] to reduce noise. ' +
                 'Use direction="in" to find what USES this file, direction="out" for what this file USES.',
             inputSchema: {
                 filepath: zod_1.z.string().optional().describe('Single file path to explore (prefer filepaths for multiple)'),
-                filepaths: zod_1.z.array(zod_1.z.string()).optional().describe('PREFERRED: Array of file paths from search_code results'),
-                query: zod_1.z.string().optional().describe('Fallback: semantic search to find seed files (prefer using filepaths from search_code)'),
+                filepaths: zod_1.z.array(zod_1.z.string()).optional().describe('PREFERRED: Array of file paths from search results'),
+                query: zod_1.z.string().optional().describe('Fallback: semantic search to find seed files (prefer using filepaths from search)'),
                 depth: zod_1.z.number().optional().default(1).describe('How many relationship hops to traverse (1-3, default: 1). Use 1 for focused results, 2+ can return many nodes.'),
                 relationship_types: zod_1.z.array(zod_1.z.enum([
                     'imports', 'exports', 'calls', 'extends', 'implements', 'contains', 'uses', 'depends_on'
@@ -693,7 +919,7 @@ class CodeSeekerMcpServer {
                     return {
                         content: [{
                                 type: 'text',
-                                text: 'Project not indexed. Use index_project first.',
+                                text: 'Project not indexed. Use index first.',
                             }],
                         isError: true,
                     };
@@ -880,11 +1106,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to get code relationships: ${message}`,
+                            text: this.formatErrorMessage('Get code relationships', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
@@ -894,12 +1119,12 @@ class CodeSeekerMcpServer {
     /**
      * Tool 4: List indexed projects
      */
-    registerListProjectsTool() {
-        this.server.registerTool('list_projects', {
+    registerProjectsTool() {
+        this.server.registerTool('projects', {
             description: 'List all indexed projects with their metadata. ' +
                 'Returns project names, paths, indexed file counts, and last index timestamps. ' +
-                'Use to discover available projects before running search_code or get_code_relationships. ' +
-                'Example: list_projects() shows all projects ready for semantic search.',
+                'Use to discover available projects before running search or show_dependencies. ' +
+                'Example: projects() shows all projects ready for semantic search.',
         }, async () => {
             try {
                 const storageManager = await (0, storage_1.getStorageManager)();
@@ -910,21 +1135,28 @@ class CodeSeekerMcpServer {
                     return {
                         content: [{
                                 type: 'text',
-                                text: 'No projects indexed. Use index_project to add a project.',
+                                text: 'No projects indexed. Use index to add a project.',
                             }],
                     };
                 }
-                // Get file and chunk counts for each project
+                // Get file and chunk counts for each project, plus indexing status
                 const projectsWithCounts = await Promise.all(projects.map(async (p) => {
                     const fileCount = await vectorStore.countFiles(p.id);
                     const chunkCount = await vectorStore.count(p.id);
-                    return {
+                    // Check for background indexing status
+                    const indexingStatus = this._getIndexingStatusForProject(p.id);
+                    const projectInfo = {
                         name: p.name,
                         path: p.path,
                         files: fileCount,
                         chunks: chunkCount,
                         last_indexed: p.updatedAt.toISOString(),
                     };
+                    // Add indexing status if job exists
+                    if (indexingStatus) {
+                        Object.assign(projectInfo, indexingStatus);
+                    }
+                    return projectInfo;
                 }));
                 return {
                     content: [{
@@ -938,11 +1170,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to list projects: ${message}`,
+                            text: this.formatErrorMessage('List projects', error instanceof Error ? error : String(error)),
                         }],
                     isError: true,
                 };
@@ -951,13 +1182,15 @@ class CodeSeekerMcpServer {
     }
     /**
      * Tool 5: Index a project (with proper embeddings and knowledge graph)
+     * NOW RUNS IN BACKGROUND to prevent MCP timeouts
      */
-    registerIndexProjectTool() {
-        this.server.registerTool('index_project', {
+    registerIndexTool() {
+        this.server.registerTool('index', {
             description: 'Index a project directory for semantic search and knowledge graph. ' +
                 'Scans code, documentation, configs, and other text files. Generates vector embeddings and extracts code relationships. ' +
-                'Run once per project, then use notify_file_changes for incremental updates. ' +
-                'Example: index_project({path: "/home/user/my-app"}) indexes all files in my-app.',
+                'Run once per project, then use sync for incremental updates. ' +
+                'Example: index({path: "/home/user/my-app"}) indexes all files in my-app.' +
+                '\n\nNOTE: Indexing runs in BACKGROUND to prevent timeouts. Use projects() to check indexing status.',
             inputSchema: {
                 path: zod_1.z.string().describe('Absolute path to the project directory'),
                 name: zod_1.z.string().optional().describe('Project name (defaults to directory name)'),
@@ -969,6 +1202,17 @@ class CodeSeekerMcpServer {
                 const absolutePath = path.isAbsolute(projectPath)
                     ? projectPath
                     : path.resolve(projectPath);
+                // Security: validate path is safe to index
+                const pathError = this.validateProjectPath(absolutePath);
+                if (pathError) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: pathError,
+                            }],
+                        isError: true,
+                    };
+                }
                 if (!fs.existsSync(absolutePath)) {
                     return {
                         content: [{
@@ -988,84 +1232,114 @@ class CodeSeekerMcpServer {
                     };
                 }
                 const projectName = name || path.basename(absolutePath);
-                // Get storage and create project
+                const projectId = this.generateProjectId(absolutePath);
+                // Mutex: prevent concurrent indexing of same project (race condition protection)
+                if (this.indexingMutex.has(projectId)) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'already_indexing',
+                                    project_name: projectName,
+                                    project_path: absolutePath,
+                                    message: 'Indexing request already being processed. Please wait.',
+                                }, null, 2),
+                            }],
+                    };
+                }
+                // Check if already indexing (from job status)
+                const existingJob = this.getIndexingStatus(projectId);
+                if (existingJob?.status === 'running') {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    status: 'already_indexing',
+                                    project_name: projectName,
+                                    project_path: absolutePath,
+                                    progress: existingJob.progress,
+                                    message: 'Indexing already in progress. Use projects() to check status.',
+                                }, null, 2),
+                            }],
+                    };
+                }
+                // Acquire mutex before starting
+                this.indexingMutex.add(projectId);
+                // Get storage and create project entry
                 const storageManager = await (0, storage_1.getStorageManager)();
                 const projectStore = storageManager.getProjectStore();
-                const vectorStore = storageManager.getVectorStore();
-                const graphStore = storageManager.getGraphStore();
                 // Create or update project
-                const project = await projectStore.upsert({
-                    id: this.generateProjectId(absolutePath),
+                await projectStore.upsert({
+                    id: projectId,
                     name: projectName,
                     path: absolutePath,
-                    metadata: { indexedAt: new Date().toISOString() },
+                    metadata: { indexedAt: new Date().toISOString(), indexing: true },
                 });
-                // Clear existing index data for clean reindex
-                await vectorStore.deleteByProject(project.id);
-                await graphStore.deleteByProject(project.id);
                 // Delete coding standards file (will be regenerated)
                 const codingStandardsPath = path.join(absolutePath, '.codeseeker', 'coding-standards.json');
                 if (fs.existsSync(codingStandardsPath)) {
-                    fs.unlinkSync(codingStandardsPath);
-                }
-                // Use IndexingService for proper indexing with embeddings and graph
-                // Track progress for detailed reporting
-                let lastProgress;
-                const result = await this.indexingService.indexProject(absolutePath, project.id, (progress) => {
-                    lastProgress = progress;
-                });
-                // Build response with progress details
-                const response = {
-                    success: result.success,
-                    project_name: projectName,
-                    project_path: absolutePath,
-                    files_indexed: result.filesIndexed,
-                    chunks_created: result.chunksCreated,
-                    graph_nodes: result.nodesCreated,
-                    graph_edges: result.edgesCreated,
-                    duration_ms: result.durationMs,
-                };
-                // Add scanning summary if available
-                if (lastProgress?.scanningStatus) {
-                    response.scanning_summary = {
-                        folders_scanned: lastProgress.scanningStatus.foldersScanned,
-                        files_found: lastProgress.scanningStatus.filesFound,
-                    };
-                }
-                // Add warnings (file limits, recommendations)
-                if (result.warnings && result.warnings.length > 0) {
-                    response.warnings = result.warnings;
-                }
-                // Add errors if any
-                if (result.errors.length > 0) {
-                    response.errors = result.errors.slice(0, 5);
+                    try {
+                        fs.unlinkSync(codingStandardsPath);
+                    }
+                    catch { /* ignore */ }
                 }
+                // Start background indexing (returns immediately)
+                this.startBackgroundIndexing(projectId, projectName, absolutePath, true);
+                // Return immediately with "started" status
                 return {
                     content: [{
                             type: 'text',
-                            text: JSON.stringify(response, null, 2),
+                            text: JSON.stringify({
+                                status: 'indexing_started',
+                                project_name: projectName,
+                                project_path: absolutePath,
+                                message: 'Indexing started in background. Search will work with partial results. Use projects() to check progress.',
+                            }, null, 2),
                         }],
                 };
+                // OLD SYNCHRONOUS CODE REMOVED - was causing MCP timeouts
+                // Now handled by startBackgroundIndexing()
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to index project: ${message}`,
+                            text: JSON.stringify({ error: message }, null, 2),
                         }],
                     isError: true,
                 };
             }
         });
     }
+    // Remove the old synchronous indexing response builder (now in background)
+    _unusedOldIndexingResponse() {
+        // This is a placeholder to mark where old code was removed
+        // The synchronous indexing logic is now in runBackgroundIndexing()
+    }
+    /**
+     * Tool 5b: Check indexing status (part of projects output now)
+     */
+    _getIndexingStatusForProject(projectId) {
+        const job = this.indexingJobs.get(projectId);
+        if (!job)
+            return null;
+        return {
+            indexing_status: job.status,
+            indexing_progress: job.progress,
+            indexing_result: job.result,
+            indexing_error: job.error,
+            indexing_started: job.startedAt.toISOString(),
+            indexing_completed: job.completedAt?.toISOString(),
+        };
+    }
     /**
-     * Tool 5: Notify file changes for incremental updates
+     * Tool 6: Notify file changes for incremental updates
      */
-    registerNotifyFileChangesTool() {
-        this.server.registerTool('notify_file_changes', {
+    registerSyncTool() {
+        this.server.registerTool('sync', {
             description: '**KEEP INDEX IN SYNC** - Call this after creating, editing, or deleting files. ' +
-                'IMPORTANT: If search_code returns stale results or grep finds content not in search results, ' +
+                'IMPORTANT: If search returns stale results or grep finds content not in search results, ' +
                 'call this tool immediately to sync. Fast incremental updates (~100-500ms per file). ' +
                 'Use after: Edit/Write tool, file deletions, or when search results seem outdated. ' +
                 'For large changes (git pull, branch switch, many files), use full_reindex: true instead.',
@@ -1113,68 +1387,49 @@ class CodeSeekerMcpServer {
                         content: [{
                                 type: 'text',
                                 text: project
-                                    ? `Project not found: ${project}. Use list_projects to see available projects.`
+                                    ? `Project not found: ${project}. Use projects to see available projects.`
                                     : `Could not auto-detect project. Specify project name or use absolute paths in changes. Available: ${projects.map(p => p.name).join(', ')}`,
                             }],
                         isError: true,
                     };
                 }
-                // Full reindex mode - use IndexingService
+                // Full reindex mode - NOW RUNS IN BACKGROUND
                 if (full_reindex) {
-                    // Clear existing index for this project
-                    await vectorStore.deleteByProject(found.id);
-                    await graphStore.deleteByProject(found.id);
+                    // Check if already indexing
+                    const existingJob = this.getIndexingStatus(found.id);
+                    if (existingJob?.status === 'running') {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        status: 'already_indexing',
+                                        project: found.name,
+                                        progress: existingJob.progress,
+                                        message: 'Full reindex already in progress. Use projects() to check status.',
+                                    }, null, 2),
+                                }],
+                        };
+                    }
                     // Delete coding standards file (will be regenerated)
                     const codingStandardsPath = path.join(found.path, '.codeseeker', 'coding-standards.json');
                     if (fs.existsSync(codingStandardsPath)) {
-                        fs.unlinkSync(codingStandardsPath);
-                    }
-                    // Re-index all files using IndexingService (with proper embeddings and graph)
-                    let lastProgress;
-                    const result = await this.indexingService.indexProject(found.path, found.id, (progress) => {
-                        lastProgress = progress;
-                    });
-                    // Update project metadata
-                    await projectStore.upsert({
-                        id: found.id,
-                        name: found.name,
-                        path: found.path,
-                        metadata: {
-                            ...found.metadata,
-                            lastFullReindex: new Date().toISOString(),
-                        },
-                    });
-                    // Build response with all details
-                    const response = {
-                        success: result.success,
-                        mode: 'full_reindex',
-                        project: found.name,
-                        files_indexed: result.filesIndexed,
-                        chunks_created: result.chunksCreated,
-                        graph_nodes: result.nodesCreated,
-                        graph_edges: result.edgesCreated,
-                        duration_ms: result.durationMs,
-                        message: `Complete reindex finished. ${result.filesIndexed} files indexed, ${result.chunksCreated} chunks created.`,
-                    };
-                    // Add scanning summary
-                    if (lastProgress?.scanningStatus) {
-                        response.scanning_summary = {
-                            folders_scanned: lastProgress.scanningStatus.foldersScanned,
-                            files_found: lastProgress.scanningStatus.filesFound,
-                        };
-                    }
-                    // Add warnings
-                    if (result.warnings && result.warnings.length > 0) {
-                        response.warnings = result.warnings;
-                    }
-                    // Add errors
-                    if (result.errors.length > 0) {
-                        response.errors = result.errors.slice(0, 5);
+                        try {
+                            fs.unlinkSync(codingStandardsPath);
+                        }
+                        catch { /* ignore */ }
                     }
+                    // Start background indexing (returns immediately)
+                    this.startBackgroundIndexing(found.id, found.name, found.path, true);
+                    // Return immediately with "started" status
                     return {
                         content: [{
                                 type: 'text',
-                                text: JSON.stringify(response, null, 2),
+                                text: JSON.stringify({
+                                    status: 'reindex_started',
+                                    mode: 'full_reindex',
+                                    project: found.name,
+                                    message: 'Full reindex started in background. Search will work with partial results. Use projects() to check progress.',
+                                }, null, 2),
                             }],
                     };
                 }
@@ -1236,6 +1491,15 @@ class CodeSeekerMcpServer {
                     // Don't fail the whole operation if standards update fails
                     console.error('Failed to update coding standards:', error);
                 }
+                // Invalidate query cache for this project (files changed)
+                let cacheInvalidated = 0;
+                try {
+                    cacheInvalidated = await this.queryCache.invalidateProject(found.id);
+                }
+                catch (error) {
+                    // Don't fail if cache invalidation fails
+                    console.error('Failed to invalidate query cache:', error);
+                }
                 const duration = Date.now() - startTime;
                 return {
                     content: [{
@@ -1249,6 +1513,7 @@ class CodeSeekerMcpServer {
                                 files_skipped: filesSkipped > 0 ? filesSkipped : undefined,
                                 chunks_created: chunksCreated,
                                 chunks_deleted: chunksDeleted,
+                                cache_invalidated: cacheInvalidated > 0 ? cacheInvalidated : undefined,
                                 duration_ms: duration,
                                 note: filesSkipped > 0 ? `${filesSkipped} file(s) unchanged (skipped via mtime/hash check)` : undefined,
                                 errors: errors.length > 0 ? errors.slice(0, 5) : undefined,
@@ -1257,22 +1522,21 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to process file changes: ${message}`,
+                            text: this.formatErrorMessage('Process file changes', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
             }
         });
-        // get_coding_standards - Get auto-detected coding standards
-        this.server.registerTool('get_coding_standards', {
+        // standards - Get auto-detected coding standards
+        this.server.registerTool('standards', {
             description: 'Get auto-detected coding patterns and standards for a project. ' +
                 'Returns validation patterns, error handling patterns, logging patterns, and testing patterns ' +
                 'discovered from the codebase. Use this to write code that follows project conventions. ' +
-                'Example: get_coding_standards({project: "my-app", category: "validation"})',
+                'Example: standards({project: "my-app", category: "validation"})',
             inputSchema: {
                 project: zod_1.z.string().describe('Project name or path'),
                 category: zod_1.z.enum(['validation', 'error-handling', 'logging', 'testing', 'all']).optional().default('all')
@@ -1292,7 +1556,7 @@ class CodeSeekerMcpServer {
                     return {
                         content: [{
                                 type: 'text',
-                                text: `Project not found: ${project}. Use list_projects to see available projects.`,
+                                text: `Project not found: ${project}. Use projects to see available projects.`,
                             }],
                         isError: true,
                     };
@@ -1315,7 +1579,7 @@ class CodeSeekerMcpServer {
                         return {
                             content: [{
                                     type: 'text',
-                                    text: 'No coding standards detected yet. The project may need to be indexed first using index_project.',
+                                    text: 'No coding standards detected yet. The project may need to be indexed first using index.',
                                 }],
                             isError: true,
                         };
@@ -1340,11 +1604,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to get coding standards: ${message}`,
+                            text: this.formatErrorMessage('Get coding standards', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
@@ -1354,13 +1617,13 @@ class CodeSeekerMcpServer {
     /**
      * Tool 7: Install language support (Tree-sitter parsers)
      */
-    registerInstallLanguageSupportTool() {
-        this.server.registerTool('install_language_support', {
+    registerInstallParsersTool() {
+        this.server.registerTool('install_parsers', {
             description: 'Analyze project languages and install Tree-sitter parsers for better code understanding. ' +
                 'Detects which programming languages are used in a project and installs enhanced parsers. ' +
                 'Enhanced parsers provide better AST extraction for imports, classes, functions, and relationships. ' +
-                'Example: install_language_support({project: "/path/to/project"}) to auto-detect and install. ' +
-                'Example: install_language_support({languages: ["python", "java"]}) to install specific parsers.',
+                'Example: install_parsers({project: "/path/to/project"}) to auto-detect and install. ' +
+                'Example: install_parsers({languages: ["python", "java"]}) to install specific parsers.',
             inputSchema: {
                 project: zod_1.z.string().optional().describe('Project path to analyze for languages (auto-detects needed parsers)'),
                 languages: zod_1.z.array(zod_1.z.string()).optional().describe('Specific languages to install parsers for (e.g., ["python", "java", "csharp"])'),
@@ -1391,7 +1654,7 @@ class CodeSeekerMcpServer {
                                         description: p.description,
                                     })),
                                     install_command: available.length > 0
-                                        ? `Use install_language_support({languages: [${available.slice(0, 3).map(p => `"${p.language.toLowerCase()}"`).join(', ')}]})`
+                                        ? `Use install_parsers({languages: [${available.slice(0, 3).map(p => `"${p.language.toLowerCase()}"`).join(', ')}]})`
                                         : 'All parsers are already installed!',
                                 }, null, 2),
                             }],
@@ -1409,7 +1672,7 @@ class CodeSeekerMcpServer {
                                     failed: result.failed.length > 0 ? result.failed : undefined,
                                     message: result.message,
                                     next_step: result.success
-                                        ? 'Reindex your project to use the new parsers: notify_file_changes({project: "...", full_reindex: true})'
+                                        ? 'Reindex your project to use the new parsers: sync({project: "...", full_reindex: true})'
                                         : 'Check the errors above and try again.',
                                 }, null, 2),
                             }],
@@ -1447,7 +1710,7 @@ class CodeSeekerMcpServer {
                                     })),
                                     recommendations: analysis.recommendations,
                                     install_command: missingLanguages.length > 0
-                                        ? `Use install_language_support({languages: [${missingLanguages.map(l => `"${l}"`).join(', ')}]}) to install enhanced parsers`
+                                        ? `Use install_parsers({languages: [${missingLanguages.map(l => `"${l}"`).join(', ')}]}) to install enhanced parsers`
                                         : 'All detected languages have parsers installed!',
                                 }, null, 2),
                             }],
@@ -1459,9 +1722,9 @@ class CodeSeekerMcpServer {
                             type: 'text',
                             text: JSON.stringify({
                                 usage: {
-                                    analyze_project: 'install_language_support({project: "/path/to/project"}) - Detect languages and suggest parsers',
-                                    install_specific: 'install_language_support({languages: ["python", "java"]}) - Install parsers for specific languages',
-                                    list_available: 'install_language_support({list_available: true}) - Show all available parsers',
+                                    analyze_project: 'install_parsers({project: "/path/to/project"}) - Detect languages and suggest parsers',
+                                    install_specific: 'install_parsers({languages: ["python", "java"]}) - Install parsers for specific languages',
+                                    list_available: 'install_parsers({list_available: true}) - Show all available parsers',
                                 },
                                 supported_languages: [
                                     'TypeScript (bundled)', 'JavaScript (bundled)',
@@ -1473,11 +1736,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to manage language support: ${message}`,
+                            text: this.formatErrorMessage('Manage language support', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
@@ -1489,12 +1751,12 @@ class CodeSeekerMcpServer {
      * Allows Claude to exclude files that shouldn't be indexed (like Unity's Library folder)
      * and include files that were wrongly excluded
      */
-    registerManageIndexTool() {
-        this.server.registerTool('manage_index', {
+    registerExcludeTool() {
+        this.server.registerTool('exclude', {
             description: 'Dynamically manage which files are included or excluded from the index. ' +
                 'Use this to exclude files that shouldn\'t be searched (e.g., Library/, build outputs, generated files) ' +
                 'or include files that were incorrectly excluded. Exclusions persist in .codeseeker/exclusions.json. ' +
-                'Example: manage_index({action: "exclude", project: "my-app", paths: ["Library/**", "Temp/**"]}) ' +
+                'Example: exclude({action: "exclude", project: "my-app", paths: ["Library/**", "Temp/**"]}) ' +
                 'to exclude Unity folders. Changes take effect immediately - excluded files are removed from the index.',
             inputSchema: {
                 action: zod_1.z.enum(['exclude', 'include', 'list']).describe('Action: "exclude" adds paths to exclusion list and removes from index, ' +
@@ -1520,7 +1782,7 @@ class CodeSeekerMcpServer {
                     return {
                         content: [{
                                 type: 'text',
-                                text: `Project not found: ${project}. Use list_projects to see available projects.`,
+                                text: `Project not found: ${project}. Use projects to see available projects.`,
                             }],
                         isError: true,
                     };
@@ -1558,8 +1820,8 @@ class CodeSeekerMcpServer {
                                     patterns: exclusions.patterns,
                                     last_modified: exclusions.lastModified,
                                     usage: {
-                                        exclude: 'manage_index({action: "exclude", project: "...", paths: ["pattern/**"]})',
-                                        include: 'manage_index({action: "include", project: "...", paths: ["pattern/**"]})',
+                                        exclude: 'exclude({action: "exclude", project: "...", paths: ["pattern/**"]})',
+                                        include: 'exclude({action: "include", project: "...", paths: ["pattern/**"]})',
                                     }
                                 }, null, 2),
                             }],
@@ -1665,7 +1927,7 @@ class CodeSeekerMcpServer {
                                             `Files matching these patterns will be indexed on next reindex.`
                                         : 'No patterns were removed (none matched).',
                                     next_step: removedPatterns.length > 0
-                                        ? 'Run notify_file_changes({project: "...", full_reindex: true}) to index the previously excluded files.'
+                                        ? 'Run sync({project: "...", full_reindex: true}) to index the previously excluded files.'
                                         : undefined
                                 }, null, 2),
                             }],
@@ -1681,11 +1943,10 @@ class CodeSeekerMcpServer {
                 };
             }
             catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
                 return {
                     content: [{
                             type: 'text',
-                            text: `Failed to manage index: ${message}`,
+                            text: this.formatErrorMessage('Manage index exclusions', error instanceof Error ? error : String(error), { projectPath: project }),
                         }],
                     isError: true,
                 };
@@ -1741,6 +2002,63 @@ class CodeSeekerMcpServer {
     generateProjectId(projectPath) {
         return crypto.createHash('md5').update(projectPath).digest('hex');
     }
+    /**
+     * Generate actionable error message based on error type
+     */
+    formatErrorMessage(operation, error, context) {
+        const message = error instanceof Error ? error.message : String(error);
+        const lowerMessage = message.toLowerCase();
+        // Common error patterns with actionable guidance
+        if (lowerMessage.includes('enoent') || lowerMessage.includes('not found') || lowerMessage.includes('no such file')) {
+            return `${operation} failed: File or directory not found.\n\n` +
+                `TROUBLESHOOTING:\n` +
+                `• Verify the path exists: ${context?.projectPath || 'the specified path'}\n` +
+                `• Check for typos in the path\n` +
+                `• Ensure you have read permissions`;
+        }
+        if (lowerMessage.includes('eacces') || lowerMessage.includes('permission denied')) {
+            return `${operation} failed: Permission denied.\n\n` +
+                `TROUBLESHOOTING:\n` +
+                `• Check file/folder permissions\n` +
+                `• Run with appropriate access rights\n` +
+                `• Avoid system-protected directories`;
+        }
+        if (lowerMessage.includes('timeout') || lowerMessage.includes('timed out')) {
+            return `${operation} failed: Operation timed out.\n\n` +
+                `TROUBLESHOOTING:\n` +
+                `• Try again - the operation may complete on retry\n` +
+                `• For large projects, indexing runs in background - check status with projects()\n` +
+                `• Check network connectivity if using server storage mode`;
+        }
+        if (lowerMessage.includes('connection') || lowerMessage.includes('econnrefused') || lowerMessage.includes('network')) {
+            return `${operation} failed: Connection error.\n\n` +
+                `TROUBLESHOOTING:\n` +
+                `• Check if storage services are running (if using server mode)\n` +
+                `• Verify network connectivity\n` +
+                `• Consider switching to embedded mode for local development`;
+        }
+        if (lowerMessage.includes('not indexed') || lowerMessage.includes('no project')) {
+            const pathHint = context?.projectPath ? `index({path: "${context.projectPath}"})` : 'index({path: "/path/to/project"})';
+            return `${operation} failed: Project not indexed.\n\n` +
+                `ACTION REQUIRED:\n` +
+                `• First run: ${pathHint}\n` +
+                `• Then retry your search\n` +
+                `• Use projects() to see indexed projects`;
+        }
+        if (lowerMessage.includes('out of memory') || lowerMessage.includes('heap')) {
+            return `${operation} failed: Out of memory.\n\n` +
+                `TROUBLESHOOTING:\n` +
+                `• Try indexing fewer files at once\n` +
+                `• Use exclude() to skip large directories (e.g., node_modules, dist)\n` +
+                `• Increase Node.js memory: NODE_OPTIONS=--max-old-space-size=4096`;
+        }
+        // Default: include original message with generic guidance
+        return `${operation} failed: ${message}\n\n` +
+            `TROUBLESHOOTING:\n` +
+            `• Check the error message above for details\n` +
+            `• Use projects() to verify project status\n` +
+            `• Try sync({project: "...", full_reindex: true}) if index seems corrupted`;
+    }
     /**
      * Start the MCP server
      */