@zokizuan/satori-mcp 3.8.0 → 4.0.0

package/README.md

@@ -6,6 +6,8 @@ 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
+- Deterministic query-prefix operators in `search_codebase` (`lang:`, `path:`, `-path:`, `must:`, `exclude:`)
+- Default grouped-result diversity and auto changed-files ranking (`rankingMode="auto_changed_first"`)
 - 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
@@ -61,29 +63,29 @@ Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposi
 
 ### `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 (no full reindex required). If you need immediate convergence after ignore edits, run action="sync" and then rerun search_codebase. Use action="reindex" for fingerprint/schema incompatibility or full rebuild recovery.
+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.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `action` | enum("create", "reindex", "sync", "status", "clear") | 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. |
-| `splitter` | enum("ast", "langchain") | no |  | Only for action='create'. Code splitter strategy. |
 | `customExtensions` | array<string> | no |  | Only for action='create'. Additional file extensions to include. |
 | `ignorePatterns` | array<string> | no |  | Only for action='create'. Additional ignore patterns to apply. |
 | `zillizDropCollection` | string | no |  | Only for action='create'. Zilliz-only: drop this Satori-managed collection before creating the new index. |
 
 ### `search_codebase`
 
-Unified semantic search with runtime/docs scope control, grouped/raw output modes, deterministic ranking, and structured freshness decisions. For runtime debugging, start with scope="runtime". If you need both runtime and docs context, use scope="mixed". If top results are dominated by tests/fixtures/docs, edit repo-root .satoriignore using your host/editor (examples, not exhaustive: **/*.test.*, **/*.spec.*, **/__tests__/**, **/__fixtures__/**, **/fixtures/**, coverage/**), wait one debounce window (MCP_WATCH_DEBOUNCE_MS, default 5000ms), then rerun search_codebase. For immediate convergence, run manage_index with {"action":"sync","path":"<same path used in search_codebase>"}.
+Unified semantic search with runtime-first defaults (start with scope="runtime"), grouped/raw output modes, and deterministic ranking/freshness behavior. Operators are parsed from a query prefix block: lang:, path:, -path:, must:, exclude: (escape with \\ to keep literals). Use debug:true for explainability payloads, and rely on response hints for remediation (.satoriignore noise handling, navigation fallback, reindex guidance).
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `path` | string | yes |  | ABSOLUTE path to an indexed codebase or subdirectory. |
 | `query` | string | yes |  | Natural-language query. |
-| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime excludes docs/tests, docs returns docs/tests only, mixed includes all. |
+| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime excludes docs/tests, docs returns docs/tests only, mixed includes all. Docs scope skips reranker by policy in the current tool surface. |
 | `resultMode` | enum("grouped", "raw") | no | `"grouped"` | Output mode. grouped returns merged search groups, raw returns chunk hits. |
 | `groupBy` | enum("symbol", "file") | no | `"symbol"` | Grouping strategy in grouped mode. |
+| `rankingMode` | enum("default", "auto_changed_first") | no | `"auto_changed_first"` | Ranking policy. auto_changed_first boosts files changed in the current git working tree when available. |
 | `limit` | integer | no | `50` | Maximum groups (grouped mode) or chunks (raw mode). |
 | `debug` | boolean | no | `false` | Optional debug payload toggle for score and fusion breakdowns. |
 

package/dist/core/capabilities.d.ts

@@ -23,9 +23,5 @@ export declare class CapabilityResolver {
     getDefaultSearchLimit(): number;
     getMaxSearchLimit(): number;
     getDefaultRerankEnabled(): boolean;
-    resolveRerankDecision(useReranker: boolean | undefined): {
-        enabled: boolean;
-        blockedByMissingCapability: boolean;
-    };
 }
 //# sourceMappingURL=capabilities.d.ts.map

package/dist/core/capabilities.js

@@ -58,23 +58,5 @@ export class CapabilityResolver {
     getDefaultRerankEnabled() {
         return this.matrix.defaultRerankEnabled;
     }
-    resolveRerankDecision(useReranker) {
-        if (useReranker === true) {
-            return {
-                enabled: this.hasReranker(),
-                blockedByMissingCapability: !this.hasReranker()
-            };
-        }
-        if (useReranker === false) {
-            return {
-                enabled: false,
-                blockedByMissingCapability: false
-            };
-        }
-        return {
-            enabled: this.getDefaultRerankEnabled(),
-            blockedByMissingCapability: false
-        };
-    }
 }
 //# sourceMappingURL=capabilities.js.map

package/dist/core/handlers.d.ts

@@ -1,4 +1,5 @@
-import { Context } from "@zokizuan/satori-core";
+import { Context, VoyageAIReranker } from "@zokizuan/satori-core";
+import { CapabilityResolver } from "./capabilities.js";
 import { SnapshotManager } from "./snapshot.js";
 import { SyncManager } from "./sync.js";
 import { IndexFingerprint } from "../config.js";
@@ -8,12 +9,15 @@ export declare class ToolHandlers {
     private context;
     private snapshotManager;
     private syncManager;
+    private readonly capabilities;
     private runtimeFingerprint;
     private indexingStats;
     private currentWorkspace;
     private readonly now;
     private readonly callGraphManager;
-    constructor(context: Context, snapshotManager: SnapshotManager, syncManager: SyncManager, runtimeFingerprint: IndexFingerprint, now?: () => number, callGraphManager?: CallGraphSidecarManager);
+    private readonly reranker;
+    private readonly changedFilesCache;
+    constructor(context: Context, snapshotManager: SnapshotManager, syncManager: SyncManager, runtimeFingerprint: IndexFingerprint, capabilities: CapabilityResolver, now?: () => number, callGraphManager?: CallGraphSidecarManager, reranker?: VoyageAIReranker | null);
     private buildReindexInstruction;
     private buildReindexHint;
     private summarizeFingerprint;
@@ -40,6 +44,17 @@ export declare class ToolHandlers {
     private classifyNoiseCategory;
     private roundRatio;
     private buildNoiseMitigationHint;
+    private tokenizeQueryPrefix;
+    private unquoteOperatorValue;
+    private parseSearchOperators;
+    private pathMatchesAnyPattern;
+    private tokenMatchesAnyField;
+    private resolveRerankDecision;
+    private buildRerankDocument;
+    private buildOperatorSummary;
+    private parseGitStatusChangedPaths;
+    private getChangedFilesForCodebase;
+    private applyGroupDiversity;
     private shouldIncludeCategoryInScope;
     private parseIndexedAtMs;
     private getStalenessBucket;
@@ -48,6 +63,8 @@ export declare class ToolHandlers {
     private buildFallbackGroupId;
     private isCallGraphLanguageSupported;
     private buildCallGraphHint;
+    private sanitizeIndexedRelativeFilePath;
+    private buildNavigationFallback;
     private normalizeRelativeFilePath;
     private buildRequiresReindexFileOutlinePayload;
     private getOutlineStatusForLanguage;
@@ -137,6 +154,8 @@ export declare class ToolHandlers {
                 searchPassCount: number;
                 searchPassSuccessCount: number;
                 searchPassFailureCount: number;
+                rerankerAttempted: boolean;
+                rerankerUsed: boolean;
             };
         };
         isError?: undefined;
@@ -159,6 +178,8 @@ export declare class ToolHandlers {
                 searchPassCount: number;
                 searchPassSuccessCount: number;
                 searchPassFailureCount: number;
+                rerankerAttempted: boolean;
+                rerankerUsed: boolean;
             };
         };
     } | {