@zokizuan/satori-mcp 4.11.7 → 4.11.13

package/README.md

@@ -7,8 +7,8 @@ Read-only MCP server for Satori. It gives coding agents six deterministic tools
 Use the CLI installer for normal setup:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.5 install --client all
-npx -y @zokizuan/satori-cli@0.4.5 doctor
+npx -y @zokizuan/satori-cli@latest install --client all
+npx -y @zokizuan/satori-cli@latest doctor
 ```
 
 The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates the runtime cache, writes the stable launcher, and writes client config for you. Avoid using `npx` as the resident MCP server command; first-run package resolution can exceed normal MCP startup timeouts.
@@ -16,7 +16,7 @@ The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates
 Use `--profile default|minimal|all-text` to write repo-local `satori.toml` during install:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.4.5 install --client all --profile minimal
+npx -y @zokizuan/satori-cli@latest install --client all --profile minimal
 ```
 
 Profiles control indexing breadth, not search scope. `default` is safe-broad, `minimal` indexes source plus docs/text, and `all-text` indexes additional UTF-8 text files under the size limit. `search_codebase` still defaults to `scope=runtime`.
@@ -45,7 +45,7 @@ For Codex, add `--install-guidance-hook` only when you want an installer-managed
 Advanced direct execution is available through the package bin:
 
 ```bash
-npx -y @zokizuan/satori-mcp@4.11.7 --help
+npx -y @zokizuan/satori-mcp@4.11.13 --help
 ```
 
 Use direct package execution for inspection, smoke tests, or unsupported harnesses. For supported clients, prefer `satori-cli install` so startup does not depend on package-manager resolution.
@@ -131,11 +131,11 @@ The full generated tool reference below is kept in the npm README for MCP client
 
 ### `manage_index`
 
-Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress.
+Manage index lifecycle operations (create/reindex/sync/status/clear/repair) for a codebase path. repair rebuilds local readiness only when existing vector payload and trusted runtime fingerprint proof match; otherwise it refuses and asks for create/reindex. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true). create/reindex return the kickoff response immediately and do not poll to terminal state; use action="status" to observe progress.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `action` | enum("create", "reindex", "sync", "status", "clear") | yes |  | Required operation to run. |
+| `action` | enum("create", "reindex", "sync", "status", "clear", "repair") | yes |  | Required operation to run. |
 | `path` | string | yes |  | ABSOLUTE path to the target codebase. |
 | `force` | boolean | no |  | Only for action='create'. Force rebuild from scratch. |
 | `allowUnnecessaryReindex` | boolean | no |  | Only for action='reindex'. Override preflight block when reindex is detected as unnecessary ignore-only churn. |

package/dist/cli/install.js

@@ -395,6 +395,7 @@ function installManagedRuntimeCommand(homeDir, packageSpecifier, execImpl) {
             "--ignore-scripts",
             "--no-audit",
             "--no-fund",
+            "--",
             packageSpecifier,
         ], {
             encoding: "utf8",

package/dist/config.d.ts

@@ -54,6 +54,7 @@ export interface CodebaseSnapshotV1 {
 }
 interface CodebaseInfoBase {
     lastUpdated: string;
+    collectionName?: string;
     indexFingerprint?: IndexFingerprint;
     fingerprintSource?: FingerprintSource;
     reindexReason?: 'legacy_unverified_fingerprint' | 'fingerprint_mismatch' | 'missing_fingerprint' | 'navigation_recovery_failed';

package/dist/config.js

@@ -209,7 +209,7 @@ Environment Variables:
 
 Examples:
   # Install resident MCP config without package-manager startup on every client launch
-  npx -y @zokizuan/satori-cli@0.4.5 install --client all
+  npx -y @zokizuan/satori-cli@latest install --client all
 
   # Start MCP server with OpenAI and explicit Milvus address
   OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 satori

package/dist/core/backend-diagnostics.js

@@ -36,7 +36,7 @@ function createVectorBackendDiagnostic(code) {
         case "ZILLIZ_CLUSTER_STOPPED":
             return {
                 code,
-                message: "Vector backend is unavailable because the Zilliz Cloud cluster is stopped.",
+                message: "Zilliz Cloud cluster is stopped. Resume it in Zilliz Cloud, then retry the tool call.",
                 hints: {
                     backend: {
                         code,
@@ -101,13 +101,16 @@ function createVectorBackendDiagnostic(code) {
         case "VECTOR_BACKEND_CONNECTION_CLOSED":
             return {
                 code,
-                message: "Vector backend connection closed before the tool call completed.",
+                message: "Vector backend connection closed before the tool call completed. Check backend health, provider environment, network connectivity, or an MCP process restart in the previous log lines.",
                 hints: {
                     backend: {
                         code,
                         provider: "unknown",
                         retryable: true,
                         nextSteps: [
+                            "If the previous response mentions ZILLIZ_CLUSTER_STOPPED, resume the Zilliz cluster at https://cloud.zilliz.com.",
+                            "If the previous response mentions MISSING_PROVIDER_CONFIG, set the missing env values in the MCP client environment and restart the client.",
+                            "For non-Zilliz Milvus-compatible backends, confirm the service is running and reachable at MILVUS_ADDRESS.",
                             "Retry the MCP tool call after confirming the backend is healthy.",
                             "Restart the MCP client/session if the MCP process exited after the transport failure.",
                         ],

package/dist/core/handlers.d.ts

@@ -4,9 +4,9 @@ import { SnapshotManager } from "./snapshot.js";
 import { SyncManager } from "./sync.js";
 import { IndexFingerprint } from "../config.js";
 import { FileOutlineInput } from "./search-types.js";
-import { ManageReindexPreflightOutcome } from "./manage-types.js";
-import { WarningCode } from "./warnings.js";
 import { CallGraphSidecarManager } from "./call-graph.js";
+import { type ReindexPreflightResult } from "./working-tree-state.js";
+import { type SearchDiagnostics } from "./search-execution.js";
 import type { RuntimeOwnerMutationGate } from "./runtime-owner.js";
 type IndexCodebaseArgs = {
     path: string;
@@ -24,12 +24,6 @@ type ReindexCodebaseArgs = {
     allowUnnecessaryReindex?: boolean;
 };
 type ToolArgs = Record<string, unknown>;
-type ReindexPreflightResult = {
-    outcome: ManageReindexPreflightOutcome;
-    warnings: WarningCode[];
-    confidence: "high" | "low";
-    probeFailed?: boolean;
-};
 export declare class ToolHandlers {
     private readonly runtimeOwnerGate;
     private context;
@@ -46,7 +40,17 @@ export declare class ToolHandlers {
     private readonly changedFilesCache;
     private readonly rootGitignoreMatcherCache;
     private readonly gitignoreForceReloadEveryN;
+    private readonly searchQuerySupport;
+    private readonly trackedRootReadiness;
+    private readonly navigationHandlers;
+    private readonly manageMaintenanceHandlers;
+    private readonly manageIndexingHandlers;
+    private readonly vectorBackendMaintenance;
+    private readonly relationshipBackedCallGraph;
+    private readonly toolResponseBuilders;
     constructor(context: Context, snapshotManager: SnapshotManager, syncManager: SyncManager, runtimeFingerprint: IndexFingerprint, capabilities: CapabilityResolver, now?: () => number, callGraphManager?: CallGraphSidecarManager, reranker?: VoyageAIReranker | null, gitignoreForceReloadEveryN?: number, navigationStore?: NavigationStore, runtimeOwnerGate?: RuntimeOwnerMutationGate | null);
+    private setIndexingStats;
+    private clearIndexingStats;
     private createSearchPhaseTimings;
     private searchPhaseNowMs;
     private addSearchPhaseTiming;
@@ -54,6 +58,8 @@ export declare class ToolHandlers {
     private buildReindexInstruction;
     private buildReindexHint;
     private buildCreateHint;
+    private buildSyncHint;
+    private buildRepairHint;
     private buildManageIndexRecommendedAction;
     private buildStatusHint;
     private buildManageRequiresReindexHints;
@@ -70,6 +76,7 @@ export declare class ToolHandlers {
     private getSnapshotIndexingProgress;
     private ensureSnapshotFingerprintCompatibility;
     private saveSnapshotIfSupported;
+    private canonicalizeCodebasePath;
     private fallbackCollectionName;
     private resolveCollectionName;
     private resolveStagedCollectionName;
@@ -78,16 +85,11 @@ export declare class ToolHandlers {
     private getContextActiveIgnorePatterns;
     private getContextIndexedExtensions;
     private getContextTrackedRelativePaths;
-    private writeIndexCompletionMarker;
     private clearIndexCompletionMarker;
     private pruneIndexedCollectionFamily;
+    private pruneUnprovenStagedCollectionFamily;
     private markCodebaseCleared;
-    private buildManageResponseEnvelope;
-    private buildCompactManageMessage;
     private stringifyToolJson;
-    private manageResponseFromEnvelope;
-    private manageResponse;
-    private manageVectorBackendResponse;
     private buildRuntimeOwnerConflictResponseIfBlocked;
     private buildRuntimeOwnerConflictResponse;
     private buildIndexingMetadata;
@@ -96,27 +98,19 @@ export declare class ToolHandlers {
     private buildManageActionBlockedMessage;
     private getManageRetryAfterMs;
     private buildStaleLocalHint;
+    private getSnapshotCollectionName;
+    private canSyncStaleLocal;
     private buildStaleLocalMessage;
     private withProofDebugHint;
     private validateCompletionProof;
     private extractIndexedRecoveryFromCompletionProof;
     private recoverIndexedSnapshotFromCompletionProof;
+    private getActiveIndexedCollectionNameForSnapshotRecovery;
     private refreshSnapshotStateFromDisk;
     private isPathWithinCodebase;
     private getTrackedRootEntryForPath;
-    private resolveTrackedRoot;
     private probeLocalSearchCollectionState;
     private markCodebaseSearchStateMissing;
-    private buildMissingLocalCollectionMessage;
-    private buildMissingLocalCollectionSearchPayload;
-    private buildIndexingFailureMetadata;
-    private buildIndexFailedMessage;
-    private buildIndexFailedSearchPayload;
-    private buildIndexFailedFileOutlinePayload;
-    private buildIndexFailedCallGraphPayload;
-    private buildMissingLocalCollectionFileOutlinePayload;
-    private buildMissingLocalCollectionCallGraphPayload;
-    private prepareTrackedRootForRead;
     private summarizeFingerprint;
     private fingerprintsEqual;
     private isRuntimeFingerprintMismatch;
@@ -124,7 +118,6 @@ export declare class ToolHandlers {
     private buildCompatibilityDiagnostics;
     private buildCompatibilityStatusLines;
     private buildRequiresReindexPayload;
-    private buildRequiresReindexSearchResponse;
     private buildRequiresReindexCallGraphPayload;
     private buildNotReadySearchPayload;
     private buildFreshnessBlockedSearchPayload;
@@ -138,107 +131,27 @@ export declare class ToolHandlers {
     private buildInvalidCallGraphRequestPayload;
     private getMatchingBlockedRoot;
     private enforceFingerprintGate;
-    private buildSearchExcludeMatcher;
-    private applySearchExcludeMatcher;
-    private normalizeBreadcrumbs;
-    private getBreadcrumbMergeKey;
-    private formatScopeLine;
     private normalizeSearchPath;
     private hasPathSegment;
-    private hasLeadingPathSegment;
     private isTestPath;
     private isDocPath;
     private isGeneratedPath;
     private isFixturePath;
-    private isArtifactPath;
-    private isLandingPath;
-    private isExamplePath;
-    private isAdapterPath;
-    private isEntrypointPath;
-    private isScriptRuntimePath;
     private classifyPathCategory;
-    private classifyNoiseCategory;
-    private roundRatio;
-    private normalizeRelativePathForIgnoreCheck;
-    private isExactSearchPathFilter;
-    private activeIgnorePatternsExcludePath;
-    private buildLivePathScopedSearchResults;
-    private shouldRunTrackedLexicalSearch;
-    private buildTrackedLexicalSearchResults;
-    private findBestLivePathLexicalLineIndex;
-    private trimTrailingSeparators;
-    private canonicalizeCodebasePath;
-    private loadRootGitignoreMatcher;
-    private patternMatchesAnyPath;
-    private filterNoiseHintPatternsByRootGitignore;
-    private buildNoiseMitigationHint;
-    private tokenizeQueryPrefix;
-    private unquoteOperatorValue;
-    private deriveOperatorOnlySemanticQuery;
-    private parseSearchOperators;
-    private tokenizeLexicalTerms;
-    private isIdentifierLikeToken;
-    private extractQuotedLiteralPhrases;
-    private buildSearchQueryPlan;
-    private escapeLexicalRegex;
-    private hasTokenBoundaryMatch;
-    private getReferenceUsageKind;
-    private hasDeclarationMatch;
-    private getLexicalTermFactor;
-    private isHighSignalStructuralAnchorTerm;
-    private extractNormalizedCandidateTokens;
-    private splitStructuralAnchorSegments;
-    private isSiblingStructuralAnchorNearMiss;
-    private scoreCandidateLexicalEvidence;
-    private pathMatchesAnyPattern;
-    private buildSearchPathMatcher;
-    private tokenMatchesAnyField;
-    private resolveRerankDecision;
-    private buildExactRegistrySymbolFilter;
-    private buildUnavailableExactRegistryDebug;
-    private buildRerankDocument;
-    private buildOperatorSummary;
     private parseGitStatusChangedPaths;
     private getChangedFilesForCodebase;
     private getWorkingTreeChangedPathsForPreflight;
     private evaluateReindexPreflight;
-    private applyGroupDiversity;
-    private shouldIncludeCategoryInScope;
-    private isImplementationPathCategory;
-    private shouldApplyChangedFilesBoost;
-    private classifyAgentFitSymbolRole;
-    private isWriterOwnerResult;
-    private isStrongWriterOwnerResult;
-    private isWriterActionTerm;
-    private countCandidateDomainTermMatches;
-    private resolveAgentFitMultiplier;
     private parseIndexedAtMs;
-    private getStalenessBucket;
-    private compareNullableNumbersAsc;
-    private compareNullableStringsAsc;
-    private compareSearchCandidates;
-    private sortSearchCandidates;
-    private compareGroupedSearchResults;
+    private shouldIncludeCategoryInScope;
     private sortGroupedSearchResults;
-    private buildSearchCandidateProvenance;
-    private buildExactRegistryGroupResult;
-    private isDeclarationSearchGroup;
-    private normalizeDeclarationGroupKey;
-    private collapseDuplicateDeclarationGroups;
-    private buildFallbackGroupId;
     private isCallGraphLanguageSupported;
     private isFileOutlineLanguageSupported;
     private isPartialIndexNavigationUnavailable;
     private loadRegistryValidatedCallGraphSidecar;
-    private buildRelationshipCallGraphHint;
     private sanitizeIndexedRelativeFilePath;
-    private buildSearchOwnerChunk;
-    private resolveBestOverlappingSearchSymbol;
     private resolveSearchOwnerFromRegistry;
-    private buildSearchOpenSymbolAction;
-    private shouldAllowPreviewReadFallback;
-    private buildNavigationFallback;
-    private buildSearchNextActions;
+    private getSearchNavigationHelpers;
     private buildChangedCodeDebug;
     private buildGeneratedArtifactsVerificationHint;
     private normalizeRelativeFilePath;
@@ -248,77 +161,15 @@ export declare class ToolHandlers {
     private getRegistryFileFreshness;
     private buildStaleSymbolRefCallGraphPayload;
     private getOutlineStatusForLanguage;
-    private sortFileOutlineSymbols;
-    private sortRegistrySymbols;
-    private buildVisibleRegistrySymbolState;
-    private findExactRegistrySymbols;
     private buildRegistrySymbolCallGraphHint;
-    private buildRegistryFileOutlinePayload;
-    private buildSearchGroupCallGraphHint;
-    private buildSearchPassWarning;
-    private buildSearchWarningDetails;
-    private buildSearchWarningDetail;
-    private buildSearchSpanWarningCodes;
     private buildOutlineSpanWarningCodes;
-    private buildSearchDebugSummary;
-    private buildSearchResultCapabilities;
-    private buildSearchGroupRecommendedAction;
-    private buildTopRecommendedSearchAction;
-    private buildTopRecommendedRawSearchAction;
-    private buildSearchGroupFallbacks;
-    private buildExactSymbolFallbackQuery;
-    private extractIdentifierFromSymbolLabel;
-    private buildDisplaySymbolLabel;
-    private normalizeSearchSymbolLabel;
-    private buildSearchGroupPreview;
-    private normalizeSearchPreviewLine;
-    private isSearchPreviewNoiseLine;
-    private isSearchPreviewDeclarationLine;
-    private isSearchPreviewOpenSignatureLine;
-    private isSearchPreviewSignatureContinuationLine;
-    private isSearchPreviewSignatureContinuationEndLine;
-    private isSearchPreviewNeighborDeclarationLine;
-    private isSearchPreviewPureDuplicateDeclarationLine;
     private isSearchPassFaultInjectionEnabled;
     private getForcedFailedSearchPassId;
     private shouldForceSearchPassFailure;
-    private sortRelationshipBackedCallGraphNodes;
-    private compareRelationshipBackedCallGraphEdges;
-    private sortRelationshipBackedCallGraphEdges;
-    private sortRelationshipBackedCallGraphNotes;
-    private mapRelationshipConfidenceToCallGraphConfidence;
-    private createCallGraphNodeFromRegistrySymbol;
-    private countPythonIndent;
-    private escapeRegExp;
-    private isPythonHeaderTerminated;
-    private findPythonDefinitionIndexByName;
-    private findPythonDefinitionIndexNearSpan;
-    private findPythonDecoratedDefinitionStart;
-    private findPythonSourceBackedBlockEnd;
-    private repairSourceBackedPythonSpan;
-    private repairSourceBackedPythonSpans;
-    private extractDirectCallNamesFromLine;
-    private resolveUnambiguousDirectCallTarget;
-    private buildDirectCallTargetIndex;
-    private readSafeCodebaseFileLines;
-    private buildSourceBackedPythonCalleeFallback;
-    private buildSourceBackedPythonCallerFallback;
-    private buildSuppressedLowConfidenceCallGraphNotes;
     private buildRelationshipBackedCallGraph;
-    private getContextIgnorePatterns;
     private rebuildCallGraphForIndex;
     private rebuildCallGraphForSyncDelta;
-    private getVectorStore;
-    private isSatoriCodeCollection;
-    private getVectorBackendInfo;
     private isZillizBackend;
-    private listCollectionDetailsWithFallback;
-    private parseCodebaseFromMetadata;
-    private resolveCollectionCodebasePath;
-    private formatCollectionTimestamp;
-    private parseTimestampMs;
-    private resolveCollectionSortTimestampMs;
-    private buildZillizCollectionLimitGuidance;
     private buildCollectionLimitMessage;
     private dropZillizCollectionForCreate;
     handleIndexCodebase(args: IndexCodebaseArgs): Promise<{
@@ -326,13 +177,21 @@ export declare class ToolHandlers {
             type: "text";
             text: string;
         }>;
+        isError?: boolean;
     }>;
-    private startBackgroundIndexing;
     handleReindexCodebase(args: ReindexCodebaseArgs): Promise<{
         content: Array<{
             type: "text";
             text: string;
         }>;
+        isError?: boolean;
+    }>;
+    handleRepairIndex(args: ToolArgs): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        isError?: boolean;
     }>;
     handleSearchCode(args: ToolArgs): Promise<{
         content: {
@@ -342,28 +201,14 @@ export declare class ToolHandlers {
         isError: boolean;
         meta?: undefined;
     } | {
+        meta: {
+            searchDiagnostics: SearchDiagnostics;
+        };
+        isError?: boolean | undefined;
         content: {
             type: string;
             text: string;
         }[];
-        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;
-                rerankerAttempted: boolean;
-                rerankerUsed: boolean;
-            };
-        };
-        isError?: undefined;
     } | {
         content: {
             type: string;
@@ -389,29 +234,6 @@ export declare class ToolHandlers {
             };
         };
         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;
-                rerankerAttempted: boolean;
-                rerankerUsed: boolean;
-            };
-        };
     } | {
         content: {
             type: string;
@@ -424,51 +246,34 @@ export declare class ToolHandlers {
             };
         };
         isError?: undefined;
-    } | {
-        content: {
-            type: string;
-            text: string;
-        }[];
-        isError?: undefined;
-        meta?: undefined;
     }>;
     handleFileOutline(args: FileOutlineInput): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-        isError: boolean;
-    } | {
-        content: {
-            type: string;
+        content: Array<{
+            type: "text";
             text: string;
-        }[];
-        isError?: undefined;
+        }>;
+        isError?: boolean;
     }>;
     handleCallGraph(args: ToolArgs): Promise<{
-        content: {
-            type: string;
-            text: string;
-        }[];
-        isError: boolean;
-    } | {
-        content: {
-            type: string;
+        content: Array<{
+            type: "text";
             text: string;
-        }[];
-        isError?: undefined;
+        }>;
+        isError?: boolean;
     }>;
     handleClearIndex(args: ToolArgs): Promise<{
         content: Array<{
             type: "text";
             text: string;
         }>;
+        isError?: boolean;
     }>;
     handleGetIndexingStatus(args: ToolArgs): Promise<{
         content: Array<{
             type: "text";
             text: string;
         }>;
+        isError?: boolean;
     }>;
     /**
      * Handle sync request - manually trigger incremental sync for a codebase
@@ -478,6 +283,7 @@ export declare class ToolHandlers {
             type: "text";
             text: string;
         }>;
+        isError?: boolean;
     }>;
     handleReadCode(args: ToolArgs): Promise<{
         content: {