preflight-mcp 0.4.4 → 0.5.1

package/README.md

@@ -51,7 +51,8 @@ Preflight: 🔗 Trace links:
 - 📖 **Auto-generated guides** — `START_HERE.md`, `AGENTS.md`, `OVERVIEW.md`
 - ☁️ **Cloud sync** — Multi-path mirror backup for redundancy
 - 🧠 **EDDA (Evidence-Driven Deep Analysis)** — Auto-generate auditable claims with evidence
-- ⚡ **18 MCP tools + 5 prompts** — Complete toolkit for code exploration
+- ⚡ **22 MCP tools + 5 prompts** — Complete toolkit for code exploration
+- 📄 **Cursor pagination** — Handle large result sets efficiently (RFC v2)
 
 <details>
 <summary><b>All Features (click to expand)</b></summary>
@@ -75,7 +76,7 @@ Preflight: 🔗 Trace links:
 - [Demo](#demo)
 - [Core Features](#core-features)
 - [Quick Start](#quick-start)
-- [Tools](#tools-15-total)
+- [Tools](#tools-22-total)
 - [Prompts](#prompts-5-total)
 - [Environment Variables](#environment-variables)
 - [Contributing](#contributing)
@@ -160,10 +161,11 @@ Run end-to-end smoke test:
 npm run smoke
 ```
 
-## Tools (18 total)
+## Tools (22 total)
 
 ### `preflight_list_bundles`
 List bundle IDs in storage.
+- **Cursor pagination** (v0.5.0): Use `cursor` parameter for large bundle lists
 - Triggers: "show bundles", "查看bundle", "有哪些bundle"
 
 ### `preflight_create_bundle`
@@ -236,10 +238,15 @@ Important: **this tool is strictly read-only**.
 - `fileTypeFilters`: Filter by extension (e.g., `[".py", ".ts"]`)
 - `includeScore`: Include BM25 relevance score in results
 
+**Cursor pagination** (v0.5.0):
+- `cursor`: Pagination cursor from previous call for fetching next page
+- Response includes `truncation.nextCursor` when more results available
+
 **Deprecated parameters**: `ensureFresh`, `autoRepairIndex`, `maxAgeHours` are deprecated and will return warnings instead of errors.
 
 ### `preflight_search_by_tags`
 Search across multiple bundles filtered by tags (line-based SQLite FTS5).
+- **Cursor pagination** (v0.5.0): Use `cursor` parameter for large result sets
 - Triggers: "search in MCP bundles", "在MCP项目中搜索", "搜索所有agent"
 
 Notes:
@@ -250,6 +257,7 @@ Optional parameters:
 - `tags`: Filter bundles by tags (e.g., `["mcp", "agents"]`)
 - `scope`: Search scope (`docs`, `code`, or `all`)
 - `limit`: Max total hits across all bundles
+- `cursor`: Pagination cursor for fetching next page
 
 ### `preflight_evidence_dependency_graph`
 Generate an evidence-based dependency graph. Two modes:
@@ -280,6 +288,7 @@ Create or update traceability links (code↔test, code↔doc, file↔requirement
 ### `preflight_trace_query`
 Query traceability links (code↔test, code↔doc, commit↔ticket).
 - **Proactive use**: LLM automatically queries trace links when analyzing specific files
+- **Cursor pagination** (v0.5.0): Use `cursor` parameter for large result sets
 - Returns `reason` and `nextSteps` when no edges found (helps LLM decide next action)
 - Fast when `bundleId` is provided; can scan across bundles when omitted.
 
@@ -301,20 +310,39 @@ Parameters:
 - `min_confidence`: 0-1 (default: 0.85)
 - `limit`: Max suggestions (default: 50)
 
-### `preflight_deep_analyze_bundle` *(NEW v0.4.0)*
-One-call deep analysis aggregating tree, search, deps, and traces.
+### `preflight_deep_analyze_bundle` *(Enhanced v0.5.1)*
+One-call deep analysis aggregating tree, search, deps, traces, **overview content**, and **test detection**.
 - Returns unified evidence pack with LLM-friendly summary
+- **Now includes OVERVIEW.md, START_HERE.md, AGENTS.md, README content** (v0.5.1)
+- **Auto-detects test frameworks** (jest, vitest, pytest, go, mocha) (v0.5.1)
+- **Generates copyable `nextCommands`** for follow-up actions (v0.5.1)
 - Auto-generates **claims** with evidence references
 - Tracks analysis progress via **checklistStatus**
 - Reports unanswered questions as **openQuestions**
-- Triggers: "deep analyze", "comprehensive analysis", "深度分析"
+- Triggers: "deep analyze", "comprehensive analysis", "深度分析", "快速了解项目"
+
+**New in v0.5.1 - Aggregated content (reduces round-trips):**
+- `includeOverview` (default: true): Include OVERVIEW.md, START_HERE.md, AGENTS.md
+- `includeReadme` (default: true): Include repo README.md
+- `includeTests` (default: true): Detect test directories and frameworks
 
 Output includes:
+- `overviewContent`: `{overview, startHere, agents, readme}` - bundle documentation content
+- `testInfo`: `{detected, framework, testDirs, testFileCount, configFiles, hint}` - test detection result
+- `nextCommands[]`: Copyable tool calls for next steps (can be directly used as arguments)
 - `claims[]`: Auto-generated findings with evidence
 - `checklistStatus`: Analysis progress (repo_tree, deps, entrypoints, etc.)
 - `openQuestions[]`: Questions with `nextEvidenceToFetch` hints
 - `summary`: Markdown summary with checklist and key findings
 
+**Example `nextCommands` output:**
+```json
+[
+  { "tool": "preflight_search_bundle", "description": "Search for specific code", "args": { "bundleId": "...", "query": "<填入关键词>" } },
+  { "tool": "preflight_read_file", "description": "Read core module", "args": { "bundleId": "...", "file": "src/server.ts" } }
+]
+```
+
 ### `preflight_validate_report` *(NEW v0.4.0)*
 Validate claims and evidence chains for auditability.
 - Checks: missing evidence, invalid file references, broken snippet hashes
@@ -327,6 +355,37 @@ Parameters:
 - `verifyFileExists`: Check evidence files exist (default: true)
 - `strictMode`: Treat warnings as errors (default: false)
 
+### `preflight_read_files` *(NEW v0.5.0)*
+Batch read multiple files from a bundle in a single call.
+- Reduces round-trips for evidence gathering
+- **RFC v2 unified envelope**: Returns `ok`, `meta`, `data`, `evidence[]`
+- Triggers: "read these files", "get content of", "批量读取"
+
+Parameters:
+- `bundleId`: Bundle ID
+- `files[]`: Array of `{path, ranges?, withLineNumbers?}`
+- `format`: `"json"` (default) or `"text"`
+
+### `preflight_search_and_read` *(NEW v0.5.0)*
+Search + excerpt in one call - finds relevant code and returns context.
+- Combines search with automatic context extraction
+- **RFC v2 unified envelope**: Returns `ok`, `meta`, `data`, `evidence[]`
+- Triggers: "search and show code", "find and read", "搜索并读取"
+
+Parameters:
+- `bundleId`: Bundle ID
+- `query`: Search query
+- `contextLines`: Lines of context around matches (default: 5)
+- `maxFiles`: Max files to read (default: 5)
+- `format`: `"json"` (default) or `"text"`
+
+### `preflight_get_dependency_graph` *(Simplified wrapper)*
+Simplified dependency graph query.
+- `scope: "global"` (default): Project-wide graph
+- `scope: "target"` with `targetFile`: Single file dependencies
+- `format: "summary"` (default): Aggregated view
+- `format: "full"`: Raw graph data
+
 ### `preflight_cleanup_orphans`
 Remove incomplete or corrupted bundles (bundles without valid manifest.json).
 - Triggers: "clean up broken bundles", "remove orphans", "清理孤儿bundle"
@@ -393,6 +452,11 @@ Common kinds:
 - `invalid_path` (unsafe path traversal attempt)
 - `permission_denied`
 - `index_missing_or_corrupt`
+- `cursor_invalid` *(v0.5.0)*
+- `cursor_expired` *(v0.5.0)*
+- `rate_limited` *(v0.5.0)*
+- `timeout` *(v0.5.0)*
+- `pagination_required` *(v0.5.0)*
 - `unknown`
 
 This is designed so UIs/agents can reliably decide whether to:

package/dist/analysis/deep.js

@@ -8,7 +8,7 @@ import { createEmptyCoverageReport, isCoverageSufficient, } from '../types/evide
  * This is called by the server after gathering data from each source.
  */
 export function buildDeepAnalysis(bundleId, components) {
-    const { tree, search, deps, traces, focusPath, focusQuery, errors = [] } = components;
+    const { tree, search, deps, traces, overviewContent, testInfo, focusPath, focusQuery, errors = [] } = components;
     // Build coverage report
     const coverageReport = createEmptyCoverageReport();
     if (tree) {
@@ -75,9 +75,28 @@ export function buildDeepAnalysis(bundleId, components) {
         }
         summaryParts.push('');
     }
+    // Test detection summary
+    if (testInfo) {
+        summaryParts.push(`## Test Detection`);
+        if (testInfo.detected) {
+            summaryParts.push(`- Framework: ${testInfo.framework ?? 'unknown'}`);
+            summaryParts.push(`- Test files: ${testInfo.testFileCount}`);
+            if (testInfo.testDirs.length > 0) {
+                summaryParts.push(`- Test directories: ${testInfo.testDirs.slice(0, 3).join(', ')}`);
+            }
+            if (testInfo.configFiles.length > 0) {
+                summaryParts.push(`- Config files: ${testInfo.configFiles.join(', ')}`);
+            }
+        }
+        else {
+            summaryParts.push(`- No tests detected`);
+        }
+        summaryParts.push(`- 💡 ${testInfo.hint}`);
+        summaryParts.push('');
+    }
     // Build checklist status
     const checklistStatus = {
-        read_overview: false, // Would need OVERVIEW.md read - caller should set
+        read_overview: !!(overviewContent?.overview || overviewContent?.startHere),
         repo_tree: !!tree && tree.totalFiles > 0,
         search_focus: !!search && search.totalHits > 0,
         dependency_graph_global: !!deps && deps.totalNodes > 0,
@@ -271,6 +290,51 @@ export function buildDeepAnalysis(bundleId, components) {
     if (isCoverageSufficient(coverageReport) && openQuestions.length === 0 && claims.length > 0) {
         nextSteps.push('🎉 Analysis complete - all key areas covered. Ready for detailed review.');
     }
+    // Build nextCommands (copyable JSON for LLM)
+    const nextCommands = [];
+    // Always suggest search as a useful next step
+    nextCommands.push({
+        tool: 'preflight_search_bundle',
+        description: 'Search for specific code or concepts',
+        args: { bundleId, query: '<填入关键词>', scope: 'all', limit: 30 },
+    });
+    // Suggest reading a specific entry point if identified
+    if (deps && deps.topImported.length > 0) {
+        const coreFile = deps.topImported[0].file;
+        nextCommands.push({
+            tool: 'preflight_read_file',
+            description: `Read core module: ${coreFile}`,
+            args: { bundleId, file: coreFile, withLineNumbers: true },
+        });
+    }
+    // Suggest dependency analysis for a specific file if entry point identified
+    if (deps && deps.topImporters.length > 0) {
+        const entryFile = deps.topImporters[0].file;
+        nextCommands.push({
+            tool: 'preflight_evidence_dependency_graph',
+            description: `Analyze dependencies of entry point: ${entryFile}`,
+            args: { bundleId, target: { file: entryFile } },
+        });
+    }
+    // Suggest trace discovery if no traces exist
+    if (!traces || traces.totalLinks === 0) {
+        nextCommands.push({
+            tool: 'preflight_suggest_traces',
+            description: 'Auto-discover test↔code relationships',
+            args: { bundleId, edge_type: 'tested_by', scope: 'repo' },
+        });
+    }
+    // Suggest focused tree if large directory detected
+    if (tree) {
+        const largeDir = tree.topDirs.find(d => d.fileCount > 50);
+        if (largeDir) {
+            nextCommands.push({
+                tool: 'preflight_repo_tree',
+                description: `Explore large directory: ${largeDir.path}`,
+                args: { bundleId, focusDir: largeDir.path, depth: 6 },
+            });
+        }
+    }
     // Add checklist and claims to summary
     summaryParts.push(`## Analysis Checklist`);
     const checklistItems = [
@@ -307,11 +371,104 @@ export function buildDeepAnalysis(bundleId, components) {
         search,
         deps,
         traces,
+        overviewContent,
+        testInfo,
         claims,
         checklistStatus,
         openQuestions,
         coverageReport,
         summary: summaryParts.join('\n'),
         nextSteps,
+        nextCommands,
+    };
+}
+/**
+ * Detect test setup from file tree statistics.
+ * Scans for test directories, test files, and framework config files.
+ */
+export function detectTestInfo(stats, filesFound) {
+    const testDirs = [];
+    let testFileCount = 0;
+    const configFiles = [];
+    let framework = null;
+    // Common test directory patterns
+    const testDirPatterns = ['tests', 'test', '__tests__', 'spec', 'specs', 'e2e', 'integration'];
+    // Check byTopDir for test directories
+    if (stats.byTopDir) {
+        for (const [dir, count] of Object.entries(stats.byTopDir)) {
+            const dirLower = dir.toLowerCase();
+            if (testDirPatterns.some(p => dirLower === p || dirLower.endsWith('/' + p))) {
+                testDirs.push(dir);
+                testFileCount += count;
+            }
+        }
+    }
+    // Framework detection from config files (if filesFound provided)
+    const frameworkConfigs = [
+        { pattern: /^jest\.config\.(js|ts|mjs|cjs|json)$/i, framework: 'jest' },
+        { pattern: /^vitest\.config\.(js|ts|mjs|cjs)$/i, framework: 'vitest' },
+        { pattern: /^pytest\.ini$/i, framework: 'pytest' },
+        { pattern: /^pyproject\.toml$/i, framework: 'pytest' }, // May contain pytest config
+        { pattern: /^setup\.cfg$/i, framework: 'pytest' },
+        { pattern: /^\.mocharc\.(js|json|yml|yaml)$/i, framework: 'mocha' },
+        { pattern: /^mocha\.opts$/i, framework: 'mocha' },
+    ];
+    if (filesFound) {
+        for (const file of filesFound) {
+            for (const cfg of frameworkConfigs) {
+                if (cfg.pattern.test(file.name)) {
+                    configFiles.push(file.path);
+                    if (!framework) {
+                        framework = cfg.framework;
+                    }
+                }
+            }
+        }
+    }
+    // Infer framework from file extensions if not detected from config
+    if (!framework && stats.byExtension) {
+        // Check for test file patterns in extensions
+        const hasTs = (stats.byExtension['.ts'] ?? 0) > 0 || (stats.byExtension['.tsx'] ?? 0) > 0;
+        const hasPy = (stats.byExtension['.py'] ?? 0) > 0;
+        const hasGo = (stats.byExtension['.go'] ?? 0) > 0;
+        if (testDirs.length > 0 || testFileCount > 0) {
+            if (hasGo)
+                framework = 'go';
+            else if (hasPy)
+                framework = 'pytest';
+            else if (hasTs)
+                framework = 'unknown'; // Could be jest/vitest/mocha
+        }
+    }
+    // Count test files by pattern (approximate from extensions)
+    // This is a heuristic - actual test files may vary
+    if (testFileCount === 0 && stats.byExtension) {
+        // If no test directories found, estimate based on common patterns
+        // This is imprecise but gives a hint
+    }
+    const detected = testDirs.length > 0 || testFileCount > 0 || configFiles.length > 0;
+    // Generate hint based on detection results
+    let hint;
+    if (detected) {
+        if (testFileCount > 0) {
+            hint = `Found ${testFileCount} test files. Run preflight_suggest_traces to map code↔test relationships.`;
+        }
+        else if (configFiles.length > 0) {
+            hint = `Test config found (${configFiles[0]}). Run preflight_suggest_traces to discover test files.`;
+        }
+        else {
+            hint = `Test directories found. Run preflight_suggest_traces to map code↔test relationships.`;
+        }
+    }
+    else {
+        hint = 'No tests detected. Consider adding tests or check if test files use non-standard naming.';
+    }
+    return {
+        detected,
+        framework,
+        testDirs,
+        testFileCount,
+        configFiles,
+        hint,
     };
 }

package/dist/mcp/cursor.js

@@ -0,0 +1,145 @@
+/**
+ * RFC v2: Cursor encoding/decoding for stable pagination.
+ *
+ * Cursors are opaque, base64-encoded JSON objects that contain:
+ * - offset: The position in the result set
+ * - sortKey: The last seen sort key for stable ordering
+ * - tool: The tool that generated the cursor (for validation)
+ * - timestamp: When the cursor was created (for expiration)
+ *
+ * This enables LLMs to reliably paginate through large result sets.
+ */
+/**
+ * Maximum cursor age in milliseconds (24 hours).
+ * Cursors older than this are considered expired.
+ */
+const MAX_CURSOR_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Encode cursor state to an opaque string.
+ */
+export function encodeCursor(state) {
+    const json = JSON.stringify(state);
+    // Use base64url encoding (URL-safe, no padding)
+    return Buffer.from(json, 'utf8').toString('base64url');
+}
+/**
+ * Decode cursor string to cursor state.
+ * Returns null if the cursor is invalid.
+ */
+export function decodeCursor(cursor) {
+    try {
+        const json = Buffer.from(cursor, 'base64url').toString('utf8');
+        const state = JSON.parse(json);
+        // Validate structure
+        if (typeof state !== 'object' ||
+            state === null ||
+            typeof state.offset !== 'number' ||
+            typeof state.tool !== 'string' ||
+            typeof state.timestamp !== 'number') {
+            return null;
+        }
+        return state;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate a cursor for a specific tool.
+ * Checks structure, tool match, and expiration.
+ */
+export function validateCursor(cursor, expectedTool, options) {
+    const state = decodeCursor(cursor);
+    if (!state) {
+        return {
+            valid: false,
+            error: 'Invalid cursor format',
+        };
+    }
+    // Check tool match
+    if (!options?.allowToolMismatch && state.tool !== expectedTool) {
+        return {
+            valid: false,
+            state,
+            error: `Cursor was created by ${state.tool}, not ${expectedTool}`,
+        };
+    }
+    // Check expiration
+    const maxAge = options?.maxAgeMs ?? MAX_CURSOR_AGE_MS;
+    const age = Date.now() - state.timestamp;
+    if (age > maxAge) {
+        return {
+            valid: false,
+            state,
+            error: `Cursor expired (age: ${Math.round(age / 1000)}s, max: ${Math.round(maxAge / 1000)}s)`,
+        };
+    }
+    return {
+        valid: true,
+        state,
+    };
+}
+/**
+ * Create a cursor for the next page of results.
+ *
+ * @param tool - The tool creating the cursor
+ * @param offset - Current offset (will be incremented by pageSize)
+ * @param pageSize - Number of items per page
+ * @param sortKey - Optional sort key for keyset pagination
+ * @param extra - Optional additional data
+ */
+export function createNextCursor(tool, offset, pageSize, sortKey, extra) {
+    const state = {
+        offset: offset + pageSize,
+        tool,
+        timestamp: Date.now(),
+    };
+    if (sortKey !== undefined)
+        state.sortKey = sortKey;
+    if (extra !== undefined)
+        state.extra = extra;
+    return encodeCursor(state);
+}
+/**
+ * Parse cursor or return default offset.
+ * Convenience function for tool handlers.
+ *
+ * @param cursor - Optional cursor string
+ * @param tool - Expected tool name
+ * @param defaultOffset - Default offset if no cursor (default: 0)
+ * @returns Offset to use and any error message
+ */
+export function parseCursorOrDefault(cursor, tool, defaultOffset = 0) {
+    if (!cursor) {
+        return { offset: defaultOffset };
+    }
+    const validation = validateCursor(cursor, tool);
+    if (!validation.valid) {
+        return { offset: defaultOffset, error: validation.error };
+    }
+    return {
+        offset: validation.state.offset,
+        sortKey: validation.state.sortKey,
+        extra: validation.state.extra,
+    };
+}
+/**
+ * Helper to determine if pagination should continue.
+ *
+ * @param returnedCount - Number of items returned in this page
+ * @param limit - Requested limit
+ * @param totalCount - Optional total count (if known)
+ * @param currentOffset - Current offset in result set
+ */
+export function shouldPaginate(returnedCount, limit, totalCount, currentOffset = 0) {
+    // If we got fewer items than requested, we're at the end
+    if (returnedCount < limit) {
+        return false;
+    }
+    // If we know the total and have fetched everything, no more pages
+    if (totalCount !== undefined && currentOffset + returnedCount >= totalCount) {
+        return false;
+    }
+    // Otherwise, assume there might be more
+    return true;
+}

package/dist/mcp/envelope.js

@@ -0,0 +1,61 @@
+/**
+ * RFC v2: Unified Response Envelope for all Preflight MCP tools.
+ *
+ * This module defines the standardized response structure that enables:
+ * - LLM-friendly JSON output with stable field names
+ * - Evidence-first design with traceable citations
+ * - Pagination/truncation support with cursor-based continuation
+ * - Structured error handling with recovery hints
+ */
+/**
+ * Schema version for response envelope.
+ * Increment when making breaking changes to envelope structure.
+ */
+export const SCHEMA_VERSION = '2.0';
+/**
+ * Type guard to check if response is successful.
+ */
+export function isSuccessResponse(response) {
+    return response.ok === true && response.data !== undefined;
+}
+/**
+ * Type guard to check if response is an error.
+ */
+export function isErrorResponse(response) {
+    return response.ok === false && response.error !== undefined;
+}
+/**
+ * Helper to create a source range from line numbers.
+ */
+export function createRange(startLine, endLine, startCol, endCol) {
+    const range = { startLine, endLine };
+    if (startCol !== undefined)
+        range.startCol = startCol;
+    if (endCol !== undefined)
+        range.endCol = endCol;
+    return range;
+}
+/**
+ * Helper to create an evidence pointer.
+ */
+export function createEvidencePointer(path, range, options) {
+    const pointer = { path, range };
+    if (options?.uri)
+        pointer.uri = options.uri;
+    if (options?.snippet)
+        pointer.snippet = options.snippet;
+    if (options?.snippetSha256)
+        pointer.snippetSha256 = options.snippetSha256;
+    return pointer;
+}
+/**
+ * Format evidence pointer as citation string.
+ * Format: "path:startLine-endLine" or "path:line" for single line
+ */
+export function formatEvidenceCitation(pointer) {
+    const { path, range } = pointer;
+    if (range.startLine === range.endLine) {
+        return `${path}:${range.startLine}`;
+    }
+    return `${path}:${range.startLine}-${range.endLine}`;
+}

package/dist/mcp/errorKinds.js

@@ -72,6 +72,41 @@ const LLM_RECOVERY_HINTS = {
 This parameter is deprecated. The tool is now strictly read-only.
 - For updates: use preflight_update_bundle first, then retry
 - For repairs: use preflight_repair_bundle first, then retry`,
+    // RFC v2 additions
+    cursor_invalid: `💡 Recovery steps:
+1. The cursor format is invalid or corrupted
+2. Start fresh without a cursor to get the first page
+3. Use the nextCursor from the previous response exactly as provided`,
+    cursor_expired: `💡 Recovery steps:
+1. Cursors expire after 24 hours
+2. Start fresh without a cursor to get the first page
+3. Complete pagination within a reasonable time window`,
+    cursor_tool_mismatch: `💡 Recovery steps:
+1. The cursor was created by a different tool
+2. Use the cursor only with the same tool that created it
+3. Start fresh without a cursor for this tool`,
+    rate_limited: `💡 Recovery steps:
+1. You are making requests too quickly
+2. Wait a few seconds before retrying
+3. Consider batching multiple operations into single calls`,
+    timeout: `💡 Recovery steps:
+1. The operation took too long to complete
+2. Try with a smaller scope or limit
+3. Use cursor pagination to process in smaller batches`,
+    pagination_required: `💡 Note:
+The result set is large. Use cursor pagination:
+1. Check the 'truncation' field in the response
+2. Pass the 'nextCursor' value in subsequent calls
+3. Continue until truncated=false`,
+    validation_error: `💡 Recovery steps:
+1. Check that all required parameters are provided
+2. Verify parameter types match the schema
+3. Review the error message for specific field issues`,
+    partial_success: `💡 Note:
+Some operations succeeded but others failed:
+1. Check the 'warnings' array for details on failed items
+2. Address individual issues and retry failed items
+3. Successfully processed items are already applied`,
     unknown: `💡 If this error persists:
 1. Check the error message for specific details
 2. Verify your input parameters match the tool's schema