grepmax 0.18.1 → 0.20.0

package/dist/commands/mcp.js

@@ -53,16 +53,18 @@ exports.mcp = void 0;
 exports.toStringArray = toStringArray;
 exports.ok = ok;
 exports.err = err;
+exports.searchResultPath = searchResultPath;
+exports.searchResultStartLine = searchResultStartLine;
+exports.searchResultEndLine = searchResultEndLine;
 exports.filterMcpSearchResults = filterMcpSearchResults;
 exports.formatMcpPointerSearchResults = formatMcpPointerSearchResults;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
-const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
 const commander_1 = require("commander");
+const zod_1 = require("zod");
 const config_1 = require("../config");
-const audit_1 = require("./audit");
 const graph_builder_1 = require("../lib/graph/graph-builder");
 const index_config_1 = require("../lib/index/index-config");
 const syncer_1 = require("../lib/index/syncer");
@@ -82,482 +84,7 @@ const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 const watcher_launcher_1 = require("../lib/utils/watcher-launcher");
 const watcher_store_1 = require("../lib/utils/watcher-store");
-// ---------------------------------------------------------------------------
-// Tool definitions
-// ---------------------------------------------------------------------------
-const TOOLS = [
-    {
-        name: "semantic_search",
-        description: "Search code by meaning. Use scope:'all' for cross-project. Prefer CLI: gmax \"query\" --plain",
-        inputSchema: {
-            type: "object",
-            properties: {
-                query: {
-                    type: "string",
-                    description: "Natural language query (5+ words recommended)",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max results (default 3, max 50)",
-                },
-                root: {
-                    type: "string",
-                    description: "Search a different directory (absolute path)",
-                },
-                path: {
-                    type: "string",
-                    description: "Path prefix filter (e.g. 'src/auth/')",
-                },
-                detail: {
-                    type: "string",
-                    description: "'pointer' (default), 'code', or 'full'",
-                },
-                min_score: { type: "number", description: "Min score 0-1 (default 0)" },
-                max_per_file: { type: "number", description: "Max results per file" },
-                file: {
-                    type: "string",
-                    description: "Filename filter (e.g. 'syncer.ts')",
-                },
-                exclude: {
-                    type: "string",
-                    description: "Exclude path prefix (e.g. 'tests/')",
-                },
-                language: {
-                    type: "string",
-                    description: "Extension filter (e.g. 'ts', 'py')",
-                },
-                role: {
-                    type: "string",
-                    description: "'ORCHESTRATION', 'DEFINITION', or 'IMPLEMENTATION'",
-                },
-                context_lines: {
-                    type: "number",
-                    description: "Lines before/after chunk (max 20)",
-                },
-                mode: {
-                    type: "string",
-                    description: "'default' or 'symbol' (appends call graph)",
-                },
-                include_imports: {
-                    type: "boolean",
-                    description: "Prepend file imports to results",
-                },
-                name_pattern: {
-                    type: "string",
-                    description: "Regex filter on symbol name",
-                },
-                scope: {
-                    type: "string",
-                    description: "'project' (default) or 'all' (search everything)",
-                },
-                projects: {
-                    type: "string",
-                    description: "Project names to include (comma-separated)",
-                },
-                exclude_projects: {
-                    type: "string",
-                    description: "Project names to exclude (comma-separated)",
-                },
-                seed_files: {
-                    type: "string",
-                    description: "Bias results toward your working context: comma-separated paths you have open (e.g. 'src/lib/llm/server.ts'). On-topic chunks in these files get lifted; off-topic ones are not.",
-                },
-                seed_symbols: {
-                    type: "string",
-                    description: "Bias results toward identifiers you're working with: comma-separated symbol names. Chunks defining a seeded symbol are preferred over mere callers.",
-                },
-            },
-            required: ["query"],
-        },
-    },
-    {
-        name: "code_skeleton",
-        description: "File structure with bodies collapsed (~4x fewer tokens). Accepts file, directory, or comma-separated paths.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                target: {
-                    type: "string",
-                    description: "File, directory, or comma-separated paths",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max files for directory mode (default 10)",
-                },
-                format: { type: "string", description: "'text' (default) or 'json'" },
-            },
-            required: ["target"],
-        },
-    },
-    {
-        name: "trace_calls",
-        description: "Call graph: importers, callers (multi-hop), callees with file:line.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                symbol: { type: "string", description: "Function/class name to trace" },
-                depth: {
-                    type: "number",
-                    description: "Caller depth (default 1, max 3)",
-                },
-            },
-            required: ["symbol"],
-        },
-    },
-    {
-        name: "extract_symbol",
-        description: "Extract complete function/class body by symbol name.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                symbol: { type: "string", description: "Symbol name to extract" },
-                root: { type: "string", description: "Project root (absolute path)" },
-                include_imports: {
-                    type: "boolean",
-                    description: "Prepend file imports",
-                },
-            },
-            required: ["symbol"],
-        },
-    },
-    {
-        name: "peek_symbol",
-        description: "Compact symbol overview: signature + callers + callees.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                symbol: { type: "string", description: "Symbol name" },
-                root: { type: "string", description: "Project root (absolute path)" },
-                depth: {
-                    type: "number",
-                    description: "Caller depth (default 1, max 3)",
-                },
-            },
-            required: ["symbol"],
-        },
-    },
-    {
-        name: "dead",
-        description: "Report whether a symbol has zero inbound callers in the indexed call graph. Returns DEAD, PUBLIC EXPORT (exported with no internal callers), or LIVE with caller count. Hypothesis, not proof: dynamic dispatch, reflection, and string-built call sites won't show up.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                symbol: { type: "string", description: "Symbol name to check" },
-                root: { type: "string", description: "Project root (absolute path)" },
-            },
-            required: ["symbol"],
-        },
-    },
-    {
-        name: "audit",
-        description: "Graph-summary of the indexed project in one call: god nodes (most depended-upon symbols), hub files (most depended-upon files), and dead-code candidates (non-exported symbols with zero inbound references). Built from the static call graph — dynamic dispatch, reflection, eval, and type-position-only references are invisible, so dead candidates are hypotheses; verify with the `dead` tool before acting.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                root: {
-                    type: "string",
-                    description: "Project root (default: current)",
-                },
-                top: {
-                    type: "number",
-                    description: "How many of each category to return (default 10)",
-                },
-            },
-        },
-    },
-    {
-        name: "get_neighbors",
-        description: "Graph primitive: symbols reachable from a node along call edges within N hops. direction 'callees' = what it calls (outbound), 'callers' = what calls it (inbound). Each result carries its hop distance and definition location. Static call graph — same caveats as `dead`/`audit`.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                symbol: { type: "string", description: "Starting symbol" },
-                direction: {
-                    type: "string",
-                    enum: ["callers", "callees"],
-                    description: "Edge direction (default callees)",
-                },
-                max_hops: {
-                    type: "number",
-                    description: "Max hops (default 2, max 5)",
-                },
-                root: { type: "string", description: "Project root (absolute path)" },
-            },
-            required: ["symbol"],
-        },
-    },
-    {
-        name: "find_paths",
-        description: "Graph primitive: shortest call-graph path between two symbols, as a symbol sequence. direction 'callees' searches outward from `from` (does `from` transitively call `to`?), 'callers' searches inward. Returns 'no path' if unreachable within max_hops.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                from: { type: "string", description: "Start symbol" },
-                to: { type: "string", description: "Target symbol" },
-                direction: {
-                    type: "string",
-                    enum: ["callers", "callees"],
-                    description: "Search direction (default callees)",
-                },
-                max_hops: {
-                    type: "number",
-                    description: "Max hops (default 6, max 10)",
-                },
-                root: { type: "string", description: "Project root (absolute path)" },
-            },
-            required: ["from", "to"],
-        },
-    },
-    {
-        name: "subgraph_for_files",
-        description: "Graph primitive: the local dependency subgraph for a set of files — symbols they define, the call edges among those symbols, and their outbound external dependencies. Paths may be absolute or project-root-relative.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                files: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "File paths (absolute or root-relative)",
-                },
-                root: { type: "string", description: "Project root (absolute path)" },
-            },
-            required: ["files"],
-        },
-    },
-    {
-        name: "list_symbols",
-        description: "List indexed symbols with role and export status.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                pattern: {
-                    type: "string",
-                    description: "Name filter (case-insensitive)",
-                },
-                limit: { type: "number", description: "Max results (default 20)" },
-                path: { type: "string", description: "Path prefix filter" },
-            },
-        },
-    },
-    {
-        name: "index_status",
-        description: "Index health: chunks, files, projects, watcher status.",
-        inputSchema: { type: "object", properties: {} },
-        _meta: { "anthropic/alwaysLoad": true },
-    },
-    {
-        name: "summarize_directory",
-        description: "Generate LLM summaries for indexed chunks.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: {
-                    type: "string",
-                    description: "Directory to summarize (default: project root)",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max chunks (default 200, max 5000)",
-                },
-            },
-        },
-    },
-    {
-        name: "summarize_project",
-        description: "Project overview: languages, structure, roles, key symbols, entry points.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                root: {
-                    type: "string",
-                    description: "Project root (default: current)",
-                },
-            },
-        },
-    },
-    {
-        name: "related_files",
-        description: "Find dependencies and dependents of a file by shared symbols.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                file: {
-                    type: "string",
-                    description: "File path relative to project root",
-                },
-                limit: {
-                    type: "number",
-                    description: "Max results per direction (default 10)",
-                },
-            },
-            required: ["file"],
-        },
-    },
-    {
-        name: "recent_changes",
-        description: "Recently modified indexed files with timestamps.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                limit: {
-                    type: "number",
-                    description: "Max files to return (default 20)",
-                },
-                root: {
-                    type: "string",
-                    description: "Project root (defaults to current project)",
-                },
-            },
-        },
-    },
-    {
-        name: "diff_changes",
-        description: "Search code scoped to git changes. Omit ref for uncommitted changes.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                ref: {
-                    type: "string",
-                    description: "Git ref to diff against (e.g. main, HEAD~5)",
-                },
-                query: {
-                    type: "string",
-                    description: "Semantic search within changed files",
-                },
-                limit: { type: "number", description: "Max results (default 10)" },
-                role: {
-                    type: "string",
-                    description: "Filter by role: ORCHESTRATION, DEFINITION, IMPLEMENTATION",
-                },
-            },
-        },
-    },
-    {
-        name: "find_tests",
-        description: "Find tests that exercise a symbol or file via reverse call graph.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                target: { type: "string", description: "Symbol name or file path" },
-                depth: {
-                    type: "number",
-                    description: "Caller traversal depth 1-3 (default 1)",
-                },
-            },
-            required: ["target"],
-        },
-    },
-    {
-        name: "impact_analysis",
-        description: "Change impact: dependents and affected tests for a symbol or file.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                target: { type: "string", description: "Symbol name or file path" },
-                depth: {
-                    type: "number",
-                    description: "Caller traversal depth 1-3 (default 1)",
-                },
-            },
-            required: ["target"],
-        },
-    },
-    {
-        name: "find_similar",
-        description: "Find semantically similar code using vector similarity.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                target: { type: "string", description: "Symbol name or file path" },
-                limit: { type: "number", description: "Max results (default 5)" },
-                threshold: {
-                    type: "number",
-                    description: "Min similarity 0-1 (default 0)",
-                },
-            },
-            required: ["target"],
-        },
-    },
-    {
-        name: "build_context",
-        description: "Token-budgeted topic summary (search + skeleton + extract).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                topic: {
-                    type: "string",
-                    description: "Natural language topic or directory path",
-                },
-                budget: { type: "number", description: "Max tokens (default 4000)" },
-                limit: {
-                    type: "number",
-                    description: "Search result limit (default 10)",
-                },
-            },
-            required: ["topic"],
-        },
-    },
-    {
-        name: "investigate",
-        description: "Agentic codebase Q&A: a local LLM answers questions using search, trace, peek, impact, and related tools. Requires LLM to be enabled (gmax llm on).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                question: {
-                    type: "string",
-                    description: "Natural language question about the codebase",
-                },
-                max_rounds: {
-                    type: "number",
-                    description: "Max tool-call rounds (default 10)",
-                },
-            },
-            required: ["question"],
-        },
-    },
-    {
-        name: "review_commit",
-        description: "Review a git commit for bugs, breaking changes, and security issues using local LLM + codebase context. Returns structured findings. Requires LLM to be enabled (gmax llm on).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                commit: {
-                    type: "string",
-                    description: "Git ref to review (default: HEAD)",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "review_report",
-        description: "Get the accumulated code review report for the current project. Returns findings from all reviewed commits.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                json: {
-                    type: "boolean",
-                    description: "Return raw JSON instead of text (default: false)",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "review_risk",
-        description: "Deterministic risk ranking of the symbols a commit's diff touches, ordered by blast radius (inbound callers) × test presence × file churn. No LLM required — fast, graph + git only. Use to triage what a change endangers before a deep review.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                commit: {
-                    type: "string",
-                    description: "Git ref to analyze (default: HEAD)",
-                },
-            },
-            required: [],
-        },
-    },
-];
+const audit_1 = require("./audit");
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -589,6 +116,23 @@ function chunkSymbols(chunk) {
     var _a;
     return toStringArray((_a = chunk.definedSymbols) !== null && _a !== void 0 ? _a : chunk.defined_symbols);
 }
+// searcher.search() returns mapped ChunkType objects: the absolute path lives in
+// metadata.path and line numbers in generated_metadata, never at the top level.
+// Handlers that consume search results must read through these — reading r.path /
+// r.start_line directly yields undefined (and crashed build_context's rel()).
+// Use nullish (not ||) so a legitimate line 0 isn't skipped.
+function searchResultPath(r) {
+    var _a, _b, _c;
+    return String((_c = (_a = r === null || r === void 0 ? void 0 : r.path) !== null && _a !== void 0 ? _a : (_b = r === null || r === void 0 ? void 0 : r.metadata) === null || _b === void 0 ? void 0 : _b.path) !== null && _c !== void 0 ? _c : "");
+}
+function searchResultStartLine(r) {
+    var _a, _b, _c;
+    return Number((_c = (_a = r === null || r === void 0 ? void 0 : r.start_line) !== null && _a !== void 0 ? _a : (_b = r === null || r === void 0 ? void 0 : r.generated_metadata) === null || _b === void 0 ? void 0 : _b.start_line) !== null && _c !== void 0 ? _c : 0);
+}
+function searchResultEndLine(r, fallbackStart = 0) {
+    var _a, _b, _c;
+    return Number((_c = (_a = r === null || r === void 0 ? void 0 : r.end_line) !== null && _a !== void 0 ? _a : (_b = r === null || r === void 0 ? void 0 : r.generated_metadata) === null || _b === void 0 ? void 0 : _b.end_line) !== null && _c !== void 0 ? _c : fallbackStart);
+}
 function filterMcpSearchResults(data, options = {}) {
     var _a, _b;
     let results = data;
@@ -722,18 +266,34 @@ exports.mcp = new commander_1.Command("mcp")
     // --- Tool handlers ---
     function handleSemanticSearch(args_1) {
         return __awaiter(this, arguments, void 0, function* (args, isSearchAll = false) {
-            var _a, _b;
             const query = String(args.query || "");
             if (!query)
                 return err("Missing required parameter: query");
-            const searchAll = isSearchAll || args.scope === "all";
+            let searchAll = isSearchAll || args.scope === "all";
             const limit = Math.min(Math.max(Number(args.limit) || 3, 1), 50);
             ensureWatcher();
+            // Project resolution. The server is pinned to whatever cwd it launched in
+            // (resolved once at startup). When that cwd ISN'T an indexed project and
+            // the caller hasn't pinned an explicit --root, fall back to cross-project
+            // search instead of dead-ending — this is what makes the server usable
+            // from a session that isn't sitting inside a registered repo.
+            let scopeNote = "";
             const proj = (0, project_registry_1.getProject)(projectRoot);
-            if (!proj) {
+            if (!proj && typeof args.root !== "string") {
+                const indexed = (0, project_registry_1.listProjects)().filter((p) => { var _a; return p.status !== "pending" && ((_a = p.chunkCount) !== null && _a !== void 0 ? _a : 0) > 0; });
+                if (indexed.length === 0) {
+                    return err("No indexed projects yet. cd into a repo and run `gmax add` to index it first.");
+                }
+                searchAll = true;
+                scopeNote =
+                    `Note: ${path.basename(projectRoot)}/ isn't an indexed gmax project — ` +
+                        `searching all ${indexed.length} indexed project(s). ` +
+                        `Call list_projects to see them, then pass projects:"name" to narrow.`;
+            }
+            else if (!proj) {
                 return err("Project not added to gmax yet. Run `gmax add` to index it first.");
             }
-            if (proj.status === "pending" || proj.chunkCount === 0) {
+            else if (proj.status === "pending" || proj.chunkCount === 0) {
                 return err("Project not indexed yet. Run `gmax add` to index it first.");
             }
             try {
@@ -807,10 +367,19 @@ exports.mcp = new commander_1.Command("mcp")
                 };
                 const seedFiles = parseSeedList(args.seed_files);
                 const seedSymbols = parseSeedList(args.seed_symbols);
-                const seeds = seedFiles || seedSymbols ? { files: seedFiles, symbols: seedSymbols } : undefined;
+                const seeds = seedFiles || seedSymbols
+                    ? { files: seedFiles, symbols: seedSymbols }
+                    : undefined;
                 const result = yield searcher.search(query, limit, { rerank: process.env.GMAX_RERANK === "1", seeds }, Object.keys(filters).length > 0 ? filters : undefined, pathPrefix);
+                // Prepend the scope-fallback note (if any) + searcher warnings to
+                // whatever body we return, so the agent learns it searched all projects.
+                const prefixNotes = (body) => {
+                    var _a;
+                    const notes = [scopeNote, ...((_a = result.warnings) !== null && _a !== void 0 ? _a : [])].filter(Boolean);
+                    return notes.length ? `${notes.join("\n")}\n\n${body}` : body;
+                };
                 if (!result.data || result.data.length === 0) {
-                    return ok("No matches found. Try broadening your query, using fewer keywords, or check `gmax status` to verify the project is indexed.");
+                    return ok(prefixNotes("No matches found. Try broadening your query, using fewer keywords, or check `gmax status` to verify the project is indexed."));
                 }
                 const minScore = typeof args.min_score === "number" ? args.min_score : 0;
                 const maxPerFile = typeof args.max_per_file === "number" ? args.max_per_file : 0;
@@ -837,10 +406,7 @@ exports.mcp = new commander_1.Command("mcp")
                         getImportsForFile,
                         query,
                     });
-                    if ((_a = result.warnings) === null || _a === void 0 ? void 0 : _a.length) {
-                        return ok(`${result.warnings.join("\n")}\n\n${output}`);
-                    }
-                    return ok(output);
+                    return ok(prefixNotes(output));
                 }
                 let results = result.data.map((r) => {
                     var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
@@ -936,7 +502,7 @@ exports.mcp = new commander_1.Command("mcp")
                         const regex = new RegExp(namePattern, "i");
                         results = results.filter((r) => r.symbols.some((s) => regex.test(s)));
                     }
-                    catch (_c) {
+                    catch (_a) {
                         // Invalid regex — skip filter
                     }
                 }
@@ -979,14 +545,11 @@ exports.mcp = new commander_1.Command("mcp")
                             output += `\n${traceLines.join("\n")}`;
                         }
                     }
-                    catch (_d) {
+                    catch (_b) {
                         // Trace failed — return search results without trace
                     }
                 }
-                if ((_b = result.warnings) === null || _b === void 0 ? void 0 : _b.length) {
-                    return ok(`${result.warnings.join("\n")}\n\n${output}`);
-                }
-                return ok(output);
+                return ok(prefixNotes(output));
             }
             catch (e) {
                 const msg = e instanceof Error ? e.message : String(e);
@@ -1210,7 +773,7 @@ exports.mcp = new commander_1.Command("mcp")
                     "is_exported",
                     "defined_symbols",
                 ])
-                    .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbol)}') AND path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+                    .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbol)}') AND ${(0, filter_builder_1.pathStartsWith)(prefix)}`)
                     .limit(10)
                     .toArray();
                 if (rows.length === 0) {
@@ -1304,7 +867,7 @@ exports.mcp = new commander_1.Command("mcp")
                 const metaRows = yield table
                     .query()
                     .select(["is_exported", "start_line", "end_line"])
-                    .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbol)}') AND path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+                    .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbol)}') AND ${(0, filter_builder_1.pathStartsWith)(prefix)}`)
                     .limit(1)
                     .toArray();
                 const exported = metaRows.length > 0 && Boolean(metaRows[0].is_exported);
@@ -1419,7 +982,7 @@ exports.mcp = new commander_1.Command("mcp")
                 const defRows = yield table
                     .query()
                     .select(["path", "start_line", "is_exported"])
-                    .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbol)}') AND path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+                    .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(symbol)}') AND ${(0, filter_builder_1.pathStartsWith)(prefix)}`)
                     .limit(1)
                     .toArray();
                 if (defRows.length === 0) {
@@ -1474,7 +1037,7 @@ exports.mcp = new commander_1.Command("mcp")
                     "referenced_symbols",
                     "is_exported",
                 ])
-                    .where(`path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+                    .where((0, filter_builder_1.pathStartsWith)(prefix))
                     .limit(500000)
                     .toArray();
                 if (rows.length === 0) {
@@ -1658,7 +1221,7 @@ exports.mcp = new commander_1.Command("mcp")
                     const absPrefix = path.isAbsolute(pathPrefix)
                         ? pathPrefix
                         : path.resolve(projectRoot, pathPrefix);
-                    query = query.where(`path LIKE '${(0, filter_builder_1.escapeSqlString)((0, filter_builder_1.normalizePath)(absPrefix))}%'`);
+                    query = query.where((0, filter_builder_1.pathStartsWith)((0, filter_builder_1.normalizePath)(absPrefix)));
                 }
                 const rows = yield query.toArray();
                 const map = new Map();
@@ -1714,6 +1277,32 @@ exports.mcp = new commander_1.Command("mcp")
             }
         });
     }
+    function handleListProjects() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            try {
+                const projects = (0, project_registry_1.listProjects)();
+                if (projects.length === 0) {
+                    return ok("No projects indexed yet. cd into a repo and run `gmax add` to index it.");
+                }
+                const currentName = (_a = (0, project_registry_1.getProject)(projectRoot)) === null || _a === void 0 ? void 0 : _a.name;
+                const lines = projects.map((p) => {
+                    const here = p.name === currentName ? " (current)" : "";
+                    const chunks = typeof p.chunkCount === "number"
+                        ? `\t(${p.chunkCount} chunks)`
+                        : "";
+                    return `${p.name}${here}\t${p.root}\t${p.status}${chunks}`;
+                });
+                return ok(`${projects.length} indexed project(s). ` +
+                    `Pass a name to semantic_search via projects:"name", or use scope:"all".\n\n` +
+                    lines.join("\n"));
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return err(`Listing projects failed: ${msg}`);
+            }
+        });
+    }
     function handleIndexStatus() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f;
@@ -1738,30 +1327,15 @@ exports.mcp = new commander_1.Command("mcp")
                         watcherLine += " — search results may be incomplete";
                     }
                 }
+                // Health overview only. The per-project listing (names, roots,
+                // per-project chunk counts) lives in `list_projects` — keep this tool
+                // focused on index health and avoid the N-project LanceDB scans.
                 const lines = [
                     `Index: ~/.gmax/lancedb (${stats.chunks} chunks, ${fileCount} files)`,
                     `Model: ${globalConfig.embedMode === "gpu" ? ((_d = (_c = (_b = config_1.MODEL_TIERS[globalConfig.modelTier]) === null || _b === void 0 ? void 0 : _b.mlxModel) !== null && _c !== void 0 ? _c : config === null || config === void 0 ? void 0 : config.embedModel) !== null && _d !== void 0 ? _d : "unknown") : ((_e = config === null || config === void 0 ? void 0 : config.embedModel) !== null && _e !== void 0 ? _e : "unknown")} (${(_f = config === null || config === void 0 ? void 0 : config.vectorDim) !== null && _f !== void 0 ? _f : "?"}d, ${globalConfig.embedMode})`,
                     (config === null || config === void 0 ? void 0 : config.indexedAt) ? `Last indexed: ${config.indexedAt}` : "",
                     watcherLine,
-                    "",
-                    "Indexed directories:",
-                    ...(yield Promise.all(projects.map((p) => __awaiter(this, void 0, void 0, function* () {
-                        var _a, _b;
-                        const prefix = p.root.endsWith("/") ? p.root : `${p.root}/`;
-                        try {
-                            const table = yield db.ensureTable();
-                            const rows = yield table
-                                .query()
-                                .select(["id"])
-                                .where(`path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
-                                .limit(100000)
-                                .toArray();
-                            return `  ${p.name}\t${p.root}\t${(_a = p.lastIndexed) !== null && _a !== void 0 ? _a : "unknown"}\t(${rows.length} chunks)`;
-                        }
-                        catch (_c) {
-                            return `  ${p.name}\t${p.root}\t${(_b = p.lastIndexed) !== null && _b !== void 0 ? _b : "unknown"}`;
-                        }
-                    })))),
+                    `Projects: ${projects.length} indexed (call list_projects for names + per-project chunk counts)`,
                 ].filter(Boolean);
                 return ok(lines.join("\n"));
             }
@@ -1814,7 +1388,7 @@ exports.mcp = new commander_1.Command("mcp")
                     "defined_symbols",
                     "referenced_symbols",
                 ])
-                    .where(`path LIKE '${(0, filter_builder_1.escapeSqlString)(prefix)}%'`)
+                    .where((0, filter_builder_1.pathStartsWith)(prefix))
                     .limit(200000)
                     .toArray();
                 if (rows.length === 0) {
@@ -2092,7 +1666,9 @@ exports.mcp = new commander_1.Command("mcp")
                     const searcher = getSearcher();
                     const response = yield searcher.search(query, limit, { rerank: process.env.GMAX_RERANK === "1" }, {}, projectRoot);
                     const changedSet = new Set(changedFiles);
-                    let filtered = response.data.filter((r) => changedSet.has(String(r.path || "")));
+                    // searcher.search() returns mapped chunks (path under metadata.path);
+                    // changedFiles are absolute, so match on the resolved absolute path.
+                    let filtered = response.data.filter((r) => changedSet.has(searchResultPath(r)));
                     if (role)
                         filtered = filtered.filter((r) => String(r.role || "")
                             .toUpperCase()
@@ -2100,9 +1676,9 @@ exports.mcp = new commander_1.Command("mcp")
                     if (filtered.length === 0)
                         return ok("No indexed results found in changed files for that query.");
                     const lines = filtered.slice(0, limit).map((r) => {
-                        var _a, _b, _c;
+                        var _a, _b;
                         const sym = (_b = (_a = toStringArray(r.defined_symbols)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "";
-                        return `${rel(r.path)}:${Number((_c = r.start_line) !== null && _c !== void 0 ? _c : 0) + 1} ${sym} [${r.role || "IMPL"}]`;
+                        return `${rel(searchResultPath(r))}:${searchResultStartLine(r) + 1} ${sym} [${r.role || "IMPL"}]`;
                     });
                     return ok(lines.join("\n"));
                 }
@@ -2253,7 +1829,7 @@ exports.mcp = new commander_1.Command("mcp")
                     "role",
                     "_distance",
                 ])
-                    .where(`path LIKE '${(0, filter_builder_1.escapeSqlString)(projectRoot)}/%'`)
+                    .where((0, filter_builder_1.pathStartsWith)(`${projectRoot}/`))
                     .limit(limit + 5)
                     .toArray();
                 let filtered = results.filter((r) => !(r.path === source.path && r.start_line === source.start_line));
@@ -2276,7 +1852,7 @@ exports.mcp = new commander_1.Command("mcp")
     }
     function handleBuildContext(args) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d;
+            var _a, _b;
             ensureWatcher();
             const topic = String(args.topic || "");
             if (!topic)
@@ -2292,21 +1868,22 @@ exports.mcp = new commander_1.Command("mcp")
                 const estTokens = (s) => Math.ceil(s.length / 4);
                 let tokensUsed = 0;
                 const sections = [];
-                // Entry points
+                // Entry points. searcher.search() returns mapped chunks, so the path and
+                // line live under metadata/generated_metadata — read via the helpers.
                 const epLines = response.data.slice(0, 5).map((r) => {
-                    var _a, _b, _c;
+                    var _a, _b;
                     const sym = (_b = (_a = toStringArray(r.defined_symbols)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "";
-                    return `${rel(r.path)}:${Number((_c = r.start_line) !== null && _c !== void 0 ? _c : 0) + 1} ${sym} [${r.role || "IMPL"}]`;
+                    return `${rel(searchResultPath(r))}:${searchResultStartLine(r) + 1} ${sym} [${r.role || "IMPL"}]`;
                 });
                 const epSection = `## Entry Points\n${epLines.join("\n")}`;
                 sections.push(epSection);
                 tokensUsed += estTokens(epSection);
                 // Key function bodies
                 for (const r of response.data.slice(0, 3)) {
-                    const absP = String(r.path || "");
-                    const startLine = Number((_a = r.start_line) !== null && _a !== void 0 ? _a : 0);
-                    const endLine = Number((_b = r.end_line) !== null && _b !== void 0 ? _b : startLine);
-                    const sym = (_d = (_c = toStringArray(r.defined_symbols)) === null || _c === void 0 ? void 0 : _c[0]) !== null && _d !== void 0 ? _d : "";
+                    const absP = searchResultPath(r);
+                    const startLine = searchResultStartLine(r);
+                    const endLine = searchResultEndLine(r, startLine);
+                    const sym = (_b = (_a = toStringArray(r.defined_symbols)) === null || _a === void 0 ? void 0 : _a[0]) !== null && _b !== void 0 ? _b : "";
                     try {
                         const content = fs.readFileSync(absP, "utf-8");
                         const body = content
@@ -2319,7 +1896,7 @@ exports.mcp = new commander_1.Command("mcp")
                         sections.push(blob);
                         tokensUsed += estTokens(blob);
                     }
-                    catch (_e) {
+                    catch (_c) {
                         /* skip unreadable */
                     }
                 }
@@ -2331,219 +1908,514 @@ exports.mcp = new commander_1.Command("mcp")
             }
         });
     }
-    // --- MCP server setup ---
-    const transport = new stdio_js_1.StdioServerTransport();
-    const server = new index_js_1.Server({
-        name: "gmax",
-        version: JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), {
-            encoding: "utf-8",
-        })).version,
-    }, {
-        capabilities: {
-            tools: {},
-        },
-    });
-    server.setRequestHandler(types_js_1.ListToolsRequestSchema, () => __awaiter(void 0, void 0, void 0, function* () {
-        return { tools: TOOLS };
-    }));
-    server.setRequestHandler(types_js_1.CallToolRequestSchema, (request) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g;
-        const { name, arguments: args } = request.params;
-        const toolArgs = (args !== null && args !== void 0 ? args : {});
-        const startMs = Date.now();
-        let result;
-        switch (name) {
-            case "semantic_search":
-                result = yield handleSemanticSearch(toolArgs, false);
-                break;
-            case "code_skeleton":
-                result = yield handleCodeSkeleton(toolArgs);
-                break;
-            case "trace_calls":
-                result = yield handleTraceCalls(toolArgs);
-                break;
-            case "extract_symbol":
-                result = yield handleExtractSymbol(toolArgs);
-                break;
-            case "peek_symbol":
-                result = yield handlePeekSymbol(toolArgs);
-                break;
-            case "dead":
-                result = yield handleDead(toolArgs);
-                break;
-            case "audit":
-                result = yield handleAudit(toolArgs);
-                break;
-            case "get_neighbors":
-                result = yield handleGetNeighbors(toolArgs);
-                break;
-            case "find_paths":
-                result = yield handleFindPaths(toolArgs);
-                break;
-            case "subgraph_for_files":
-                result = yield handleSubgraphForFiles(toolArgs);
-                break;
-            case "list_symbols":
-                result = yield handleListSymbols(toolArgs);
-                break;
-            case "index_status":
-                result = yield handleIndexStatus();
-                break;
-            case "summarize_directory":
-                result = yield handleSummarizeDirectory(toolArgs);
-                break;
-            case "summarize_project":
-                result = yield handleSummarizeProject(toolArgs);
-                break;
-            case "related_files":
-                result = yield handleRelatedFiles(toolArgs);
-                break;
-            case "recent_changes":
-                result = yield handleRecentChanges(toolArgs);
-                break;
-            case "diff_changes":
-                result = yield handleDiffChanges(toolArgs);
-                break;
-            case "find_tests":
-                result = yield handleFindTests(toolArgs);
-                break;
-            case "impact_analysis":
-                result = yield handleImpactAnalysis(toolArgs);
-                break;
-            case "find_similar":
-                result = yield handleFindSimilar(toolArgs);
-                break;
-            case "build_context":
-                result = yield handleBuildContext(toolArgs);
-                break;
-            case "investigate": {
-                const question = String(toolArgs.question || "");
-                if (!question) {
-                    result = err("Missing required parameter: question");
-                    break;
-                }
-                const maxRounds = Math.min(Math.max(Number(toolArgs.max_rounds) || 10, 1), 15);
-                try {
-                    const { isDaemonRunning, sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
-                    if (yield isDaemonRunning()) {
-                        const llmResp = yield sendDaemonCommand({ cmd: "llm-start" }, { timeoutMs: 90000 });
-                        if (!llmResp.ok) {
-                            result = err(`LLM server not available: ${llmResp.error}. Run \`gmax llm on && gmax llm start\`.`);
-                            break;
-                        }
-                    }
-                    else {
-                        result = err("LLM server not available. Run `gmax llm on && gmax llm start`.");
-                        break;
+    // --- Review/LLM tool handlers (extracted from the old dispatch switch) ---
+    function handleInvestigate(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const question = String(args.question || "");
+            if (!question)
+                return err("Missing required parameter: question");
+            const maxRounds = Math.min(Math.max(Number(args.max_rounds) || 10, 1), 15);
+            try {
+                const { isDaemonRunning, sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
+                if (yield isDaemonRunning()) {
+                    const llmResp = yield sendDaemonCommand({ cmd: "llm-start" }, { timeoutMs: 90000 });
+                    if (!llmResp.ok) {
+                        return err(`LLM server not available: ${llmResp.error}. Run \`gmax llm on && gmax llm start\`.`);
                     }
-                    const { investigate } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/investigate")));
-                    const inv = yield investigate({ question, projectRoot, maxRounds });
-                    result = ok(inv.answer);
                 }
-                catch (e) {
-                    result = err(`Investigate failed: ${e instanceof Error ? e.message : String(e)}`);
+                else {
+                    return err("LLM server not available. Run `gmax llm on && gmax llm start`.");
                 }
-                break;
+                const { investigate } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/investigate")));
+                const inv = yield investigate({ question, projectRoot, maxRounds });
+                return ok(inv.answer);
             }
-            case "review_commit": {
-                const commitRef = String(toolArgs.commit || "HEAD");
-                try {
-                    const { isDaemonRunning, sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
-                    if (yield isDaemonRunning()) {
-                        const llmResp = yield sendDaemonCommand({ cmd: "llm-start" }, { timeoutMs: 90000 });
-                        if (!llmResp.ok) {
-                            result = err(`LLM server not available: ${llmResp.error}. Run \`gmax llm on && gmax llm start\`.`);
-                            break;
-                        }
-                    }
-                    else {
-                        result = err("LLM server not available. Run `gmax llm on && gmax llm start`.");
-                        break;
-                    }
-                    const { reviewCommit } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/review")));
-                    const rev = yield reviewCommit({ commitRef, projectRoot });
-                    if (rev.clean) {
-                        result = ok(`Clean commit (${rev.commit}) — no issues found in ${rev.duration}s.`);
-                    }
-                    else {
-                        const { readReport } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/report")));
-                        const report = readReport(projectRoot);
-                        const entry = report === null || report === void 0 ? void 0 : report.reviews.find((r) => r.commit === rev.commit);
-                        result = ok(JSON.stringify({
-                            commit: rev.commit,
-                            findings: (_a = entry === null || entry === void 0 ? void 0 : entry.findings) !== null && _a !== void 0 ? _a : [],
-                            duration: rev.duration,
-                        }, null, 2));
+            catch (e) {
+                return err(`Investigate failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        });
+    }
+    function handleReviewCommit(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const commitRef = String(args.commit || "HEAD");
+            try {
+                const { isDaemonRunning, sendDaemonCommand } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/daemon-client")));
+                if (yield isDaemonRunning()) {
+                    const llmResp = yield sendDaemonCommand({ cmd: "llm-start" }, { timeoutMs: 90000 });
+                    if (!llmResp.ok) {
+                        return err(`LLM server not available: ${llmResp.error}. Run \`gmax llm on && gmax llm start\`.`);
                     }
                 }
-                catch (e) {
-                    result = err(`Review failed: ${e instanceof Error ? e.message : String(e)}`);
-                }
-                break;
+                else {
+                    return err("LLM server not available. Run `gmax llm on && gmax llm start`.");
+                }
+                const { reviewCommit } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/review")));
+                const rev = yield reviewCommit({ commitRef, projectRoot });
+                if (rev.clean) {
+                    return ok(`Clean commit (${rev.commit}) — no issues found in ${rev.duration}s.`);
+                }
+                const { readReport } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/report")));
+                const report = readReport(projectRoot);
+                const entry = report === null || report === void 0 ? void 0 : report.reviews.find((r) => r.commit === rev.commit);
+                return ok(JSON.stringify({
+                    commit: rev.commit,
+                    findings: (_a = entry === null || entry === void 0 ? void 0 : entry.findings) !== null && _a !== void 0 ? _a : [],
+                    duration: rev.duration,
+                }, null, 2));
             }
-            case "review_risk": {
-                ensureWatcher();
-                const commitRef = String(toolArgs.commit || "HEAD");
-                try {
-                    const db = getVectorDb();
-                    const builder = new graph_builder_1.GraphBuilder(db, projectRoot);
-                    const { gatherRiskInputs, computeRiskTable, formatRiskTable } = yield Promise.resolve().then(() => __importStar(require("../lib/review/risk")));
-                    const inputs = yield gatherRiskInputs(commitRef, projectRoot, {
-                        vectorDb: db,
-                        graphBuilder: builder,
-                    });
-                    const rows = computeRiskTable(inputs);
-                    result =
-                        rows.length === 0
-                            ? ok("(no changed symbols in this diff)")
-                            : ok(formatRiskTable(rows, { agent: true }));
-                }
-                catch (e) {
-                    result = err(`Risk ranking failed: ${e instanceof Error ? e.message : String(e)}`);
-                }
-                break;
+            catch (e) {
+                return err(`Review failed: ${e instanceof Error ? e.message : String(e)}`);
             }
-            case "review_report": {
-                try {
-                    const { readReport, formatReportText } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/report")));
-                    const report = readReport(projectRoot);
-                    if (!report || report.reviews.length === 0) {
-                        result = ok("No review findings yet.");
-                    }
-                    else if (toolArgs.json) {
-                        result = ok(JSON.stringify(report, null, 2));
-                    }
-                    else {
-                        result = ok(formatReportText(report));
-                    }
+        });
+    }
+    function handleReviewRisk(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            ensureWatcher();
+            const commitRef = String(args.commit || "HEAD");
+            try {
+                const db = getVectorDb();
+                const builder = new graph_builder_1.GraphBuilder(db, projectRoot);
+                const { gatherRiskInputs, computeRiskTable, formatRiskTable } = yield Promise.resolve().then(() => __importStar(require("../lib/review/risk")));
+                const inputs = yield gatherRiskInputs(commitRef, projectRoot, {
+                    vectorDb: db,
+                    graphBuilder: builder,
+                });
+                const rows = computeRiskTable(inputs);
+                return rows.length === 0
+                    ? ok("(no changed symbols in this diff)")
+                    : ok(formatRiskTable(rows, { agent: true }));
+            }
+            catch (e) {
+                return err(`Risk ranking failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        });
+    }
+    function handleReviewReport(args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const { readReport, formatReportText } = yield Promise.resolve().then(() => __importStar(require("../lib/llm/report")));
+                const report = readReport(projectRoot);
+                if (!report || report.reviews.length === 0) {
+                    return ok("No review findings yet.");
                 }
-                catch (e) {
-                    result = err(`Report failed: ${e instanceof Error ? e.message : String(e)}`);
+                if (args.json) {
+                    return ok(JSON.stringify(report, null, 2));
                 }
-                break;
+                return ok(formatReportText(report));
             }
-            default:
-                return err(`Unknown tool: ${name}`);
-        }
-        // Best-effort query logging
+            catch (e) {
+                return err(`Report failed: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        });
+    }
+    // --- MCP server setup ---
+    const transport = new stdio_js_1.StdioServerTransport();
+    const server = new mcp_js_1.McpServer({
+        name: "gmax",
+        version: JSON.parse(fs.readFileSync(path.join(__dirname, "../../package.json"), {
+            encoding: "utf-8",
+        })).version,
+    }, {
+        capabilities: {
+            tools: {},
+        },
+        instructions: "gmax is a local semantic code-search index over one or more projects. " +
+            "By default tools operate on the project at the server's working directory. " +
+            "If you are NOT inside a specific repo, or want a different one: call " +
+            '`list_projects` to see what\'s indexed, then pass `projects:"name"` (or ' +
+            '`scope:"all"`) to `semantic_search`. When the working directory isn\'t an ' +
+            "indexed project, `semantic_search` automatically searches all of them and " +
+            "says so. Prefer `semantic_search` (detail:'pointer') for discovery, then " +
+            "`extract_symbol`/`peek_symbol`/`code_skeleton` to read, and " +
+            "`trace_calls`/`impact_analysis`/`find_tests` for call-graph questions.",
+    });
+    // Best-effort query logging, applied uniformly to every tool exactly as the
+    // old single CallToolRequestSchema dispatch did before each return.
+    const logToolCall = (name, toolArgs, startMs, result) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f;
         try {
             const { logQuery } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/query-log")));
-            const text = (_d = (_c = (_b = result.content) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.text) !== null && _d !== void 0 ? _d : "";
+            const text = (_c = (_b = (_a = result.content) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text) !== null && _c !== void 0 ? _c : "";
             const resultLines = text.split("\n").filter((l) => l.trim()).length;
             logQuery({
                 ts: new Date().toISOString(),
                 source: "mcp",
                 tool: name,
-                query: String((_g = (_f = (_e = toolArgs.query) !== null && _e !== void 0 ? _e : toolArgs.symbol) !== null && _f !== void 0 ? _f : toolArgs.target) !== null && _g !== void 0 ? _g : ""),
+                query: String((_f = (_e = (_d = toolArgs.query) !== null && _d !== void 0 ? _d : toolArgs.symbol) !== null && _e !== void 0 ? _e : toolArgs.target) !== null && _f !== void 0 ? _f : ""),
                 project: projectRoot,
                 results: resultLines,
                 ms: Date.now() - startMs,
                 error: result.isError ? text.slice(0, 200) : undefined,
             });
         }
-        catch (_h) { }
-        return result;
-    }));
+        catch (_g) { }
+    });
+    // Register a tool, wrapping its handler with timing + query logging. Zod raw
+    // shapes give us free input validation (the SDK rejects calls that violate
+    // the schema before the handler runs); handlers stay defensively coded.
+    function tool(name, config, handler) {
+        server.registerTool(name, config, (rawArgs) => __awaiter(this, void 0, void 0, function* () {
+            const args = (rawArgs !== null && rawArgs !== void 0 ? rawArgs : {});
+            const startMs = Date.now();
+            const result = yield handler(args);
+            yield logToolCall(name, args, startMs, result);
+            return result;
+        }));
+    }
+    tool("semantic_search", {
+        description: "Search code by meaning. Use scope:'all' for cross-project. Prefer CLI: gmax \"query\" --plain",
+        inputSchema: {
+            query: zod_1.z
+                .string()
+                .describe("Natural language query (5+ words recommended)"),
+            limit: zod_1.z
+                .number()
+                .describe("Max results (default 3, max 50)")
+                .optional(),
+            root: zod_1.z
+                .string()
+                .describe("Search a different directory (absolute path)")
+                .optional(),
+            path: zod_1.z
+                .string()
+                .describe("Path prefix filter (e.g. 'src/auth/')")
+                .optional(),
+            detail: zod_1.z
+                .string()
+                .describe("'pointer' (default), 'code', or 'full'")
+                .optional(),
+            min_score: zod_1.z
+                .number()
+                .describe("Min score 0-1 (default 0)")
+                .optional(),
+            max_per_file: zod_1.z.number().describe("Max results per file").optional(),
+            file: zod_1.z
+                .string()
+                .describe("Filename filter (e.g. 'syncer.ts')")
+                .optional(),
+            exclude: zod_1.z
+                .string()
+                .describe("Exclude path prefix (e.g. 'tests/')")
+                .optional(),
+            language: zod_1.z
+                .string()
+                .describe("Extension filter (e.g. 'ts', 'py')")
+                .optional(),
+            role: zod_1.z
+                .string()
+                .describe("'ORCHESTRATION', 'DEFINITION', or 'IMPLEMENTATION'")
+                .optional(),
+            context_lines: zod_1.z
+                .number()
+                .describe("Lines before/after chunk (max 20)")
+                .optional(),
+            mode: zod_1.z
+                .string()
+                .describe("'default' or 'symbol' (appends call graph)")
+                .optional(),
+            include_imports: zod_1.z
+                .boolean()
+                .describe("Prepend file imports to results")
+                .optional(),
+            name_pattern: zod_1.z
+                .string()
+                .describe("Regex filter on symbol name")
+                .optional(),
+            scope: zod_1.z
+                .string()
+                .describe("'project' (default) or 'all' (search everything)")
+                .optional(),
+            projects: zod_1.z
+                .string()
+                .describe("Project names to include (comma-separated)")
+                .optional(),
+            exclude_projects: zod_1.z
+                .string()
+                .describe("Project names to exclude (comma-separated)")
+                .optional(),
+            seed_files: zod_1.z
+                .string()
+                .describe("Bias results toward your working context: comma-separated paths you have open (e.g. 'src/lib/llm/server.ts'). On-topic chunks in these files get lifted; off-topic ones are not.")
+                .optional(),
+            seed_symbols: zod_1.z
+                .string()
+                .describe("Bias results toward identifiers you're working with: comma-separated symbol names. Chunks defining a seeded symbol are preferred over mere callers.")
+                .optional(),
+        },
+    }, handleSemanticSearch);
+    tool("code_skeleton", {
+        description: "File structure with bodies collapsed (~4x fewer tokens). Accepts file, directory, or comma-separated paths.",
+        inputSchema: {
+            target: zod_1.z
+                .string()
+                .describe("File, directory, or comma-separated paths"),
+            limit: zod_1.z
+                .number()
+                .describe("Max files for directory mode (default 10)")
+                .optional(),
+            format: zod_1.z.string().describe("'text' (default) or 'json'").optional(),
+        },
+    }, handleCodeSkeleton);
+    tool("trace_calls", {
+        description: "Call graph: importers, callers (multi-hop), callees with file:line.",
+        inputSchema: {
+            symbol: zod_1.z.string().describe("Function/class name to trace"),
+            depth: zod_1.z
+                .number()
+                .describe("Caller depth (default 1, max 3)")
+                .optional(),
+        },
+    }, handleTraceCalls);
+    tool("extract_symbol", {
+        description: "Extract complete function/class body by symbol name.",
+        inputSchema: {
+            symbol: zod_1.z.string().describe("Symbol name to extract"),
+            root: zod_1.z.string().describe("Project root (absolute path)").optional(),
+            include_imports: zod_1.z
+                .boolean()
+                .describe("Prepend file imports")
+                .optional(),
+        },
+    }, handleExtractSymbol);
+    tool("peek_symbol", {
+        description: "Compact symbol overview: signature + callers + callees.",
+        inputSchema: {
+            symbol: zod_1.z.string().describe("Symbol name"),
+            root: zod_1.z.string().describe("Project root (absolute path)").optional(),
+            depth: zod_1.z
+                .number()
+                .describe("Caller depth (default 1, max 3)")
+                .optional(),
+        },
+    }, handlePeekSymbol);
+    tool("dead", {
+        description: "Report whether a symbol has zero inbound callers in the indexed call graph. Returns DEAD, PUBLIC EXPORT (exported with no internal callers), or LIVE with caller count. Hypothesis, not proof: dynamic dispatch, reflection, and string-built call sites won't show up.",
+        inputSchema: {
+            symbol: zod_1.z.string().describe("Symbol name to check"),
+            root: zod_1.z.string().describe("Project root (absolute path)").optional(),
+        },
+    }, handleDead);
+    tool("audit", {
+        description: "Graph-summary of the indexed project in one call: god nodes (most depended-upon symbols), hub files (most depended-upon files), and dead-code candidates (non-exported symbols with zero inbound references). Built from the static call graph — dynamic dispatch, reflection, eval, and type-position-only references are invisible, so dead candidates are hypotheses; verify with the `dead` tool before acting.",
+        inputSchema: {
+            root: zod_1.z
+                .string()
+                .describe("Project root (default: current)")
+                .optional(),
+            top: zod_1.z
+                .number()
+                .describe("How many of each category to return (default 10)")
+                .optional(),
+        },
+    }, handleAudit);
+    tool("get_neighbors", {
+        description: "Graph primitive: symbols reachable from a node along call edges within N hops. direction 'callees' = what it calls (outbound), 'callers' = what calls it (inbound). Each result carries its hop distance and definition location. Static call graph — same caveats as `dead`/`audit`.",
+        inputSchema: {
+            symbol: zod_1.z.string().describe("Starting symbol"),
+            direction: zod_1.z
+                .enum(["callers", "callees"])
+                .describe("Edge direction (default callees)")
+                .optional(),
+            max_hops: zod_1.z
+                .number()
+                .describe("Max hops (default 2, max 5)")
+                .optional(),
+            root: zod_1.z.string().describe("Project root (absolute path)").optional(),
+        },
+    }, handleGetNeighbors);
+    tool("find_paths", {
+        description: "Graph primitive: shortest call-graph path between two symbols, as a symbol sequence. direction 'callees' searches outward from `from` (does `from` transitively call `to`?), 'callers' searches inward. Returns 'no path' if unreachable within max_hops.",
+        inputSchema: {
+            from: zod_1.z.string().describe("Start symbol"),
+            to: zod_1.z.string().describe("Target symbol"),
+            direction: zod_1.z
+                .enum(["callers", "callees"])
+                .describe("Search direction (default callees)")
+                .optional(),
+            max_hops: zod_1.z
+                .number()
+                .describe("Max hops (default 6, max 10)")
+                .optional(),
+            root: zod_1.z.string().describe("Project root (absolute path)").optional(),
+        },
+    }, handleFindPaths);
+    tool("subgraph_for_files", {
+        description: "Graph primitive: the local dependency subgraph for a set of files — symbols they define, the call edges among those symbols, and their outbound external dependencies. Paths may be absolute or project-root-relative.",
+        inputSchema: {
+            files: zod_1.z
+                .array(zod_1.z.string())
+                .describe("File paths (absolute or root-relative)"),
+            root: zod_1.z.string().describe("Project root (absolute path)").optional(),
+        },
+    }, handleSubgraphForFiles);
+    tool("list_symbols", {
+        description: "List indexed symbols with role and export status.",
+        inputSchema: {
+            pattern: zod_1.z
+                .string()
+                .describe("Name filter (case-insensitive)")
+                .optional(),
+            limit: zod_1.z.number().describe("Max results (default 20)").optional(),
+            path: zod_1.z.string().describe("Path prefix filter").optional(),
+        },
+    }, handleListSymbols);
+    tool("index_status", {
+        description: "Index health: chunks, files, projects, watcher status.",
+        inputSchema: {},
+        _meta: { "anthropic/alwaysLoad": true },
+    }, handleIndexStatus);
+    tool("list_projects", {
+        description: "List every gmax-indexed project (name, root, status, chunk count). Use this to pick a search scope when you're not inside a specific repo: feed a name into semantic_search's projects: param, or use scope:'all'. The working-directory project is marked (current).",
+        inputSchema: {},
+        _meta: { "anthropic/alwaysLoad": true },
+    }, handleListProjects);
+    tool("summarize_directory", {
+        description: "Generate LLM summaries for indexed chunks.",
+        inputSchema: {
+            path: zod_1.z
+                .string()
+                .describe("Directory to summarize (default: project root)")
+                .optional(),
+            limit: zod_1.z
+                .number()
+                .describe("Max chunks (default 200, max 5000)")
+                .optional(),
+        },
+    }, handleSummarizeDirectory);
+    tool("summarize_project", {
+        description: "Project overview: languages, structure, roles, key symbols, entry points.",
+        inputSchema: {
+            root: zod_1.z
+                .string()
+                .describe("Project root (default: current)")
+                .optional(),
+        },
+    }, handleSummarizeProject);
+    tool("related_files", {
+        description: "Find dependencies and dependents of a file by shared symbols.",
+        inputSchema: {
+            file: zod_1.z.string().describe("File path relative to project root"),
+            limit: zod_1.z
+                .number()
+                .describe("Max results per direction (default 10)")
+                .optional(),
+        },
+    }, handleRelatedFiles);
+    tool("recent_changes", {
+        description: "Recently modified indexed files with timestamps.",
+        inputSchema: {
+            limit: zod_1.z
+                .number()
+                .describe("Max files to return (default 20)")
+                .optional(),
+            root: zod_1.z
+                .string()
+                .describe("Project root (defaults to current project)")
+                .optional(),
+        },
+    }, handleRecentChanges);
+    tool("diff_changes", {
+        description: "Search code scoped to git changes. Omit ref for uncommitted changes.",
+        inputSchema: {
+            ref: zod_1.z
+                .string()
+                .describe("Git ref to diff against (e.g. main, HEAD~5)")
+                .optional(),
+            query: zod_1.z
+                .string()
+                .describe("Semantic search within changed files")
+                .optional(),
+            limit: zod_1.z.number().describe("Max results (default 10)").optional(),
+            role: zod_1.z
+                .string()
+                .describe("Filter by role: ORCHESTRATION, DEFINITION, IMPLEMENTATION")
+                .optional(),
+        },
+    }, handleDiffChanges);
+    tool("find_tests", {
+        description: "Find tests that exercise a symbol or file via reverse call graph.",
+        inputSchema: {
+            target: zod_1.z.string().describe("Symbol name or file path"),
+            depth: zod_1.z
+                .number()
+                .describe("Caller traversal depth 1-3 (default 1)")
+                .optional(),
+        },
+    }, handleFindTests);
+    tool("impact_analysis", {
+        description: "Change impact: dependents and affected tests for a symbol or file.",
+        inputSchema: {
+            target: zod_1.z.string().describe("Symbol name or file path"),
+            depth: zod_1.z
+                .number()
+                .describe("Caller traversal depth 1-3 (default 1)")
+                .optional(),
+        },
+    }, handleImpactAnalysis);
+    tool("find_similar", {
+        description: "Find semantically similar code using vector similarity.",
+        inputSchema: {
+            target: zod_1.z.string().describe("Symbol name or file path"),
+            limit: zod_1.z.number().describe("Max results (default 5)").optional(),
+            threshold: zod_1.z
+                .number()
+                .describe("Min similarity 0-1 (default 0)")
+                .optional(),
+        },
+    }, handleFindSimilar);
+    tool("build_context", {
+        description: "Token-budgeted topic summary (search + skeleton + extract).",
+        inputSchema: {
+            topic: zod_1.z
+                .string()
+                .describe("Natural language topic or directory path"),
+            budget: zod_1.z.number().describe("Max tokens (default 4000)").optional(),
+            limit: zod_1.z
+                .number()
+                .describe("Search result limit (default 10)")
+                .optional(),
+        },
+    }, handleBuildContext);
+    tool("investigate", {
+        description: "Agentic codebase Q&A: a local LLM answers questions using search, trace, peek, impact, and related tools. Requires LLM to be enabled (gmax llm on).",
+        inputSchema: {
+            question: zod_1.z
+                .string()
+                .describe("Natural language question about the codebase"),
+            max_rounds: zod_1.z
+                .number()
+                .describe("Max tool-call rounds (default 10)")
+                .optional(),
+        },
+    }, handleInvestigate);
+    tool("review_commit", {
+        description: "Review a git commit for bugs, breaking changes, and security issues using local LLM + codebase context. Returns structured findings. Requires LLM to be enabled (gmax llm on).",
+        inputSchema: {
+            commit: zod_1.z
+                .string()
+                .describe("Git ref to review (default: HEAD)")
+                .optional(),
+        },
+    }, handleReviewCommit);
+    tool("review_report", {
+        description: "Get the accumulated code review report for the current project. Returns findings from all reviewed commits.",
+        inputSchema: {
+            json: zod_1.z
+                .boolean()
+                .describe("Return raw JSON instead of text (default: false)")
+                .optional(),
+        },
+    }, handleReviewReport);
+    tool("review_risk", {
+        description: "Deterministic risk ranking of the symbols a commit's diff touches, ordered by blast radius (inbound callers) × test presence × file churn. No LLM required — fast, graph + git only. Use to triage what a change endangers before a deep review.",
+        inputSchema: {
+            commit: zod_1.z
+                .string()
+                .describe("Git ref to analyze (default: HEAD)")
+                .optional(),
+        },
+    }, handleReviewRisk);
     yield server.connect(transport);
     // Kick off index readiness check and watcher in background
     ensureIndexReady().catch((e) => console.error("[MCP] Index readiness check failed:", e));