@zokizuan/satori-mcp 4.11.0 → 4.11.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ham-zax
+Copyright (c) 2026 Hamza (@ham-zax)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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.0 install --client all
-npx -y @zokizuan/satori-cli@0.4.0 doctor
+npx -y @zokizuan/satori-cli@0.4.1 install --client all
+npx -y @zokizuan/satori-cli@0.4.1 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,9 +16,11 @@ The CLI installer supports `codex`, `claude`, `opencode`, and `all`. It creates
 Advanced direct execution is available through the package bin:
 
 ```bash
-npx -y @zokizuan/satori-mcp@4.11.0 --help
+npx -y @zokizuan/satori-mcp@4.11.1 --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.
+
 ## Agent Workflow
 
 ```text
@@ -42,6 +44,27 @@ Important defaults:
 
 Configure an embedding provider and Milvus-compatible backend before indexing. Supported embedding providers are OpenAI, VoyageAI, Gemini, and Ollama. Changing provider, model, dimension, vector store, or schema requires a reindex because those values are part of the index fingerprint.
 
+MCP startup, `tools/list`, and installer operations are lazy with respect to provider credentials. Missing provider values become `MISSING_PROVIDER_CONFIG` only when a provider-backed tool call needs them.
+
+Installer-managed client config starts the resident launcher. Runtime provider settings come from the MCP client's environment and are exposed in native client config:
+
+- Codex writes active `env_vars` forwarding plus an optional commented `[mcp_servers.satori.env]` template in `~/.codex/config.toml`.
+- Claude Code writes `mcpServers.satori.env` in `~/.claude.json` with `${VAR:-}` pass-through values.
+- OpenCode writes `mcp.satori.environment` in `~/.config/opencode/opencode.json` with `{env:VAR}` pass-through values.
+
+Users who want literal values in a client config can replace the generated pass-through value for that client. In Codex, uncomment or add this table outside the installer-managed launcher block so reinstalls keep edits:
+
+```toml
+[mcp_servers.satori.env]
+EMBEDDING_PROVIDER = "VoyageAI"
+EMBEDDING_MODEL = "voyage-4-large"
+EMBEDDING_OUTPUT_DIMENSION = "1024"
+VOYAGEAI_API_KEY = "pa-..."
+VOYAGEAI_RERANKER_MODEL = "rerank-2.5"
+MILVUS_ADDRESS = "https://your-zilliz-endpoint"
+MILVUS_TOKEN = "your-zilliz-token"
+```
+
 Cloud-quality setup:
 
 ```bash

package/dist/cli/install.js

@@ -7,12 +7,47 @@ import { applyEdits, modify, parse as parseJsonc } from "jsonc-parser";
 import { CliError } from "./errors.js";
 const MANAGED_BLOCK_START = "# >>> satori-cli managed satori start >>>";
 const MANAGED_BLOCK_END = "# <<< satori-cli managed satori end <<<";
+const CODEX_ENV_TEMPLATE_START = "# >>> satori-cli optional satori env template >>>";
+const CODEX_ENV_TEMPLATE_END = "# <<< satori-cli optional satori env template <<<";
 const INSTRUCTIONS_BLOCK_START = "<!-- satori-mcp:start -->";
 const INSTRUCTIONS_BLOCK_END = "<!-- satori-mcp:end -->";
 const OWNED_SKILL_DIRS = ["satori"];
 const MANAGED_RUNTIME_DIR = "mcp-runtime";
 const MANAGED_BIN_DIR = "bin";
 const MANAGED_LAUNCHER_FILE = "satori-mcp.js";
+const SATORI_RUNTIME_ENV_VARS = [
+    "EMBEDDING_PROVIDER",
+    "EMBEDDING_MODEL",
+    "EMBEDDING_OUTPUT_DIMENSION",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "VOYAGEAI_API_KEY",
+    "VOYAGEAI_RERANKER_MODEL",
+    "GEMINI_API_KEY",
+    "GEMINI_BASE_URL",
+    "OLLAMA_HOST",
+    "OLLAMA_MODEL",
+    "MILVUS_ADDRESS",
+    "MILVUS_TOKEN",
+    "READ_FILE_MAX_LINES",
+    "MCP_ENABLE_WATCHER",
+    "MCP_WATCH_DEBOUNCE_MS",
+];
+const CODEX_ENV_TEMPLATE_LINES = [
+    CODEX_ENV_TEMPLATE_START,
+    "# Optional direct Codex env values. Uncomment/fill these if you prefer",
+    "# ~/.codex/config.toml to store Satori runtime settings directly.",
+    "# This template is outside the launcher block so reinstall keeps edits.",
+    "# [mcp_servers.satori.env]",
+    "# EMBEDDING_PROVIDER = \"VoyageAI\"",
+    "# EMBEDDING_MODEL = \"voyage-4-large\"",
+    "# EMBEDDING_OUTPUT_DIMENSION = \"1024\"",
+    "# VOYAGEAI_API_KEY = \"pa-...\"",
+    "# VOYAGEAI_RERANKER_MODEL = \"rerank-2.5\"",
+    "# MILVUS_ADDRESS = \"https://your-zilliz-endpoint\"",
+    "# MILVUS_TOKEN = \"your-zilliz-token\"",
+    CODEX_ENV_TEMPLATE_END,
+];
 const OPENCODE_INSTRUCTIONS = `# Satori MCP
 
 This project uses Satori MCP for semantic code search, deterministic navigation, and index lifecycle management.
@@ -60,7 +95,7 @@ function resolveClientTargets(homeDir) {
         },
         {
             client: "claude",
-            configPath: path.join(homeDir, ".claude", "settings.json"),
+            configPath: path.join(homeDir, ".claude.json"),
             companion: {
                 kind: "skills",
                 path: path.join(homeDir, ".claude", "skills"),
@@ -107,6 +142,21 @@ function toTomlString(value) {
 function buildTomlArray(values) {
     return `[${values.map(toTomlString).join(", ")}]`;
 }
+function runtimeEnvMap(valueForName) {
+    return Object.fromEntries(SATORI_RUNTIME_ENV_VARS.map((name) => [name, valueForName(name)]));
+}
+function objectValue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function mergeRuntimeEnv(existing, defaults) {
+    return {
+        ...defaults,
+        ...(objectValue(existing) ?? {}),
+    };
+}
 function packageNameFromSpecifier(packageSpecifier) {
     if (packageSpecifier.startsWith("@")) {
         const versionMarker = packageSpecifier.indexOf("@", 1);
@@ -262,10 +312,25 @@ function buildCodexManagedBlock(runtimeCommand) {
         "[mcp_servers.satori]",
         `command = ${toTomlString(runtimeCommand.command)}`,
         `args = ${buildTomlArray(runtimeCommand.args)}`,
+        "# Satori reads provider/vector settings from environment at MCP startup.",
+        "# env_vars forwards these names from Codex's parent environment when set.",
+        `env_vars = ${buildTomlArray([...SATORI_RUNTIME_ENV_VARS])}`,
         MANAGED_BLOCK_END,
         "",
     ].join("\n");
 }
+function buildCodexEnvTemplateBlock() {
+    return `${CODEX_ENV_TEMPLATE_LINES.join("\n")}\n`;
+}
+function codexHasSatoriEnvTable(content) {
+    return /^\s*\[mcp_servers\.satori\.env\]\s*$/m.test(content);
+}
+function ensureCodexEnvTemplate(content) {
+    if (content.includes(CODEX_ENV_TEMPLATE_START) || codexHasSatoriEnvTable(content)) {
+        return content;
+    }
+    return `${normalizeTrailingNewline(content)}\n${buildCodexEnvTemplateBlock()}`;
+}
 function codexHasUnmanagedSatoriSection(content) {
     if (!content.includes("[mcp_servers.satori]")) {
         return false;
@@ -288,6 +353,7 @@ function prepareCodexInstall(filePath, runtimeCommand) {
     else {
         next = `${normalizeTrailingNewline(current)}\n${managedBlock}`;
     }
+    next = ensureCodexEnvTemplate(next);
     return {
         changed: next !== current,
         apply: () => {
@@ -341,10 +407,12 @@ function parseJsonObject(filePath) {
     }
     return parsed;
 }
-function buildClaudeServerConfig(runtimeCommand) {
+function buildClaudeServerConfig(runtimeCommand, existing) {
     return {
+        type: "stdio",
         command: runtimeCommand.command,
         args: runtimeCommand.args,
+        env: mergeRuntimeEnv(existing?.env, runtimeEnvMap((name) => `\${${name}:-}`)),
     };
 }
 function isManagedLauncherPath(value) {
@@ -370,7 +438,8 @@ function isManagedClaudeEntry(value) {
 function prepareClaudeInstall(filePath, runtimeCommand) {
     const currentObject = parseJsonObject(filePath);
     const currentSerialized = JSON.stringify(currentObject);
-    const desiredServer = buildClaudeServerConfig(runtimeCommand);
+    const existingSatori = objectValue(currentObject.mcpServers?.satori);
+    const desiredServer = buildClaudeServerConfig(runtimeCommand, existingSatori);
     const mcpServersValue = currentObject.mcpServers;
     let mcpServers;
     if (mcpServersValue === undefined) {
@@ -382,8 +451,7 @@ function prepareClaudeInstall(filePath, runtimeCommand) {
     else {
         throw new CliError("E_USAGE", `Expected mcpServers to be an object in ${filePath}.`, 2);
     }
-    const existingSatori = mcpServers.satori;
-    if (existingSatori !== undefined && !isManagedClaudeEntry(existingSatori)) {
+    if (mcpServers.satori !== undefined && !isManagedClaudeEntry(mcpServers.satori)) {
         throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcpServers.satori manually or align it to the managed Satori form first.`, 2);
     }
     mcpServers.satori = {
@@ -443,11 +511,12 @@ function parseJsoncObject(filePath, content) {
     }
     return parsed;
 }
-function buildOpenCodeServerConfig(runtimeCommand) {
+function buildOpenCodeServerConfig(runtimeCommand, existing) {
     return {
         enabled: true,
         type: "local",
         command: [runtimeCommand.command, ...runtimeCommand.args],
+        environment: mergeRuntimeEnv(existing?.environment, runtimeEnvMap((name) => `{env:${name}}`)),
     };
 }
 function isManagedOpenCodeEntry(value) {
@@ -492,7 +561,7 @@ function prepareOpenCodeInstall(filePath, runtimeCommand) {
     if (existingSatori !== undefined && !isManagedOpenCodeEntry(existingSatori)) {
         throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcp.satori manually or align it to the managed Satori form first.`, 2);
     }
-    return mutateJsonc(filePath, current, ["mcp", "satori"], buildOpenCodeServerConfig(runtimeCommand));
+    return mutateJsonc(filePath, current, ["mcp", "satori"], buildOpenCodeServerConfig(runtimeCommand, objectValue(existingSatori)));
 }
 function prepareOpenCodeUninstall(filePath) {
     const current = readTextIfExists(filePath);

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.0 install --client all
+  npx -y @zokizuan/satori-cli@0.4.1 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/handlers.js

@@ -3541,6 +3541,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                         rerankerFailurePhase = 'parse_results';
                         throw new Error('reranker_parse_failed');
                     }
+                    let rerankerUpdatedCandidates = 0;
                     for (let idx = 0; idx < rerankSlice.length; idx++) {
                         const rank = rerankRanks.get(idx);
                         if (!rank) {
@@ -3549,9 +3550,10 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                         const rerankRrf = 1 / (SEARCH_RERANK_RRF_K + rank);
                         rerankSlice[idx].fusionScore += SEARCH_RERANK_WEIGHT * rerankRrf;
                         rerankSlice[idx].finalScore = (rerankSlice[idx].fusionScore + rerankSlice[idx].lexicalScore) * rerankSlice[idx].pathMultiplier * rerankSlice[idx].changedFilesMultiplier;
+                        rerankerUpdatedCandidates++;
                     }
                     exactMatchPinningApplied = this.sortSearchCandidates(scored, rerankDecision.exactMatchPinningEnabled, parsedOperators.must.length > 0) || exactMatchPinningApplied;
-                    rerankerApplied = true;
+                    rerankerApplied = rerankerUpdatedCandidates > 0;
                 }
                 catch {
                     if (!rerankerFailurePhase) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "4.11.0",
+  "version": "4.11.1",
   "description": "MCP server for Satori with agent-safe semantic search and indexing",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "jsonc-parser": "^3.3.1",
     "zod": "^3.25.55",
     "zod-to-json-schema": "^3.25.1",
-    "@zokizuan/satori-core": "1.6.0"
+    "@zokizuan/satori-core": "1.6.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",