@zokizuan/satori-mcp 4.10.0 → 4.11.0

package/README.md

@@ -1,62 +1,60 @@
 # @zokizuan/satori-mcp
 
-MCP server for Satori — agent-safe semantic code search and indexing.
-
-## Features
-
-- 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 capability-driven language support (currently TS/JS/Python)
-- 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
-- Deterministic train-in-the-error responses for incompatible or legacy index states
-- Query-time exclusion support with `.gitignore`-style matching
-- Structured search telemetry logs (`[TELEMETRY]` JSON to `stderr`)
-- Zod-first tool schemas converted to MCP JSON Schema for `ListTools`
-- Auto-generated tool docs from live tool schemas
-- `read_file` line-range retrieval with default large-file truncation guard and optional `mode="annotated"` metadata envelope
-- Optional proactive sync watcher mode (debounced filesystem events for explicitly touched roots in the current session)
-- Index-time AST scope breadcrumbs (TS/JS/Python) rendered in search output as `🧬 Scope`
-- Fingerprint schema `dense_v3`/`hybrid_v3` with hard gate for all pre-v3 indexes
-
-## Architecture
+Read-only MCP server for Satori. It gives coding agents six deterministic tools for repo search, symbol navigation, call graph context, bounded file reads, and index lifecycle management.
 
+## Install
+
+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
 ```
-[MCP Client]
-    -> [index.ts bootstrap + ListTools/CallTool]
-    -> [tool registry]
-    -> [manage_index | search_codebase | call_graph | file_outline | read_file | list_codebases]
-    -> [ToolContext DI]
-       -> [CapabilityResolver]
-       -> [SnapshotManager v3 + access gate]
-       -> [Context / Vector store / Embedding / Reranker adapters]
+
+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.0 --help
 ```
 
-Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposing call-chain traversal and file-level navigation as first-class operations.
+## Agent Workflow
 
-## read_file Behavior
+```text
+list_codebases
+manage_index action="create" path="/absolute/path/to/repo"
+search_codebase path="/absolute/path/to/repo" query="where is auth refresh handled"
+file_outline path="/absolute/path/to/repo" file="src/auth.ts"
+call_graph path="/absolute/path/to/repo" symbolRef={...} direction="both"
+read_file path="/absolute/path/to/repo/src/auth.ts" start_line=1 end_line=160
+```
+
+Important defaults:
+
+- `search_codebase` starts with runtime code, grouped by symbol.
+- `search_codebase` runs freshness checks before returning results.
+- `read_file` is bounded and can return continuation hints.
+- `requires_reindex` means reindex first, then retry the original call.
+- `manage_index action="clear"` is destructive and should be explicit.
 
-- Supports optional `start_line` and `end_line` (1-based, inclusive)
-- When no range is provided and file length exceeds `READ_FILE_MAX_LINES` (default `1000`), output is truncated and includes a continuation hint with `path` and next `start_line`
-- Optional `mode="annotated"` returns content plus `outlineStatus`, `outline`, `hasMore`, and reindex hints when sidecar data is unavailable
+## Runtime Requirements
 
-## Proactive Sync
+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.
+
+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
+```
 
-- Enabled by default. Set `MCP_ENABLE_WATCHER=false` to disable
-- Debounce window via `MCP_WATCH_DEBOUNCE_MS` (default `5000`)
-- Watchers are session-scoped: startup does not watch every indexed codebase, only roots touched by successful index/search/navigation/read flows in the current session
-- 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`
-  - Ignored/hidden paths are excluded (`node_modules`, `.git`, build artifacts, dotfiles)
-- On shutdown (`SIGINT`/`SIGTERM`), watchers are explicitly closed
+The full generated tool reference below is kept in the npm README for MCP clients and package consumers.
 
 <!-- TOOLS_START -->
 
@@ -84,7 +82,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. |
@@ -139,171 +137,21 @@ 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)
-
-```json
-{
-  "mcpServers": {
-    "satori": {
-      "command": "npx",
-      "args": ["-y", "@zokizuan/satori-mcp@4.10.0"],
-      "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"
-      }
-    }
-  }
-}
-```
-
-### TOML-style (Claude Code CLI)
-
-```toml
-[mcp_servers.satori]
-command = "npx"
-args = ["-y", "@zokizuan/satori-mcp@4.10.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
-{
-  "mcpServers": {
-    "satori": {
-      "command": "node",
-      "args": ["/absolute/path/to/satori/packages/mcp/dist/index.js"],
-      "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"
-      }
-    }
-  }
-}
-```
+## Notes
 
-Never commit real API keys/tokens into repo config files.
+- `open_symbol` resolves exact symbols inside the same file passed to `read_file.path`.
+- `MILVUS_TOKEN` is optional auth; local unauthenticated Milvus only needs `MILVUS_ADDRESS`.
+- MCP startup does not require provider credentials or a live Milvus backend. Provider-backed calls report `MISSING_PROVIDER_CONFIG` when setup is incomplete.
+- `MISSING_PROVIDER_CONFIG` is an active setup failure only when it appears as a tool response `code` or `reason`.
 
-## Run Locally
+## Local Development
 
 ```bash
 pnpm --filter @zokizuan/satori-mcp start
-```
-
-## Shell CLI (`@zokizuan/satori-cli`)
-
-The shell-first installer/client now lives in a separate package: `@zokizuan/satori-cli`.
-
-### Install / Uninstall
-
-Supported installer targets in Phase 1:
-- `codex`
-- `claude`
-- `all`
-
-Examples:
-
-```bash
-npx -y @zokizuan/satori-cli@0.3.1 install --client codex
-npx -y @zokizuan/satori-cli@0.3.1 install --client claude
-npx -y @zokizuan/satori-cli@0.3.1 install --client all --dry-run
-npx -y @zokizuan/satori-cli@0.3.1 uninstall --client codex
-npx -y @zokizuan/satori-cli@0.3.1 doctor
-```
-
-Install and uninstall run before MCP session startup, only touch Satori-managed config, and copy/remove these packaged skills:
-- `satori-search`
-- `satori-navigation`
-- `satori-indexing`
-
-### Commands
-
-```bash
-satori-cli tools list
-satori-cli tool call <toolName> --args-json '{"path":"/abs/repo","query":"auth"}'
-satori-cli tool call <toolName> --args-file ./args.json
-satori-cli tool call <toolName> --args-json @-
-satori-cli <toolName> [schema-subset flags]
-```
-
-Global flags (`--startup-timeout-ms`, `--call-timeout-ms`, `--format`, `--debug`) must appear before the command token.
-Example: `satori-cli --debug tools list`.
-
-### Output + Exit Contract
-
-- `stdout`: JSON only
-- `stderr`: diagnostics and text summaries
-- exit `0`: success
-- exit `1`: tool-level error (`isError=true` or structured envelope `status!="ok"`)
-- exit `2`: usage/argument/schema-subset errors
-- exit `3`: startup/transport/protocol/timeout failures
-
-### Wrapper Flag Support
-
-Wrapper mode (`satori-cli <toolName> ...`) supports a strict subset from reflected `tools/list` schemas:
-
-- primitive properties (`string|number|integer|boolean`)
-- enums of primitives
-- arrays of primitives (repeat flags in insertion order)
-- object properties only via `--<prop>-json '{...}'`
-
-Tool-level flags that overlap global names are preserved in wrapper mode once command parsing starts.
-Example: `satori-cli search_codebase --path /repo --query auth --debug` forwards `debug=true` to the tool.
-For boolean wrapper flags, `--flag` implies `true` and `--flag false` is supported.
-
-Unsupported schema shapes (for example `oneOf`, `anyOf`, `$ref`, complex arrays, nested expansion) return `E_SCHEMA_UNSUPPORTED` with fallback guidance to `--args-json` / `--args-file`.
-
-### Run Mode Semantics
-
-When spawned by `satori-cli`, server process mode is `SATORI_RUN_MODE=cli`:
-
-- startup background loops are disabled (`verifyCloudState`, watcher mode, background sync)
-- stdio safety hardening is enabled (`stdout` protocol-only, logs to `stderr`)
-- tool behavior stays on-demand and uses the same six MCP tools
-
-`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.
-
-`MISSING_PROVIDER_CONFIG` is an active setup failure only when it appears as a tool response `code` or `reason`. Seeing the string inside `search_codebase` results can simply mean the query matched Satori code that implements the setup error.
-
-## Development
-
-```bash
 pnpm --filter @zokizuan/satori-mcp build
 pnpm --filter @zokizuan/satori-mcp typecheck
 pnpm --filter @zokizuan/satori-mcp test
 pnpm --filter @zokizuan/satori-mcp docs:check
-pnpm --filter @zokizuan/satori-cli build
-pnpm --filter @zokizuan/satori-cli test
 ```
 
-`build` automatically runs docs generation from tool schemas.
+`build` regenerates the tool reference from live tool schemas.

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;
 }