preflight-mcp 0.4.0 → 0.4.2

package/dist/bundle/service.js

@@ -20,6 +20,50 @@ const DEDUP_INDEX_FILE = '.preflight-dedup-index.json';
 function sha256Hex(text) {
     return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
 }
+/**
+ * Parse a skipped file string (from ingest) into structured SkippedFileEntry.
+ * Formats:
+ * - "path/to/file (too large: 12345 bytes)"
+ * - "path/to/file (binary)"
+ * - "path/to/file (non-utf8)"
+ * - "(bundle maxTotalBytes reached) stopped before: path/to/file"
+ */
+function parseSkippedString(s, repoId) {
+    // Pattern: "path (too large: 12345 bytes)"
+    const tooLargeMatch = s.match(/^(.+?) \(too large: (\d+) bytes\)$/);
+    if (tooLargeMatch) {
+        return {
+            path: `${repoId}/${tooLargeMatch[1]}`,
+            reason: 'too_large',
+            size: parseInt(tooLargeMatch[2], 10),
+        };
+    }
+    // Pattern: "path (binary)"
+    const binaryMatch = s.match(/^(.+?) \(binary\)$/);
+    if (binaryMatch) {
+        return {
+            path: `${repoId}/${binaryMatch[1]}`,
+            reason: 'binary',
+        };
+    }
+    // Pattern: "path (non-utf8)"
+    const nonUtf8Match = s.match(/^(.+?) \(non-utf8\)$/);
+    if (nonUtf8Match) {
+        return {
+            path: `${repoId}/${nonUtf8Match[1]}`,
+            reason: 'non_utf8',
+        };
+    }
+    // Pattern: "(bundle maxTotalBytes reached) stopped before: path"
+    const maxTotalMatch = s.match(/^\(bundle maxTotalBytes reached\) stopped before: (.+)$/);
+    if (maxTotalMatch) {
+        return {
+            path: `${repoId}/${maxTotalMatch[1]}`,
+            reason: 'max_total_reached',
+        };
+    }
+    return null;
+}
 function normalizeList(values) {
     return (values ?? [])
         .map((s) => s.trim())
@@ -939,6 +983,7 @@ async function createBundleInternal(cfg, input, options) {
     await ensureDir(tmpPaths.rootDir);
     const finalPaths = getBundlePaths(effectiveStorageDir, bundleId);
     const allIngestedFiles = [];
+    const allSkippedFiles = [];
     const reposSummary = [];
     const allWarnings = [];
     // Track temp checkout directory for cleanup
@@ -970,9 +1015,16 @@ async function createBundleInternal(cfg, input, options) {
                 });
                 allIngestedFiles.push(...files);
                 allWarnings.push(...warnings);
+                // Parse and collect skipped files
+                const repoId = `${owner}/${repo}`;
+                for (const s of skipped) {
+                    const entry = parseSkippedString(s, repoId);
+                    if (entry)
+                        allSkippedFiles.push(entry);
+                }
                 reposSummary.push({
                     kind: 'github',
-                    id: `${owner}/${repo}`,
+                    id: repoId,
                     source,
                     headSha,
                     notes: [...notes, ...skipped].slice(0, 50),
@@ -993,7 +1045,14 @@ async function createBundleInternal(cfg, input, options) {
                     ref: repoInput.ref,
                 });
                 allIngestedFiles.push(...files);
-                reposSummary.push({ kind: 'local', id: `${owner}/${repo}`, source: 'local', notes: skipped.slice(0, 50) });
+                // Parse and collect skipped files
+                const repoId = `${owner}/${repo}`;
+                for (const s of skipped) {
+                    const entry = parseSkippedString(s, repoId);
+                    if (entry)
+                        allSkippedFiles.push(entry);
+                }
+                reposSummary.push({ kind: 'local', id: repoId, source: 'local', notes: skipped.slice(0, 50) });
             }
         }
         // Context7 libraries (best-effort).
@@ -1061,6 +1120,8 @@ async function createBundleInternal(cfg, input, options) {
                 includeDocs: true,
                 includeCode: true,
             },
+            // Store skipped files for transparency (limit to 200 entries to avoid bloat)
+            skippedFiles: allSkippedFiles.length > 0 ? allSkippedFiles.slice(0, 200) : undefined,
         };
         await writeManifest(tmpPaths.manifestPath, manifest);
         // Guides.

package/dist/server.js

@@ -134,7 +134,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.4.0',
+        version: '0.4.2',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -547,6 +547,7 @@ export async function startServer() {
             focusDir: z.string().optional().describe('Focus directory path - expand deeper within this path (e.g., "owner/repo/norm/src"). Gets +3 extra depth levels.'),
             focusDepthBonus: z.number().int().min(1).max(6).optional().describe('Extra depth levels for focusDir. Default 3.'),
             showFileCountPerDir: z.boolean().optional().describe('If true, include file count per directory in stats.byDir.'),
+            showSkippedFiles: z.boolean().optional().describe('If true, include list of files that were skipped during indexing (too large, binary, etc.). Helps understand what content is NOT searchable.'),
         },
         outputSchema: {
             bundleId: z.string(),
@@ -563,6 +564,11 @@ export async function startServer() {
                 type: z.enum(['readme', 'main', 'index', 'cli', 'server', 'app', 'test', 'config']),
                 priority: z.number(),
             })),
+            skippedFiles: z.array(z.object({
+                path: z.string(),
+                reason: z.string(),
+                size: z.number().optional(),
+            })).optional().describe('Files skipped during indexing (only when showSkippedFiles=true). These files are NOT searchable.'),
         },
         annotations: {
             readOnlyHint: true,
@@ -582,10 +588,45 @@ export async function startServer() {
                 focusDepthBonus: args.focusDepthBonus,
                 showFileCountPerDir: args.showFileCountPerDir,
             });
+            // Add skipped files if requested
+            let skippedFiles;
+            if (args.showSkippedFiles) {
+                try {
+                    const manifest = await readManifest(paths.manifestPath);
+                    if (manifest.skippedFiles && manifest.skippedFiles.length > 0) {
+                        const reasonLabels = {
+                            too_large: 'too large',
+                            binary: 'binary file',
+                            non_utf8: 'non-UTF8 encoding',
+                            max_total_reached: 'bundle size limit reached',
+                        };
+                        skippedFiles = manifest.skippedFiles.map(s => ({
+                            path: s.path,
+                            reason: reasonLabels[s.reason] ?? s.reason,
+                            size: s.size,
+                        }));
+                    }
+                }
+                catch {
+                    // Ignore manifest read errors
+                }
+            }
             const textOutput = formatTreeResult(result);
+            let fullTextOutput = textOutput;
+            if (skippedFiles && skippedFiles.length > 0) {
+                fullTextOutput += `\n\n## Skipped Files (${skippedFiles.length} files not searchable)\n`;
+                for (const sf of skippedFiles.slice(0, 20)) {
+                    const sizeStr = sf.size ? ` (${(sf.size / 1024).toFixed(0)}KB)` : '';
+                    fullTextOutput += `- ${sf.path}: ${sf.reason}${sizeStr}\n`;
+                }
+                if (skippedFiles.length > 20) {
+                    fullTextOutput += `... and ${skippedFiles.length - 20} more\n`;
+                }
+            }
+            const structuredResult = { ...result, skippedFiles };
             return {
-                content: [{ type: 'text', text: textOutput }],
-                structuredContent: result,
+                content: [{ type: 'text', text: fullTextOutput }],
+                structuredContent: structuredResult,
             };
         }
         catch (err) {
@@ -708,7 +749,11 @@ export async function startServer() {
     });
     server.registerTool('preflight_create_bundle', {
         title: 'Create bundle',
-        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.',
+        description: 'Create a new bundle from GitHub repos or local directories. ' +
+            '**Safe to call proactively** - use `ifExists: "returnExisting"` to avoid duplicates. ' +
+            'Bundle creation is a **read-only collection** operation (clones repo, builds index, generates guides). ' +
+            'When user asks to analyze/understand a project, create the bundle first if it does not exist. ' +
+            'Use when: "analyze this repo", "understand this codebase", "index project", "分析项目", "理解代码".',
         inputSchema: CreateBundleInputSchema,
         outputSchema: {
             // Normal completion fields
@@ -1084,6 +1129,16 @@ export async function startServer() {
             meta: z.object({
                 tokenBudgetHint: z.string().optional().describe('Hint about token savings from groupByFile.'),
             }).optional().describe('Search metadata for EDDA optimization.'),
+            // Skipped files hint for transparency
+            skippedFilesHint: z.object({
+                message: z.string().describe('Human-readable hint explaining why some content might be missing.'),
+                skippedCount: z.number().describe('Total number of files skipped during indexing.'),
+                examples: z.array(z.object({
+                    path: z.string(),
+                    reason: z.string(),
+                    size: z.number().optional(),
+                })).describe('Example skipped files (limited to 5).'),
+            }).optional().describe('Present when search returns 0 results and files were skipped during indexing. Helps explain why expected content might be missing.'),
             autoUpdated: z
                 .boolean()
                 .optional()
@@ -1130,6 +1185,34 @@ export async function startServer() {
                 });
             }
             const paths = getBundlePathsForId(storageDir, args.bundleId);
+            // Helper to build skippedFilesHint when search returns 0 results
+            const buildSkippedFilesHint = async () => {
+                try {
+                    const manifest = await readManifest(paths.manifestPath);
+                    if (!manifest.skippedFiles || manifest.skippedFiles.length === 0) {
+                        return undefined;
+                    }
+                    const skipped = manifest.skippedFiles;
+                    const reasonLabels = {
+                        too_large: 'too large',
+                        binary: 'binary file',
+                        non_utf8: 'non-UTF8 encoding',
+                        max_total_reached: 'bundle size limit reached',
+                    };
+                    return {
+                        message: `Search returned 0 results. Note: ${skipped.length} file(s) were skipped during indexing and are not searchable. Check if your target content might be in a skipped file.`,
+                        skippedCount: skipped.length,
+                        examples: skipped.slice(0, 5).map(s => ({
+                            path: s.path,
+                            reason: reasonLabels[s.reason] ?? s.reason,
+                            size: s.size,
+                        })),
+                    };
+                }
+                catch {
+                    return undefined;
+                }
+            };
             // Use advanced search if EDDA features are requested
             const useAdvanced = args.groupByFile || args.fileTypeFilters?.length || args.includeScore;
             if (useAdvanced) {
@@ -1178,6 +1261,14 @@ export async function startServer() {
                 if (warnings.length > 0) {
                     out.warnings = warnings;
                 }
+                // Add skippedFilesHint when 0 results
+                const hasNoResults = result.hits.length === 0 && (!grouped || grouped.length === 0);
+                if (hasNoResults) {
+                    const hint = await buildSkippedFilesHint();
+                    if (hint) {
+                        out.skippedFilesHint = hint;
+                    }
+                }
                 return {
                     content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
                     structuredContent: out,
@@ -1228,6 +1319,13 @@ export async function startServer() {
             if (warnings.length > 0) {
                 out.warnings = warnings;
             }
+            // Add skippedFilesHint when 0 results
+            if (hits.length === 0) {
+                const hint = await buildSkippedFilesHint();
+                if (hint) {
+                    out.skippedFilesHint = hint;
+                }
+            }
             return {
                 content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
                 structuredContent: out,

package/package.json

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