preflight-mcp 0.1.9 → 0.2.0

package/README.md

@@ -16,6 +16,9 @@ Each bundle contains:
 ## Features
 
 - **13 MCP tools** to create/update/repair/search/read bundles, generate evidence graphs, and manage trace links
+- **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
@@ -203,10 +206,16 @@ Generate an evidence-based dependency graph. Two modes:
 - Emits `imports` edges (file → module) and `imports_resolved` edges (file → internal file).
 
 ### `preflight_trace_upsert`
-Upsert traceability links (commit↔ticket, symbol↔test, code↔doc, etc.) for a bundle.
+Create or update traceability links (code↔test, code↔doc, file↔requirement).
+- **Proactive use**: LLM automatically records discovered relationships during code analysis
+- Common link types: `tested_by`, `implements`, `documents`, `relates_to`, `depends_on`
+- **Auto-exports** to `trace/trace.json` after each upsert for direct LLM reading
 
 ### `preflight_trace_query`
-Query traceability links (fast when `bundleId` is provided; can scan across bundles when omitted).
+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?"
+- Fast when `bundleId` is provided; can scan across bundles when omitted.
 
 ### `preflight_cleanup_orphans`
 Remove incomplete or corrupted bundles (bundles without valid manifest.json).
@@ -287,7 +296,9 @@ Inside a bundle directory:
 - `OVERVIEW.md`
 - `indexes/search.sqlite3`
 - `analysis/FACTS.json` (static analysis)
+- `deps/dependency-graph.json` (global import graph; generated on demand)
 - `trace/trace.sqlite3` (traceability links; created on demand)
+- `trace/trace.json` (**NEW**: auto-exported JSON for direct LLM reading)
 - `repos/<owner>/<repo>/raw/...`
 - `repos/<owner>/<repo>/norm/...` (GitHub/local snapshots)
 - `libraries/context7/<...>/meta.json`

package/dist/server.js

@@ -100,7 +100,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.1.8',
+        version: '0.2.0',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -457,7 +457,12 @@ export async function startServer() {
                 textResponse += '\n';
             }
             textResponse += `✅ Bundle created: ${summary.bundleId}\n`;
-            textResponse += `Repos: ${summary.repos.map(r => `${r.id} (${r.source})`).join(', ')}`;
+            textResponse += `Repos: ${summary.repos.map(r => `${r.id} (${r.source})`).join(', ')}\n\n`;
+            // Prompt user for advanced analysis
+            textResponse += `📊 **Recommended next steps:**\n`;
+            textResponse += `Would you like me to generate a **global dependency graph** for deeper code analysis? ` +
+                `This will analyze import relationships across all files.\n`;
+            textResponse += `(Call \`preflight_evidence_dependency_graph\` with this bundleId to generate)`;
             return {
                 content: [{ type: 'text', text: textResponse }],
                 structuredContent: out,
@@ -792,8 +797,9 @@ export async function startServer() {
         }
     });
     server.registerTool('preflight_evidence_dependency_graph', {
-        title: 'Evidence: dependency graph (callers + imports)',
-        description: 'Generate an evidence-based dependency graph. IMPORTANT: Before running, ASK the user which bundle and which file/mode they want! ' +
+        title: 'Evidence: dependency graph',
+        description: '**Proactive use recommended**: Generate dependency graphs to understand code structure. ' +
+            '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}.',
@@ -822,7 +828,12 @@ export async function startServer() {
     });
     server.registerTool('preflight_trace_upsert', {
         title: 'Trace: upsert links',
-        description: 'Upsert traceability links (commit↔ticket, symbol↔test, code↔doc, etc.) for a bundle. Stores trace edges in a per-bundle SQLite database.',
+        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.',
         inputSchema: TraceUpsertInputSchema,
         outputSchema: {
             bundleId: z.string(),
@@ -848,7 +859,11 @@ export async function startServer() {
     });
     server.registerTool('preflight_trace_query', {
         title: 'Trace: query links',
-        description: 'Query traceability links. Provide bundleId for fast queries; if omitted, scans across bundles (capped). This tool is read-only.',
+        description: 'Query traceability links (code↔test, code↔doc, commit↔ticket). ' +
+            '**Proactive use recommended**: When analyzing a specific file or discussing code structure, ' +
+            'automatically query trace links to find related tests, documentation, or requirements. ' +
+            'This helps answer questions like "does this code have tests?" or "what requirements does this implement?". ' +
+            'Provide bundleId for fast queries; if omitted, scans across bundles (capped). This tool is read-only.',
         inputSchema: TraceQueryInputSchema,
         outputSchema: {
             bundleId: z.string().optional(),

package/dist/trace/store.js

@@ -98,8 +98,56 @@ export async function upsertTraceEdges(traceDbPath, edges) {
             return ids;
         });
         const ids = tx(edges);
+        // Close DB before export (export opens its own readonly connection)
+        db.close();
+        // Auto-export to JSON after each upsert for LLM direct reading
+        try {
+            await exportTraceToJson(traceDbPath);
+        }
+        catch {
+            // Non-critical: JSON export failure shouldn't block upsert
+        }
         return { upserted: ids.length, ids };
     }
+    catch (err) {
+        db.close();
+        throw err;
+    }
+}
+/**
+ * Export all trace edges to a JSON file for LLM direct reading.
+ * Called automatically after upsertTraceEdges.
+ */
+export async function exportTraceToJson(traceDbPath) {
+    const jsonPath = traceDbPath.replace(/\.sqlite3$/, '.json');
+    const db = new Database(traceDbPath, { readonly: true });
+    try {
+        const rows = db.prepare(`
+      SELECT
+        id, source_type, source_id, target_type, target_id,
+        edge_type, confidence, method, sources_json, created_at, updated_at
+      FROM trace_edges
+      ORDER BY updated_at DESC
+    `).all();
+        const edges = rows.map((r) => ({
+            id: r.id,
+            source: { type: r.source_type, id: r.source_id },
+            target: { type: r.target_type, id: r.target_id },
+            type: r.edge_type,
+            confidence: r.confidence,
+            method: r.method,
+            sources: JSON.parse(r.sources_json || '[]'),
+            createdAt: r.created_at,
+            updatedAt: r.updated_at,
+        }));
+        const exportData = {
+            exportedAt: new Date().toISOString(),
+            totalEdges: edges.length,
+            edges,
+        };
+        await fs.writeFile(jsonPath, JSON.stringify(exportData, null, 2), 'utf8');
+        return { exported: edges.length, jsonPath };
+    }
     finally {
         db.close();
     }

package/package.json

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