@zokizuan/satori-mcp 3.8.0 → 4.3.1

package/README.md

@@ -6,7 +6,9 @@ MCP server for Satori — agent-safe semantic code search and indexing.
 
 - Capability-driven execution via `CapabilityResolver`
 - Runtime-first `search_codebase` with explicit `scope`, `resultMode`, `groupBy`, and optional `debug` traces
-- First-class `call_graph` tool with deterministic node/edge sorting and TS/Python support
+- 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
@@ -61,35 +63,36 @@ 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 (no full reindex required). If you need immediate convergence after ignore edits, run action="sync" and then rerun search_codebase. Use action="reindex" for fingerprint/schema incompatibility or 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. |
-| `splitter` | enum("ast", "langchain") | no |  | Only for action='create'. Code splitter strategy. |
+| `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. |
 
 ### `search_codebase`
 
-Unified semantic search with runtime/docs scope control, grouped/raw output modes, deterministic ranking, and structured freshness decisions. For runtime debugging, start with scope="runtime". If you need both runtime and docs context, use scope="mixed". If top results are dominated by tests/fixtures/docs, edit repo-root .satoriignore using your host/editor (examples, not exhaustive: **/*.test.*, **/*.spec.*, **/__tests__/**, **/__fixtures__/**, **/fixtures/**, coverage/**), wait one debounce window (MCP_WATCH_DEBOUNCE_MS, default 5000ms), then rerun search_codebase. For immediate convergence, run manage_index with {"action":"sync","path":"<same path used in search_codebase>"}.
+Unified semantic search with runtime-first defaults (start with scope="runtime"), grouped/raw output modes, and deterministic ranking/freshness behavior. Operators are parsed from a query prefix block: lang:, path:, -path:, must:, exclude: (escape with \\ to keep literals). Use debug:true for explainability payloads, and rely on response hints for remediation (.satoriignore noise handling, navigation fallback, reindex guidance).
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `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. |
+| `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. |
 | `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. |
 | `limit` | integer | no | `50` | Maximum groups (grouped mode) or chunks (raw mode). |
 | `debug` | boolean | no | `false` | Optional debug payload toggle for score and fusion breakdowns. |
 
 ### `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 |
 |---|---|---|---|---|
@@ -210,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/dist/cli/args.d.ts

@@ -0,0 +1,45 @@
+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: "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 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

package/dist/cli/args.js

@@ -0,0 +1,440 @@
+import fs from "node:fs";
+import { CliError } from "./errors.js";
+const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version"]);
+const PRIMITIVE_TYPES = new Set(["string", "number", "integer", "boolean"]);
+function parsePositiveInteger(value, flagName) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new CliError("E_USAGE", `${flagName} must be a positive integer.`, 2);
+    }
+    return parsed;
+}
+function normalizeFlagToken(token) {
+    return token.replace(/^--/, "").replace(/-/g, "_");
+}
+function stripFlagPrefix(token) {
+    if (!token.startsWith("--")) {
+        throw new CliError("E_USAGE", `Expected a flag but found '${token}'.`, 2);
+    }
+    return token.slice(2);
+}
+function parseGlobalOptions(argv) {
+    const globals = {
+        startupTimeoutMs: 180000,
+        callTimeoutMs: 600000,
+        format: "json",
+        debug: false,
+    };
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        switch (token) {
+            case "--startup-timeout-ms": {
+                const next = argv[i + 1];
+                if (!next) {
+                    throw new CliError("E_USAGE", "Missing value for --startup-timeout-ms.", 2);
+                }
+                globals.startupTimeoutMs = parsePositiveInteger(next, "--startup-timeout-ms");
+                i += 2;
+                break;
+            }
+            case "--call-timeout-ms": {
+                const next = argv[i + 1];
+                if (!next) {
+                    throw new CliError("E_USAGE", "Missing value for --call-timeout-ms.", 2);
+                }
+                globals.callTimeoutMs = parsePositiveInteger(next, "--call-timeout-ms");
+                i += 2;
+                break;
+            }
+            case "--format": {
+                const next = argv[i + 1];
+                if (!next || (next !== "json" && next !== "text")) {
+                    throw new CliError("E_USAGE", "--format must be one of: json, text.", 2);
+                }
+                globals.format = next;
+                i += 2;
+                break;
+            }
+            case "--debug": {
+                globals.debug = true;
+                i += 1;
+                break;
+            }
+            default: {
+                return {
+                    globals,
+                    rest: argv.slice(i),
+                };
+            }
+        }
+    }
+    return { globals, rest: [] };
+}
+function parseRawArgsMode(args) {
+    let rawArgsMode = { kind: "none" };
+    const remaining = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--args-json") {
+            if (rawArgsMode.kind !== "none") {
+                throw new CliError("E_USAGE", "Use only one of --args-json or --args-file.", 2);
+            }
+            const next = args[i + 1];
+            if (!next) {
+                throw new CliError("E_USAGE", "Missing value for --args-json.", 2);
+            }
+            rawArgsMode = next === "@-"
+                ? { kind: "stdin-json" }
+                : { kind: "json", value: next };
+            i += 1;
+            continue;
+        }
+        if (token === "--args-file") {
+            if (rawArgsMode.kind !== "none") {
+                throw new CliError("E_USAGE", "Use only one of --args-json or --args-file.", 2);
+            }
+            const next = args[i + 1];
+            if (!next) {
+                throw new CliError("E_USAGE", "Missing value for --args-file.", 2);
+            }
+            rawArgsMode = { kind: "file", path: next };
+            i += 1;
+            continue;
+        }
+        remaining.push(token);
+    }
+    if (rawArgsMode.kind !== "none" && remaining.length > 0) {
+        throw new CliError("E_USAGE", "Tool argument flags cannot be combined with --args-json/--args-file.", 2);
+    }
+    return { rawArgsMode, remaining };
+}
+export function parseCliArgs(argv) {
+    const { globals, rest } = parseGlobalOptions(argv);
+    if (rest.length === 0 || rest[0] === "help" || rest.includes("--help") || rest.includes("-h")) {
+        return {
+            globals,
+            command: { kind: "help" }
+        };
+    }
+    if (rest[0] === "version" || rest.includes("--version") || rest.includes("-v")) {
+        return {
+            globals,
+            command: { kind: "version" }
+        };
+    }
+    if (rest[0] === "tools") {
+        if (rest.length === 2 && rest[1] === "list") {
+            return {
+                globals,
+                command: { kind: "tools-list" }
+            };
+        }
+        throw new CliError("E_USAGE", "Unsupported tools subcommand. Use: tools list", 2);
+    }
+    if (rest[0] === "tool") {
+        if (rest[1] !== "call") {
+            throw new CliError("E_USAGE", "Unsupported tool subcommand. Use: tool call <toolName>", 2);
+        }
+        const toolName = rest[2];
+        if (!toolName) {
+            throw new CliError("E_USAGE", "Missing tool name. Use: tool call <toolName>", 2);
+        }
+        const { rawArgsMode, remaining } = parseRawArgsMode(rest.slice(3));
+        if (remaining.length > 0) {
+            throw new CliError("E_USAGE", `Unknown arguments for tool call: ${remaining.join(" ")}`, 2);
+        }
+        return {
+            globals,
+            command: {
+                kind: "tool-call",
+                toolName,
+                rawArgsMode
+            }
+        };
+    }
+    if (RESERVED_SUBCOMMANDS.has(rest[0])) {
+        throw new CliError("E_USAGE", `Unsupported command '${rest[0]}'.`, 2);
+    }
+    const toolName = rest[0];
+    const { rawArgsMode, remaining } = parseRawArgsMode(rest.slice(1));
+    return {
+        globals,
+        command: {
+            kind: "wrapper",
+            toolName,
+            rawArgsMode,
+            wrapperArgs: remaining
+        }
+    };
+}
+function readStdin(stdin, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let settled = false;
+        const timeout = setTimeout(() => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            reject(new CliError("E_USAGE", "Timed out while reading stdin JSON for --args-json @-.", 2));
+        }, timeoutMs);
+        timeout.unref();
+        stdin.setEncoding("utf8");
+        stdin.on("data", (chunk) => {
+            chunks.push(String(chunk));
+        });
+        stdin.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            reject(new CliError("E_USAGE", `Failed to read stdin: ${error.message}`, 2));
+        });
+        stdin.on("end", () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve(chunks.join(""));
+        });
+        stdin.resume();
+    });
+}
+function parseJsonObject(value, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CliError("E_USAGE", `Invalid JSON from ${source}: ${message}`, 2);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("E_USAGE", `JSON from ${source} must be an object.`, 2);
+    }
+    return parsed;
+}
+export async function resolveRawArguments(rawArgsMode, options) {
+    switch (rawArgsMode.kind) {
+        case "none":
+            return {};
+        case "json":
+            return parseJsonObject(rawArgsMode.value, "--args-json");
+        case "file": {
+            if (!fs.existsSync(rawArgsMode.path)) {
+                throw new CliError("E_USAGE", `Arguments file not found: ${rawArgsMode.path}`, 2);
+            }
+            const content = fs.readFileSync(rawArgsMode.path, "utf8");
+            return parseJsonObject(content, "--args-file");
+        }
+        case "stdin-json": {
+            const text = await readStdin(options.stdin || process.stdin, options.stdinTimeoutMs);
+            if (text.trim().length === 0) {
+                throw new CliError("E_USAGE", "stdin was empty for --args-json @-.", 2);
+            }
+            return parseJsonObject(text, "--args-json @-");
+        }
+        default:
+            return {};
+    }
+}
+function isPrimitiveEnum(enumValues) {
+    return enumValues.every((value) => {
+        const valueType = typeof value;
+        return valueType === "string" || valueType === "number" || valueType === "boolean";
+    });
+}
+function unsupportedSchemaReason(schema) {
+    if (!schema || typeof schema !== "object") {
+        return "schema is not an object";
+    }
+    if ("oneOf" in schema) {
+        return "oneOf is not supported in wrapper mode";
+    }
+    if ("anyOf" in schema) {
+        return "anyOf is not supported in wrapper mode";
+    }
+    if ("allOf" in schema) {
+        return "allOf is not supported in wrapper mode";
+    }
+    if ("$ref" in schema) {
+        return "$ref is not supported in wrapper mode";
+    }
+    if ("patternProperties" in schema) {
+        return "patternProperties is not supported in wrapper mode";
+    }
+    if (Array.isArray(schema.enum) && !isPrimitiveEnum(schema.enum)) {
+        return "enum values must be primitive";
+    }
+    if (schema.type === "array") {
+        const itemSchema = schema.items;
+        if (!itemSchema || typeof itemSchema !== "object") {
+            return "array items schema is missing";
+        }
+        const itemReason = unsupportedSchemaReason(itemSchema);
+        if (itemReason) {
+            return `array item schema unsupported: ${itemReason}`;
+        }
+        if (typeof itemSchema.type === "string" && !PRIMITIVE_TYPES.has(itemSchema.type) && !Array.isArray(itemSchema.enum)) {
+            return "array item type must be primitive";
+        }
+    }
+    if (typeof schema.type === "string" && schema.type !== "object" && !PRIMITIVE_TYPES.has(schema.type) && !Array.isArray(schema.enum)) {
+        return `schema type '${schema.type}' is not supported`;
+    }
+    return null;
+}
+function parseBooleanValue(value) {
+    if (value === "true") {
+        return true;
+    }
+    if (value === "false") {
+        return false;
+    }
+    throw new CliError("E_USAGE", `Invalid boolean value '${value}'. Use true or false.`, 2);
+}
+function parseEnumValue(raw, enumValues) {
+    for (const entry of enumValues) {
+        if (typeof entry === "string" && entry === raw) {
+            return entry;
+        }
+        if (typeof entry === "number" && Number(raw) === entry) {
+            return entry;
+        }
+        if (typeof entry === "boolean") {
+            if (raw === "true" && entry === true) {
+                return true;
+            }
+            if (raw === "false" && entry === false) {
+                return false;
+            }
+        }
+    }
+    throw new CliError("E_USAGE", `Value '${raw}' is not in enum [${enumValues.map(String).join(", ")}].`, 2);
+}
+function parsePrimitive(schema, raw) {
+    if (Array.isArray(schema.enum)) {
+        return parseEnumValue(raw, schema.enum);
+    }
+    switch (schema.type) {
+        case "string":
+            return raw;
+        case "number": {
+            const parsed = Number(raw);
+            if (!Number.isFinite(parsed)) {
+                throw new CliError("E_USAGE", `Value '${raw}' must be a finite number.`, 2);
+            }
+            return parsed;
+        }
+        case "integer": {
+            const parsed = Number(raw);
+            if (!Number.isInteger(parsed)) {
+                throw new CliError("E_USAGE", `Value '${raw}' must be an integer.`, 2);
+            }
+            return parsed;
+        }
+        case "boolean":
+            return parseBooleanValue(raw);
+        default:
+            throw new CliError("E_SCHEMA_UNSUPPORTED", `Primitive parsing unsupported for schema type '${String(schema.type)}'. Use --args-json/--args-file.`, 2);
+    }
+}
+export function parseWrapperArgumentsFromSchema(toolName, inputSchema, wrapperArgs) {
+    if (!inputSchema || typeof inputSchema !== "object") {
+        throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName} schema is missing or invalid. Use --args-json/--args-file.`, 2);
+    }
+    const schema = inputSchema;
+    const rootReason = unsupportedSchemaReason(schema);
+    if (rootReason) {
+        throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName} schema unsupported (${rootReason}). Use --args-json/--args-file.`, 2);
+    }
+    const properties = schema.properties;
+    if (!properties || typeof properties !== "object") {
+        throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName} schema has no object properties. Use --args-json/--args-file.`, 2);
+    }
+    const requiredProps = Array.isArray(schema.required)
+        ? schema.required.filter((entry) => typeof entry === "string")
+        : [];
+    const normalizedToCanonical = new Map();
+    const propertySchemas = new Map();
+    for (const [propertyName, propertySchema] of Object.entries(properties)) {
+        const unsupportedReason = unsupportedSchemaReason(propertySchema);
+        if (unsupportedReason) {
+            throw new CliError("E_SCHEMA_UNSUPPORTED", `${toolName}.${propertyName} uses unsupported schema (${unsupportedReason}). Use --args-json/--args-file.`, 2);
+        }
+        const normalized = normalizeFlagToken(`--${propertyName}`);
+        normalizedToCanonical.set(normalized, propertyName);
+        propertySchemas.set(propertyName, propertySchema);
+    }
+    const parsed = {};
+    for (let i = 0; i < wrapperArgs.length; i += 1) {
+        const token = wrapperArgs[i];
+        if (!token.startsWith("--")) {
+            throw new CliError("E_USAGE", `Unexpected positional argument '${token}'.`, 2);
+        }
+        const normalizedFlag = normalizeFlagToken(token);
+        const isJsonFlag = normalizedFlag.endsWith("_json");
+        const baseNormalized = isJsonFlag ? normalizedFlag.slice(0, -5) : normalizedFlag;
+        const canonicalName = normalizedToCanonical.get(baseNormalized);
+        if (!canonicalName) {
+            throw new CliError("E_USAGE", `Unknown flag '${token}' for tool '${toolName}'.`, 2);
+        }
+        const propertySchema = propertySchemas.get(canonicalName);
+        if (isJsonFlag) {
+            const next = wrapperArgs[i + 1];
+            if (!next) {
+                throw new CliError("E_USAGE", `Missing JSON value for ${token}.`, 2);
+            }
+            parsed[canonicalName] = parseJsonObject(next, token);
+            i += 1;
+            continue;
+        }
+        if (propertySchema?.type === "object") {
+            throw new CliError("E_USAGE", `Flag '${token}' requires JSON input. Use --${stripFlagPrefix(token)}-json '<json>'.`, 2);
+        }
+        if (propertySchema?.type === "array") {
+            const next = wrapperArgs[i + 1];
+            if (!next || next.startsWith("--")) {
+                throw new CliError("E_USAGE", `Missing value for ${token}.`, 2);
+            }
+            const itemSchema = propertySchema.items;
+            const parsedValue = parsePrimitive(itemSchema, next);
+            const existing = parsed[canonicalName];
+            if (!Array.isArray(existing)) {
+                parsed[canonicalName] = [parsedValue];
+            }
+            else {
+                existing.push(parsedValue);
+            }
+            i += 1;
+            continue;
+        }
+        if (propertySchema?.type === "boolean") {
+            const next = wrapperArgs[i + 1];
+            if (!next || next.startsWith("--")) {
+                parsed[canonicalName] = true;
+            }
+            else {
+                parsed[canonicalName] = parseBooleanValue(next);
+                i += 1;
+            }
+            continue;
+        }
+        const next = wrapperArgs[i + 1];
+        if (!next || next.startsWith("--")) {
+            throw new CliError("E_USAGE", `Missing value for ${token}.`, 2);
+        }
+        parsed[canonicalName] = parsePrimitive(propertySchema, next);
+        i += 1;
+    }
+    for (const requiredProp of requiredProps) {
+        if (!(requiredProp in parsed)) {
+            throw new CliError("E_USAGE", `Missing required flag for '${toolName}': --${requiredProp}.`, 2);
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/client.d.ts

@@ -0,0 +1,26 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+interface SessionOptions {
+    command: string;
+    args: string[];
+    env: Record<string, string | undefined>;
+    cwd?: string;
+    startupTimeoutMs: number;
+    callTimeoutMs: number;
+    writeStderr: (text: string) => void;
+}
+export declare class CliMcpSession {
+    private readonly client;
+    private readonly transport;
+    private readonly callTimeoutMs;
+    private readonly writeStderr;
+    constructor(client: Client, transport: StdioClientTransport, callTimeoutMs: number, writeStderr: (text: string) => void);
+    listTools(): Promise<any>;
+    callTool(name: string, args: Record<string, unknown>): Promise<any>;
+    close(): Promise<void>;
+    logProtocolFailure(error: unknown): never;
+    wireStderr(): void;
+}
+export declare function connectCliMcpSession(options: SessionOptions): Promise<CliMcpSession>;
+export {};
+//# sourceMappingURL=client.d.ts.map