@zokizuan/satori-mcp 4.6.0 → 4.9.0

package/README.md

@@ -157,7 +157,7 @@ No parameters.
   "mcpServers": {
     "satori": {
       "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@4.4.1"],
+      "args": ["-y", "@zokizuan/satori-mcp@4.9.0"],
       "timeout": 180000,
       "env": {
         "EMBEDDING_PROVIDER": "VoyageAI",
@@ -178,11 +178,13 @@ No parameters.
 ```toml
 [mcp_servers.satori]
 command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.4.1"]
+args = ["-y", "@zokizuan/satori-mcp@4.9.0"]
 startup_timeout_ms = 180000
 env = { EMBEDDING_PROVIDER = "VoyageAI", EMBEDDING_MODEL = "voyage-4-large", EMBEDDING_OUTPUT_DIMENSION = "1024", VOYAGEAI_API_KEY = "your-api-key", VOYAGEAI_RERANKER_MODEL = "rerank-2.5", MILVUS_ADDRESS = "your-milvus-endpoint", MILVUS_TOKEN = "your-milvus-token" }
 ```
 
+`MILVUS_TOKEN` is optional auth for endpoints that require it; local unauthenticated Milvus only needs `MILVUS_ADDRESS`.
+
 ### Local development (when working on this repo)
 
 ```json
@@ -228,10 +230,11 @@ Supported installer targets in Phase 1:
 Examples:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.1.1 install --client codex
-npx -y @zokizuan/satori-cli@0.1.1 install --client claude
-npx -y @zokizuan/satori-cli@0.1.1 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.1.1 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.0 install --client codex
+npx -y @zokizuan/satori-cli@0.3.0 install --client claude
+npx -y @zokizuan/satori-cli@0.3.0 install --client all --dry-run
+npx -y @zokizuan/satori-cli@0.3.0 uninstall --client codex
+npx -y @zokizuan/satori-cli@0.3.0 doctor
 ```
 
 Install and uninstall run before MCP session startup, only touch Satori-managed config, and copy/remove these packaged skills:
@@ -286,6 +289,10 @@ When spawned by `satori-cli`, server process mode is `SATORI_RUN_MODE=cli`:
 
 `SATORI_CLI_STDOUT_GUARD=drop|redirect` controls accidental non-protocol stdout handling (`drop` default).
 
+### Startup vs Provider Setup
+
+MCP startup does not require provider credentials, network access, or a live Milvus backend. The server should complete `initialize` and expose the six tools with an empty provider environment. Provider-backed calls (`manage_index create|reindex|sync|clear` and `search_codebase`) validate their required environment at call time and return `MISSING_PROVIDER_CONFIG` when setup is incomplete.
+
 ## Development
 
 ```bash

package/dist/cli/install.js

@@ -69,7 +69,7 @@ function buildCodexManagedBlock(packageSpecifier) {
         MANAGED_BLOCK_START,
         "[mcp_servers.satori]",
         'command = "npx"',
-        `args = ["-y", "--package", "${packageSpecifier}", "satori"]`,
+        `args = ["-y", "${packageSpecifier}"]`,
         `startup_timeout_ms = ${MANAGED_TIMEOUT_MS}`,
         MANAGED_BLOCK_END,
         "",
@@ -153,10 +153,13 @@ function parseJsonObject(filePath) {
 function buildClaudeServerConfig(packageSpecifier) {
     return {
         command: "npx",
-        args: ["-y", "--package", packageSpecifier, "satori"],
+        args: ["-y", packageSpecifier],
         timeout: MANAGED_TIMEOUT_MS,
     };
 }
+function isManagedPackageSpecifier(value) {
+    return typeof value === "string" && /^@zokizuan\/satori-mcp@.+$/.test(value);
+}
 function isManagedClaudeEntry(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return false;
@@ -168,14 +171,19 @@ function isManagedClaudeEntry(value) {
     if (entry.timeout !== MANAGED_TIMEOUT_MS) {
         return false;
     }
-    if (!Array.isArray(entry.args) || entry.args.length !== 4) {
+    if (!Array.isArray(entry.args)) {
         return false;
     }
-    return entry.args[0] === "-y"
-        && entry.args[1] === "--package"
-        && typeof entry.args[2] === "string"
-        && /^@zokizuan\/satori-mcp@.+$/.test(entry.args[2])
-        && entry.args[3] === "satori";
+    if (entry.args.length === 2) {
+        return entry.args[0] === "-y" && isManagedPackageSpecifier(entry.args[1]);
+    }
+    if (entry.args.length === 4) {
+        return entry.args[0] === "-y"
+            && entry.args[1] === "--package"
+            && isManagedPackageSpecifier(entry.args[2])
+            && entry.args[3] === "satori";
+    }
+    return false;
 }
 function prepareClaudeInstall(filePath, packageSpecifier) {
     const currentObject = parseJsonObject(filePath);

package/dist/cli/package-installability.js

@@ -55,7 +55,7 @@ function assertPublishedVersion(packageName, version, ownerPackageName, ownerPac
             stdio: ["ignore", "pipe", "pipe"],
         });
     }
-    catch (error) {
+    catch {
         if (relation === "self") {
             throw new CliError("E_USAGE", `Cannot install ${ownerPackageName}@${ownerPackageVersion} because that package version is not published on npm. Publish ${ownerPackageName}@${ownerPackageVersion} first or use a local dev server config instead.`, 2);
         }

package/dist/config.d.ts

@@ -42,6 +42,10 @@ export interface CodebaseIndexManifest {
     indexedPaths: string[];
     updatedAt: string;
 }
+export interface CodebaseClearTombstone {
+    clearedAt: string;
+    collectionName?: string;
+}
 export interface CodebaseSnapshotV1 {
     indexedCodebases: string[];
     indexingCodebases: string[] | Record<string, number>;
@@ -94,6 +98,7 @@ export interface CodebaseSnapshotV2 {
 export interface CodebaseSnapshotV3 {
     formatVersion: 'v3';
     codebases: Record<string, CodebaseInfo>;
+    clearTombstones?: Record<string, CodebaseClearTombstone>;
     lastUpdated: string;
 }
 export type CodebaseSnapshot = CodebaseSnapshotV1 | CodebaseSnapshotV2 | CodebaseSnapshotV3;

package/dist/config.js

@@ -119,8 +119,8 @@ export function createMcpConfig() {
         // Ollama configuration
         ollamaEncoderModel: envManager.get('OLLAMA_MODEL'),
         ollamaEndpoint: envManager.get('OLLAMA_HOST'),
-        // Vector database configuration - address can be auto-resolved from token
-        milvusEndpoint: envManager.get('MILVUS_ADDRESS'), // Optional, can be resolved from token
+        // Vector database configuration
+        milvusEndpoint: envManager.get('MILVUS_ADDRESS'),
         milvusApiToken: envManager.get('MILVUS_TOKEN'),
         // Reranker configuration
         rankerModel,
@@ -139,7 +139,7 @@ export function logConfigurationSummary(config) {
     console.log(`[MCP]   Server: ${config.name} v${config.version}`);
     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]   Milvus Address: ${config.milvusEndpoint || '[Not configured]'}`);
     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) {
@@ -169,7 +169,7 @@ export function showHelpMessage() {
     console.log(`
 Satori MCP Server
 
-Usage: npx -y @zokizuan/satori-mcp@4.4.1 [options]
+Usage: npx -y @zokizuan/satori-mcp@4.9.0 [options]
 
 Options:
   --help, -h                          Show this help message
@@ -194,8 +194,8 @@ Environment Variables:
   OLLAMA_MODEL            Ollama model name (alternative to EMBEDDING_MODEL for Ollama)
 
   Vector Database Configuration:
-  MILVUS_ADDRESS          Milvus address (optional, can be auto-resolved from token)
-  MILVUS_TOKEN            Milvus token (optional, used for authentication and address resolution)
+  MILVUS_ADDRESS          Milvus address (required for index/search/clear tool calls)
+  MILVUS_TOKEN            Milvus token (optional, used for authenticated endpoints)
 
   Read File Configuration:
   READ_FILE_MAX_LINES     Max lines returned by read_file when no explicit range is provided (default: 1000)
@@ -206,16 +206,16 @@ Environment Variables:
 
 Examples:
   # Start MCP server with OpenAI and explicit Milvus address
-  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.4.1
+  OPENAI_API_KEY=sk-xxx MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.9.0
 
   # Start MCP server with VoyageAI and specific model
-  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
+  EMBEDDING_PROVIDER=VoyageAI VOYAGEAI_API_KEY=pa-xxx EMBEDDING_MODEL=voyage-4-large MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.9.0
 
   # Start MCP server with Gemini and specific model
-  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
+  EMBEDDING_PROVIDER=Gemini GEMINI_API_KEY=xxx EMBEDDING_MODEL=gemini-embedding-001 MILVUS_ADDRESS=https://your-zilliz-endpoint MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.9.0
 
   # Start MCP server with Ollama and specific model
-  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_TOKEN=your-token npx -y @zokizuan/satori-mcp@4.4.1
+  EMBEDDING_PROVIDER=Ollama EMBEDDING_MODEL=nomic-embed-text MILVUS_ADDRESS=localhost:19530 npx -y @zokizuan/satori-mcp@4.9.0
         `);
 }
 //# sourceMappingURL=config.js.map

package/dist/core/capabilities.js

@@ -15,7 +15,7 @@ export class CapabilityResolver {
         else {
             performanceProfile = 'standard';
         }
-        const hasVectorStore = Boolean(this.config.milvusEndpoint || this.config.milvusApiToken);
+        const hasVectorStore = Boolean(this.config.milvusEndpoint);
         const hasReranker = Boolean(this.config.voyageKey);
         const defaultSearchLimit = performanceProfile === 'fast' ? 50 :
             performanceProfile === 'standard' ? 25 :

package/dist/core/completion-proof.d.ts

@@ -0,0 +1,24 @@
+import type { IndexFingerprint } from "../config.js";
+export type CompletionProofOutcome = "valid" | "stale_local" | "fingerprint_mismatch" | "probe_failed";
+export type CompletionProofReason = "missing_marker_doc" | "invalid_marker_kind" | "path_mismatch" | "invalid_payload" | "fingerprint_mismatch" | "probe_failed";
+export type CompletionProofValidationResult = {
+    outcome: CompletionProofOutcome;
+    reason?: CompletionProofReason;
+    marker?: {
+        kind?: string;
+        codebasePath?: string;
+        fingerprint?: unknown;
+        indexedFiles?: number;
+        totalChunks?: number;
+        completedAt?: string;
+        runId?: string;
+    };
+};
+export type CompletionMarkerReader = (codebasePath: string) => Promise<unknown>;
+export declare function validateCompletionProof(args: {
+    codebasePath: string;
+    runtimeFingerprint?: IndexFingerprint;
+    getIndexCompletionMarker?: CompletionMarkerReader;
+    onProbeError?: (error: unknown) => void;
+}): Promise<CompletionProofValidationResult>;
+//# sourceMappingURL=completion-proof.d.ts.map

package/dist/core/completion-proof.js

@@ -0,0 +1,106 @@
+import fs from "node:fs";
+import path from "node:path";
+function trimTrailingSeparators(inputPath) {
+    const normalized = path.normalize(inputPath);
+    const parsedRoot = path.parse(normalized).root;
+    if (normalized === parsedRoot) {
+        return normalized;
+    }
+    return normalized.replace(/[\\/]+$/, "");
+}
+function canonicalizeCodebasePath(codebasePath) {
+    const resolved = path.resolve(codebasePath);
+    try {
+        const realPath = typeof fs.realpathSync.native === "function"
+            ? fs.realpathSync.native(resolved)
+            : fs.realpathSync(resolved);
+        return trimTrailingSeparators(realPath);
+    }
+    catch {
+        return trimTrailingSeparators(resolved);
+    }
+}
+function markerMatchesRuntimeFingerprint(marker, runtimeFingerprint) {
+    if (!runtimeFingerprint || typeof runtimeFingerprint !== "object") {
+        return true;
+    }
+    const fingerprint = marker?.fingerprint;
+    if (!fingerprint || typeof fingerprint !== "object") {
+        return false;
+    }
+    const record = fingerprint;
+    return record.embeddingProvider === runtimeFingerprint.embeddingProvider
+        && record.embeddingModel === runtimeFingerprint.embeddingModel
+        && Number(record.embeddingDimension) === Number(runtimeFingerprint.embeddingDimension)
+        && record.vectorStoreProvider === runtimeFingerprint.vectorStoreProvider
+        && record.schemaVersion === runtimeFingerprint.schemaVersion;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number"
+        && Number.isInteger(value)
+        && value >= 0;
+}
+function validateMarkerShape(expectedCodebasePath, marker) {
+    if (!marker || typeof marker !== "object") {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    const record = marker;
+    if (record.kind !== "satori_index_completion_v1") {
+        return { ok: false, reason: "invalid_marker_kind" };
+    }
+    if (typeof record.codebasePath !== "string" || record.codebasePath.trim().length === 0) {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    if (!record.fingerprint || typeof record.fingerprint !== "object") {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    if (!isNonNegativeInteger(record.indexedFiles) || !isNonNegativeInteger(record.totalChunks)) {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    if (typeof record.completedAt !== "string" || Number.isNaN(Date.parse(record.completedAt))) {
+        return { ok: false, reason: "invalid_payload" };
+    }
+    const expectedCanonical = canonicalizeCodebasePath(expectedCodebasePath);
+    const markerCanonical = canonicalizeCodebasePath(record.codebasePath);
+    if (expectedCanonical !== markerCanonical) {
+        return { ok: false, reason: "path_mismatch" };
+    }
+    return { ok: true };
+}
+export async function validateCompletionProof(args) {
+    const { codebasePath, runtimeFingerprint, getIndexCompletionMarker, onProbeError } = args;
+    if (typeof getIndexCompletionMarker !== "function") {
+        return { outcome: "probe_failed", reason: "probe_failed" };
+    }
+    let marker;
+    try {
+        marker = await getIndexCompletionMarker(codebasePath);
+    }
+    catch (error) {
+        onProbeError?.(error);
+        return { outcome: "probe_failed", reason: "probe_failed" };
+    }
+    if (!marker) {
+        return { outcome: "stale_local", reason: "missing_marker_doc" };
+    }
+    const markerShape = validateMarkerShape(codebasePath, marker);
+    if (!markerShape.ok) {
+        return {
+            outcome: "stale_local",
+            reason: markerShape.reason,
+            marker: marker
+        };
+    }
+    if (!markerMatchesRuntimeFingerprint(marker, runtimeFingerprint)) {
+        return {
+            outcome: "fingerprint_mismatch",
+            reason: "fingerprint_mismatch",
+            marker: marker
+        };
+    }
+    return {
+        outcome: "valid",
+        marker: marker
+    };
+}
+//# sourceMappingURL=completion-proof.js.map

package/dist/core/handlers.d.ts

@@ -33,10 +33,6 @@ export declare class ToolHandlers {
     private isIndexingStateStale;
     private recoverStaleIndexingStateIfNeeded;
     private buildManageActionBlockedMessage;
-    private markerMatchesRuntimeFingerprint;
-    private trimTrailingSeparators;
-    private canonicalizeCodebasePath;
-    private validateMarkerShape;
     private buildStaleLocalHint;
     private buildStaleLocalMessage;
     private withProofDebugHint;
@@ -72,6 +68,8 @@ export declare class ToolHandlers {
     private classifyNoiseCategory;
     private roundRatio;
     private normalizeRelativePathForIgnoreCheck;
+    private trimTrailingSeparators;
+    private canonicalizeCodebasePath;
     private loadRootGitignoreMatcher;
     private patternMatchesAnyPath;
     private filterNoiseHintPatternsByRootGitignore;