codesearch-mcp 0.0.13-alpha → 0.0.15-alpha

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.0.15-alpha] - 2026-05-02
+
+### Changed
+
+- **MCP server instructions restructured** — `Step 0` (query classification table) moved before the `Tools` list so it arrives before the truncation threshold and is always visible to the model
+- **Lookup workflow fixed** — corrected order to `find_symbol` first (faster, exact match), `search_codebase` as fallback
+- **Path distinction clarified** — `read_file_range` (relative path) and `read_file` (absolute path) now labelled directly in the Tools list, reducing wrong-path errors
+- **Threshold contradiction resolved** — removed conflicting `0.35` example from Lookup/Conceptual workflow; canonical threshold guidance kept only in Relevance scores section

package/README.md

@@ -34,7 +34,7 @@ rag-setup
 Walks you through:
 - **Local Docker** — copies `docker-compose.yml`, starts PostgreSQL + Ollama, pulls `bge-m3` automatically
 - **Remote DB** — enter connection details for Supabase, Railway, or self-hosted; connection is verified before saving
-- **Logging** — choose log level and file path (defaults: `error` level, `~/.config/codesearch-mcp/rag.log`)
+- **Logging** — choose log level and directory (defaults: `error` level, `~/.config/codesearch-mcp/logs/`)
 
 Config is saved to `~/.config/codesearch-mcp/.env`.
 
@@ -102,18 +102,18 @@ src/generated/
 
 ## Logging
 
-Logs are written to `~/.config/codesearch-mcp/rag.log` by default. Only errors are logged unless configured otherwise.
+Logs are written to `~/.config/codesearch-mcp/logs/` by default (separate subdirectories for indexer and MCP). Only errors are logged unless configured otherwise.
 
 ```bash
 # Read logs
-tail -f ~/.config/codesearch-mcp/rag.log
-npx pino-pretty < ~/.config/codesearch-mcp/rag.log
+tail -f ~/.config/codesearch-mcp/logs/indexer/current.log
+npx pino-pretty < ~/.config/codesearch-mcp/logs/indexer/current.log
 
 # Detailed indexing diagnostics (timing per file: deps / embed / db)
 LOG_LEVEL=debug rag-index /path/to/workspace
 
 # Disable file logging
-LOG_FILE=false rag-index /path/to/workspace
+LOG_DIR=false rag-index /path/to/workspace
 ```
 
 ## Environment variables
@@ -134,7 +134,7 @@ All set by `rag-setup`. Override any of them in `~/.config/codesearch-mcp/.env`.
 | `AUTO_TRANSLATE` | `false` | Translate non-English queries to English before embedding |
 | `TRANSLATE_MODEL` | `llama3.2` | Ollama model for translation (requires `ollama pull llama3.2`) |
 | `LOG_LEVEL` | `error` | Log level written to file: `error` \| `warn` \| `info` \| `debug` |
-| `LOG_FILE` | `~/.config/codesearch-mcp/rag.log` | Log file path, or `false` to disable |
+| `LOG_DIR` | `~/.config/codesearch-mcp/logs` | Base log directory, or `false` to disable |
 
 ## License
 

package/dist/app.js

@@ -53,7 +53,8 @@ async function main() {
         (0, help_1.printHelp)(argv1 !== 'app.js' ? argv1 : mode);
         process.exit(0);
     }
-    const container = (0, container_1.createContainer)();
+    const loggerName = mode === 'index' || mode === 'backfill' ? 'indexer' : mode === 'mcp' ? 'mcp' : mode === 'setup' ? 'setup' : undefined;
+    const container = (0, container_1.createContainer)(loggerName);
     if (!container.config.workspaceRoot && mode !== 'setup') {
         const hint = argv1 === 'rag-mcp'
             ? 'Set WORKSPACE_ROOT in ~/.config/codesearch-mcp/.env or run `rag-setup`.'
@@ -64,7 +65,7 @@ async function main() {
     const commands = {
         index: new IndexCommand_1.IndexCommand(container, argv1),
         mcp: new McpCommand_1.McpCommand(container),
-        setup: new SetupCommand_1.SetupCommand(),
+        setup: new SetupCommand_1.SetupCommand(container),
         backfill: new BackfillCommand_1.BackfillCommand(container),
     };
     const cmd = commands[mode];

package/dist/src/commands/McpCommand.js

@@ -7,9 +7,22 @@ class McpCommand {
         this.container = container;
     }
     async execute() {
-        const { db, mcp } = this.container;
-        await db.initDb();
-        await mcp.start();
+        const { db, mcp, logger } = this.container;
+        let startupError;
+        try {
+            await db.initDb();
+        }
+        catch (err) {
+            startupError = err;
+            logger.error('McpCommand: database connection failed', { reason: err.message });
+        }
+        try {
+            await mcp.start(startupError);
+        }
+        catch (err) {
+            logger.error('McpCommand: MCP server failed to start', { reason: err.message });
+            return;
+        }
         // server.connect() resolves immediately after setup; keep the process alive
         // until the MCP client disconnects (stdin closes)
         await new Promise(resolve => {

package/dist/src/commands/SetupCommand.d.ts

@@ -1,4 +1,7 @@
+import type { Container } from '../container';
 import type { ICommand } from './ICommand';
 export declare class SetupCommand implements ICommand {
+    private container;
+    constructor(container: Container);
     execute(): Promise<void>;
 }

package/dist/src/commands/SetupCommand.js

@@ -3,8 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SetupCommand = void 0;
 const setup_1 = require("../setup");
 class SetupCommand {
+    container;
+    constructor(container) {
+        this.container = container;
+    }
     async execute() {
-        await (0, setup_1.runSetup)();
+        await (0, setup_1.runSetup)(this.container.logger);
     }
 }
 exports.SetupCommand = SetupCommand;

package/dist/src/container.d.ts

@@ -12,4 +12,4 @@ export interface Container {
     mcp: McpServer;
     logger: LoggerService;
 }
-export declare function createContainer(): Container;
+export declare function createContainer(loggerName?: string): Container;

package/dist/src/container.js

@@ -9,8 +9,8 @@ const IndexerService_1 = require("./services/IndexerService");
 const SearcherService_1 = require("./services/SearcherService");
 const McpServer_1 = require("./services/McpServer");
 const LoggerService_1 = require("./services/LoggerService");
-function createContainer() {
-    const logger = LoggerService_1.LoggerService.fromEnv();
+function createContainer(loggerName) {
+    const logger = LoggerService_1.LoggerService.fromEnv(loggerName);
     const db = new DatabaseService_1.DatabaseService(config_1.config);
     const embedder = new OllamaEmbedder_1.OllamaEmbedder(config_1.config);
     const ast = new AstParserService_1.AstParserService(logger);

package/dist/src/project-selector.js

@@ -37,37 +37,49 @@ exports.selectProjects = selectProjects;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const prompts_1 = require("@inquirer/prompts");
-function loadLines(filePath) {
-    if (!fs.existsSync(filePath))
+async function loadLines(filePath) {
+    try {
+        const content = await fs.promises.readFile(filePath, 'utf-8');
+        return new Set(content.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#')));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
         return new Set();
-    return new Set(fs.readFileSync(filePath, 'utf-8')
-        .split('\n')
-        .map(l => l.trim())
-        .filter(l => l && !l.startsWith('#')));
+    }
 }
 // Write the set if non-empty, otherwise delete the file so state is deterministic.
 // Previously .ragskip could be left stale (last entry removed but file not rewritten);
 // treating both files the same way avoids that drift.
-function saveLines(filePath, names) {
+async function saveLines(filePath, names) {
     if (names.size > 0) {
-        fs.writeFileSync(filePath, [...names].sort().join('\n') + '\n');
+        await fs.promises.writeFile(filePath, [...names].sort().join('\n') + '\n');
     }
-    else if (fs.existsSync(filePath)) {
-        fs.unlinkSync(filePath);
+    else {
+        try {
+            await fs.promises.unlink(filePath);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
     }
 }
-function loadConfig(workspaceDir) {
-    return {
-        included: loadLines(path.join(workspaceDir, '.ragprojects')),
-        skipped: loadLines(path.join(workspaceDir, '.ragskip')),
-    };
+async function loadConfig(workspaceDir) {
+    const [included, skipped] = await Promise.all([
+        loadLines(path.join(workspaceDir, '.ragprojects')),
+        loadLines(path.join(workspaceDir, '.ragskip')),
+    ]);
+    return { included, skipped };
 }
-function saveConfig(workspaceDir, config) {
-    saveLines(path.join(workspaceDir, '.ragprojects'), config.included);
-    saveLines(path.join(workspaceDir, '.ragskip'), config.skipped);
+async function saveConfig(workspaceDir, config) {
+    await Promise.all([
+        saveLines(path.join(workspaceDir, '.ragprojects'), config.included),
+        saveLines(path.join(workspaceDir, '.ragskip'), config.skipped),
+    ]);
 }
 async function selectProjects(allProjects, workspaceDir, forceSelect) {
-    const config = loadConfig(workspaceDir);
+    const config = await loadConfig(workspaceDir);
     const newProjects = allProjects.filter(p => !config.included.has(p.name) && !config.skipped.has(p.name));
     // Nothing to ask — return previously saved selection silently
     if (newProjects.length === 0 && !forceSelect) {
@@ -121,7 +133,7 @@ async function selectProjects(allProjects, workspaceDir, forceSelect) {
         for (const name of toSkip)
             config.skipped.add(name);
     }
-    saveConfig(workspaceDir, config);
+    await saveConfig(workspaceDir, config);
     const selected = allProjects.filter(p => config.included.has(p.name));
     console.log(`\nSelected: ${selected.map(p => p.name).join(', ') || '(none)'}`);
     return selected;

package/dist/src/services/AstParserService.js

@@ -43,6 +43,7 @@ const FALLBACK_OPTS = {
     skipFileDependencyResolution: false,
     compilerOptions: { allowJs: true, noEmit: true },
 };
+const MORPH_CACHE_MAX = 10;
 class AstParserService {
     logger;
     morphProjects = new Map();
@@ -75,38 +76,49 @@ class AstParserService {
         const { edges } = await this.analyzeFile(filePath, serviceName, projectRoot);
         return edges;
     }
-    // ── private: MorphProject cache ────────────────────────────────────────────
+    // ── private: MorphProject cache (LRU, max MORPH_CACHE_MAX entries) ──────────
     getMorphProject(projectRoot) {
-        if (!this.morphProjects.has(projectRoot)) {
-            const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
-            const hasTsconfig = fs.existsSync(tsconfigPath);
-            this.logger.debug('AstParser: tsconfig lookup', { projectRoot, found: hasTsconfig });
-            let project;
-            try {
-                const opts = hasTsconfig
-                    ? { tsConfigFilePath: tsconfigPath, skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: false }
-                    : FALLBACK_OPTS;
-                project = new ts_morph_1.Project(opts);
-                if (hasTsconfig) {
-                    const co = project.getCompilerOptions();
-                    const pathsMap = co.paths ?? {};
-                    const pathCount = Object.keys(pathsMap).length;
-                    this.logger.debug('AstParser: tsconfig loaded', { pathCount });
-                    if (pathCount > 0) {
-                        this.logger.debug('AstParser: path aliases', { aliases: Object.keys(pathsMap) });
-                    }
+        if (this.morphProjects.has(projectRoot)) {
+            // Move to end = most recently used
+            const cached = this.morphProjects.get(projectRoot);
+            this.morphProjects.delete(projectRoot);
+            this.morphProjects.set(projectRoot, cached);
+            return cached;
+        }
+        if (this.morphProjects.size >= MORPH_CACHE_MAX) {
+            // Evict least recently used (first entry in insertion-order Map)
+            const lruKey = this.morphProjects.keys().next().value;
+            this.morphProjects.delete(lruKey);
+            this.logger.debug('AstParser: evicted LRU project', { lruKey });
+        }
+        const tsconfigPath = path.join(projectRoot, 'tsconfig.json');
+        const hasTsconfig = fs.existsSync(tsconfigPath);
+        this.logger.debug('AstParser: tsconfig lookup', { projectRoot, found: hasTsconfig });
+        let project;
+        try {
+            const opts = hasTsconfig
+                ? { tsConfigFilePath: tsconfigPath, skipAddingFilesFromTsConfig: true, skipFileDependencyResolution: false }
+                : FALLBACK_OPTS;
+            project = new ts_morph_1.Project(opts);
+            if (hasTsconfig) {
+                const co = project.getCompilerOptions();
+                const pathsMap = co.paths ?? {};
+                const pathCount = Object.keys(pathsMap).length;
+                this.logger.debug('AstParser: tsconfig loaded', { pathCount });
+                if (pathCount > 0) {
+                    this.logger.debug('AstParser: path aliases', { aliases: Object.keys(pathsMap) });
                 }
             }
-            catch (err) {
-                this.logger.warn('AstParser: tsconfig load failed, using fallback', {
-                    tsconfigPath,
-                    reason: err.message,
-                });
-                project = new ts_morph_1.Project(FALLBACK_OPTS);
-            }
-            this.morphProjects.set(projectRoot, project);
         }
-        return this.morphProjects.get(projectRoot);
+        catch (err) {
+            this.logger.warn('AstParser: tsconfig load failed, using fallback', {
+                tsconfigPath,
+                reason: err.message,
+            });
+            project = new ts_morph_1.Project(FALLBACK_OPTS);
+        }
+        this.morphProjects.set(projectRoot, project);
+        return project;
     }
     // ── private: edge extraction (imports + re-exports) ────────────────────────
     extractEdges(sourceFile, filePath, serviceName) {

package/dist/src/services/DatabaseService.js

@@ -108,7 +108,8 @@ class DatabaseService {
             await client.connect();
             const { rows } = await client.query(`SELECT 1 FROM pg_database WHERE datname = $1`, [database]);
             if (rows.length === 0) {
-                await client.query(`CREATE DATABASE "${database}"`);
+                const safeName = database.replace(/"/g, '""');
+                await client.query(`CREATE DATABASE "${safeName}"`);
                 await client.end();
                 const extClient = new pg_1.Client({ host, port, user: username, password, database });
                 try {
@@ -126,7 +127,8 @@ class DatabaseService {
         }
         catch (err) {
             await client.end().catch(() => { });
-            throw new Error(`Failed to ensure database "${database}" exists: ${err.message}`);
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to ensure database "${database}" exists: ${msg}`);
         }
     }
 }

package/dist/src/services/LoggerService.d.ts

@@ -4,7 +4,7 @@ export declare class LoggerService {
     private readonly logger;
     constructor(logger: pino.Logger);
     static silent(): LoggerService;
-    static fromEnv(): LoggerService;
+    static fromEnv(name?: string): LoggerService;
     debug(msg: string, data?: Record<string, unknown>): void;
     info(msg: string, data?: Record<string, unknown>): void;
     warn(msg: string, data?: Record<string, unknown>): void;

package/dist/src/services/LoggerService.js

@@ -41,7 +41,7 @@ const pino_1 = __importDefault(require("pino"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
-const DEFAULT_LOG_FILE = path.join(os.homedir(), '.config', 'codesearch-mcp', 'rag.log');
+const DEFAULT_LOG_DIR = path.join(os.homedir(), '.config', 'codesearch-mcp', 'logs');
 class LoggerService {
     logger;
     constructor(logger) {
@@ -50,11 +50,17 @@ class LoggerService {
     static silent() {
         return new LoggerService((0, pino_1.default)({ level: 'silent' }));
     }
-    static fromEnv() {
+    static fromEnv(name) {
         const level = (process.env.LOG_LEVEL ?? 'error');
-        const logFileEnv = process.env.LOG_FILE;
-        const enabled = logFileEnv !== 'false' && logFileEnv !== '0';
-        const filePath = enabled ? (logFileEnv || DEFAULT_LOG_FILE) : null;
+        const logDirEnv = process.env.LOG_DIR;
+        const enabled = logDirEnv !== 'false' && logDirEnv !== '0';
+        let filePath = null;
+        if (enabled) {
+            const logDir = logDirEnv || DEFAULT_LOG_DIR;
+            filePath = name
+                ? path.join(logDir, name, `${name}.log`)
+                : path.join(logDir, 'rag.log');
+        }
         if (filePath)
             fs.mkdirSync(path.dirname(filePath), { recursive: true });
         const transport = filePath

package/dist/src/services/McpServer.d.ts

@@ -6,7 +6,7 @@ export declare class McpServer {
     private config;
     private logger;
     constructor(searcher: SearcherService, config: Config, logger?: LoggerService);
-    start(): Promise<void>;
+    start(startupError?: Error): Promise<void>;
     private formatChunk;
     private formatDependencies;
     private formatDependents;

package/dist/src/services/McpServer.js

@@ -48,48 +48,77 @@ const PKG_VERSION = (() => {
         return '0.0.0';
     }
 })();
-const SERVER_INSTRUCTIONS = `
-You have access to a local semantic code search server. Use these tools to navigate unfamiliar codebases.
+function buildInstructions(t) {
+    return `
+You have access to a local code intelligence server. Use these tools to search codebases by meaning, navigate import graphs, look up symbol definitions, and read source files.
+
+## Step 0 — Classify your query before starting
+
+Pick one workflow based on what you need:
+
+| Type | Signals | Workflow |
+|---|---|---|
+| **Lookup** | "where is X defined", "find Y" | find_symbol (if name known) → search_codebase (if not found) |
+| **Conceptual** | "how does X work", "what is Y" | search_codebase → read_file_range |
+| **Flow audit** | "how does X connect to Y", "audit this flow", "trace the path" | search_codebase → **get_dependencies + get_dependents** → Grep |
+| **Impact** | "what would break if I change X", "what uses Z" | get_dependents → search_codebase for context |
 
 ## Tools
 
 - **list_projects** — call this first to see what projects are indexed and their exact names.
 - **search_codebase** — semantic search across indexed source files. Returns file path, line number, and a code chunk.
-- **read_file_range** — read a specific line range from any indexed file. Use this to expand context around a search result.
+- **read_file_range** — read a specific line range from any indexed file. Expects a **relative path** as returned by search_codebase.
 - **get_dependencies** — show what files a given file imports (direct or transitive). Use to understand what a file depends on.
 - **get_dependents** — show which files import a given file (reverse graph). Use before refactoring to find all callers.
 - **find_symbol** — find where a symbol (function, class, type, interface, variable, method) is defined by exact name. Faster than semantic search when you know the name.
 - **list_files** — browse the directory tree of a project path. Use to understand project structure before reading files.
-- **read_file** — read a complete file by absolute path with line numbers. Truncates at max_lines with a hint to continue.
+- **read_file** — read a complete file by **absolute path** with line numbers. Truncates at max_lines with a hint to continue.
 
 ## Recommended workflow
 
+### Lookup / Conceptual
 1. Use \`list_projects\` to discover available projects before filtering by \`project\`.
-2. Use \`search_codebase\` to find relevant code by meaning.
-3. If a result looks **truncated or incomplete** (e.g. you see only the middle of a function), call \`read_file_range\` with the returned \`file_path\` and \`start_line\` set to the **Line** number shown in the result. Example: if the result shows **Line:** 150, pass \`start_line: 150\`.
-4. For exploratory searches where you expect results to span chunk boundaries, pass \`include_neighbors: true\` to automatically include the chunk before and after each match.
-5. Use \`find_symbol\` when you know the exact name of a function, class, or method and want its definition location immediately — faster than semantic search. Use \`kind: "method"\` to find public class methods like \`canActivate\`, \`execute\`, \`handle\`.
-6. Use \`list_files\` to explore project structure (src/, components/, etc.) before diving into files.
-7. Use \`read_file\` to read a complete file when you have its absolute path from \`search_codebase\` results.
-8. If \`search_codebase\` returns results that seem off-topic, pass a lower \`threshold\` (e.g. \`0.35\`) to filter out weak semantic matches.
+2. Use \`search_codebase\` to find relevant code by meaning. If your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.40–0.45\`) to filter out weak matches.
+3. If a result looks **truncated or incomplete**, call \`read_file_range\` with the returned \`file_path\` and \`start_line\`.
+4. For exploratory searches where results span chunk boundaries, pass \`include_neighbors: true\`.
+5. Use \`find_symbol\` when you know the exact name — faster than semantic search. Use \`kind: "method"\` for class methods — grep matches lines where \`public\`, \`async\`, \`static\`, or \`override\` appears before the name.
+6. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file by absolute path.
 
-## When to use read_file_range vs include_neighbors
+### Flow audit (mandatory steps — do not skip 3 and 4)
+1. Use \`list_projects\` to confirm project names.
+2. Use \`search_codebase\` to find the **central file** (entry point of the flow).
+3. **\`get_dependencies(central_file)\`** — what does this file import? Catches configs, loaders, Redis clients, types.
+4. **\`get_dependents(central_file)\`** — who calls this file? Catches resolvers, routes, socket handlers.
+5. For each peripheral file found in steps 3–4: use \`read_file_range\` or \`find_symbol\` to inspect it.
+6. Only after steps 3–4 draw architectural conclusions — \`search_codebase\` alone misses peripheral files because they are semantically thin (configs, types, loaders contain no domain vocabulary).
 
-- **include_neighbors: true** — good when you already know the context will be fragmented (e.g. searching for a class definition that's likely split across chunks).
-- **read_file_range** — better when you want to read a precise section, or when a result looks cut off and you want to expand just that one file.
+> **Note:** If \`get_dependencies\` / \`get_dependents\` return empty, the file likely uses path aliases (e.g. \`@core/\`, \`@/\`, \`@db/\`). Fall back to \`Grep\` on the symbol name across the project.
 
-## Handling Code Structure
-- **Class/Function limits**: Chunks often end abruptly. Always use \`read_file_range\` to find the closing brace or the beginning of a method if you suspect you're seeing only a fragment.
-- **Cross-file references**: If you see a method call like \`this.validator.validate(data)\`, use \`search_codebase\` to find the definition of that \`validator\` service.
+### Impact analysis
+1. \`get_dependents(target_file)\` — direct callers.
+2. \`get_dependents(target_file, transitive: true)\` — full reverse graph.
+3. \`search_codebase\` for context on unfamiliar dependents.
 
-## Relevance scores
+## When to use read_file_range vs include_neighbors
 
-Lower score = better match (cosine distance). Results above the configured threshold are filtered out automatically. Pass \`threshold\` to \`search_codebase\` to override the default per-query (e.g. \`0.35\` for strict matching, \`0.55\` for broader results).
+- **include_neighbors: true** — good when context is fragmented across chunks (e.g. a class definition split across chunks).
+- **read_file_range** — better for a precise section, or when one result is cut off.
+
+## Handling Code Structure
+- **Class/Function limits**: Chunks often end abruptly. Use \`read_file_range\` to find the closing brace or method start.
+- **Cross-file references**: If you see \`this.validator.validate(data)\`, use \`search_codebase\` to find \`validator\`.
 
 ## Dependency graph
 
 \`get_dependencies\` and \`get_dependents\` require \`file_path\` (as returned by \`search_codebase\`) and \`project\` (from \`list_projects\`). Pass \`transitive: true\` for the full dependency chain. depType values: \`import\` | \`import-default\` | \`import-namespace\` | \`reexport\` | \`reexport-namespace\`. \`fromSymbol\` — the top-level class or function in the importing file that uses this import (null if ambiguous or not tracked).
+
+If \`get_dependents\` returns 0 results, add \`symbol\` (the exported name you care about) — this triggers a grep fallback that finds runtime usages in DI containers, string references, and dynamic lookups that the import graph misses.
+
+## Relevance scores
+
+Lower score = better match (cosine distance). Results above the configured threshold are filtered out automatically. Treat scores above 0.50 as weak hints — verify with \`read_file_range\` or \`Grep\`. Pass \`threshold\` to \`search_codebase\` to override per-query: \`0.40–0.45\` for precise technical queries (known term, exact concept); \`${t}\` default (broad but reliable). Avoid \`0.35\` — too strict for DSL files (GraphQL, Prisma) and infrastructure code.
 `.trim();
+}
 class McpServer {
     searcher;
     config;
@@ -99,8 +128,8 @@ class McpServer {
         this.config = config;
         this.logger = logger;
     }
-    async start() {
-        const server = new index_js_1.Server({ name: 'local-rag', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+    async start(startupError) {
+        const server = new index_js_1.Server({ name: 'local-rag', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: buildInstructions(this.config.search.similarityThreshold) });
         server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
             tools: [
                 {
@@ -113,14 +142,14 @@ class McpServer {
                             limit: { type: 'number', description: `Max results (default ${this.config.search.defaultLimit}, max ${this.config.search.maxLimit})` },
                             project: { type: 'string', description: 'Filter by project name (optional). Use list_projects to see available names.' },
                             include_neighbors: { type: 'boolean', description: 'Also include the chunk before and after each result from the same file (Small-to-Big retrieval). Useful when results look truncated.' },
-                            threshold: { type: 'number', description: `Max cosine distance (0–1). Lower = stricter. Default: ${this.config.search.similarityThreshold}. Use a lower value (e.g. 0.35) to filter out weak matches.` },
+                            threshold: { type: 'number', description: `Max cosine distance (0–1). Lower = stricter. Default: ${this.config.search.similarityThreshold}. Use 0.40–0.45 for precise technical queries, 0.55–0.60 for broad exploration.` },
                         },
                         required: ['query'],
                     },
                 },
                 {
                     name: 'list_projects',
-                    description: 'List all indexed projects with their chunk counts',
+                    description: 'List all indexed projects with their chunk counts and metadata (description, stack, notes, relations from .ragmeta.json).',
                     inputSchema: { type: 'object', properties: {} },
                 },
                 {
@@ -193,11 +222,11 @@ class McpServer {
                 },
                 {
                     name: 'read_file',
-                    description: 'Read a file from the workspace by absolute path (as returned by search_codebase). Returns contents with line numbers. Truncates at max_lines with a hint to continue with read_file_range.',
+                    description: 'Read a file by absolute path. Returns contents with line numbers. Truncates at max_lines with a hint to continue with read_file_range.',
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            file_path: { type: 'string', description: 'Absolute path to the file (as returned in filePath by search_codebase)' },
+                            file_path: { type: 'string', description: 'Absolute path to the file. Note: search_codebase returns relative paths — construct the absolute path from your workspace root.' },
                             max_lines: { type: 'number', description: 'Maximum lines to return (default 300, max 1000)' },
                         },
                         required: ['file_path'],
@@ -206,6 +235,14 @@ class McpServer {
             ],
         }));
         server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+            if (startupError) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `MCP server is unavailable: ${startupError.message}\n\nCheck the log file and fix the issue, then restart the MCP server.`,
+                        }],
+                };
+            }
             try {
                 if (req.params.name === 'list_projects') {
                     const rows = await this.searcher.listProjects();

package/dist/src/setup.d.ts

@@ -1 +1,2 @@
-export declare function runSetup(): Promise<void>;
+import type { LoggerService } from './services/LoggerService';
+export declare function runSetup(logger?: LoggerService): Promise<void>;

package/dist/src/setup.js

@@ -41,6 +41,7 @@ const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const constants_1 = require("./constants");
 const CONFIG_DIR = path.join(os.homedir(), '.config', 'codesearch-mcp');
+const DEFAULT_LOG_DIR = path.join(CONFIG_DIR, 'logs');
 const CONFIG_FILE = path.join(CONFIG_DIR, '.env');
 const DOCKER_COMPOSE_SRC = path.join(__dirname, '..', '..', 'docker', 'docker-compose.yml');
 const DOCKER_COMPOSE_DST = path.join(CONFIG_DIR, 'docker-compose.yml');
@@ -64,7 +65,7 @@ function writeEnv(vars) {
     fs.writeFileSync(CONFIG_FILE, content, { mode: 0o600 });
     console.log(`\nConfig saved to ${CONFIG_FILE}`);
 }
-async function waitForDb(host, port, user, pass, db, maxWaitSec = 60) {
+async function waitForDb(host, port, user, pass, db, maxWaitSec = 60, logger, steps) {
     const { Client } = await Promise.resolve().then(() => __importStar(require('pg')));
     const deadline = Date.now() + maxWaitSec * 1000;
     process.stdout.write('Waiting for PostgreSQL to be ready');
@@ -81,10 +82,12 @@ async function waitForDb(host, port, user, pass, db, maxWaitSec = 60) {
             await new Promise(r => setTimeout(r, 2000));
         }
     }
-    console.error('\nPostgreSQL did not become ready in time.');
+    const reason = 'PostgreSQL did not become ready in time.';
+    console.error(`\n${reason}`);
+    logger?.error('waitForDb: timeout', { reason, steps });
     process.exit(1);
 }
-async function waitForOllama(host, maxWaitSec = 60) {
+async function waitForOllama(host, maxWaitSec = 60, logger, steps) {
     const deadline = Date.now() + maxWaitSec * 1000;
     process.stdout.write('Waiting for Ollama to be ready');
     while (Date.now() < deadline) {
@@ -106,10 +109,12 @@ async function waitForOllama(host, maxWaitSec = 60) {
             await new Promise(r => setTimeout(r, 2000));
         }
     }
-    console.error('\nOllama did not become ready in time.');
+    const reason = 'Ollama did not become ready in time.';
+    console.error(`\n${reason}`);
+    logger?.error('waitForOllama: timeout', { reason, steps });
     process.exit(1);
 }
-async function checkRemoteDb(host, port, user, pass, db) {
+async function checkRemoteDb(host, port, user, pass, db, logger, steps) {
     try {
         const { Client } = await Promise.resolve().then(() => __importStar(require('pg')));
         const client = new Client({ host, port: parseInt(port), user, password: pass, database: db, connectionTimeoutMillis: 5000 });
@@ -118,50 +123,62 @@ async function checkRemoteDb(host, port, user, pass, db) {
         return true;
     }
     catch (err) {
-        console.error(`  Connection failed: ${err.message}`);
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`  Connection failed: ${msg}`);
+        logger?.error('checkRemoteDb: connection failed', { reason: msg, steps });
         return false;
     }
 }
-async function setupLocalDocker(ollamaHost) {
-    console.log('\nCopying docker-compose.yml to', DOCKER_COMPOSE_DST);
+async function setupLocalDocker(ollamaHost, dbPort, dbUser, dbPass, logger, steps) {
+    console.log('\nWriting docker-compose.yml to', DOCKER_COMPOSE_DST);
+    const yamlQuote = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    let composeContent = fs.readFileSync(DOCKER_COMPOSE_SRC, 'utf-8');
+    composeContent = composeContent
+        .replace('POSTGRES_USER: dev', `POSTGRES_USER: ${yamlQuote(dbUser)}`)
+        .replace('POSTGRES_PASSWORD: dev', `POSTGRES_PASSWORD: ${yamlQuote(dbPass)}`)
+        .replace('"5433:5432"', `"${dbPort}:5432"`);
     fs.mkdirSync(CONFIG_DIR, { recursive: true });
-    fs.copyFileSync(DOCKER_COMPOSE_SRC, DOCKER_COMPOSE_DST);
+    fs.writeFileSync(DOCKER_COMPOSE_DST, composeContent, 'utf-8');
     console.log('\nStarting Docker containers...');
     const upResult = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'up', '-d'], { stdio: 'inherit' });
     if (upResult.status !== 0) {
-        console.error('Failed to start Docker containers. Make sure Docker is running.');
+        const reason = 'Failed to start Docker containers. Make sure Docker is running.';
+        console.error(reason);
+        logger?.error('setupLocalDocker: docker startup failed', { reason, steps });
         process.exit(1);
     }
-    await waitForDb('localhost', 5433, 'dev', 'dev', 'postgres');
-    await waitForOllama(ollamaHost);
+    await waitForDb('localhost', parseInt(dbPort), dbUser, dbPass, 'postgres', 60, logger, steps);
+    await waitForOllama(ollamaHost, 60, logger, steps);
     // Resolve the ollama container ID via compose — compose project name (and thus the
     // default container name) depends on the parent directory, so hardcoding it breaks when
     // users install via npm -g or move the compose file around.
     const ollamaId = (0, child_process_1.spawnSync)('docker', ['compose', '-f', DOCKER_COMPOSE_DST, 'ps', '-q', 'ollama'], { encoding: 'utf-8' })
         .stdout?.trim();
     if (!ollamaId) {
-        console.error('Could not resolve ollama container ID from compose. Pull the model manually:');
+        const reason = 'Could not resolve ollama container ID from compose. Pull the model manually:';
+        console.error(reason);
         console.error(`  docker exec <ollama-container> ollama pull ${constants_1.DEFAULT_EMBED_MODEL}`);
+        logger?.error('setupLocalDocker: ollama container not found', { reason, steps });
         process.exit(1);
     }
     console.log(`Pulling ${constants_1.DEFAULT_EMBED_MODEL} model (this may take a while)...`);
     (0, child_process_1.spawnSync)('docker', ['exec', ollamaId, 'ollama', 'pull', constants_1.DEFAULT_EMBED_MODEL], { stdio: 'inherit' });
-    return {
-        DB_HOST: 'localhost',
-        DB_PORT: '5433',
-        DB_USER: 'dev',
-        DB_PASS: 'dev',
-    };
+    return { DB_HOST: 'localhost', DB_PORT: dbPort, DB_USER: dbUser, DB_PASS: dbPass };
 }
-async function setupRemoteDb(rl) {
+async function setupRemoteDb(rl, logger, steps, logStep) {
+    const lp = async (label, def) => {
+        const answer = await prompt(rl, label, def);
+        logStep?.(label, answer);
+        return answer;
+    };
     let vars = {};
     while (true) {
-        vars.DB_HOST = await prompt(rl, 'DB host', 'localhost');
-        vars.DB_PORT = await prompt(rl, 'DB port', '5432');
-        vars.DB_USER = await prompt(rl, 'DB user', 'postgres');
-        vars.DB_PASS = await prompt(rl, 'DB password', '');
+        vars.DB_HOST = await lp('DB host', 'localhost');
+        vars.DB_PORT = await lp('DB port', '5432');
+        vars.DB_USER = await lp('DB user', 'postgres');
+        vars.DB_PASS = await lp('DB password', '');
         console.log('\nTesting connection...');
-        const ok = await checkRemoteDb(vars.DB_HOST, vars.DB_PORT, vars.DB_USER, vars.DB_PASS, 'postgres');
+        const ok = await checkRemoteDb(vars.DB_HOST, vars.DB_PORT, vars.DB_USER, vars.DB_PASS, 'postgres', logger, steps);
         if (ok) {
             console.log('Connection successful.');
             break;
@@ -172,18 +189,47 @@ async function setupRemoteDb(rl) {
     }
     return vars;
 }
-async function runSetup() {
+async function runSetup(logger) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    console.log('=== codesearch-mcp setup ===\n');
-    const dbChoice = await ask(rl, 'Infrastructure:\n  1. Local Docker (auto-start PostgreSQL + Ollama)\n  2. Remote (Supabase, Railway, self-hosted DB + local Ollama)\n\nEnter choice (1): ');
+    const steps = [];
+    function logStep(q, raw) {
+        const a = /password/i.test(q) ? '***' : raw.trim();
+        logger?.debug('setup: prompt', { q, a });
+        steps.push({ q, a });
+    }
+    const loggedAsk = async (question) => {
+        const answer = await ask(rl, question);
+        const key = question.split('\n').find(l => l.trim())?.trim() ?? question.trim();
+        logStep(key, answer);
+        return answer;
+    };
+    const loggedPrompt = async (label, def) => {
+        const answer = await prompt(rl, label, def);
+        logStep(label, answer || def);
+        return answer;
+    };
+    console.log('=== codesearch-mcp setup ===');
+    console.log('Press Enter to keep the default value shown in parentheses.\n');
+    const dbChoice = await loggedAsk('Infrastructure:\n  1. Local Docker (auto-start PostgreSQL + Ollama)\n  2. Remote (Supabase, Railway, self-hosted DB + local Ollama)\n\nEnter choice (1): ');
     const useDocker = (dbChoice.trim() || '1') === '1';
-    const defaultWorkspace = path.join(os.homedir(), 'Projects');
-    const workspaceInput = await ask(rl, `\nWorkspace root — directory that contains all your projects\n  Example: ${os.homedir()}/WebstormProjects\n  Path (${defaultWorkspace}): `);
-    const workspaceRoot = expandHome(workspaceInput.trim() || defaultWorkspace);
-    const ollamaHost = await prompt(rl, 'Ollama API URL', 'http://localhost:11434');
+    const workspaceExample = (() => {
+        const candidates = ['Projects', 'projects', 'workspace', 'code', 'Code', 'dev', 'Development'];
+        const found = candidates.find(d => fs.existsSync(path.join(os.homedir(), d)));
+        return path.join(os.homedir(), found ?? 'projects');
+    })();
+    console.log(`\nWorkspace root — full path to the directory that contains all your projects`);
+    console.log(`  (e.g. ${workspaceExample})`);
+    let workspaceInput;
+    do {
+        workspaceInput = await loggedAsk('Path: ');
+        if (!workspaceInput.trim())
+            console.log('  Path is required.');
+    } while (!workspaceInput.trim());
+    const workspaceRoot = expandHome(workspaceInput.trim());
+    const ollamaHost = await loggedPrompt('Ollama API URL', 'http://localhost:11434');
     const dbVars = useDocker
-        ? await setupLocalDocker(ollamaHost)
-        : await setupRemoteDb(rl);
+        ? await setupLocalDocker(ollamaHost, await loggedPrompt('DB port', '5433'), await loggedPrompt('DB user', 'dev'), await loggedPrompt('DB password', 'dev'), logger, steps)
+        : await setupRemoteDb(rl, logger, steps, logStep);
     console.log('\n--- Logging ---');
     console.log('  error  — failures only (recommended)');
     console.log('  warn   — + recoverable issues');
@@ -191,20 +237,21 @@ async function runSetup() {
     const validLevels = ['error', 'warn', 'info', 'debug'];
     let logLevel;
     do {
-        logLevel = await prompt(rl, 'Log level (error/warn/info/debug)', 'error');
+        logLevel = await loggedPrompt('Log level (error/warn/info/debug)', 'error');
         if (!validLevels.includes(logLevel))
             console.log(`  Invalid level. Choose: ${validLevels.join(', ')}`);
     } while (!validLevels.includes(logLevel));
-    const defaultLogFile = path.join(os.homedir(), '.config', 'codesearch-mcp', 'rag.log');
-    const logFileInput = await ask(rl, `Log file (${defaultLogFile}, or "false" to disable): `);
-    const logFile = logFileInput.trim() || defaultLogFile;
-    writeEnv({
+    const logDirInput = await loggedAsk(`Log dir (leave blank for default: ${DEFAULT_LOG_DIR}, or "false" to disable): `);
+    const logDir = logDirInput.trim();
+    const envVars = {
         ...dbVars,
         WORKSPACE_ROOT: workspaceRoot,
         OLLAMA_HOST: ollamaHost,
         LOG_LEVEL: logLevel,
-        LOG_FILE: logFile,
-    });
+    };
+    if (logDir)
+        envVars['LOG_DIR'] = logDir;
+    writeEnv(envVars);
     rl.close();
     console.log('\nInitializing database schema...');
     const dotenv = await Promise.resolve().then(() => __importStar(require('dotenv')));
@@ -212,8 +259,21 @@ async function runSetup() {
     const { config } = await Promise.resolve().then(() => __importStar(require('./config')));
     const { DatabaseService } = await Promise.resolve().then(() => __importStar(require('./services/DatabaseService')));
     const dbService = new DatabaseService(config);
-    await dbService.initDbWithSchema();
-    await dbService.destroy();
+    let initError = null;
+    try {
+        await dbService.initDbWithSchema();
+    }
+    catch (err) {
+        initError = err instanceof Error ? err : new Error(String(err));
+    }
+    finally {
+        await dbService.destroy();
+    }
+    if (initError) {
+        console.error(`Database schema init failed: ${initError.message}`);
+        logger?.error('runSetup: database schema init failed', { reason: initError.message, steps });
+        process.exit(1);
+    }
     console.log('\nSetup complete!');
     console.log('\nNext steps:');
     console.log(`  rag-index ${workspaceRoot}`);

package/docker/docker-compose.yml

@@ -6,7 +6,7 @@ services:
     environment:
       POSTGRES_USER: dev
       POSTGRES_PASSWORD: dev
-      POSTGRES_DB: rag
+      POSTGRES_DB: postgres
     ports:
       - "5433:5432"
     volumes:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesearch-mcp",
-  "version": "0.0.13-alpha",
+  "version": "0.0.15-alpha",
   "description": "Local semantic codebase search via MCP — indexes projects into pgvector, exposes search to Claude",
   "license": "MIT",
   "main": "dist/app.js",
@@ -12,7 +12,8 @@
   "files": [
     "dist/",
     "docker/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -29,7 +30,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.1",
-    "@langchain/textsplitters": "^0.1.0",
+    "@langchain/textsplitters": "^1.0.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "cli-progress": "^3.12.0",
     "dotenv": "^17.4.2",