preflight-mcp 0.5.2 → 0.5.3

package/README.md

@@ -51,7 +51,7 @@ 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
-- ⚡ **22 MCP tools + 5 prompts** — Complete toolkit for code exploration
+- ⚡ **21 MCP tools + 5 prompts** — Complete toolkit for code exploration
 - 📄 **Cursor pagination** — Handle large result sets efficiently (RFC v2)
 
 <details>
@@ -76,7 +76,7 @@ Preflight: 🔗 Trace links:
 - [Demo](#demo)
 - [Core Features](#core-features)
 - [Quick Start](#quick-start)
-- [Tools](#tools-22-total)
+- [Tools](#tools-21-total)
 - [Prompts](#prompts-5-total)
 - [Environment Variables](#environment-variables)
 - [Contributing](#contributing)
@@ -161,7 +161,7 @@ Run end-to-end smoke test:
 npm run smoke
 ```
 
-## Tools (22 total)
+## Tools (21 total)
 
 ### `preflight_list_bundles`
 List bundle IDs in storage.
@@ -191,12 +191,31 @@ Input (example):
 **Note**: If the bundle contains code files, consider using `preflight_evidence_dependency_graph` for dependency analysis or `preflight_trace_upsert` for trace links.
 
 ### `preflight_read_file`
-Read file(s) from bundle. Two modes:
+Read file(s) from bundle. Multiple modes:
 - **Batch mode** (omit `file`): Returns ALL key files (OVERVIEW.md, START_HERE.md, AGENTS.md, manifest.json, deps/dependency-graph.json, repo READMEs) in one call
 - **Single file mode** (provide `file`): Returns that specific file
 - **Evidence citation**: Use `withLineNumbers: true` to get `N|line` format; use `ranges: ["20-80"]` to read specific lines
 - Triggers: "查看bundle", "bundle概览", "项目信息", "show bundle", "读取依赖图"
 
+**NEW in v0.5.3 - Symbol outline & reading:**
+- `outline: true`: Returns symbol structure (function/class/method/interface/type/enum) with line ranges
+  - Supports: `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`
+  - 90%+ token savings for understanding file structure
+- `symbol: "name"`: Read a specific symbol by name
+  - Format: `"functionName"` or `"ClassName.methodName"`
+  - Auto-includes context lines and returns with line numbers
+
+**Example - Outline mode:**
+```
+[src/server.ts] Outline (15 top-level symbols, typescript):
+├── ⚡function startServer(): Promise<void> :174-200
+├── ⚡class McpServer :205-400
+│   ├── method registerTool :210-250
+│   └── method start :380-400
+└── ⚡interface Config :45-71
+```
+(`⚡` = exported)
+
 ### `preflight_repo_tree`
 Get repository structure overview without wasting tokens on search.
 - Returns: ASCII directory tree, file count by extension/directory, entry point candidates

package/README.zh-CN.md

@@ -209,12 +209,31 @@ npm run smoke
 **💡 提示**：对于代码仓库，创建 bundle 后可进一步使用 `preflight_evidence_dependency_graph` 获取依赖图，或使用 `preflight_trace_upsert` 记录代码←→需求/测试的追溯链接。
 
 ### `preflight_read_file`
-从 bundle 读取文件。两种模式：
-- **批量模式**（省略 `file`）：返回所有关键文件
+从 bundle 读取文件。多种模式：
+- **批量模式**（省略 `file`）：返回所有关键文件（OVERVIEW.md、START_HERE.md、AGENTS.md、manifest.json 等）
 - **单文件模式**（提供 `file`）：返回指定文件
 - **证据引用**：使用 `withLineNumbers: true` 获取 `N|行` 格式；使用 `ranges: ["20-80"]` 读取指定行
 - 触发词：「查看概览」「项目概览」「bundle详情」「读取依赖图」
 
+**v0.5.3 新增 - 符号大纲与按符号读取：**
+- `outline: true`：返回文件的符号结构（function/class/method/interface/type/enum），附带行号范围
+  - 支持：`.ts`、`.tsx`、`.js`、`.jsx`、`.py`、`.go`、`.rs`
+  - 理解文件结构可节省 90%+ token
+- `symbol: "name"`：按名称读取特定符号
+  - 格式：`"functionName"` 或 `"ClassName.methodName"`
+  - 自动包含上下文行并返回带行号的内容
+
+**示例 - 大纲模式：**
+```
+[src/server.ts] Outline (15 top-level symbols, typescript):
+├── ⚡function startServer(): Promise<void> :174-200
+├── ⚡class McpServer :205-400
+│   ├── method registerTool :210-250
+│   └── method start :380-400
+└── ⚡interface Config :45-71
+```
+（`⚡` = 已导出）
+
 ### `preflight_repo_tree`
 获取仓库结构概览，避免浪费 token 搜索。
 - 返回：ASCII 目录树、按扩展名/目录统计文件数、入口点候选

package/dist/ast/treeSitter.js

@@ -586,3 +586,613 @@ export async function extractExportedSymbolsWasm(filePath, normalizedContent) {
         return null;
     return { language: res.language, exports: res.exports };
 }
+// ============================================================================
+// Outline extraction (symbol structure for code navigation)
+// ============================================================================
+/**
+ * Check if a node is preceded by an export keyword (for JS/TS).
+ */
+function isExportedJsTs(node) {
+    const parent = node.parent;
+    if (!parent)
+        return false;
+    // Direct export: export function foo() {}
+    if (parent.type === 'export_statement')
+        return true;
+    // export default function foo() {}
+    if (parent.type === 'export_statement' && parent.text.includes('default'))
+        return true;
+    return false;
+}
+/**
+ * Extract function signature from a function declaration node.
+ */
+function extractFunctionSignatureJsTs(node) {
+    const params = node.childForFieldName('parameters');
+    const returnType = node.childForFieldName('return_type');
+    if (!params)
+        return undefined;
+    let sig = params.text;
+    if (returnType) {
+        sig += `: ${returnType.text}`;
+    }
+    return sig;
+}
+/**
+ * Extract method signature from a method definition node.
+ */
+function extractMethodSignatureJsTs(node) {
+    const params = node.childForFieldName('parameters');
+    const returnType = node.childForFieldName('return_type');
+    if (!params)
+        return undefined;
+    let sig = params.text;
+    if (returnType) {
+        sig += `: ${returnType.text}`;
+    }
+    return sig;
+}
+/**
+ * Extract class methods as children.
+ */
+function extractClassMethodsJsTs(classNode) {
+    const methods = [];
+    const body = classNode.childForFieldName('body');
+    if (!body)
+        return methods;
+    for (const child of body.namedChildren) {
+        if (child.type === 'method_definition' || child.type === 'public_field_definition') {
+            const name = child.childForFieldName('name');
+            if (!name)
+                continue;
+            const isMethod = child.type === 'method_definition';
+            methods.push({
+                kind: isMethod ? 'method' : 'variable',
+                name: name.text,
+                signature: isMethod ? extractMethodSignatureJsTs(child) : undefined,
+                range: {
+                    startLine: child.startPosition.row + 1,
+                    endLine: child.endPosition.row + 1,
+                },
+                exported: true, // Class members are implicitly accessible
+            });
+        }
+    }
+    return methods;
+}
+/**
+ * Extract outline from JavaScript/TypeScript/TSX files.
+ */
+function extractOutlineJsTs(root, lang) {
+    const outline = [];
+    // Collect all exported names for checking
+    const exportedNames = new Set();
+    for (const st of root.descendantsOfType('export_statement')) {
+        // export { name1, name2 }
+        const clause = st.descendantsOfType('export_clause')[0];
+        if (clause) {
+            for (const spec of clause.descendantsOfType('export_specifier')) {
+                const name = spec.childForFieldName('name');
+                if (name)
+                    exportedNames.add(name.text);
+            }
+        }
+    }
+    for (const child of root.namedChildren) {
+        // Handle export statements
+        let actualNode = child;
+        let isExported = false;
+        if (child.type === 'export_statement') {
+            isExported = true;
+            // Get the actual declaration inside
+            const decl = child.namedChildren.find(n => n.type !== 'export_clause' &&
+                n.type !== 'string' &&
+                n.type !== 'comment');
+            if (decl) {
+                actualNode = decl;
+            }
+            else {
+                continue; // export { ... } without declaration
+            }
+        }
+        const name = actualNode.childForFieldName('name');
+        switch (actualNode.type) {
+            case 'function_declaration': {
+                if (!name)
+                    continue;
+                outline.push({
+                    kind: 'function',
+                    name: name.text,
+                    signature: extractFunctionSignatureJsTs(actualNode),
+                    range: {
+                        startLine: actualNode.startPosition.row + 1,
+                        endLine: actualNode.endPosition.row + 1,
+                    },
+                    exported: isExported || exportedNames.has(name.text),
+                });
+                break;
+            }
+            case 'class_declaration': {
+                if (!name)
+                    continue;
+                const children = extractClassMethodsJsTs(actualNode);
+                outline.push({
+                    kind: 'class',
+                    name: name.text,
+                    range: {
+                        startLine: actualNode.startPosition.row + 1,
+                        endLine: actualNode.endPosition.row + 1,
+                    },
+                    exported: isExported || exportedNames.has(name.text),
+                    children: children.length > 0 ? children : undefined,
+                });
+                break;
+            }
+            case 'interface_declaration': {
+                if (!name)
+                    continue;
+                outline.push({
+                    kind: 'interface',
+                    name: name.text,
+                    range: {
+                        startLine: actualNode.startPosition.row + 1,
+                        endLine: actualNode.endPosition.row + 1,
+                    },
+                    exported: isExported || exportedNames.has(name.text),
+                });
+                break;
+            }
+            case 'type_alias_declaration': {
+                if (!name)
+                    continue;
+                outline.push({
+                    kind: 'type',
+                    name: name.text,
+                    range: {
+                        startLine: actualNode.startPosition.row + 1,
+                        endLine: actualNode.endPosition.row + 1,
+                    },
+                    exported: isExported || exportedNames.has(name.text),
+                });
+                break;
+            }
+            case 'enum_declaration': {
+                if (!name)
+                    continue;
+                outline.push({
+                    kind: 'enum',
+                    name: name.text,
+                    range: {
+                        startLine: actualNode.startPosition.row + 1,
+                        endLine: actualNode.endPosition.row + 1,
+                    },
+                    exported: isExported || exportedNames.has(name.text),
+                });
+                break;
+            }
+            case 'lexical_declaration':
+            case 'variable_declaration': {
+                // const/let/var declarations
+                for (const decl of actualNode.descendantsOfType('variable_declarator')) {
+                    const varName = decl.childForFieldName('name');
+                    if (!varName || varName.type !== 'identifier')
+                        continue;
+                    // Check if it's an arrow function
+                    const value = decl.childForFieldName('value');
+                    const isArrowFn = value?.type === 'arrow_function';
+                    outline.push({
+                        kind: isArrowFn ? 'function' : 'variable',
+                        name: varName.text,
+                        signature: isArrowFn ? extractFunctionSignatureJsTs(value) : undefined,
+                        range: {
+                            startLine: decl.startPosition.row + 1,
+                            endLine: decl.endPosition.row + 1,
+                        },
+                        exported: isExported || exportedNames.has(varName.text),
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return outline;
+}
+/**
+ * Extract function signature from Python function definition.
+ */
+function extractFunctionSignaturePython(node) {
+    const params = node.childForFieldName('parameters');
+    const returnType = node.childForFieldName('return_type');
+    if (!params)
+        return undefined;
+    let sig = params.text;
+    if (returnType) {
+        sig += ` -> ${returnType.text}`;
+    }
+    return sig;
+}
+/**
+ * Extract class methods for Python.
+ */
+function extractClassMethodsPython(classNode) {
+    const methods = [];
+    const body = classNode.childForFieldName('body');
+    if (!body)
+        return methods;
+    for (const child of body.namedChildren) {
+        if (child.type === 'function_definition') {
+            const name = child.childForFieldName('name');
+            if (!name)
+                continue;
+            const methodName = name.text;
+            // Skip private methods (starting with __) except __init__
+            const isPrivate = methodName.startsWith('_') && methodName !== '__init__';
+            methods.push({
+                kind: 'method',
+                name: methodName,
+                signature: extractFunctionSignaturePython(child),
+                range: {
+                    startLine: child.startPosition.row + 1,
+                    endLine: child.endPosition.row + 1,
+                },
+                exported: !isPrivate,
+            });
+        }
+    }
+    return methods;
+}
+/**
+ * Extract outline from Python files.
+ */
+function extractOutlinePython(root) {
+    const outline = [];
+    // Check __all__ for explicit exports
+    const exportedNames = new Set();
+    for (const asn of root.descendantsOfType(['assignment', 'assignment_statement'])) {
+        const left = asn.childForFieldName('left') ?? asn.namedChild(0);
+        if (!left || left.text !== '__all__')
+            continue;
+        const right = asn.childForFieldName('right') ?? asn.namedChild(asn.namedChildCount - 1);
+        if (!right)
+            continue;
+        // Extract names from list/tuple
+        for (const s of right.descendantsOfType('string')) {
+            const inner = s.text.replace(/^['"]|['"]$/g, '');
+            if (inner)
+                exportedNames.add(inner);
+        }
+    }
+    const hasExplicitAll = exportedNames.size > 0;
+    for (const child of root.namedChildren) {
+        switch (child.type) {
+            case 'function_definition': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const funcName = name.text;
+                // Public if: in __all__, or doesn't start with _ (when no __all__)
+                const isPublic = hasExplicitAll
+                    ? exportedNames.has(funcName)
+                    : !funcName.startsWith('_');
+                outline.push({
+                    kind: 'function',
+                    name: funcName,
+                    signature: extractFunctionSignaturePython(child),
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isPublic,
+                });
+                break;
+            }
+            case 'class_definition': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const className = name.text;
+                const isPublic = hasExplicitAll
+                    ? exportedNames.has(className)
+                    : !className.startsWith('_');
+                const methods = extractClassMethodsPython(child);
+                outline.push({
+                    kind: 'class',
+                    name: className,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isPublic,
+                    children: methods.length > 0 ? methods : undefined,
+                });
+                break;
+            }
+        }
+    }
+    return outline;
+}
+/**
+ * Extract outline from Go files.
+ */
+function extractOutlineGo(root) {
+    const outline = [];
+    for (const child of root.namedChildren) {
+        switch (child.type) {
+            case 'function_declaration': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const funcName = name.text;
+                // Go: exported if starts with uppercase
+                const isExported = /^[A-Z]/.test(funcName);
+                // Extract signature
+                const params = child.childForFieldName('parameters');
+                const result = child.childForFieldName('result');
+                let sig = params?.text || '()';
+                if (result)
+                    sig += ` ${result.text}`;
+                outline.push({
+                    kind: 'function',
+                    name: funcName,
+                    signature: sig,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isExported,
+                });
+                break;
+            }
+            case 'method_declaration': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const methodName = name.text;
+                const isExported = /^[A-Z]/.test(methodName);
+                // Get receiver type
+                const receiver = child.childForFieldName('receiver');
+                const params = child.childForFieldName('parameters');
+                const result = child.childForFieldName('result');
+                let sig = params?.text || '()';
+                if (result)
+                    sig += ` ${result.text}`;
+                if (receiver)
+                    sig = `${receiver.text} ${sig}`;
+                outline.push({
+                    kind: 'method',
+                    name: methodName,
+                    signature: sig,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isExported,
+                });
+                break;
+            }
+            case 'type_declaration': {
+                // type Foo struct { ... } or type Bar interface { ... }
+                for (const spec of child.descendantsOfType('type_spec')) {
+                    const name = spec.childForFieldName('name');
+                    if (!name)
+                        continue;
+                    const typeName = name.text;
+                    const isExported = /^[A-Z]/.test(typeName);
+                    // Determine kind based on type definition
+                    const typeNode = spec.childForFieldName('type');
+                    let kind = 'type';
+                    if (typeNode?.type === 'struct_type')
+                        kind = 'class'; // Treat struct as class
+                    else if (typeNode?.type === 'interface_type')
+                        kind = 'interface';
+                    outline.push({
+                        kind,
+                        name: typeName,
+                        range: {
+                            startLine: spec.startPosition.row + 1,
+                            endLine: spec.endPosition.row + 1,
+                        },
+                        exported: isExported,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return outline;
+}
+/**
+ * Extract outline from Rust files.
+ */
+function extractOutlineRust(root) {
+    const outline = [];
+    for (const child of root.namedChildren) {
+        switch (child.type) {
+            case 'function_item': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const funcName = name.text;
+                const isExported = hasRustPubVisibility(child);
+                // Extract signature
+                const params = child.childForFieldName('parameters');
+                const returnType = child.childForFieldName('return_type');
+                let sig = params?.text || '()';
+                if (returnType)
+                    sig += ` -> ${returnType.text}`;
+                outline.push({
+                    kind: 'function',
+                    name: funcName,
+                    signature: sig,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isExported,
+                });
+                break;
+            }
+            case 'struct_item': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const structName = name.text;
+                const isExported = hasRustPubVisibility(child);
+                outline.push({
+                    kind: 'class', // Treat struct as class
+                    name: structName,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isExported,
+                });
+                break;
+            }
+            case 'enum_item': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const enumName = name.text;
+                const isExported = hasRustPubVisibility(child);
+                outline.push({
+                    kind: 'enum',
+                    name: enumName,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isExported,
+                });
+                break;
+            }
+            case 'trait_item': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const traitName = name.text;
+                const isExported = hasRustPubVisibility(child);
+                outline.push({
+                    kind: 'interface', // Treat trait as interface
+                    name: traitName,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isExported,
+                });
+                break;
+            }
+            case 'type_item': {
+                const name = child.childForFieldName('name');
+                if (!name)
+                    continue;
+                const typeName = name.text;
+                const isExported = hasRustPubVisibility(child);
+                outline.push({
+                    kind: 'type',
+                    name: typeName,
+                    range: {
+                        startLine: child.startPosition.row + 1,
+                        endLine: child.endPosition.row + 1,
+                    },
+                    exported: isExported,
+                });
+                break;
+            }
+            case 'impl_item': {
+                // Extract methods from impl blocks
+                const typeNode = child.childForFieldName('type');
+                const typeName = typeNode?.text || 'impl';
+                // Find all function_items inside the impl
+                const body = child.childForFieldName('body');
+                if (!body)
+                    continue;
+                const methods = [];
+                for (const item of body.namedChildren) {
+                    if (item.type === 'function_item') {
+                        const name = item.childForFieldName('name');
+                        if (!name)
+                            continue;
+                        const methodName = name.text;
+                        const isExported = hasRustPubVisibility(item);
+                        const params = item.childForFieldName('parameters');
+                        const returnType = item.childForFieldName('return_type');
+                        let sig = params?.text || '()';
+                        if (returnType)
+                            sig += ` -> ${returnType.text}`;
+                        methods.push({
+                            kind: 'method',
+                            name: methodName,
+                            signature: sig,
+                            range: {
+                                startLine: item.startPosition.row + 1,
+                                endLine: item.endPosition.row + 1,
+                            },
+                            exported: isExported,
+                        });
+                    }
+                }
+                if (methods.length > 0) {
+                    outline.push({
+                        kind: 'class', // impl block as a class-like container
+                        name: `impl ${typeName}`,
+                        range: {
+                            startLine: child.startPosition.row + 1,
+                            endLine: child.endPosition.row + 1,
+                        },
+                        exported: true, // impl blocks are always "public" in terms of structure
+                        children: methods,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return outline;
+}
+/**
+ * Extract symbol outline from a source file.
+ * Returns null if the file type is not supported.
+ */
+export async function extractOutlineWasm(filePath, normalizedContent) {
+    const lang = languageForFile(filePath);
+    if (!lang)
+        return null;
+    // Supported languages: JS/TS, Python, Go, Rust
+    if (!['javascript', 'typescript', 'tsx', 'python', 'go', 'rust'].includes(lang)) {
+        return null;
+    }
+    const language = await loadLanguage(lang);
+    const parser = new Parser();
+    try {
+        parser.setLanguage(language);
+        const tree = parser.parse(normalizedContent);
+        if (!tree)
+            return { language: lang, outline: [] };
+        try {
+            const root = tree.rootNode;
+            let outline;
+            switch (lang) {
+                case 'python':
+                    outline = extractOutlinePython(root);
+                    break;
+                case 'go':
+                    outline = extractOutlineGo(root);
+                    break;
+                case 'rust':
+                    outline = extractOutlineRust(root);
+                    break;
+                default:
+                    outline = extractOutlineJsTs(root, lang);
+            }
+            return { language: lang, outline };
+        }
+        finally {
+            tree.delete();
+        }
+    }
+    finally {
+        parser.delete();
+    }
+}

package/dist/server.js

@@ -21,6 +21,7 @@ import { suggestTestedByTraces } from './trace/suggest.js';
 import { generateRepoTree, formatTreeResult } from './bundle/tree.js';
 import { buildDeepAnalysis, detectTestInfo } from './analysis/deep.js';
 import { validateReport } from './analysis/validate.js';
+import { extractOutlineWasm } from './ast/treeSitter.js';
 // RFC v2: New aggregation tools
 import { ReadFilesInputSchema, createReadFilesHandler, readFilesToolDescription } from './tools/readFiles.js';
 import { SearchAndReadInputSchema, createSearchAndReadHandler, searchAndReadToolDescription } from './tools/searchAndRead.js';
@@ -147,7 +148,7 @@ export async function startServer() {
     startHttpServer(cfg);
     const server = new McpServer({
         name: 'preflight-mcp',
-        version: '0.5.2',
+        version: '0.5.3',
         description: 'Create evidence-based preflight bundles for repositories (docs + code) with SQLite FTS search.',
     }, {
         capabilities: {
@@ -390,6 +391,16 @@ export async function startServer() {
             includeDepsGraph: z.boolean().optional().default(false).describe('Include deps/dependency-graph.json in batch mode.'),
             withLineNumbers: z.boolean().optional().default(false).describe('If true, prefix each line with line number in "N|" format for evidence citation.'),
             ranges: z.array(z.string()).optional().describe('Line ranges to read, e.g. ["20-80", "100-120"]. Each range is "start-end" (1-indexed, inclusive). If omitted, reads entire file.'),
+            // NEW: outline mode for code structure extraction
+            outline: z.boolean().optional().default(false).describe('If true, return symbol outline instead of file content. ' +
+                'Returns function/class/method/interface/type/enum with line ranges. ' +
+                'Saves tokens by showing code structure without full content. ' +
+                'Supports: .ts, .tsx, .js, .jsx, .py, .go, .rs files.'),
+            // NEW: symbol-based reading
+            symbol: z.string().optional().describe('Read a specific symbol (function/class/method) by name. ' +
+                'Format: "functionName" or "ClassName" or "ClassName.methodName". ' +
+                'Automatically locates and returns the symbol\'s code with context. ' +
+                'Requires outline-supported file types (.ts, .tsx, .js, .jsx, .py).'),
         },
         outputSchema: {
             bundleId: z.string(),
@@ -405,6 +416,16 @@ export async function startServer() {
                     end: z.number(),
                 })),
             }).optional(),
+            // NEW: outline output
+            outline: z.array(z.object({
+                kind: z.enum(['function', 'class', 'method', 'interface', 'type', 'enum', 'variable']),
+                name: z.string(),
+                signature: z.string().optional(),
+                range: z.object({ startLine: z.number(), endLine: z.number() }),
+                exported: z.boolean(),
+                children: z.array(z.any()).optional(),
+            })).optional().describe('Symbol outline (when outline=true).'),
+            language: z.string().optional().describe('Detected language (when outline=true).'),
         },
         annotations: {
             readOnlyHint: true,
@@ -460,6 +481,115 @@ export async function startServer() {
             if (args.file) {
                 const absPath = safeJoin(bundleRoot, args.file);
                 const rawContent = await fs.readFile(absPath, 'utf8');
+                const normalizedContent = rawContent.replace(/\r\n/g, '\n');
+                // NEW: Outline mode - extract symbol structure
+                if (args.outline) {
+                    const outlineResult = await extractOutlineWasm(args.file, normalizedContent);
+                    if (!outlineResult) {
+                        // Unsupported file type
+                        return {
+                            content: [{ type: 'text', text: `[${args.file}] Outline not supported for this file type. Supported: .ts, .tsx, .js, .jsx` }],
+                            structuredContent: {
+                                bundleId: args.bundleId,
+                                file: args.file,
+                                outline: null,
+                                language: null,
+                            },
+                        };
+                    }
+                    // Format outline as readable text
+                    const formatOutlineText = (symbols, indent = '') => {
+                        const lines = [];
+                        for (let i = 0; i < symbols.length; i++) {
+                            const sym = symbols[i];
+                            const isLast = i === symbols.length - 1;
+                            const prefix = indent + (isLast ? '└── ' : '├── ');
+                            const exportMark = sym.exported ? '⚡' : '';
+                            const sig = sym.signature ? sym.signature : '';
+                            lines.push(`${prefix}${exportMark}${sym.kind} ${sym.name}${sig} :${sym.range.startLine}-${sym.range.endLine}`);
+                            if (sym.children && sym.children.length > 0) {
+                                const childIndent = indent + (isLast ? '    ' : '│   ');
+                                lines.push(...formatOutlineText(sym.children, childIndent));
+                            }
+                        }
+                        return lines;
+                    };
+                    const outlineText = formatOutlineText(outlineResult.outline);
+                    const totalSymbols = outlineResult.outline.length;
+                    const header = `[${args.file}] Outline (${totalSymbols} top-level symbols, ${outlineResult.language}):\n`;
+                    return {
+                        content: [{ type: 'text', text: header + outlineText.join('\n') }],
+                        structuredContent: {
+                            bundleId: args.bundleId,
+                            file: args.file,
+                            outline: outlineResult.outline,
+                            language: outlineResult.language,
+                        },
+                    };
+                }
+                // NEW: Symbol-based reading - locate and read a specific symbol
+                if (args.symbol) {
+                    const outlineResult = await extractOutlineWasm(args.file, normalizedContent);
+                    if (!outlineResult) {
+                        return {
+                            content: [{ type: 'text', text: `[${args.file}] Symbol lookup not supported for this file type. Supported: .ts, .tsx, .js, .jsx, .py` }],
+                            structuredContent: { bundleId: args.bundleId, file: args.file, error: 'unsupported_file_type' },
+                        };
+                    }
+                    // Parse symbol query: "funcName" or "ClassName.methodName"
+                    const parts = args.symbol.split('.');
+                    const targetName = parts[0];
+                    const methodName = parts[1];
+                    // Find the symbol in outline
+                    let foundSymbol;
+                    let foundIn = 'top';
+                    for (const sym of outlineResult.outline) {
+                        if (sym.name === targetName) {
+                            if (methodName && sym.children) {
+                                // Looking for a method inside this class
+                                const method = sym.children.find(c => c.name === methodName);
+                                if (method) {
+                                    foundSymbol = method;
+                                    foundIn = 'child';
+                                    break;
+                                }
+                            }
+                            else {
+                                foundSymbol = sym;
+                                break;
+                            }
+                        }
+                    }
+                    if (!foundSymbol) {
+                        // Symbol not found - provide helpful error with available symbols
+                        const available = outlineResult.outline.map(s => {
+                            if (s.children && s.children.length > 0) {
+                                return `${s.name} (${s.kind}, methods: ${s.children.map(c => c.name).join(', ')})`;
+                            }
+                            return `${s.name} (${s.kind})`;
+                        }).join(', ');
+                        return {
+                            content: [{ type: 'text', text: `[${args.file}] Symbol "${args.symbol}" not found.\n\nAvailable symbols: ${available}` }],
+                            structuredContent: { bundleId: args.bundleId, file: args.file, error: 'symbol_not_found', available: outlineResult.outline.map(s => s.name) },
+                        };
+                    }
+                    // Read the symbol's code (with 2 lines of context before)
+                    const contextLines = 2;
+                    const startLine = Math.max(1, foundSymbol.range.startLine - contextLines);
+                    const endLine = foundSymbol.range.endLine;
+                    const { content, lineInfo } = formatContent(rawContent, true, [{ start: startLine, end: endLine }]);
+                    const header = `[${args.file}:${startLine}-${endLine}] ${foundSymbol.kind} ${foundSymbol.name}${foundSymbol.signature || ''}\n\n`;
+                    return {
+                        content: [{ type: 'text', text: header + content }],
+                        structuredContent: {
+                            bundleId: args.bundleId,
+                            file: args.file,
+                            symbol: foundSymbol,
+                            content,
+                            lineInfo,
+                        },
+                    };
+                }
                 // Parse ranges if provided
                 let parsedRanges;
                 if (args.ranges && args.ranges.length > 0) {

package/package.json

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