@colbymchenry/codegraph-darwin-x64 1.1.1 → 1.1.2

package/lib/dist/mcp/tools.js

@@ -340,6 +340,23 @@ const projectPathProperty = {
     type: 'string',
     description: 'Absolute path to the project to query (or any directory inside it) — codegraph uses the nearest .codegraph/ index at or above that path. Omit to use this session\'s default project. Pass it to query a second codebase, or when the server root has no index of its own (e.g. a monorepo where only sub-projects are indexed, so there is no default project).',
 };
+/**
+ * EVERY codegraph tool is query-only: it reads the pre-built index and never
+ * mutates the workspace (indexing is the user's explicit CLI call, never the
+ * agent's). Advertising this read-only contract lets clients that gate on it run
+ * the tools where a possibly-mutating tool would be blocked — most concretely,
+ * Cursor's Ask mode, which rejects any MCP tool lacking `readOnlyHint: true`
+ * (issue #1018). `idempotentHint`: a repeated query has no additional effect.
+ * `openWorldHint: false`: the domain is the closed local index, not an open
+ * external world. Shared so the contract is declared once; a hypothetical
+ * mutating tool would simply not reference it.
+ */
+const READ_ONLY_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
 /**
  * All CodeGraph MCP tools
  *
@@ -374,6 +391,7 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'codegraph_callers',
@@ -398,6 +416,7 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'codegraph_callees',
@@ -422,6 +441,7 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'codegraph_impact',
@@ -446,6 +466,7 @@ exports.tools = [
             },
             required: ['symbol'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'codegraph_node',
@@ -487,6 +508,7 @@ exports.tools = [
             },
             required: [],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'codegraph_explore',
@@ -507,6 +529,7 @@ exports.tools = [
             },
             required: ['query'],
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'codegraph_status',
@@ -517,6 +540,7 @@ exports.tools = [
                 projectPath: projectPathProperty,
             },
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
     {
         name: 'codegraph_files',
@@ -550,8 +574,40 @@ exports.tools = [
                 projectPath: projectPathProperty,
             },
         },
+        annotations: READ_ONLY_ANNOTATIONS,
     },
 ];
+/**
+ * Return `defs` with `projectPath` marked `required` in each tool's inputSchema.
+ *
+ * Used for the NO-DEFAULT-PROJECT tool surface (issue #993): when the MCP server
+ * has no default project to fall back to — a gateway server started outside any
+ * repo, or a monorepo root whose `.codegraph/` indexes live only in sub-projects
+ * — every call MUST carry an explicit `projectPath`, so the schema should say so.
+ * A `required` field is a HIGH-salience channel (MCP clients surface and often
+ * validate it), unlike the instructions text the reporter found too weak to stop
+ * the agent omitting the param. When a default project IS open, callers leave
+ * projectPath optional and never call this.
+ *
+ * Pure: clones each tool's schema rather than mutating the shared module-level
+ * `tools` array (reused by every session and the static surface). A tool that
+ * doesn't expose projectPath, or already requires it, is returned untouched;
+ * explore's `['query']` becomes `['query', 'projectPath']`, and a tool with no
+ * `required` list (status/files) gains `['projectPath']`.
+ */
+function withRequiredProjectPath(defs) {
+    return defs.map((tool) => {
+        if (!tool.inputSchema.properties.projectPath)
+            return tool;
+        const required = tool.inputSchema.required ?? [];
+        if (required.includes('projectPath'))
+            return tool;
+        return {
+            ...tool,
+            inputSchema: { ...tool.inputSchema, required: [...required, 'projectPath'] },
+        };
+    });
+}
 /**
  * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
  * proxy answers `tools/list` with before any project is open. Mirrors
@@ -607,9 +663,23 @@ class ToolHandler {
     // huge repo can't hang the first call (#905); cleared on first await so
     // subsequent calls don't pay any cost.
     catchUpGate = null;
+    // Optional worker-thread pool for off-loop read-tool dispatch (daemon mode).
+    // When set + healthy, the heavy read tools run on a worker so the daemon's
+    // main loop stays free for the MCP transport under concurrent load. Null in
+    // direct/in-process mode (one client, no concurrency to parallelize).
+    queryPool = null;
     constructor(cg) {
         this.cg = cg;
     }
+    /**
+     * Engine-only: attach (or detach with null) the worker-thread query pool. The
+     * shared daemon sets this once its default project is open; the workers each
+     * hold their own WAL read connection and run {@link executeReadTool}. A
+     * worker's own ToolHandler never has a pool, so there is no nested off-loading.
+     */
+    setQueryPool(pool) {
+        this.queryPool = pool;
+    }
     /**
      * Update the default CodeGraph instance (e.g. after lazy initialization)
      */
@@ -713,8 +783,18 @@ class ToolHandler {
         let visible = allow
             ? exports.tools.filter(t => allow.has(t.name.replace(/^codegraph_/, '')))
             : exports.tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^codegraph_/, '')));
+        // No default project loaded → no-root-index case (#993): a gateway server
+        // started outside any repo, or a monorepo root whose indexes live in
+        // sub-projects. With nothing to fall back to, EVERY call needs an explicit
+        // projectPath, so mark it required in the schema — a high-salience nudge the
+        // agent acts on, where SERVER_INSTRUCTIONS_NO_ROOT_INDEX's prose alone
+        // wasn't enough (the reporter had to add an AGENTS.md note). `this.cg` is
+        // settled by `retryInitIfNeeded()` before `handleToolsList` calls us, so a
+        // null here means "genuinely no default", not a startup race. When a default
+        // IS open we leave projectPath optional (below): a bare call falls back to
+        // it, exactly as in the common single-project launch.
         if (!this.cg)
-            return visible;
+            return withRequiredProjectPath(visible);
         try {
             const stats = this.cg.getStats();
             const budget = getExploreBudget(stats.fileCount);
@@ -1113,43 +1193,26 @@ class ToolHandler {
                 if (typeof check === 'object' && check !== undefined)
                     return check;
             }
-            // Read tools resolve through a single result variable so cross-cutting
-            // notices — worktree-index mismatch (issue #155) and per-file
-            // staleness (issue #403) — can be applied in one place. status embeds
-            // its own verbose worktree warning but still flows through the
-            // staleness wrapper so its pending-files section stays consistent
-            // with what the read tools surface.
-            let result;
-            switch (toolName) {
-                case 'codegraph_search':
-                    result = await this.handleSearch(args);
-                    break;
-                case 'codegraph_callers':
-                    result = await this.handleCallers(args);
-                    break;
-                case 'codegraph_callees':
-                    result = await this.handleCallees(args);
-                    break;
-                case 'codegraph_impact':
-                    result = await this.handleImpact(args);
-                    break;
-                case 'codegraph_explore':
-                    result = await this.handleExplore(args);
-                    break;
-                case 'codegraph_node':
-                    result = await this.handleNode(args);
-                    break;
-                case 'codegraph_status':
-                    // status embeds the pending-files list as a first-class section
-                    // (see handleStatus), so we skip the auto-banner wrapper here to
-                    // avoid duplicating the same info at the top of the response.
-                    return await this.handleStatus(args);
-                case 'codegraph_files':
-                    result = await this.handleFiles(args);
-                    break;
-                default:
-                    return this.errorResult(`Unknown tool: ${toolName}`);
+            // codegraph_status reports watcher state (pending files, degraded mode,
+            // worktree warning) and embeds its own sections — it must run on the MAIN
+            // thread against the watched default instance, so it is NEVER off-loaded to
+            // a worker (whose read connection has no watcher). It also skips the
+            // auto-banner wrapper to avoid duplicating its own pending-files section.
+            if (toolName === 'codegraph_status') {
+                return await this.handleStatus(args);
             }
+            // Read tools: off-load the CPU-heavy dispatch to the worker pool when one
+            // is attached and healthy (daemon mode), so the daemon's single event loop
+            // stays free for the MCP transport under concurrent load — otherwise N
+            // concurrent explores serialize AND starve the transport until the whole
+            // batch drains (clients then time out). With no pool (direct mode) or a
+            // degraded one, dispatch runs in-process exactly as before. Either way the
+            // result flows through the cross-cutting notices — worktree-index mismatch
+            // (#155) and per-file staleness (#403) — which need the watched MAIN
+            // instance and so are always applied here, never in the worker.
+            const result = (this.queryPool && this.queryPool.healthy)
+                ? await this.queryPool.run(toolName, args)
+                : await this.executeReadTool(toolName, args);
             const withWorktree = this.withWorktreeNotice(result, args.projectPath);
             return this.withStalenessNotice(withWorktree, args.projectPath);
         }
@@ -1169,6 +1232,53 @@ class ToolHandler {
                 'continue without codegraph for this task.');
         }
     }
+    /**
+     * Run a single read tool to completion and return its raw {@link ToolResult},
+     * classifying expected failures the same way {@link execute}'s catch does so
+     * the SHAPE is identical whether dispatch runs in-process or on a worker:
+     * NotIndexed → success-shaped guidance, PathRefusal → clean error, anything
+     * else → internal-error-with-retry. Never throws.
+     *
+     * This is the worker thread's entry point (see {@link ./query-worker}) and the
+     * in-process fallback for {@link execute}. It deliberately does NOT run the
+     * catch-up gate or the staleness/worktree notices — those need the daemon's
+     * watched main instance and stay on the main thread. Cross-cutting allowlist +
+     * path validation already ran in {@link execute} before routing here.
+     */
+    async executeReadTool(toolName, args) {
+        try {
+            return await this.dispatchTool(toolName, args);
+        }
+        catch (err) {
+            if (err instanceof NotIndexedError) {
+                return this.textResult(err.message);
+            }
+            if (err instanceof PathRefusalError) {
+                return this.errorResult(err.message);
+            }
+            return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}. ` +
+                'This is an internal codegraph error — retry the call once; if it persists, ' +
+                'continue without codegraph for this task.');
+        }
+    }
+    /**
+     * Pure dispatch over the read tools — the switch, with no gate, no notices, no
+     * allowlist/validation (the caller owns those). `codegraph_status` is handled
+     * on the main thread in {@link execute} and never reaches here. May throw
+     * NotIndexed/PathRefusal, which {@link executeReadTool} classifies.
+     */
+    async dispatchTool(toolName, args) {
+        switch (toolName) {
+            case 'codegraph_search': return await this.handleSearch(args);
+            case 'codegraph_callers': return await this.handleCallers(args);
+            case 'codegraph_callees': return await this.handleCallees(args);
+            case 'codegraph_impact': return await this.handleImpact(args);
+            case 'codegraph_explore': return await this.handleExplore(args);
+            case 'codegraph_node': return await this.handleNode(args);
+            case 'codegraph_files': return await this.handleFiles(args);
+            default: return this.errorResult(`Unknown tool: ${toolName}`);
+        }
+    }
     /**
      * Handle codegraph_search
      */