preflight-mcp 0.2.5 → 0.3.0

package/README.md

@@ -3,47 +3,81 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
+[![npm version](https://img.shields.io/npm/v/preflight-mcp)](https://www.npmjs.com/package/preflight-mcp)
 
 > **English** | [中文](./README.zh-CN.md)
 
-An MCP (Model Context Protocol) **stdio** server that creates evidence-based preflight bundles for GitHub repositories and library documentation.
-
-Each bundle contains:
-- A local copy of repo docs + code (normalized text)
-- A lightweight **full-text search index** (SQLite FTS5)
-- Agent-facing entry files: `START_HERE.md`, `AGENTS.md`, and `OVERVIEW.md` (factual-only, with evidence pointers)
-
-## Features
-
-- **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
-- **Auto-export trace.json**: Trace links are automatically exported to JSON for direct LLM reading (no API needed)
-- **Progress tracking**: Real-time progress reporting for long-running operations (create/update bundles)
-- **Bundle integrity check**: Prevents operations on incomplete bundles with helpful error messages
-- **De-duplication with in-progress lock**: Prevent duplicate bundle creation even during MCP timeouts
-- **Global dependency graph**: Generate project-wide import relationship graphs
-- **Batch file reading**: Read all key bundle files in a single call
-- **Resilient GitHub fetching**: configurable git clone timeout + GitHub archive (zipball) fallback
-- **Offline repair**: rebuild missing/empty derived artifacts (index/guides/overview) without re-fetching
-- **Static facts extraction** via `analysis/FACTS.json` (non-LLM)
-- **Resources** to read bundle files via `preflight://...` URIs
-- **Multi-path mirror backup** for cloud storage redundancy
-- **Resilient storage** with automatic failover when mounts are unavailable
-- **Atomic bundle creation** with crash-safety and zero orphans
-- **Fast background deletion** with 100-300x performance improvement
-- **Auto-cleanup** on startup for historical orphan bundles
+**Give your AI assistant deep knowledge of any codebase — in seconds.**
+
+Preflight-MCP creates searchable, indexed knowledge bundles from GitHub repos, so Claude/GPT/Cursor can understand your project structure, find relevant code, and trace dependencies — without copy-pasting or token limits.
+
+## Why Preflight?
+
+| Problem | Preflight Solution |
+|---------|--------------------|
+| 🤯 AI forgets your codebase context | Persistent, searchable bundles |
+| 📋 Copy-pasting code into chat | One command: `"index this repo"` |
+| 🔍 AI can't find related files | Full-text search + dependency graph |
+| 🧩 Lost in large projects | Auto-generated `START_HERE.md` & `OVERVIEW.md` |
+| 🔗 No idea what tests cover what | Trace links: code↔test↔doc |
+
+## Demo
+
+```
+You: "Create a bundle for the repository facebook/react"
+
+Preflight: ✅ Cloned, indexed 2,847 files, generated overview
+
+You: "Search for 'useState' implementation"
+
+Preflight: 📍 Found 23 matches:
+  → packages/react/src/ReactHooks.js:24
+  → packages/react-reconciler/src/ReactFiberHooks.js:1042
+  ...
+
+You: "Show me what tests cover useState"
+
+Preflight: 🔗 Trace links:
+  → ReactHooks.js tested_by ReactHooksTest.js
+  ...
+```
+
+## Core Features
+
+- 🚀 **One-command indexing** — `"index owner/repo"` creates a complete knowledge bundle
+- 🔍 **Full-text search** — SQLite FTS5 search across all code and docs
+- 🗺️ **Dependency graph** — Visualize imports and file relationships
+- 🔗 **Trace links** — Track code↔test↔doc relationships
+- 📖 **Auto-generated guides** — `START_HERE.md`, `AGENTS.md`, `OVERVIEW.md`
+- ☁️ **Cloud sync** — Multi-path mirror backup for redundancy
+- ⚡ **15 MCP tools + 5 prompts** — Complete toolkit for code exploration
+
+<details>
+<summary><b>All Features (click to expand)</b></summary>
+
+- **Progress tracking**: Real-time progress for long-running operations
+- **Bundle integrity check**: Prevents operations on incomplete bundles
+- **De-duplication**: Prevent duplicate bundle creation even during timeouts
+- **Resilient GitHub fetching**: Git clone timeout + archive fallback
+- **Offline repair**: Rebuild derived artifacts without re-fetching
+- **Static facts extraction**: `analysis/FACTS.json` (non-LLM)
+- **Resources**: Read bundle files via `preflight://...` URIs
+- **Atomic operations**: Crash-safety with zero orphans
+- **Fast deletion**: 100-300x performance improvement
+- **Auto-cleanup**: Removes orphan bundles on startup
+
+</details>
 
 ## Table of Contents
 
-- [Requirements](#requirements)
-- [Installation](#installation)
+- [Why Preflight?](#why-preflight)
+- [Demo](#demo)
+- [Core Features](#core-features)
 - [Quick Start](#quick-start)
-- [Tools](#tools-12-total)
+- [Tools](#tools-15-total)
+- [Prompts](#prompts-5-total)
 - [Environment Variables](#environment-variables)
 - [Contributing](#contributing)
-- [License](#license)
 
 ## Requirements
 
@@ -191,6 +225,8 @@ 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.
 
+**Deprecated parameters** (v0.2.7+): `ensureFresh`, `autoRepairIndex`, `maxAgeHours` are deprecated and will return warnings instead of errors. Use separate update/repair tools.
+
 ### `preflight_search_by_tags`
 Search across multiple bundles filtered by tags (line-based SQLite FTS5).
 - Triggers: "search in MCP bundles", "在MCP项目中搜索", "搜索所有agent"
@@ -206,11 +242,23 @@ Optional parameters:
 
 ### `preflight_evidence_dependency_graph`
 Generate an evidence-based dependency graph. Two modes:
-- **Target mode** (provide `target.file`): Analyze a specific file's imports and callers
+- **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.
-- Emits `imports` edges (file → module) and `imports_resolved` edges (file → internal file).
+
+**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)
+
+**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_trace_upsert`
 Create or update traceability links (code↔test, code↔doc, file↔requirement).

package/README.zh-CN.md

@@ -3,41 +3,81 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
+[![npm version](https://img.shields.io/npm/v/preflight-mcp)](https://www.npmjs.com/package/preflight-mcp)
 
 > [English](./README.md) | **中文**
 
-一个 MCP (Model Context Protocol) **stdio** 服务器，用于为 GitHub 仓库与库文档生成"基于证据"的 preflight bundles。
-
-每个 bundle 包含：
-- 仓库文档 + 代码的本地副本（规范化文本）
-- 轻量级 **全文搜索索引**（SQLite FTS5）
-- 面向 Agent 的入口文件：`START_HERE.md`、`AGENTS.md`、`OVERVIEW.md`（仅事实，带证据指针）
-
-## Features
-
-- **15 个 MCP 工具**：create/update/repair/search/evidence/trace/read/cleanup（外加 resources）
-- **5 个 MCP prompts**：交互式引导（菜单、分析指南、搜索指南、管理指南、追溯指南）
-- **去重**：避免对相同的规范化输入重复索引
-- **可靠的 GitHub 获取**：可配置 git clone 超时 + GitHub archive（zipball）兜底
-- **离线修复**：无需重新抓取，重建缺失/为空的派生物（index/guides/overview）
-- **静态事实提取**：生成 `analysis/FACTS.json`（非 LLM）
-- **Resources**：通过 `preflight://...` URI 读取 bundle 文件
-- **多路径镜像备份**：云存储冗余
-- **弹性存储**：挂载点不可用时自动故障转移
-- **原子创建 + 零孤儿**：临时目录 + 原子重命名，崩溃安全
-- **后台快速删除**：<100ms 响应，实际删除在后台进行
-- **启动自动清理**：历史孤儿目录自动清理（非阻塞）
-
-## Table of Contents
-
-- [Requirements](#requirements)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [Tools](#tools-12-total)
-- [Environment Variables](#environment-variables)
-- [Contributing](#contributing)
-- [License](#license)
+**让你的 AI 助手秒懂任何代码仓库。**
+
+Preflight-MCP 为 GitHub 仓库创建可搜索的知识库，让 Claude/GPT/Cursor 理解你的项目结构、快速定位代码、追踪依赖关系 —— 无需复制粘贴，不受 token 限制。
+
+## 为什么需要 Preflight？
+
+| 痛点 | Preflight 解决方案 |
+|------|--------------------|
+| 🤯 AI 记不住你的代码库 | 持久化、可搜索的知识包 |
+| 📋 反复复制粘贴代码 | 一句话：「索引这个仓库」 |
+| 🔍 AI 找不到相关文件 | 全文搜索 + 依赖图 |
+| 🧩 大项目里迷失方向 | 自动生成 `START_HERE.md` 和 `OVERVIEW.md` |
+| 🔗 不知道哪些测试覆盖哪些代码 | 追溯链接：代码↔测试↔文档 |
+
+## 效果演示
+
+```
+你：「为 facebook/react 创建 bundle」
+
+Preflight：✅ 已克隆，索引了 2,847 个文件，生成概览完成
+
+你：「搜索 useState 的实现」
+
+Preflight：📍 找到 23 处匹配：
+  → packages/react/src/ReactHooks.js:24
+  → packages/react-reconciler/src/ReactFiberHooks.js:1042
+  ...
+
+你：「哪些测试覆盖了 useState」
+
+Preflight：🔗 追溯链接：
+  → ReactHooks.js tested_by ReactHooksTest.js
+  ...
+```
+
+## 核心功能
+
+- 🚀 **一句话索引** — 「索引 owner/repo」即可创建完整知识包
+- 🔍 **全文搜索** — SQLite FTS5 搜索全部代码和文档
+- 🗺️ **依赖图** — 可视化 import 关系和文件依赖
+- 🔗 **追溯链接** — 追踪代码↔测试↔文档关系
+- 📖 **自动生成指南** — `START_HERE.md`、`AGENTS.md`、`OVERVIEW.md`
+- ☁️ **云端同步** — 多路径镜像备份
+- ⚡ **15 个 MCP 工具 + 5 个 prompts** — 完整的代码探索工具集
+
+<details>
+<summary><b>全部功能（点击展开）</b></summary>
+
+- **进度追踪**：长时间操作的实时进度显示
+- **Bundle 完整性检查**：防止对不完整 bundle 进行操作
+- **去重机制**：即使超时也能防止重复创建
+- **可靠的 GitHub 抓取**：git clone 超时 + archive 兜底
+- **离线修复**：无需重新抓取即可重建派生文件
+- **静态事实提取**：`analysis/FACTS.json`（非 LLM）
+- **Resources**：通过 `preflight://...` URI 读取文件
+- **原子操作**：崩溃安全，零孤儿目录
+- **快速删除**：100-300 倍性能提升
+- **自动清理**：启动时自动清理孤儿 bundle
+
+</details>
+
+## 目录
+
+- [为什么需要 Preflight](#为什么需要-preflight)
+- [效果演示](#效果演示)
+- [核心功能](#核心功能)
+- [快速开始](#quick-start)
+- [工具](#tools-15-total)
+- [Prompts](#prompts-5-total)
+- [环境变量](#environment-variables)
+- [贡献指南](#contributing)
 
 ## Requirements
 
@@ -203,10 +243,11 @@ npm run smoke
 - 触发词：「搜索bundle」「在仓库中查找」「搜代码」
 
 重要：**此工具是严格只读的**。
-- `ensureFresh` / `maxAgeHours` 已**弃用**，提供时会报错
 - 更新：先调用 `preflight_update_bundle`，再搜索
 - 修复：先调用 `preflight_repair_bundle`，再搜索
 
+**已弃用参数**（v0.2.7+）：`ensureFresh`、`autoRepairIndex`、`maxAgeHours` 已弃用，使用时会返回警告（不再报错）。请使用单独的 update/repair 工具。
+
 ### `preflight_search_by_tags`
 跨多个 bundle 按标签过滤搜索（基于行的 SQLite FTS5）。
 - 触发词：「search in MCP bundles」「search in all bundles」「在MCP项目中搜索」「搜索所有agent」
@@ -221,10 +262,22 @@ npm run smoke
 - `limit`：跨所有 bundle 的最大命中数
 
 ### `preflight_evidence_dependency_graph`
-生成目标文件/符号的「基于证据」的依赖图（imports + callers）。
+生成目标文件/符号的「基于证据」的依赖图（imports + references）。
 - 输出确定性（best-effort），并为每条边提供可追溯 source range
 - `PREFLIGHT_AST_ENGINE=wasm` 时使用 Tree-sitter；否则回退到正则抽取
-- 既输出 `imports`（file → module），也会在可解析时输出 `imports_resolved`（file → file）
+
+**边类型**（v0.2.7+）：
+- `edgeTypes: "imports"`（默认）：仅返回基于 AST 的 import 边（高置信度，推荐）
+- `edgeTypes: "all"`：包含基于 FTS 的 reference 边（名称匹配，可能有误报）
+
+**缓存透明化**（v0.2.7+）：
+- 响应包含 `meta.cacheInfo`：`fromCache`、`generatedAt`、`cacheAgeMs`
+- 使用 `force: true` 可重新生成缓存的全局图
+
+**大文件处理**：
+- `options.maxFileSizeBytes`（默认：1MB）：跳过超过此大小的文件
+- `options.largeFileStrategy`：`"skip"`（默认）或 `"truncate"`
+- `options.excludeExtensions`：从 reference 搜索中排除非代码文件（默认：`.json`、`.md`、`.txt`、`.yml` 等）
 
 ### `preflight_trace_upsert`
 写入/更新 bundle 级 traceability links（commit↔ticket、symbol↔test、code↔doc 等）。

package/dist/evidence/dependencyGraph.js

@@ -23,6 +23,10 @@ export const DependencyGraphInputSchema = {
         'Global mode shows import relationships between all files but may be truncated for large projects.'),
     force: z.boolean().default(false).describe('If true, regenerate the dependency graph even if cached. ' +
         'Global mode results are cached in the bundle; use force=true to refresh.'),
+    /** Edge types to include in the result. Default: only imports (AST-based, high confidence). */
+    edgeTypes: z.enum(['imports', 'all']).default('imports').describe('Edge types to include. "imports": only AST-based import edges (high confidence, recommended). ' +
+        '"all": include FTS-based reference edges (name matching, may have false positives). ' +
+        'Default: "imports" for accuracy. Use "all" only when you need to find callers/references.'),
     options: z
         .object({
         maxFiles: z.number().int().min(1).max(500).default(200),
@@ -38,8 +42,11 @@ export const DependencyGraphInputSchema = {
         /** 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.'),
+        /** File extensions to exclude from reference search (FTS). Helps reduce false positives. */
+        excludeExtensions: z.array(z.string()).default(['.json', '.md', '.txt', '.yml', '.yaml', '.toml', '.lock'])
+            .describe('File extensions to exclude from reference/caller search. Default excludes non-code files.'),
     })
-        .default({ maxFiles: 200, maxNodes: 300, maxEdges: 800, timeBudgetMs: 25_000, maxFileSizeBytes: 1_000_000, largeFileStrategy: 'skip', truncateLines: 500 }),
+        .default({ maxFiles: 200, maxNodes: 300, maxEdges: 800, timeBudgetMs: 25_000, maxFileSizeBytes: 1_000_000, largeFileStrategy: 'skip', truncateLines: 500, excludeExtensions: ['.json', '.md', '.txt', '.yml', '.yaml', '.toml', '.lock'] }),
 };
 function sha256Hex(text) {
     return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
@@ -217,11 +224,20 @@ export async function generateDependencyGraph(cfg, rawArgs) {
         try {
             const cached = await fs.readFile(paths.depsGraphPath, 'utf8');
             const parsed = JSON.parse(cached);
+            const cachedAt = parsed.meta.generatedAt ? new Date(parsed.meta.generatedAt).getTime() : 0;
+            const cacheAgeMs = cachedAt ? Date.now() - cachedAt : 0;
+            // Add cacheInfo to meta
+            parsed.meta.cacheInfo = {
+                fromCache: true,
+                generatedAt: parsed.meta.generatedAt,
+                cacheAgeMs,
+                hint: 'Use force=true to regenerate the graph.',
+            };
             // Add note that this is from cache
             parsed.signals.warnings = parsed.signals.warnings || [];
             parsed.signals.warnings.unshift({
                 code: 'from_cache',
-                message: `Loaded from cache (generated at ${parsed.meta.generatedAt}). Use force=true to regenerate.`,
+                message: `Loaded from cache (generated at ${parsed.meta.generatedAt}, age: ${Math.round(cacheAgeMs / 1000)}s). Use force=true to regenerate.`,
             });
             return parsed;
         }
@@ -777,26 +793,32 @@ export async function generateDependencyGraph(cfg, rawArgs) {
             message: `Failed to read target file for import extraction: ${err instanceof Error ? err.message : String(err)}`,
         });
     }
-    // 2) Upstream: find callers via FTS hits
+    // 2) Upstream: find references via FTS hits (only if edgeTypes='all')
     let searchHits = 0;
     let filesRead = 0;
-    let callEdges = 0;
+    let referenceEdges = 0;
     let importEdges = edges.filter((e) => e.type === 'imports').length;
-    if (targetSymbol && targetSymbol.length >= 2) {
+    const includeReferences = args.edgeTypes === 'all';
+    const excludeExtensions = new Set(args.options.excludeExtensions ?? ['.json', '.md', '.txt', '.yml', '.yaml', '.toml', '.lock']);
+    if (includeReferences && targetSymbol && targetSymbol.length >= 2) {
         const maxHits = Math.min(500, limits.maxFiles * 5);
         const hits = searchIndex(paths.searchDbPath, targetSymbol, 'code', maxHits, paths.rootDir);
         searchHits = hits.length;
         const fileLineCache = new Map();
         for (const hit of hits) {
-            if (checkBudget('timeBudget exceeded during caller scan'))
+            if (checkBudget('timeBudget exceeded during reference scan'))
                 break;
             if (edges.length >= limits.maxEdges)
                 break;
             const hitPath = hit.path;
             if (!hitPath || hit.kind !== 'code')
                 continue;
+            // P3: Filter out non-code files by extension
+            const hitExt = path.extname(hitPath).toLowerCase();
+            if (excludeExtensions.has(hitExt))
+                continue;
             // Skip obvious self-reference in the same file if no symbol boundary detection.
-            // We still allow calls within the same file (but avoid exploding edges).
+            // We still allow references within the same file (but avoid exploding edges).
             // Read file lines (cache)
             let lines = fileLineCache.get(hitPath);
             if (!lines) {
@@ -845,19 +867,19 @@ export async function generateDependencyGraph(cfg, rawArgs) {
                 snippet: clampSnippet(line, 200),
             };
             src.snippetSha256 = sha256Hex(src.snippet ?? '');
-            const evidenceId = makeEvidenceId(['calls', callerId, targetSymbolId, hitPath, String(hit.lineNo), String(call.startCol)]);
+            const evidenceId = makeEvidenceId(['references', callerId, targetSymbolId, hitPath, String(hit.lineNo), String(call.startCol)]);
             addEdge({
                 evidenceId,
                 kind: 'edge',
-                type: 'calls',
+                type: 'references',
                 from: callerId,
                 to: targetSymbolId,
                 method: 'heuristic',
-                confidence: 0.6,
+                confidence: 0.5,
                 sources: [src],
-                notes: ['call edge is name-based (no type/overload resolution)'],
+                notes: ['reference edge is FTS name-based (may include false positives from comments/strings/docs)'],
             });
-            callEdges++;
+            referenceEdges++;
             if (nodes.size >= limits.maxNodes) {
                 truncated = true;
                 truncatedReason = 'maxNodes reached';
@@ -871,21 +893,27 @@ export async function generateDependencyGraph(cfg, rawArgs) {
             });
         }
     }
+    else if (!includeReferences && targetSymbol && targetSymbol.length >= 2) {
+        warnings.push({
+            code: 'references_skipped',
+            message: 'Reference/caller search was skipped (edgeTypes="imports"). Use edgeTypes="all" to include FTS-based reference edges (may have false positives).',
+        });
+    }
     else {
         warnings.push({
             code: 'symbol_missing_or_too_short',
-            message: 'No symbol provided (or symbol too short). Upstream call graph was skipped; only imports were extracted from the target file.',
+            message: 'No symbol provided (or symbol too short). Reference graph was skipped; only imports were extracted from the target file.',
         });
     }
     // Post-process warnings
     warnings.push({
         code: 'limitations',
         message: usedAstForImports
-            ? 'This dependency graph uses deterministic parsing for imports (Tree-sitter WASM syntax AST) plus heuristics for callers (FTS + name-based). Results may be incomplete and are not type-resolved. Each edge includes method/confidence/sources for auditability.'
-            : 'This dependency graph is generated with deterministic heuristics (FTS + regex). Calls/imports may be incomplete and are not type-resolved. Each edge includes method/confidence/sources for auditability.',
+            ? 'This dependency graph uses deterministic parsing for imports (Tree-sitter WASM syntax AST). Reference edges (if enabled) use FTS + name-based heuristics and may have false positives. Each edge includes method/confidence/sources for auditability.'
+            : 'This dependency graph uses regex-based import extraction. Reference edges (if enabled) use FTS + name-based heuristics. Each edge includes method/confidence/sources for auditability.',
     });
     // Stats
-    importEdges = edges.filter((e) => e.type === 'imports').length;
+    importEdges = edges.filter((e) => e.type === 'imports' || e.type === 'imports_resolved').length;
     const out = {
         meta: {
             requestId,
@@ -901,6 +929,9 @@ export async function generateDependencyGraph(cfg, rawArgs) {
                 truncatedReason,
                 limits,
             },
+            cacheInfo: {
+                fromCache: false,
+            },
         },
         facts: {
             nodes: Array.from(nodes.values()),
@@ -910,7 +941,8 @@ export async function generateDependencyGraph(cfg, rawArgs) {
             stats: {
                 filesRead,
                 searchHits,
-                callEdges,
+                callEdges: referenceEdges, // deprecated, use referenceEdges
+                referenceEdges,
                 importEdges,
             },
             warnings,
@@ -1154,6 +1186,9 @@ async function generateGlobalDependencyGraph(ctx) {
                 truncatedReason,
                 limits,
             },
+            cacheInfo: {
+                fromCache: false,
+            },
         },
         facts: {
             nodes: Array.from(nodes.values()),
@@ -1163,7 +1198,8 @@ async function generateGlobalDependencyGraph(ctx) {
             stats: {
                 filesRead: filesProcessed,
                 searchHits: 0,
-                callEdges: 0,
+                callEdges: 0, // deprecated
+                referenceEdges: 0,
                 importEdges,
             },
             warnings,

package/dist/mcp/responseMeta.js

@@ -0,0 +1,100 @@
+/**
+ * Unified response metadata for all Preflight MCP tools.
+ * Provides routing signals for LLM cost-minimization and self-healing.
+ */
+import crypto from 'node:crypto';
+/**
+ * Generate a unique request ID.
+ */
+export function generateRequestId() {
+    return `req_${crypto.randomBytes(8).toString('hex')}`;
+}
+/**
+ * Create a ResponseMeta builder for tracking execution.
+ */
+export function createMetaBuilder() {
+    const requestId = generateRequestId();
+    const startTime = Date.now();
+    const warnings = [];
+    const nextActions = [];
+    let truncated = false;
+    let truncatedReason;
+    let fromCache = false;
+    return {
+        requestId,
+        startTime,
+        warnings,
+        nextActions,
+        truncated,
+        truncatedReason,
+        fromCache,
+        addWarning(code, message, recoverable = true) {
+            warnings.push({ code, message, recoverable });
+        },
+        addNextAction(action) {
+            nextActions.push(action);
+        },
+        setTruncated(reason) {
+            truncated = true;
+            truncatedReason = reason;
+        },
+        setFromCache(cached) {
+            fromCache = cached;
+        },
+        build() {
+            const meta = {
+                requestId,
+                durationMs: Date.now() - startTime,
+            };
+            if (fromCache) {
+                meta.fromCache = true;
+            }
+            if (warnings.length > 0) {
+                meta.warnings = warnings;
+            }
+            if (truncated) {
+                meta.truncated = true;
+                meta.truncatedReason = truncatedReason;
+            }
+            if (nextActions.length > 0) {
+                meta.nextActions = nextActions;
+            }
+            return meta;
+        },
+    };
+}
+/**
+ * Common warning codes for standardized error handling.
+ */
+export const WarningCodes = {
+    /** Source ID format mismatch */
+    SOURCE_ID_MISMATCH: 'SOURCE_ID_MISMATCH',
+    /** No matching results found */
+    NO_MATCHES: 'NO_MATCHES',
+    /** Result truncated due to limits */
+    RESULT_TRUNCATED: 'RESULT_TRUNCATED',
+    /** Index not initialized */
+    INDEX_NOT_INITIALIZED: 'INDEX_NOT_INITIALIZED',
+    /** Evidence sources missing */
+    SOURCES_MISSING: 'SOURCES_MISSING',
+    /** Bundle not found */
+    BUNDLE_NOT_FOUND: 'BUNDLE_NOT_FOUND',
+    /** File not found in bundle */
+    FILE_NOT_FOUND: 'FILE_NOT_FOUND',
+    /** Deprecated parameter used */
+    DEPRECATED_PARAM: 'DEPRECATED_PARAM',
+};
+/**
+ * Helper to create "did you mean" suggestions for source_id mismatches.
+ */
+export function createDidYouMeanNextActions(bundleId, sourceType, candidates, originalSourceId) {
+    return candidates.slice(0, 5).map((candidate) => ({
+        toolName: 'preflight_trace_query',
+        paramsTemplate: {
+            bundleId,
+            source_type: sourceType,
+            source_id: candidate,
+        },
+        why: `Try "${candidate}" instead of "${originalSourceId}"`,
+    }));
+}