fix: tighten multi-project root handling

PatrickSys · PatrickSys · commit 27f17001aec9 · 2026-03-08T19:41:42.000+01:00
diff --git a/README.md b/README.md
@@ -72,10 +72,10 @@ Start with the default setup:
 
 ### Pick the right setup
 
-| Situation | Recommended config |
-| --- | --- |
-| Default setup | Run `npx -y codebase-context` with no project path |
-| Single repo setup | Append one project path or set `CODEBASE_ROOT` |
+| Situation                             | Recommended config                                                                                   |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Default setup                         | Run `npx -y codebase-context` with no project path                                                   |
+| Single repo setup                     | Append one project path or set `CODEBASE_ROOT`                                                       |
 | Multi-project call is still ambiguous | Retry with `project`, or keep separate server entries if your client cannot preserve project context |
 
 ### Recommended setup
@@ -195,11 +195,11 @@ The MCP server can serve multiple projects in one session without requiring one
 
 Three cases matter:
 
-| Case | What happens |
-| --- | --- |
-| One project | Routing is automatic |
+| Case                                                               | What happens                                                  |
+| ------------------------------------------------------------------ | ------------------------------------------------------------- |
+| One project                                                        | Routing is automatic                                          |
 | Multiple projects and the client provides enough workspace context | The server can route across those projects in one MCP session |
-| Multiple projects and the target is still ambiguous | The server does not guess. Use `project` explicitly |
+| Multiple projects and the target is still ambiguous                | The server does not guess. Use `project` explicitly           |
 
 Important rules:
 
@@ -265,7 +265,7 @@ Then point your MCP client at the local build:
   "mcpServers": {
     "codebase-context": {
       "command": "node",
-      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js"]
+      "args": ["<path-to-local-build>/dist/index.js"]
     }
   }
 }
@@ -278,7 +278,7 @@ If the default setup is not enough for your client, use this instead:
   "mcpServers": {
     "codebase-context": {
       "command": "node",
-      "args": ["C:/Users/bitaz/Repos/codebase-context/dist/index.js", "C:/path/to/your/project"]
+      "args": ["<path-to-local-build>/dist/index.js", "/path/to/your/project"]
     }
   }
 }
@@ -514,7 +514,7 @@ Structured filters available: `framework`, `language`, `componentType`, `layer`
 | ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `EMBEDDING_PROVIDER`     | `transformers`             | `openai` (fast, cloud) or `transformers` (local, private)                                                  |
 | `OPENAI_API_KEY`         | -                          | Required only if using `openai` provider                                                                   |
-| `CODEBASE_ROOT`          | -                          | Optional bootstrap root for CLI and single-project MCP clients without roots                              |
+| `CODEBASE_ROOT`          | -                          | Optional bootstrap root for CLI and single-project MCP clients without roots                               |
 | `CODEBASE_CONTEXT_DEBUG` | -                          | Set to `1` for verbose logging                                                                             |
 | `EMBEDDING_MODEL`        | `Xenova/bge-small-en-v1.5` | Local embedding model override (e.g. `onnx-community/granite-embedding-small-english-r2-ONNX` for Granite) |
 
diff --git a/src/index.ts b/src/index.ts
@@ -1200,19 +1200,42 @@ async function refreshDiscoveredProjectsForKnownRoots(): Promise<void> {
   );
 }
 
+async function validateClientRootEntries(
+  rootEntries: Array<{ rootPath: string; label?: string }>
+): Promise<Array<{ rootPath: string; label?: string }>> {
+  const validatedRoots = await Promise.all(
+    rootEntries.map(async (entry) => {
+      try {
+        const stats = await fs.stat(entry.rootPath);
+        if (!stats.isDirectory()) {
+          return undefined;
+        }
+
+        return entry;
+      } catch {
+        return undefined;
+      }
+    })
+  );
+
+  return validatedRoots.filter((entry): entry is { rootPath: string; label?: string } => !!entry);
+}
+
 async function refreshKnownRootsFromClient(): Promise<void> {
   try {
     const { roots } = await server.listRoots();
-    const fileRoots = roots
-      .map((root) => ({
-        uri: root.uri,
-        label: typeof root.name === 'string' && root.name.trim() ? root.name.trim() : undefined
-      }))
-      .filter((root) => root.uri.startsWith('file://'))
-      .map((root) => ({
-        rootPath: fileURLToPath(root.uri),
-        label: root.label
-      }));
+    const fileRoots = await validateClientRootEntries(
+      roots
+        .map((root) => ({
+          uri: root.uri,
+          label: typeof root.name === 'string' && root.name.trim() ? root.name.trim() : undefined
+        }))
+        .filter((root) => root.uri.startsWith('file://'))
+        .map((root) => ({
+          rootPath: fileURLToPath(root.uri),
+          label: root.label
+        }))
+    );
 
     clientRootsEnabled = fileRoots.length > 0;
     syncKnownRoots(fileRoots);
@@ -1222,14 +1245,6 @@ async function refreshKnownRootsFromClient(): Promise<void> {
   }
 
   await refreshDiscoveredProjectsForKnownRoots();
-
-  await Promise.all(
-    getKnownRootPaths().map((rootPath) =>
-      initProject(rootPath, watcherDebounceMs, { enableWatcher: false }).catch(() => {
-        /* best-effort prewarm */
-      })
-    )
-  );
 }
 
 async function resolveExplicitProjectSelection(selection: {
@@ -1605,7 +1620,7 @@ async function main() {
 
   await refreshKnownRootsFromClient();
 
-  // Keep the current single-project auto-select behavior while roots are pre-warmed in background.
+  // Keep the current single-project auto-select behavior when exactly one startup project is known.
   const startupRoots = getKnownRootPaths();
   if (startupRoots.length === 1) {
     await initProject(startupRoots[0], watcherDebounceMs, { enableWatcher: true });
diff --git a/tests/multi-project-routing.test.ts b/tests/multi-project-routing.test.ts
@@ -11,10 +11,7 @@ import {
   KEYWORD_INDEX_FILENAME,
   VECTOR_DB_DIRNAME
 } from '../src/constants/codebase-context.js';
-import {
-  CONTEXT_RESOURCE_URI,
-  buildProjectContextResourceUri
-} from '../src/resources/uri.js';
+import { CONTEXT_RESOURCE_URI, buildProjectContextResourceUri } from '../src/resources/uri.js';
 
 interface SearchResultRow {
   summary: string;
@@ -47,6 +44,10 @@ const searchMocks = vi.hoisted(() => ({
   search: vi.fn()
 }));
 
+const indexerMocks = vi.hoisted(() => ({
+  index: vi.fn()
+}));
+
 const watcherMocks = vi.hoisted(() => ({
   start: vi.fn()
 }));
@@ -72,6 +73,7 @@ vi.mock('../src/core/indexer.js', () => {
     }
 
     async index() {
+      indexerMocks.index();
       return {
         totalFiles: 0,
         indexedFiles: 0,
@@ -172,6 +174,7 @@ describe('multi-project routing', () => {
   beforeEach(async () => {
     vi.resetModules();
     searchMocks.search.mockReset();
+    indexerMocks.index.mockReset();
     watcherMocks.start.mockReset();
 
     originalArgv = [...process.argv];
@@ -258,6 +261,75 @@ describe('multi-project routing', () => {
     }
   });
 
+  it('ignores invalid client roots instead of registering or creating them', async () => {
+    delete process.env.CODEBASE_ROOT;
+    delete process.argv[2];
+
+    const missingRoot = path.join(os.tmpdir(), `cc-missing-root-${Date.now()}`);
+    const { server, refreshKnownRootsFromClient } = await import('../src/index.js');
+    const typedServer = server as unknown as TestServer & {
+      listRoots: () => Promise<{ roots: Array<{ uri: string; name?: string }> }>;
+    };
+    const originalListRoots = typedServer.listRoots.bind(typedServer);
+    const toolHandler = typedServer._requestHandlers.get('tools/call');
+    const resourceHandler = typedServer._requestHandlers.get('resources/read');
+    if (!toolHandler || !resourceHandler) throw new Error('required handlers not registered');
+
+    typedServer.listRoots = vi.fn().mockResolvedValue({
+      roots: [{ uri: pathToFileURL(missingRoot).href, name: 'Missing' }]
+    });
+
+    try {
+      await refreshKnownRootsFromClient();
+
+      const response = await callTool(toolHandler, 90, 'search_codebase', { query: 'feature' });
+      const payload = parsePayload(response) as {
+        status: string;
+        errorCode: string;
+      };
+
+      expect(response.isError).toBe(true);
+      expect(payload.status).toBe('selection_required');
+      expect(payload.errorCode).toBe('selection_required');
+      await expect(fs.stat(missingRoot)).rejects.toThrow();
+
+      const resourceResponse = (await resourceHandler({
+        jsonrpc: '2.0',
+        id: 91,
+        method: 'resources/read',
+        params: { uri: CONTEXT_RESOURCE_URI }
+      })) as ResourceReadResponse;
+
+      expect(resourceResponse.contents[0]?.text).not.toContain(missingRoot);
+    } finally {
+      typedServer.listRoots = originalListRoots;
+    }
+  });
+
+  it('does not eagerly index every announced root during background refresh', async () => {
+    delete process.env.CODEBASE_ROOT;
+    delete process.argv[2];
+
+    const unindexedRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'cc-unindexed-root-'));
+    const { server, refreshKnownRootsFromClient } = await import('../src/index.js');
+    const typedServer = server as unknown as TestServer & {
+      listRoots: () => Promise<{ roots: Array<{ uri: string; name?: string }> }>;
+    };
+    const originalListRoots = typedServer.listRoots.bind(typedServer);
+
+    typedServer.listRoots = vi.fn().mockResolvedValue({
+      roots: [{ uri: pathToFileURL(unindexedRoot).href, name: 'Unindexed' }]
+    });
+
+    try {
+      await refreshKnownRootsFromClient();
+      expect(indexerMocks.index).not.toHaveBeenCalled();
+    } finally {
+      typedServer.listRoots = originalListRoots;
+      await fs.rm(unindexedRoot, { recursive: true, force: true });
+    }
+  });
+
   it('supports explicit project routing without bootstrap roots when the client does not expose roots', async () => {
     delete process.env.CODEBASE_ROOT;
     delete process.argv[2];
@@ -337,7 +409,9 @@ describe('multi-project routing', () => {
     expect(payload.status).toBe('success');
     expect(payload.project.rootPath).toBe(primaryRoot);
     expect(payload.project.project).toBe(primaryRoot);
-    expect(watcherMocks.start).toHaveBeenCalledWith(expect.objectContaining({ rootPath: primaryRoot }));
+    expect(watcherMocks.start).toHaveBeenCalledWith(
+      expect.objectContaining({ rootPath: primaryRoot })
+    );
   });
 
   it('explicit project starts a watcher and makes that project active', async () => {
@@ -371,7 +445,8 @@ describe('multi-project routing', () => {
       query: 'feature',
       project: secondaryRoot
     });
-    const selectedProject = (parsePayload(selection) as { project: { project: string } }).project.project;
+    const selectedProject = (parsePayload(selection) as { project: { project: string } }).project
+      .project;
 
     const response = await callTool(handler, 7, 'search_codebase', { query: 'feature' });
     const payload = parsePayload(response) as {
@@ -383,13 +458,9 @@ describe('multi-project routing', () => {
     expect(payload.status).toBe('success');
     expect(payload.project.project).toBe(selectedProject);
     expect(payload.project.rootPath).toBe(secondaryRoot);
-    expect(searchMocks.search).toHaveBeenCalledWith(
-      secondaryRoot,
-      'feature',
-      5,
-      undefined,
-      { profile: 'explore' }
-    );
+    expect(searchMocks.search).toHaveBeenCalledWith(secondaryRoot, 'feature', 5, undefined, {
+      profile: 'explore'
+    });
     expect(payload.results[0]?.file).toContain('feature.ts');
   });
 
@@ -501,7 +572,9 @@ describe('multi-project routing', () => {
       })) as ResourceReadResponse;
 
       expect(response.contents[0]?.text).toContain('# Codebase Workspace');
-      expect(response.contents[0]?.text).toContain('client-announced roots as the workspace boundary');
+      expect(response.contents[0]?.text).toContain(
+        'client-announced roots as the workspace boundary'
+      );
       expect(response.contents[0]?.text).toContain('codebase://context/project/');
       expect(response.contents[0]?.text).toContain('retry tool calls with `project`');
       expect(response.contents[0]?.text).toContain('apps/dashboard');
@@ -547,9 +620,7 @@ describe('multi-project routing', () => {
       params: { uri: buildProjectContextResourceUri(payload.project.project) }
     })) as ResourceReadResponse;
 
-    expect(response.contents[0]?.uri).toBe(
-      buildProjectContextResourceUri(payload.project.project)
-    );
+    expect(response.contents[0]?.uri).toBe(buildProjectContextResourceUri(payload.project.project));
     expect(response.contents[0]?.text).toContain('# Codebase Intelligence');
   });
 
