@zokizuan/satori-mcp 4.0.0 → 4.4.0

package/README.md

@@ -8,7 +8,7 @@ MCP server for Satori — agent-safe semantic code search and indexing.
 - 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 TS/Python support
+- 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
@@ -63,13 +63,14 @@ Tool surface is hard-broken to 6 tools. This keeps routing explicit while exposi
 
 ### `manage_index`
 
-Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery.
+Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path. Ignore-rule edits in repo-root .satoriignore/.gitignore reconcile automatically in the normal sync path. Use action="sync" for immediate convergence and action="reindex" for full rebuild recovery (preflight may block unnecessary ignore-only reindex churn unless allowUnnecessaryReindex=true).
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `action` | enum("create", "reindex", "sync", "status", "clear") | yes |  | Required operation to run. |
 | `path` | string | yes |  | ABSOLUTE path to the target codebase. |
 | `force` | boolean | no |  | Only for action='create'. Force rebuild from scratch. |
+| `allowUnnecessaryReindex` | boolean | no |  | Only for action='reindex'. Override preflight block when reindex is detected as unnecessary ignore-only churn. |
 | `customExtensions` | array<string> | no |  | Only for action='create'. Additional file extensions to include. |
 | `ignorePatterns` | array<string> | no |  | Only for action='create'. Additional ignore patterns to apply. |
 | `zillizDropCollection` | string | no |  | Only for action='create'. Zilliz-only: drop this Satori-managed collection before creating the new index. |
@@ -91,7 +92,7 @@ Unified semantic search with runtime-first defaults (start with scope="runtime")
 
 ### `call_graph`
 
-Traverse the prebuilt TS/JS/Python call graph sidecar for callers/callees/bidirectional symbol relationships.
+Traverse the prebuilt call graph sidecar for callers/callees/bidirectional symbol relationships (language support follows the core callGraphQuery capability set; currently TS/JS/Python).
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
@@ -188,7 +189,7 @@ env = { EMBEDDING_PROVIDER = "VoyageAI", EMBEDDING_MODEL = "voyage-4-large", EMB
   "mcpServers": {
     "satori": {
       "command": "node",
-      "args": ["/absolute/path/to/claude-context/packages/mcp/dist/index.js"],
+      "args": ["/absolute/path/to/satori/packages/mcp/dist/index.js"],
       "timeout": 180000,
       "env": {
         "EMBEDDING_PROVIDER": "VoyageAI",
@@ -212,6 +213,57 @@ Never commit real API keys/tokens into repo config files.
 pnpm --filter @zokizuan/satori-mcp start
 ```
 
+## Shell CLI (`satori-cli`)
+
+`@zokizuan/satori-mcp` also ships a shell-first client binary that works without an MCP adapter.
+
+### 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).
+
 ## Development
 
 ```bash

package/assets/skills/satori-indexing/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: satori-indexing
+description: Index lifecycle and remediation for Satori. Use when codebases are not indexed, stale, blocked, or need freshness recovery.
+---
+
+# Satori Indexing
+
+Use this skill when the task is to create, reindex, sync, inspect readiness, or recover from stale index state.
+
+## Tools
+
+Use only:
+1. `list_codebases`
+2. `manage_index`
+
+## Workflow
+
+1. Use `list_codebases` for a global view of tracked roots.
+2. Use `manage_index(action="status", path=...)` for the specific codebase.
+3. Use `manage_index(action="create", path=...)` when the codebase is not indexed.
+4. Use `manage_index(action="reindex", path=...)` only for compatibility gates or explicit rebuilds.
+5. Use `manage_index(action="sync", path=...)` for freshness convergence and ignore-rule updates.
+
+## Rules
+
+- If any tool returns `requires_reindex`, stop and reindex. Do not substitute `sync`.
+- Never call `manage_index(action="clear")` unless the user explicitly requests destructive reset.
+- Treat ignore-only churn as a `sync` problem first.
+- Respect blocked and indexing states instead of forcing retries blindly.
+
+## Status Handling
+
+- `requires_reindex`: run `manage_index(action="reindex")`.
+- `not_ready` with indexing reason: check status and wait for terminal completion.
+- `not_indexed`: create the index.
+- Ignore-rule noise mitigation: update `.satoriignore`, wait debounce, and run `sync` for immediate convergence.

package/assets/skills/satori-navigation/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: satori-navigation
+description: Deterministic symbol navigation with Satori. Use after search results are found to lock exact spans and inspect call relationships.
+---
+
+# Satori Navigation
+
+Use this skill after `search_codebase` has returned candidate results and you need exact symbol/file navigation.
+
+## Tools
+
+Use only:
+1. `file_outline`
+2. `call_graph`
+3. `read_file`
+
+## Workflow
+
+1. Use grouped `search_codebase` results as the starting point.
+2. If `callGraphHint.supported=true`, call `call_graph(path=..., symbolRef=..., direction="both", depth=1)`.
+3. If `callGraphHint.supported=false`, execute `navigationFallback.readSpan.args` exactly.
+4. Use `file_outline(resolveMode="exact", symbolIdExact|symbolLabelExact)` to lock the symbol span.
+5. Use `read_file(path=..., open_symbol=...)` or deterministic line spans for the final read.
+
+## Rules
+
+- Treat `navigationFallback` as authoritative. Do not invent spans.
+- `open_symbol` must resolve deterministically. Do not guess on ambiguity.
+- `read_file(mode="annotated")` is preferred when outline metadata is useful.
+- Follow continuation hints when plain reads are truncated.
+
+## Remediation
+
+- `requires_reindex`: reindex before retrying navigation.
+- `not_ready`: wait for indexing to finish.
+- `unsupported`: fall back to deterministic `read_file` spans when supplied by `navigationFallback`.

package/assets/skills/satori-search/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: satori-search
+description: Semantic-first code search with Satori. Use for intent-based code discovery before file reads or grep.
+---
+
+# Satori Search
+
+Use this skill when the task is to find where behavior lives, identify candidate symbols, or narrow the search space before deeper navigation.
+
+## Tools
+
+Use only:
+1. `list_codebases`
+2. `manage_index`
+3. `search_codebase`
+
+## Workflow
+
+1. Check readiness with `manage_index(action="status", path=...)`.
+2. If not indexed, use `manage_index(action="create", path=...)`.
+3. If `requires_reindex` appears, stop and use `manage_index(action="reindex", path=...)`, then retry.
+4. Search with `search_codebase(path=..., query=..., scope="runtime", resultMode="grouped", groupBy="symbol", rankingMode="auto_changed_first")`.
+
+## Search Rules
+
+- Start with natural-language intent, not filenames.
+- Default to `scope="runtime"`.
+- Use operators only when needed: `lang:`, `path:`, `-path:`, `must:`, `exclude:`.
+- Treat warnings as usable-but-degraded results, not fatal errors.
+- Use `debug=true` only when ranking or filter explanations are required.
+
+## Remediation
+
+- `requires_reindex`: run `manage_index(action="reindex")`, not `sync`.
+- `not_ready` with indexing reason: wait or check `manage_index(action="status")`.
+- Noise mitigation hint: update `.satoriignore`, wait debounce, rerun search, and use `manage_index(action="sync")` only for immediate convergence.

package/dist/cli/args.d.ts

@@ -0,0 +1,54 @@
+export interface GlobalOptions {
+    startupTimeoutMs: number;
+    callTimeoutMs: number;
+    format: "json" | "text";
+    debug: boolean;
+}
+export type RawArgsMode = {
+    kind: "none";
+} | {
+    kind: "json";
+    value: string;
+} | {
+    kind: "file";
+    path: string;
+} | {
+    kind: "stdin-json";
+};
+export type ParsedCommand = {
+    kind: "help";
+} | {
+    kind: "version";
+} | {
+    kind: "install";
+    client: InstallClient;
+    dryRun: boolean;
+} | {
+    kind: "uninstall";
+    client: InstallClient;
+    dryRun: boolean;
+} | {
+    kind: "tools-list";
+} | {
+    kind: "tool-call";
+    toolName: string;
+    rawArgsMode: RawArgsMode;
+} | {
+    kind: "wrapper";
+    toolName: string;
+    rawArgsMode: RawArgsMode;
+    wrapperArgs: string[];
+};
+export interface ParsedCliInput {
+    globals: GlobalOptions;
+    command: ParsedCommand;
+}
+export interface ResolveRawArgsOptions {
+    stdin?: NodeJS.ReadStream;
+    stdinTimeoutMs: number;
+}
+export type InstallClient = "all" | "claude" | "codex";
+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>;
+//# sourceMappingURL=args.d.ts.map