preflight-mcp 0.2.3 → 0.2.5

package/README.md

@@ -15,7 +15,7 @@ Each bundle contains:
 
 ## Features
 
-- **13 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
+- **15 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
 - **5 MCP prompts** for interactive guidance: menu, analyze guide, search guide, manage guide, trace guide
 - **LLM-friendly outputs**: After bundle creation, prompts user to generate dependency graph for deeper analysis
 - **Proactive trace links**: LLM automatically discovers and records code↔test, code↔doc relationships
@@ -125,7 +125,7 @@ Run end-to-end smoke test:
 npm run smoke
 ```
 
-## Tools (13 total)
+## Tools (15 total)
 
 ### `preflight_list_bundles`
 List bundle IDs in storage.
@@ -156,10 +156,15 @@ Input (example):
 ### `preflight_read_file`
 Read file(s) from bundle. Two modes:
 - **Batch mode** (omit `file`): Returns ALL key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, deps/dependency-graph.json, repo READMEs) in one call
-- **Single file mode** (provide `file`): Returns that specific file (e.g., `deps/dependency-graph.json` for dependency graph)
+- **Single file mode** (provide `file`): Returns that specific file
+- **Evidence citation**: Use `withLineNumbers: true` to get `N|line` format; use `ranges: ["20-80"]` to read specific lines
 - Triggers: "查看bundle", "bundle概览", "项目信息", "show bundle", "读取依赖图"
-- Use `file: "manifest.json"` to get bundle metadata (repos, timestamps, tags, etc.)
-- Use `file: "deps/dependency-graph.json"` to read the dependency graph (generated by `preflight_evidence_dependency_graph`)
+
+### `preflight_repo_tree`
+Get repository structure overview without wasting tokens on search.
+- Returns: ASCII directory tree, file count by extension/directory, entry point candidates
+- Use BEFORE deep analysis to understand project layout
+- Triggers: "show project structure", "what files are in this repo", "项目结构", "文件分布"
 
 ### `preflight_delete_bundle`
 Delete/remove a bundle permanently.
@@ -216,9 +221,14 @@ Create or update traceability links (code↔test, code↔doc, file↔requirement
 ### `preflight_trace_query`
 Query traceability links (code↔test, code↔doc, commit↔ticket).
 - **Proactive use**: LLM automatically queries trace links when analyzing specific files
-- Helps answer: "Does this code have tests?", "What requirements does this implement?"
+- 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_cleanup_orphans`
 Remove incomplete or corrupted bundles (bundles without valid manifest.json).
 - Triggers: "clean up broken bundles", "remove orphans", "清理孤儿bundle"

package/README.zh-CN.md

@@ -15,7 +15,7 @@
 
 ## Features
 
-- **13 个 MCP 工具**：create/update/repair/search/evidence/trace/read/cleanup（外加 resources）
+- **15 个 MCP 工具**：create/update/repair/search/evidence/trace/read/cleanup（外加 resources）
 - **5 个 MCP prompts**：交互式引导（菜单、分析指南、搜索指南、管理指南、追溯指南）
 - **去重**：避免对相同的规范化输入重复索引
 - **可靠的 GitHub 获取**：可配置 git clone 超时 + GitHub archive（zipball）兜底
@@ -140,7 +140,7 @@ npm run smoke
 - 列表与清理逻辑只接受 UUID v4 作为 bundleId
 - 会自动过滤 `#recycle`、`tmp`、`.deleting` 等非 bundle 目录
 
-## Tools (12 total)
+## Tools (15 total)
 
 ### `preflight_list_bundles`
 列出所有 bundle。
@@ -170,11 +170,16 @@ npm run smoke
 
 ### `preflight_read_file`
 从 bundle 读取文件。两种模式：
-- **批量模式**（省略 `file`）：返回所有关键文件（OVERVIEW.md、START_HERE.md、AGENTS.md、manifest.json、deps/dependency-graph.json、repo READMEs）
-- **单文件模式**（提供 `file`）：返回指定文件（如 `deps/dependency-graph.json` 获取依赖图）
+- **批量模式**（省略 `file`）：返回所有关键文件
+- **单文件模式**（提供 `file`）：返回指定文件
+- **证据引用**：使用 `withLineNumbers: true` 获取 `N|行` 格式；使用 `ranges: ["20-80"]` 读取指定行
 - 触发词：「查看概览」「项目概览」「bundle详情」「读取依赖图」
-- 使用 `file: "manifest.json"` 获取 bundle 元数据
-- 使用 `file: "deps/dependency-graph.json"` 读取依赖图（由 `preflight_evidence_dependency_graph` 生成）
+
+### `preflight_repo_tree`
+获取仓库结构概览，避免浪费 token 搜索。
+- 返回：ASCII 目录树、按扩展名/目录统计文件数、入口点候选
+- 在深入分析前使用，了解项目布局
+- 触发词：「项目结构」「文件分布」「show tree」
 
 ### `preflight_delete_bundle`
 永久删除/移除一个 bundle。
@@ -225,7 +230,14 @@ npm run smoke
 写入/更新 bundle 级 traceability links（commit↔ticket、symbol↔test、code↔doc 等）。
 
 ### `preflight_trace_query`
-查询 traceability links（提供 `bundleId` 时更快；省略时可跨 bundle 扫描，带上限）。
+查询 traceability links。
+- 无匹配边时返回 `reason` 和 `nextSteps`（帮助 LLM 决定下一步）
+- 提供 `bundleId` 时更快；省略时可跨 bundle 扫描
+
+### `preflight_trace_export`
+导出 trace links 到 `trace/trace.json`。
+- 注意：每次 `trace_upsert` 后会自动导出，此工具仅用于手动刷新
+- 触发词：「导出trace」「刷新trace.json」
 
 ### `preflight_cleanup_orphans`
 删除不完整或损坏的 bundle（缺少有效 manifest.json）。

package/dist/bundle/tree.js

@@ -0,0 +1,224 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const ENTRY_POINT_PATTERNS = [
+    { pattern: /^readme\.md$/i, type: 'readme', priority: 100 },
+    { pattern: /^readme$/i, type: 'readme', priority: 95 },
+    { pattern: /^index\.(ts|js|tsx|jsx|py|go|rs)$/i, type: 'index', priority: 90 },
+    { pattern: /^main\.(ts|js|tsx|jsx|py|go|rs)$/i, type: 'main', priority: 85 },
+    { pattern: /^app\.(ts|js|tsx|jsx|py)$/i, type: 'app', priority: 80 },
+    { pattern: /^server\.(ts|js|tsx|jsx|py|go)$/i, type: 'server', priority: 75 },
+    { pattern: /^cli\.(ts|js|py)$/i, type: 'cli', priority: 70 },
+    { pattern: /^__init__\.py$/i, type: 'index', priority: 60 },
+    { pattern: /^mod\.rs$/i, type: 'index', priority: 60 },
+    { pattern: /^lib\.rs$/i, type: 'main', priority: 85 },
+    { pattern: /^package\.json$/i, type: 'config', priority: 50 },
+    { pattern: /^pyproject\.toml$/i, type: 'config', priority: 50 },
+    { pattern: /^cargo\.toml$/i, type: 'config', priority: 50 },
+    { pattern: /^go\.mod$/i, type: 'config', priority: 50 },
+    { pattern: /\.test\.(ts|js|tsx|jsx)$/i, type: 'test', priority: 30 },
+    { pattern: /_test\.(py|go)$/i, type: 'test', priority: 30 },
+    { pattern: /^test_.*\.py$/i, type: 'test', priority: 30 },
+];
+function matchesGlob(filename, patterns) {
+    if (patterns.length === 0)
+        return true;
+    for (const pattern of patterns) {
+        // Simple glob matching: * matches any sequence, ** matches any path
+        const regexPattern = pattern
+            .replace(/\./g, '\\.')
+            .replace(/\*\*/g, '.*')
+            .replace(/\*/g, '[^/]*');
+        const regex = new RegExp(`^${regexPattern}$`, 'i');
+        if (regex.test(filename))
+            return true;
+    }
+    return false;
+}
+function shouldExclude(relativePath, excludePatterns) {
+    if (excludePatterns.length === 0)
+        return false;
+    for (const pattern of excludePatterns) {
+        // Simple exclusion matching
+        if (relativePath.includes(pattern))
+            return true;
+        if (pattern.startsWith('*') && relativePath.endsWith(pattern.slice(1)))
+            return true;
+    }
+    return false;
+}
+export async function generateRepoTree(bundleRootDir, bundleId, options = {}) {
+    const depth = options.depth ?? 4;
+    const includePatterns = options.include ?? [];
+    const excludePatterns = options.exclude ?? ['node_modules', '.git', '__pycache__', '.venv', 'venv', 'dist', 'build', '*.pyc'];
+    const reposDir = path.join(bundleRootDir, 'repos');
+    const stats = {
+        totalFiles: 0,
+        totalDirs: 0,
+        byExtension: {},
+        byTopDir: {},
+    };
+    const entryPointCandidates = [];
+    // Build tree recursively
+    async function buildTree(dir, currentDepth, relativePath) {
+        if (currentDepth > depth)
+            return null;
+        try {
+            const stat = await fs.stat(dir);
+            const name = path.basename(dir);
+            if (stat.isFile()) {
+                // Check include/exclude patterns
+                if (includePatterns.length > 0 && !matchesGlob(name, includePatterns)) {
+                    return null;
+                }
+                if (shouldExclude(relativePath, excludePatterns)) {
+                    return null;
+                }
+                stats.totalFiles++;
+                // Track extension stats
+                const ext = path.extname(name).toLowerCase() || '(no ext)';
+                stats.byExtension[ext] = (stats.byExtension[ext] ?? 0) + 1;
+                // Track top directory stats
+                const topDir = relativePath.split('/')[0] ?? '(root)';
+                stats.byTopDir[topDir] = (stats.byTopDir[topDir] ?? 0) + 1;
+                // Check for entry point candidates
+                for (const ep of ENTRY_POINT_PATTERNS) {
+                    if (ep.pattern.test(name)) {
+                        entryPointCandidates.push({
+                            path: relativePath,
+                            type: ep.type,
+                            priority: ep.priority,
+                        });
+                        break;
+                    }
+                }
+                return { name, type: 'file', size: stat.size };
+            }
+            if (stat.isDirectory()) {
+                // Check exclude patterns for directories
+                if (shouldExclude(name, excludePatterns) || shouldExclude(relativePath, excludePatterns)) {
+                    return null;
+                }
+                stats.totalDirs++;
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                const children = [];
+                // Sort: directories first, then files, alphabetically
+                const sortedEntries = entries.sort((a, b) => {
+                    if (a.isDirectory() && !b.isDirectory())
+                        return -1;
+                    if (!a.isDirectory() && b.isDirectory())
+                        return 1;
+                    return a.name.localeCompare(b.name);
+                });
+                for (const entry of sortedEntries) {
+                    const childPath = path.join(dir, entry.name);
+                    const childRelPath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+                    const childNode = await buildTree(childPath, currentDepth + 1, childRelPath);
+                    if (childNode) {
+                        children.push(childNode);
+                    }
+                }
+                return { name, type: 'dir', children: children.length > 0 ? children : undefined };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Build tree starting from repos directory
+    let rootNode = null;
+    try {
+        await fs.access(reposDir);
+        rootNode = await buildTree(reposDir, 0, '');
+    }
+    catch {
+        // repos directory doesn't exist, try bundle root
+        rootNode = await buildTree(bundleRootDir, 0, '');
+    }
+    // Generate ASCII tree
+    function renderTree(node, prefix = '', isLast = true) {
+        const lines = [];
+        const connector = isLast ? '└── ' : '├── ';
+        const extension = isLast ? '    ' : '│   ';
+        lines.push(`${prefix}${connector}${node.name}${node.type === 'dir' ? '/' : ''}`);
+        if (node.children) {
+            const childCount = node.children.length;
+            node.children.forEach((child, index) => {
+                const childLines = renderTree(child, prefix + extension, index === childCount - 1);
+                lines.push(...childLines);
+            });
+        }
+        return lines;
+    }
+    let treeText = '';
+    if (rootNode) {
+        if (rootNode.children && rootNode.children.length > 0) {
+            treeText = `${rootNode.name}/\n`;
+            rootNode.children.forEach((child, index) => {
+                const childLines = renderTree(child, '', index === rootNode.children.length - 1);
+                treeText += childLines.join('\n') + '\n';
+            });
+        }
+        else {
+            treeText = `${rootNode.name}/ (empty or filtered out)`;
+        }
+    }
+    else {
+        treeText = '(no files found)';
+    }
+    // Sort entry point candidates by priority
+    entryPointCandidates.sort((a, b) => b.priority - a.priority);
+    return {
+        bundleId,
+        tree: treeText.trim(),
+        stats,
+        entryPointCandidates: entryPointCandidates.slice(0, 20), // Limit to top 20
+    };
+}
+/**
+ * Format tree result as human-readable text
+ */
+export function formatTreeResult(result) {
+    const lines = [];
+    lines.push(`📂 Repository Structure for bundle: ${result.bundleId}`);
+    lines.push('');
+    lines.push('## Directory Tree');
+    lines.push('```');
+    lines.push(result.tree);
+    lines.push('```');
+    lines.push('');
+    lines.push('## Statistics');
+    lines.push(`- Total files: ${result.stats.totalFiles}`);
+    lines.push(`- Total directories: ${result.stats.totalDirs}`);
+    lines.push('');
+    // By extension (top 10)
+    const extEntries = Object.entries(result.stats.byExtension)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    if (extEntries.length > 0) {
+        lines.push('### Files by Extension');
+        for (const [ext, count] of extEntries) {
+            lines.push(`- ${ext}: ${count}`);
+        }
+        lines.push('');
+    }
+    // By top directory (top 10)
+    const dirEntries = Object.entries(result.stats.byTopDir)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    if (dirEntries.length > 0) {
+        lines.push('### Files by Top Directory');
+        for (const [dir, count] of dirEntries) {
+            lines.push(`- ${dir}: ${count}`);
+        }
+        lines.push('');
+    }
+    // Entry point candidates
+    if (result.entryPointCandidates.length > 0) {
+        lines.push('## Entry Point Candidates');
+        for (const ep of result.entryPointCandidates.slice(0, 10)) {
+            lines.push(`- \`${ep.path}\` (${ep.type})`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/evidence/dependencyGraph.js

@@ -29,8 +29,17 @@ export const DependencyGraphInputSchema = {
         maxNodes: z.number().int().min(10).max(2000).default(300),
         maxEdges: z.number().int().min(10).max(5000).default(800),
         timeBudgetMs: z.number().int().min(1000).max(30_000).default(25_000),
+        /** Maximum file size in bytes. Files larger than this are skipped. Default 1MB. */
+        maxFileSizeBytes: z.number().int().min(10_000).max(50_000_000).default(1_000_000)
+            .describe('Max file size in bytes. Default 1MB. Increase if important large files are skipped.'),
+        /** Strategy for handling large files */
+        largeFileStrategy: z.enum(['skip', 'truncate']).default('skip')
+            .describe('How to handle files exceeding maxFileSizeBytes. skip=ignore entirely, truncate=read first N lines.'),
+        /** If largeFileStrategy=truncate, how many lines to read */
+        truncateLines: z.number().int().min(100).max(5000).default(500)
+            .describe('When largeFileStrategy=truncate, read this many lines. Default 500.'),
     })
-        .default({ maxFiles: 200, maxNodes: 300, maxEdges: 800, timeBudgetMs: 25_000 }),
+        .default({ maxFiles: 200, maxNodes: 300, maxEdges: 800, timeBudgetMs: 25_000, maxFileSizeBytes: 1_000_000, largeFileStrategy: 'skip', truncateLines: 500 }),
 };
 function sha256Hex(text) {
     return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
@@ -919,6 +928,35 @@ async function generateGlobalDependencyGraph(ctx) {
     let truncatedReason;
     let filesProcessed = 0;
     let usedAstCount = 0;
+    // Coverage tracking
+    const perLanguage = {};
+    const perDir = {};
+    const skippedFiles = [];
+    let scannedFilesCount = 0;
+    // Helper to get language from extension
+    const extToLang = {
+        '.ts': 'TypeScript', '.tsx': 'TypeScript',
+        '.js': 'JavaScript', '.jsx': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript',
+        '.py': 'Python',
+        '.go': 'Go',
+        '.rs': 'Rust',
+        '.java': 'Java',
+        '.rb': 'Ruby',
+        '.php': 'PHP',
+    };
+    const getLang = (filePath) => {
+        const ext = path.extname(filePath).toLowerCase();
+        return extToLang[ext] ?? 'Other';
+    };
+    const getTopDir = (filePath) => {
+        // Extract the top-level directory under repos/owner/repo/norm/
+        const parts = filePath.split('/');
+        // repos/owner/repo/norm/[topDir]/...
+        if (parts.length > 4 && parts[0] === 'repos' && parts[3] === 'norm') {
+            return parts[4] ?? '(root)';
+        }
+        return parts[0] ?? '(root)';
+    };
     // Collect all code files
     const codeExtensions = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.rb', '.php']);
     const codeFiles = [];
@@ -946,15 +984,29 @@ async function generateGlobalDependencyGraph(ctx) {
     }
     // Walk repos directory
     for await (const relPath of walkDir(paths.reposDir, 'repos')) {
+        scannedFilesCount++;
+        // Track per-directory stats
+        const topDir = getTopDir(relPath);
+        perDir[topDir] = (perDir[topDir] ?? 0) + 1;
+        // Track per-language stats
+        const lang = getLang(relPath);
+        if (!perLanguage[lang]) {
+            perLanguage[lang] = { scanned: 0, parsed: 0, edges: 0 };
+        }
+        perLanguage[lang].scanned++;
         if (codeFiles.length >= limits.maxFiles) {
             truncated = true;
             truncatedReason = 'maxFiles reached during discovery';
-            break;
+            skippedFiles.push({ path: relPath, reason: 'maxFiles limit reached' });
+            continue;
         }
         // Only include files under norm/ directories
         if (relPath.includes('/norm/')) {
             codeFiles.push(relPath);
         }
+        else {
+            skippedFiles.push({ path: relPath, reason: 'not in norm/ directory' });
+        }
     }
     warnings.push({
         code: 'global_mode',
@@ -971,15 +1023,49 @@ async function generateGlobalDependencyGraph(ctx) {
         const fileId = `file:${filePath}`;
         addNode({ id: fileId, kind: 'file', name: filePath, file: filePath });
         // Read and extract imports
+        const lang = getLang(filePath);
         try {
             const absPath = safeJoin(paths.rootDir, filePath);
-            const raw = await fs.readFile(absPath, 'utf8');
+            const stat = await fs.stat(absPath);
+            // Handle large files based on strategy
+            const maxSize = args.options.maxFileSizeBytes ?? 1_000_000;
+            const strategy = args.options.largeFileStrategy ?? 'skip';
+            const truncateLines = args.options.truncateLines ?? 500;
+            if (stat.size > maxSize) {
+                if (strategy === 'skip') {
+                    skippedFiles.push({
+                        path: filePath,
+                        size: stat.size,
+                        reason: `file too large (>${Math.round(maxSize / 1024)}KB). Use largeFileStrategy='truncate' or increase maxFileSizeBytes to include.`
+                    });
+                    continue;
+                }
+                // strategy === 'truncate': read first N lines only
+            }
+            let raw;
+            if (stat.size > maxSize && strategy === 'truncate') {
+                // Read file and take first N lines
+                const fullContent = await fs.readFile(absPath, 'utf8');
+                const allLines = fullContent.replace(/\r\n/g, '\n').split('\n');
+                raw = allLines.slice(0, truncateLines).join('\n');
+                warnings.push({
+                    code: 'file_truncated',
+                    message: `${filePath}: truncated to first ${truncateLines} lines (file size ${Math.round(stat.size / 1024)}KB exceeds ${Math.round(maxSize / 1024)}KB limit)`,
+                });
+            }
+            else {
+                raw = await fs.readFile(absPath, 'utf8');
+            }
             const normalized = raw.replace(/\r\n/g, '\n');
             const lines = normalized.split('\n');
             const extracted = await extractImportsForFile(cfg, filePath, normalized, lines, warnings);
             if (extracted.usedAst)
                 usedAstCount++;
             filesProcessed++;
+            // Track parsed count per language
+            if (perLanguage[lang]) {
+                perLanguage[lang].parsed++;
+            }
             const fileRepo = parseRepoNormPath(filePath);
             if (!fileRepo)
                 continue;
@@ -1016,11 +1102,17 @@ async function generateGlobalDependencyGraph(ctx) {
                         sources: [source],
                         notes: [...imp.notes, `resolved import "${imp.module}" to ${resolvedFile}`],
                     });
+                    // Track edges per language
+                    if (perLanguage[lang]) {
+                        perLanguage[lang].edges++;
+                    }
                 }
             }
         }
-        catch {
-            // Skip unreadable files
+        catch (err) {
+            // Track skipped files with reason
+            const reason = err instanceof Error ? err.message : 'unknown error';
+            skippedFiles.push({ path: filePath, reason: `read error: ${reason.slice(0, 100)}` });
         }
     }
     // Post-process warnings
@@ -1031,6 +1123,22 @@ async function generateGlobalDependencyGraph(ctx) {
             : 'Global graph used regex-based import extraction. Import resolution is best-effort. Only internal imports (resolved to files in the bundle) are shown.',
     });
     const importEdges = edges.filter((e) => e.type === 'imports_resolved').length;
+    // Build coverage report
+    const coverageReport = {
+        scannedFilesCount,
+        parsedFilesCount: filesProcessed,
+        perLanguage,
+        perDir,
+        skippedFiles: skippedFiles.slice(0, 50), // Limit to first 50 for output size
+        truncated,
+        truncatedReason,
+        limits: {
+            maxFiles: limits.maxFiles,
+            maxNodes: limits.maxNodes,
+            maxEdges: limits.maxEdges,
+            timeBudgetMs,
+        },
+    };
     return {
         meta: {
             requestId,
@@ -1060,6 +1168,7 @@ async function generateGlobalDependencyGraph(ctx) {
             },
             warnings,
         },
+        coverageReport,
     };
 }
 /**

package/dist/server.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import path from 'node:path';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
@@ -16,6 +17,7 @@ import { cleanupOnStartup, cleanupOrphanBundles } from './bundle/cleanup.js';
 import { startHttpServer } from './http/server.js';
 import { DependencyGraphInputSchema, generateDependencyGraph } from './evidence/dependencyGraph.js';
 import { TraceQueryInputSchema, TraceUpsertInputSchema, traceQuery, traceUpsert } from './trace/service.js';
+import { generateRepoTree, formatTreeResult } from './bundle/tree.js';
 const CreateRepoInputSchema = z.union([
     z.object({
         kind: z.literal('github'),
@@ -100,7 +102,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.2.3',
+        version: '0.2.5',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -268,41 +270,54 @@ export async function startServer() {
             '(1) Omit "file" param → returns ALL key files in one call. ' +
             '(2) Provide "file" param → returns that specific file. ' +
             'Use when: "查看bundle", "show bundle", "read overview", "bundle概览", "项目信息", "读取依赖图".\n\n' +
+            '⭐ **Evidence Citation Support:**\n' +
+            '- Use `withLineNumbers: true` to get output in `N|line` format for precise citations\n' +
+            '- Use `ranges: ["20-80", "100-120"]` to read only specific line ranges\n' +
+            '- Combine both for efficient evidence gathering: `{ file: "src/main.ts", withLineNumbers: true, ranges: ["50-100"] }`\n' +
+            '- Citation format: `repos/owner/repo/norm/src/main.ts:50-100`\n\n' +
+            '⭐ **Recommended Reading Order (AI-optimized summaries are better than raw README):**\n' +
+            '1. `OVERVIEW.md` - Project structure & architecture summary (START HERE)\n' +
+            '2. `START_HERE.md` - Key entry points & critical paths\n' +
+            '3. `AGENTS.md` - AI agent usage guide\n' +
+            '4. `analysis/FACTS.json` - Static analysis data (dependencies, exports, etc.)\n' +
+            '5. `deps/dependency-graph.json` - Import relationships (if generated)\n' +
+            '6. `repos/{owner}/{repo}/norm/README.md` - Original README (only if you need raw docs)\n\n' +
             '📁 **Bundle Structure:**\n' +
             '```\n' +
             'bundle-{id}/\n' +
-            '├── manifest.json          # Bundle metadata (JSON)\n' +
-            '├── OVERVIEW.md            # Project overview\n' +
-            '├── START_HERE.md          # Entry points guide\n' +
-            '├── AGENTS.md              # AI agent instructions\n' +
-            '├── analysis/\n' +
-            '│   └── FACTS.json         # Static analysis facts (JSON) - use this tool to read\n' +
-            '├── deps/\n' +
-            '│   └── dependency-graph.json  # Import graph (JSON) - generated by preflight_evidence_dependency_graph\n' +
-            '├── trace/\n' +
-            '│   ├── trace.sqlite3      # Trace links DB - query via preflight_trace_query\n' +
-            '│   └── trace.json         # Trace links export (JSON) - use this tool to read\n' +
-            '├── indexes/\n' +
-            '│   └── search.sqlite3     # FTS5 index - query via preflight_search_bundle\n' +
-            '└── repos/{owner}/{repo}/\n' +
-            '    ├── raw/               # Original files\n' +
-            '    └── norm/              # Normalized source code\n' +
+            '├── OVERVIEW.md            # ⭐ Start here - AI-generated project summary\n' +
+            '├── START_HERE.md          # ⭐ Entry points & key files\n' +
+            '├── AGENTS.md              # ⭐ AI agent instructions\n' +
+            '├── manifest.json          # Bundle metadata\n' +
+            '├── analysis/FACTS.json    # Static analysis facts\n' +
+            '├── deps/dependency-graph.json  # Import graph (generated on demand)\n' +
+            '├── trace/trace.json       # Trace links export (auto-generated after trace_upsert)\n' +
+            '├── indexes/search.sqlite3 # FTS5 index (use preflight_search_bundle)\n' +
+            '└── repos/{owner}/{repo}/norm/  # Source code & original README\n' +
             '```\n\n' +
-            '**File Access Methods:**\n' +
-            '- README: `repos/{owner}/{repo}/norm/README.md` - use THIS tool\n' +
-            '- JSON files (FACTS.json, dependency-graph.json, trace.json, manifest.json): Use THIS tool\n' +
-            '- SQLite DBs (search.sqlite3): Use preflight_search_bundle\n' +
-            '- SQLite DBs (trace.sqlite3): Use preflight_trace_query/preflight_trace_upsert\n' +
-            '- Source code: `repos/{owner}/{repo}/norm/{path}` - use THIS tool',
+            '**File Access:**\n' +
+            '- Omit `file` param → returns OVERVIEW + START_HERE + AGENTS + manifest (recommended)\n' +
+            '- Original README: `file: "repos/{owner}/{repo}/norm/README.md"`\n' +
+            '- Source code: `file: "repos/{owner}/{repo}/norm/{path}"`\n' +
+            '- Search code: use preflight_search_bundle instead',
         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, returns all key files including dependency graph if exists.'),
+            withLineNumbers: z.boolean().optional().default(false).describe('If true, prefix each line with line number in "N|" format for evidence citation.'),
+            ranges: z.array(z.string()).optional().describe('Line ranges to read, e.g. ["20-80", "100-120"]. Each range is "start-end" (1-indexed, inclusive). If omitted, reads entire file.'),
         },
         outputSchema: {
             bundleId: z.string(),
             file: z.string().optional(),
             content: z.string().optional(),
             files: z.record(z.string(), z.string().nullable()).optional(),
+            lineInfo: z.object({
+                totalLines: z.number(),
+                ranges: z.array(z.object({
+                    start: z.number(),
+                    end: z.number(),
+                })),
+            }).optional(),
         },
         annotations: {
             readOnlyHint: true,
@@ -315,13 +330,78 @@ export async function startServer() {
             }
             const paths = getBundlePathsForId(storageDir, args.bundleId);
             const bundleRoot = paths.rootDir;
+            // Helper: parse range string "start-end" into { start, end }
+            const parseRange = (rangeStr) => {
+                const match = rangeStr.match(/^(\d+)-(\d+)$/);
+                if (!match)
+                    return null;
+                const start = parseInt(match[1], 10);
+                const end = parseInt(match[2], 10);
+                if (start < 1 || end < start)
+                    return null;
+                return { start, end };
+            };
+            // Helper: format content with optional line numbers and ranges
+            const formatContent = (rawContent, withLineNumbers, ranges) => {
+                const lines = rawContent.replace(/\r\n/g, '\n').split('\n');
+                const totalLines = lines.length;
+                let selectedLines = [];
+                if (ranges && ranges.length > 0) {
+                    // Extract specified ranges
+                    for (const range of ranges) {
+                        const start = Math.max(1, range.start);
+                        const end = Math.min(totalLines, range.end);
+                        for (let i = start; i <= end; i++) {
+                            selectedLines.push({ lineNo: i, text: lines[i - 1] ?? '' });
+                        }
+                    }
+                }
+                else {
+                    // All lines
+                    selectedLines = lines.map((text, idx) => ({ lineNo: idx + 1, text }));
+                }
+                // Format output
+                const formatted = withLineNumbers
+                    ? selectedLines.map((l) => `${l.lineNo}|${l.text}`).join('\n')
+                    : selectedLines.map((l) => l.text).join('\n');
+                const actualRanges = ranges && ranges.length > 0
+                    ? ranges.map((r) => ({ start: Math.max(1, r.start), end: Math.min(totalLines, r.end) }))
+                    : [{ start: 1, end: totalLines }];
+                return { content: formatted, lineInfo: { totalLines, ranges: actualRanges } };
+            };
             // Single file mode
             if (args.file) {
                 const absPath = safeJoin(bundleRoot, args.file);
-                const content = await fs.readFile(absPath, 'utf8');
-                const out = { bundleId: args.bundleId, file: args.file, content };
+                const rawContent = await fs.readFile(absPath, 'utf8');
+                // Parse ranges if provided
+                let parsedRanges;
+                if (args.ranges && args.ranges.length > 0) {
+                    parsedRanges = [];
+                    for (const rangeStr of args.ranges) {
+                        const parsed = parseRange(rangeStr);
+                        if (!parsed) {
+                            throw new Error(`Invalid range format: "${rangeStr}". Expected "start-end" (e.g., "20-80").`);
+                        }
+                        parsedRanges.push(parsed);
+                    }
+                    // Sort and merge overlapping ranges
+                    parsedRanges.sort((a, b) => a.start - b.start);
+                }
+                const { content, lineInfo } = formatContent(rawContent, args.withLineNumbers ?? false, parsedRanges);
+                const out = {
+                    bundleId: args.bundleId,
+                    file: args.file,
+                    content,
+                    lineInfo,
+                };
+                // Build text with citation hint
+                let textOutput = content;
+                if (parsedRanges && parsedRanges.length > 0) {
+                    const rangeStr = parsedRanges.map((r) => `${r.start}-${r.end}`).join(', ');
+                    textOutput = `[${args.file}:${rangeStr}] (${lineInfo.totalLines} total lines)\n\n${content}`;
+                }
                 return {
-                    content: [{ type: 'text', text: content }],
+                    content: [{ type: 'text', text: textOutput }],
                     structuredContent: out,
                 };
             }
@@ -380,6 +460,67 @@ export async function startServer() {
             throw wrapPreflightError(err);
         }
     });
+    server.registerTool('preflight_repo_tree', {
+        title: 'Repository tree & statistics',
+        description: 'Get repository structure overview with directory tree, file statistics, and entry point candidates. ' +
+            'Use this BEFORE deep analysis to understand project layout without wasting tokens on search. ' +
+            'Use when: "show project structure", "what files are in this repo", "项目结构", "文件分布", "show tree".\n\n' +
+            '**Output includes:**\n' +
+            '- ASCII directory tree (depth-limited)\n' +
+            '- File count by extension (.ts, .py, etc.)\n' +
+            '- File count by top-level directory\n' +
+            '- Entry point candidates (README, main, index, cli, server, etc.)\n\n' +
+            '**Recommended workflow:**\n' +
+            '1. Call preflight_repo_tree to understand structure\n' +
+            '2. Read OVERVIEW.md for AI-generated summary\n' +
+            '3. Use preflight_search_bundle to find specific code\n' +
+            '4. Use preflight_read_file with ranges for evidence gathering',
+        inputSchema: {
+            bundleId: z.string().describe('Bundle ID to analyze.'),
+            depth: z.number().int().min(1).max(10).default(4).describe('Maximum directory depth to traverse. Default 4.'),
+            include: z.array(z.string()).optional().describe('Glob patterns to include (e.g., ["*.ts", "*.py"]). If omitted, includes all files.'),
+            exclude: z.array(z.string()).optional().describe('Patterns to exclude (e.g., ["node_modules", "*.pyc"]). Defaults include common excludes.'),
+        },
+        outputSchema: {
+            bundleId: z.string(),
+            tree: z.string().describe('ASCII directory tree representation.'),
+            stats: z.object({
+                totalFiles: z.number(),
+                totalDirs: z.number(),
+                byExtension: z.record(z.string(), z.number()),
+                byTopDir: z.record(z.string(), z.number()),
+            }),
+            entryPointCandidates: z.array(z.object({
+                path: z.string(),
+                type: z.enum(['readme', 'main', 'index', 'cli', 'server', 'app', 'test', 'config']),
+                priority: z.number(),
+            })),
+        },
+        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 result = await generateRepoTree(paths.rootDir, args.bundleId, {
+                depth: args.depth,
+                include: args.include,
+                exclude: args.exclude,
+            });
+            const textOutput = formatTreeResult(result);
+            return {
+                content: [{ type: 'text', text: textOutput }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
+    });
     server.registerTool('preflight_delete_bundle', {
         title: 'Delete bundle',
         description: 'Delete/remove a bundle permanently. Use when: "delete bundle", "remove bundle", "清除bundle", "删除索引", "移除仓库".',
@@ -832,12 +973,50 @@ export async function startServer() {
             'Generate an evidence-based dependency graph. IMPORTANT: Before running, ASK the user which bundle and which file/mode they want! ' +
             '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}.',
+            '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',
         inputSchema: DependencyGraphInputSchema,
         outputSchema: {
             meta: z.any(),
             facts: z.any(),
             signals: z.any(),
+            coverageReport: z.object({
+                scannedFilesCount: z.number(),
+                parsedFilesCount: z.number(),
+                perLanguage: z.record(z.string(), z.object({
+                    scanned: z.number(),
+                    parsed: z.number(),
+                    edges: z.number(),
+                })),
+                perDir: z.record(z.string(), z.number()),
+                skippedFiles: z.array(z.object({
+                    path: z.string(),
+                    size: z.number().optional(),
+                    reason: z.string(),
+                })),
+                truncated: z.boolean(),
+                truncatedReason: z.string().optional(),
+                limits: z.object({
+                    maxFiles: z.number(),
+                    maxNodes: z.number(),
+                    maxEdges: z.number(),
+                    timeBudgetMs: z.number(),
+                }),
+            }).optional().describe('Coverage report explaining what was analyzed and what was skipped (global mode only).'),
         },
         annotations: {
             readOnlyHint: true,
@@ -861,9 +1040,21 @@ export async function startServer() {
         description: 'Create or update traceability links (code↔test, code↔doc, file↔requirement). ' +
             '**Proactive use recommended**: When you discover relationships during code analysis ' +
             '(e.g., "this file has a corresponding test", "this module implements feature X"), ' +
-            'automatically create trace links to record these findings for future queries. ' +
-            'Common link types: tested_by, implements, documents, relates_to, depends_on. ' +
-            'Stores trace edges in a per-bundle SQLite database.',
+            'automatically create trace links to record these findings for future queries.\n\n' +
+            '📌 **When to Write Trace Links (LLM Rules):**\n' +
+            'Write trace links ONLY for these 3 high-value relationship types:\n' +
+            '1. **Entry ↔ Core module** (entrypoint_of): Main entry points and their critical paths\n' +
+            '2. **Implementation ↔ Test** (tested_by): Code files and their corresponding tests\n' +
+            '3. **Code ↔ Documentation** (documents/implements): Code implementing specs or documented in files\n\n' +
+            '⚠️ **Required Evidence:**\n' +
+            '- sources: Array of evidence with file path + line range or note\n' +
+            '- method: "exact" (parser-verified) or "heuristic" (name-based)\n' +
+            '- confidence: 0.0-1.0 (use 0.9 for exact matches, 0.6-0.8 for heuristics)\n\n' +
+            '❌ **Do NOT write:**\n' +
+            '- Pure import relationships (use dependency_graph instead)\n' +
+            '- Low-value or obvious relationships\n\n' +
+            '**Standard edge_types:** tested_by, documents, implements, relates_to, entrypoint_of, depends_on\n\n' +
+            '📤 **Auto-export:** trace.json is automatically exported to trace/trace.json after each upsert for LLM direct reading.',
         inputSchema: TraceUpsertInputSchema,
         outputSchema: {
             bundleId: z.string(),
@@ -911,6 +1102,10 @@ export async function startServer() {
                 updatedAt: z.string(),
                 bundleId: z.string().optional(),
             })),
+            reason: z.enum(['no_edges', 'no_matching_edges', 'not_initialized', 'no_matching_bundle']).optional()
+                .describe('Reason for empty results. no_edges=no trace links exist across bundles, no_matching_edges=links exist but none match query, not_initialized=trace DB empty for this bundle, no_matching_bundle=no bundles found.'),
+            nextSteps: z.array(z.string()).optional()
+                .describe('Actionable guidance when edges is empty.'),
         },
         annotations: {
             readOnlyHint: true,
@@ -922,8 +1117,60 @@ export async function startServer() {
                 await assertBundleComplete(cfg, args.bundleId);
             }
             const out = await traceQuery(cfg, args);
+            // Build human-readable text output
+            let textOutput;
+            if (out.edges.length === 0 && out.reason) {
+                textOutput = `No trace links found.\nReason: ${out.reason}\n\nNext steps:\n${(out.nextSteps ?? []).map(s => `- ${s}`).join('\n')}`;
+            }
+            else {
+                textOutput = JSON.stringify(out, null, 2);
+            }
             return {
-                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+                content: [{ type: 'text', text: textOutput }],
+                structuredContent: out,
+            };
+        }
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
+    });
+    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".',
+        inputSchema: {
+            bundleId: z.string().describe('Bundle ID to export trace links from.'),
+        },
+        outputSchema: {
+            bundleId: z.string(),
+            exported: z.number().int().describe('Number of edges exported.'),
+            jsonPath: z.string().describe('Bundle-relative path to the exported JSON file.'),
+        },
+        annotations: {
+            readOnlyHint: false,
+        },
+    }, async (args) => {
+        try {
+            await assertBundleComplete(cfg, args.bundleId);
+            const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
+            if (!storageDir) {
+                throw new BundleNotFoundError(args.bundleId);
+            }
+            const paths = getBundlePathsForId(storageDir, args.bundleId);
+            const traceDbPath = path.join(paths.rootDir, 'trace', 'trace.sqlite3');
+            // Import and call exportTraceToJson
+            const { exportTraceToJson } = await import('./trace/store.js');
+            const result = await exportTraceToJson(traceDbPath);
+            // Convert absolute path to bundle-relative path
+            const jsonRelPath = 'trace/trace.json';
+            const out = {
+                bundleId: args.bundleId,
+                exported: result.exported,
+                jsonPath: jsonRelPath,
+            };
+            return {
+                content: [{ type: 'text', text: `Exported ${result.exported} trace edge(s) to ${jsonRelPath}` }],
                 structuredContent: out,
             };
         }

package/dist/trace/service.js

@@ -70,6 +70,28 @@ export async function traceQuery(cfg, rawArgs) {
     if (args.bundleId) {
         const dbPath = await getTraceDbPathForBundleId(cfg, args.bundleId);
         const rows = queryTraceEdges(dbPath, { source, target, edgeType: args.edge_type, limit: args.limit });
+        // Add reason and nextSteps for empty results
+        if (rows.length === 0) {
+            // Check if trace DB has any edges at all
+            const allEdges = queryTraceEdges(dbPath, { limit: 1 });
+            const hasAnyEdges = allEdges.length > 0;
+            return {
+                bundleId: args.bundleId,
+                edges: [],
+                reason: hasAnyEdges ? 'no_matching_edges' : 'not_initialized',
+                nextSteps: hasAnyEdges
+                    ? [
+                        'Try a different source_type/source_id combination',
+                        'Use preflight_search_bundle to find related files first',
+                        'Check if the file path uses bundle-relative format: repos/{owner}/{repo}/norm/{path}',
+                    ]
+                    : [
+                        'Use preflight_trace_upsert to create trace links',
+                        'Trace links record relationships: code↔test (tested_by), code↔doc (documents), module↔requirement (implements)',
+                        'Example: { edges: [{ type: "tested_by", source: { type: "file", id: "repos/.../src/main.ts" }, target: { type: "file", id: "repos/.../tests/main.test.ts" }, method: "exact", confidence: 0.9 }] }',
+                    ],
+            };
+        }
         return { bundleId: args.bundleId, edges: rows };
     }
     // Slow path: scan across bundles (best-effort, capped)
@@ -100,9 +122,23 @@ export async function traceQuery(cfg, rawArgs) {
     }
     // Sort by updatedAt desc across bundles
     collected.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
-    return {
+    const result = {
         scannedBundles: bundleIds.length,
         truncated: truncated ? true : undefined,
         edges: collected.slice(0, args.limit),
     };
+    // Add reason and nextSteps for empty results
+    if (collected.length === 0) {
+        result.reason = bundleIds.length === 0 ? 'no_matching_bundle' : 'no_edges';
+        result.nextSteps = bundleIds.length === 0
+            ? [
+                'No bundles found. Create a bundle first using preflight_create_bundle.',
+            ]
+            : [
+                'No trace links found across any bundle.',
+                'Use preflight_trace_upsert with a specific bundleId to create trace links.',
+                'Trace links record relationships: code↔test (tested_by), code↔doc (documents), module↔requirement (implements)',
+            ];
+    }
+    return result;
 }

package/package.json

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