@zokizuan/satori-mcp 4.10.1 → 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

@@ -4,38 +4,22 @@ Read-only MCP server for Satori. It gives coding agents six deterministic tools
 
 ## Install
 
-Prefer the CLI installer when possible:
+Use the CLI installer for normal setup:
 
 ```bash
-npx -y @zokizuan/satori-cli@0.3.2 install --client codex
-npx -y @zokizuan/satori-cli@0.3.2 install --client claude
-npx -y @zokizuan/satori-cli@0.3.2 doctor
+npx -y @zokizuan/satori-cli@0.4.1 install --client all
+npx -y @zokizuan/satori-cli@0.4.1 doctor
 ```
 
-Manual MCP config:
-
-```json
-{
-  "mcpServers": {
-    "satori": {
-      "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@4.10.1"],
-      "timeout": 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"
-      }
-    }
-  }
-}
+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.
+
+Advanced direct execution is available through the package bin:
+
+```bash
+npx -y @zokizuan/satori-mcp@4.11.1 --help
 ```
 
-Keep startup timeout at `180000` for first-run package resolution.
+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
 
@@ -60,6 +44,41 @@ 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
+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
+```
+
+The full generated tool reference below is kept in the npm README for MCP clients and package consumers.
+
 <!-- TOOLS_START -->
 
 ## Tool Reference
@@ -86,7 +105,7 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 |---|---|---|---|---|
 | `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. Docs scope skips reranker by policy in the current tool surface. |
+| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime includes source/runtime code and tests while excluding docs/generated/artifacts/landing/fixtures; 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. |

package/dist/cli/args.d.ts

@@ -47,7 +47,7 @@ export interface ResolveRawArgsOptions {
     stdin?: NodeJS.ReadStream;
     stdinTimeoutMs: number;
 }
-export type InstallClient = "all" | "claude" | "codex";
+export type InstallClient = "all" | "claude" | "codex" | "opencode";
 export declare function parseCliArgs(argv: string[]): ParsedCliInput;
 export declare function resolveRawArguments(rawArgsMode: RawArgsMode, options: ResolveRawArgsOptions): Promise<Record<string, unknown>>;
 export declare function parseWrapperArgumentsFromSchema(toolName: string, inputSchema: unknown, wrapperArgs: string[]): Record<string, unknown>;

package/dist/cli/args.js

@@ -20,7 +20,7 @@ function stripFlagPrefix(token) {
 }
 function parseGlobalOptions(argv) {
     const globals = {
-        startupTimeoutMs: 180000,
+        startupTimeoutMs: 30000,
         callTimeoutMs: 600000,
         format: "json",
         debug: false,
@@ -116,8 +116,8 @@ function parseInstallCommand(kind, args) {
         const token = args[i];
         if (token === "--client") {
             const next = args[i + 1];
-            if (next !== "all" && next !== "claude" && next !== "codex") {
-                throw new CliError("E_USAGE", "--client must be one of: all, claude, codex.", 2);
+            if (next !== "all" && next !== "claude" && next !== "codex" && next !== "opencode") {
+                throw new CliError("E_USAGE", "--client must be one of: all, claude, codex, opencode.", 2);
             }
             client = next;
             i += 1;

package/dist/cli/index.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type ManagedRuntimeCommand } from "./install.js";
 interface RunCliOptions {
     writeStdout?: (text: string) => void;
     writeStderr?: (text: string) => void;
@@ -11,6 +12,7 @@ interface RunCliOptions {
     callTimeoutMs?: number;
     cwd?: string;
     installabilityVerifier?: () => string | Promise<string>;
+    installRuntimeCommand?: ManagedRuntimeCommand;
     connectSession?: (options: {
         command: string;
         args: string[];

package/dist/cli/index.js

@@ -44,8 +44,8 @@ function buildHelpPayload() {
     return {
         usage: "satori-cli <command>",
         commands: [
-            "install [--client all|codex|claude] [--dry-run]",
-            "uninstall [--client all|codex|claude] [--dry-run]",
+            "install [--client all|codex|claude|opencode] [--dry-run]",
+            "uninstall [--client all|codex|claude|opencode] [--dry-run]",
             "tools list",
             "tool call <toolName> --args-json '<json>'",
             "tool call <toolName> --args-file <path>",
@@ -196,11 +196,14 @@ export async function runCli(argv, options = {}) {
             return 0;
         }
         if (parsed.command.kind === "install" || parsed.command.kind === "uninstall") {
+            let packageSpecifier;
             if (parsed.command.kind === "install") {
-                await (options.installabilityVerifier || verifyManagedPackageInstallability)();
+                packageSpecifier = await (options.installabilityVerifier || verifyManagedPackageInstallability)();
             }
             const result = executeInstallCommand(parsed.command, {
                 homeDir: effectiveEnv.HOME,
+                packageSpecifier,
+                runtimeCommand: options.installRuntimeCommand,
             });
             emitJson(writers, result);
             if (parsed.globals.format === "text") {

package/dist/cli/install.d.ts

@@ -1,5 +1,11 @@
+import { execFileSync } from "node:child_process";
 import type { InstallClient } from "./args.js";
+type ExecFileSyncLike = typeof execFileSync;
 type ClientName = Exclude<InstallClient, "all">;
+export interface ManagedRuntimeCommand {
+    command: string;
+    args: string[];
+}
 export interface InstallCommandInput {
     kind: "install" | "uninstall";
     client: InstallClient;
@@ -9,13 +15,17 @@ export interface InstallCommandOptions {
     homeDir?: string;
     packageSpecifier?: string;
     skillAssetRoot?: string;
+    runtimeCommand?: ManagedRuntimeCommand;
+    execFileSyncImpl?: ExecFileSyncLike;
 }
 export interface ClientInstallResult {
     client: ClientName;
     configPath: string;
-    skillsPath: string;
+    skillsPath?: string;
+    instructionsPath?: string;
     configChanged: boolean;
     skillsChanged: boolean;
+    instructionsChanged: boolean;
     status: "updated" | "unchanged";
     dryRun: boolean;
 }