feat: add server config file support for pre-registering projects

Reads ~/.codebase-context/config.json on startup to pre-register
project roots and per-project exclude pattern overrides without
requiring a connected MCP client. Config roots are additive —
they survive syncKnownRoots() refreshes from client root changes.

- src/server/config.ts: new module to load/parse config file
- src/project-state.ts: add extraExcludePatterns field
- src/index.ts: wire applyServerConfig() in main() and startHttp(),
  preserve configRoots in syncKnownRoots(), merge extraExcludePatterns
  in performIndexingOnce()
- tests/server-config.test.ts: 11 unit tests covering all edge paths

Author: PatrickSys

src/index.ts

@@ -13,6 +13,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server/factory.js';
 import { startHttpServer } from './server/http.js';
+import { loadServerConfig } from './server/config.js';
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
@@ -46,6 +47,7 @@ import {
   getProjectPathFromContextResourceUri,
   isContextResourceUri
 } from './resources/uri.js';
+import { EXCLUDED_GLOB_PATTERNS } from './constants/codebase-context.js';
 import {
   discoverProjectsWithinRoot,
   findNearestProjectBoundary,
@@ -102,6 +104,8 @@ function resolveRootPath(): string | undefined {
 const primaryRootPath = resolveRootPath();
 const toolNames = new Set(TOOLS.map((tool) => tool.name));
 const knownRoots = new Map<string, { rootPath: string; label?: string }>();
+/** Roots loaded from config file — preserved across syncKnownRoots() refreshes. */
+const configRoots = new Map<string, { rootPath: string }>();
 const discoveredProjectPaths = new Map<string, string>();
 let clientRootsEnabled = false;
 const projectSourcesByKey = new Map<string, ProjectDescriptor['source']>();
@@ -337,6 +341,13 @@ function syncKnownRoots(rootEntries: Array<{ rootPath: string; label?: string }>
     });
   }
 
+  // Always include config-registered roots — config is additive (REPO-03)
+  for (const [rootKey, rootEntry] of configRoots.entries()) {
+    if (!nextRoots.has(rootKey)) {
+      nextRoots.set(rootKey, rootEntry);
+    }
+  }
+
   for (const [rootKey, existingRoot] of knownRoots.entries()) {
     if (!nextRoots.has(rootKey)) {
       removeProject(existingRoot.rootPath);
@@ -1240,6 +1251,9 @@ async function performIndexingOnce(
     let lastLoggedProgress = { phase: '', percentage: -1 };
     const indexer = new CodebaseIndexer({
       rootPath: project.rootPath,
+      ...(project.extraExcludePatterns?.length
+        ? { config: { exclude: [...EXCLUDED_GLOB_PATTERNS, ...project.extraExcludePatterns] } }
+        : {}),
       incrementalOnly,
       onProgress: (progress) => {
         // Only log when phase or percentage actually changes (prevents duplicate logs)
@@ -1587,7 +1601,33 @@ async function initProject(
   }
 }
 
+async function applyServerConfig(
+  serverConfig: Awaited<ReturnType<typeof loadServerConfig>>
+): Promise<void> {
+  for (const proj of serverConfig?.projects ?? []) {
+    try {
+      const stats = await fs.stat(proj.root);
+      if (!stats.isDirectory()) {
+        console.error(`[config] Skipping non-directory project root: ${proj.root}`);
+        continue;
+      }
+      const rootKey = normalizeRootKey(proj.root);
+      configRoots.set(rootKey, { rootPath: proj.root });
+      registerKnownRoot(proj.root);
+      if (proj.excludePatterns?.length) {
+        const project = getOrCreateProject(proj.root);
+        project.extraExcludePatterns = proj.excludePatterns;
+      }
+    } catch {
+      console.error(`[config] Skipping inaccessible project root: ${proj.root}`);
+    }
+  }
+}
+
 async function main() {
+  const serverConfig = await loadServerConfig();
+  await applyServerConfig(serverConfig);
+
   if (primaryRootPath) {
     // Validate bootstrap root path exists and is a directory when explicitly configured.
     try {
@@ -1711,7 +1751,18 @@ export { performIndexing };
  * Each connecting MCP client gets its own Server+Transport pair,
  * sharing the same module-level project state.
  */
-async function startHttp(port: number): Promise<void> {
+async function startHttp(explicitPort?: number): Promise<void> {
+  const serverConfig = await loadServerConfig();
+  await applyServerConfig(serverConfig);
+
+  // Port resolution priority: CLI flag > env var > config file > built-in default (3100)
+  const portFromEnv = process.env.CODEBASE_CONTEXT_PORT
+    ? Number.parseInt(process.env.CODEBASE_CONTEXT_PORT, 10)
+    : undefined;
+  const resolvedEnvPort = portFromEnv && Number.isFinite(portFromEnv) ? portFromEnv : undefined;
+  const port = explicitPort ?? resolvedEnvPort ?? serverConfig?.server?.port ?? 3100;
+  const host = serverConfig?.server?.host ?? '127.0.0.1';
+
   // Validate bootstrap root the same way main() does
   if (primaryRootPath) {
     try {
@@ -1730,6 +1781,7 @@ async function startHttp(port: number): Promise<void> {
     name: 'codebase-context',
     version: PKG_VERSION,
     port,
+    host,
     registerHandlers,
     onSessionReady: (sessionServer) => {
       // Per-session roots change handler
@@ -1803,20 +1855,15 @@ if (isDirectRun) {
     const httpFlag = process.argv.includes('--http') || process.env.CODEBASE_CONTEXT_HTTP === '1';
 
     if (httpFlag) {
+      // Extract only the CLI flag value. Env var, config, and default
+      // are resolved inside startHttp() in priority order: flag > env > config > 3100.
       const portFlagIdx = process.argv.indexOf('--port');
       const portFromFlag =
         portFlagIdx !== -1 ? Number.parseInt(process.argv[portFlagIdx + 1], 10) : undefined;
-      const portFromEnv = process.env.CODEBASE_CONTEXT_PORT
-        ? Number.parseInt(process.env.CODEBASE_CONTEXT_PORT, 10)
-        : undefined;
-      const port =
-        portFromFlag && Number.isFinite(portFromFlag)
-          ? portFromFlag
-          : portFromEnv && Number.isFinite(portFromEnv)
-            ? portFromEnv
-            : 3100;
-
-      startHttp(port).catch((error) => {
+      const explicitPort =
+        portFromFlag && Number.isFinite(portFromFlag) ? portFromFlag : undefined;
+
+      startHttp(explicitPort).catch((error) => {
         console.error('Fatal:', error);
         process.exit(1);
       });

src/project-state.ts

@@ -17,6 +17,8 @@ export interface ProjectState {
   autoRefresh: AutoRefreshController;
   initPromise?: Promise<void>;
   stopWatcher?: () => void;
+  /** Extra glob exclusion patterns from config file — merged with EXCLUDED_GLOB_PATTERNS at index time. */
+  extraExcludePatterns?: string[];
 }
 
 export function makePaths(rootPath: string): ToolPaths {

src/server/config.ts

@@ -0,0 +1,91 @@
+import os from 'node:os';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export interface ProjectConfig {
+  root: string;
+  excludePatterns?: string[];
+}
+
+export interface ServerConfig {
+  projects?: ProjectConfig[];
+  server?: { port?: number; host?: string };
+}
+
+function expandTilde(filePath: string): string {
+  if (filePath === '~' || filePath.startsWith('~/') || filePath.startsWith('~\\')) {
+    return path.join(os.homedir(), filePath.slice(1));
+  }
+  return filePath;
+}
+
+export async function loadServerConfig(): Promise<ServerConfig | null> {
+  const configPath =
+    process.env.CODEBASE_CONTEXT_CONFIG_PATH ??
+    path.join(os.homedir(), '.codebase-context', 'config.json');
+
+  let raw: string;
+  try {
+    raw = await fs.readFile(configPath, 'utf8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    console.error(`[config] Failed to load config: ${(err as Error).message}`);
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`[config] Failed to load config: ${(err as Error).message}`);
+    return null;
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+
+  const config = parsed as Record<string, unknown>;
+  const result: ServerConfig = {};
+
+  // Resolve projects
+  if (Array.isArray(config.projects)) {
+    result.projects = (config.projects as unknown[])
+      .filter((p): p is Record<string, unknown> => typeof p === 'object' && p !== null)
+      .map((p) => {
+        const rawRoot = typeof p.root === 'string' ? p.root : '';
+        const resolvedRoot = path.resolve(expandTilde(rawRoot));
+        const proj: ProjectConfig = { root: resolvedRoot };
+        if (Array.isArray(p.excludePatterns)) {
+          proj.excludePatterns = p.excludePatterns.filter(
+            (pattern): pattern is string => typeof pattern === 'string'
+          );
+        }
+        return proj;
+      });
+  }
+
+  // Resolve server options
+  if (typeof config.server === 'object' && config.server !== null) {
+    const srv = config.server as Record<string, unknown>;
+    result.server = {};
+
+    if (typeof srv.host === 'string') {
+      result.server.host = srv.host;
+    }
+
+    if (srv.port !== undefined) {
+      const portValue = srv.port;
+      const portNum = typeof portValue === 'number' ? portValue : Number(portValue);
+      if (Number.isInteger(portNum) && portNum > 0) {
+        result.server.port = portNum;
+      } else {
+        console.error(`[config] Ignoring invalid server.port: ${portValue}`);
+      }
+    }
+  }
+
+  return result;
+}

tests/server-config.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadServerConfig } from '../src/server/config.js';
+
+// Helper: write a temp config file and set CODEBASE_CONTEXT_CONFIG_PATH
+async function withTempConfig(content: string, fn: (filePath: string) => Promise<void>) {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ccc-config-test-'));
+  const filePath = path.join(tmpDir, 'config.json');
+  await fs.writeFile(filePath, content, 'utf8');
+  try {
+    await fn(filePath);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+describe('loadServerConfig', () => {
+  afterEach(() => {
+    delete process.env.CODEBASE_CONTEXT_CONFIG_PATH;
+    vi.restoreAllMocks();
+  });
+
+  it('returns null silently when config file does not exist (ENOENT)', async () => {
+    const errorSpy = vi.spyOn(console, 'error');
+    process.env.CODEBASE_CONTEXT_CONFIG_PATH = '/tmp/nonexistent-ccc-config-99999.json';
+    const result = await loadServerConfig();
+    expect(result).toBeNull();
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it('returns null and logs to stderr on malformed JSON', async () => {
+    const errorSpy = vi.spyOn(console, 'error');
+    await withTempConfig('{ invalid json }', async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).toBeNull();
+      expect(errorSpy).toHaveBeenCalledOnce();
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[config\] Failed to load config:/);
+    });
+  });
+
+  it('returns null when top-level value is an array', async () => {
+    await withTempConfig('[]', async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).toBeNull();
+    });
+  });
+
+  it('returns null when top-level value is a string', async () => {
+    await withTempConfig('"just a string"', async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).toBeNull();
+    });
+  });
+
+  it('resolves ~/my-repo to an absolute path using os.homedir()', async () => {
+    const config = JSON.stringify({
+      projects: [{ root: '~/my-repo' }]
+    });
+    await withTempConfig(config, async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).not.toBeNull();
+      expect(result!.projects).toHaveLength(1);
+      const resolved = result!.projects![0].root;
+      expect(path.isAbsolute(resolved)).toBe(true);
+      expect(resolved).toBe(path.join(os.homedir(), 'my-repo'));
+    });
+  });
+
+  it('resolves a relative path via path.resolve()', async () => {
+    const config = JSON.stringify({
+      projects: [{ root: 'relative/path' }]
+    });
+    await withTempConfig(config, async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).not.toBeNull();
+      const resolved = result!.projects![0].root;
+      expect(path.isAbsolute(resolved)).toBe(true);
+      expect(resolved).toBe(path.resolve('relative/path'));
+    });
+  });
+
+  it('returns valid config for well-formed input with projects and server.port', async () => {
+    // Use absolute paths that are valid on all platforms
+    const projA = path.join(os.tmpdir(), 'ccc-test-proj-a');
+    const projB = path.join(os.tmpdir(), 'ccc-test-proj-b');
+    const config = JSON.stringify({
+      projects: [
+        { root: projA, excludePatterns: ['**/dist/**'] },
+        { root: projB }
+      ],
+      server: { port: 5199, host: '0.0.0.0' }
+    });
+    await withTempConfig(config, async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).not.toBeNull();
+      expect(result!.projects).toHaveLength(2);
+      expect(result!.projects![0].root).toBe(path.resolve(projA));
+      expect(result!.projects![0].excludePatterns).toEqual(['**/dist/**']);
+      expect(result!.projects![1].root).toBe(path.resolve(projB));
+      expect(result!.server?.port).toBe(5199);
+      expect(result!.server?.host).toBe('0.0.0.0');
+    });
+  });
+
+  it('drops server.port with a warning when value is 0', async () => {
+    const errorSpy = vi.spyOn(console, 'error');
+    const config = JSON.stringify({ server: { port: 0 } });
+    await withTempConfig(config, async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).not.toBeNull();
+      expect(result!.server?.port).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledOnce();
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[config\] Ignoring invalid server\.port: 0/);
+    });
+  });
+
+  it('drops server.port with a warning when value is negative', async () => {
+    const errorSpy = vi.spyOn(console, 'error');
+    const config = JSON.stringify({ server: { port: -1 } });
+    await withTempConfig(config, async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result!.server?.port).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledOnce();
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[config\] Ignoring invalid server\.port: -1/);
+    });
+  });
+
+  it('drops server.port with a warning when value is a non-numeric string', async () => {
+    const errorSpy = vi.spyOn(console, 'error');
+    const config = JSON.stringify({ server: { port: 'abc' } });
+    await withTempConfig(config, async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result!.server?.port).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledOnce();
+      expect(errorSpy.mock.calls[0][0]).toMatch(/\[config\] Ignoring invalid server\.port: abc/);
+    });
+  });
+
+  it('respects CODEBASE_CONTEXT_CONFIG_PATH env var', async () => {
+    const config = JSON.stringify({ server: { port: 4242 } });
+    await withTempConfig(config, async (filePath) => {
+      process.env.CODEBASE_CONTEXT_CONFIG_PATH = filePath;
+      const result = await loadServerConfig();
+      expect(result).not.toBeNull();
+      expect(result!.server?.port).toBe(4242);
+    });
+  });
+});