preflight-mcp 0.5.4 → 0.6.0

package/README.md

@@ -51,8 +51,9 @@ Preflight: 🔗 Trace links:
 - 📖 **Auto-generated guides** — `START_HERE.md`, `AGENTS.md`, `OVERVIEW.md`
 - ☁️ **Cloud sync** — Multi-path mirror backup for redundancy
 - 🧠 **EDDA (Evidence-Driven Deep Analysis)** — Auto-generate auditable claims with evidence
-- ⚡ **21 MCP tools + 5 prompts** — Complete toolkit for code exploration
+- ⚡ **17 MCP tools + 5 prompts** — Streamlined toolkit optimized for LLM use
 - 📄 **Cursor pagination** — Handle large result sets efficiently (RFC v2)
+- 🧠 **LLM-friendly** — Auto-compressed outputs, unified interfaces (v0.6.0)
 
 <details>
 <summary><b>All Features (click to expand)</b></summary>
@@ -161,13 +162,20 @@ Run end-to-end smoke test:
 npm run smoke
 ```
 
-## Tools (21 total)
+## Tools (17 active + 5 deprecated)
 
 ### `preflight_list_bundles`
 List bundle IDs in storage.
+- **Markdown output** (v0.6.0): LLM-friendly structured format
 - **Cursor pagination** (v0.5.0): Use `cursor` parameter for large bundle lists
 - Triggers: "show bundles", "查看bundle", "有哪些bundle"
 
+### `preflight_get_overview` *(NEW v0.6.0)*
+⭐ **START HERE** - Get project overview in one call.
+- Returns: OVERVIEW.md + START_HERE.md + AGENTS.md
+- Simplest entry point for exploring any bundle
+- Triggers: "了解项目", "项目概览", "what is this project", "show overview"
+
 ### `preflight_create_bundle`
 Create a new bundle from GitHub repos or local directories.
 - Triggers: "index this repo", "学习这个项目", "创建bundle"
@@ -240,28 +248,10 @@ Offline repair for a bundle (no fetching): rebuild missing/empty derived artifac
 - Rebuilds `indexes/search.sqlite3`, `START_HERE.md`, `AGENTS.md`, `OVERVIEW.md` when missing/empty.
 - Use when: search fails due to index corruption, bundle files were partially deleted, etc.
 
-### `preflight_search_bundle`
-Full-text search across ingested docs/code (line-based SQLite FTS5).
-- Triggers: "搜索bundle", "在仓库中查找", "搜代码"
-
-Important: **this tool is strictly read-only**.
-- To update: call `preflight_update_bundle`, then search again.
-- To repair: call `preflight_repair_bundle`, then search again.
-
-**New filtering options** (v0.3.1):
-- `excludePatterns`: Filter out paths matching patterns (e.g., `["**/tests/**", "**/__pycache__/**"]`)
-- `maxSnippetLength`: Limit snippet length per result (50-500 chars) to reduce token consumption
+### `preflight_search_bundle` *(DEPRECATED)*
+⚠️ **Use `preflight_search_and_read` instead** with `readContent: false` for index-only searches.
 
-**EDDA enhancements** (v0.4.0):
-- `groupByFile`: Group hits by file, returns `{path, hitCount, topSnippet}` - significantly reduces tokens
-- `fileTypeFilters`: Filter by extension (e.g., `[".py", ".ts"]`)
-- `includeScore`: Include BM25 relevance score in results
-
-**Cursor pagination** (v0.5.0):
-- `cursor`: Pagination cursor from previous call for fetching next page
-- Response includes `truncation.nextCursor` when more results available
-
-**Deprecated parameters**: `ensureFresh`, `autoRepairIndex`, `maxAgeHours` are deprecated and will return warnings instead of errors.
+Full-text search across ingested docs/code (line-based SQLite FTS5).
 
 ### `preflight_search_by_tags`
 Search across multiple bundles filtered by tags (line-based SQLite FTS5).
@@ -278,25 +268,17 @@ Optional parameters:
 - `limit`: Max total hits across all bundles
 - `cursor`: Pagination cursor for fetching next page
 
-### `preflight_evidence_dependency_graph`
-Generate an evidence-based dependency graph. Two modes:
-- **Target mode** (provide `target.file`): Analyze a specific file's imports and references
-- **Global mode** (omit `target`): Generate project-wide import graph of all code files
-- Deterministic output with source ranges for edges.
-- Uses Tree-sitter parsing when `PREFLIGHT_AST_ENGINE=wasm`; falls back to regex extraction otherwise.
-
-**Edge types** (v0.2.7+):
-- `edgeTypes: "imports"` (default): Only AST-based import edges (high confidence, recommended)
-- `edgeTypes: "all"`: Include FTS-based reference edges (name matching, may have false positives)
+### `preflight_dependency_graph` *(UNIFIED v0.6.0)*
+Get or generate dependency graph for a bundle.
+- **Auto-generates** if not cached, returns cached version if available
+- `scope: "global"` (default): Project-wide dependency graph
+- `scope: "target"` with `targetFile`: Dependencies for a specific file
+- `format: "summary"` (default): Top nodes, aggregated by directory
+- `format: "full"`: Complete graph data with coverage report
+- Triggers: "show dependencies", "看依赖图", "import graph"
 
-**Cache transparency** (v0.2.7+):
-- Response includes `meta.cacheInfo` with `fromCache`, `generatedAt`, `cacheAgeMs`
-- Use `force: true` to regenerate cached global graphs
-
-**Large file handling**:
-- `options.maxFileSizeBytes` (default: 1MB): Skip files larger than this
-- `options.largeFileStrategy`: `"skip"` (default) or `"truncate"`
-- `options.excludeExtensions`: Filter out non-code files from reference search (default: `.json`, `.md`, `.txt`, `.yml`, etc.)
+### `preflight_evidence_dependency_graph` *(DEPRECATED)*
+⚠️ **Use `preflight_dependency_graph` instead** - simpler interface with same functionality.
 
 ### `preflight_trace_upsert`
 Create or update traceability links (code↔test, code↔doc, file↔requirement).
@@ -311,27 +293,16 @@ Query traceability links (code↔test, code↔doc, commit↔ticket).
 - Returns `reason` and `nextSteps` when no edges found (helps LLM decide next action)
 - Fast when `bundleId` is provided; can scan across bundles when omitted.
 
-### `preflight_trace_export`
-Export trace links to `trace/trace.json` for direct LLM reading.
-- Note: Auto-exported after each `trace_upsert`, so only needed to manually refresh
-- Triggers: "export trace", "refresh trace.json", "导出trace"
-
-### `preflight_suggest_traces` *(NEW v0.4.0)*
-Automatically suggest trace links based on file naming patterns.
-- **MVP**: Only supports `tested_by` edge type (code↔test relationships)
-- Scans for patterns: `test_*.py`, `*_test.py`, `*.test.ts`, `*.spec.ts`, `*_test.go`
-- Returns ready-to-use `upsertPayload` for `preflight_trace_upsert`
-- Triggers: "suggest test links", "find test coverage", "发现测试关系"
+### `preflight_trace_export` *(DEPRECATED)*
+⚠️ trace.json is auto-exported after each `trace_upsert`. Use `preflight_read_file` with `file: "trace/trace.json"` to read.
 
-Parameters:
-- `edge_type`: `"tested_by"` (MVP only)
-- `scope`: `"repo"` | `"dir"` | `"file"`
-- `min_confidence`: 0-1 (default: 0.85)
-- `limit`: Max suggestions (default: 50)
+### `preflight_suggest_traces` *(DEPRECATED)*
+⚠️ Use `preflight_deep_analyze_bundle` for test detection, then `preflight_trace_upsert` manually.
 
-### `preflight_deep_analyze_bundle` *(Enhanced v0.5.1)*
+### `preflight_deep_analyze_bundle` *(Enhanced v0.6.0)*
 One-call deep analysis aggregating tree, search, deps, traces, **overview content**, and **test detection**.
 - Returns unified evidence pack with LLM-friendly summary
+- **Summary now includes OVERVIEW.md excerpt** (v0.6.0) - one call for complete context
 - **Now includes OVERVIEW.md, START_HERE.md, AGENTS.md, README content** (v0.5.1)
 - **Auto-detects test frameworks** (jest, vitest, pytest, go, mocha) (v0.5.1)
 - **Generates copyable `nextCommands`** for follow-up actions (v0.5.1)
@@ -374,36 +345,23 @@ Parameters:
 - `verifyFileExists`: Check evidence files exist (default: true)
 - `strictMode`: Treat warnings as errors (default: false)
 
-### `preflight_read_files` *(NEW v0.5.0)*
-Batch read multiple files from a bundle in a single call.
-- Reduces round-trips for evidence gathering
-- **RFC v2 unified envelope**: Returns `ok`, `meta`, `data`, `evidence[]`
-- Triggers: "read these files", "get content of", "批量读取"
-
-Parameters:
-- `bundleId`: Bundle ID
-- `files[]`: Array of `{path, ranges?, withLineNumbers?}`
-- `format`: `"json"` (default) or `"text"`
+### `preflight_read_files` *(DEPRECATED)*
+⚠️ Use multiple `preflight_read_file` calls, or use `preflight_search_and_read`.
 
-### `preflight_search_and_read` *(NEW v0.5.0)*
-Search + excerpt in one call - finds relevant code and returns context.
+### `preflight_search_and_read` *(Enhanced v0.6.0)*
+Search + excerpt in one call - the **primary search tool**.
 - Combines search with automatic context extraction
+- **`readContent: false`** (v0.6.0): Index-only search (replaces `preflight_search_bundle`)
 - **RFC v2 unified envelope**: Returns `ok`, `meta`, `data`, `evidence[]`
 - Triggers: "search and show code", "find and read", "搜索并读取"
 
 Parameters:
 - `bundleId`: Bundle ID
 - `query`: Search query
-- `contextLines`: Lines of context around matches (default: 5)
-- `maxFiles`: Max files to read (default: 5)
+- `contextLines`: Lines of context around matches (default: 30)
+- `readContent`: If false, return metadata only without reading files (default: true)
 - `format`: `"json"` (default) or `"text"`
 
-### `preflight_get_dependency_graph` *(Simplified wrapper)*
-Simplified dependency graph query.
-- `scope: "global"` (default): Project-wide graph
-- `scope: "target"` with `targetFile`: Single file dependencies
-- `format: "summary"` (default): Aggregated view
-- `format: "full"`: Raw graph data
 
 ### `preflight_cleanup_orphans`
 Remove incomplete or corrupted bundles (bundles without valid manifest.json).

package/dist/analysis/deep.js

@@ -23,6 +23,31 @@ export function buildDeepAnalysis(bundleId, components) {
     }
     // Build summary text
     const summaryParts = [];
+    // ✅ Enhancement: Include OVERVIEW.md summary at the top for one-call context
+    if (overviewContent?.overview) {
+        summaryParts.push(`## Project Overview`);
+        // Extract first meaningful paragraph (skip title lines starting with #)
+        const lines = overviewContent.overview.split('\n');
+        const contentLines = [];
+        let charCount = 0;
+        const MAX_CHARS = 800; // Limit to ~200 tokens
+        for (const line of lines) {
+            if (charCount >= MAX_CHARS)
+                break;
+            // Skip empty lines at start and title lines
+            if (contentLines.length === 0 && (line.trim() === '' || line.startsWith('#')))
+                continue;
+            contentLines.push(line);
+            charCount += line.length + 1;
+        }
+        if (contentLines.length > 0) {
+            summaryParts.push(contentLines.join('\n'));
+            if (charCount >= MAX_CHARS) {
+                summaryParts.push('...(truncated, see OVERVIEW.md for full content)');
+            }
+        }
+        summaryParts.push('');
+    }
     if (focusPath || focusQuery) {
         summaryParts.push(`## Analysis Focus`);
         if (focusPath)
@@ -403,12 +428,23 @@ export function buildDeepAnalysis(bundleId, components) {
         nextCommands,
     };
 }
+/**
+ * Test file naming patterns (language-agnostic)
+ */
+const TEST_FILE_PATTERNS = [
+    /\.test\.(ts|tsx|js|jsx|mjs|cjs)$/i, // *.test.ts, *.test.js
+    /\.spec\.(ts|tsx|js|jsx|mjs|cjs)$/i, // *.spec.ts, *.spec.js
+    /_test\.(py|go)$/i, // *_test.py, *_test.go
+    /^test_.*\.py$/i, // test_*.py (pytest convention)
+    /_test\.rs$/i, // *_test.rs (Rust)
+];
 /**
  * Detect test setup from file tree statistics.
- * Scans for test directories, test files, and framework config files.
+ * Scans for test directories, test files by naming pattern, and framework config files.
  */
 export function detectTestInfo(stats, filesFound) {
     const testDirs = [];
+    const testFiles = [];
     let testFileCount = 0;
     const configFiles = [];
     let framework = null;
@@ -424,6 +460,17 @@ export function detectTestInfo(stats, filesFound) {
             }
         }
     }
+    // **CRITICAL FIX**: Detect test files by naming pattern (*.test.ts, *.spec.ts, etc.)
+    // This catches test files that live alongside source files (e.g., src/foo.test.ts)
+    if (filesFound) {
+        for (const file of filesFound) {
+            const isTestFile = TEST_FILE_PATTERNS.some(pattern => pattern.test(file.name));
+            if (isTestFile) {
+                testFiles.push(file.path);
+                testFileCount++;
+            }
+        }
+    }
     // Framework detection from config files (if filesFound provided)
     const frameworkConfigs = [
         { pattern: /^jest\.config\.(js|ts|mjs|cjs|json)$/i, framework: 'jest' },
@@ -446,39 +493,49 @@ export function detectTestInfo(stats, filesFound) {
             }
         }
     }
-    // Infer framework from file extensions if not detected from config
-    if (!framework && stats.byExtension) {
-        // Check for test file patterns in extensions
+    // Infer framework from test file patterns if not detected from config
+    if (!framework && testFiles.length > 0) {
+        // Infer from file extensions
+        const hasTsTests = testFiles.some(f => /\.(ts|tsx)$/i.test(f));
+        const hasPyTests = testFiles.some(f => /\.py$/i.test(f));
+        const hasGoTests = testFiles.some(f => /\.go$/i.test(f));
+        if (hasGoTests)
+            framework = 'go';
+        else if (hasPyTests)
+            framework = 'pytest';
+        else if (hasTsTests)
+            framework = 'unknown'; // Could be jest/vitest/mocha
+    }
+    // Fallback: infer from general extension stats
+    if (!framework && testDirs.length > 0 && stats.byExtension) {
         const hasTs = (stats.byExtension['.ts'] ?? 0) > 0 || (stats.byExtension['.tsx'] ?? 0) > 0;
         const hasPy = (stats.byExtension['.py'] ?? 0) > 0;
         const hasGo = (stats.byExtension['.go'] ?? 0) > 0;
-        if (testDirs.length > 0 || testFileCount > 0) {
-            if (hasGo)
-                framework = 'go';
-            else if (hasPy)
-                framework = 'pytest';
-            else if (hasTs)
-                framework = 'unknown'; // Could be jest/vitest/mocha
-        }
-    }
-    // Count test files by pattern (approximate from extensions)
-    // This is a heuristic - actual test files may vary
-    if (testFileCount === 0 && stats.byExtension) {
-        // If no test directories found, estimate based on common patterns
-        // This is imprecise but gives a hint
+        if (hasGo)
+            framework = 'go';
+        else if (hasPy)
+            framework = 'pytest';
+        else if (hasTs)
+            framework = 'unknown';
     }
     const detected = testDirs.length > 0 || testFileCount > 0 || configFiles.length > 0;
     // Generate hint based on detection results
     let hint;
     if (detected) {
-        if (testFileCount > 0) {
-            hint = `Found ${testFileCount} test files. Run preflight_suggest_traces to map code↔test relationships.`;
+        if (testFiles.length > 0) {
+            // Show sample of detected test files
+            const sampleFiles = testFiles.slice(0, 3).map(f => f.split('/').pop()).join(', ');
+            const moreCount = testFiles.length > 3 ? ` (+${testFiles.length - 3} more)` : '';
+            hint = `Found ${testFileCount} test files (${sampleFiles}${moreCount}). Run preflight_suggest_traces to map code↔test relationships.`;
+        }
+        else if (testDirs.length > 0) {
+            hint = `Test directories found (${testDirs.join(', ')}). Run preflight_suggest_traces to map code↔test relationships.`;
         }
         else if (configFiles.length > 0) {
             hint = `Test config found (${configFiles[0]}). Run preflight_suggest_traces to discover test files.`;
         }
         else {
-            hint = `Test directories found. Run preflight_suggest_traces to map code↔test relationships.`;
+            hint = `Tests detected. Run preflight_suggest_traces to map code↔test relationships.`;
         }
     }
     else {
@@ -488,6 +545,7 @@ export function detectTestInfo(stats, filesFound) {
         detected,
         framework,
         testDirs,
+        testFiles: testFiles.slice(0, 20), // Limit to 20 for output size
         testFileCount,
         configFiles,
         hint,

package/dist/server.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
@@ -138,6 +139,17 @@ const GetTaskStatusInputSchema = {
     libraries: z.array(z.string()).optional().describe('Libraries for fingerprint computation.'),
     topics: z.array(z.string()).optional().describe('Topics for fingerprint computation.'),
 };
+// Read version from package.json at startup
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = path.resolve(__dirname, '..', 'package.json');
+let PACKAGE_VERSION = '0.0.0';
+try {
+    const pkgJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+    PACKAGE_VERSION = pkgJson.version ?? '0.0.0';
+}
+catch {
+    // Fallback if package.json cannot be read
+}
 export async function startServer() {
     const cfg = getConfig();
     // Run orphan bundle cleanup on startup (non-blocking, best-effort)
@@ -148,7 +160,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.5.3',
+        version: PACKAGE_VERSION,
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -329,22 +341,117 @@ export async function startServer() {
             }
             : { truncated: false, returnedCount: filtered.length, totalCount: allIds.length };
         const out = { bundles: filtered, truncation };
-        // Stable human-readable format for UI logs.
-        const lines = filtered.map((b) => {
-            const repos = b.repos.length ? b.repos.join(', ') : '(none)';
-            const tags = b.tags.length ? b.tags.join(', ') : '(none)';
-            return `${b.bundleId} | ${b.displayName} | repos: ${repos} | tags: ${tags}`;
-        });
-        // Add pagination hint to text output
-        let textOutput = lines.join('\n') || '(no bundles)';
+        // LLM-friendly Markdown format (easier to parse than pipe-separated)
+        const lines = [];
+        lines.push(`## Bundles (${filtered.length}${hasMore ? '+' : ''})`);
+        lines.push('');
+        for (const b of filtered) {
+            lines.push(`### ${b.displayName}`);
+            lines.push(`- **ID**: \`${b.bundleId}\``);
+            if (b.repos.length > 0) {
+                lines.push(`- **Repos**: ${b.repos.join(', ')}`);
+            }
+            if (b.tags.length > 0) {
+                lines.push(`- **Tags**: ${b.tags.join(', ')}`);
+            }
+            lines.push('');
+        }
+        // Add pagination hint
         if (hasMore) {
-            textOutput += `\n\n📄 More bundles available. Use cursor to fetch next page.`;
+            lines.push('---');
+            lines.push(`📄 More bundles available (total: ${allIds.length}). Use cursor to fetch next page.`);
         }
+        const textOutput = filtered.length > 0 ? lines.join('\n') : '(no bundles found)';
         return {
             content: [{ type: 'text', text: textOutput }],
             structuredContent: out,
         };
     });
+    // ==================== NEW: preflight_get_overview ====================
+    // Simplified tool for getting project overview - the FIRST step when exploring a bundle
+    server.registerTool('preflight_get_overview', {
+        title: 'Get bundle overview',
+        description: '⭐ **START HERE** - Get project overview in one call. Returns OVERVIEW.md + START_HERE.md + AGENTS.md. ' +
+            'This is the recommended FIRST tool to call when exploring any bundle. ' +
+            'Use when: "了解项目", "项目概览", "what is this project", "show overview", "get started".\n\n' +
+            '**Returns:**\n' +
+            '- OVERVIEW.md: AI-generated project summary & architecture\n' +
+            '- START_HERE.md: Key entry points & critical paths\n' +
+            '- AGENTS.md: AI agent usage guide\n\n' +
+            '**Next steps after overview:**\n' +
+            '1. `preflight_repo_tree` - See file structure\n' +
+            '2. `preflight_search` - Find specific code\n' +
+            '3. `preflight_read_file` - Read specific files',
+        inputSchema: {
+            bundleId: z.string().describe('Bundle ID to get overview for.'),
+        },
+        outputSchema: {
+            bundleId: z.string(),
+            overview: z.string().nullable().describe('OVERVIEW.md content'),
+            startHere: z.string().nullable().describe('START_HERE.md content'),
+            agents: z.string().nullable().describe('AGENTS.md content'),
+            sections: z.array(z.string()).describe('List of available sections'),
+        },
+        annotations: {
+            readOnlyHint: true,
+        },
+    }, async (args) => {
+        try {
+            const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
+            if (!storageDir) {
+                throw new BundleNotFoundError(args.bundleId);
+            }
+            const paths = getBundlePathsForId(storageDir, args.bundleId);
+            const bundleRoot = paths.rootDir;
+            const readFile = async (name) => {
+                try {
+                    return await fs.readFile(safeJoin(bundleRoot, name), 'utf8');
+                }
+                catch {
+                    return null;
+                }
+            };
+            const overview = await readFile('OVERVIEW.md');
+            const startHere = await readFile('START_HERE.md');
+            const agents = await readFile('AGENTS.md');
+            const sections = [];
+            if (overview)
+                sections.push('OVERVIEW.md');
+            if (startHere)
+                sections.push('START_HERE.md');
+            if (agents)
+                sections.push('AGENTS.md');
+            // Build human-readable text output
+            const textParts = [];
+            textParts.push(`[Bundle: ${args.bundleId}] Overview (${sections.length} sections)`);
+            textParts.push('');
+            if (overview) {
+                textParts.push('=== OVERVIEW.md ===');
+                textParts.push(overview);
+                textParts.push('');
+            }
+            if (startHere) {
+                textParts.push('=== START_HERE.md ===');
+                textParts.push(startHere);
+                textParts.push('');
+            }
+            if (agents) {
+                textParts.push('=== AGENTS.md ===');
+                textParts.push(agents);
+            }
+            if (sections.length === 0) {
+                textParts.push('⚠️ No overview files found. Try preflight_repo_tree to explore structure.');
+            }
+            const out = { bundleId: args.bundleId, overview, startHere, agents, sections };
+            return {
+                content: [{ type: 'text', text: textParts.join('\n') }],
+                structuredContent: out,
+            };
+        }
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
+    });
     server.registerTool('preflight_read_file', {
         title: 'Read bundle file(s)',
         description: 'Read file(s) from bundle. Two modes: ' +
@@ -384,9 +491,16 @@ export async function startServer() {
         inputSchema: {
             bundleId: z.string().describe('Bundle ID to read.'),
             file: z.string().optional().describe('Specific file to read (e.g., "deps/dependency-graph.json"). If omitted, uses mode-based batch reading.'),
-            mode: z.enum(['light', 'full']).optional().default('light').describe('Batch reading mode (used when file param is omitted). ' +
+            mode: z.enum(['light', 'full', 'core']).optional().default('light').describe('Batch reading mode (used when file param is omitted). ' +
                 'light: OVERVIEW + START_HERE + AGENTS + manifest only (recommended, saves tokens). ' +
-                'full: includes README and deps graph too.'),
+                'full: includes README and deps graph too. ' +
+                'core: ⭐ NEW - reads core source files (top imported + entry points) with outline and content.'),
+            coreOptions: z.object({
+                maxFiles: z.number().int().min(1).max(10).default(5).describe('Max core files to read.'),
+                includeOutline: z.boolean().default(true).describe('Include symbol outline for each file.'),
+                includeContent: z.boolean().default(true).describe('Include full file content.'),
+                tokenBudget: z.number().int().optional().describe('Approximate token budget (chars/4). Files exceeding budget return outline only.'),
+            }).optional().describe('Options for mode="core". Controls which files and how much content to return.'),
             includeReadme: z.boolean().optional().default(false).describe('Include repo README files in batch mode (can be large).'),
             includeDepsGraph: z.boolean().optional().default(false).describe('Include deps/dependency-graph.json in batch mode.'),
             withLineNumbers: z.boolean().optional().default(false).describe('If true, prefix each line with line number in "N|" format for evidence citation.'),
@@ -426,6 +540,20 @@ export async function startServer() {
                 children: z.array(z.any()).optional(),
             })).optional().describe('Symbol outline (when outline=true).'),
             language: z.string().optional().describe('Detected language (when outline=true).'),
+            // NEW: core mode output
+            coreFiles: z.array(z.object({
+                path: z.string(),
+                reason: z.string().describe('Why this file is considered core (e.g., "Most imported (5 dependents)")'),
+                outline: z.array(z.any()).optional().describe('Symbol outline'),
+                content: z.string().optional().describe('Full content (if within token budget)'),
+                language: z.string().optional(),
+                charCount: z.number().describe('Character count of file'),
+            })).optional().describe('Core files with outline and content (when mode="core").'),
+            coreStats: z.object({
+                totalFiles: z.number(),
+                totalChars: z.number(),
+                truncatedFiles: z.number().describe('Files where content was omitted due to token budget'),
+            }).optional().describe('Statistics for core mode.'),
         },
         annotations: {
             readOnlyHint: true,
@@ -624,6 +752,193 @@ export async function startServer() {
             }
             // Batch mode: read key files based on mode
             const mode = args.mode ?? 'light';
+            // ==================== MODE: CORE ====================
+            // Read core source files (top imported + entry points) with outline and content
+            if (mode === 'core') {
+                const coreOpts = (args.coreOptions ?? {});
+                const maxFiles = coreOpts.maxFiles ?? 5;
+                const includeOutline = coreOpts.includeOutline ?? true;
+                const includeContent = coreOpts.includeContent ?? true;
+                const tokenBudget = coreOpts.tokenBudget; // chars / 4 ≈ tokens
+                const charBudget = tokenBudget ? tokenBudget * 4 : undefined;
+                // Step 1: Generate dependency graph to find core files
+                let depResult;
+                try {
+                    depResult = await generateDependencyGraph(cfg, {
+                        bundleId: args.bundleId,
+                        options: { timeBudgetMs: 10000, maxNodes: 200, maxEdges: 1000 },
+                    });
+                }
+                catch {
+                    depResult = null;
+                }
+                // Step 2: Identify core files (most imported + entry points)
+                const coreFileCandidates = [];
+                if (depResult?.facts?.edges) {
+                    // Count how many times each file is imported
+                    const importedByCounts = {};
+                    for (const edge of depResult.facts.edges) {
+                        if (edge.type === 'imports' || edge.type === 'imports_resolved') {
+                            const to = typeof edge.to === 'string' ? edge.to.replace(/^(file:|module:)/, '') : '';
+                            if (to && !to.startsWith('node_modules') && !to.includes('node:')) {
+                                importedByCounts[to] = (importedByCounts[to] ?? 0) + 1;
+                            }
+                        }
+                    }
+                    // Sort by import count and add top files
+                    const sortedByImports = Object.entries(importedByCounts)
+                        .sort((a, b) => b[1] - a[1])
+                        .slice(0, maxFiles * 2); // Get more candidates for filtering
+                    for (const [filePath, count] of sortedByImports) {
+                        coreFileCandidates.push({
+                            path: filePath,
+                            reason: `Most imported (${count} dependents)`,
+                            score: count * 10,
+                        });
+                    }
+                }
+                // Add entry points (index.ts, main.ts, etc.)
+                const entryPointPatterns = [
+                    { pattern: /\/(index|main)\.(ts|js|tsx|jsx)$/i, reason: 'Entry point', score: 50 },
+                    { pattern: /\/app\.(ts|js|tsx|jsx)$/i, reason: 'App entry', score: 40 },
+                    { pattern: /\/server\.(ts|js)$/i, reason: 'Server entry', score: 40 },
+                    { pattern: /\/types\.(ts|d\.ts)$/i, reason: 'Type definitions', score: 30 },
+                ];
+                // Scan for entry points in repos directory
+                const scanEntryPoints = async (dir, relPath) => {
+                    try {
+                        const entries = await fs.readdir(dir, { withFileTypes: true });
+                        for (const entry of entries) {
+                            if (entry.name.startsWith('.') || ['node_modules', '__pycache__', 'dist', 'build'].includes(entry.name))
+                                continue;
+                            const fullPath = path.join(dir, entry.name);
+                            const entryRelPath = relPath ? `${relPath}/${entry.name}` : entry.name;
+                            if (entry.isFile()) {
+                                for (const ep of entryPointPatterns) {
+                                    if (ep.pattern.test('/' + entryRelPath)) {
+                                        // Check if already in candidates
+                                        const existing = coreFileCandidates.find(c => c.path.endsWith(entry.name) || c.path === entryRelPath);
+                                        if (!existing) {
+                                            coreFileCandidates.push({ path: entryRelPath, reason: ep.reason, score: ep.score });
+                                        }
+                                    }
+                                }
+                            }
+                            else if (entry.isDirectory() && relPath.split('/').length < 6) {
+                                await scanEntryPoints(fullPath, entryRelPath);
+                            }
+                        }
+                    }
+                    catch { /* ignore */ }
+                };
+                await scanEntryPoints(paths.reposDir, 'repos');
+                // Sort by score and dedupe
+                coreFileCandidates.sort((a, b) => b.score - a.score);
+                const seenPaths = new Set();
+                const uniqueCandidates = coreFileCandidates.filter(c => {
+                    const key = c.path.split('/').pop() ?? c.path;
+                    if (seenPaths.has(key))
+                        return false;
+                    seenPaths.add(key);
+                    return true;
+                }).slice(0, maxFiles);
+                // Step 3: Read each core file with outline and content
+                const coreFilesResult = [];
+                let totalChars = 0;
+                let truncatedFiles = 0;
+                for (const candidate of uniqueCandidates) {
+                    // Resolve actual file path
+                    let actualPath = candidate.path;
+                    let absPath;
+                    // Try different path resolutions
+                    const pathsToTry = [
+                        candidate.path,
+                        `repos/${candidate.path}`,
+                        candidate.path.startsWith('repos/') ? candidate.path : null,
+                    ].filter(Boolean);
+                    let fileContent = null;
+                    for (const tryPath of pathsToTry) {
+                        try {
+                            absPath = safeJoin(bundleRoot, tryPath);
+                            fileContent = await fs.readFile(absPath, 'utf8');
+                            actualPath = tryPath;
+                            break;
+                        }
+                        catch { /* try next */ }
+                    }
+                    if (!fileContent)
+                        continue;
+                    const charCount = fileContent.length;
+                    const withinBudget = !charBudget || (totalChars + charCount <= charBudget);
+                    const result = {
+                        path: actualPath,
+                        reason: candidate.reason,
+                        charCount,
+                    };
+                    // Extract outline if requested
+                    if (includeOutline) {
+                        const outlineResult = await extractOutlineWasm(actualPath, fileContent);
+                        if (outlineResult) {
+                            result.outline = outlineResult.outline;
+                            result.language = outlineResult.language;
+                        }
+                    }
+                    // Include content if requested and within budget
+                    if (includeContent && withinBudget) {
+                        result.content = fileContent;
+                        totalChars += charCount;
+                    }
+                    else if (includeContent && !withinBudget) {
+                        truncatedFiles++;
+                    }
+                    coreFilesResult.push(result);
+                }
+                // Build text output
+                const textParts = [];
+                textParts.push(`[Mode: core] ${coreFilesResult.length} core files identified`);
+                textParts.push(`Total: ${totalChars} chars (~${Math.round(totalChars / 4)} tokens)`);
+                if (truncatedFiles > 0) {
+                    textParts.push(`⚠️ ${truncatedFiles} file(s) exceeded token budget - showing outline only`);
+                }
+                textParts.push('');
+                for (const cf of coreFilesResult) {
+                    textParts.push(`=== ${cf.path} (${cf.reason}) ===`);
+                    // Show outline
+                    if (cf.outline && cf.outline.length > 0) {
+                        textParts.push(`[Outline - ${cf.outline.length} symbols]`);
+                        for (const sym of cf.outline.slice(0, 10)) {
+                            const exp = sym.exported ? '⚡' : '';
+                            textParts.push(`  ${exp}${sym.kind} ${sym.name}${sym.signature || ''} :${sym.range.startLine}-${sym.range.endLine}`);
+                        }
+                        if (cf.outline.length > 10) {
+                            textParts.push(`  ... and ${cf.outline.length - 10} more symbols`);
+                        }
+                    }
+                    // Show content
+                    if (cf.content) {
+                        textParts.push(`[Content - ${cf.charCount} chars]`);
+                        textParts.push('```' + (cf.language || ''));
+                        textParts.push(cf.content);
+                        textParts.push('```');
+                    }
+                    textParts.push('');
+                }
+                const out = {
+                    bundleId: args.bundleId,
+                    mode: 'core',
+                    coreFiles: coreFilesResult,
+                    coreStats: {
+                        totalFiles: coreFilesResult.length,
+                        totalChars,
+                        truncatedFiles,
+                    },
+                };
+                return {
+                    content: [{ type: 'text', text: textParts.join('\n') }],
+                    structuredContent: out,
+                };
+            }
+            // ==================== MODE: LIGHT / FULL ====================
             const includeReadme = args.includeReadme ?? (mode === 'full');
             const includeDepsGraph = args.includeDepsGraph ?? (mode === 'full');
             // Core files (always included in both modes)
@@ -690,6 +1005,7 @@ export async function startServer() {
                 textParts.push('💡 To include README: set includeReadme=true');
                 textParts.push('💡 To include dependency graph: set includeDepsGraph=true');
                 textParts.push('💡 For all content: set mode="full"');
+                textParts.push('💡 ⭐ For core source code: set mode="core"');
             }
             const out = { bundleId: args.bundleId, mode, files, sections };
             return {
@@ -1460,8 +1776,10 @@ export async function startServer() {
     // End RFC v2 tools
     // ==========================================================================
     server.registerTool('preflight_search_bundle', {
-        title: 'Search bundle',
-        description: 'Full-text search in bundle docs and code (strictly read-only). If you need to update or repair, call preflight_update_bundle or preflight_repair_bundle explicitly, then search again. Use when: "search in bundle", "find in repo", "look for X in bundle", "搜索bundle", "在仓库中查找", "搜代码", "搜文档".',
+        title: 'Search bundle (DEPRECATED)',
+        description: '⚠️ **DEPRECATED**: Use `preflight_search_and_read` instead. ' +
+            'For index-only search without reading content, use `preflight_search_and_read` with `readContent: false`.\n\n' +
+            'Full-text search in bundle docs and code (strictly read-only). If you need to update or repair, call preflight_update_bundle or preflight_repair_bundle explicitly, then search again.',
         inputSchema: SearchBundleInputSchema,
         outputSchema: {
             bundleId: z.string(),
@@ -1638,15 +1956,35 @@ export async function startServer() {
                             : g.topSnippet,
                     }));
                 }
+                // Auto-compress: extract common repo to top-level if all results from same repo
+                let commonRepo;
+                if (grouped && grouped.length > 0) {
+                    const repos = new Set(grouped.map(g => g.repo));
+                    if (repos.size === 1 && grouped[0]) {
+                        commonRepo = grouped[0].repo;
+                    }
+                }
+                // Build compressed grouped results (omit repo when extracted to top-level)
+                const compressedGrouped = grouped?.map(g => {
+                    const { repo, ...rest } = g;
+                    return commonRepo ? rest : g;
+                });
                 const out = {
                     bundleId: args.bundleId,
                     query: args.query,
                     scope: args.scope,
-                    hits: paginatedHits.map(h => ({
-                        ...h,
-                        uri: toBundleFileUri({ bundleId: args.bundleId, relativePath: h.path }),
-                    })),
-                    grouped,
+                    // Auto-compress: omit uri (can be derived from bundleId + path)
+                    hits: paginatedHits.map(h => {
+                        const { context, ...rest } = h;
+                        // Auto-compress: trim surroundingLines to save tokens
+                        const compressedContext = context ? {
+                            ...context,
+                            surroundingLines: context.surroundingLines?.slice(0, 5),
+                        } : undefined;
+                        return compressedContext ? { ...rest, context: compressedContext } : rest;
+                    }),
+                    grouped: compressedGrouped,
+                    ...(commonRepo && { repo: commonRepo }), // Extracted common repo
                     meta: result.meta,
                 };
                 if (warnings.length > 0) {
@@ -1697,21 +2035,33 @@ export async function startServer() {
             const hasMore = rawHits.length > offset + pageSize;
             // Apply cursor pagination
             rawHits = rawHits.slice(offset, offset + pageSize);
+            // Auto-compress: extract common repo if all hits from same repo
+            let commonRepo;
+            if (rawHits.length > 0 && rawHits[0]) {
+                const repos = new Set(rawHits.map(h => h.repo).filter(Boolean));
+                if (repos.size === 1) {
+                    commonRepo = rawHits[0].repo;
+                }
+            }
             const hits = rawHits.map((h) => {
-                const hit = {
-                    ...h,
-                    uri: toBundleFileUri({ bundleId: args.bundleId, relativePath: h.path }),
-                };
+                // Auto-compress: omit uri (derivable from bundleId + path), omit repo when extracted
+                const { uri: _uri, repo, context, ...rest } = h;
+                const hit = commonRepo && repo === commonRepo
+                    ? rest // Omit repo when extracted to top-level
+                    : { ...rest, ...(repo ? { repo } : {}) };
                 // Apply maxSnippetLength truncation
                 if (args.maxSnippetLength && h.snippet && h.snippet.length > args.maxSnippetLength) {
                     hit.snippet = h.snippet.slice(0, args.maxSnippetLength) + '…';
                 }
-                // Truncate surroundingLines if maxSnippetLength is set
-                if (args.maxSnippetLength && h.context?.surroundingLines) {
-                    const maxLines = Math.max(3, Math.floor(args.maxSnippetLength / 50));
+                // Auto-compress: limit surroundingLines to save tokens (default 5, or based on maxSnippetLength)
+                if (context?.surroundingLines) {
+                    const ctx = context;
+                    const maxLines = args.maxSnippetLength
+                        ? Math.max(3, Math.floor(args.maxSnippetLength / 50))
+                        : 5; // Default auto-compress to 5 lines
                     hit.context = {
-                        ...h.context,
-                        surroundingLines: h.context.surroundingLines.slice(0, maxLines),
+                        ...ctx,
+                        surroundingLines: ctx.surroundingLines.slice(0, maxLines),
                     };
                 }
                 return hit;
@@ -1721,6 +2071,7 @@ export async function startServer() {
                 query: args.query,
                 scope: args.scope,
                 hits,
+                ...(commonRepo && { repo: commonRepo }), // Auto-compress: extracted common repo
             };
             if (warnings.length > 0) {
                 out.warnings = warnings;
@@ -1751,27 +2102,12 @@ export async function startServer() {
         }
     });
     server.registerTool('preflight_evidence_dependency_graph', {
-        title: 'Evidence: dependency graph',
-        description: '**Proactive use recommended**: Generate dependency graphs to understand code structure. ' +
-            'Generate an evidence-based dependency graph. IMPORTANT: Before running, ASK the user which bundle and which file/mode they want! ' +
+        title: 'Evidence: dependency graph (DEPRECATED)',
+        description: '⚠️ **DEPRECATED**: Use `preflight_dependency_graph` instead. ' +
+            'This tool provides the same functionality with a simpler interface.\n\n' +
+            'Generate an evidence-based dependency graph. ' +
             'Two modes: (1) TARGET MODE: analyze a specific file (provide target.file). (2) GLOBAL MODE: project-wide graph (omit target). ' +
-            'Do NOT automatically choose bundle or mode - confirm with user first! ' +
-            'File path must be bundle-relative: repos/{owner}/{repo}/norm/{path}.\n\n' +
-            '📊 **Coverage Report (Global Mode):**\n' +
-            'The response includes a `coverageReport` explaining what was analyzed:\n' +
-            '- `scannedFilesCount` / `parsedFilesCount`: Files discovered vs successfully parsed\n' +
-            '- `perLanguage`: Statistics per programming language (TypeScript, Python, etc.)\n' +
-            '- `perDir`: File counts per top-level directory\n' +
-            '- `skippedFiles`: Files that were skipped with reasons (too large, read error, etc.)\n' +
-            '- `truncated` / `truncatedReason`: Whether limits were hit\n\n' +
-            'Use this to understand graph completeness and identify gaps.\n\n' +
-            '📂 **Large File Handling (LLM Guidance):**\n' +
-            '- Default: files >1MB are skipped to avoid timeouts\n' +
-            '- If coverageReport.skippedFiles shows important files were skipped:\n' +
-            '  1. Try `largeFileStrategy: "truncate"` to read first 500 lines\n' +
-            '  2. Or increase `maxFileSizeBytes` (e.g., 5000000 for 5MB)\n' +
-            '- Options: `{ maxFileSizeBytes: 5000000, largeFileStrategy: "truncate", truncateLines: 1000 }`\n' +
-            '- User can override these settings if needed',
+            'File path must be bundle-relative: repos/{owner}/{repo}/norm/{path}.',
         inputSchema: DependencyGraphInputSchema,
         outputSchema: {
             meta: z.any(),
@@ -1842,18 +2178,19 @@ export async function startServer() {
             throw wrapPreflightError(err);
         }
     });
-    // Simplified dependency graph tool for single-point tasks
-    server.registerTool('preflight_get_dependency_graph', {
-        title: 'Get dependency graph (simplified)',
-        description: 'Get dependency graph with minimal parameters. ' +
-            'Use when user asks: "show dependencies", "看依赖图", "import graph", "what does X depend on". ' +
-            'This is a simplified wrapper around preflight_evidence_dependency_graph.\n\n' +
+    // ==================== MAIN: preflight_dependency_graph ====================
+    // Unified tool for dependency graphs (replaces both evidence_dependency_graph and get_dependency_graph)
+    server.registerTool('preflight_dependency_graph', {
+        title: 'Dependency graph',
+        description: 'Get or generate dependency graph for a bundle. ' +
+            'Auto-generates if not cached, returns cached version if available. ' +
+            'Use when: "show dependencies", "看依赖图", "import graph", "what does X depend on".\n\n' +
             '**Modes:**\n' +
             '- `scope: "global"` (default): Project-wide dependency graph\n' +
             '- `scope: "target"` with `targetFile`: Dependencies for a specific file\n\n' +
             '**Format:**\n' +
             '- `format: "summary"` (default): Top nodes, aggregated by directory, key edges only\n' +
-            '- `format: "full"`: Complete graph data',
+            '- `format: "full"`: Complete graph data with coverage report',
         inputSchema: {
             bundleId: z.string().describe('Bundle ID. Use preflight_list_bundles to find available bundles.'),
             scope: z.enum(['global', 'target']).optional().default('global').describe('global=project-wide, target=single file.'),
@@ -2140,10 +2477,10 @@ export async function startServer() {
         }
     });
     server.registerTool('preflight_trace_export', {
-        title: 'Trace: export to JSON',
-        description: 'Export trace links to trace/trace.json for direct LLM reading. ' +
-            'Note: trace.json is auto-exported after each trace_upsert, so this tool is only needed to manually refresh or verify the export. ' +
-            'Use when: "export trace", "refresh trace.json", "导出trace", "刷新trace.json".',
+        title: 'Trace: export to JSON (DEPRECATED)',
+        description: '⚠️ **DEPRECATED**: trace.json is auto-exported after each trace_upsert, so this tool is rarely needed. ' +
+            'Use `preflight_read_file` with `file: "trace/trace.json"` to read exported traces directly.\n\n' +
+            'Export trace links to trace/trace.json. Only needed to manually refresh or verify the export.',
         inputSchema: {
             bundleId: z.string().describe('Bundle ID to export trace links from.'),
         },
@@ -2250,6 +2587,7 @@ export async function startServer() {
                 detected: z.boolean(),
                 framework: z.enum(['jest', 'vitest', 'pytest', 'go', 'mocha', 'unknown']).nullable(),
                 testDirs: z.array(z.string()),
+                testFiles: z.array(z.string()).describe('Test files detected by naming pattern (*.test.ts, *.spec.ts, etc.)'),
                 testFileCount: z.number(),
                 configFiles: z.array(z.string()),
                 hint: z.string(),
@@ -2488,8 +2826,31 @@ export async function startServer() {
             }
             // 7. Test detection
             if ((opts.includeTests ?? true) && tree) {
-                // Collect files for framework detection
+                // Collect files for test detection (config files + source files)
                 const filesFound = [];
+                // Helper to recursively scan for files
+                const scanDir = async (dir, relPath, maxDepth) => {
+                    if (maxDepth <= 0)
+                        return;
+                    try {
+                        const entries = await fs.readdir(dir, { withFileTypes: true });
+                        for (const entry of entries) {
+                            if (entry.name.startsWith('.') || ['node_modules', '__pycache__', 'venv', '.venv', 'dist', 'build'].includes(entry.name))
+                                continue;
+                            const fullPath = safeJoin(dir, entry.name);
+                            const entryRelPath = relPath ? `${relPath}/${entry.name}` : entry.name;
+                            if (entry.isFile()) {
+                                filesFound.push({ path: entryRelPath, name: entry.name });
+                            }
+                            else if (entry.isDirectory()) {
+                                await scanDir(fullPath, entryRelPath, maxDepth - 1);
+                            }
+                        }
+                    }
+                    catch {
+                        // Ignore directory access errors
+                    }
+                };
                 try {
                     // Scan for config files at bundle root
                     const configPatterns = [
@@ -2508,9 +2869,12 @@ export async function startServer() {
                             // Config file doesn't exist
                         }
                     }
+                    // **CRITICAL**: Scan repos/ directory to find test files (*.test.ts, *.spec.ts, etc.)
+                    // This is essential for detecting tests that live alongside source files
+                    await scanDir(paths.reposDir, 'repos', 8); // Scan up to 8 levels deep
                 }
                 catch {
-                    // Ignore errors during config scanning
+                    // Ignore errors during scanning
                 }
                 testInfo = detectTestInfo({ byExtension: tree.byExtension, byTopDir: tree.topDirs.reduce((acc, d) => ({ ...acc, [d.path]: d.fileCount }), {}) }, filesFound.length > 0 ? filesFound : undefined);
             }
@@ -2635,14 +2999,11 @@ export async function startServer() {
         }
     });
     server.registerTool('preflight_suggest_traces', {
-        title: 'Trace: suggest links',
-        description: 'Automatically suggest trace links based on file naming patterns. ' +
-            'MVP: Only supports tested_by edge type (code↔test relationships). ' +
-            'Use to bulk-discover test coverage relationships before reviewing/upserting.\n\n' +
-            '**Workflow:**\n' +
-            '1. Call with dryRun-style output to preview suggestions\n' +
-            '2. Review suggestions (LLM or human)\n' +
-            '3. Use trace_upsert with returned upsertPayload to persist approved links',
+        title: 'Trace: suggest links (DEPRECATED)',
+        description: '⚠️ **DEPRECATED**: This tool has limited value. Use `preflight_deep_analyze_bundle` for test detection, ' +
+            'then manually create trace links with `preflight_trace_upsert` if needed.\n\n' +
+            'Automatically suggest trace links based on file naming patterns. ' +
+            'MVP: Only supports tested_by edge type (code↔test relationships).',
         inputSchema: {
             bundleId: z.string().describe('Bundle ID to scan for trace suggestions.'),
             edge_type: z.enum(['tested_by']).default('tested_by').describe('Type of edge to suggest. MVP only supports tested_by.'),

package/dist/tools/readFiles.js

@@ -208,17 +208,9 @@ export function createReadFilesHandler(deps) {
  * Tool description for MCP registration.
  */
 export const readFilesToolDescription = {
-    title: 'Read multiple files',
-    description: 'Read multiple files from a bundle in a single call. ' +
-        'Reduces round-trips for evidence gathering. ' +
-        'Each file can specify optional line ranges and line number formatting.\n\n' +
-        '**LLM Usage Guide:**\n' +
-        '- Use when you know which files to read (from search results, tree, or overview)\n' +
-        '- Specify ranges to read only relevant portions (saves tokens)\n' +
-        '- Default withLineNumbers=true provides citation-ready format\n' +
-        '- Max 20 files per call, 1MB total response limit\n\n' +
-        '**Evidence Citation:**\n' +
-        '- Response includes evidence[] with path + range for each file read\n' +
-        '- Use format "path:startLine-endLine" in your citations\n\n' +
-        'Triggers: "read these files", "get content of", "批量读取", "读取多个文件"',
+    title: 'Read multiple files (DEPRECATED)',
+    description: '⚠️ **DEPRECATED**: Use multiple `preflight_read_file` calls, or use `preflight_search_and_read` ' +
+        'which combines search and reading in one call.\n\n' +
+        'Read multiple files from a bundle in a single call. ' +
+        'Each file can specify optional line ranges and line number formatting.',
 };

package/dist/tools/searchAndRead.js

@@ -65,6 +65,13 @@ export const SearchAndReadInputSchema = {
         .enum(['json', 'text'])
         .default('json')
         .describe('Response format. json=unified envelope (default).'),
+    // NEW: readContent parameter for search-only mode (replaces search_bundle)
+    readContent: z
+        .boolean()
+        .default(true)
+        .describe('If true (default), read file excerpts for each hit. ' +
+        'If false, return search metadata only (path, lineNo, score) without reading file content. ' +
+        'Use false for quick index-only searches (like groupByFile in search_bundle).'),
 };
 /**
  * Compute SHA256 hash of content.
@@ -189,15 +196,16 @@ export function createSearchAndReadHandler(deps) {
             });
             // Apply pagination offset
             rawHits = rawHits.slice(offset);
-            // Build result hits with excerpts
+            // Build result hits with excerpts (or metadata-only if readContent=false)
             const hits = [];
             let totalBytes = 0;
             const estimatedTokensPerByte = 0.25; // Rough estimate
+            const shouldReadContent = args.readContent ?? true;
             for (const rawHit of rawHits) {
                 if (hits.length >= limit)
                     break;
-                // Check token budget
-                if (tokenBudget && totalBytes * estimatedTokensPerByte > tokenBudget) {
+                // Check token budget (only relevant when reading content)
+                if (shouldReadContent && tokenBudget && totalBytes * estimatedTokensPerByte > tokenBudget) {
                     addWarning(ctx, WarningCodes.RESULT_TRUNCATED, 'Token budget exceeded', true);
                     setTruncation(ctx, true, {
                         reason: 'Token budget exceeded',
@@ -205,6 +213,21 @@ export function createSearchAndReadHandler(deps) {
                     });
                     break;
                 }
+                // readContent=false: return metadata only (index-only search)
+                if (!shouldReadContent) {
+                    const hit = {
+                        path: rawHit.path,
+                        repo: rawHit.repo,
+                        kind: rawHit.kind,
+                        matchRange: { startLine: rawHit.lineNo, endLine: rawHit.lineNo },
+                        excerptRange: { startLine: rawHit.lineNo, endLine: rawHit.lineNo },
+                        excerpt: rawHit.snippet || '', // Use indexed snippet if available
+                        score: rawHit.score,
+                    };
+                    hits.push(hit);
+                    continue;
+                }
+                // readContent=true: read full excerpt with context
                 const excerptResult = await readExcerpt(paths.rootDir, rawHit, contextLines, withLineNumbers, maxBytesPerHit);
                 if (!excerptResult)
                     continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preflight-mcp",
-"version": "0.5.4",
+"version": "0.6.0",
   "description": "MCP server that creates evidence-based preflight bundles for GitHub repositories and library docs.",
   "type": "module",
   "license": "MIT",