@zokizuan/satori-mcp 3.0.0 → 3.1.0

package/README.md

@@ -7,13 +7,14 @@ MCP server for Satori — agent-safe semantic code search and indexing.
 - Capability-driven execution via `CapabilityResolver`
 - Runtime-first `search_codebase` with explicit `scope`, `resultMode`, `groupBy`, and optional `debug` traces
 - First-class `call_graph` tool with deterministic node/edge sorting and TS/Python support
+- Sidecar-backed `file_outline` tool for per-file symbol navigation and direct call_graph jump handles
 - Snapshot v3 safety with index fingerprints and strict `requires_reindex` access gates
 - Deterministic train-in-the-error responses for incompatible or legacy index states
 - Query-time exclusion support with `.gitignore`-style matching
 - Structured search telemetry logs (`[TELEMETRY]` JSON to `stderr`)
 - Zod-first tool schemas converted to MCP JSON Schema for `ListTools`
 - Auto-generated tool docs from live tool schemas
-- `read_file` line-range retrieval with default large-file truncation guard
+- `read_file` line-range retrieval with default large-file truncation guard and optional `mode="annotated"` metadata envelope
 - Optional proactive sync watcher mode (debounced filesystem events)
 - Index-time AST scope breadcrumbs (TS/JS/Python) rendered in search output as `🧬 Scope`
 - Fingerprint schema `dense_v3`/`hybrid_v3` with hard gate for all pre-v3 indexes
@@ -24,19 +25,20 @@ MCP server for Satori — agent-safe semantic code search and indexing.
 [MCP Client]
     -> [index.ts bootstrap + ListTools/CallTool]
     -> [tool registry]
-    -> [manage_index | search_codebase | call_graph | read_file | list_codebases]
+    -> [manage_index | search_codebase | call_graph | file_outline | read_file | list_codebases]
     -> [ToolContext DI]
        -> [CapabilityResolver]
        -> [SnapshotManager v3 + access gate]
        -> [Context / Vector store / Embedding / Reranker adapters]
 ```
 
-Tool surface is hard-broken to 5 tools. This keeps routing explicit while exposing call-chain traversal as a first-class operation.
+Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposing call-chain traversal and file-level navigation as first-class operations.
 
 ## read_file Behavior
 
 - Supports optional `start_line` and `end_line` (1-based, inclusive)
 - When no range is provided and file length exceeds `READ_FILE_MAX_LINES` (default `1000`), output is truncated and includes a continuation hint with `path` and next `start_line`
+- Optional `mode="annotated"` returns content plus `outlineStatus`, `outline`, `hasMore`, and reindex hints when sidecar data is unavailable
 
 ## Proactive Sync
 
@@ -93,6 +95,18 @@ Traverse the prebuilt TS/Python call graph sidecar for callers/callees/bidirecti
 | `depth` | integer | no | `1` | Traversal depth (max 3). |
 | `limit` | integer | no | `20` | Maximum number of returned edges. |
 
+### `file_outline`
+
+Return a sidecar-backed symbol outline for one file, including call_graph jump handles.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `path` | string | yes |  | ABSOLUTE path to the indexed codebase root. |
+| `file` | string | yes |  | Relative file path inside the codebase root. |
+| `start_line` | integer | no |  | Optional start line filter (1-based, inclusive). |
+| `end_line` | integer | no |  | Optional end line filter (1-based, inclusive). |
+| `limitSymbols` | integer | no | `500` | Maximum number of returned symbols after line filtering. |
+
 ### `read_file`
 
 Read file content from the local filesystem, with optional 1-based inclusive line ranges and safe truncation.
@@ -102,6 +116,7 @@ Read file content from the local filesystem, with optional 1-based inclusive lin
 | `path` | string | yes |  | ABSOLUTE path to the file. |
 | `start_line` | integer | no |  | Optional start line (1-based, inclusive). |
 | `end_line` | integer | no |  | Optional end line (1-based, inclusive). |
+| `mode` | enum("plain", "annotated") | no | `"plain"` | Output mode. plain returns text only; annotated returns content plus sidecar-backed outline metadata. |
 
 ### `list_codebases`
 

package/dist/core/handlers.d.ts

@@ -2,6 +2,7 @@ import { Context } from "@zokizuan/satori-core";
 import { SnapshotManager } from "./snapshot.js";
 import { SyncManager } from "./sync.js";
 import { IndexFingerprint } from "../config.js";
+import { FileOutlineInput } from "./search-types.js";
 import { CallGraphSidecarManager } from "./call-graph.js";
 export declare class ToolHandlers {
     private context;
@@ -26,6 +27,7 @@ export declare class ToolHandlers {
     private getBreadcrumbMergeKey;
     private formatScopeLine;
     private normalizeSearchPath;
+    private hasPathSegment;
     private isTestPath;
     private isDocPath;
     private isGeneratedPath;
@@ -39,6 +41,11 @@ export declare class ToolHandlers {
     private buildFallbackGroupId;
     private isCallGraphLanguageSupported;
     private buildCallGraphHint;
+    private normalizeRelativeFilePath;
+    private buildRequiresReindexFileOutlinePayload;
+    private getOutlineStatusForLanguage;
+    private sortFileOutlineSymbols;
+    private buildSearchPassWarning;
     private mapCallGraphStatus;
     private getContextIgnorePatterns;
     private rebuildCallGraphForIndex;
@@ -115,9 +122,33 @@ export declare class ToolHandlers {
                 excludedBySubdirectory: number;
                 filterPass: "initial" | "expanded";
                 freshnessMode: string | undefined;
+                searchPassCount: number;
+                searchPassSuccessCount: number;
+                searchPassFailureCount: number;
             };
         };
         isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+        meta: {
+            searchDiagnostics: {
+                queryLength: number;
+                limitRequested: number;
+                resultsBeforeFilter: number;
+                resultsAfterFilter: number;
+                excludedByIgnore: number;
+                excludedBySubdirectory: number;
+                filterPass: "initial" | "expanded";
+                freshnessMode: string | undefined;
+                searchPassCount: number;
+                searchPassSuccessCount: number;
+                searchPassFailureCount: number;
+            };
+        };
     } | {
         content: {
             type: string;
@@ -126,6 +157,19 @@ export declare class ToolHandlers {
         isError?: undefined;
         meta?: undefined;
     }>;
+    handleFileOutline(args: FileOutlineInput): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
     handleCallGraph(args: any): Promise<{
         content: {
             type: string;

package/dist/core/handlers.js

@@ -328,15 +328,24 @@ export class ToolHandlers {
     normalizeSearchPath(relativePath) {
         return relativePath.replace(/\\/g, '/').replace(/^\/+/, '').toLowerCase();
     }
+    hasPathSegment(normalizedPath, segment) {
+        return normalizedPath === segment
+            || normalizedPath.startsWith(`${segment}/`)
+            || normalizedPath.includes(`/${segment}/`);
+    }
     isTestPath(normalizedPath) {
-        return normalizedPath.includes('/test/')
-            || normalizedPath.includes('/tests/')
-            || normalizedPath.includes('/__tests__/')
+        return this.hasPathSegment(normalizedPath, 'test')
+            || this.hasPathSegment(normalizedPath, 'tests')
+            || this.hasPathSegment(normalizedPath, '__tests__')
             || /\.test\.[^/]+$/.test(normalizedPath)
             || /\.spec\.[^/]+$/.test(normalizedPath);
     }
     isDocPath(normalizedPath) {
-        return normalizedPath.includes('/docs/')
+        return this.hasPathSegment(normalizedPath, 'docs')
+            || this.hasPathSegment(normalizedPath, 'doc')
+            || this.hasPathSegment(normalizedPath, 'documentation')
+            || this.hasPathSegment(normalizedPath, 'guide')
+            || this.hasPathSegment(normalizedPath, 'guides')
             || normalizedPath.endsWith('.md')
             || normalizedPath.endsWith('.mdx')
             || normalizedPath.endsWith('.rst')
@@ -449,6 +458,46 @@ export class ToolHandlers {
             }
         };
     }
+    normalizeRelativeFilePath(relativeFilePath) {
+        return relativeFilePath.replace(/\\/g, '/').replace(/^\.\/+/, '').trim();
+    }
+    buildRequiresReindexFileOutlinePayload(codebasePath, input, detail) {
+        const detailLine = detail ? `${detail}\n\n` : '';
+        return {
+            status: 'requires_reindex',
+            path: codebasePath,
+            file: input.file,
+            outline: null,
+            hasMore: false,
+            message: `${detailLine}Call graph sidecar is missing or incompatible. Please run manage_index with {"action":"reindex","path":"${codebasePath}"}.`,
+            hints: {
+                reindex: this.buildReindexHint(codebasePath)
+            }
+        };
+    }
+    getOutlineStatusForLanguage(relativeFilePath) {
+        if (this.isCallGraphLanguageSupported('unknown', relativeFilePath)) {
+            return 'ok';
+        }
+        return 'unsupported';
+    }
+    sortFileOutlineSymbols(symbols) {
+        return [...symbols].sort((a, b) => {
+            const startCmp = this.compareNullableNumbersAsc(a.span?.startLine, b.span?.startLine);
+            if (startCmp !== 0)
+                return startCmp;
+            const endCmp = this.compareNullableNumbersAsc(a.span?.endLine, b.span?.endLine);
+            if (endCmp !== 0)
+                return endCmp;
+            const labelCmp = this.compareNullableStringsAsc(a.symbolLabel, b.symbolLabel);
+            if (labelCmp !== 0)
+                return labelCmp;
+            return this.compareNullableStringsAsc(a.symbolId, b.symbolId);
+        });
+    }
+    buildSearchPassWarning(passId) {
+        return `SEARCH_PASS_FAILED:${passId} - ${passId} semantic search pass failed; results may be degraded.`;
+    }
     mapCallGraphStatus(graph) {
         if (graph.supported) {
             return 'ok';
@@ -1228,6 +1277,9 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             excludedBySubdirectory: 0,
             filterPass: 'expanded',
             freshnessMode: undefined,
+            searchPassCount: 0,
+            searchPassSuccessCount: 0,
+            searchPassFailureCount: 0,
         };
         try {
             await this.syncIndexedCodebasesFromCloud();
@@ -1329,8 +1381,40 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             console.log(`[SEARCH] 🧠 Using embedding provider: ${encoderEngine.getProvider()} for search`);
             const candidateLimit = Math.max(1, Math.min(SEARCH_MAX_CANDIDATES, Math.max(input.limit * 8, 32)));
             const expandedQuery = `${input.query}\nimplementation runtime source entrypoint`;
-            const passOne = await this.context.semanticSearch(effectiveRoot, input.query, candidateLimit, 0.3);
-            const passTwo = await this.context.semanticSearch(effectiveRoot, expandedQuery, candidateLimit, 0.3);
+            const passDescriptors = [
+                { id: 'primary', query: input.query },
+                { id: 'expanded', query: expandedQuery },
+            ];
+            searchDiagnostics.searchPassCount = passDescriptors.length;
+            const passSettled = await Promise.allSettled(passDescriptors.map((pass) => {
+                return this.context.semanticSearch(effectiveRoot, pass.query, candidateLimit, 0.3);
+            }));
+            const searchWarnings = [];
+            const successfulPasses = [];
+            for (let idx = 0; idx < passSettled.length; idx++) {
+                const passResult = passSettled[idx];
+                const passDescriptor = passDescriptors[idx];
+                if (passResult.status === 'fulfilled' && Array.isArray(passResult.value)) {
+                    successfulPasses.push({
+                        id: passDescriptor.id,
+                        results: passResult.value
+                    });
+                    continue;
+                }
+                searchWarnings.push(this.buildSearchPassWarning(passDescriptor.id));
+            }
+            searchDiagnostics.searchPassSuccessCount = successfulPasses.length;
+            searchDiagnostics.searchPassFailureCount = searchDiagnostics.searchPassCount - successfulPasses.length;
+            if (successfulPasses.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "Error searching code: all semantic search passes failed. Please retry and verify embedding/vector backends are reachable."
+                        }],
+                    isError: true,
+                    meta: { searchDiagnostics }
+                };
+            }
             const byChunkKey = new Map();
             const addPass = (results, passWeight = 1) => {
                 for (let i = 0; i < results.length; i++) {
@@ -1359,8 +1443,9 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     }
                 }
             };
-            addPass(passOne, 1);
-            addPass(passTwo, 1);
+            for (const pass of successfulPasses) {
+                addPass(pass.results, 1);
+            }
             const beforeFilter = byChunkKey.size;
             const scored = [];
             for (const candidate of byChunkKey.values()) {
@@ -1424,6 +1509,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     limit: input.limit,
                     resultMode: "raw",
                     freshnessDecision,
+                    ...(searchWarnings.length > 0 ? { warnings: searchWarnings } : {}),
                     results: rawResults
                 };
                 return {
@@ -1521,6 +1607,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 limit: input.limit,
                 resultMode: "grouped",
                 freshnessDecision,
+                ...(searchWarnings.length > 0 ? { warnings: searchWarnings } : {}),
                 results: groupedResults.slice(0, input.limit)
             };
             return {
@@ -1544,6 +1631,197 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             };
         }
     }
+    async handleFileOutline(args) {
+        const limitSymbols = Number.isFinite(args?.limitSymbols)
+            ? Math.max(1, Number(args.limitSymbols))
+            : 500;
+        const requestedStartLine = Number.isFinite(args?.start_line) ? Math.max(1, Number(args.start_line)) : undefined;
+        const requestedEndLine = Number.isFinite(args?.end_line) ? Math.max(1, Number(args.end_line)) : undefined;
+        try {
+            await this.syncIndexedCodebasesFromCloud();
+            const absoluteRoot = ensureAbsolutePath(args.path);
+            const normalizedFile = this.normalizeRelativeFilePath(args.file);
+            const absoluteFile = path.resolve(absoluteRoot, normalizedFile);
+            const relativeToRoot = path.relative(absoluteRoot, absoluteFile);
+            if (!fs.existsSync(absoluteRoot)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: Path '${absoluteRoot}' does not exist.`
+                        }],
+                    isError: true
+                };
+            }
+            const rootStat = fs.statSync(absoluteRoot);
+            if (!rootStat.isDirectory()) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: Path '${absoluteRoot}' is not a directory`
+                        }],
+                    isError: true
+                };
+            }
+            if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: File '${normalizedFile}' must be inside codebase root '${absoluteRoot}'.`
+                        }],
+                    isError: true
+                };
+            }
+            trackCodebasePath(absoluteRoot);
+            const blockedRoot = this.getMatchingBlockedRoot(absoluteRoot);
+            if (blockedRoot) {
+                const payload = this.buildRequiresReindexFileOutlinePayload(blockedRoot.path, {
+                    ...args,
+                    file: normalizedFile
+                }, blockedRoot.message);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                };
+            }
+            const gateResult = this.enforceFingerprintGate(absoluteRoot);
+            if (gateResult.blockedResponse) {
+                const payload = this.buildRequiresReindexFileOutlinePayload(absoluteRoot, {
+                    ...args,
+                    file: normalizedFile
+                }, gateResult.message);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                };
+            }
+            const sidecarInfo = this.snapshotManager.getCodebaseCallGraphSidecar(absoluteRoot);
+            if (!sidecarInfo || sidecarInfo.version !== 'v3') {
+                const payload = this.buildRequiresReindexFileOutlinePayload(absoluteRoot, {
+                    ...args,
+                    file: normalizedFile
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                };
+            }
+            if (!fs.existsSync(absoluteFile)) {
+                const payload = {
+                    status: 'not_found',
+                    path: absoluteRoot,
+                    file: normalizedFile,
+                    outline: null,
+                    hasMore: false,
+                    message: `File '${normalizedFile}' does not exist under codebase root '${absoluteRoot}'.`
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                };
+            }
+            const fileStat = fs.statSync(absoluteFile);
+            if (!fileStat.isFile()) {
+                const payload = {
+                    status: 'not_found',
+                    path: absoluteRoot,
+                    file: normalizedFile,
+                    outline: null,
+                    hasMore: false,
+                    message: `'${normalizedFile}' is not a file.`
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                };
+            }
+            const languageStatus = this.getOutlineStatusForLanguage(normalizedFile);
+            if (languageStatus !== 'ok') {
+                const payload = {
+                    status: 'unsupported',
+                    path: absoluteRoot,
+                    file: normalizedFile,
+                    outline: null,
+                    hasMore: false,
+                    message: `File '${normalizedFile}' is not supported for sidecar outline. Supported extensions: .ts, .tsx, .py.`
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                };
+            }
+            const sidecar = this.callGraphManager.loadSidecar(absoluteRoot);
+            if (!sidecar) {
+                const payload = this.buildRequiresReindexFileOutlinePayload(absoluteRoot, {
+                    ...args,
+                    file: normalizedFile
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+                };
+            }
+            const windowStart = requestedStartLine;
+            const windowEnd = requestedEndLine && requestedStartLine
+                ? Math.max(requestedEndLine, requestedStartLine)
+                : requestedEndLine;
+            const byFile = sidecar.nodes.filter((node) => this.normalizeRelativeFilePath(node.file) === normalizedFile);
+            const windowed = byFile.filter((node) => {
+                if (!windowStart && !windowEnd) {
+                    return true;
+                }
+                const startsBeforeWindowEnd = windowEnd === undefined || node.span.startLine <= windowEnd;
+                const endsAfterWindowStart = windowStart === undefined || node.span.endLine >= windowStart;
+                return startsBeforeWindowEnd && endsAfterWindowStart;
+            });
+            const symbols = this.sortFileOutlineSymbols(windowed.map((node) => {
+                const symbolLabel = (typeof node.symbolLabel === 'string' && node.symbolLabel.trim().length > 0)
+                    ? node.symbolLabel
+                    : node.symbolId;
+                return {
+                    symbolId: node.symbolId,
+                    symbolLabel,
+                    span: {
+                        startLine: node.span.startLine,
+                        endLine: node.span.endLine
+                    },
+                    callGraphHint: {
+                        supported: true,
+                        symbolRef: {
+                            file: normalizedFile,
+                            symbolId: node.symbolId,
+                            symbolLabel,
+                            span: {
+                                startLine: node.span.startLine,
+                                endLine: node.span.endLine
+                            }
+                        }
+                    }
+                };
+            }));
+            const hasMore = symbols.length > limitSymbols;
+            const missingSymbolMetadataCount = sidecar.notes.filter((note) => {
+                return note.type === 'missing_symbol_metadata' && this.normalizeRelativeFilePath(note.file) === normalizedFile;
+            }).length;
+            const warnings = missingSymbolMetadataCount > 0
+                ? [`OUTLINE_MISSING_SYMBOL_METADATA:${missingSymbolMetadataCount}`]
+                : undefined;
+            const payload = {
+                status: 'ok',
+                path: absoluteRoot,
+                file: normalizedFile,
+                outline: {
+                    symbols: symbols.slice(0, limitSymbols)
+                },
+                hasMore,
+                ...(warnings ? { warnings } : {})
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Error building file outline: ${error?.message || error}`
+                    }],
+                isError: true
+            };
+        }
+    }
     async handleCallGraph(args) {
         const rawDirection = args?.direction;
         const direction = rawDirection === 'callers' || rawDirection === 'callees' || rawDirection === 'both'

package/dist/core/search-types.d.ts

@@ -67,6 +67,7 @@ interface SearchBaseResponseEnvelope {
     freshnessDecision: FreshnessDecision | {
         mode: "skipped_requires_reindex";
     } | null;
+    warnings?: string[];
     message?: string;
     hints?: Record<string, unknown>;
 }
@@ -88,5 +89,34 @@ export interface SearchRequestInput {
     limit: number;
     debug?: boolean;
 }
+export interface FileOutlineInput {
+    path: string;
+    file: string;
+    start_line?: number;
+    end_line?: number;
+    limitSymbols?: number;
+}
+export type FileOutlineStatus = "ok" | "not_found" | "requires_reindex" | "unsupported";
+export interface FileOutlineSymbolResult {
+    symbolId: string;
+    symbolLabel: string;
+    span: SearchSpan;
+    callGraphHint: {
+        supported: true;
+        symbolRef: CallGraphSymbolRef;
+    };
+}
+export interface FileOutlineResponseEnvelope {
+    status: FileOutlineStatus;
+    path: string;
+    file: string;
+    outline: {
+        symbols: FileOutlineSymbolResult[];
+    } | null;
+    hasMore: boolean;
+    warnings?: string[];
+    message?: string;
+    hints?: Record<string, unknown>;
+}
 export {};
 //# sourceMappingURL=search-types.d.ts.map

package/dist/telemetry/search.d.ts

@@ -11,6 +11,10 @@ export interface SearchTelemetryEvent {
     reranker_used: boolean;
     latency_ms: number;
     freshness_mode?: string;
+    search_pass_count?: number;
+    search_pass_success_count?: number;
+    search_pass_failure_count?: number;
+    parallel_fanout?: boolean;
     error?: string;
 }
 export declare function emitSearchTelemetry(event: SearchTelemetryEvent): void;

package/dist/tools/file_outline.d.ts

@@ -0,0 +1,3 @@
+import { McpTool } from './types.js';
+export declare const fileOutlineTool: McpTool;
+//# sourceMappingURL=file_outline.d.ts.map

package/dist/tools/file_outline.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { formatZodError } from './types.js';
+const fileOutlineInputSchema = z.object({
+    path: z.string().min(1).describe('ABSOLUTE path to the indexed codebase root.'),
+    file: z.string().min(1).describe('Relative file path inside the codebase root.'),
+    start_line: z.number().int().positive().optional().describe('Optional start line filter (1-based, inclusive).'),
+    end_line: z.number().int().positive().optional().describe('Optional end line filter (1-based, inclusive).'),
+    limitSymbols: z.number().int().positive().default(500).optional().describe('Maximum number of returned symbols after line filtering.'),
+});
+export const fileOutlineTool = {
+    name: 'file_outline',
+    description: () => 'Return a sidecar-backed symbol outline for one file, including call_graph jump handles.',
+    inputSchemaZod: () => fileOutlineInputSchema,
+    execute: async (args, ctx) => {
+        const parsed = fileOutlineInputSchema.safeParse(args || {});
+        if (!parsed.success) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: formatZodError('file_outline', parsed.error)
+                    }],
+                isError: true
+            };
+        }
+        return ctx.toolHandlers.handleFileOutline(parsed.data);
+    }
+};
+//# sourceMappingURL=file_outline.js.map

package/dist/tools/read_file.js

@@ -1,11 +1,13 @@
 import fs from "node:fs";
+import path from "node:path";
 import { z } from "zod";
 import { formatZodError } from "./types.js";
 import { ensureAbsolutePath } from "../utils.js";
 const readFileInputSchema = z.object({
     path: z.string().min(1).describe("ABSOLUTE path to the file."),
     start_line: z.number().int().positive().optional().describe("Optional start line (1-based, inclusive)."),
-    end_line: z.number().int().positive().optional().describe("Optional end line (1-based, inclusive).")
+    end_line: z.number().int().positive().optional().describe("Optional end line (1-based, inclusive)."),
+    mode: z.enum(["plain", "annotated"]).default("plain").optional().describe("Output mode. plain returns text only; annotated returns content plus sidecar-backed outline metadata.")
 });
 function splitIntoLines(content) {
     if (content.length === 0) {
@@ -20,6 +22,32 @@ function splitIntoLines(content) {
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
+function normalizeRelativePath(value) {
+    return value.replace(/\\/g, "/");
+}
+function isOutlineSupportedFile(absolutePath) {
+    const ext = path.extname(absolutePath).toLowerCase();
+    return ext === ".ts" || ext === ".tsx" || ext === ".py";
+}
+function resolveCodebaseRootForFile(absolutePath, ctx) {
+    const allCodebases = typeof ctx.snapshotManager?.getAllCodebases === "function"
+        ? ctx.snapshotManager.getAllCodebases()
+        : [];
+    if (!Array.isArray(allCodebases)) {
+        return undefined;
+    }
+    const matches = allCodebases
+        .map((item) => (item && typeof item.path === "string") ? ensureAbsolutePath(item.path) : undefined)
+        .filter((candidate) => Boolean(candidate))
+        .filter((candidate) => {
+        return absolutePath === candidate || absolutePath.startsWith(`${candidate}${path.sep}`);
+    });
+    if (matches.length === 0) {
+        return undefined;
+    }
+    matches.sort((a, b) => b.length - a.length);
+    return matches[0];
+}
 export const readFileTool = {
     name: "read_file",
     description: () => "Read file content from the local filesystem, with optional 1-based inclusive line ranges and safe truncation.",
@@ -36,6 +64,7 @@ export const readFileTool = {
             };
         }
         const input = parsed.data;
+        const mode = input.mode || "plain";
         try {
             const absolutePath = ensureAbsolutePath(input.path);
             if (!fs.existsSync(absolutePath)) {
@@ -54,21 +83,17 @@ export const readFileTool = {
             const content = fs.readFileSync(absolutePath, "utf-8");
             const lines = splitIntoLines(content);
             const totalLines = lines.length;
-            if (totalLines === 0) {
-                return {
-                    content: [{
-                            type: "text",
-                            text: content
-                        }]
-                };
-            }
             const maxLines = Math.max(1, ctx.readFileMaxLines);
             const hasStart = input.start_line !== undefined;
             const hasEnd = input.end_line !== undefined;
             let startLine = 1;
-            let endLine = totalLines;
+            let endLine = totalLines > 0 ? totalLines : 0;
             let addContinuationHint = false;
-            if (!hasStart && !hasEnd) {
+            if (totalLines === 0) {
+                startLine = 1;
+                endLine = 0;
+            }
+            else if (!hasStart && !hasEnd) {
                 if (totalLines > maxLines) {
                     endLine = maxLines;
                     addContinuationHint = true;
@@ -86,21 +111,87 @@ export const readFileTool = {
                 startLine = clamp(input.start_line, 1, totalLines);
                 endLine = clamp(input.end_line, startLine, totalLines);
             }
-            const selected = lines.slice(startLine - 1, endLine).join("\n");
-            if (!addContinuationHint) {
+            const selected = totalLines === 0 ? content : lines.slice(startLine - 1, endLine).join("\n");
+            const nextStartLine = addContinuationHint ? endLine + 1 : undefined;
+            const hint = addContinuationHint
+                ? `\n\n(File truncated at line ${endLine}. To read more, call read_file with path="${absolutePath}" and start_line=${nextStartLine}.)`
+                : "";
+            const contentWithHint = `${selected}${hint}`;
+            if (mode === "plain") {
                 return {
                     content: [{
                             type: "text",
-                            text: selected
+                            text: contentWithHint
                         }]
                 };
             }
-            const nextStartLine = endLine + 1;
-            const hint = `\n\n(File truncated at line ${endLine}. To read more, call read_file with path="${absolutePath}" and start_line=${nextStartLine}.)`;
+            const supportedByExtension = isOutlineSupportedFile(absolutePath);
+            const resolvedRoot = resolveCodebaseRootForFile(absolutePath, ctx);
+            const relativeFile = resolvedRoot
+                ? normalizeRelativePath(path.relative(resolvedRoot, absolutePath))
+                : undefined;
+            let outlineStatus = supportedByExtension ? "requires_reindex" : "unsupported";
+            let outline = null;
+            let hasMore = false;
+            let warnings;
+            let hints;
+            if (!supportedByExtension) {
+                outlineStatus = "unsupported";
+            }
+            else if (!resolvedRoot || !relativeFile) {
+                outlineStatus = "requires_reindex";
+                hints = {
+                    reindex: {
+                        tool: "manage_index",
+                        args: {
+                            action: "reindex",
+                            path: path.dirname(absolutePath),
+                        },
+                    },
+                };
+            }
+            else {
+                try {
+                    const outlineResponse = await ctx.toolHandlers.handleFileOutline({
+                        path: resolvedRoot,
+                        file: relativeFile,
+                        start_line: totalLines === 0 ? undefined : startLine,
+                        end_line: totalLines === 0 ? undefined : endLine,
+                    });
+                    const parsedOutline = JSON.parse(outlineResponse.content?.[0]?.text || "{}");
+                    const status = parsedOutline?.status;
+                    if (status === "ok" || status === "requires_reindex" || status === "unsupported") {
+                        outlineStatus = status;
+                    }
+                    else {
+                        outlineStatus = "requires_reindex";
+                    }
+                    outline = outlineStatus === "ok" && parsedOutline?.outline ? parsedOutline.outline : null;
+                    hasMore = parsedOutline?.hasMore === true;
+                    if (Array.isArray(parsedOutline?.warnings)) {
+                        warnings = parsedOutline.warnings.filter((item) => typeof item === "string");
+                    }
+                    if (parsedOutline?.hints && typeof parsedOutline.hints === "object") {
+                        hints = parsedOutline.hints;
+                    }
+                }
+                catch {
+                    outlineStatus = "requires_reindex";
+                }
+            }
             return {
                 content: [{
                         type: "text",
-                        text: `${selected}${hint}`
+                        text: JSON.stringify({
+                            path: absolutePath,
+                            mode: "annotated",
+                            content: contentWithHint,
+                            outlineStatus,
+                            outline,
+                            hasMore,
+                            ...(warnings && warnings.length > 0 ? { warnings } : {}),
+                            ...(hints ? { hints } : {})
+                        }, null, 2)
                     }]
             };
         }

package/dist/tools/registry.js

@@ -2,12 +2,14 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 import { manageIndexTool } from "./manage_index.js";
 import { searchCodebaseTool } from "./search_codebase.js";
 import { callGraphTool } from "./call_graph.js";
+import { fileOutlineTool } from "./file_outline.js";
 import { readFileTool } from "./read_file.js";
 import { listCodebasesTool } from "./list_codebases.js";
 export const toolList = [
     manageIndexTool,
     searchCodebaseTool,
     callGraphTool,
+    fileOutlineTool,
     readFileTool,
     listCodebasesTool,
 ];

package/dist/tools/search_codebase.js

@@ -35,6 +35,9 @@ function extractDiagnostics(response) {
             excludedByIgnore: safeNumber(metaDiagnostics.excludedByIgnore, 0),
             resultsReturned: afterFilter,
             freshnessMode: typeof metaDiagnostics.freshnessMode === "string" ? metaDiagnostics.freshnessMode : undefined,
+            searchPassCount: safeNumber(metaDiagnostics.searchPassCount, 0),
+            searchPassSuccessCount: safeNumber(metaDiagnostics.searchPassSuccessCount, 0),
+            searchPassFailureCount: safeNumber(metaDiagnostics.searchPassFailureCount, 0),
         };
     }
     const text = response.content?.[0]?.text;
@@ -50,6 +53,9 @@ function extractDiagnostics(response) {
             excludedByIgnore: safeNumber(parsed?.excludedByIgnore, 0),
             resultsReturned: results,
             freshnessMode: typeof parsed?.freshnessDecision?.mode === "string" ? parsed.freshnessDecision.mode : undefined,
+            searchPassCount: safeNumber(parsed?.searchPassCount, 0),
+            searchPassSuccessCount: safeNumber(parsed?.searchPassSuccessCount, 0),
+            searchPassFailureCount: safeNumber(parsed?.searchPassFailureCount, 0),
         };
     }
     catch {
@@ -103,6 +109,10 @@ export const searchCodebaseTool = {
             reranker_used: false,
             latency_ms: Date.now() - startedAt,
             freshness_mode: diagnostics.freshnessMode,
+            search_pass_count: diagnostics.searchPassCount,
+            search_pass_success_count: diagnostics.searchPassSuccessCount,
+            search_pass_failure_count: diagnostics.searchPassFailureCount,
+            parallel_fanout: true,
             ...(response.isError ? { error: getErrorMessage(response) } : {})
         });
         return response;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "MCP server for Satori with agent-safe semantic search and indexing",
   "type": "module",
   "main": "dist/index.js",