@zokizuan/satori-mcp 3.5.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
@@ -45,6 +47,10 @@ Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposi
 - Enabled by default. Set `MCP_ENABLE_WATCHER=false` to disable
 - Debounce window via `MCP_WATCH_DEBOUNCE_MS` (default `5000`)
 - Watch events reuse the same incremental sync pipeline (`reindexByChange`)
+- Ignore control files (`.satoriignore`, root `.gitignore`) trigger no-reindex reconciliation:
+  - delete indexed paths now ignored by active rules
+  - incremental sync picks up newly unignored files
+  - signature checks in `ensureFreshness` keep this working even when watcher events are missed
 - Safety gates:
   - Watch-triggered sync only runs for `indexed`/`sync_completed` codebases
   - Events are dropped for `indexing`, `indexfailed`, and `requires_reindex`
@@ -57,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.
+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 decision.
+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. |
 
@@ -106,6 +112,9 @@ Return a sidecar-backed symbol outline for one file, including call_graph jump h
 | `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. |
+| `resolveMode` | enum("outline", "exact") | no | `"outline"` | Outline mode returns all symbols (windowed/limited). Exact mode resolves deterministic symbol matches in this file. |
+| `symbolIdExact` | string | no |  | Used with resolveMode="exact": exact symbolId match in the target file. |
+| `symbolLabelExact` | string | no |  | Used with resolveMode="exact": exact symbol label match in the target file. |
 
 ### `read_file`
 
@@ -117,6 +126,7 @@ Read file content from the local filesystem, with optional 1-based inclusive lin
 | `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. |
+| `open_symbol` | object | no |  | Optional deterministic symbol jump request for this file path. Uses exact symbol resolution within `path` when symbolId/symbolLabel is provided. |
 
 ### `list_codebases`
 
@@ -127,6 +137,15 @@ No parameters.
 
 <!-- TOOLS_END -->
 
+### `read_file.open_symbol` Fields
+
+`open_symbol` resolves symbols inside the same file passed in `read_file.path`.
+
+- `symbolId` (string, optional): deterministic symbol id to resolve in `path`.
+- `symbolLabel` (string, optional): exact symbol label to resolve in `path`.
+- `start_line` (integer, optional): direct 1-based start line for span-based jump.
+- `end_line` (integer, optional): direct 1-based end line (inclusive).
+
 ## MCP Config Examples
 
 ### JSON-style (Claude Desktop, Cursor)

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 export type EmbeddingProvider = 'OpenAI' | 'VoyageAI' | 'Gemini' | 'Ollama';
 export type VectorStoreProvider = 'Milvus';
 export type FingerprintSource = 'verified' | 'assumed_v2';
+export declare const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 export interface IndexFingerprint {
     embeddingProvider: EmbeddingProvider;
     embeddingModel: string;
@@ -37,6 +38,10 @@ export interface CallGraphSidecarInfo {
     noteCount: number;
     fingerprint: IndexFingerprint;
 }
+export interface CodebaseIndexManifest {
+    indexedPaths: string[];
+    updatedAt: string;
+}
 export interface CodebaseSnapshotV1 {
     indexedCodebases: string[];
     indexingCodebases: string[] | Record<string, number>;
@@ -48,6 +53,9 @@ interface CodebaseInfoBase {
     fingerprintSource?: FingerprintSource;
     reindexReason?: 'legacy_unverified_fingerprint' | 'fingerprint_mismatch' | 'missing_fingerprint';
     callGraphSidecar?: CallGraphSidecarInfo;
+    indexManifest?: CodebaseIndexManifest;
+    ignoreRulesVersion?: number;
+    ignoreControlSignature?: string;
 }
 export interface CodebaseInfoIndexing extends CodebaseInfoBase {
     status: 'indexing';

package/dist/config.js

@@ -1,4 +1,5 @@
 import { envManager } from "@zokizuan/satori-core";
+export const DEFAULT_WATCH_DEBOUNCE_MS = 5000;
 // Helper function to get default model for each provider
 export function getDefaultModelForProvider(provider) {
     switch (provider) {
@@ -51,7 +52,6 @@ export function buildRuntimeIndexFingerprint(config, embeddingDimension) {
 export function createMcpConfig() {
     const defaultProvider = envManager.get('EMBEDDING_PROVIDER') || 'VoyageAI';
     const defaultReadFileMaxLines = 1000;
-    const defaultWatchDebounceMs = 5000;
     // Parse output dimension from env var
     const outputDimensionStr = envManager.get('EMBEDDING_OUTPUT_DIMENSION');
     let encoderOutputDimension;
@@ -92,7 +92,7 @@ export function createMcpConfig() {
     const watchSyncEnabled = watchSyncEnabledRaw
         ? watchSyncEnabledRaw.toLowerCase() === 'true'
         : true;
-    let watchDebounceMs = defaultWatchDebounceMs;
+    let watchDebounceMs = DEFAULT_WATCH_DEBOUNCE_MS;
     const watchDebounceRaw = envManager.get('MCP_WATCH_DEBOUNCE_MS');
     if (watchDebounceRaw) {
         const parsed = Number.parseInt(watchDebounceRaw, 10);
@@ -100,7 +100,7 @@ export function createMcpConfig() {
             watchDebounceMs = parsed;
         }
         else {
-            console.warn(`[WARN] Invalid MCP_WATCH_DEBOUNCE_MS value: ${watchDebounceRaw}. Using default ${defaultWatchDebounceMs}.`);
+            console.warn(`[WARN] Invalid MCP_WATCH_DEBOUNCE_MS value: ${watchDebounceRaw}. Using default ${DEFAULT_WATCH_DEBOUNCE_MS}.`);
         }
     }
     const config = {
@@ -140,7 +140,7 @@ export function logConfigurationSummary(config) {
     console.log(`[MCP]   Embedding Provider: ${config.encoderProvider}`);
     console.log(`[MCP]   Embedding Model: ${config.encoderModel}`);
     console.log(`[MCP]   Milvus Address: ${config.milvusEndpoint || (config.milvusApiToken ? '[Auto-resolve from token]' : '[Not configured]')}`);
-    console.log(`[MCP]   Proactive Watcher: ${config.watchSyncEnabled ? `enabled (${config.watchDebounceMs || 5000}ms debounce)` : 'disabled'}`);
+    console.log(`[MCP]   Proactive Watcher: ${config.watchSyncEnabled ? `enabled (${config.watchDebounceMs || DEFAULT_WATCH_DEBOUNCE_MS}ms debounce)` : 'disabled'}`);
     // Log provider-specific configuration without exposing sensitive data
     switch (config.encoderProvider) {
         case 'OpenAI':

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;
@@ -34,8 +38,23 @@ export declare class ToolHandlers {
     private isTestPath;
     private isDocPath;
     private isGeneratedPath;
+    private isFixturePath;
     private isEntrypointPath;
     private classifyPathCategory;
+    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;
@@ -44,6 +63,8 @@ export declare class ToolHandlers {
     private buildFallbackGroupId;
     private isCallGraphLanguageSupported;
     private buildCallGraphHint;
+    private sanitizeIndexedRelativeFilePath;
+    private buildNavigationFallback;
     private normalizeRelativeFilePath;
     private buildRequiresReindexFileOutlinePayload;
     private getOutlineStatusForLanguage;
@@ -64,6 +85,8 @@ export declare class ToolHandlers {
     private parseCodebaseFromMetadata;
     private resolveCollectionCodebasePath;
     private formatCollectionTimestamp;
+    private parseTimestampMs;
+    private resolveCollectionSortTimestampMs;
     private buildZillizCollectionLimitGuidance;
     private buildCollectionLimitMessage;
     private clearAllCollectionsForForceReindex;
@@ -131,6 +154,8 @@ export declare class ToolHandlers {
                 searchPassCount: number;
                 searchPassSuccessCount: number;
                 searchPassFailureCount: number;
+                rerankerAttempted: boolean;
+                rerankerUsed: boolean;
             };
         };
         isError?: undefined;
@@ -153,6 +178,8 @@ export declare class ToolHandlers {
                 searchPassCount: number;
                 searchPassSuccessCount: number;
                 searchPassFailureCount: number;
+                rerankerAttempted: boolean;
+                rerankerUsed: boolean;
             };
         };
     } | {