codeseeker 1.11.1 → 2.0.0

package/dist/mcp/mcp-server.js

@@ -6,10 +6,9 @@
  * as an MCP (Model Context Protocol) server for use with Claude Desktop
  * and Claude Code.
  *
- * OPTIMIZED: 12 tools consolidated to 3 to minimize token usage:
- *   1. search  - Code discovery (search, search+read, read-with-context)
- *   2. analyze - Code analysis (dependencies, dead_code, duplicates, standards)
- *   3. index   - Index management (init, sync, status, parsers, exclude)
+ * Single sentinel tool: codeseeker
+ *   Routes to: search (q), symbol lookup (sym), graph traversal (graph),
+ *              analysis (analyze), index management (index)
  *
  * Usage:
  *   codeseeker serve --mcp
@@ -403,312 +402,264 @@ class CodeSeekerMcpServer {
     // TOOL REGISTRATION - 3 CONSOLIDATED TOOLS
     // ============================================================
     registerTools() {
-        this.registerSearchTool();
-        this.registerAnalyzeTool();
-        this.registerIndexTool();
+        this.registerSentinelTool();
     }
     // ============================================================
-    // TOOL 1: search
-    //   Combines: search, search_and_read, read_with_context
+    // SENTINEL TOOL: codeseeker
+    //   Hierarchical schema — each action carries its own nested params
     // ============================================================
-    registerSearchTool() {
-        this.server.registerTool('search', {
-            description: 'Semantic code search. Finds code by meaning, not just text. ' +
-                'Pass query to search, add read=true to include file contents, or pass filepath instead to read a file with related context.',
+    registerSentinelTool() {
+        this.server.registerTool('codeseeker', {
+            description: 'Code intelligence: search (q), symbol lookup (sym), graph traversal (graph), analysis (analyze), index management (index).',
             inputSchema: {
-                query: zod_1.z.string().optional().describe('Natural language search query'),
-                filepath: zod_1.z.string().optional().describe('File path to read with semantic context (alternative to query)'),
+                action: zod_1.z.enum(['search', 'sym', 'graph', 'analyze', 'index'])
+                    .describe('Routing key — fill only the matching nested param group'),
                 project: zod_1.z.string().optional().describe('Project path or name'),
-                read: zod_1.z.boolean().optional().default(false).describe('Include file contents in results'),
-                limit: zod_1.z.number().optional().default(10).describe('Max results'),
-                max_lines: zod_1.z.number().optional().default(500).describe('Max lines per file when read=true'),
-                search_type: zod_1.z.enum(['hybrid', 'fts', 'vector', 'graph']).optional().default('hybrid')
-                    .describe('Search method'),
-                mode: zod_1.z.enum(['full', 'exists']).optional().default('full')
-                    .describe('"exists" returns quick yes/no'),
+                search: zod_1.z.object({
+                    q: zod_1.z.string().describe('Natural language query'),
+                    exists: zod_1.z.boolean().optional().default(false).describe('Quick yes/no — returns {found,count,top_file}'),
+                    full: zod_1.z.boolean().optional().default(false).describe('Add snippet to each result (default: summary only)'),
+                    limit: zod_1.z.number().optional().default(10),
+                    type: zod_1.z.enum(['hybrid', 'fts', 'vector']).optional().default('hybrid'),
+                }).optional().describe('Params for action=search'),
+                sym: zod_1.z.object({
+                    name: zod_1.z.string().describe('Symbol name (exact or partial)'),
+                    full: zod_1.z.boolean().optional().default(false).describe('Include resolved relationships'),
+                }).optional().describe('Params for action=sym'),
+                graph: zod_1.z.object({
+                    seed: zod_1.z.string().optional().describe('Seed file (relative path)'),
+                    q: zod_1.z.string().optional().describe('Query to find seed files semantically'),
+                    depth: zod_1.z.number().optional().default(1).describe('Traversal depth 1-3'),
+                    rel: zod_1.z.array(zod_1.z.enum(['imports', 'exports', 'calls', 'extends', 'implements', 'contains', 'uses', 'depends_on'])).optional(),
+                    dir: zod_1.z.enum(['in', 'out', 'both']).optional().default('both'),
+                    max: zod_1.z.number().optional().default(50),
+                }).optional().describe('Params for action=graph'),
+                analyze: zod_1.z.object({
+                    kind: zod_1.z.enum(['duplicates', 'dead_code', 'standards']).describe('Analysis type'),
+                    threshold: zod_1.z.number().optional().default(0.80).describe('Similarity threshold for duplicates'),
+                    min_lines: zod_1.z.number().optional().default(5),
+                    patterns: zod_1.z.array(zod_1.z.enum(['dead_code', 'god_class', 'circular_deps', 'feature_envy', 'coupling'])).optional(),
+                    category: zod_1.z.enum(['validation', 'error-handling', 'logging', 'testing', 'all']).optional().default('all'),
+                }).optional().describe('Params for action=analyze'),
+                index: zod_1.z.object({
+                    op: zod_1.z.enum(['init', 'sync', 'status', 'parsers', 'exclude']).describe('Operation'),
+                    path: zod_1.z.string().optional().describe('Project dir (op=init)'),
+                    name: zod_1.z.string().optional().describe('Project name (op=init)'),
+                    changes: zod_1.z.array(zod_1.z.object({ type: zod_1.z.enum(['created', 'modified', 'deleted']), path: zod_1.z.string() })).optional(),
+                    full_reindex: zod_1.z.boolean().optional().default(false),
+                    languages: zod_1.z.array(zod_1.z.string()).optional(),
+                    list_available: zod_1.z.boolean().optional().default(false),
+                    exclude_op: zod_1.z.enum(['exclude', 'include', 'list']).optional(),
+                    paths: zod_1.z.array(zod_1.z.string()).optional(),
+                    reason: zod_1.z.string().optional(),
+                }).optional().describe('Params for action=index'),
             },
-        }, async ({ query, filepath, project, read = false, limit = 10, max_lines = 500, search_type = 'hybrid', mode = 'full' }) => {
+        }, async (params) => {
             try {
-                // Dispatch: filepath → read-with-context, read → search-and-read, else → search
-                if (filepath) {
-                    return await this.handleReadWithContext(filepath, project, !read ? true : read);
-                }
-                if (!query) {
-                    return {
-                        content: [{ type: 'text', text: 'Provide either query or filepath parameter.' }],
-                        isError: true,
-                    };
-                }
-                if (read) {
-                    return await this.handleSearchAndRead(query, project, Math.min(limit, 3), Math.min(max_lines, 1000));
+                switch (params.action) {
+                    case 'search': {
+                        const s = params.search;
+                        if (!s)
+                            return { content: [{ type: 'text', text: 'Provide search params.' }], isError: true };
+                        return await this.handleSearch(s.q, params.project, s.limit ?? 10, s.type ?? 'hybrid', s.exists ?? false, s.full ?? false);
+                    }
+                    case 'sym': {
+                        const s = params.sym;
+                        if (!s)
+                            return { content: [{ type: 'text', text: 'Provide sym params.' }], isError: true };
+                        return await this.handleSymbolLookup(s.name, params.project, s.full ?? false);
+                    }
+                    case 'graph': {
+                        const g = params.graph;
+                        if (!g)
+                            return { content: [{ type: 'text', text: 'Provide graph params.' }], isError: true };
+                        const { projectPath, error } = await this.resolveProject(params.project);
+                        if (error)
+                            return error;
+                        return await this.handleShowDependencies({
+                            project: projectPath,
+                            filepath: g.seed,
+                            query: g.q,
+                            depth: g.depth,
+                            relationship_types: g.rel,
+                            direction: g.dir,
+                            max_nodes: g.max,
+                        });
+                    }
+                    case 'analyze': {
+                        const a = params.analyze;
+                        if (!a)
+                            return { content: [{ type: 'text', text: 'Provide analyze params.' }], isError: true };
+                        if (!params.project)
+                            return { content: [{ type: 'text', text: 'project required for analyze.' }], isError: true };
+                        switch (a.kind) {
+                            case 'duplicates': return await this.handleFindDuplicates({ project: params.project, similarity_threshold: a.threshold, min_lines: a.min_lines });
+                            case 'dead_code': return await this.handleFindDeadCode({ project: params.project, include_patterns: a.patterns });
+                            case 'standards': return await this.handleStandards({ project: params.project, category: a.category });
+                        }
+                        break;
+                    }
+                    case 'index': {
+                        const ix = params.index;
+                        if (!ix)
+                            return { content: [{ type: 'text', text: 'Provide index params.' }], isError: true };
+                        switch (ix.op) {
+                            case 'init': return await this.handleIndexInit({ path: ix.path, name: ix.name || params.project });
+                            case 'sync': return await this.handleSync({ project: params.project, changes: ix.changes, full_reindex: ix.full_reindex });
+                            case 'status': return await this.handleProjects();
+                            case 'parsers': return await this.handleInstallParsers({ project: params.project, languages: ix.languages, list_available: ix.list_available });
+                            case 'exclude': return await this.handleExclude({ project: params.project, exclude_action: ix.exclude_op, paths: ix.paths, reason: ix.reason });
+                        }
+                        break;
+                    }
                 }
-                return await this.handleSearch(query, project, limit, search_type, mode);
+                return { content: [{ type: 'text', text: `Unknown action` }], isError: true };
             }
             catch (error) {
                 return {
-                    content: [{ type: 'text', text: this.formatErrorMessage('Search', error instanceof Error ? error : String(error), { projectPath: project }) }],
+                    content: [{ type: 'text', text: this.formatErrorMessage('CodeSeeker', error instanceof Error ? error : String(error), { projectPath: params.project }) }],
                     isError: true,
                 };
             }
         });
     }
-    async handleSearch(query, project, limit, search_type, mode) {
-        const { projectPath, projectRecord, error } = await this.resolveProject(project);
-        if (error)
-            return error;
-        const indexCheck = await this.verifyIndexed(projectPath, projectRecord);
-        if (indexCheck.error)
-            return indexCheck.error;
-        // Check cache (only for 'full' mode)
-        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;
+    /** Extract the first meaningful declaration line from a code chunk */
+    extractSignature(content) {
+        const skip = /^\s*($|\/\/|\/\*|\*|#!|import |from |require\(|using |namespace )/;
+        for (const line of content.split('\n')) {
+            if (!skip.test(line))
+                return line.trim().substring(0, 120);
+        }
+        return content.split('\n')[0]?.trim().substring(0, 120) || '';
+    }
+    // ── Public test-accessible handlers ───────────────────────────────────────
+    // ── Public test-accessible handlers ───────────────────────────────────────
+    /** Search and return file contents for top results. Used by tests via `as any`. */
+    async handleSearchAndRead(query, project, limit, tokenBudget) {
+        const inner = await this.handleSearch(query, project, limit, 'hybrid', false, false);
+        const text = inner.content[0]?.type === 'text' ? inner.content[0].text : '';
+        try {
+            const parsed = JSON.parse(text);
+            if (!parsed.results) {
+                return { content: [{ type: 'text', text: JSON.stringify({ query, project, files_found: 0, results: [] }) }], isError: false };
             }
-            else {
-                results = await this.searchOrchestrator.performSemanticSearch(query, projectPath, search_type);
-                if (results.length > 0) {
-                    await this.queryCache.set(query, cacheProjectId, results, search_type);
+            const charBudget = tokenBudget * 4;
+            let remaining = charBudget;
+            const results = parsed.results.map((r) => {
+                const filepath = r.file && require('path').isAbsolute(r.file) ? r.file
+                    : require('path').join(parsed.project_path ?? '', r.file);
+                let content = '';
+                try {
+                    const raw = require('fs').readFileSync(filepath, 'utf-8');
+                    content = raw.substring(0, Math.min(raw.length, remaining));
+                    remaining = Math.max(0, remaining - content.length);
                 }
-            }
+                catch {
+                    content = '';
+                }
+                return { file: r.file, score: r.score, content };
+            });
+            return { content: [{ type: 'text', text: JSON.stringify({ query, project, files_found: results.length, results }) }], isError: false };
         }
-        else {
-            results = await this.searchOrchestrator.performSemanticSearch(query, projectPath, search_type);
+        catch {
+            return { content: [{ type: 'text', text: JSON.stringify({ query, project, files_found: 0, results: [] }) }], isError: false };
         }
-        const limitedResults = results.slice(0, mode === 'exists' ? 5 : limit);
-        if (limitedResults.length === 0) {
-            if (mode === 'exists') {
-                return {
-                    content: [{ type: 'text', text: JSON.stringify({ exists: false, query, project: projectPath, message: 'No matching code found' }, null, 2) }],
-                };
+    }
+    /** Read a file from disk and return its content. Used by tests via `as any`. */
+    async handleReadWithContext(filepath, _project, includeSummary) {
+        const fs = require('fs');
+        try {
+            const content = fs.readFileSync(filepath, 'utf-8');
+            const lineCount = content.split('\n').length;
+            const resp = {
+                file: filepath,
+                filepath,
+                content,
+                line_count: lineCount,
+            };
+            if (includeSummary) {
+                resp.related_chunks = []; // graph neighbors not available in disk-only mode
             }
             return {
-                content: [{ type: 'text', text: `No results for: "${query}". Try different terms or reindex.` }],
+                content: [{ type: 'text', text: JSON.stringify(resp) }],
+                isError: false
             };
         }
-        if (mode === 'exists') {
-            const topResult = limitedResults[0];
-            const absolutePath = path.isAbsolute(topResult.file) ? topResult.file : path.join(projectPath, topResult.file);
+        catch {
             return {
-                content: [{ type: 'text', text: JSON.stringify({
-                            exists: true, query, project: projectPath,
-                            total_matches: results.length, top_file: absolutePath,
-                            top_score: Math.round(topResult.similarity * 100) / 100,
-                        }, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify({ file: filepath, error: 'File not found' }) }],
+                isError: true
             };
         }
-        const formattedResults = limitedResults.map((r, i) => {
-            const absolutePath = path.isAbsolute(r.file) ? r.file : path.join(projectPath, r.file);
-            return {
-                rank: i + 1,
-                file: absolutePath,
-                relative_path: r.file,
-                score: Math.round(r.similarity * 100) / 100,
-                type: r.type,
-                match_source: r.debug?.matchSource || 'hybrid',
-                chunk: r.content.substring(0, 500) + (r.content.length > 500 ? '...' : ''),
-                lines: r.lineStart && r.lineEnd ? `${r.lineStart}-${r.lineEnd}` : undefined,
-            };
-        });
-        const wasLimited = results.length > limit;
-        const response = {
-            query, project: projectPath,
-            total_results: limitedResults.length,
-            search_type, results: formattedResults,
-        };
-        if (fromCache)
-            response.cached = true;
-        if (wasLimited) {
-            response.truncated = true;
-            response.total_available = results.length;
-        }
-        return { content: [{ type: 'text', text: JSON.stringify(response, null, 2) }] };
     }
-    async handleSearchAndRead(query, project, max_files, max_lines) {
-        const fileLimit = Math.min(max_files, 3);
-        const lineLimit = Math.min(max_lines, 1000);
+    async handleSearch(query, project, limit, search_type, exists, full) {
         const { projectPath, projectRecord, error } = await this.resolveProject(project);
         if (error)
             return error;
         const indexCheck = await this.verifyIndexed(projectPath, projectRecord);
         if (indexCheck.error)
             return indexCheck.error;
-        const results = await this.searchOrchestrator.performSemanticSearch(query, projectPath);
-        if (results.length === 0) {
-            return {
-                content: [{ type: 'text', text: JSON.stringify({ query, project: projectPath, found: false, message: 'No matching code found.' }, null, 2) }],
-            };
-        }
-        // Get unique files
-        const seenFiles = new Set();
-        const uniqueResults = [];
-        for (const r of results) {
-            const normalizedPath = r.file.replace(/\\/g, '/');
-            if (!seenFiles.has(normalizedPath)) {
-                seenFiles.add(normalizedPath);
-                uniqueResults.push(r);
-                if (uniqueResults.length >= fileLimit)
-                    break;
-            }
-        }
-        const files = [];
-        for (const result of uniqueResults) {
-            const absolutePath = path.isAbsolute(result.file) ? result.file : path.join(projectPath, result.file);
-            try {
-                if (!fs.existsSync(absolutePath))
-                    continue;
-                const content = fs.readFileSync(absolutePath, 'utf-8');
-                const lines = content.split('\n');
-                const truncated = lines.length > lineLimit;
-                const displayLines = truncated ? lines.slice(0, lineLimit) : lines;
-                const numberedContent = displayLines.map((line, i) => `${String(i + 1).padStart(4)}│ ${line}`).join('\n');
-                files.push({
-                    file: absolutePath,
-                    relative_path: result.file,
-                    score: Math.round(result.similarity * 100) / 100,
-                    file_type: result.type,
-                    match_source: result.debug?.matchSource || 'hybrid',
-                    line_count: lines.length,
-                    content: numberedContent + (truncated ? `\n... (truncated at ${lineLimit} lines)` : ''),
-                    truncated,
-                });
-            }
-            catch {
-                continue;
+        const cacheProjectId = projectRecord?.id || this.generateProjectId(projectPath);
+        const cap = exists ? 5 : limit;
+        // exists mode: skip cache, quick check
+        if (exists) {
+            const results = await this.searchOrchestrator.performSemanticSearch(query, projectPath, search_type);
+            if (results.length === 0) {
+                return { content: [{ type: 'text', text: JSON.stringify({ found: false, query }) }] };
             }
-        }
-        if (files.length === 0) {
+            const top = results[0];
             return {
-                content: [{ type: 'text', text: JSON.stringify({ query, project: projectPath, found: true, readable: false, message: 'Found matching files but could not read them.' }, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify({
+                            found: true, count: results.length,
+                            top_file: path.relative(projectPath, path.isAbsolute(top.file) ? top.file : path.join(projectPath, top.file)),
+                            score: Math.round(top.similarity * 100) / 100,
+                        }) }],
             };
         }
-        return {
-            content: [{ type: 'text', text: JSON.stringify({
-                        query, project: projectPath,
-                        files_found: results.length, files_returned: files.length,
-                        results: files,
-                    }, null, 2) }],
-        };
-    }
-    async handleReadWithContext(filepath, project, include_related) {
-        const storageManager = await (0, storage_1.getStorageManager)();
-        const projectStore = storageManager.getProjectStore();
-        let projectPath;
-        if (project) {
-            const projects = await projectStore.list();
-            const found = projects.find(p => p.name === project || p.path === project || path.basename(p.path) === project);
-            projectPath = found?.path || process.cwd();
+        // full search — use cache
+        let results;
+        let fromCache = false;
+        const cached = await this.queryCache.get(query, cacheProjectId, search_type);
+        if (cached) {
+            results = cached.results;
+            fromCache = true;
         }
         else {
-            projectPath = process.cwd();
+            results = await this.searchOrchestrator.performSemanticSearch(query, projectPath, search_type);
+            if (results.length > 0)
+                await this.queryCache.set(query, cacheProjectId, results, search_type);
         }
-        const absolutePath = path.isAbsolute(filepath) ? filepath : path.join(projectPath, filepath);
-        if (!fs.existsSync(absolutePath)) {
-            return { content: [{ type: 'text', text: `File not found: ${absolutePath}` }], isError: true };
-        }
-        const content = fs.readFileSync(absolutePath, 'utf-8');
-        let relatedChunks = [];
-        if (include_related) {
-            const lines = content.split('\n');
-            const meaningfulLines = [];
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed)
-                    continue;
-                if (trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*'))
-                    continue;
-                if (trimmed.startsWith('import ') || trimmed.startsWith('from ') || trimmed.startsWith('require('))
-                    continue;
-                if (trimmed.startsWith('#') && !trimmed.startsWith('##'))
-                    continue;
-                if (trimmed.startsWith('using ') || trimmed.startsWith('namespace '))
-                    continue;
-                meaningfulLines.push(trimmed);
-                if (meaningfulLines.length >= 5)
-                    break;
-            }
-            const fileName = path.basename(filepath);
-            const fileNameQuery = fileName.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
-            const contentQuery = meaningfulLines.join(' ').substring(0, 200);
-            const searchQuery = `${fileNameQuery} ${contentQuery}`.trim();
-            const results = await this.searchOrchestrator.performSemanticSearch(searchQuery || fileNameQuery, projectPath);
-            relatedChunks = results
-                .filter(r => !r.file.endsWith(path.basename(filepath)))
-                .slice(0, 5)
-                .map(r => ({
-                file: r.file,
-                chunk: r.content.substring(0, 300) + (r.content.length > 300 ? '...' : ''),
-                score: Math.round(r.similarity * 100) / 100,
-            }));
+        if (results.length === 0) {
+            return { content: [{ type: 'text', text: `No results for: "${query}". Try different terms or reindex.` }] };
         }
-        return {
-            content: [{ type: 'text', text: JSON.stringify({
-                        filepath: path.relative(projectPath, absolutePath),
-                        content: content.length > 10000 ? content.substring(0, 10000) + '\n... (truncated)' : content,
-                        line_count: content.split('\n').length,
-                        related_chunks: include_related ? relatedChunks : undefined,
-                    }, null, 2) }],
+        const limited = results.slice(0, cap);
+        const formatted = limited.map((r, i) => {
+            const rel = path.isAbsolute(r.file) ? path.relative(projectPath, r.file) : r.file;
+            const node = {
+                rank: i + 1,
+                file: rel,
+                score: Math.round(r.similarity * 100) / 100,
+                lines: r.lineStart && r.lineEnd ? `${r.lineStart}-${r.lineEnd}` : undefined,
+                sig: this.extractSignature(r.content),
+            };
+            if (full)
+                node.snippet = r.content.substring(0, 300) + (r.content.length > 300 ? '…' : '');
+            return node;
+        });
+        const resp = {
+            query, project: path.basename(projectPath),
+            count: limited.length, results: formatted,
         };
+        if (fromCache)
+            resp.cached = true;
+        if (results.length > cap) {
+            resp.more = results.length - cap;
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(resp) }] };
     }
     // ============================================================
-    // TOOL 2: analyze
-    //   Combines: show_dependencies, find_duplicates, find_dead_code, standards
+    // HANDLERS: graph, duplicates, dead_code, standards
     // ============================================================
-    registerAnalyzeTool() {
-        this.server.registerTool('analyze', {
-            description: 'Code analysis. Actions: "dependencies" (imports/calls/extends graph), ' +
-                '"dead_code" (unused code, anti-patterns), "duplicates" (similar code), ' +
-                '"standards" (auto-detected coding patterns).',
-            inputSchema: {
-                action: zod_1.z.enum(['dependencies', 'dead_code', 'duplicates', 'standards']).describe('Analysis type'),
-                project: zod_1.z.string().describe('Project path or name'),
-                // dependencies params
-                filepath: zod_1.z.string().optional().describe('File for dependency analysis'),
-                filepaths: zod_1.z.array(zod_1.z.string()).optional().describe('Multiple files for dependency analysis'),
-                query: zod_1.z.string().optional().describe('Search query to find seed files for dependencies'),
-                depth: zod_1.z.number().optional().default(1).describe('Relationship hops (1-3)'),
-                relationship_types: zod_1.z.array(zod_1.z.enum([
-                    'imports', 'exports', 'calls', 'extends', 'implements', 'contains', 'uses', 'depends_on'
-                ])).optional().describe('Filter relationship types'),
-                direction: zod_1.z.enum(['in', 'out', 'both']).optional().default('both').describe('Relationship direction'),
-                max_nodes: zod_1.z.number().optional().default(50).describe('Max nodes'),
-                // duplicates params
-                similarity_threshold: zod_1.z.number().optional().default(0.80).describe('Min similarity for duplicates (0-1)'),
-                min_lines: zod_1.z.number().optional().default(5).describe('Min lines for duplicate analysis'),
-                // dead_code params
-                include_patterns: zod_1.z.array(zod_1.z.enum(['dead_code', 'god_class', 'circular_deps', 'feature_envy', 'coupling'])).optional()
-                    .describe('Anti-patterns to detect'),
-                // standards params
-                category: zod_1.z.enum(['validation', 'error-handling', 'logging', 'testing', 'all']).optional().default('all')
-                    .describe('Standards category'),
-            },
-        }, async (params) => {
-            try {
-                switch (params.action) {
-                    case 'dependencies':
-                        return await this.handleShowDependencies(params);
-                    case 'dead_code':
-                        return await this.handleFindDeadCode(params);
-                    case 'duplicates':
-                        return await this.handleFindDuplicates(params);
-                    case 'standards':
-                        return await this.handleStandards(params);
-                    default:
-                        return { content: [{ type: 'text', text: `Unknown action: ${params.action}` }], isError: true };
-                }
-            }
-            catch (error) {
-                return {
-                    content: [{ type: 'text', text: this.formatErrorMessage('Analyze', error instanceof Error ? error : String(error), { projectPath: params.project }) }],
-                    isError: true,
-                };
-            }
-        });
-    }
     async handleShowDependencies(params) {
         const { filepath, filepaths, query, depth = 1, relationship_types, direction = 'both', max_nodes = 50, project } = params;
         const storageManager = await (0, storage_1.getStorageManager)();
@@ -737,7 +688,7 @@ class CodeSeekerMcpServer {
             }
         }
         if (!projectId) {
-            return { content: [{ type: 'text', text: 'Project not indexed. Use index({action: "init"}) first.' }], isError: true };
+            return { content: [{ type: 'text', text: 'Project not indexed. Run codeseeker({action:"index",index:{op:"init",path:"..."}}) first.' }], isError: true };
         }
         // Determine seed file paths
         let seedFilePaths = [];
@@ -860,7 +811,7 @@ class CodeSeekerMcpServer {
                 ].filter(Boolean),
             };
         }
-        return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(summary) }] };
     }
     async handleFindDuplicates(params) {
         const { project, similarity_threshold = 0.80, min_lines = 5 } = params;
@@ -979,21 +930,46 @@ class CodeSeekerMcpServer {
         const deadCodeItems = [];
         const antiPatternItems = [];
         const couplingItems = [];
+        // Entry-point name fragments — files/symbols with these names are never flagged as dead.
+        // Covers common naming conventions across frameworks and languages.
+        const ENTRY_POINT_NAMES = ['main', 'index', 'app', 'server', 'cli', 'worker', 'bin', 'entry', 'bootstrap', 'start', 'init', 'run', 'launch'];
+        const isEntryPointName = (name) => {
+            const lower = name.toLowerCase();
+            return ENTRY_POINT_NAMES.some(ep => lower === ep || lower.startsWith(ep + '.') || lower.endsWith('/' + ep));
+        };
         for (const node of allNodes) {
             const inEdges = await graphStore.getEdges(node.id, 'in');
             const outEdges = await graphStore.getEdges(node.id, 'out');
             if (patterns.includes('dead_code')) {
-                const isEntryPoint = node.type === 'file' ||
-                    node.name.toLowerCase().includes('main') ||
-                    node.name.toLowerCase().includes('index') ||
-                    node.name.toLowerCase().includes('app');
-                if (!isEntryPoint && (node.type === 'class' || node.type === 'function') && inEdges.length === 0) {
+                // Files are handled separately in the orphaned-files pass below.
+                if (node.type === 'class' || node.type === 'function') {
+                    if (isEntryPointName(node.name) || isEntryPointName(node.filePath))
+                        continue;
+                    if (inEdges.length > 0)
+                        continue;
+                    // Read export and visibility metadata stored by the graph builder.
+                    const props = node.properties;
+                    const isExported = props?.isExported === true || props?.is_exported === true;
+                    const visibility = props?.visibility ?? 'unknown';
+                    // Exported symbols may be consumed by other packages — skip, don't guess.
+                    if (isExported)
+                        continue;
+                    // Tier confidence by how much we know about visibility.
+                    // private/internal with no callers: strong signal.
+                    // public/unknown unexported: moderate signal (dynamic dispatch, callbacks possible).
+                    const isPrivate = visibility === 'private' || visibility === 'internal';
+                    const confidence = isPrivate ? '85%' : '60%';
+                    const caveat = isPrivate
+                        ? 'Not exported and no detected callers.'
+                        : 'Not exported and no detected static callers — dynamic dispatch or callbacks may still use this.';
                     deadCodeItems.push({
-                        type: 'Dead Code', name: node.name,
+                        type: 'Unreferenced Symbol', name: node.name,
                         file: path.relative(projectRecord.path, node.filePath),
-                        description: `Unused ${node.type}: ${node.name} - no incoming references`,
-                        confidence: '70%', impact: 'medium',
-                        recommendation: 'Review if needed. Remove if unused or add to exports.',
+                        description: `${node.type} "${node.name}" has no incoming static references. ${caveat}`,
+                        confidence, impact: 'low',
+                        recommendation: isPrivate
+                            ? 'Safe to remove if no dynamic usage (reflection, eval, plugin system).'
+                            : 'Verify no dynamic callers before removing. Consider exporting if used externally.',
                     });
                 }
             }
@@ -1023,6 +999,37 @@ class CodeSeekerMcpServer {
                 }
             }
         }
+        // Orphaned-file detection — uses import edges only (the most reliable graph signal).
+        // A file with no inbound imports from within the project and no entry-point name is
+        // a strong candidate for removal. Confidence is higher than symbol-level dead code
+        // because import edges are static and unambiguous.
+        const orphanedFiles = [];
+        if (patterns.includes('dead_code')) {
+            const fileNodes = allNodes.filter(n => n.type === 'file');
+            // Build inbound import count per file node
+            const inboundImportCount = new Map(fileNodes.map(n => [n.id, 0]));
+            for (const fileNode of fileNodes) {
+                const outEdges = await graphStore.getEdges(fileNode.id, 'out');
+                for (const edge of outEdges) {
+                    if (edge.type === 'imports' && inboundImportCount.has(edge.target)) {
+                        inboundImportCount.set(edge.target, (inboundImportCount.get(edge.target) ?? 0) + 1);
+                    }
+                }
+            }
+            for (const fileNode of fileNodes) {
+                if (isEntryPointName(fileNode.name) || isEntryPointName(fileNode.filePath))
+                    continue;
+                if ((inboundImportCount.get(fileNode.id) ?? 0) === 0) {
+                    const relPath = path.relative(projectRecord.path, fileNode.filePath);
+                    orphanedFiles.push({
+                        file: relPath,
+                        description: `No other project file imports "${fileNode.name}". Could be an entry point, script, or dead file.`,
+                        confidence: '80%',
+                        recommendation: 'Verify this is not an entry point, CLI script, or plugin. Remove if truly unused.',
+                    });
+                }
+            }
+        }
         // Circular dependency detection
         if (patterns.includes('circular_deps')) {
             const fileNodes = allNodes.filter(n => n.type === 'file');
@@ -1060,13 +1067,21 @@ class CodeSeekerMcpServer {
                             classes: allNodes.filter(n => n.type === 'class').length,
                             functions: allNodes.filter(n => n.type === 'function').length,
                         },
+                        // Limitations of static graph analysis — AI should consider these before acting.
+                        graph_limitations: [
+                            'Call edges use regex heuristics — dynamic dispatch, callbacks, and event handlers are not detected.',
+                            'Export status is only reliable for TypeScript/JS (Babel AST). Other languages use conventions.',
+                            'Symbols consumed by external packages will appear unreferenced.',
+                        ],
                         summary: {
-                            total_issues: deadCodeItems.length + antiPatternItems.length + couplingItems.length,
-                            dead_code_count: deadCodeItems.length,
+                            total_issues: deadCodeItems.length + orphanedFiles.length + antiPatternItems.length + couplingItems.length,
+                            unreferenced_symbols: deadCodeItems.length,
+                            orphaned_files: orphanedFiles.length,
                             anti_patterns_count: antiPatternItems.length,
                             coupling_issues_count: couplingItems.length,
                         },
                         dead_code: deadCodeItems.slice(0, 20),
+                        orphaned_files: orphanedFiles.slice(0, 20),
                         anti_patterns: antiPatternItems.slice(0, 10),
                         coupling_issues: couplingItems.slice(0, 10),
                     }, null, 2) }],
@@ -1108,60 +1123,11 @@ class CodeSeekerMcpServer {
         if (category !== 'all') {
             result = { ...standards, standards: { [category]: standards.standards[category] || {} } };
         }
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }
     // ============================================================
-    // TOOL 3: index
-    //   Combines: index (init), sync, projects (status), install_parsers, exclude
+    // HANDLERS: index management
     // ============================================================
-    registerIndexTool() {
-        this.server.registerTool('index', {
-            description: 'Index management. Actions: "init" (index project), "sync" (update changed files), ' +
-                '"status" (list projects), "parsers" (install language parsers), "exclude" (manage exclusions).',
-            inputSchema: {
-                action: zod_1.z.enum(['init', 'sync', 'status', 'parsers', 'exclude']).describe('Action'),
-                path: zod_1.z.string().optional().describe('Project directory (for init)'),
-                project: zod_1.z.string().optional().describe('Project name or path'),
-                name: zod_1.z.string().optional().describe('Project name (for init)'),
-                // sync params
-                changes: zod_1.z.array(zod_1.z.object({
-                    type: zod_1.z.enum(['created', 'modified', 'deleted']),
-                    path: zod_1.z.string(),
-                })).optional().describe('File changes for sync'),
-                full_reindex: zod_1.z.boolean().optional().default(false).describe('Full reindex'),
-                // parsers params
-                languages: zod_1.z.array(zod_1.z.string()).optional().describe('Languages to install parsers for'),
-                list_available: zod_1.z.boolean().optional().default(false).describe('List available parsers'),
-                // exclude params
-                exclude_action: zod_1.z.enum(['exclude', 'include', 'list']).optional().describe('Exclusion sub-action'),
-                paths: zod_1.z.array(zod_1.z.string()).optional().describe('Paths/patterns to exclude/include'),
-                reason: zod_1.z.string().optional().describe('Exclusion reason'),
-            },
-        }, async (params) => {
-            try {
-                switch (params.action) {
-                    case 'init':
-                        return await this.handleIndexInit(params);
-                    case 'sync':
-                        return await this.handleSync(params);
-                    case 'status':
-                        return await this.handleProjects();
-                    case 'parsers':
-                        return await this.handleInstallParsers(params);
-                    case 'exclude':
-                        return await this.handleExclude(params);
-                    default:
-                        return { content: [{ type: 'text', text: `Unknown action: ${params.action}` }], isError: true };
-                }
-            }
-            catch (error) {
-                return {
-                    content: [{ type: 'text', text: this.formatErrorMessage('Index', error instanceof Error ? error : String(error), { projectPath: params.path || params.project }) }],
-                    isError: true,
-                };
-            }
-        });
-    }
     async handleIndexInit(params) {
         const projectPath = params.path;
         if (!projectPath) {
@@ -1530,6 +1496,82 @@ class CodeSeekerMcpServer {
         }
         return { content: [{ type: 'text', text: `Unknown exclude_action: ${exclude_action}` }], isError: true };
     }
+    async handleSymbolLookup(sym, project, full) {
+        const storageManager = await (0, storage_1.getStorageManager)();
+        const projectStore = storageManager.getProjectStore();
+        const graphStore = storageManager.getGraphStore();
+        let projectId;
+        let projectPath;
+        if (project) {
+            const projects = await projectStore.list();
+            const found = projects.find(p => p.name === project || p.path === project || path.basename(p.path) === project);
+            if (found) {
+                projectId = found.id;
+                projectPath = found.path;
+            }
+            else
+                projectPath = process.cwd();
+        }
+        else {
+            projectPath = process.cwd();
+            const projects = await projectStore.list();
+            const found = projects.find(p => p.path === projectPath || path.basename(p.path) === path.basename(projectPath));
+            if (found) {
+                projectId = found.id;
+                projectPath = found.path;
+            }
+        }
+        if (!projectId) {
+            return { content: [{ type: 'text', text: 'Project not indexed. Run codeseeker({action:"index",index:{op:"init",path:"..."}}) first.' }], isError: true };
+        }
+        const allNodes = await graphStore.findNodes(projectId);
+        const symLower = sym.toLowerCase();
+        // Exact matches first, then partial — exclude file nodes (they add noise)
+        const exact = allNodes.filter(n => n.type !== 'file' && n.name.toLowerCase() === symLower);
+        const partial = allNodes.filter(n => n.type !== 'file' && n.name.toLowerCase() !== symLower && n.name.toLowerCase().includes(symLower));
+        const matches = [...exact, ...partial].slice(0, 20);
+        if (matches.length === 0) {
+            return { content: [{ type: 'text', text: JSON.stringify({ found: false, sym }) }] };
+        }
+        // Build a node-ID → {name,type,file} map for peer resolution (only load what we need)
+        const nodeCache = new Map();
+        const resolveNode = async (id) => {
+            if (nodeCache.has(id))
+                return nodeCache.get(id);
+            const n = await graphStore.getNode(id);
+            if (!n)
+                return null;
+            const rel = n.properties?.relativePath || path.relative(projectPath, n.filePath);
+            const entry = { name: n.name, type: n.type, file: rel };
+            nodeCache.set(id, entry);
+            return entry;
+        };
+        const symbols = await Promise.all(matches.map(async (n) => {
+            const rel = n.properties?.relativePath || path.relative(projectPath, n.filePath);
+            const edges = await graphStore.getEdges(n.id, 'both');
+            const entry = {
+                name: n.name,
+                type: n.type,
+                file: rel,
+                in: edges.filter(e => e.target === n.id).length,
+                out: edges.filter(e => e.source === n.id).length,
+            };
+            if (full) {
+                const resolved = await Promise.all(edges.slice(0, 5).map(async (e) => {
+                    const peerId = e.source === n.id ? e.target : e.source;
+                    const peer = await resolveNode(peerId);
+                    return peer ? { rel: e.type, dir: e.source === n.id ? 'out' : 'in', ...peer } : null;
+                }));
+                entry.edges = resolved.filter(Boolean);
+            }
+            return entry;
+        }));
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        sym, count: matches.length, symbols,
+                    }) }],
+        };
+    }
     // ============================================================
     // SERVER LIFECYCLE
     // ============================================================