@zokizuan/satori-mcp 4.8.0 → 4.9.0

package/README.md

@@ -157,7 +157,7 @@ No parameters.
   "mcpServers": {
     "satori": {
       "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@4.8.0"],
+      "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.8.0"]
+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.2.0 install --client codex
-npx -y @zokizuan/satori-cli@0.2.0 install --client claude
-npx -y @zokizuan/satori-cli@0.2.0 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.2.0 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/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.8.0 [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.8.0
+  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.8.0
+  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.8.0
+  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.8.0
+  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/manage-types.d.ts

@@ -1,7 +1,7 @@
 import { WarningCode } from "./warnings.js";
 export type ManageIndexAction = "create" | "reindex" | "sync" | "status" | "clear";
 export type ManageIndexStatus = "ok" | "not_ready" | "not_indexed" | "requires_reindex" | "blocked" | "error";
-export type ManageIndexReason = "indexing" | "not_indexed" | "requires_reindex" | "unnecessary_reindex_ignore_only" | "preflight_unknown" | "backend_timeout" | "remote_delete_pending";
+export type ManageIndexReason = "indexing" | "not_indexed" | "requires_reindex" | "unnecessary_reindex_ignore_only" | "preflight_unknown" | "backend_timeout" | "remote_delete_pending" | "missing_provider_config";
 export type ManageReindexPreflightOutcome = "reindex_required" | "reindex_unnecessary_ignore_only" | "unknown" | "probe_failed";
 export interface ManageIndexToolHint {
     tool: "manage_index";
@@ -14,6 +14,7 @@ export interface ManageIndexResponseEnvelope {
     path: string;
     status: ManageIndexStatus;
     reason?: ManageIndexReason;
+    code?: "MISSING_PROVIDER_CONFIG";
     message: string;
     humanText: string;
     warnings?: WarningCode[];

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

@@ -198,10 +198,11 @@ export interface SearchResponseHints extends Record<string, unknown> {
     noiseMitigation?: SearchNoiseMitigationHint;
     debugSearch?: SearchDebugHint;
 }
-export type NonOkReason = "indexing" | "requires_reindex" | "not_indexed";
+export type NonOkReason = "indexing" | "requires_reindex" | "not_indexed" | "missing_provider_config";
 interface SearchBaseResponseEnvelope {
     status: "ok" | "requires_reindex" | "not_indexed" | "not_ready";
     reason?: NonOkReason;
+    code?: "MISSING_PROVIDER_CONFIG";
     path: string;
     query: string;
     scope: SearchScope;

package/dist/index.js

@@ -3,6 +3,10 @@ import { Writable } from "node:stream";
 let activeServer = null;
 let shuttingDown = false;
 let guardDisabledWarningEmitted = false;
+const bootstrapKeepAlive = setInterval(() => {
+    // Node may otherwise exit before top-level async ESM imports finish and stdio transport connects.
+    // The server owns steady-state lifetime after startMcpServerFromEnv resolves.
+}, 60 * 60 * 1000);
 function resolveRunMode() {
     return process.env.SATORI_RUN_MODE === "cli" ? "cli" : "mcp";
 }
@@ -79,7 +83,10 @@ process.on("SIGINT", () => {
 process.on("SIGTERM", () => {
     void handleShutdownSignal("SIGTERM");
 });
-main().catch((error) => {
+main().then(() => {
+    clearInterval(bootstrapKeepAlive);
+}).catch((error) => {
+    clearInterval(bootstrapKeepAlive);
     const message = error instanceof Error ? error.message : String(error);
     if (message.includes("E_PROTOCOL_FAILURE")) {
         console.error(`E_PROTOCOL_FAILURE ${message}`);

package/dist/server/provider-runtime.d.ts

@@ -0,0 +1,38 @@
+import { Context } from "@zokizuan/satori-core";
+import { CapabilityResolver } from "../core/capabilities.js";
+import { CallGraphSidecarManager } from "../core/call-graph.js";
+import { SnapshotManager } from "../core/snapshot.js";
+import { ContextMcpConfig, IndexFingerprint } from "../config.js";
+import { MissingProviderConfigIssue, ProviderBackedOperation, ToolContext } from "../tools/types.js";
+export declare function resolveConfiguredEmbeddingDimension(config: ContextMcpConfig): number;
+export declare function createLocalOnlyContext(config: ContextMcpConfig): Context;
+export declare class ProviderRuntime {
+    private readonly config;
+    private readonly snapshotManager;
+    private readonly runtimeFingerprint;
+    private readonly capabilities;
+    private readonly readFileMaxLines;
+    private readonly watchSyncEnabled;
+    private readonly watchDebounceMs;
+    private readonly callGraphManager;
+    private readonly now;
+    private embeddingRuntimePromise;
+    private vectorRuntimePromise;
+    private activeContexts;
+    constructor(args: {
+        config: ContextMcpConfig;
+        snapshotManager: SnapshotManager;
+        runtimeFingerprint: IndexFingerprint;
+        capabilities: CapabilityResolver;
+        readFileMaxLines: number;
+        watchSyncEnabled: boolean;
+        watchDebounceMs: number;
+        callGraphManager: CallGraphSidecarManager;
+        now?: () => number;
+    });
+    validate(operation: ProviderBackedOperation): MissingProviderConfigIssue | null;
+    requireToolContext(operation: ProviderBackedOperation): Promise<ToolContext | MissingProviderConfigIssue>;
+    private createRuntime;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=provider-runtime.d.ts.map

package/dist/server/provider-runtime.js

@@ -0,0 +1,211 @@
+import { Context, Embedding, MilvusVectorDatabase, VoyageAIReranker, } from "@zokizuan/satori-core";
+import { ToolHandlers } from "../core/handlers.js";
+import { SyncManager } from "../core/sync.js";
+import { createEmbeddingInstance, logEmbeddingProviderInfo } from "../embedding.js";
+class MetadataOnlyEmbedding extends Embedding {
+    constructor(provider, dimension) {
+        super();
+        this.maxTokens = 1;
+        this.provider = provider;
+        this.dimension = dimension;
+    }
+    async detectDimension() {
+        return this.dimension;
+    }
+    async embed(_text) {
+        throw new Error("MISSING_PROVIDER_CONFIG embedding provider is not configured");
+    }
+    async embedBatch(_texts) {
+        throw new Error("MISSING_PROVIDER_CONFIG embedding provider is not configured");
+    }
+    getDimension() {
+        return this.dimension;
+    }
+    getProvider() {
+        return this.provider;
+    }
+}
+class UnconfiguredVectorDatabase {
+    throwMissing() {
+        throw new Error("MISSING_PROVIDER_CONFIG MILVUS_ADDRESS is not configured");
+    }
+    async createCollection() { this.throwMissing(); }
+    async createHybridCollection() { this.throwMissing(); }
+    async dropCollection() { this.throwMissing(); }
+    async hasCollection() { this.throwMissing(); }
+    async listCollections() { this.throwMissing(); }
+    async insert() { this.throwMissing(); }
+    async insertHybrid() { this.throwMissing(); }
+    async search() { this.throwMissing(); }
+    async hybridSearch() { this.throwMissing(); }
+    async delete() { this.throwMissing(); }
+    async query() { this.throwMissing(); }
+    async checkCollectionLimit() { this.throwMissing(); }
+}
+// Local-only startup scaffolding: these satisfy Context/ToolHandlers constructor
+// contracts for provider-free tools. They must not perform provider I/O.
+// Provider-backed tools must use ProviderRuntime.requireToolContext instead.
+export function resolveConfiguredEmbeddingDimension(config) {
+    switch (config.encoderProvider) {
+        case "OpenAI":
+            if (config.encoderModel === "text-embedding-3-large")
+                return 3072;
+            return 1536;
+        case "Gemini":
+            return 3072;
+        case "Ollama":
+            return 768;
+        case "VoyageAI":
+        default:
+            return config.encoderOutputDimension || 1024;
+    }
+}
+export function createLocalOnlyContext(config) {
+    return new Context({
+        embedding: new MetadataOnlyEmbedding(config.encoderProvider, resolveConfiguredEmbeddingDimension(config)),
+        vectorDatabase: new UnconfiguredVectorDatabase(),
+    });
+}
+function createMissingConfigIssue(missingEnv) {
+    const uniqueMissing = [...new Set(missingEnv)];
+    const message = `Satori provider setup is incomplete. Missing required environment variable(s): ${uniqueMissing.join(", ")}. MCP startup does not require provider credentials, but this tool call does.`;
+    return {
+        ok: false,
+        code: "MISSING_PROVIDER_CONFIG",
+        missingEnv: uniqueMissing,
+        message,
+        hints: {
+            setup: {
+                code: "MISSING_PROVIDER_CONFIG",
+                missingEnv: uniqueMissing,
+                nextSteps: uniqueMissing.map((name) => `Set ${name}, restart the MCP server, then retry the tool call.`),
+            }
+        }
+    };
+}
+export class ProviderRuntime {
+    constructor(args) {
+        this.embeddingRuntimePromise = null;
+        this.vectorRuntimePromise = null;
+        this.activeContexts = [];
+        this.config = args.config;
+        this.snapshotManager = args.snapshotManager;
+        this.runtimeFingerprint = args.runtimeFingerprint;
+        this.capabilities = args.capabilities;
+        this.readFileMaxLines = args.readFileMaxLines;
+        this.watchSyncEnabled = args.watchSyncEnabled;
+        this.watchDebounceMs = args.watchDebounceMs;
+        this.callGraphManager = args.callGraphManager;
+        this.now = args.now || (() => Date.now());
+    }
+    validate(operation) {
+        const missing = [];
+        if (operation === "embedding_vector") {
+            switch (this.config.encoderProvider) {
+                case "OpenAI":
+                    if (!this.config.openaiKey)
+                        missing.push("OPENAI_API_KEY");
+                    break;
+                case "VoyageAI":
+                    if (!this.config.voyageKey)
+                        missing.push("VOYAGEAI_API_KEY");
+                    break;
+                case "Gemini":
+                    if (!this.config.geminiKey)
+                        missing.push("GEMINI_API_KEY");
+                    break;
+                case "Ollama":
+                    break;
+            }
+        }
+        if (!this.config.milvusEndpoint) {
+            missing.push("MILVUS_ADDRESS");
+        }
+        return missing.length > 0 ? createMissingConfigIssue(missing) : null;
+    }
+    async requireToolContext(operation) {
+        const validation = this.validate(operation);
+        if (validation) {
+            return validation;
+        }
+        if (operation === "vector_only") {
+            if (!this.vectorRuntimePromise) {
+                this.vectorRuntimePromise = this.createRuntime(false).catch((error) => {
+                    this.vectorRuntimePromise = null;
+                    throw error;
+                });
+            }
+            return this.vectorRuntimePromise;
+        }
+        if (!this.embeddingRuntimePromise) {
+            this.embeddingRuntimePromise = this.createRuntime(true).catch((error) => {
+                this.embeddingRuntimePromise = null;
+                throw error;
+            });
+        }
+        return this.embeddingRuntimePromise;
+    }
+    async createRuntime(requireEmbedding) {
+        const embedding = requireEmbedding
+            ? createEmbeddingInstance(this.config)
+            : new MetadataOnlyEmbedding(this.config.encoderProvider, resolveConfiguredEmbeddingDimension(this.config));
+        if (requireEmbedding) {
+            logEmbeddingProviderInfo(this.config, embedding);
+        }
+        const vectorDatabase = new MilvusVectorDatabase({
+            address: this.config.milvusEndpoint,
+            ...(this.config.milvusApiToken && { token: this.config.milvusApiToken }),
+        });
+        const context = new Context({
+            embedding,
+            vectorDatabase,
+        });
+        const syncManager = new SyncManager(context, this.snapshotManager, {
+            watchEnabled: this.watchSyncEnabled,
+            watchDebounceMs: this.watchDebounceMs,
+            onSyncCompleted: async (codebasePath, stats) => {
+                try {
+                    const sidecar = await this.callGraphManager.rebuildIfSupportedDelta(codebasePath, stats.changedFiles, context.getActiveIgnorePatterns(codebasePath));
+                    if (sidecar) {
+                        this.snapshotManager.setCodebaseCallGraphSidecar(codebasePath, sidecar);
+                        this.snapshotManager.saveCodebaseSnapshot();
+                        console.log(`[CALL-GRAPH] Rebuilt sidecar for '${codebasePath}' from sync lifecycle callback.`);
+                    }
+                }
+                catch (error) {
+                    console.warn(`[CALL-GRAPH] Sync lifecycle rebuild failed for '${codebasePath}': ${error?.message || error}`);
+                }
+            }
+        });
+        const reranker = requireEmbedding && this.capabilities.hasReranker()
+            ? new VoyageAIReranker({
+                apiKey: this.config.voyageKey,
+                model: this.config.rankerModel || "rerank-2.5",
+            })
+            : null;
+        if (reranker) {
+            console.log(`[RERANKER] VoyageAI Reranker initialized with model: ${this.config.rankerModel || "rerank-2.5"}`);
+        }
+        const toolHandlers = new ToolHandlers(context, this.snapshotManager, syncManager, this.runtimeFingerprint, this.capabilities, this.now, this.callGraphManager, reranker);
+        const toolContext = {
+            context,
+            snapshotManager: this.snapshotManager,
+            syncManager,
+            capabilities: this.capabilities,
+            reranker,
+            runtimeFingerprint: this.runtimeFingerprint,
+            toolHandlers,
+            readFileMaxLines: this.readFileMaxLines,
+            providerRuntime: this,
+        };
+        this.activeContexts.push(toolContext);
+        return toolContext;
+    }
+    async shutdown() {
+        await Promise.all(this.activeContexts.map(async (toolContext) => {
+            toolContext.syncManager.stopBackgroundSync();
+            await toolContext.syncManager.stopWatcherMode();
+        }));
+    }
+}
+//# sourceMappingURL=provider-runtime.js.map

package/dist/server/start-server.d.ts

@@ -1,8 +1,9 @@
-import { Writable } from "node:stream";
+import { Readable, Writable } from "node:stream";
 import { ContextMcpConfig } from "../config.js";
 export type ServerRunMode = "mcp" | "cli";
 export interface StartMcpServerOptions {
     runMode?: ServerRunMode;
+    protocolStdin?: Readable;
     protocolStdout?: Writable;
     args?: string[];
 }
@@ -19,20 +20,22 @@ interface StartupLifecycleDependencies {
 export declare function runPostConnectStartupLifecycle(runMode: ServerRunMode, dependencies: StartupLifecycleDependencies): Promise<void>;
 declare class ContextMcpServer {
     private server;
-    private context;
+    private toolContext;
     private snapshotManager;
     private syncManager;
     private toolHandlers;
-    private reranker;
     private capabilities;
     private runtimeFingerprint;
     private readFileMaxLines;
     private watchSyncEnabled;
     private watchDebounceMs;
     private callGraphManager;
+    private providerRuntime;
     private runMode;
+    private protocolStdin?;
     private protocolStdout?;
-    constructor(config: ContextMcpConfig, runMode: ServerRunMode, protocolStdout?: Writable);
+    private keepAliveTimer;
+    constructor(config: ContextMcpConfig, runMode: ServerRunMode, protocolStdout?: Writable, protocolStdin?: Readable);
     private getCliTransportStdout;
     private getToolContext;
     /**

package/dist/server/start-server.js

@@ -4,9 +4,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { Context, MilvusVectorDatabase, VoyageAIReranker } from "@zokizuan/satori-core";
 import { buildRuntimeIndexFingerprint, createMcpConfig, logConfigurationSummary, showHelpMessage, } from "../config.js";
-import { createEmbeddingInstance, logEmbeddingProviderInfo } from "../embedding.js";
 import { CapabilityResolver } from "../core/capabilities.js";
 import { SnapshotManager } from "../core/snapshot.js";
 import { SyncManager } from "../core/sync.js";
@@ -14,6 +12,7 @@ import { ToolHandlers } from "../core/handlers.js";
 import { CallGraphSidecarManager } from "../core/call-graph.js";
 import { decideInterruptedIndexingRecovery } from "../core/indexing-recovery.js";
 import { getMcpToolList, toolRegistry } from "../tools/registry.js";
+import { createLocalOnlyContext, ProviderRuntime, resolveConfiguredEmbeddingDimension } from "./provider-runtime.js";
 export async function runPostConnectStartupLifecycle(runMode, dependencies) {
     if (runMode === "cli") {
         try {
@@ -57,9 +56,10 @@ function migrateLegacyStateDir() {
     }
 }
 class ContextMcpServer {
-    constructor(config, runMode, protocolStdout) {
-        this.reranker = null;
+    constructor(config, runMode, protocolStdout, protocolStdin) {
+        this.keepAliveTimer = null;
         this.runMode = runMode;
+        this.protocolStdin = protocolStdin;
         this.protocolStdout = protocolStdout;
         this.server = new Server({
             name: config.name,
@@ -69,100 +69,81 @@ class ContextMcpServer {
                 tools: {},
             },
         });
-        console.log(`[EMBEDDING] Initializing embedding provider: ${config.encoderProvider}`);
-        console.log(`[EMBEDDING] Using model: ${config.encoderModel}`);
-        const embedding = createEmbeddingInstance(config);
-        logEmbeddingProviderInfo(config, embedding);
         this.capabilities = new CapabilityResolver(config);
-        this.runtimeFingerprint = buildRuntimeIndexFingerprint(config, embedding.getDimension());
+        this.runtimeFingerprint = buildRuntimeIndexFingerprint(config, resolveConfiguredEmbeddingDimension(config));
         this.readFileMaxLines = Math.max(1, config.readFileMaxLines ?? 1000);
         this.watchSyncEnabled = config.watchSyncEnabled === true;
         this.watchDebounceMs = Math.max(1, config.watchDebounceMs ?? 5000);
         console.log(`[FINGERPRINT] Runtime index fingerprint: ${JSON.stringify(this.runtimeFingerprint)}`);
-        const vectorDatabase = new MilvusVectorDatabase({
-            address: config.milvusEndpoint,
-            ...(config.milvusApiToken && { token: config.milvusApiToken }),
-        });
-        this.context = new Context({
-            embedding,
-            vectorDatabase,
-        });
         this.snapshotManager = new SnapshotManager(this.runtimeFingerprint);
         this.callGraphManager = new CallGraphSidecarManager(this.runtimeFingerprint);
-        this.syncManager = new SyncManager(this.context, this.snapshotManager, {
+        const localContext = createLocalOnlyContext(config);
+        this.syncManager = new SyncManager(localContext, this.snapshotManager, {
             watchEnabled: this.watchSyncEnabled,
             watchDebounceMs: this.watchDebounceMs,
-            onSyncCompleted: async (codebasePath, stats) => {
-                try {
-                    const sidecar = await this.callGraphManager.rebuildIfSupportedDelta(codebasePath, stats.changedFiles, this.context.getActiveIgnorePatterns(codebasePath));
-                    if (sidecar) {
-                        this.snapshotManager.setCodebaseCallGraphSidecar(codebasePath, sidecar);
-                        this.snapshotManager.saveCodebaseSnapshot();
-                        console.log(`[CALL-GRAPH] Rebuilt sidecar for '${codebasePath}' from sync lifecycle callback.`);
-                    }
-                }
-                catch (error) {
-                    console.warn(`[CALL-GRAPH] Sync lifecycle rebuild failed for '${codebasePath}': ${error?.message || error}`);
-                }
-            }
         });
-        if (this.capabilities.hasReranker()) {
-            this.reranker = new VoyageAIReranker({
-                apiKey: config.voyageKey,
-                model: config.rankerModel || "rerank-2.5",
-            });
-            console.log(`[RERANKER] VoyageAI Reranker initialized with model: ${config.rankerModel || "rerank-2.5"}`);
-        }
-        this.toolHandlers = new ToolHandlers(this.context, this.snapshotManager, this.syncManager, this.runtimeFingerprint, this.capabilities, () => Date.now(), this.callGraphManager, this.reranker);
+        this.toolHandlers = new ToolHandlers(localContext, this.snapshotManager, this.syncManager, this.runtimeFingerprint, this.capabilities, () => Date.now(), this.callGraphManager, null);
+        this.providerRuntime = new ProviderRuntime({
+            config,
+            snapshotManager: this.snapshotManager,
+            runtimeFingerprint: this.runtimeFingerprint,
+            capabilities: this.capabilities,
+            readFileMaxLines: this.readFileMaxLines,
+            watchSyncEnabled: this.watchSyncEnabled,
+            watchDebounceMs: this.watchDebounceMs,
+            callGraphManager: this.callGraphManager,
+        });
+        this.toolContext = {
+            context: localContext,
+            snapshotManager: this.snapshotManager,
+            syncManager: this.syncManager,
+            capabilities: this.capabilities,
+            reranker: null,
+            runtimeFingerprint: this.runtimeFingerprint,
+            toolHandlers: this.toolHandlers,
+            readFileMaxLines: this.readFileMaxLines,
+            providerRuntime: this.providerRuntime,
+        };
         this.snapshotManager.loadCodebaseSnapshot();
         this.setupTools();
     }
     getCliTransportStdout() {
+        if (this.protocolStdout) {
+            return this.protocolStdout;
+        }
         if (this.runMode !== "cli") {
             return process.stdout;
         }
-        if (!this.protocolStdout) {
-            throw new Error("E_PROTOCOL_FAILURE Missing protocolStdout for cli mode");
-        }
-        return this.protocolStdout;
+        throw new Error("E_PROTOCOL_FAILURE Missing protocolStdout for cli mode");
     }
     getToolContext() {
-        return {
-            context: this.context,
-            snapshotManager: this.snapshotManager,
-            syncManager: this.syncManager,
-            capabilities: this.capabilities,
-            reranker: this.reranker,
-            runtimeFingerprint: this.runtimeFingerprint,
-            toolHandlers: this.toolHandlers,
-            readFileMaxLines: this.readFileMaxLines,
-        };
+        return this.toolContext;
     }
     /**
      * Verify cloud state and fix interrupted indexing snapshots.
      */
-    async verifyCloudState() {
+    async verifyCloudState(toolContext) {
         console.log("[STARTUP] Verifying interrupted indexing state against completion markers...");
-        const indexingCodebases = this.snapshotManager.getIndexingCodebases();
+        const indexingCodebases = toolContext.snapshotManager.getIndexingCodebases();
         let promotedCount = 0;
         let failedCount = 0;
         for (const codebasePath of indexingCodebases) {
-            const marker = typeof this.context.getIndexCompletionMarker === "function"
-                ? await this.context.getIndexCompletionMarker(codebasePath)
+            const marker = typeof toolContext.context.getIndexCompletionMarker === "function"
+                ? await toolContext.context.getIndexCompletionMarker(codebasePath)
                 : null;
             const decision = decideInterruptedIndexingRecovery(marker, this.runtimeFingerprint);
             if (decision.action === "promote_indexed") {
-                this.snapshotManager.setCodebaseIndexed(codebasePath, decision.stats, this.runtimeFingerprint, "verified");
+                toolContext.snapshotManager.setCodebaseIndexed(codebasePath, decision.stats, this.runtimeFingerprint, "verified");
                 promotedCount++;
                 console.log(`[STARTUP] Recovered interrupted indexing from marker: ${codebasePath} -> indexed`);
                 continue;
             }
-            this.snapshotManager.setCodebaseIndexFailed(codebasePath, decision.message);
+            toolContext.snapshotManager.setCodebaseIndexFailed(codebasePath, decision.message);
             failedCount++;
             console.log(`[STARTUP] Marked interrupted indexing as failed: ${codebasePath} (${decision.reason})`);
         }
         if (promotedCount > 0 || failedCount > 0) {
-            this.snapshotManager.saveCodebaseSnapshot();
+            toolContext.snapshotManager.saveCodebaseSnapshot();
             console.log(`[STARTUP] Recovery summary: promoted=${promotedCount}, failed=${failedCount}`);
         }
         else {
@@ -192,25 +173,26 @@ class ContextMcpServer {
     }
     async start() {
         console.log("Starting Satori MCP server...");
-        const transport = this.runMode === "cli"
-            ? new StdioServerTransport(process.stdin, this.getCliTransportStdout())
+        const transportStdin = this.protocolStdin ?? process.stdin;
+        const transport = this.runMode === "cli" || this.protocolStdin || this.protocolStdout
+            ? new StdioServerTransport(transportStdin, this.getCliTransportStdout())
             : new StdioServerTransport();
         await this.server.connect(transport);
+        transportStdin.resume();
+        this.keepAliveTimer = setInterval(() => {
+            // Keep stdio MCP process alive when startup has no background provider lifecycle.
+        }, 60 * 60 * 1000);
         console.log("MCP server started and listening on stdio.");
-        await runPostConnectStartupLifecycle(this.runMode, {
-            watchSyncEnabled: this.watchSyncEnabled,
-            verifyCloudState: () => this.verifyCloudState(),
-            onVerifyCloudStateError: (error) => {
-                const message = error instanceof Error ? error.message : String(error);
-                console.error("[STARTUP] Error verifying cloud state:", message);
-            },
-            syncManager: this.syncManager,
-        });
     }
     async shutdown() {
         console.log("Shutting down Satori MCP server...");
+        if (this.keepAliveTimer) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = null;
+        }
         this.syncManager.stopBackgroundSync();
         await this.syncManager.stopWatcherMode();
+        await this.providerRuntime.shutdown();
     }
 }
 function isHelpRequested(args) {
@@ -226,7 +208,7 @@ export async function startMcpServerFromEnv(options = {}) {
     migrateLegacyStateDir();
     const config = createMcpConfig();
     logConfigurationSummary(config);
-    const server = new ContextMcpServer(config, runMode, options.protocolStdout);
+    const server = new ContextMcpServer(config, runMode, options.protocolStdout, options.protocolStdin);
     await server.start();
     return server;
 }

package/dist/tools/manage_index.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatZodError } from "./types.js";
+import { formatManageProviderConfigError, isMissingProviderConfigIssue } from "./setup-errors.js";
 const actionEnum = z.enum(["create", "reindex", "sync", "status", "clear"]);
 const manageIndexInputSchema = z.object({
     action: actionEnum.describe("Required operation to run."),
@@ -26,17 +27,28 @@ export const manageIndexTool = {
             };
         }
         const input = parsed.data;
+        const providerOperation = input.action === "clear"
+            ? "vector_only"
+            : (input.action === "create" || input.action === "reindex" || input.action === "sync")
+                ? "embedding_vector"
+                : null;
+        const executionContext = providerOperation && ctx.providerRuntime
+            ? await ctx.providerRuntime.requireToolContext(providerOperation)
+            : ctx;
+        if (isMissingProviderConfigIssue(executionContext)) {
+            return formatManageProviderConfigError(input.action, input.path, executionContext);
+        }
         switch (input.action) {
             case 'create':
-                return ctx.toolHandlers.handleIndexCodebase(input);
+                return executionContext.toolHandlers.handleIndexCodebase(input);
             case 'reindex':
-                return ctx.toolHandlers.handleReindexCodebase(input);
+                return executionContext.toolHandlers.handleReindexCodebase(input);
             case 'sync':
-                return ctx.toolHandlers.handleSyncCodebase(input);
+                return executionContext.toolHandlers.handleSyncCodebase(input);
             case 'status':
-                return ctx.toolHandlers.handleGetIndexingStatus(input);
+                return executionContext.toolHandlers.handleGetIndexingStatus(input);
             case 'clear':
-                return ctx.toolHandlers.handleClearIndex(input);
+                return executionContext.toolHandlers.handleClearIndex(input);
             default:
                 return {
                     content: [{

package/dist/tools/search_codebase.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { formatZodError } from "./types.js";
 import { emitSearchTelemetry } from "../telemetry/search.js";
+import { formatSearchProviderConfigError, isMissingProviderConfigIssue } from "./setup-errors.js";
 function getProfile(ctx) {
     const locality = ctx.capabilities.getEmbeddingLocality();
     const profile = ctx.capabilities.getPerformanceProfile();
@@ -92,11 +93,43 @@ export const searchCodebaseTool = {
                 isError: true
             };
         }
-        const input = parsed.data;
+        const input = {
+            ...parsed.data,
+            scope: parsed.data.scope ?? "runtime",
+            resultMode: parsed.data.resultMode ?? "grouped",
+            groupBy: parsed.data.groupBy ?? "symbol",
+            rankingMode: parsed.data.rankingMode ?? "auto_changed_first",
+        };
         const startedAt = Date.now();
         const limit = Math.max(1, Math.min(ctx.capabilities.getMaxSearchLimit(), input.limit ?? ctx.capabilities.getDefaultSearchLimit()));
         const profile = getProfile(ctx);
-        const response = await ctx.toolHandlers.handleSearchCode({
+        const executionContext = ctx.providerRuntime
+            ? await ctx.providerRuntime.requireToolContext("embedding_vector")
+            : ctx;
+        if (isMissingProviderConfigIssue(executionContext)) {
+            const response = formatSearchProviderConfigError({
+                ...input,
+                limit,
+            }, executionContext);
+            emitSearchTelemetry({
+                event: "search_executed",
+                tool_name: "search_codebase",
+                profile,
+                query_length: input.query.length,
+                limit_requested: limit,
+                results_before_filter: 0,
+                results_after_filter: 0,
+                results_returned: 0,
+                excluded_by_ignore: 0,
+                reranker_used: false,
+                reranker_attempted: false,
+                latency_ms: Date.now() - startedAt,
+                parallel_fanout: true,
+                error: executionContext.code,
+            });
+            return response;
+        }
+        const response = await executionContext.toolHandlers.handleSearchCode({
             ...input,
             limit
         });

package/dist/tools/setup-errors.d.ts

@@ -0,0 +1,14 @@
+import { ManageIndexAction } from "../core/manage-types.js";
+import { SearchGroupBy, SearchResultMode, SearchScope } from "../core/search-constants.js";
+import { MissingProviderConfigIssue, ToolResponse } from "./types.js";
+export declare function isMissingProviderConfigIssue(value: unknown): value is MissingProviderConfigIssue;
+export declare function formatManageProviderConfigError(action: ManageIndexAction, path: string, issue: MissingProviderConfigIssue): ToolResponse;
+export declare function formatSearchProviderConfigError(input: {
+    path: string;
+    query: string;
+    scope: SearchScope;
+    groupBy: SearchGroupBy;
+    resultMode: SearchResultMode;
+    limit: number;
+}, issue: MissingProviderConfigIssue): ToolResponse;
+//# sourceMappingURL=setup-errors.d.ts.map

package/dist/tools/setup-errors.js

@@ -0,0 +1,48 @@
+export function isMissingProviderConfigIssue(value) {
+    return Boolean(value)
+        && typeof value === "object"
+        && value.ok === false
+        && value.code === "MISSING_PROVIDER_CONFIG";
+}
+export function formatManageProviderConfigError(action, path, issue) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    tool: "manage_index",
+                    version: 1,
+                    action,
+                    path,
+                    status: "error",
+                    reason: "missing_provider_config",
+                    code: issue.code,
+                    message: issue.message,
+                    humanText: issue.message,
+                    hints: issue.hints,
+                }, null, 2)
+            }]
+    };
+}
+export function formatSearchProviderConfigError(input, issue) {
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: "not_ready",
+                    reason: "missing_provider_config",
+                    code: issue.code,
+                    path: input.path,
+                    query: input.query,
+                    scope: input.scope,
+                    groupBy: input.groupBy,
+                    resultMode: input.resultMode,
+                    limit: input.limit,
+                    freshnessDecision: null,
+                    message: issue.message,
+                    hints: issue.hints,
+                    results: [],
+                }, null, 2)
+            }]
+    };
+}
+//# sourceMappingURL=setup-errors.js.map

package/dist/tools/types.d.ts

@@ -5,6 +5,20 @@ import { SnapshotManager } from "../core/snapshot.js";
 import { SyncManager } from "../core/sync.js";
 import { IndexFingerprint } from "../config.js";
 import { ToolHandlers } from "../core/handlers.js";
+export type ProviderBackedOperation = "embedding_vector" | "vector_only";
+export interface MissingProviderConfigIssue {
+    ok: false;
+    code: "MISSING_PROVIDER_CONFIG";
+    missingEnv: string[];
+    message: string;
+    hints: {
+        setup: {
+            code: "MISSING_PROVIDER_CONFIG";
+            missingEnv: string[];
+            nextSteps: string[];
+        };
+    };
+}
 export interface ToolResponse {
     content: Array<{
         type: string;
@@ -22,6 +36,9 @@ export interface ToolContext {
     runtimeFingerprint: IndexFingerprint;
     toolHandlers: ToolHandlers;
     readFileMaxLines: number;
+    providerRuntime?: {
+        requireToolContext(operation: ProviderBackedOperation): Promise<ToolContext | MissingProviderConfigIssue>;
+    };
 }
 export interface McpTool<TSchema extends z.ZodTypeAny = z.ZodTypeAny> {
     name: string;

package/package.json

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