codebase-context 1.8.2 → 1.9.0

package/dist/index.js

@@ -5,54 +5,374 @@
  */
 import { promises as fs } from 'fs';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, RootsListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
 import { CodebaseIndexer } from './core/indexer.js';
 import { analyzerRegistry } from './core/analyzer-registry.js';
 import { AngularAnalyzer } from './analyzers/angular/index.js';
 import { GenericAnalyzer } from './analyzers/generic/index.js';
 import { IndexCorruptedError } from './errors/index.js';
-import { CODEBASE_CONTEXT_DIRNAME, MEMORY_FILENAME, INTELLIGENCE_FILENAME, KEYWORD_INDEX_FILENAME, VECTOR_DB_DIRNAME } from './constants/codebase-context.js';
 import { appendMemoryFile } from './memory/store.js';
 import { handleCliCommand } from './cli.js';
 import { startFileWatcher } from './core/file-watcher.js';
-import { createAutoRefreshController } from './core/auto-refresh.js';
 import { parseGitLogLineToMemory } from './memory/git-memory.js';
 import { isComplementaryPatternCategory, shouldSkipLegacyTestingFrameworkCategory } from './patterns/semantics.js';
-import { CONTEXT_RESOURCE_URI, isContextResourceUri } from './resources/uri.js';
+import { CONTEXT_RESOURCE_URI, buildProjectContextResourceUri, getProjectPathFromContextResourceUri, isContextResourceUri } from './resources/uri.js';
+import { discoverProjectsWithinRoot, findNearestProjectBoundary, isPathWithin } from './utils/project-discovery.js';
 import { readIndexMeta, validateIndexArtifacts } from './core/index-meta.js';
 import { TOOLS, dispatchTool } from './tools/index.js';
+import { getOrCreateProject, getAllProjects, getProject, makePaths, makeLegacyPaths, normalizeRootKey, removeProject } from './project-state.js';
 analyzerRegistry.register(new AngularAnalyzer());
 analyzerRegistry.register(new GenericAnalyzer());
-// Resolve root path with validation
+// Resolve optional bootstrap root with validation handled later in main().
 function resolveRootPath() {
     const arg = process.argv[2];
     const envPath = process.env.CODEBASE_ROOT;
-    // Priority: CLI arg > env var > cwd
-    let rootPath = arg || envPath || process.cwd();
-    rootPath = path.resolve(rootPath);
-    // Warn if using cwd as fallback (guarded to avoid stderr during MCP STDIO handshake)
-    if (!arg && !envPath && process.env.CODEBASE_CONTEXT_DEBUG) {
-        console.error(`[DEBUG] No project path specified. Using current directory: ${rootPath}`);
-        console.error(`[DEBUG] Hint: Specify path as CLI argument or set CODEBASE_ROOT env var`);
-    }
-    return rootPath;
-}
-const ROOT_PATH = resolveRootPath();
-// File paths (new structure)
-const PATHS = {
-    baseDir: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME),
-    memory: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, MEMORY_FILENAME),
-    intelligence: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, INTELLIGENCE_FILENAME),
-    keywordIndex: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, KEYWORD_INDEX_FILENAME),
-    vectorDb: path.join(ROOT_PATH, CODEBASE_CONTEXT_DIRNAME, VECTOR_DB_DIRNAME)
-};
-const LEGACY_PATHS = {
-    intelligence: path.join(ROOT_PATH, '.codebase-intelligence.json'),
-    keywordIndex: path.join(ROOT_PATH, '.codebase-index.json'),
-    vectorDb: path.join(ROOT_PATH, '.codebase-index')
-};
+    // Priority: CLI arg > env var. Do not fall back to cwd in MCP mode.
+    const configuredRoot = arg || envPath;
+    if (!configuredRoot) {
+        return undefined;
+    }
+    return path.resolve(configuredRoot);
+}
+const primaryRootPath = resolveRootPath();
+const toolNames = new Set(TOOLS.map((tool) => tool.name));
+const knownRoots = new Map();
+const discoveredProjectPaths = new Map();
+let clientRootsEnabled = false;
+const projectSourcesByKey = new Map();
+const projectAccessOrder = new Map();
+let activeProjectKey;
+let nextProjectAccessOrder = 1;
+const MAX_WATCHED_PROJECTS = 5;
+const PROJECT_DISCOVERY_MAX_DEPTH = 4;
+const debounceEnv = Number.parseInt(process.env.CODEBASE_CONTEXT_DEBOUNCE_MS ?? '', 10);
+const watcherDebounceMs = Number.isFinite(debounceEnv) && debounceEnv >= 0 ? debounceEnv : 2000;
+function registerKnownRoot(rootPath) {
+    const resolvedRootPath = path.resolve(rootPath);
+    knownRoots.set(normalizeRootKey(resolvedRootPath), { rootPath: resolvedRootPath });
+    rememberProjectPath(resolvedRootPath, 'root');
+    return resolvedRootPath;
+}
+function getKnownRootPaths() {
+    return Array.from(knownRoots.values())
+        .map((entry) => entry.rootPath)
+        .sort((a, b) => a.localeCompare(b));
+}
+function getKnownRootLabel(rootPath) {
+    return knownRoots.get(normalizeRootKey(rootPath))?.label;
+}
+function getContainingKnownRoot(rootPath) {
+    const orderedRoots = getKnownRootPaths().sort((a, b) => b.length - a.length);
+    return orderedRoots.find((knownRootPath) => isPathWithin(knownRootPath, rootPath));
+}
+function classifyProjectSource(rootPath) {
+    const rootKey = normalizeRootKey(rootPath);
+    if (knownRoots.has(rootKey)) {
+        return 'root';
+    }
+    return getContainingKnownRoot(rootPath) ? 'subdirectory' : 'ad_hoc';
+}
+function touchProject(rootPath) {
+    projectAccessOrder.set(normalizeRootKey(rootPath), nextProjectAccessOrder++);
+}
+function rememberProjectPath(rootPath, source = classifyProjectSource(rootPath), options = {}) {
+    const resolvedRootPath = path.resolve(rootPath);
+    const rootKey = normalizeRootKey(resolvedRootPath);
+    const existingSource = projectSourcesByKey.get(rootKey);
+    if (!existingSource ||
+        source === 'root' ||
+        (source === 'subdirectory' && existingSource === 'ad_hoc')) {
+        projectSourcesByKey.set(rootKey, source);
+    }
+    if (options.touch !== false) {
+        touchProject(resolvedRootPath);
+    }
+}
+function registerDiscoveredProjectPath(rootPath, source = 'subdirectory') {
+    const resolvedRootPath = path.resolve(rootPath);
+    discoveredProjectPaths.set(normalizeRootKey(resolvedRootPath), resolvedRootPath);
+    rememberProjectPath(resolvedRootPath, source, { touch: false });
+}
+function clearDiscoveredProjectPaths() {
+    discoveredProjectPaths.clear();
+}
+function getTrackedRootPathByKey(rootKey) {
+    if (knownRoots.has(rootKey)) {
+        return knownRoots.get(rootKey)?.rootPath;
+    }
+    const project = Array.from(getAllProjects()).find((entry) => normalizeRootKey(entry.rootPath) === rootKey);
+    return project?.rootPath;
+}
+function forgetProjectPath(rootPath) {
+    const rootKey = normalizeRootKey(rootPath);
+    projectSourcesByKey.delete(rootKey);
+    projectAccessOrder.delete(rootKey);
+    if (activeProjectKey === rootKey) {
+        activeProjectKey = undefined;
+    }
+}
+function formatProjectLabel(rootPath) {
+    const knownRootLabel = getKnownRootLabel(rootPath);
+    if (knownRootLabel) {
+        return knownRootLabel;
+    }
+    const containingRoot = getContainingKnownRoot(rootPath);
+    if (containingRoot) {
+        const relativePath = path.relative(containingRoot, rootPath);
+        if (!relativePath) {
+            return getKnownRootLabel(containingRoot) ?? (path.basename(rootPath) || rootPath);
+        }
+        return relativePath.replace(/\\/g, '/');
+    }
+    return path.basename(rootPath) || rootPath;
+}
+function getRelativeProjectPath(rootPath) {
+    const containingRoot = getContainingKnownRoot(rootPath);
+    if (!containingRoot)
+        return undefined;
+    const relativePath = path.relative(containingRoot, rootPath).replace(/\\/g, '/');
+    return relativePath || undefined;
+}
+function getProjectIndexStatus(rootPath) {
+    return getProject(rootPath)?.indexState.status ?? 'idle';
+}
+function buildProjectDescriptor(rootPath) {
+    const resolvedRootPath = path.resolve(rootPath);
+    const rootKey = normalizeRootKey(resolvedRootPath);
+    rememberProjectPath(resolvedRootPath, classifyProjectSource(resolvedRootPath), { touch: false });
+    return {
+        project: resolvedRootPath,
+        label: formatProjectLabel(resolvedRootPath),
+        rootPath: resolvedRootPath,
+        relativePath: getRelativeProjectPath(resolvedRootPath),
+        active: activeProjectKey === rootKey,
+        source: projectSourcesByKey.get(rootKey) ?? classifyProjectSource(resolvedRootPath),
+        indexStatus: getProjectIndexStatus(resolvedRootPath)
+    };
+}
+function listProjectDescriptors() {
+    const rootPaths = new Map();
+    for (const rootPath of getKnownRootPaths()) {
+        rootPaths.set(normalizeRootKey(rootPath), rootPath);
+    }
+    for (const [projectKey, rootPath] of discoveredProjectPaths.entries()) {
+        rootPaths.set(projectKey, rootPath);
+    }
+    for (const project of getAllProjects()) {
+        rootPaths.set(normalizeRootKey(project.rootPath), project.rootPath);
+    }
+    const descriptors = Array.from(rootPaths.values())
+        .map((rootPath) => buildProjectDescriptor(rootPath))
+        .sort((a, b) => {
+        if (a.active !== b.active)
+            return a.active ? -1 : 1;
+        if (a.source !== b.source) {
+            const weight = {
+                root: 0,
+                subdirectory: 1,
+                ad_hoc: 2
+            };
+            return weight[a.source] - weight[b.source];
+        }
+        return a.label.localeCompare(b.label);
+    });
+    const duplicates = new Set();
+    const counts = new Map();
+    for (const descriptor of descriptors) {
+        counts.set(descriptor.label, (counts.get(descriptor.label) ?? 0) + 1);
+    }
+    for (const [label, count] of counts.entries()) {
+        if (count > 1) {
+            duplicates.add(label);
+        }
+    }
+    return descriptors.map((descriptor) => {
+        if (!duplicates.has(descriptor.label)) {
+            return descriptor;
+        }
+        const containingRoot = getContainingKnownRoot(descriptor.rootPath);
+        const rootHint = (containingRoot && getKnownRootLabel(containingRoot)) ||
+            (containingRoot && path.basename(containingRoot)) ||
+            path.basename(descriptor.rootPath);
+        return {
+            ...descriptor,
+            label: `${descriptor.label} (${rootHint})`
+        };
+    });
+}
+function getActiveProjectDescriptor() {
+    if (!activeProjectKey)
+        return undefined;
+    const trackedRootPath = getTrackedRootPathByKey(activeProjectKey);
+    if (!trackedRootPath) {
+        activeProjectKey = undefined;
+        return undefined;
+    }
+    return buildProjectDescriptor(trackedRootPath);
+}
+function setActiveProject(rootPath) {
+    const resolvedRootPath = path.resolve(rootPath);
+    activeProjectKey = normalizeRootKey(resolvedRootPath);
+    rememberProjectPath(resolvedRootPath);
+}
+function syncKnownRoots(rootEntries) {
+    const nextRoots = new Map();
+    const normalizedRoots = rootEntries.length > 0 ? rootEntries : primaryRootPath ? [{ rootPath: primaryRootPath }] : [];
+    for (const entry of normalizedRoots) {
+        const resolvedRootPath = path.resolve(entry.rootPath);
+        nextRoots.set(normalizeRootKey(resolvedRootPath), {
+            rootPath: resolvedRootPath,
+            label: entry.label?.trim() || undefined
+        });
+    }
+    for (const [rootKey, existingRoot] of knownRoots.entries()) {
+        if (!nextRoots.has(rootKey)) {
+            removeProject(existingRoot.rootPath);
+            forgetProjectPath(existingRoot.rootPath);
+        }
+    }
+    for (const project of getAllProjects()) {
+        const stillAllowed = Array.from(nextRoots.values()).some((knownRoot) => isPathWithin(knownRoot.rootPath, project.rootPath));
+        if (!stillAllowed) {
+            removeProject(project.rootPath);
+            forgetProjectPath(project.rootPath);
+        }
+    }
+    knownRoots.clear();
+    clearDiscoveredProjectPaths();
+    for (const [rootKey, rootEntry] of nextRoots.entries()) {
+        knownRoots.set(rootKey, rootEntry);
+        rememberProjectPath(rootEntry.rootPath, 'root', { touch: false });
+    }
+    if (activeProjectKey) {
+        if (!getTrackedRootPathByKey(activeProjectKey)) {
+            activeProjectKey = undefined;
+        }
+    }
+}
+function parseProjectSelector(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmedValue = value.trim();
+    if (!trimmedValue)
+        return undefined;
+    return trimmedValue;
+}
+function parseProjectDirectory(value) {
+    const selector = parseProjectSelector(value);
+    if (!selector)
+        return undefined;
+    return selector.startsWith('file://')
+        ? path.resolve(fileURLToPath(selector))
+        : path.resolve(selector);
+}
+function getProjectSourceForResolvedPath(rootPath) {
+    return getContainingKnownRoot(rootPath) ? 'subdirectory' : 'ad_hoc';
+}
+async function resolveProjectFromAbsolutePath(resolvedPath) {
+    const absolutePath = path.resolve(resolvedPath);
+    const containingRoot = getContainingKnownRoot(absolutePath);
+    if (clientRootsEnabled && getKnownRootPaths().length > 0 && !containingRoot) {
+        return {
+            ok: false,
+            response: buildProjectSelectionError('unknown_project', 'Requested project is not under an active MCP root.')
+        };
+    }
+    let stats;
+    try {
+        stats = await fs.stat(absolutePath);
+    }
+    catch {
+        return {
+            ok: false,
+            response: buildProjectSelectionError('unknown_project', `project does not exist: ${absolutePath}`)
+        };
+    }
+    const lookupPath = stats.isDirectory() ? absolutePath : path.dirname(absolutePath);
+    const exactDescriptor = listProjectDescriptors().find((descriptor) => normalizeRootKey(descriptor.rootPath) === normalizeRootKey(lookupPath));
+    if (exactDescriptor) {
+        const project = getOrCreateProject(exactDescriptor.rootPath);
+        if (exactDescriptor.source === 'subdirectory') {
+            registerDiscoveredProjectPath(exactDescriptor.rootPath, 'subdirectory');
+        }
+        else {
+            rememberProjectPath(exactDescriptor.rootPath, exactDescriptor.source, { touch: false });
+        }
+        return { ok: true, project };
+    }
+    const nearestBoundary = await findNearestProjectBoundary(absolutePath, containingRoot);
+    const resolvedProjectPath = nearestBoundary?.rootPath ?? containingRoot ?? (stats.isDirectory() ? absolutePath : undefined);
+    if (!resolvedProjectPath) {
+        return {
+            ok: false,
+            response: buildProjectSelectionError('unknown_project', `project was not found from path: ${absolutePath}`)
+        };
+    }
+    const invalidProjectResponse = await validateResolvedProjectPath(resolvedProjectPath);
+    if (invalidProjectResponse) {
+        return { ok: false, response: invalidProjectResponse };
+    }
+    const projectSource = getProjectSourceForResolvedPath(resolvedProjectPath);
+    if (projectSource === 'subdirectory') {
+        registerDiscoveredProjectPath(resolvedProjectPath, 'subdirectory');
+    }
+    else {
+        rememberProjectPath(resolvedProjectPath, projectSource, { touch: false });
+    }
+    const project = getOrCreateProject(resolvedProjectPath);
+    return { ok: true, project };
+}
+function buildProjectSelectionPayload(status, message, project, extras = {}) {
+    return {
+        status,
+        message,
+        activeProject: project
+            ? buildProjectDescriptor(project.rootPath)
+            : (getActiveProjectDescriptor() ?? null),
+        availableProjects: listProjectDescriptors(),
+        ...extras
+    };
+}
+function buildProjectSelectionError(errorCode, message, extras = {}) {
+    const status = errorCode === 'selection_required' ? 'selection_required' : 'error';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ ...buildProjectSelectionPayload(status, message, undefined, extras), errorCode }, null, 2)
+            }
+        ],
+        isError: true
+    };
+}
+function createToolContext(project) {
+    return {
+        indexState: project.indexState,
+        paths: project.paths,
+        rootPath: project.rootPath,
+        project: buildProjectDescriptor(project.rootPath),
+        performIndexing: (incrementalOnly) => performIndexing(project, incrementalOnly),
+        listProjects: () => listProjectDescriptors(),
+        getActiveProject: () => getActiveProjectDescriptor()
+    };
+}
+function createWorkspaceToolContext() {
+    const fallbackRootPath = primaryRootPath ?? path.resolve(process.cwd());
+    return {
+        indexState: { status: 'idle' },
+        paths: makePaths(fallbackRootPath),
+        rootPath: fallbackRootPath,
+        performIndexing: () => undefined,
+        listProjects: () => listProjectDescriptors(),
+        getActiveProject: () => getActiveProjectDescriptor()
+    };
+}
+if (primaryRootPath) {
+    registerKnownRoot(primaryRootPath);
+}
 export const INDEX_CONSUMING_TOOL_NAMES = [
     'search_codebase',
     'get_symbol_references',
@@ -61,11 +381,11 @@ export const INDEX_CONSUMING_TOOL_NAMES = [
     'get_codebase_metadata'
 ];
 export const INDEX_CONSUMING_RESOURCE_NAMES = ['Codebase Intelligence'];
-async function requireValidIndex(rootPath) {
+async function requireValidIndex(rootPath, paths) {
     const meta = await readIndexMeta(rootPath);
     await validateIndexArtifacts(rootPath, meta);
     // Optional artifact presence informs confidence.
-    const hasIntelligence = await fileExists(PATHS.intelligence);
+    const hasIntelligence = await fileExists(paths.intelligence);
     return {
         status: 'ready',
         confidence: hasIntelligence ? 'high' : 'low',
@@ -73,8 +393,8 @@ async function requireValidIndex(rootPath) {
         ...(hasIntelligence ? {} : { reason: 'Optional intelligence artifact missing' })
     };
 }
-async function ensureValidIndexOrAutoHeal() {
-    if (indexState.status === 'indexing') {
+async function ensureValidIndexOrAutoHeal(project) {
+    if (project.indexState.status === 'indexing') {
         return {
             status: 'indexing',
             confidence: 'low',
@@ -83,40 +403,118 @@ async function ensureValidIndexOrAutoHeal() {
         };
     }
     try {
-        return await requireValidIndex(ROOT_PATH);
+        return await requireValidIndex(project.rootPath, project.paths);
     }
     catch (error) {
         if (error instanceof IndexCorruptedError) {
             const reason = error.message;
             console.error(`[Index] ${reason}`);
-            console.error('[Auto-Heal] Triggering full re-index...');
-            await performIndexing();
-            if (indexState.status === 'ready') {
-                try {
-                    let validated = await requireValidIndex(ROOT_PATH);
-                    validated = { ...validated, action: 'rebuilt-and-served', reason };
-                    return validated;
-                }
-                catch (revalidateError) {
-                    const msg = revalidateError instanceof Error ? revalidateError.message : String(revalidateError);
-                    return {
-                        status: 'rebuild-required',
-                        confidence: 'low',
-                        action: 'rebuild-failed',
-                        reason: `Auto-heal completed but index did not validate: ${msg}`
-                    };
-                }
-            }
+            console.error('[Auto-Heal] Triggering background re-index...');
+            // Fire-and-forget: don't block the tool call
+            void performIndexing(project);
             return {
-                status: 'rebuild-required',
+                status: 'indexing',
                 confidence: 'low',
-                action: 'rebuild-failed',
-                reason: `Auto-heal failed: ${indexState.error || reason}`
+                action: 'rebuild-started',
+                reason: `Auto-heal triggered: ${reason}`
             };
         }
         throw error;
     }
 }
+async function validateResolvedProjectPath(rootPath) {
+    try {
+        const stats = await fs.stat(rootPath);
+        if (!stats.isDirectory()) {
+            return buildProjectSelectionError('unknown_project', `project is not a directory: ${rootPath}`);
+        }
+        if (clientRootsEnabled && getKnownRootPaths().length > 0 && !getContainingKnownRoot(rootPath)) {
+            return buildProjectSelectionError('unknown_project', 'Requested project is not under an active MCP root.');
+        }
+        return undefined;
+    }
+    catch {
+        return buildProjectSelectionError('unknown_project', `project does not exist: ${rootPath}`);
+    }
+}
+async function resolveProjectSelector(selector) {
+    const trimmedSelector = selector.trim();
+    if (!trimmedSelector) {
+        return {
+            ok: false,
+            response: buildProjectSelectionError('unknown_project', 'project must be a non-empty absolute path, file:// URI, or relative subproject path.')
+        };
+    }
+    if (trimmedSelector.startsWith('file://') || path.isAbsolute(trimmedSelector)) {
+        const resolvedPath = parseProjectDirectory(trimmedSelector);
+        if (!resolvedPath) {
+            return {
+                ok: false,
+                response: buildProjectSelectionError('unknown_project', 'project must be a non-empty absolute path, file:// URI, or relative subproject path.')
+            };
+        }
+        return resolveProjectFromAbsolutePath(resolvedPath);
+    }
+    const normalizedSelector = trimmedSelector.replace(/\\/g, '/').replace(/^\.\/+/, '');
+    const descriptorMatches = listProjectDescriptors().filter((descriptor) => descriptor.label === normalizedSelector ||
+        descriptor.relativePath === normalizedSelector ||
+        path.basename(descriptor.rootPath) === normalizedSelector);
+    if (descriptorMatches.length === 1) {
+        const matchedRootPath = descriptorMatches[0].rootPath;
+        if (descriptorMatches[0].source === 'subdirectory') {
+            registerDiscoveredProjectPath(matchedRootPath, 'subdirectory');
+        }
+        else {
+            rememberProjectPath(matchedRootPath, classifyProjectSource(matchedRootPath), {
+                touch: false
+            });
+        }
+        const project = getOrCreateProject(matchedRootPath);
+        return { ok: true, project };
+    }
+    if (descriptorMatches.length > 1) {
+        return {
+            ok: false,
+            response: buildProjectSelectionError('selection_required', `Project selector "${normalizedSelector}" matches multiple known projects. Retry with an absolute path.`, {
+                reason: 'project_selector_ambiguous',
+                nextAction: 'retry_with_project'
+            })
+        };
+    }
+    const matchingProjects = getKnownRootPaths()
+        .map((rootPath) => ({ rootPath, candidatePath: path.resolve(rootPath, normalizedSelector) }))
+        .filter(({ rootPath, candidatePath }) => isPathWithin(rootPath, candidatePath))
+        .map(({ candidatePath }) => candidatePath);
+    const resolvedMatches = new Map();
+    for (const candidatePath of matchingProjects) {
+        const resolution = await resolveProjectFromAbsolutePath(candidatePath);
+        if (resolution.ok) {
+            resolvedMatches.set(normalizeRootKey(resolution.project.rootPath), resolution.project);
+            continue;
+        }
+        const payload = JSON.parse(resolution.response.content?.[0]?.text ?? '{}');
+        if (payload.errorCode !== 'unknown_project') {
+            return resolution;
+        }
+    }
+    if (resolvedMatches.size === 1) {
+        const project = Array.from(resolvedMatches.values())[0];
+        return { ok: true, project };
+    }
+    if (resolvedMatches.size > 1) {
+        return {
+            ok: false,
+            response: buildProjectSelectionError('selection_required', `Relative project path "${normalizedSelector}" matches multiple configured roots. Retry with an absolute path.`, {
+                reason: 'relative_project_ambiguous',
+                nextAction: 'retry_with_project'
+            })
+        };
+    }
+    return {
+        ok: false,
+        response: buildProjectSelectionError('unknown_project', `Relative project path "${normalizedSelector}" was not found under any configured root.`)
+    };
+}
 /**
  * Check if file/directory exists
  */
@@ -133,14 +531,14 @@ async function fileExists(filePath) {
  * Migrate legacy file structure to .codebase-context/ folder.
  * Idempotent, fail-safe. Rollback compatibility is not required.
  */
-async function migrateToNewStructure() {
+async function migrateToNewStructure(paths, legacyPaths) {
     let migrated = false;
     try {
-        await fs.mkdir(PATHS.baseDir, { recursive: true });
+        await fs.mkdir(paths.baseDir, { recursive: true });
         // intelligence.json
-        if (!(await fileExists(PATHS.intelligence))) {
-            if (await fileExists(LEGACY_PATHS.intelligence)) {
-                await fs.copyFile(LEGACY_PATHS.intelligence, PATHS.intelligence);
+        if (!(await fileExists(paths.intelligence))) {
+            if (await fileExists(legacyPaths.intelligence)) {
+                await fs.copyFile(legacyPaths.intelligence, paths.intelligence);
                 migrated = true;
                 if (process.env.CODEBASE_CONTEXT_DEBUG) {
                     console.error('[DEBUG] Migrated intelligence.json');
@@ -148,9 +546,9 @@ async function migrateToNewStructure() {
             }
         }
         // index.json (keyword index)
-        if (!(await fileExists(PATHS.keywordIndex))) {
-            if (await fileExists(LEGACY_PATHS.keywordIndex)) {
-                await fs.copyFile(LEGACY_PATHS.keywordIndex, PATHS.keywordIndex);
+        if (!(await fileExists(paths.keywordIndex))) {
+            if (await fileExists(legacyPaths.keywordIndex)) {
+                await fs.copyFile(legacyPaths.keywordIndex, paths.keywordIndex);
                 migrated = true;
                 if (process.env.CODEBASE_CONTEXT_DEBUG) {
                     console.error('[DEBUG] Migrated index.json');
@@ -158,9 +556,9 @@ async function migrateToNewStructure() {
             }
         }
         // Vector DB directory
-        if (!(await fileExists(PATHS.vectorDb))) {
-            if (await fileExists(LEGACY_PATHS.vectorDb)) {
-                await fs.rename(LEGACY_PATHS.vectorDb, PATHS.vectorDb);
+        if (!(await fileExists(paths.vectorDb))) {
+            if (await fileExists(legacyPaths.vectorDb)) {
+                await fs.rename(legacyPaths.vectorDb, paths.vectorDb);
                 migrated = true;
                 if (process.env.CODEBASE_CONTEXT_DEBUG) {
                     console.error('[DEBUG] Migrated vector database');
@@ -178,10 +576,6 @@ async function migrateToNewStructure() {
 }
 // Read version from package.json so it never drifts
 const PKG_VERSION = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url), 'utf-8')).version;
-const indexState = {
-    status: 'idle'
-};
-const autoRefresh = createAutoRefreshController();
 const server = new Server({
     name: 'codebase-context',
     version: PKG_VERSION
@@ -194,34 +588,37 @@ const server = new Server({
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: TOOLS };
 });
-// MCP Resources - Proactive context injection
-const RESOURCES = [
-    {
-        uri: CONTEXT_RESOURCE_URI,
-        name: 'Codebase Intelligence',
-        description: 'Automatic codebase context: libraries used, team patterns, and conventions. ' +
-            'Read this BEFORE generating code to follow team standards.',
-        mimeType: 'text/plain'
+function buildResources() {
+    const resources = [
+        {
+            uri: CONTEXT_RESOURCE_URI,
+            name: 'Codebase Intelligence',
+            description: 'Context for the active project in this MCP session. In multi-project sessions, this falls back to a workspace overview until a project is selected.',
+            mimeType: 'text/plain'
+        }
+    ];
+    for (const project of listProjectDescriptors()) {
+        resources.push({
+            uri: buildProjectContextResourceUri(project.rootPath),
+            name: `Codebase Intelligence (${project.label})`,
+            description: `Project-scoped context for ${project.label}.`,
+            mimeType: 'text/plain'
+        });
     }
-];
+    return resources;
+}
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
-    return { resources: RESOURCES };
+    return { resources: buildResources() };
 });
-async function generateCodebaseContext() {
-    const intelligencePath = PATHS.intelligence;
-    const index = await ensureValidIndexOrAutoHeal();
+async function generateCodebaseContext(project) {
+    const intelligencePath = project.paths.intelligence;
+    const index = await ensureValidIndexOrAutoHeal(project);
     if (index.status === 'indexing') {
         return ('# Codebase Intelligence\n\n' +
             'Index is still being built. Retry in a moment.\n\n' +
             `Index: ${index.status} (${index.confidence}, ${index.action})` +
             (index.reason ? `\nReason: ${index.reason}` : ''));
     }
-    if (index.action === 'rebuild-failed') {
-        return ('# Codebase Intelligence\n\n' +
-            'Index rebuild required before intelligence can be served.\n\n' +
-            `Index: ${index.status} (${index.confidence}, ${index.action})` +
-            (index.reason ? `\nReason: ${index.reason}` : ''));
-    }
     try {
         const content = await fs.readFile(intelligencePath, 'utf-8');
         const intelligence = JSON.parse(content);
@@ -338,16 +735,68 @@ async function generateCodebaseContext() {
             `Error: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+function buildProjectSelectionMessage() {
+    const projects = listProjectDescriptors();
+    if (projects.length === 0) {
+        return [
+            '# Codebase Workspace',
+            '',
+            'This MCP session is waiting for project context.',
+            'If your host supports MCP roots, project discovery will begin after the client announces its workspace roots.',
+            'Otherwise retry the tool call with `project` using an absolute project path, file path, or file:// URI.'
+        ].join('\n');
+    }
+    const lines = [
+        '# Codebase Workspace',
+        '',
+        'This MCP session is using client-announced roots as the workspace boundary.',
+        'Automatic routing is only possible when one project is unambiguous or this session already has an active project.',
+        'If the MCP client does not provide enough context, retry tool calls with `project` using a root path, subproject path, or file path.',
+        '',
+        'Available projects:',
+        ''
+    ];
+    for (const project of projects) {
+        const projectPathHint = project.relativePath
+            ? `${project.relativePath} | ${project.rootPath}`
+            : project.rootPath;
+        lines.push(`- ${project.label} [${project.indexStatus}]`);
+        lines.push(`  project: ${projectPathHint}`);
+        lines.push(`  resource: ${buildProjectContextResourceUri(project.rootPath)}`);
+    }
+    lines.push('');
+    lines.push('Recommended flow: retry the tool call with `project`.');
+    return lines.join('\n');
+}
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const uri = request.params.uri;
+    const explicitProjectPath = getProjectPathFromContextResourceUri(uri);
+    if (explicitProjectPath) {
+        const selection = await resolveProjectSelector(explicitProjectPath);
+        if (!selection.ok) {
+            throw new Error(`Unknown project resource: ${uri}`);
+        }
+        const project = selection.project;
+        await initProject(project.rootPath, watcherDebounceMs, { enableWatcher: true });
+        setActiveProject(project.rootPath);
+        return {
+            contents: [
+                {
+                    uri: buildProjectContextResourceUri(project.rootPath),
+                    mimeType: 'text/plain',
+                    text: await generateCodebaseContext(project)
+                }
+            ]
+        };
+    }
     if (isContextResourceUri(uri)) {
-        const content = await generateCodebaseContext();
+        const project = await resolveProjectForResource();
         return {
             contents: [
                 {
                     uri: CONTEXT_RESOURCE_URI,
                     mimeType: 'text/plain',
-                    text: content
+                    text: project ? await generateCodebaseContext(project) : buildProjectSelectionMessage()
                 }
             ]
         };
@@ -358,16 +807,16 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  * Extract memories from conventional git commits (refactor:, migrate:, fix:, revert:).
  * Scans last 90 days. Deduplicates via content hash. Zero friction alternative to manual memory.
  */
-async function extractGitMemories() {
+async function extractGitMemories(rootPath, memoryPath) {
     // Quick check: skip if not a git repo
-    if (!(await fileExists(path.join(ROOT_PATH, '.git'))))
+    if (!(await fileExists(path.join(rootPath, '.git'))))
         return 0;
     const { execSync } = await import('child_process');
     let log;
     try {
         // Format: ISO-date<TAB>hash subject  (e.g. "2026-01-15T10:00:00+00:00\tabc1234 fix: race condition")
         log = execSync('git log --format="%aI\t%h %s" --since="90 days ago" --no-merges', {
-            cwd: ROOT_PATH,
+            cwd: rootPath,
             encoding: 'utf-8',
             timeout: 5000
         }).trim();
@@ -384,20 +833,20 @@ async function extractGitMemories() {
         const parsedMemory = parseGitLogLineToMemory(line);
         if (!parsedMemory)
             continue;
-        const result = await appendMemoryFile(PATHS.memory, parsedMemory);
+        const result = await appendMemoryFile(memoryPath, parsedMemory);
         if (result.status === 'added')
             added++;
     }
     return added;
 }
-async function performIndexingOnce(incrementalOnly) {
-    indexState.status = 'indexing';
+async function performIndexingOnce(project, incrementalOnly) {
+    project.indexState.status = 'indexing';
     const mode = incrementalOnly ? 'incremental' : 'full';
-    console.error(`Indexing (${mode}): ${ROOT_PATH}`);
+    console.error(`Indexing (${mode}): ${project.rootPath}`);
     try {
         let lastLoggedProgress = { phase: '', percentage: -1 };
         const indexer = new CodebaseIndexer({
-            rootPath: ROOT_PATH,
+            rootPath: project.rootPath,
             incrementalOnly,
             onProgress: (progress) => {
                 // Only log when phase or percentage actually changes (prevents duplicate logs)
@@ -409,15 +858,15 @@ async function performIndexingOnce(incrementalOnly) {
                 }
             }
         });
-        indexState.indexer = indexer;
+        project.indexState.indexer = indexer;
         const stats = await indexer.index();
-        indexState.status = 'ready';
-        indexState.lastIndexed = new Date();
-        indexState.stats = stats;
+        project.indexState.status = 'ready';
+        project.indexState.lastIndexed = new Date();
+        project.indexState.stats = stats;
         console.error(`Complete: ${stats.indexedFiles} files, ${stats.totalChunks} chunks in ${(stats.duration / 1000).toFixed(2)}s`);
         // Auto-extract memories from git history (non-blocking, best-effort)
         try {
-            const gitMemories = await extractGitMemories();
+            const gitMemories = await extractGitMemories(project.rootPath, project.paths.memory);
             if (gitMemories > 0) {
                 console.error(`[git-memory] Extracted ${gitMemories} new memor${gitMemories === 1 ? 'y' : 'ies'} from git history`);
             }
@@ -427,16 +876,16 @@ async function performIndexingOnce(incrementalOnly) {
         }
     }
     catch (error) {
-        indexState.status = 'error';
-        indexState.error = error instanceof Error ? error.message : String(error);
-        console.error('Indexing failed:', indexState.error);
+        project.indexState.status = 'error';
+        project.indexState.error = error instanceof Error ? error.message : String(error);
+        console.error('Indexing failed:', project.indexState.error);
     }
 }
-async function performIndexing(incrementalOnly) {
+async function performIndexing(project, incrementalOnly) {
     let nextMode = incrementalOnly;
     for (;;) {
-        await performIndexingOnce(nextMode);
-        const shouldRunQueuedRefresh = autoRefresh.consumeQueuedRefresh(indexState.status);
+        await performIndexingOnce(project, nextMode);
+        const shouldRunQueuedRefresh = project.autoRefresh.consumeQueuedRefresh(project.indexState.status);
         if (!shouldRunQueuedRefresh)
             return;
         if (process.env.CODEBASE_CONTEXT_DEBUG) {
@@ -445,23 +894,156 @@ async function performIndexing(incrementalOnly) {
         nextMode = true;
     }
 }
-async function shouldReindex() {
-    const indexPath = PATHS.keywordIndex;
+async function shouldReindex(paths) {
     try {
-        await fs.access(indexPath);
+        await fs.access(paths.keywordIndex);
         return false;
     }
     catch {
         return true;
     }
 }
+async function refreshDiscoveredProjectsForKnownRoots() {
+    clearDiscoveredProjectPaths();
+    await Promise.all(getKnownRootPaths().map(async (rootPath) => {
+        const candidates = await discoverProjectsWithinRoot(rootPath, {
+            maxDepth: PROJECT_DISCOVERY_MAX_DEPTH
+        });
+        for (const candidate of candidates) {
+            registerDiscoveredProjectPath(candidate.rootPath, 'subdirectory');
+        }
+    }));
+}
+async function validateClientRootEntries(rootEntries) {
+    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);
+}
+async function refreshKnownRootsFromClient() {
+    try {
+        const { roots } = await server.listRoots();
+        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);
+    }
+    catch {
+        clientRootsEnabled = false;
+        syncKnownRoots(primaryRootPath ? [{ rootPath: primaryRootPath }] : []);
+    }
+    await refreshDiscoveredProjectsForKnownRoots();
+}
+async function resolveExplicitProjectSelection(selection) {
+    const explicitProject = selection.project ?? selection.projectDirectory;
+    if (explicitProject) {
+        const resolution = await resolveProjectSelector(explicitProject);
+        if (!resolution.ok) {
+            return resolution;
+        }
+        await initProject(resolution.project.rootPath, watcherDebounceMs, { enableWatcher: true });
+        setActiveProject(resolution.project.rootPath);
+        return resolution;
+    }
+    return {
+        ok: false,
+        response: buildProjectSelectionError('selection_required', 'No project selector was provided.')
+    };
+}
+async function resolveProjectForTool(args) {
+    const requestedProject = parseProjectSelector(args.project);
+    const requestedProjectDirectory = parseProjectSelector(args.project_directory);
+    if (requestedProject || requestedProjectDirectory) {
+        return resolveExplicitProjectSelection({
+            project: requestedProject,
+            projectDirectory: requestedProjectDirectory
+        });
+    }
+    const activeProject = activeProjectKey ? getTrackedRootPathByKey(activeProjectKey) : undefined;
+    if (activeProject) {
+        const project = getOrCreateProject(activeProject);
+        await initProject(project.rootPath, watcherDebounceMs, { enableWatcher: true });
+        touchProject(project.rootPath);
+        return { ok: true, project };
+    }
+    const availableProjects = listProjectDescriptors();
+    if (availableProjects.length === 0) {
+        return {
+            ok: false,
+            response: buildProjectSelectionError('selection_required', 'No active project is available yet. Retry with project or wait for MCP roots to arrive.', {
+                reason: clientRootsEnabled
+                    ? 'workspace_waiting_for_project_selection'
+                    : 'workspace_waiting_for_roots_or_project',
+                nextAction: 'retry_with_project'
+            })
+        };
+    }
+    if (availableProjects.length === 1) {
+        const project = getOrCreateProject(availableProjects[0].rootPath);
+        await initProject(project.rootPath, watcherDebounceMs, { enableWatcher: true });
+        setActiveProject(project.rootPath);
+        return { ok: true, project };
+    }
+    return {
+        ok: false,
+        response: buildProjectSelectionError('selection_required', 'Multiple projects are available and no active project could be inferred. Retry with project.', {
+            reason: 'multiple_projects_configured_no_active_context',
+            nextAction: 'retry_with_project'
+        })
+    };
+}
+async function resolveProjectForResource() {
+    const activeProject = activeProjectKey ? getTrackedRootPathByKey(activeProjectKey) : undefined;
+    if (activeProject) {
+        const project = getOrCreateProject(activeProject);
+        await initProject(project.rootPath, watcherDebounceMs, { enableWatcher: true });
+        touchProject(project.rootPath);
+        return project;
+    }
+    const availableProjects = listProjectDescriptors();
+    if (availableProjects.length !== 1) {
+        return undefined;
+    }
+    const project = getOrCreateProject(availableProjects[0].rootPath);
+    await initProject(project.rootPath, watcherDebounceMs, { enableWatcher: true });
+    setActiveProject(project.rootPath);
+    return project;
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    const normalizedArgs = args && typeof args === 'object' && !Array.isArray(args)
+        ? args
+        : {};
     try {
+        if (!toolNames.has(name)) {
+            return await dispatchTool(name, normalizedArgs, createWorkspaceToolContext());
+        }
+        const projectResolution = await resolveProjectForTool(normalizedArgs);
+        if (!projectResolution.ok) {
+            return projectResolution.response;
+        }
+        const project = projectResolution.project;
         // Gate INDEX_CONSUMING tools on a valid, healthy index
         let indexSignal;
         if (INDEX_CONSUMING_TOOL_NAMES.includes(name)) {
-            if (indexState.status === 'indexing') {
+            if (project.indexState.status === 'indexing') {
                 return {
                     content: [
                         {
@@ -474,49 +1056,59 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ]
                 };
             }
-            if (indexState.status === 'error') {
+            if (project.indexState.status === 'error') {
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
                                 status: 'error',
-                                message: `Indexer error: ${indexState.error}`
+                                message: `Indexer error: ${project.indexState.error}`
                             })
                         }
                     ]
                 };
             }
-            indexSignal = await ensureValidIndexOrAutoHeal();
-            if (indexSignal.action === 'rebuild-failed') {
+            indexSignal = await ensureValidIndexOrAutoHeal(project);
+            if (indexSignal.action === 'rebuild-started') {
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
-                                error: 'Index is corrupt and could not be rebuilt automatically.',
+                                status: 'indexing',
+                                message: 'Index rebuild in progress — please retry shortly',
                                 index: indexSignal
                             })
                         }
-                    ],
-                    isError: true
+                    ]
                 };
             }
         }
-        const ctx = {
-            indexState,
-            paths: PATHS,
-            rootPath: ROOT_PATH,
-            performIndexing
-        };
-        const result = await dispatchTool(name, args ?? {}, ctx);
-        // Inject IndexSignal into response so callers can inspect index health
+        const result = await dispatchTool(name, normalizedArgs, createToolContext(project));
+        // Inject routing/index metadata into JSON responses so agents can reuse the resolved project safely.
         if (indexSignal !== undefined && result.content?.[0]) {
             try {
                 const parsed = JSON.parse(result.content[0].text);
                 result.content[0] = {
                     type: 'text',
-                    text: JSON.stringify({ ...parsed, index: indexSignal })
+                    text: JSON.stringify({
+                        ...parsed,
+                        index: indexSignal,
+                        project: buildProjectDescriptor(project.rootPath)
+                    })
+                };
+            }
+            catch {
+                /* response wasn't JSON, skip injection */
+            }
+        }
+        else if (result.content?.[0]) {
+            try {
+                const parsed = JSON.parse(result.content[0].text);
+                result.content[0] = {
+                    type: 'text',
+                    text: JSON.stringify({ ...parsed, project: buildProjectDescriptor(project.rootPath) })
                 };
             }
             catch {
@@ -537,101 +1129,201 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
 });
-async function main() {
-    // Validate root path exists and is a directory
-    try {
-        const stats = await fs.stat(ROOT_PATH);
-        if (!stats.isDirectory()) {
-            console.error(`ERROR: Root path is not a directory: ${ROOT_PATH}`);
-            console.error(`Please specify a valid project directory.`);
-            process.exit(1);
-        }
+async function ensureProjectInitialized(project) {
+    if (project.initPromise) {
+        await project.initPromise;
+        return;
     }
-    catch (_error) {
-        console.error(`ERROR: Root path does not exist: ${ROOT_PATH}`);
-        console.error(`Please specify a valid project directory.`);
-        process.exit(1);
+    if (project.indexState.status !== 'idle') {
+        return;
     }
-    // Migrate legacy structure before server starts
-    try {
-        const migrated = await migrateToNewStructure();
-        if (migrated && process.env.CODEBASE_CONTEXT_DEBUG) {
-            console.error('[DEBUG] Migrated to .codebase-context/ structure');
+    project.initPromise = (async () => {
+        // Migrate legacy structure
+        try {
+            const legacyPaths = makeLegacyPaths(project.rootPath);
+            const migrated = await migrateToNewStructure(project.paths, legacyPaths);
+            if (migrated && process.env.CODEBASE_CONTEXT_DEBUG) {
+                console.error(`[DEBUG] Migrated to .codebase-context/ structure: ${project.rootPath}`);
+            }
         }
+        catch {
+            // Non-fatal
+        }
+        // Check if indexing is needed
+        const needsIndex = await shouldReindex(project.paths);
+        if (needsIndex) {
+            if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                console.error(`[DEBUG] Starting indexing: ${project.rootPath}`);
+            }
+            void performIndexing(project);
+        }
+        else {
+            if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                console.error(`[DEBUG] Index found. Ready: ${project.rootPath}`);
+            }
+            project.indexState.status = 'ready';
+            project.indexState.lastIndexed = new Date();
+        }
+    })().finally(() => {
+        project.initPromise = undefined;
+    });
+    await project.initPromise;
+}
+function ensureProjectWatcher(project, debounceMs) {
+    if (project.stopWatcher) {
+        touchProject(project.rootPath);
+        return;
     }
-    catch (error) {
-        // Non-fatal: continue with current paths
-        if (process.env.CODEBASE_CONTEXT_DEBUG) {
-            console.error('[DEBUG] Migration failed:', error);
+    project.stopWatcher = startFileWatcher({
+        rootPath: project.rootPath,
+        debounceMs,
+        onChanged: () => {
+            const shouldRunNow = project.autoRefresh.onFileChange(project.indexState.status === 'indexing');
+            if (!shouldRunNow) {
+                if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                    console.error(`[file-watcher] Index in progress — queueing auto-refresh: ${project.rootPath}`);
+                }
+                return;
+            }
+            if (process.env.CODEBASE_CONTEXT_DEBUG) {
+                console.error(`[file-watcher] Changes detected — incremental reindex starting: ${project.rootPath}`);
+            }
+            void performIndexing(project, true);
+        }
+    });
+    touchProject(project.rootPath);
+    const watchedProjects = getAllProjects().filter((entry) => entry.stopWatcher);
+    if (watchedProjects.length <= MAX_WATCHED_PROJECTS) {
+        return;
+    }
+    const evictionCandidates = watchedProjects
+        .filter((entry) => normalizeRootKey(entry.rootPath) !== activeProjectKey)
+        .sort((a, b) => {
+        const accessA = projectAccessOrder.get(normalizeRootKey(a.rootPath)) ?? 0;
+        const accessB = projectAccessOrder.get(normalizeRootKey(b.rootPath)) ?? 0;
+        return accessA - accessB;
+    });
+    const projectToEvict = evictionCandidates[0];
+    if (projectToEvict?.stopWatcher) {
+        projectToEvict.stopWatcher();
+        delete projectToEvict.stopWatcher;
+    }
+}
+async function initProject(rootPath, debounceMs, options) {
+    rememberProjectPath(rootPath);
+    const project = getOrCreateProject(rootPath);
+    await ensureProjectInitialized(project);
+    touchProject(project.rootPath);
+    if (options.enableWatcher) {
+        ensureProjectWatcher(project, debounceMs);
+    }
+}
+async function main() {
+    if (primaryRootPath) {
+        // Validate bootstrap root path exists and is a directory when explicitly configured.
+        try {
+            const stats = await fs.stat(primaryRootPath);
+            if (!stats.isDirectory()) {
+                console.error(`ERROR: Root path is not a directory: ${primaryRootPath}`);
+                console.error(`Please specify a valid project directory.`);
+                process.exit(1);
+            }
+        }
+        catch (_error) {
+            console.error(`ERROR: Root path does not exist: ${primaryRootPath}`);
+            console.error(`Please specify a valid project directory.`);
+            process.exit(1);
         }
     }
     // Server startup banner (guarded to avoid stderr during MCP STDIO handshake)
     if (process.env.CODEBASE_CONTEXT_DEBUG) {
         console.error('[DEBUG] Codebase Context MCP Server');
-        console.error(`[DEBUG] Root: ${ROOT_PATH}`);
+        console.error(primaryRootPath
+            ? `[DEBUG] Bootstrap root: ${primaryRootPath}`
+            : '[DEBUG] Bootstrap root: <workspace-awaiting>');
         console.error(`[DEBUG] Analyzers: ${analyzerRegistry
             .getAll()
             .map((a) => a.name)
             .join(', ')}`);
     }
     // Check for package.json to confirm it's a project root (guarded to avoid stderr during handshake)
-    if (process.env.CODEBASE_CONTEXT_DEBUG) {
+    if (process.env.CODEBASE_CONTEXT_DEBUG && primaryRootPath) {
         try {
-            await fs.access(path.join(ROOT_PATH, 'package.json'));
-            console.error(`[DEBUG] Project detected: ${path.basename(ROOT_PATH)}`);
+            await fs.access(path.join(primaryRootPath, 'package.json'));
+            console.error(`[DEBUG] Project detected: ${path.basename(primaryRootPath)}`);
         }
         catch {
             console.error(`[DEBUG] WARNING: No package.json found. This may not be a project root.`);
         }
     }
-    const needsIndex = await shouldReindex();
-    if (needsIndex) {
-        if (process.env.CODEBASE_CONTEXT_DEBUG)
-            console.error('[DEBUG] Starting indexing...');
-        performIndexing();
-    }
-    else {
-        if (process.env.CODEBASE_CONTEXT_DEBUG)
-            console.error('[DEBUG] Index found. Ready.');
-        indexState.status = 'ready';
-        indexState.lastIndexed = new Date();
+    // Parent death guard — catches SIGKILL, crashes, terminal close on ALL platforms.
+    // process.kill(pid, 0) throws ESRCH when the process no longer exists.
+    const parentPid = process.ppid;
+    if (parentPid > 1) {
+        const parentGuard = setInterval(() => {
+            try {
+                process.kill(parentPid, 0);
+            }
+            catch (err) {
+                // ESRCH = process gone → exit. EPERM = process alive, different UID → ignore.
+                if (err.code === 'ESRCH') {
+                    process.exit(0);
+                }
+            }
+        }, 5_000);
+        parentGuard.unref();
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    if (process.env.CODEBASE_CONTEXT_DEBUG)
-        console.error('[DEBUG] Server ready');
-    // Auto-refresh: watch for file changes and trigger incremental reindex
-    const debounceEnv = Number.parseInt(process.env.CODEBASE_CONTEXT_DEBOUNCE_MS ?? '', 10);
-    const debounceMs = Number.isFinite(debounceEnv) && debounceEnv >= 0 ? debounceEnv : 2000;
-    const stopWatcher = startFileWatcher({
-        rootPath: ROOT_PATH,
-        debounceMs,
-        onChanged: () => {
-            const shouldRunNow = autoRefresh.onFileChange(indexState.status === 'indexing');
-            if (!shouldRunNow) {
-                if (process.env.CODEBASE_CONTEXT_DEBUG) {
-                    console.error('[file-watcher] Index in progress — queueing auto-refresh');
-                }
-                return;
-            }
-            if (process.env.CODEBASE_CONTEXT_DEBUG) {
-                console.error('[file-watcher] Changes detected — incremental reindex starting');
-            }
-            void performIndexing(true);
+    // Register cleanup before any handler that calls process.exit(), so the
+    // exit listener is always in place when stdin/onclose/signals fire.
+    const stopAllWatchers = () => {
+        for (const project of getAllProjects()) {
+            project.stopWatcher?.();
         }
-    });
-    process.once('exit', stopWatcher);
+    };
+    process.once('exit', stopAllWatchers);
     process.once('SIGINT', () => {
-        stopWatcher();
+        stopAllWatchers();
         process.exit(0);
     });
     process.once('SIGTERM', () => {
-        stopWatcher();
+        stopAllWatchers();
+        process.exit(0);
+    });
+    process.once('SIGHUP', () => {
+        stopAllWatchers();
         process.exit(0);
     });
+    // Detect stdin pipe closure — the primary signal that the MCP client is gone.
+    // StdioServerTransport only listens for 'data'/'error', never 'end'.
+    process.stdin.on('end', () => process.exit(0));
+    process.stdin.on('close', () => process.exit(0));
+    // Handle graceful MCP protocol-level disconnect.
+    // Fires after SDK internal cleanup when transport.close() is called.
+    server.onclose = () => process.exit(0);
+    if (process.env.CODEBASE_CONTEXT_DEBUG)
+        console.error('[DEBUG] Server ready');
+    await refreshKnownRootsFromClient();
+    // 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 });
+        setActiveProject(startupRoots[0]);
+    }
+    // Subscribe to root changes
+    server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+        try {
+            await refreshKnownRootsFromClient();
+        }
+        catch {
+            /* best-effort */
+        }
+    });
 }
 // Export server components for programmatic use
-export { server, performIndexing, resolveRootPath, shouldReindex, TOOLS };
+export { server, refreshKnownRootsFromClient, resolveRootPath, shouldReindex, TOOLS };
+export { performIndexing };
 // Only auto-start when run directly as CLI (not when imported as module)
 // Check if this module is the entry point
 const isDirectRun = process.argv[1]?.replace(/\\/g, '/').endsWith('index.js') ||