preflight-mcp 0.1.6 → 0.1.8

package/dist/bundle/githubArchive.js

@@ -7,7 +7,7 @@ function nowIso() {
 }
 function githubHeaders(cfg) {
     const headers = {
-        'User-Agent': 'preflight-mcp/0.1.6',
+        'User-Agent': 'preflight-mcp/0.1.8',
         Accept: 'application/vnd.github+json',
     };
     if (cfg.githubToken) {

package/dist/bundle/paths.js

@@ -25,6 +25,7 @@ export function getBundlePaths(storageDir, bundleId) {
     validateBundleId(bundleId);
     const rootDir = path.join(storageDir, bundleId);
     const indexesDir = path.join(rootDir, 'indexes');
+    const depsDir = path.join(rootDir, 'deps');
     return {
         bundleId,
         rootDir,
@@ -36,6 +37,8 @@ export function getBundlePaths(storageDir, bundleId) {
         searchDbPath: path.join(indexesDir, 'search.sqlite3'),
         reposDir: path.join(rootDir, 'repos'),
         librariesDir: path.join(rootDir, 'libraries'),
+        depsDir,
+        depsGraphPath: path.join(depsDir, 'dependency-graph.json'),
     };
 }
 export function repoRootDir(paths, owner, repo) {

package/dist/bundle/service.js

@@ -15,6 +15,7 @@ import { analyzeBundleStatic } from './analysis.js';
 import { autoDetectTags, generateDisplayName, generateDescription } from './tagging.js';
 import { bundleCreationLimiter } from '../core/concurrency-limiter.js';
 import { getProgressTracker, calcPercent } from '../jobs/progressTracker.js';
+import { BundleNotFoundError } from '../errors.js';
 const DEDUP_INDEX_FILE = '.preflight-dedup-index.json';
 function sha256Hex(text) {
     return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
@@ -425,7 +426,7 @@ async function validateBundleCompleteness(bundleRoot) {
 export async function assertBundleComplete(cfg, bundleId) {
     const storageDir = await findBundleStorageDir(cfg.storageDirs, bundleId);
     if (!storageDir) {
-        throw new Error(`Bundle not found: ${bundleId}`);
+        throw new BundleNotFoundError(bundleId);
     }
     const bundleRoot = getBundlePaths(storageDir, bundleId).rootDir;
     const { isValid, missingComponents } = await validateBundleCompleteness(bundleRoot);
@@ -1316,7 +1317,7 @@ export async function repairBundle(cfg, bundleId, options) {
     const rebuildOverviewOpt = options?.rebuildOverview ?? true;
     const storageDir = await findBundleStorageDir(cfg.storageDirs, bundleId);
     if (!storageDir) {
-        throw new Error(`Bundle not found: ${bundleId}`);
+        throw new BundleNotFoundError(bundleId);
     }
     const paths = getBundlePaths(storageDir, bundleId);
     const before = await validateBundleCompleteness(paths.rootDir);

package/dist/context7/client.js

@@ -20,7 +20,7 @@ export async function connectContext7(cfg) {
             maxRetries: 1,
         },
     });
-    const client = new Client({ name: 'preflight-context7', version: '0.1.6' });
+    const client = new Client({ name: 'preflight-context7', version: '0.1.8' });
     await client.connect(transport);
     return {
         client,

package/dist/errors.js

@@ -31,12 +31,24 @@ export class PreflightError extends Error {
         };
     }
 }
+/**
+ * Check if a string looks like a valid UUID v4.
+ */
+function isUuidFormat(id) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);
+}
 /**
  * Error thrown when a bundle is not found.
  */
 export class BundleNotFoundError extends PreflightError {
     constructor(bundleId) {
-        super(`Bundle not found: ${bundleId}`, 'BUNDLE_NOT_FOUND', {
+        const hint = isUuidFormat(bundleId)
+            ? '\nUse preflight_list_bundles to see available bundles.'
+            : `\nHint: bundleId must be a UUID (e.g., 025c6dcb-1234-5678-9abc-def012345678).\n` +
+                `      "${bundleId}" looks like a displayName, not a bundleId.\n` +
+                `      Use preflight_list_bundles to find the correct bundleId.\n` +
+                `      DO NOT automatically create a new bundle - ASK the user first!`;
+        super(`Bundle not found: ${bundleId}${hint}`, 'BUNDLE_NOT_FOUND', {
             context: { bundleId },
         });
         this.name = 'BundleNotFoundError';

package/dist/evidence/dependencyGraph.js

@@ -21,6 +21,8 @@ export const DependencyGraphInputSchema = {
             .describe('Optional symbol name (function/class). If omitted, graph is file-level.'),
     }).optional().describe('Target file/symbol to analyze. If omitted, generates a GLOBAL dependency graph of all code files in the bundle. ' +
         '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.'),
     options: z
         .object({
         maxFiles: z.number().int().min(1).max(500).default(200),
@@ -200,6 +202,24 @@ export async function generateDependencyGraph(cfg, rawArgs) {
     }
     const paths = getBundlePathsForId(storageDir, args.bundleId);
     const manifest = await readManifest(paths.manifestPath);
+    // Global mode: check for cached result (unless force=true)
+    const isGlobalMode = !args.target;
+    if (isGlobalMode && !args.force) {
+        try {
+            const cached = await fs.readFile(paths.depsGraphPath, 'utf8');
+            const parsed = JSON.parse(cached);
+            // 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.`,
+            });
+            return parsed;
+        }
+        catch {
+            // Cache miss - generate fresh
+        }
+    }
     const limits = {
         maxFiles: args.options.maxFiles,
         maxNodes: args.options.maxNodes,
@@ -248,7 +268,7 @@ export async function generateDependencyGraph(cfg, rawArgs) {
     const bundleFileUri = (p) => toBundleFileUri({ bundleId: args.bundleId, relativePath: p });
     // Global mode: no target specified
     if (!args.target) {
-        return generateGlobalDependencyGraph({
+        const result = await generateGlobalDependencyGraph({
             cfg,
             args,
             paths,
@@ -265,6 +285,15 @@ export async function generateDependencyGraph(cfg, rawArgs) {
             addEdge,
             bundleFileUri,
         });
+        // Save to cache
+        try {
+            await fs.mkdir(paths.depsDir, { recursive: true });
+            await fs.writeFile(paths.depsGraphPath, JSON.stringify(result, null, 2));
+        }
+        catch {
+            // Ignore cache write errors
+        }
+        return result;
     }
     const targetFile = args.target.file.replaceAll('\\', '/');
     const targetRepo = parseRepoNormPath(targetFile);

package/dist/server.js

@@ -8,6 +8,7 @@ import { getProgressTracker } from './jobs/progressTracker.js';
 import { readManifest } from './bundle/manifest.js';
 import { safeJoin, toBundleFileUri } from './mcp/uris.js';
 import { wrapPreflightError } from './mcp/errorKinds.js';
+import { BundleNotFoundError } from './errors.js';
 import { searchIndex } from './search/sqliteFts.js';
 import { logger } from './logging/logger.js';
 import { runSearchByTags } from './tools/searchByTags.js';
@@ -99,7 +100,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.1.6',
+        version: '0.1.8',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -280,7 +281,7 @@ export async function startServer() {
         try {
             const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
             if (!storageDir) {
-                throw new Error(`Bundle not found: ${args.bundleId}`);
+                throw new BundleNotFoundError(args.bundleId);
             }
             const paths = getBundlePathsForId(storageDir, args.bundleId);
             const bundleRoot = paths.rootDir;
@@ -364,7 +365,7 @@ export async function startServer() {
         try {
             const deleted = await clearBundleMulti(cfg.storageDirs, args.bundleId);
             if (!deleted) {
-                throw new Error(`Bundle not found: ${args.bundleId}`);
+                throw new BundleNotFoundError(args.bundleId);
             }
             server.sendResourceListChanged();
             const out = { deleted: true, bundleId: args.bundleId };
@@ -379,7 +380,7 @@ export async function startServer() {
     });
     server.registerTool('preflight_create_bundle', {
         title: 'Create bundle',
-        description: 'Create a new bundle from GitHub repos or local directories (or update an existing one if ifExists=updateExisting). Use when: "index this repo", "create bundle for", "add repo to preflight", "索引这个仓库", "创建bundle", "添加GitHub项目", "学习这个项目". NOTE: If the bundle contains code files, consider asking user if they want to generate dependency graph (preflight_evidence_dependency_graph) or establish trace links (preflight_trace_upsert).',
+        description: 'Create a new bundle from GitHub repos or local directories. IMPORTANT: Only call this tool when the user EXPLICITLY asks to create/index a repo. Do NOT automatically create bundles when search fails or bundle is not found - ASK the user first! Use when user says: "index this repo", "create bundle for", "创建bundle", "添加GitHub项目". If ifExists=updateExisting, updates an existing bundle.',
         inputSchema: CreateBundleInputSchema,
         outputSchema: {
             // Normal completion fields
@@ -594,7 +595,7 @@ export async function startServer() {
         try {
             const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
             if (!storageDir) {
-                throw new Error(`Bundle not found: ${args.bundleId}`);
+                throw new BundleNotFoundError(args.bundleId);
             }
             // checkOnly mode: just check for updates without applying
             if (args.checkOnly) {
@@ -759,7 +760,7 @@ export async function startServer() {
             // Resolve bundle location across storageDirs (more robust than a single effectiveDir).
             const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
             if (!storageDir) {
-                throw new Error(`Bundle not found: ${args.bundleId}`);
+                throw new BundleNotFoundError(args.bundleId);
             }
             if (args.ensureFresh) {
                 throw new Error('ensureFresh is deprecated and not supported in this tool. This tool is strictly read-only. ' +
@@ -792,11 +793,10 @@ export async function startServer() {
     });
     server.registerTool('preflight_evidence_dependency_graph', {
         title: 'Evidence: dependency graph (callers + imports)',
-        description: 'Generate an evidence-based dependency graph. Two modes: ' +
-            '(1) TARGET MODE: provide target.file to analyze a specific file\'s imports and callers. ' +
-            '(2) GLOBAL MODE: omit target to generate a project-wide import graph of all code files. ' +
-            'For target mode, file path must be bundle-relative: repos/{owner}/{repo}/norm/{path}. ' +
-            'Use preflight_search_bundle to find file paths, or check OVERVIEW.md.',
+        description: '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}.',
         inputSchema: DependencyGraphInputSchema,
         outputSchema: {
             meta: z.any(),

package/package.json

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