codesearch-mcp 0.0.14-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/dist/src/services/McpServer.js

@@ -48,29 +48,65 @@ 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. **Before searching**: if your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.35\`) to \`search_codebase\` to filter out weak matches. Default threshold is permissive — tighten it when semantic drift is likely.
-3. Use \`search_codebase\` to find relevant code by meaning.
-4. If a result **starts mid-function or mid-class** (e.g. you see a closing brace or a method body without the declaration), re-run the same search with \`include_neighbors: true\` — it automatically fetches the chunk before and after each match. If you need a specific line range, use \`read_file_range\` instead.
-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.
+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.
+
+### 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).
+
+> **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.
+
+### 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.
+
+## When to use read_file_range vs include_neighbors
+
+- **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
 
@@ -80,8 +116,9 @@ If \`get_dependents\` returns 0 results, add \`symbol\` (the exported name you c
 
 ## Relevance scores
 
-Lower score = better match (cosine distance). Results above the configured threshold are filtered out automatically. Pass \`threshold\` to \`search_codebase\` to override per-query (e.g. \`0.35\` for strict, \`0.55\` for broad).
+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;
@@ -92,7 +129,7 @@ class McpServer {
         this.logger = logger;
     }
     async start(startupError) {
-        const server = new index_js_1.Server({ name: 'local-rag', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
+        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: [
                 {
@@ -105,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: {} },
                 },
                 {
@@ -185,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'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codesearch-mcp",
-  "version": "0.0.14-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",