* Execute a tool by name. * * `sessionState` is the CALLER's per-session explore history (CG-17). The * daemon shares one ToolHandler across every connected session, so this state * cannot live on the handler — each session owns one and hands it in, which is * what keeps two sessions
(
toolName: string,
args: Record<string, unknown>,
sessionState?: ExploreSessionState,
indexVersionWarnings?: IndexVersionWarningState,
)
| 3051 | * Omit it (the CLI does) and explore behaves exactly as before, untracked. |
| 3052 | */ |
| 3053 | async execute( |
| 3054 | toolName: string, |
| 3055 | args: Record<string, unknown>, |
| 3056 | sessionState?: ExploreSessionState, |
| 3057 | indexVersionWarnings?: IndexVersionWarningState, |
| 3058 | ): Promise<ToolResult> { |
| 3059 | if (this.closing) return this.textResult('This MCP session is closing; retry with a connected session.'); |
| 3060 | this.activeCalls++; |
| 3061 | try { |
| 3062 | // Block the first tool call on the engine's post-open reconcile so we |
| 3063 | // never serve rows for files deleted/edited while no MCP server was |
| 3064 | // running. The wait is time-boxed (#905): a huge-repo reconcile takes |
| 3065 | // minutes, and blocking the first call on all of it reads as a hang, so |
| 3066 | // we wait briefly then serve and let it finish in the background. The |
| 3067 | // gate stays installed until reconciliation settles, including on timeout. |
| 3068 | // Catch-up failures are logged by the engine; we proceed regardless so a |
| 3069 | // transient sync error never breaks tools. |
| 3070 | if (this.catchUpGate) { |
| 3071 | const gate = this.catchUpGate; |
| 3072 | await this.awaitCatchUpGate(gate); |
| 3073 | } |
| 3074 | // Honor the optional tool allowlist (CODEGRAPH_MCP_TOOLS): a trimmed |
| 3075 | // surface rejects ablated tools defensively even if a client cached them. |
| 3076 | if (!this.isToolAllowed(toolName)) { |
| 3077 | return this.errorResult(`Tool ${toolName} is disabled via CODEGRAPH_MCP_TOOLS`); |
| 3078 | } |
| 3079 | // Cross-cutting input validation. All tools accept an optional |
| 3080 | // `projectPath` and most accept either `query`, `task`, or |
| 3081 | // `symbol` — bound their lengths centrally so individual handlers |
| 3082 | // can stay focused on tool-specific logic. |
| 3083 | const pathCheck = this.validateOptionalPath(args.projectPath, 'projectPath'); |
| 3084 | if (typeof pathCheck === 'object' && pathCheck !== undefined) { |
| 3085 | return pathCheck; |
| 3086 | } |
| 3087 | // An explicit project gets the same first-call guarantee as the default |
| 3088 | // (#1835): its post-open catch-up sync finishes (time-boxed) before we |
| 3089 | // serve it. Resolved on the main thread so the watcher lives here even |
| 3090 | // when dispatch is off-loaded to a worker. |
| 3091 | if (typeof pathCheck === 'string') { |
| 3092 | // A file inside a project (an agent passing the file it is looking at) |
| 3093 | // stands for its directory, like any other path inside it (#2982). |
| 3094 | // Rewritten here so the gate, the worker, the worktree notice and |
| 3095 | // getCodeGraph all see the same directory. |
| 3096 | let projectPath = pathCheck; |
| 3097 | try { |
| 3098 | if (statSync(pathCheck).isFile()) projectPath = dirname(pathCheck); |
| 3099 | } catch { /* a missing path walks up to its .codegraph/ as before */ } |
| 3100 | if (projectPath !== pathCheck) args = { ...args, projectPath }; |
| 3101 | await this.awaitProjectGate(projectPath); |
| 3102 | } |
| 3103 | // The `path` and `pattern` properties used by codegraph_files are |
| 3104 | // also path-shaped — apply the same cap. |
| 3105 | if (args.path !== undefined) { |
| 3106 | const check = this.validateOptionalPath(args.path, 'path'); |
| 3107 | if (typeof check === 'object' && check !== undefined) return check; |
| 3108 | } |
| 3109 | if (args.pattern !== undefined) { |
| 3110 | const check = this.validateOptionalPath(args.pattern, 'pattern'); |