Method handleInitialize

src/mcp/session.ts:185–241

(request: JsonRpcRequest)

  }

  private async handleInitialize(request: JsonRpcRequest): Promise<void> {
    const params = request.params as {
      rootUri?: string;
      workspaceFolders?: Array<{ uri: string; name: string }>;
      capabilities?: { roots?: unknown };
      clientInfo?: { name?: unknown; version?: unknown };
    } | undefined;

    this.clientSupportsRoots = !!params?.capabilities?.roots;
    if (params?.clientInfo) {
      this.clientInfo = {
        name: typeof params.clientInfo.name === 'string' ? params.clientInfo.name : undefined,
        version: typeof params.clientInfo.version === 'string' ? params.clientInfo.version : undefined,
      };
    }

    // Explicit project signal, strongest first: client-provided rootUri /
    // workspaceFolders (LSP-style), else the --path the server was launched
    // with. cwd is NOT used here — we defer it so a roots/list answer can
    // win over it. See issue #196.
    let explicitPath: string | null = null;
    if (params?.rootUri) {
      explicitPath = fileUriToPath(params.rootUri);
    } else if (params?.workspaceFolders?.[0]?.uri) {
      explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
    } else if (this.explicitProjectPath) {
      explicitPath = this.explicitProjectPath;
    }

    // Pick the instructions variant by the root's index state — a cheap
    // synchronous walk-up (existsSync loop only, no DB open, so the #172
    // respond-fast contract holds). When the root IS indexed, send the full
    // single-project playbook. When it ISN'T, send the per-project variant
    // (tools are still exposed — see handleToolsList): it tells the agent there
    // is no default project and to pass `projectPath` to any project that has a
    // `.codegraph/`. Gating tool AVAILABILITY on whether `./` is indexed was the
    // #964 bug — it broke monorepos (only sub-projects indexed) and never
    // surfaced the tools after a mid-session `codegraph init`. When no explicit
    // path is known yet (roots/list dance pending), cwd is the best predictor of
    // where the default project will resolve.
    const indexed = findNearestCodeGraphRoot(explicitPath ?? process.cwd()) !== null;

    // Respond to the handshake BEFORE doing any heavy init — see issue #172.
    this.transport.sendResult(request.id, {
      protocolVersion: PROTOCOL_VERSION,
      capabilities: { tools: {} },
      serverInfo: SERVER_INFO,
      instructions: initializeInstructions(indexed ? SERVER_INSTRUCTIONS : SERVER_INSTRUCTIONS_NO_ROOT_INDEX),
    });

    if (explicitPath) {
      // Kick off engine init in the background. If another session in the
      // same daemon already opened the project, `ensureInitialized` is a
      // ~free no-op — N concurrent clients pay exactly one open.
      this.resolvePromise = this.engine.ensureInitialized(explicitPath);
    }
  }