preflight-mcp 0.1.3 → 0.1.5

package/dist/server.js

@@ -3,7 +3,8 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
 import { getConfig } from './config.js';
-import { checkForUpdates, clearBundleMulti, createBundle, findBundleStorageDir, getBundlePathsForId, getEffectiveStorageDir, listBundles, repairBundle, updateBundle, } from './bundle/service.js';
+import { assertBundleComplete, checkForUpdates, checkInProgressLock, clearBundleMulti, computeCreateInputFingerprint, createBundle, findBundleStorageDir, getBundlePathsForId, getEffectiveStorageDir, listBundles, repairBundle, updateBundle, } from './bundle/service.js';
+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';
@@ -81,9 +82,12 @@ const RepairBundleInputSchema = {
     rebuildGuides: z.boolean().optional().describe('If true, rebuild START_HERE.md and AGENTS.md when missing/empty.'),
     rebuildOverview: z.boolean().optional().describe('If true, rebuild OVERVIEW.md when missing/empty.'),
 };
-const ReadFileInputSchema = {
-    bundleId: z.string().describe('Bundle ID.'),
-    file: z.string().default('OVERVIEW.md').describe('File path relative to bundle root. Common files: OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, or any repo file like repos/owner/repo/norm/README.md'),
+const GetTaskStatusInputSchema = {
+    taskId: z.string().optional().describe('Task ID to query (from BUNDLE_IN_PROGRESS error).'),
+    fingerprint: z.string().optional().describe('Fingerprint to query (computed from repos/libraries/topics).'),
+    repos: z.array(CreateRepoInputSchema).optional().describe('Repos to compute fingerprint from (alternative to fingerprint).'),
+    libraries: z.array(z.string()).optional().describe('Libraries for fingerprint computation.'),
+    topics: z.array(z.string()).optional().describe('Topics for fingerprint computation.'),
 };
 export async function startServer() {
     const cfg = getConfig();
@@ -95,7 +99,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.1.3',
+        version: '0.1.5',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -254,13 +258,20 @@ export async function startServer() {
         };
     });
     server.registerTool('preflight_read_file', {
-        title: 'Read bundle file',
-        description: 'Read a file from bundle. Use when: "show overview", "read file", "查看概览", "项目概览", "看README", "查看文档", "bundle详情", "bundle状态", "仓库信息". Common files: OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json (for bundle metadata/status).',
-        inputSchema: ReadFileInputSchema,
+        title: 'Read bundle file(s)',
+        description: 'Read file(s) from bundle. Two modes: ' +
+            '(1) Omit "file" param → returns ALL key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, repo READMEs) in one call. ' +
+            '(2) Provide "file" param → returns that specific file. ' +
+            'Use when: "查看bundle", "show bundle", "read overview", "bundle概览", "项目信息".',
+        inputSchema: {
+            bundleId: z.string().describe('Bundle ID to read.'),
+            file: z.string().optional().describe('Specific file to read. If omitted, returns all key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, repo READMEs).'),
+        },
         outputSchema: {
             bundleId: z.string(),
-            file: z.string(),
-            content: z.string(),
+            file: z.string().optional(),
+            content: z.string().optional(),
+            files: z.record(z.string(), z.string().nullable()).optional(),
         },
         annotations: {
             readOnlyHint: true,
@@ -271,16 +282,66 @@ export async function startServer() {
             if (!storageDir) {
                 throw new Error(`Bundle not found: ${args.bundleId}`);
             }
-            const bundleRoot = getBundlePathsForId(storageDir, args.bundleId).rootDir;
-            const absPath = safeJoin(bundleRoot, args.file);
-            const content = await fs.readFile(absPath, 'utf8');
-            const out = {
-                bundleId: args.bundleId,
-                file: args.file,
-                content,
-            };
+            const paths = getBundlePathsForId(storageDir, args.bundleId);
+            const bundleRoot = paths.rootDir;
+            // 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 };
+                return {
+                    content: [{ type: 'text', text: content }],
+                    structuredContent: out,
+                };
+            }
+            // Batch mode: read all key files
+            const keyFiles = ['OVERVIEW.md', 'START_HERE.md', 'AGENTS.md', 'manifest.json'];
+            const files = {};
+            for (const file of keyFiles) {
+                try {
+                    const absPath = safeJoin(bundleRoot, file);
+                    files[file] = await fs.readFile(absPath, 'utf8');
+                }
+                catch {
+                    files[file] = null;
+                }
+            }
+            // Try to find and read repo README files
+            try {
+                const manifest = await readManifest(paths.manifestPath);
+                for (const repo of manifest.repos ?? []) {
+                    if (!repo.id)
+                        continue;
+                    const [owner, repoName] = repo.id.split('/');
+                    if (!owner || !repoName)
+                        continue;
+                    const readmeNames = ['README.md', 'readme.md', 'Readme.md', 'README.MD'];
+                    for (const readmeName of readmeNames) {
+                        const readmePath = `repos/${owner}/${repoName}/norm/${readmeName}`;
+                        try {
+                            const absPath = safeJoin(bundleRoot, readmePath);
+                            files[readmePath] = await fs.readFile(absPath, 'utf8');
+                            break;
+                        }
+                        catch {
+                            // Try next
+                        }
+                    }
+                }
+            }
+            catch {
+                // Ignore manifest read errors
+            }
+            // Build combined text output
+            const textParts = [];
+            for (const [filePath, content] of Object.entries(files)) {
+                if (content) {
+                    textParts.push(`=== ${filePath} ===\n${content}`);
+                }
+            }
+            const out = { bundleId: args.bundleId, files };
             return {
-                content: [{ type: 'text', text: content }],
+                content: [{ type: 'text', text: textParts.join('\n\n') || '(no files found)' }],
                 structuredContent: out,
             };
         }
@@ -321,22 +382,23 @@ export async function startServer() {
         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).',
         inputSchema: CreateBundleInputSchema,
         outputSchema: {
-            bundleId: z.string(),
-            createdAt: z.string(),
-            updatedAt: z.string(),
+            // Normal completion fields
+            bundleId: z.string().optional(),
+            createdAt: z.string().optional(),
+            updatedAt: z.string().optional(),
             resources: z.object({
                 startHere: z.string(),
                 agents: z.string(),
                 overview: z.string(),
                 manifest: z.string(),
-            }),
+            }).optional(),
             repos: z.array(z.object({
                 kind: z.enum(['github', 'local']),
                 id: z.string(),
                 source: z.enum(['git', 'archive', 'local']).optional(),
                 headSha: z.string().optional(),
                 notes: z.array(z.string()).optional(),
-            })),
+            })).optional(),
             libraries: z
                 .array(z.object({
                 kind: z.literal('context7'),
@@ -347,6 +409,20 @@ export async function startServer() {
                 files: z.array(z.string()).optional(),
             }))
                 .optional(),
+            // User-facing warnings (e.g., git clone failed, used zip fallback)
+            warnings: z.array(z.string()).optional(),
+            // In-progress status fields
+            status: z.enum(['in-progress', 'complete']).optional(),
+            message: z.string().optional(),
+            taskId: z.string().optional(),
+            fingerprint: z.string().optional(),
+            /** Repo IDs requested (for in-progress status only, different from repos array) */
+            requestedRepos: z.array(z.string()).optional(),
+            startedAt: z.string().optional(),
+            elapsedSeconds: z.number().optional(),
+            currentPhase: z.string().optional(),
+            currentProgress: z.number().optional(),
+            currentMessage: z.string().optional(),
         },
         annotations: {
             openWorldHint: true,
@@ -370,12 +446,48 @@ export async function startServer() {
                 ...summary,
                 resources,
             };
+            // Build text response - prominently show warnings if any
+            let textResponse = '';
+            if (summary.warnings && summary.warnings.length > 0) {
+                textResponse += '📢 **Network Issues Encountered:**\n';
+                for (const warn of summary.warnings) {
+                    textResponse += `${warn}\n`;
+                }
+                textResponse += '\n';
+            }
+            textResponse += `✅ Bundle created: ${summary.bundleId}\n`;
+            textResponse += `Repos: ${summary.repos.map(r => `${r.id} (${r.source})`).join(', ')}`;
             return {
-                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+                content: [{ type: 'text', text: textResponse }],
                 structuredContent: out,
             };
         }
         catch (err) {
+            // Handle BUNDLE_IN_PROGRESS error specially - provide useful info instead of just error
+            if (err?.code === 'BUNDLE_IN_PROGRESS') {
+                const elapsedSec = err.startedAt
+                    ? Math.round((Date.now() - new Date(err.startedAt).getTime()) / 1000)
+                    : 0;
+                // Check current progress from tracker
+                const tracker = getProgressTracker();
+                const task = err.taskId ? tracker.getTask(err.taskId) : undefined;
+                const out = {
+                    status: 'in-progress',
+                    message: `Bundle creation already in progress. Use preflight_get_task_status to check progress.`,
+                    taskId: err.taskId,
+                    fingerprint: err.fingerprint,
+                    requestedRepos: err.repos,
+                    startedAt: err.startedAt,
+                    elapsedSeconds: elapsedSec,
+                    currentPhase: task?.phase,
+                    currentProgress: task?.progress,
+                    currentMessage: task?.message,
+                };
+                return {
+                    content: [{ type: 'text', text: `⚠️ Bundle creation in progress (${elapsedSec}s elapsed). ${task ? `Current: ${task.phase} (${task.progress}%) - ${task.message}` : 'Use preflight_get_task_status to check progress.'}` }],
+                    structuredContent: out,
+                };
+            }
             throw wrapPreflightError(err);
         }
     });
@@ -388,6 +500,8 @@ export async function startServer() {
             mode: z.enum(['validate', 'repair']),
             repaired: z.boolean(),
             actionsTaken: z.array(z.string()),
+            /** Issues that cannot be fixed by repair (require re-download) */
+            unfixableIssues: z.array(z.string()).optional(),
             before: z.object({
                 isValid: z.boolean(),
                 missingComponents: z.array(z.string()),
@@ -409,11 +523,21 @@ export async function startServer() {
                 rebuildGuides: args.rebuildGuides,
                 rebuildOverview: args.rebuildOverview,
             });
-            const summaryLine = out.mode === 'validate'
-                ? `VALIDATE ${out.bundleId}: ${out.before.isValid ? 'OK' : 'MISSING'} (${out.before.missingComponents.length} issue(s))`
-                : out.repaired
-                    ? `REPAIRED ${out.bundleId}: ${out.actionsTaken.length} action(s), now ${out.after.isValid ? 'OK' : 'STILL_MISSING'} (${out.after.missingComponents.length} issue(s))`
-                    : `NOOP ${out.bundleId}: nothing to repair (already OK)`;
+            let summaryLine;
+            if (out.mode === 'validate') {
+                summaryLine = `VALIDATE ${out.bundleId}: ${out.before.isValid ? 'OK' : 'INVALID'} (${out.before.missingComponents.length} issue(s))`;
+            }
+            else if (out.unfixableIssues && out.unfixableIssues.length > 0) {
+                // Has unfixable issues - clearly communicate this
+                summaryLine = `⚠️ UNFIXABLE ${out.bundleId}: ${out.unfixableIssues.length} issue(s) cannot be repaired offline.\n` +
+                    out.unfixableIssues.map(i => `  - ${i}`).join('\n');
+            }
+            else if (out.repaired) {
+                summaryLine = `REPAIRED ${out.bundleId}: ${out.actionsTaken.length} action(s), now ${out.after.isValid ? 'OK' : 'STILL_INVALID'} (${out.after.missingComponents.length} issue(s))`;
+            }
+            else {
+                summaryLine = `NOOP ${out.bundleId}: nothing to repair (already OK)`;
+            }
             return {
                 content: [{ type: 'text', text: summaryLine }],
                 structuredContent: out,
@@ -486,22 +610,38 @@ export async function startServer() {
                     structuredContent: out,
                 };
             }
-            const { summary, changed } = await updateBundle(cfg, args.bundleId, { force: args.force });
-            const resources = {
-                startHere: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'START_HERE.md' }),
-                agents: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'AGENTS.md' }),
-                overview: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'OVERVIEW.md' }),
-                manifest: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'manifest.json' }),
-            };
-            const out = {
-                changed: args.force ? true : changed,
-                ...summary,
-                resources,
-            };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
-                structuredContent: out,
-            };
+            // Create task for progress tracking
+            const tracker = getProgressTracker();
+            const fingerprint = `update-${args.bundleId}`;
+            const taskId = tracker.startTask(fingerprint, [args.bundleId]);
+            try {
+                const { summary, changed } = await updateBundle(cfg, args.bundleId, {
+                    force: args.force,
+                    onProgress: (phase, progress, message, total) => {
+                        tracker.updateProgress(taskId, phase, progress, message, total);
+                    },
+                });
+                tracker.completeTask(taskId, args.bundleId);
+                const resources = {
+                    startHere: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'START_HERE.md' }),
+                    agents: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'AGENTS.md' }),
+                    overview: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'OVERVIEW.md' }),
+                    manifest: toBundleFileUri({ bundleId: summary.bundleId, relativePath: 'manifest.json' }),
+                };
+                const out = {
+                    changed: args.force ? true : changed,
+                    ...summary,
+                    resources,
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+                    structuredContent: out,
+                };
+            }
+            catch (updateErr) {
+                tracker.failTask(taskId, updateErr instanceof Error ? updateErr.message : String(updateErr));
+                throw updateErr;
+            }
         }
         catch (err) {
             throw wrapPreflightError(err);
@@ -607,6 +747,8 @@ export async function startServer() {
         },
     }, async (args) => {
         try {
+            // Check bundle completeness before any operation
+            await assertBundleComplete(cfg, args.bundleId);
             // Resolve bundle location across storageDirs (more robust than a single effectiveDir).
             const storageDir = await findBundleStorageDir(cfg.storageDirs, args.bundleId);
             if (!storageDir) {
@@ -643,7 +785,11 @@ export async function startServer() {
     });
     server.registerTool('preflight_evidence_dependency_graph', {
         title: 'Evidence: dependency graph (callers + imports)',
-        description: 'Generate an evidence-based dependency graph for a target file/symbol inside a bundle. Output is deterministic (FTS + regex) and every edge includes traceable sources (file + range). This tool is read-only.',
+        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.',
         inputSchema: DependencyGraphInputSchema,
         outputSchema: {
             meta: z.any(),
@@ -655,6 +801,8 @@ export async function startServer() {
         },
     }, async (args) => {
         try {
+            // Check bundle completeness before generating dependency graph
+            await assertBundleComplete(cfg, args.bundleId);
             const out = await generateDependencyGraph(cfg, args);
             return {
                 content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
@@ -679,6 +827,8 @@ export async function startServer() {
         },
     }, async (args) => {
         try {
+            // Check bundle completeness before trace upsert
+            await assertBundleComplete(cfg, args.bundleId);
             const out = await traceUpsert(cfg, args);
             return {
                 content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
@@ -715,6 +865,10 @@ export async function startServer() {
         },
     }, async (args) => {
         try {
+            // Check bundle completeness if bundleId is provided
+            if (args.bundleId) {
+                await assertBundleComplete(cfg, args.bundleId);
+            }
             const out = await traceQuery(cfg, args);
             return {
                 content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
@@ -763,6 +917,115 @@ export async function startServer() {
             throw wrapPreflightError(err);
         }
     });
+    // Get task status - for checking progress of in-progress bundle creations
+    server.registerTool('preflight_get_task_status', {
+        title: 'Get task status',
+        description: 'Check status of bundle creation tasks (especially in-progress ones). Use when: "check bundle creation progress", "what is the status", "查看任务状态", "下载进度". Can query by taskId (from error), fingerprint, or repos.',
+        inputSchema: GetTaskStatusInputSchema,
+        outputSchema: {
+            found: z.boolean(),
+            task: z.object({
+                taskId: z.string(),
+                fingerprint: z.string(),
+                phase: z.string(),
+                progress: z.number(),
+                total: z.number().optional(),
+                message: z.string(),
+                startedAt: z.string(),
+                updatedAt: z.string(),
+                repos: z.array(z.string()),
+                bundleId: z.string().optional(),
+                error: z.string().optional(),
+            }).optional(),
+            inProgressLock: z.object({
+                bundleId: z.string(),
+                status: z.string(),
+                startedAt: z.string().optional(),
+                taskId: z.string().optional(),
+                repos: z.array(z.string()).optional(),
+                elapsedSeconds: z.number().optional(),
+            }).optional(),
+            activeTasks: z.array(z.object({
+                taskId: z.string(),
+                fingerprint: z.string(),
+                phase: z.string(),
+                progress: z.number(),
+                message: z.string(),
+                repos: z.array(z.string()),
+                startedAt: z.string(),
+            })).optional(),
+        },
+        annotations: {
+            readOnlyHint: true,
+        },
+    }, async (args) => {
+        try {
+            const tracker = getProgressTracker();
+            let result = { found: false };
+            // Compute fingerprint if repos provided
+            let fingerprint = args.fingerprint;
+            if (!fingerprint && args.repos?.length) {
+                fingerprint = computeCreateInputFingerprint({
+                    repos: args.repos,
+                    libraries: args.libraries,
+                    topics: args.topics,
+                });
+            }
+            // Query by taskId
+            if (args.taskId) {
+                const task = tracker.getTask(args.taskId);
+                if (task) {
+                    result = { found: true, task };
+                }
+            }
+            // Query by fingerprint
+            else if (fingerprint) {
+                const task = tracker.getTaskByFingerprint(fingerprint);
+                if (task) {
+                    result = { found: true, task };
+                }
+                // Also check persistent in-progress lock
+                const lock = await checkInProgressLock(cfg, fingerprint);
+                if (lock) {
+                    const elapsedSeconds = lock.startedAt
+                        ? Math.round((Date.now() - new Date(lock.startedAt).getTime()) / 1000)
+                        : undefined;
+                    result.inProgressLock = {
+                        bundleId: lock.bundleId,
+                        status: lock.status ?? 'unknown',
+                        startedAt: lock.startedAt,
+                        taskId: lock.taskId,
+                        repos: lock.repos,
+                        elapsedSeconds,
+                    };
+                    result.found = true;
+                }
+            }
+            // If no specific query, return all active tasks
+            else {
+                const activeTasks = tracker.listActiveTasks();
+                if (activeTasks.length > 0) {
+                    result = { found: true, activeTasks };
+                }
+            }
+            const summary = result.found
+                ? result.task
+                    ? `Task ${result.task.taskId}: ${result.task.phase} (${result.task.progress}%) - ${result.task.message}`
+                    : result.activeTasks
+                        ? `${result.activeTasks.length} active task(s)`
+                        : result.inProgressLock
+                            ? `In-progress lock found (started ${result.inProgressLock.elapsedSeconds}s ago)`
+                            : 'Status found'
+                : 'No matching task found';
+            return {
+                content: [{ type: 'text', text: summary }],
+                structuredContent: result,
+            };
+        }
+        catch (err) {
+            throw wrapPreflightError(err);
+        }
+    });
     // Provide backward-compatible parsing of the same URI via resources/read for clients that bypass templates.
     // This is a safety net: if a client gives us a fully-specified URI, we can still serve it.
     server.registerResource('bundle-file-compat', 'preflight://bundle-file', {

package/package.json

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