@zokizuan/satori-mcp 4.3.1 → 4.4.0

package/README.md

@@ -189,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",

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

@@ -19,6 +19,14 @@ export type ParsedCommand = {
     kind: "help";
 } | {
     kind: "version";
+} | {
+    kind: "install";
+    client: InstallClient;
+    dryRun: boolean;
+} | {
+    kind: "uninstall";
+    client: InstallClient;
+    dryRun: boolean;
 } | {
     kind: "tools-list";
 } | {
@@ -39,6 +47,7 @@ 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>;

package/dist/cli/args.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import { CliError } from "./errors.js";
-const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version"]);
+const RESERVED_SUBCOMMANDS = new Set(["tools", "tool", "help", "version", "install", "uninstall"]);
 const PRIMITIVE_TYPES = new Set(["string", "number", "integer", "boolean"]);
 function parsePositiveInteger(value, flagName) {
     const parsed = Number.parseInt(value, 10);
@@ -109,6 +109,28 @@ function parseRawArgsMode(args) {
     }
     return { rawArgsMode, remaining };
 }
+function parseInstallCommand(kind, args) {
+    let client = "all";
+    let dryRun = false;
+    for (let i = 0; i < args.length; i += 1) {
+        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);
+            }
+            client = next;
+            i += 1;
+            continue;
+        }
+        if (token === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        throw new CliError("E_USAGE", `Unknown arguments for ${kind}: ${args.slice(i).join(" ")}`, 2);
+    }
+    return { kind, client, dryRun };
+}
 export function parseCliArgs(argv) {
     const { globals, rest } = parseGlobalOptions(argv);
     if (rest.length === 0 || rest[0] === "help" || rest.includes("--help") || rest.includes("-h")) {
@@ -123,6 +145,18 @@ export function parseCliArgs(argv) {
             command: { kind: "version" }
         };
     }
+    if (rest[0] === "install") {
+        return {
+            globals,
+            command: parseInstallCommand("install", rest.slice(1))
+        };
+    }
+    if (rest[0] === "uninstall") {
+        return {
+            globals,
+            command: parseInstallCommand("uninstall", rest.slice(1))
+        };
+    }
     if (rest[0] === "tools") {
         if (rest.length === 2 && rest[1] === "list") {
             return {

package/dist/cli/index.d.ts

@@ -3,6 +3,7 @@ interface RunCliOptions {
     writeStdout?: (text: string) => void;
     writeStderr?: (text: string) => void;
     stdin?: NodeJS.ReadStream;
+    env?: NodeJS.ProcessEnv;
     serverCommand?: string;
     serverArgs?: string[];
     serverEnv?: Record<string, string>;

package/dist/cli/index.js

@@ -6,6 +6,7 @@ import { parseCliArgs, parseWrapperArgumentsFromSchema, resolveRawArguments } fr
 import { connectCliMcpSession } from "./client.js";
 import { asCliError, CliError } from "./errors.js";
 import { emitError, emitJson, inferManageStatusState, parseStructuredEnvelope } from "./format.js";
+import { executeInstallCommand } from "./install.js";
 import { resolveServerEntryPath } from "./resolve-server-entry.js";
 const MANAGE_INDEX_MIN_POLL_TIMEOUT_MS = 10 * 60 * 1000;
 function firstText(result) {
@@ -42,6 +43,8 @@ function buildHelpPayload() {
     return {
         usage: "satori-cli <command>",
         commands: [
+            "install [--client all|codex|claude] [--dry-run]",
+            "uninstall [--client all|codex|claude] [--dry-run]",
             "tools list",
             "tool call <toolName> --args-json '<json>'",
             "tool call <toolName> --args-file <path>",
@@ -164,6 +167,7 @@ export async function runCli(argv, options = {}) {
         writeStdout: options.writeStdout || ((text) => process.stdout.write(text)),
         writeStderr: options.writeStderr || ((text) => process.stderr.write(text)),
     };
+    const effectiveEnv = options.env || process.env;
     let parsedFormat = "json";
     let parsedCommandKind = null;
     try {
@@ -190,11 +194,21 @@ export async function runCli(argv, options = {}) {
             }
             return 0;
         }
+        if (parsed.command.kind === "install" || parsed.command.kind === "uninstall") {
+            const result = executeInstallCommand(parsed.command, {
+                homeDir: effectiveEnv.HOME,
+            });
+            emitJson(writers, result);
+            if (parsed.globals.format === "text") {
+                writers.writeStderr(`satori-cli ${parsed.command.kind} completed for ${parsed.command.client}.\n`);
+            }
+            return 0;
+        }
         const session = await connectCliMcpSession({
             command: options.serverCommand || process.execPath,
             args: options.serverArgs || resolveDefaultServerArgs(),
             env: {
-                ...process.env,
+                ...effectiveEnv,
                 ...options.serverEnv,
                 SATORI_RUN_MODE: "cli",
             },

package/dist/cli/install.d.ts

@@ -0,0 +1,30 @@
+import type { InstallClient } from "./args.js";
+type ClientName = Exclude<InstallClient, "all">;
+export interface InstallCommandInput {
+    kind: "install" | "uninstall";
+    client: InstallClient;
+    dryRun: boolean;
+}
+export interface InstallCommandOptions {
+    homeDir?: string;
+    packageSpecifier?: string;
+    skillAssetRoot?: string;
+}
+export interface ClientInstallResult {
+    client: ClientName;
+    configPath: string;
+    skillsPath: string;
+    configChanged: boolean;
+    skillsChanged: boolean;
+    status: "updated" | "unchanged";
+    dryRun: boolean;
+}
+export interface InstallCommandResult {
+    action: "install" | "uninstall";
+    client: InstallClient;
+    dryRun: boolean;
+    results: ClientInstallResult[];
+}
+export declare function executeInstallCommand(command: InstallCommandInput, options?: InstallCommandOptions): InstallCommandResult;
+export {};
+//# sourceMappingURL=install.d.ts.map

package/dist/cli/install.js

@@ -0,0 +1,327 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "./errors.js";
+const MANAGED_BLOCK_START = "# >>> satori-cli managed satori start >>>";
+const MANAGED_BLOCK_END = "# <<< satori-cli managed satori end <<<";
+const OWNED_SKILL_DIRS = ["satori-search", "satori-navigation", "satori-indexing"];
+const MANAGED_TIMEOUT_MS = 180000;
+function resolveDefaultSkillAssetRoot() {
+    const currentFile = fileURLToPath(import.meta.url);
+    return path.resolve(path.dirname(currentFile), "..", "..", "assets", "skills");
+}
+function resolveDefaultPackageSpecifier() {
+    try {
+        const currentFile = fileURLToPath(import.meta.url);
+        const packagePath = path.resolve(path.dirname(currentFile), "..", "..", "package.json");
+        const parsed = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+        if (typeof parsed.name === "string" && typeof parsed.version === "string") {
+            return `${parsed.name}@${parsed.version}`;
+        }
+    }
+    catch {
+        // Fall through to hard failure below.
+    }
+    throw new CliError("E_USAGE", "Unable to resolve the installed Satori package version for CLI install.", 2);
+}
+function resolveClientTargets(homeDir) {
+    return [
+        {
+            client: "codex",
+            configPath: path.join(homeDir, ".codex", "config.toml"),
+            skillsPath: path.join(homeDir, ".codex", "skills"),
+        },
+        {
+            client: "claude",
+            configPath: path.join(homeDir, ".claude", "settings.json"),
+            skillsPath: path.join(homeDir, ".claude", "skills"),
+        },
+    ];
+}
+function selectTargets(homeDir, client) {
+    const targets = resolveClientTargets(homeDir);
+    if (client === "all") {
+        return targets;
+    }
+    return targets.filter((target) => target.client === client);
+}
+function ensureParentDir(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+function ensureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+function readTextIfExists(filePath) {
+    if (!fs.existsSync(filePath)) {
+        return null;
+    }
+    return fs.readFileSync(filePath, "utf8");
+}
+function normalizeTrailingNewline(value) {
+    return value.endsWith("\n") ? value : `${value}\n`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildCodexManagedBlock(packageSpecifier) {
+    return [
+        MANAGED_BLOCK_START,
+        "[mcp_servers.satori]",
+        'command = "npx"',
+        `args = ["-y", "${packageSpecifier}"]`,
+        `startup_timeout_ms = ${MANAGED_TIMEOUT_MS}`,
+        MANAGED_BLOCK_END,
+        "",
+    ].join("\n");
+}
+function codexHasUnmanagedSatoriSection(content) {
+    if (!content.includes("[mcp_servers.satori]")) {
+        return false;
+    }
+    return !(content.includes(MANAGED_BLOCK_START) && content.includes(MANAGED_BLOCK_END));
+}
+function prepareCodexInstall(filePath, packageSpecifier) {
+    const current = readTextIfExists(filePath) ?? "";
+    if (codexHasUnmanagedSatoriSection(current)) {
+        throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove [mcp_servers.satori] manually or convert it to the managed block first.`, 2);
+    }
+    const managedBlock = buildCodexManagedBlock(packageSpecifier);
+    let next = current;
+    if (current.includes(MANAGED_BLOCK_START) && current.includes(MANAGED_BLOCK_END)) {
+        next = current.replace(new RegExp(`${escapeRegExp(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(MANAGED_BLOCK_END)}\\n?`, "m"), managedBlock);
+    }
+    else if (current.trim().length === 0) {
+        next = managedBlock;
+    }
+    else {
+        next = `${normalizeTrailingNewline(current)}\n${managedBlock}`;
+    }
+    return {
+        changed: next !== current,
+        apply: () => {
+            if (next === current) {
+                return;
+            }
+            ensureParentDir(filePath);
+            fs.writeFileSync(filePath, next, "utf8");
+        },
+    };
+}
+function prepareCodexUninstall(filePath) {
+    const current = readTextIfExists(filePath);
+    if (!current) {
+        return { changed: false, apply: () => { } };
+    }
+    if (codexHasUnmanagedSatoriSection(current)) {
+        throw new CliError("E_USAGE", `Refusing to remove unmanaged Satori config in ${filePath}. Remove [mcp_servers.satori] manually instead.`, 2);
+    }
+    if (!current.includes(MANAGED_BLOCK_START) || !current.includes(MANAGED_BLOCK_END)) {
+        return { changed: false, apply: () => { } };
+    }
+    const next = current
+        .replace(new RegExp(`\\n?${escapeRegExp(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(MANAGED_BLOCK_END)}\\n?`, "m"), "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .replace(/^\n+/, "");
+    return {
+        changed: next !== current,
+        apply: () => {
+            if (next === current) {
+                return;
+            }
+            fs.writeFileSync(filePath, next, "utf8");
+        },
+    };
+}
+function parseJsonObject(filePath) {
+    const current = readTextIfExists(filePath);
+    if (!current) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(current);
+    }
+    catch (error) {
+        throw new CliError("E_USAGE", `Failed to parse JSON config at ${filePath}: ${error.message}`, 2);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliError("E_USAGE", `Expected top-level JSON object in ${filePath}.`, 2);
+    }
+    return parsed;
+}
+function buildClaudeServerConfig(packageSpecifier) {
+    return {
+        command: "npx",
+        args: ["-y", packageSpecifier],
+        timeout: MANAGED_TIMEOUT_MS,
+    };
+}
+function isManagedClaudeEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const entry = value;
+    if (entry.command !== "npx") {
+        return false;
+    }
+    if (entry.timeout !== MANAGED_TIMEOUT_MS) {
+        return false;
+    }
+    if (!Array.isArray(entry.args) || entry.args.length !== 2) {
+        return false;
+    }
+    return entry.args[0] === "-y"
+        && typeof entry.args[1] === "string"
+        && /^@zokizuan\/satori-mcp@.+$/.test(entry.args[1]);
+}
+function prepareClaudeInstall(filePath, packageSpecifier) {
+    const currentObject = parseJsonObject(filePath);
+    const currentSerialized = JSON.stringify(currentObject);
+    const desiredServer = buildClaudeServerConfig(packageSpecifier);
+    const mcpServersValue = currentObject.mcpServers;
+    let mcpServers;
+    if (mcpServersValue === undefined) {
+        mcpServers = {};
+    }
+    else if (mcpServersValue && typeof mcpServersValue === "object" && !Array.isArray(mcpServersValue)) {
+        mcpServers = { ...mcpServersValue };
+    }
+    else {
+        throw new CliError("E_USAGE", `Expected mcpServers to be an object in ${filePath}.`, 2);
+    }
+    const existingSatori = mcpServers.satori;
+    if (existingSatori !== undefined && !isManagedClaudeEntry(existingSatori)) {
+        throw new CliError("E_USAGE", `Refusing to overwrite unmanaged Satori config in ${filePath}. Remove mcpServers.satori manually or align it to the managed npx form first.`, 2);
+    }
+    mcpServers.satori = {
+        ...existingSatori,
+        ...desiredServer,
+    };
+    currentObject.mcpServers = mcpServers;
+    const next = `${JSON.stringify(currentObject, null, 2)}\n`;
+    return {
+        changed: JSON.stringify(currentObject) !== currentSerialized,
+        apply: () => {
+            if (JSON.stringify(currentObject) === currentSerialized) {
+                return;
+            }
+            ensureParentDir(filePath);
+            fs.writeFileSync(filePath, next, "utf8");
+        },
+    };
+}
+function prepareClaudeUninstall(filePath) {
+    const currentObject = parseJsonObject(filePath);
+    const mcpServersValue = currentObject.mcpServers;
+    if (!mcpServersValue || typeof mcpServersValue !== "object" || Array.isArray(mcpServersValue)) {
+        return { changed: false, apply: () => { } };
+    }
+    const mcpServers = { ...mcpServersValue };
+    if (!Object.prototype.hasOwnProperty.call(mcpServers, "satori")) {
+        return { changed: false, apply: () => { } };
+    }
+    if (!isManagedClaudeEntry(mcpServers.satori)) {
+        throw new CliError("E_USAGE", `Refusing to remove unmanaged Satori config in ${filePath}. Remove mcpServers.satori manually instead.`, 2);
+    }
+    delete mcpServers.satori;
+    if (Object.keys(mcpServers).length === 0) {
+        delete currentObject.mcpServers;
+    }
+    else {
+        currentObject.mcpServers = mcpServers;
+    }
+    const next = `${JSON.stringify(currentObject, null, 2)}\n`;
+    return {
+        changed: true,
+        apply: () => {
+            fs.writeFileSync(filePath, next, "utf8");
+        },
+    };
+}
+function prepareSkillInstall(skillsPath, skillAssetRoot) {
+    const writes = [];
+    let changed = false;
+    for (const skillDirName of OWNED_SKILL_DIRS) {
+        const sourceFile = path.join(skillAssetRoot, skillDirName, "SKILL.md");
+        if (!fs.existsSync(sourceFile)) {
+            throw new CliError("E_USAGE", `Missing packaged skill asset: ${sourceFile}`, 2);
+        }
+        const content = fs.readFileSync(sourceFile, "utf8");
+        const destinationDir = path.join(skillsPath, skillDirName);
+        const destinationFile = path.join(destinationDir, "SKILL.md");
+        if (readTextIfExists(destinationFile) !== content) {
+            changed = true;
+            writes.push({ destinationDir, destinationFile, content });
+        }
+    }
+    return {
+        changed,
+        apply: () => {
+            for (const write of writes) {
+                ensureDir(write.destinationDir);
+                fs.writeFileSync(write.destinationFile, write.content, "utf8");
+            }
+        },
+    };
+}
+function prepareSkillRemoval(skillsPath) {
+    const removals = OWNED_SKILL_DIRS
+        .map((skillDirName) => path.join(skillsPath, skillDirName))
+        .filter((destinationDir) => fs.existsSync(destinationDir));
+    return {
+        changed: removals.length > 0,
+        apply: () => {
+            for (const destinationDir of removals) {
+                fs.rmSync(destinationDir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+function prepareMutation(target, command, packageSpecifier, skillAssetRoot) {
+    const configMutation = command.kind === "install"
+        ? target.client === "codex"
+            ? prepareCodexInstall(target.configPath, packageSpecifier)
+            : prepareClaudeInstall(target.configPath, packageSpecifier)
+        : target.client === "codex"
+            ? prepareCodexUninstall(target.configPath)
+            : prepareClaudeUninstall(target.configPath);
+    const skillsMutation = command.kind === "install"
+        ? prepareSkillInstall(target.skillsPath, skillAssetRoot)
+        : prepareSkillRemoval(target.skillsPath);
+    return {
+        target,
+        configChanged: configMutation.changed,
+        skillsChanged: skillsMutation.changed,
+        apply: () => {
+            configMutation.apply();
+            skillsMutation.apply();
+        },
+    };
+}
+export function executeInstallCommand(command, options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const packageSpecifier = options.packageSpecifier ?? resolveDefaultPackageSpecifier();
+    const skillAssetRoot = options.skillAssetRoot ?? resolveDefaultSkillAssetRoot();
+    const prepared = selectTargets(homeDir, command.client).map((target) => (prepareMutation(target, command, packageSpecifier, skillAssetRoot)));
+    if (!command.dryRun) {
+        for (const mutation of prepared) {
+            mutation.apply();
+        }
+    }
+    return {
+        action: command.kind,
+        client: command.client,
+        dryRun: command.dryRun,
+        results: prepared.map((mutation) => ({
+            client: mutation.target.client,
+            configPath: mutation.target.configPath,
+            skillsPath: mutation.target.skillsPath,
+            configChanged: mutation.configChanged,
+            skillsChanged: mutation.skillsChanged,
+            status: mutation.configChanged || mutation.skillsChanged ? "updated" : "unchanged",
+            dryRun: command.dryRun,
+        })),
+    };
+}
+//# sourceMappingURL=install.js.map

package/dist/core/handlers.d.ts

@@ -24,6 +24,8 @@ export declare class ToolHandlers {
     private buildReindexHint;
     private buildCreateHint;
     private buildStatusHint;
+    private touchWatchedCodebase;
+    private unwatchCodebase;
     private buildManageResponseEnvelope;
     private manageResponseFromEnvelope;
     private manageResponse;

package/dist/core/handlers.js

@@ -153,6 +153,26 @@ export class ToolHandlers {
             }
         };
     }
+    async touchWatchedCodebase(codebasePath) {
+        const syncManager = this.syncManager;
+        if (typeof syncManager.touchWatchedCodebase === 'function') {
+            await syncManager.touchWatchedCodebase(codebasePath);
+            return;
+        }
+        if (typeof syncManager.registerCodebaseWatcher === 'function') {
+            await syncManager.registerCodebaseWatcher(codebasePath);
+        }
+    }
+    async unwatchCodebase(codebasePath) {
+        const syncManager = this.syncManager;
+        if (typeof syncManager.unwatchCodebase === 'function') {
+            await syncManager.unwatchCodebase(codebasePath);
+            return;
+        }
+        if (typeof syncManager.unregisterCodebaseWatcher === 'function') {
+            await syncManager.unregisterCodebaseWatcher(codebasePath);
+        }
+    }
     buildManageResponseEnvelope(action, codebasePath, status, humanText, options = {}) {
         const envelope = {
             tool: "manage_index",
@@ -1961,7 +1981,7 @@ Agent instructions:
             this.snapshotManager.removeCodebaseCompletely(droppedCodebasePath);
             this.snapshotManager.saveCodebaseSnapshot();
             try {
-                await this.syncManager.unregisterCodebaseWatcher(droppedCodebasePath);
+                await this.unwatchCodebase(droppedCodebasePath);
             }
             catch {
                 // Best-effort watcher cleanup; dropping cloud collection remains successful.
@@ -2148,7 +2168,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 this.snapshotManager.removeCodebaseCompletely(absolutePath);
                 this.snapshotManager.saveCodebaseSnapshot();
                 try {
-                    await this.syncManager.unregisterCodebaseWatcher(absolutePath);
+                    await this.unwatchCodebase(absolutePath);
                 }
                 catch {
                     // Best-effort watcher cleanup before force rebuild.
@@ -2221,6 +2241,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             this.snapshotManager.saveCodebaseSnapshot();
             // Track the codebase path for syncing
             trackCodebasePath(absolutePath);
+            await this.touchWatchedCodebase(absolutePath);
             // Start background indexing - now safe to proceed
             this.startBackgroundIndexing(absolutePath, forceReindex);
             const pathInfo = codebasePath !== absolutePath
@@ -2308,7 +2329,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             // Save snapshot after updating codebase lists
             this.snapshotManager.saveCodebaseSnapshot();
             await this.rebuildCallGraphForIndex(absolutePath);
-            await this.syncManager.registerCodebaseWatcher(absolutePath);
+            await this.touchWatchedCodebase(absolutePath);
             let message = `Background indexing completed for '${absolutePath}'.\nIndexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks.`;
             if (stats.status === 'limit_reached') {
                 message += `\n⚠️  Warning: Indexing stopped because the chunk limit (450,000) was reached. The index may be incomplete.`;
@@ -2931,6 +2952,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     ...(Object.keys(responseHints).length > 0 ? { hints: responseHints } : {}),
                     results: rawResults
                 };
+                await this.touchWatchedCodebase(effectiveRoot);
                 return {
                     content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
                     meta: { searchDiagnostics }
@@ -3073,6 +3095,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                 ...(Object.keys(responseHints).length > 0 ? { hints: responseHints } : {}),
                 results: visibleGroupedResults
             };
+            await this.touchWatchedCodebase(effectiveRoot);
             return {
                 content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
                 meta: { searchDiagnostics }
@@ -3204,6 +3227,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
                 };
             }
+            await this.touchWatchedCodebase(effectiveRoot);
             if (!fs.existsSync(absoluteFile)) {
                 const payload = {
                     status: 'not_found',
@@ -3524,6 +3548,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                         }]
                 };
             }
+            await this.touchWatchedCodebase(effectiveRoot);
             const graph = this.callGraphManager.queryGraph(effectiveRoot, symbolRef, {
                 direction,
                 depth,
@@ -3610,7 +3635,7 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
             this.indexingStats = null;
             // Save snapshot after clearing index
             this.snapshotManager.saveCodebaseSnapshot();
-            await this.syncManager.unregisterCodebaseWatcher(absolutePath);
+            await this.unwatchCodebase(absolutePath);
             let resultText = `Successfully cleared codebase '${absolutePath}'`;
             const remainingIndexed = this.snapshotManager.getIndexedCodebases().length;
             const remainingIndexing = this.snapshotManager.getIndexingCodebases().length;
@@ -3889,10 +3914,12 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                         : '';
                     return this.manageResponse("sync", absolutePath, "error", `Error syncing codebase: coalesced in-flight reconcile failed (${decision.errorMessage}).${fallbackLine}`);
                 }
+                await this.touchWatchedCodebase(absolutePath);
                 return this.manageResponse("sync", absolutePath, "ok", `🔄 Sync request coalesced for '${absolutePath}'. Reused in-flight sync result.`);
             }
             if (decision.mode === 'reconciled_ignore_change') {
                 if (totalChanges === 0 && ignoredDeletes === 0) {
+                    await this.touchWatchedCodebase(absolutePath);
                     return this.manageResponse("sync", absolutePath, "ok", `✅ Ignore-rule reconciliation completed for '${absolutePath}'. No additional index changes were required.`);
                 }
                 const resultMessage = `🔄 Incremental sync + ignore-rule reconciliation completed for '${absolutePath}'.\n\n` +
@@ -3900,13 +3927,16 @@ To force rebuild from scratch: call manage_index with {"action":"create","path":
                     `🧹 Ignored paths removed from index: ${ignoredDeletes}\n` +
                     `\nTotal changes: ${totalChanges + ignoredDeletes}`;
                 console.log(`[SYNC] ✅ Sync+ignore reconcile completed: +${added}, -${removed}, ~${modified}, ignoredDeleted=${ignoredDeletes}`);
+                await this.touchWatchedCodebase(absolutePath);
                 return this.manageResponse("sync", absolutePath, "ok", resultMessage);
             }
             if (totalChanges === 0) {
+                await this.touchWatchedCodebase(absolutePath);
                 return this.manageResponse("sync", absolutePath, "ok", `✅ No changes detected for codebase '${absolutePath}'. Index is up to date.`);
             }
             const resultMessage = `🔄 Incremental sync completed for '${absolutePath}'.\n\n📊 Changes:\n+ ${added} file(s) added\n- ${removed} file(s) removed\n~ ${modified} file(s) modified\n\nTotal changes: ${totalChanges}`;
             console.log(`[SYNC] ✅ Sync completed: +${added}, -${removed}, ~${modified}`);
+            await this.touchWatchedCodebase(absolutePath);
             return this.manageResponse("sync", absolutePath, "ok", resultMessage);
         }
         catch (error) {

package/dist/core/sync.d.ts

@@ -53,6 +53,7 @@ export declare class SyncManager {
     private watcherModeStarted;
     private watchEnabled;
     private watchDebounceMs;
+    private watchedCodebases;
     private watchers;
     private debounceTimers;
     private watcherIgnoreMatchers;
@@ -87,8 +88,11 @@ export declare class SyncManager {
     private shouldIgnoreWatchPath;
     scheduleWatcherSync(codebasePath: string, reason?: WatchSyncReason): void;
     private handleWatcherError;
+    touchWatchedCodebase(codebasePath: string): Promise<void>;
+    unwatchCodebase(codebasePath: string): Promise<void>;
     registerCodebaseWatcher(codebasePath: string): Promise<void>;
     unregisterCodebaseWatcher(codebasePath: string): Promise<void>;
+    refreshWatchersFromWatchList(): Promise<void>;
     refreshWatchersFromSnapshot(): Promise<void>;
     startWatcherMode(): Promise<void>;
     stopWatcherMode(): Promise<void>;

package/dist/core/sync.js

@@ -11,6 +11,7 @@ export class SyncManager {
         this.lastSyncTimes = new Map();
         this.backgroundSyncTimer = null;
         this.watcherModeStarted = false;
+        this.watchedCodebases = new Set();
         this.watchers = new Map();
         this.debounceTimers = new Map();
         this.watcherIgnoreMatchers = new Map();
@@ -237,7 +238,7 @@ export class SyncManager {
             try {
                 this.snapshotManager.removeIndexedCodebase(codebasePath);
                 this.snapshotManager.saveCodebaseSnapshot();
-                await this.unregisterCodebaseWatcher(codebasePath);
+                await this.unwatchCodebase(codebasePath);
             }
             catch (e) {
                 console.error(`[SYNC] Failed to clean snapshot for '${codebasePath}':`, e);
@@ -488,6 +489,17 @@ export class SyncManager {
         }
         console.error(`[SYNC-WATCH] Watcher error for '${codebasePath}':`, error);
     }
+    async touchWatchedCodebase(codebasePath) {
+        this.watchedCodebases.add(codebasePath);
+        if (!this.watchEnabled || !this.watcherModeStarted) {
+            return;
+        }
+        await this.refreshWatchersFromWatchList();
+    }
+    async unwatchCodebase(codebasePath) {
+        this.watchedCodebases.delete(codebasePath);
+        await this.unregisterCodebaseWatcher(codebasePath);
+    }
     async registerCodebaseWatcher(codebasePath) {
         if (!this.watchEnabled || !this.watcherModeStarted) {
             return;
@@ -559,26 +571,29 @@ export class SyncManager {
             console.error(`[SYNC-WATCH] Failed to close watcher for '${codebasePath}':`, error);
         }
     }
-    async refreshWatchersFromSnapshot() {
+    async refreshWatchersFromWatchList() {
         if (!this.watchEnabled || !this.watcherModeStarted) {
             return;
         }
-        const indexedCodebases = new Set(this.snapshotManager.getIndexedCodebases());
+        const watchableCodebases = new Set(Array.from(this.watchedCodebases).filter((codebasePath) => this.canScheduleWatchSync(codebasePath)));
         for (const watchedPath of Array.from(this.watchers.keys())) {
-            if (!indexedCodebases.has(watchedPath)) {
+            if (!watchableCodebases.has(watchedPath)) {
                 await this.unregisterCodebaseWatcher(watchedPath);
             }
         }
-        for (const codebasePath of indexedCodebases) {
+        for (const codebasePath of watchableCodebases) {
             await this.registerCodebaseWatcher(codebasePath);
         }
     }
+    async refreshWatchersFromSnapshot() {
+        await this.refreshWatchersFromWatchList();
+    }
     async startWatcherMode() {
         if (!this.watchEnabled || this.watcherModeStarted) {
             return;
         }
         this.watcherModeStarted = true;
-        await this.refreshWatchersFromSnapshot();
+        await this.refreshWatchersFromWatchList();
         console.log(`[SYNC-WATCH] Watcher mode enabled.`);
     }
     async stopWatcherMode() {

package/dist/tools/read_file.js

@@ -102,6 +102,20 @@ function resolveCodebaseRootForFile(absolutePath, ctx) {
     }
     return candidates[0].path;
 }
+async function touchResolvedCodebaseRoot(absolutePath, ctx) {
+    const codebaseRoot = resolveCodebaseRootForFile(absolutePath, ctx);
+    if (!codebaseRoot) {
+        return;
+    }
+    const syncManager = ctx.syncManager;
+    if (typeof syncManager.touchWatchedCodebase === "function") {
+        await syncManager.touchWatchedCodebase(codebaseRoot);
+        return;
+    }
+    if (typeof syncManager.registerCodebaseWatcher === "function") {
+        await syncManager.registerCodebaseWatcher(codebaseRoot);
+    }
+}
 function resolveIndexingBlockForFile(absolutePath, ctx) {
     const allCodebases = typeof ctx.snapshotManager?.getAllCodebases === "function"
         ? ctx.snapshotManager.getAllCodebases()
@@ -200,6 +214,7 @@ export const readFileTool = {
                         }]
                 };
             }
+            await touchResolvedCodebaseRoot(absolutePath, ctx);
             const content = fs.readFileSync(absolutePath, "utf-8");
             const lines = splitIntoLines(content);
             const totalLines = lines.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zokizuan/satori-mcp",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "MCP server for Satori with agent-safe semantic search and indexing",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "ignore": "^7.0.5",
     "zod": "^3.25.55",
     "zod-to-json-schema": "^3.25.1",
-    "@zokizuan/satori-core": "1.0.0"
+    "@zokizuan/satori-core": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -25,6 +25,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "assets/skills/**/*.md",
     "README.md"
   ],
   "repository": {
@@ -42,7 +43,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "pnpm clean && tsc --build --force && pnpm fix:bin-perms && pnpm docs:generate",
+    "build": "pnpm clean && tsc --build --force && pnpm fix:bin-perms && pnpm docs:generate && pnpm manifest:generate",
     "dev": "tsx --watch src/index.ts",
     "clean": "rimraf dist",
     "lint": "eslint src --ext .ts",
@@ -52,7 +53,9 @@
     "start:with-env": "OPENAI_API_KEY=${OPENAI_API_KEY:your-api-key-here} MILVUS_ADDRESS=${MILVUS_ADDRESS:localhost:19530} tsx src/index.ts",
     "docs:generate": "tsx scripts/generate-docs.ts",
     "docs:check": "tsx scripts/generate-docs.ts --check",
+    "manifest:generate": "tsx scripts/generate-server-manifest.ts",
+    "manifest:check": "tsx scripts/generate-server-manifest.ts --check",
     "fix:bin-perms": "node -e \"const fs=require('fs');try{fs.chmodSync('dist/index.js',0o755);fs.chmodSync('dist/cli/index.js',0o755);}catch(e){console.error(e);process.exit(1);}\"",
-    "test": "tsx --test --test-concurrency=1 src/**/*.test.ts"
+    "test": "pnpm --filter @zokizuan/satori-core build && tsx --test --test-concurrency=1 src/**/*.test.ts"
   }
 }