minnimemory 1.0.0-beta.1

package/dist/mcpServer.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Wires the MCP tools onto a server instance. Kept separate from recall.ts so the pure logic
+ * (loadManifest, rankOnDemandFiles, recall, outlineOf) is testable without an SDK, a transport, or Zod
+ * in the loop at all.
+ *
+ * Two profiles, because a tool definition is charged to the client's prefix on every turn
+ * whether or not it is ever called. `basic` (default) is four verbs that match what a
+ * developer actually does with a memory setup - check it, optimize it, sync it, recall from it -
+ * instead of the nine build-layer tools (scan/doctor/plan/apply/update/reorganize plus
+ * recall/modules/outline) a client had to hold before this split, whether or not the session
+ * ever touched most of them. `full` keeps today's nine, unchanged in name, schema and
+ * behaviour, for maintainers and for an agent driving a folder reorganization directly.
+ *
+ * The basic surface also depends on the workspace phase, probed once per launch by
+ * detectPhase() in discover.ts (a stat on `.minnimemory/`, nothing read): a "setup" root (not
+ * compiled) registers check, plus optimize with --allow-write; a "compiled" root registers
+ * recall, plus sync with --allow-write. Each launch holds two tools at most, never four. The
+ * phase is fixed for the life of the process: a session that compiles mid-way relaunches to get
+ * the compiled surface. `full` ignores phase.
+ *
+ * Real per-turn cost of each `tools/list` response (Research/TokenTest/tool_cost.mjs, tokenizer approx-v2),
+ * measured 2026-09-15:
+ *
+ *   profile          phase     launch                        tools                       tokens
+ *   basic (default)  setup     (none)                         check                      368
+ *   basic            setup     --allow-write                  check, optimize            1,025
+ *   basic            compiled  (none)                         recall                     329
+ *   basic            compiled  --allow-write                  recall, sync               605
+ *   full             any       --profile full                 recall, modules, outline,  1,666
+ *                                                              scan, doctor, plan
+ *   full             any       --profile full --allow-write    + apply, update, reorganize 2,668
+ *
+ * (the earlier basic figures of 696 read-only and 1,589 --allow-write were for the pre-phase
+ * surface that held all four verbs per launch; superseded by this table)
+ *
+ * Gating is by registration, not by a runtime refusal inside the handler. An unregistered tool
+ * costs nothing and cannot be called; a registered tool that always answers "disabled" still
+ * costs its full definition every turn - that was about 1,080 tokens of permanently-refusing
+ * write tools on every read-only server before the original three/setup/write split this
+ * replaces.
+ *
+ * `check`, `optimize`, `sync` and basic's `recall` are one handler each over the same doctor(),
+ * planInit(), init(), scanMemoryDir() and reorganize.ts's applyPlan() the full profile's nine
+ * tools already call - no logic is duplicated here, only the surface is smaller:
+ *   check     merges doctor() + plan(), always returning the doctor half; the compile-plan
+ *             half is added when planInit() succeeds and left out, with one line saying why,
+ *             when it throws InitError (a memory directory, an index file, already compiled).
+ *   optimize  decides compilable-file vs memory-directory from discover()'s own shape, not from
+ *             an argument: a file goes through init() (apply, or update when already compiled);
+ *             a directory returns scanMemoryDir() facts plus an instruction block until called
+ *             again with ops, which then go through reorganize.ts's applyPlan().
+ *   sync      runs doctor() restricted to MM010 (drift) and, only when something drifted, calls
+ *             init() with update: true - the same re-apply update() already does.
+ *   recall    folds today's modules() (no query) and outline() (headingsOnly) into one tool
+ *             alongside its own section-retrieval behaviour, unchanged when a query is given.
+ *
+ * This is still the "full-control" MCP shape from DESIGN.md section 6 - read tools for the
+ * doctor/init-plan judgment, write tools gated behind an explicit flag - built as
+ * `optimize`/`sync` (basic) or `apply`/`update` (full) rather than a single "update_module",
+ * because the shipped mechanism recompiles a whole workspace from its stub and OnDemandMemory
+ * files on disk, not one OnDemandMemory file in isolation.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** What each mode adds, in registration order. Exported so tests, CLI help and docs quote one list. */
+export declare const SERVE_TOOLS: readonly ["recall", "modules", "outline"];
+export declare const SETUP_TOOLS: readonly ["scan", "doctor", "plan"];
+export declare const WRITE_TOOLS: readonly ["apply", "update", "reorganize"];
+/** The `basic` profile's tools, in registration order, as the union across both workspace
+ * phases; no single launch registers all of either list. A setup root gets check (and optimize
+ * with --allow-write), a compiled root gets recall (and sync with --allow-write). */
+export declare const BASIC_READ_TOOLS: readonly ["check", "recall"];
+export declare const BASIC_WRITE_TOOLS: readonly ["optimize", "sync"];
+export interface McpServerOptions {
+    /**
+     * "basic" (default) or "full". basic registers by workspace phase (detectPhase in discover.ts,
+     * probed once per launch): on a setup root `check`, plus `optimize` with --allow-write; on a
+     * compiled root `recall`, plus `sync` with --allow-write. full registers today's nine tools:
+     * recall/modules/outline and scan/doctor/plan always, plus apply/update/reorganize with
+     * --allow-write. A tool definition is charged every turn, so a per-turn retrieval client
+     * should not carry more than it needs.
+     */
+    profile?: "basic" | "full";
+    /**
+     * Adds the write tools: `optimize`/`sync` (basic) or `apply`/`update`/`reorganize` (full).
+     * Default false: a fresh `mcp` invocation is read-only, matching the locked "default stays
+     * read-only" decision - full-control write access is opt-in per launch, never the default a
+     * client silently inherits.
+     */
+    allowWrite?: boolean;
+    /**
+     * Let doctor/plan/scan (and check/optimize, their basic-profile equivalents) follow `@path`
+     * imports outside the root. A launch flag with no tool argument behind it on purpose: whether
+     * to read files elsewhere on this machine is the operator's call, and a connected client
+     * asking nicely is not consent.
+     */
+    followExternalImports?: boolean;
+    /**
+     * Let doctor/plan/apply/update/scan (and check/optimize) see the operator's OS-level Claude
+     * Code auto-memory folder, and allow "auto-memory" as a target where that tool resolves one
+     * (2026-09-13 audit round 2, D2). Separate from `followExternalImports`: reading the
+     * operator's own memory and following an `@path` an imported file names are different reaches,
+     * and each flag does one thing. A launch flag with no tool argument behind it, same reasoning
+     * as `followExternalImports`.
+     */
+    includeAutoMemory?: boolean;
+}
+/**
+ * Content returned by recall/outline is memory-file text, and a memory file can be written by
+ * whoever wrote the repo. It arrives in a model's context looking exactly like trusted memory,
+ * so it is fenced and labelled as data. Same posture this project already applies to live app
+ * state in its own PCTuner agent, which fences the block and says plainly that instructions
+ * inside it are not to be followed.
+ *
+ * Deliberately short: this is a token-optimisation tool, so the framing is one header and one
+ * footer per response, roughly thirty tokens, not a paragraph per unit.
+ */
+export declare const DATA_OPEN: string;
+export declare const DATA_CLOSE = "\n=== END RETRIEVED MEMORY ===";
+export declare function createMcpServer(root: string, options?: McpServerOptions): McpServer;
+/**
+ * Shown to a client that connects while the CLI's `mcp` command is stashed (see cli.ts). No
+ * tools are registered - per this file's own header comment, a tool that only ever refuses
+ * still costs its full definition every turn, so the honest zero-cost shape while disabled is no
+ * tools at all, with the reason carried in the spec's `instructions` field instead.
+ */
+export declare const DISABLED_MESSAGE = "Currently Disabled For Research and Testing. Learn more: https://minniai.com";
+/**
+ * A zero-tool MCP server that only completes the handshake and states DISABLED_MESSAGE.
+ *
+ * Declares the tools capability with an explicit empty list, rather than leaving it entirely
+ * undeclared (`McpServer` only declares it once `registerTool` is called, which never happens
+ * here). Confirmed live in the 2026-09-10 audit: an undeclared capability makes `tools/list`
+ * answer JSON-RPC -32601 "Method not found", which many hosts treat as a broken/failed server -
+ * exactly the opposite of "connects cleanly and says why there's nothing here".
+ */
+export declare function createDisabledMcpServer(): McpServer;