@aiwayds/dsh-mcp-adapter 0.4.2 → 0.5.1

package/README.md

@@ -4,7 +4,7 @@ English | [简体中文](README.zh.md)
 
 Token-efficient MCP adapter for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) — a **prompt-side shim** inspired by [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter).
 
-**Requires dsh >= 0.1.5-rc.2** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.**
+**Requires dsh >= 0.1.7-rc.1** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.**
 
 ## The problem
 
@@ -29,6 +29,8 @@ Image results keep their native behavior: `mcp_call` delegates `output.render` t
 
 **Code Mode:** under `mode: 'code'` the wire already collapses to `run_code`; this plugin is a no-op there.
 
+**Host resource tools (dsh ≥ 0.1.6):** the host ships `@deepseek-ai/dsh-mcp-resources`, which registers three shared tools — `list_mcp_resources`, `list_mcp_resource_templates`, `read_mcp_resource` — without the `mcp__` prefix. By design they never enter the fold path and surface to the model natively; the fold/keep semantics are unchanged, and `keep` only ever promotes names that match the prefix, so nothing here is affected.
+
 **Load position:** loaded through host composition (the `cordis.patch.yml` `insert` below) the adapter is global — every agent's assemblies are folded. Loaded through an agent-scoped context instead, it applies only to that agent.
 
 ## Setup
@@ -62,9 +64,11 @@ dsh plugin --profile <name> remove @aiwayds/dsh-mcp-adapter
 
 The host reconciles the profile automatically: the `dsh.profile.bundles` entry is spliced out and the package's patch layer drops.
 
-One thing deliberately **stays**: the `mcp-adapter:` section in `~/.dsh/settings.yaml` — the stable server ids (`1..99`) and the disabled gates. It is never pruned by design: if you reinstall the plugin, every server keeps the same id it had before.
+One thing deliberately **stays**: the plugin's gate file at `~/.dsh/storages/mcp-adapter/gate.json` (`$DSH_HOME` honors an override) — the stable server ids (`1..99`) and the disabled gates. It is never pruned by design: if you reinstall the plugin, every server keeps the same id it had before.
+
+To purge that state too, delete the `storages/mcp-adapter/` directory yourself; ids will be re-allocated from scratch on reinstall.
 
-To purge that state too, delete the `mcp-adapter:` section from `settings.yaml` yourself; ids will be re-allocated from scratch on reinstall.
+Upgrading from a dsh 0.1.5 install: the old `mcp-adapter:` section of `settings.yaml` (which the 0.1.7 host renames to `settings.yaml.imported` after its one-shot import, since the section name does not match this plugin's entry id) is **absorbed once automatically**: on the next plugin boot, if no gate file exists yet, the stable ids and the disabled set are read from `settings.yaml.imported` (fallback: the still-present `settings.yaml`), sanitized and written straight into `gate.json` — no `/mcp disable <id>` re-latching needed. The pass is recorded in `<dsh home>/storages/mcp-adapter/legacy-import.json` (a present marker means it never re-runs; an existing gate.json is left untouched). Your `config:` values in the profile patch carry over unchanged.
 
 ## Config
 
@@ -74,6 +78,9 @@ To purge that state too, delete the `mcp-adapter:` section from `settings.yaml`
 | `keep` | `[]` | name patterns (`*` wildcard) kept native — pi-mcp-adapter's "direct mode", for high-frequency tools that deserve first-class schemas |
 | `servers` | `[]` | server-name whitelist: when non-empty, only these servers' tools are folded / cataloged / dispatchable (all three consult the same list) |
 | `descriptionLimit` | `200` | max chars per tool description in the `mcp_list` catalog |
+| `storageDir` | `""` | gate storage directory override; empty = `<dsh home>/storages/mcp-adapter` (read once at plugin start — moving it takes effect on restart) |
+
+Every field is declared **volatile** (the dsh 0.1.7 settings contract): all five appear on the plugin's settings page under the `dsh-mcp-adapter` entry, and editing them there applies **without restarting the plugin** — the fold boundary, catalog and dispatch pick the new values up on their very next use. The `config:` block in your profile patch keeps working exactly as before.
 
 ```yaml
 config:
@@ -107,9 +114,9 @@ The plugin registers one slash command on the platform `commands` service — co
 | `/mcp disable <id>` | Latch a whole server off: its tools force-fold out of every prompt — keep and `servers` exemptions included — it disappears from the `mcp_list` catalog, and `mcp_call` refuses it with an `/mcp enable <id>` hint |
 | `/mcp enable <id>` | Restore it under the same stable id |
 
-Any other form answers with usage. Every server observed by `/mcp` gets a stable numeric id (`1..99`, smallest free first), persisted in the dsh settings service under the `mcp-adapter:` section of your settings file (`~/.dsh/settings.yaml` on a stock install). Ids survive restarts and re-sync gaps and are never recycled — an id always names the same server; when all 99 are taken the `/mcp` views label it explicitly (`id space exhausted (99/99): N server(s) beyond the cap cannot be gated`, plus a marker on each affected group).
+Any other form answers with usage. Every server observed by `/mcp` gets a stable numeric id (`1..99`, smallest free first), persisted in the plugin's own gate file at `<dsh home>/storages/mcp-adapter/gate.json` (machine state — deliberately a file, not a settings-page field). Ids survive restarts and re-sync gaps and are never recycled — an id always names the same server; when all 99 are taken the `/mcp` views label it explicitly (`id space exhausted (99/99): N server(s) beyond the cap cannot be gated`, plus a marker on each affected group).
 
-Disable is **gate-style, not a disconnect**: the official client exposes no disconnect API, so tools stay registered and connections keep running — gating only removes them from the prompt, the catalog, and dispatch. All three latches judge through one shared verdict, so they can never disagree with each other or with what `/mcp` displays. Enable/disable persist through the settings service; without one everything still works and only the toggles answer with an explanatory error.
+Disable is **gate-style, not a disconnect**: the official client exposes no disconnect API, so tools stay registered and connections keep running — gating only removes them from the prompt, the catalog, and dispatch. All three latches judge through one shared verdict, so they can never disagree with each other or with what `/mcp` displays. Enable/disable persist through that file (atomic tmp+rename writes; a corrupt document warns once at startup and degrades to everything-enabled, and the next allocation write heals it). If the storage location cannot be written at all, everything still works and only the toggles answer with a persistence error.
 
 One real boundary: that latch is prompt-side (catalog/dispatch); native direct calls to a remembered `mcp__server__tool` name may still execute — for hard enforcement pair with pipeline guards or `tools.restrict()`.
 

package/README.zh.md

@@ -4,7 +4,7 @@
 
 面向 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 的省 token MCP 适配器——一个受 [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) 启发的 **prompt-side shim**（提示词侧垫片）。
 
-**要求 dsh >= 0.1.5-rc.2** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
+**要求 dsh >= 0.1.7-rc.1** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
 
 ## 问题
 
@@ -29,6 +29,8 @@
 
 **Code Mode：** 在 `mode: 'code'` 下线上本来就折叠为 `run_code`，本插件天然 no-op。
 
+**宿主资源工具（dsh ≥ 0.1.6）：** 宿主内置的 `@deepseek-ai/dsh-mcp-resources` 注册三个共享工具 —— `list_mcp_resources`、`list_mcp_resource_templates`、`read_mcp_resource`，均不带 `mcp__` 前缀。它们按设计不进折叠路径，原生呈现给模型；折叠与 keep 语义保持不变，`keep` 也只会命中匹配前缀的名字，本插件无需任何额外配置。
+
 **加载位置：** 经宿主组合加载（即下方 `cordis.patch.yml` 的 `insert` 行）时全局生效——所有 agent 的装配都会被折叠；若经某个 agent 的 scoped context 加载，则只对该 agent 生效。
 
 ## 安装
@@ -54,9 +56,11 @@ dsh plugin --profile <name> remove @aiwayds/dsh-mcp-adapter
 
 宿主会自动完成清理：`dsh.profile.bundles` 里对应的条目被拼接移除，插件的 patch 层随之失效。
 
-有一份状态被刻意**保留**：`~/.dsh/settings.yaml` 里的 `mcp-adapter:` 小节——stable server id（1..99）和 disabled 门闩。它按设计永不回收：重装本插件后，每个 server 仍沿用之前的 id。
+有一份状态被刻意**保留**：插件自己的门闩文件 `~/.dsh/storages/mcp-adapter/gate.json`（设置了 `DSH_HOME` 则以其为准）——stable server id（1..99）和 disabled 门闩。它按设计永不回收：重装本插件后，每个 server 仍沿用之前的 id。
+
+连这份状态也想清掉的话，请自行删除 `storages/mcp-adapter/` 目录；重装时 id 会重新分配。
 
-连这份状态也想清掉的话，请自行删除 `settings.yaml` 里的 `mcp-adapter:` 小节；重装时 id 会重新分配。
+从 dsh 0.1.5 升级：旧 `settings.yaml` 里的 `mcp-adapter:` 小节（0.1.7 宿主首次启动时把该文件一次性导入并改名为 `settings.yaml.imported`，旧段名与本插件 entry id 不同名）会被**一次性自动承接**：下次插件启动时若尚无门闩文件，则从 `settings.yaml.imported`（兜底仍在的 `settings.yaml`）读取 stable id 与 disabled 门闩，消毒后直接写入 `gate.json`——无需再逐条 `/mcp disable <id>` 重新闩上。承接过程记录在 `<dsh home>/storages/mcp-adapter/legacy-import.json`（该 marker 存在即永不重跑；已有 gate.json 则完全不介入）。profile patch 里该 entry 的 `config:` 配置原样继承，不受影响。
 
 ## 配置
 
@@ -66,6 +70,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-mcp-adapter
 | `keep` | `[]` | 保持原生进 prompt 的名字模式（`*` 通配）——对应 pi-mcp-adapter 的 direct 模式，适合高频、值得占一等座 schema 的工具 |
 | `servers` | `[]` | server 白名单：非空时只有这些 server 的工具会被折叠 / 进目录 / 可分发（三处共用同一份名单） |
 | `descriptionLimit` | `200` | `mcp_list` 目录里每条工具描述的最大字符数 |
+| `storageDir` | `""` | 门闩存储目录覆盖；空 = `<dsh home>/storages/mcp-adapter`（插件启动时读一次，改后需重启插件生效） |
 
 ```yaml
 config:
@@ -77,6 +82,8 @@ config:
     - github
 ```
 
+以上字段全部声明为 **volatile**（dsh 0.1.7 settings 契约）：五个键都会出现在插件设置页（entry `dsh-mcp-adapter`）中，在设置页修改**无需重启插件即可生效**——折叠边界、目录与分发在下一次使用时立即采用新值。profile patch 里的 `config:` 写法照旧可用。
+
 **信任边界：** 默认所有匹配 `prefix` 的工具都会被折叠——前缀只是命名约定而非安全边界，第三方插件恰好用 `mcp__*` 注册的工具同样会折叠。若只信任官方 client 的 server，请在 `servers` 里显式列出；其余保持原生（仍可直调，只是不走 meta-tool）。
 
 ## 备注
@@ -99,9 +106,9 @@ config:
 | `/mcp disable <id>` | 把一个 server 整体闩上：工具强制折叠出 prompt（keep 与 `servers` 豁免一并覆盖）、从 `mcp_list` 目录消失、`mcp_call` 拒绝并给 `/mcp enable <id>` 指引 |
 | `/mcp enable <id>` | 用同一个 stable id 复原 |
 
-其余形态一律回复用法说明。`/mcp` 观测到的每个 server 都会分到一个稳定数字 id（1..99，最小空闲优先），经 dsh settings 服务持久化到配置文件的 `mcp-adapter:` 小节（默认安装即 `~/.dsh/settings.yaml`）。id 跨重启、跨 re-sync 空窗保持不变，且永不回收——一个 id 永远指同一个 server；99 个用尽时由 `/mcp` 视图明确标注（`id space exhausted (99/99): N server(s) beyond the cap cannot be gated`，受影响的分组行会带标记）。
+其余形态一律回复用法说明。`/mcp` 观测到的每个 server 都会分到一个稳定数字 id（1..99，最小空闲优先），持久化到插件自己的门闩文件 `<dsh home>/storages/mcp-adapter/gate.json`（机器态——刻意用文件而非设置页字段）。id 跨重启、跨 re-sync 空窗保持不变，且永不回收——一个 id 永远指同一个 server；99 个用尽时由 `/mcp` 视图明确标注（`id space exhausted (99/99): N server(s) beyond the cap cannot be gated`，受影响的分组行会带标记）。
 
-disable 是**门闩式开关，不是真断连**：官方 client 不提供断连 API，工具仍留在注册表里、连接照常运行——门闩只把它请出 prompt、目录与分发。三层门闩共用同一个判定函数，彼此之间以及与 `/mcp` 的展示永远不会口径不一。enable/disable 经 settings 服务持久化；没有 settings 服务时其余功能照常，只有 toggle 会回一条说明性报错。
+disable 是**门闩式开关，不是真断连**：官方 client 不提供断连 API，工具仍留在注册表里、连接照常运行——门闩只把它请出 prompt、目录与分发。三层门闩共用同一个判定函数，彼此之间以及与 `/mcp` 的展示永远不会口径不一。enable/disable 经该文件持久化（tmp+rename 原子写；文档损坏时启动告警一次并退化为全启，下一次分配写会自动修复）。若存储位置完全不可写，其余功能照常，只有 toggle 会回一条持久化报错。
 
 一条真实边界：门闩生效在 prompt 侧（目录/分发层）；记得完整工具名的模型仍可能原生直调 `mcp__server__tool` 成功——需要硬性拦截时，请配合管线 guard 或 `tools.restrict()`。
 

package/cordis.patch.yml

@@ -26,6 +26,12 @@
 #                       client's registrations)
 #   descriptionLimit:   max chars per tool description in the mcp_list
 #                       catalog (default 200)
+#   storageDir:         gate storage directory override; empty (default) =
+#                       <dsh home>/storages/mcp-adapter
+#
+# All five keys are volatile (dsh 0.1.7 settings contract): they appear on
+# the plugin's settings page (entry `dsh-mcp-adapter`) and hot-reload there
+# without a plugin restart. This `config:` form keeps working too.
 
 - insert:
     - id: dsh-mcp-adapter

package/icon.svg

@@ -0,0 +1,5 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg">
+  <path d="M9 2.5V7M15 2.5V7"/>
+  <path d="M6.5 7h11v4.5a5.5 5.5 0 0 1-11 0z"/>
+  <path d="M12 17v4.5"/>
+</svg>

package/lib/index.d.ts

@@ -33,8 +33,9 @@
  * three latches at once — its tools force-fold out of every prompt (keep and
  * `servers` whitelist exemptions included), it disappears from the catalog,
  * and `mcp_call` refuses it with an enable hint. Each server gets a stable
- * numeric id (1..99, smallest free first) persisted in the dsh settings
- * service (`mcp-adapter` namespace), so ids survive restarts and re-syncs.
+ * numeric id (1..99, smallest free first) persisted in the plugin's own gate
+ * file under the dsh home (`storages/mcp-adapter/gate.json`), so ids survive
+ * restarts and re-syncs.
  *
  * Child-owned projections are preserved: `mcp_call` delegates its
  * `output.render` to the dispatched child and forwards the child's
@@ -84,14 +85,19 @@ export declare const MCP_CALL_TOOL_NAME = "mcp_call";
 /** Upper bound of the stable per-server id space. */
 export declare const MCP_SERVER_ID_LIMIT = 99;
 /**
- * dsh settings namespace persisting the stable ids and the disabled set.
- * Plain literal: dsh-settings 0.1.2-alpha.3 removed the runtime
- * settingsNamespace() helper this constant used to call (same adaptation as
- * dsh-model-sync / dsh-cron / dsh-vault).
+ * dsh 0.1.7 note: the runtime settings registry this state used to live in
+ * (`settings.register('mcp-adapter', …)` on the 0.1.5 `SettingsScope`) is
+ * gone — 0.1.7 settings are the projection of a plugin's `Config` schema and
+ * volatile fields are user-editable values, which a machine-maintained id
+ * registry must never be. The gate therefore persists through the plugin's
+ * OWN file under the dsh home (same seam as dsh-cron/dsh-vault):
+ * `<dsh home>/storages/mcp-adapter/gate.json`.
  */
-export declare const MCP_ADAPTER_SETTINGS_NAMESPACE = "mcp-adapter";
+export declare const MCP_ADAPTER_STORAGE_DIRNAME = "mcp-adapter";
+/** The gate document file name inside {@link MCP_ADAPTER_STORAGE_DIRNAME}. */
+export declare const GATE_FILE_NAME = "gate.json";
 /**
- * The persisted gate state (one settings section). `serverIds` maps every
+ * The persisted gate state (one gate.json document). `serverIds` maps every
  * OBSERVED server name to its stable id and is never pruned — enable/disable
  * never recycles an id, so an id always means the same server, even across
  * restarts and temporary re-sync gaps.
@@ -105,8 +111,8 @@ export interface ServerIdRegistry {
 /**
  * Read-side snapshot of the registry the three latches consult. Structurally
  * a superset of {@link ServerIdRegistry}; everything (config objects included)
- * shaped like this qualifies, so production hands frozen `scope.get()` values
- * straight in.
+ * shaped like this qualifies, so production hands the gate store's frozen
+ * mirror straight in.
  */
 export interface ServerGateState {
     readonly serverIds: Readonly<Record<string, number>>;
@@ -114,8 +120,6 @@ export interface ServerGateState {
 }
 /** Gate snapshot meaning "nothing observed, nothing disabled". */
 export declare const EMPTY_SERVER_GATE: ServerGateState;
-/** Schema of the persisted `mcp-adapter` settings section. */
-export declare const SERVER_ID_REGISTRY_SCHEMA: z<ServerIdRegistry>;
 /**
  * Coerce any resolved settings value into a trustworthy gate snapshot. The
  * schema already validates at resolve time, but every latch judges from THIS
@@ -163,21 +167,134 @@ export interface ServerToggleOutcome {
  * removes the id mapping — re-disabling later reuses the same number.
  */
 export declare function setServerDisabledState(state: ServerGateState | undefined, server: string, disable: boolean): ServerToggleOutcome;
-/** Resolved adapter configuration. */
+/**
+ * The live gate handle production hands to the three latches and the /mcp
+ * command: an in-memory mirror loaded once at apply time, written through to
+ * the gate file on every persist. Reads never throw and never touch the disk;
+ * writes may (and the command surface turns a failed write into a structured
+ * error while the mirror keeps its previous value — "state unchanged").
+ */
+export interface GateStore {
+    /** Current normalized snapshot (corrupt input already sanitized away). */
+    get(): ServerGateState;
+    /** Persist one complete next registry; the mirror moves only after the file landed. */
+    write(next: ServerIdRegistry): Promise<void>;
+}
+/** The warning seam {@link createFileGateStore} reports boot-time problems through. */
+export type GateWarn = (message: string) => void;
+/** Resolve the dsh home (`DSH_HOME`, else `~/.dsh`) — same seam as dsh-cron/dsh-vault. */
+export declare function resolveDshHome(): string;
+/**
+ * Absolute gate directory for one `storageDir` config value: empty (default)
+ * means `<dsh home>/storages/mcp-adapter`, anything else is the override used
+ * verbatim (resolved).
+ */
+export declare function resolveGateDir(configured: string): string;
+/**
+ * Build the production gate store over one directory. The initial read is
+ * synchronous (boot-time, once); writes land atomically (tmp file + rename)
+ * so a crash mid-write can never leave a torn document, and the in-memory
+ * mirror only advances after the file is durably renamed into place.
+ *
+ * Legacy absorption (one-time, 0.1.5 → 0.1.7): on a FRESH gate — no
+ * gate.json yet — the machine state from the removed settings registry is
+ * absorbed once from the host's legacy settings documents (see
+ * {@link absorbLegacyGate}). Opt-in through `options.home`: the legacy
+ * documents are a HOME-level concern (not this store's `dir`), and stores
+ * built without a home (bare test harnesses) stay exactly as isolated as
+ * before.
+ */
+export declare function createFileGateStore(dir: string, warn: GateWarn, options?: GateStoreOptions): GateStore;
+/**
+ * dsh 0.1.7 renamed the old `<home>/settings.yaml` to
+ * `settings.yaml.imported` after a one-shot import keyed by "section name =
+ * entry id". This plugin's old `mcp-adapter:` section (the machine-maintained
+ * id registry / disabled set) does not match the entry id `dsh-mcp-adapter`
+ * and was silently dropped by the host — the state lives on only in the
+ * renamed document. {@link absorbLegacyGate} recovers it once into the
+ * plugin's own gate.json.
+ */
+/** Legacy host settings documents, in read priority order. */
+export declare const LEGACY_SETTINGS_FILES: readonly ["settings.yaml.imported", "settings.yaml"];
+/** Legacy top-level section name in the old settings document. */
+export declare const LEGACY_GATE_SECTION = "mcp-adapter";
+/** Audit marker file name: `<home>/storages/mcp-adapter/<name>`. */
+export declare const LEGACY_IMPORT_MARKER = "legacy-import.json";
+/** Marker outcomes written for every settled absorption pass. */
+export type LegacyGateOutcome = 'imported' | 'no-op' | 'no-legacy' | 'no-section';
+/**
+ * Extract the top-level `mcp-adapter:` section of the old settings document.
+ * Handles both shapes the 0.1.5 writer produced:
+ * - single-line values (`serverIds: '{"fs": 1}'`, `disabled: '[1]'`);
+ * - block collections (`serverIds:` followed by deeper-indented
+ *   `name: <int>` lines; `disabled:` followed by `- <int>` lines).
+ * Everything else (comments, folded scalars, nested junk) is skipped.
+ * undefined = no section found. Pure function — tests run it against
+ * literal strings.
+ */
+export declare function legacyGateSection(text: string): {
+    serverIds?: unknown;
+    disabled?: unknown;
+} | undefined;
+/**
+ * Turn one decoded section into the raw candidate {@link normalizeServerGate}
+ * sanitizes: flow-JSON strings are JSON-parsed (malformed → undefined, the
+ * key degrades to "absent"), already-decoded block collections pass through.
+ */
+export declare function legacyGateCandidate(section: {
+    serverIds?: unknown;
+    disabled?: unknown;
+}): {
+    serverIds?: unknown;
+    disabled?: unknown;
+};
+/** Construction options for {@link createFileGateStore} beyond the two
+ *  historical arguments (all optional — bare harnesses change nothing). */
+export interface GateStoreOptions {
+    /** Summary-line seam for the absorption (default: silent). */
+    info?: GateWarn;
+    /**
+     * The dsh home holding the legacy settings documents and the audit marker
+     * (production: `resolveDshHome()` at the call site). Absorption runs ONLY
+     * when a home is provided — a store built without one never reads outside
+     * its own directory.
+     */
+    home?: string;
+}
+/**
+ * Live config reference. 0.1.7 settings contract: volatile `Config` fields
+ * reach `apply` as host-swapped references — `.get()` snapshots the current
+ * value, and a settings-page write swaps the value in place WITHOUT remounting
+ * the plugin, so every consumer must read through the reference per use.
+ */
+export interface VolatileRef<T> {
+    get(): T;
+}
+/**
+ * Resolved adapter configuration as `apply` receives it. Every knob is
+ * user-tunable from the settings page (entry `dsh-mcp-adapter`) and hot-reloads
+ * without a plugin restart.
+ */
 export interface AdapterConfig {
     /** Tool-name prefix to fold out of assembled prompts. */
-    prefix: string;
+    prefix: VolatileRef<string>;
     /** Name patterns ("*" wildcard) kept native in the prompt. */
-    keep: string[];
+    keep: VolatileRef<string[]>;
     /**
      * Server-name whitelist. Empty (default) folds every prefix-matching tool —
      * the prefix is then a naming convention, not a trust boundary. Non-empty
      * folds/catalogs/dispatches ONLY tools of the listed servers; fold, catalog
      * and dispatch all consult the same list.
      */
-    servers: string[];
+    servers: VolatileRef<string[]>;
     /** Max chars per tool description in the mcp_list catalog. */
-    descriptionLimit: number;
+    descriptionLimit: VolatileRef<number>;
+    /**
+     * Gate storage directory override; empty (default) =
+     * `<dsh home>/storages/mcp-adapter`. Read once at apply time (the store is
+     * built there); changing it takes effect on the next plugin restart.
+     */
+    storageDir: VolatileRef<string>;
 }
 export declare const Config: z<AdapterConfig>;
 /**
@@ -264,9 +381,9 @@ export interface McpListOptions {
     /** Server-name whitelist; empty or omitted admits every server. */
     servers?: readonly string[];
     /**
-     * Live gate reader (production: fresh `settingsScope.get()` snapshot per
-     * execution). A callback, not a value: the factory is built once at apply
-     * time and must observe later /mcp disable/enable writes.
+     * Live gate reader (production: the file-backed gate store's current
+     * mirror per execution). A callback, not a value: the factory is built
+     * once at apply time and must observe later /mcp disable/enable writes.
      */
     getGate?: () => ServerGateState | undefined;
 }
@@ -403,10 +520,10 @@ export interface McpCommandOptions {
     /** Max chars per tool description in rendered listings. */
     descriptionLimit: number;
     /**
-     * Live-resolved gate snapshot at invocation time (undefined = the settings
-     * service is not composed, so ids/toggles are absent from all views and
-     * everything renders enabled). A snapshot per invocation keeps these
-     * renderers pure and never stale within one command execution.
+     * Live-resolved gate snapshot at invocation time (undefined = no gate store
+     * is available, so ids/toggles are absent from all views and everything
+     * renders enabled). A snapshot per invocation keeps these renderers pure
+     * and never stale within one command execution.
      */
     gate?: ServerGateState;
     /**
@@ -485,7 +602,7 @@ export interface McpHealthStats {
  *
  * @param schemas - schemas visible to the receiving agent.
  * @param options - adapter knobs (prefix/keep/servers) plus the live gate
- *   snapshot (`gate`) when the settings service is composed.
+ *   snapshot (`gate`) when a gate store is available.
  * @param metaToolsLive - whether both meta-tools resolve to this plugin's
  *   definitions in the receiving agent's scope.
  * @returns the folding health plus the partition behind it.
@@ -615,16 +732,15 @@ export interface McpCommandView {
     /** Whether both meta-tools resolve to this plugin's definitions there. */
     metaToolsLive: boolean;
     /**
-     * Gate snapshot resolved when the invocation started; `undefined` means the
-     * dsh settings service is not composed in this process (stable ids and
-     * toggles are unavailable; views degrade to enabled-everything).
+     * Gate snapshot resolved when the invocation started; `undefined` means no
+     * gate store is available in this process (stable ids and toggles are
+     * unavailable; views degrade to enabled-everything).
      */
     gate?: ServerGateState;
     /**
-     * Persist one complete next registry (production: a wholesale `replace` of
-     * the `mcp-adapter` settings section, mirroring agent-default-model's
-     * save-selection precedent). Absent ⇒ /mcp disable/enable answers with an
-     * explanatory error instead of silently dropping the intent.
+     * Persist one complete next registry (production: an atomic write of the
+     * plugin's gate.json document). Absent ⇒ /mcp disable/enable answers with
+     * an explanatory error instead of silently dropping the intent.
      */
     writeGate?: (next: ServerIdRegistry) => Promise<void>;
     /**
@@ -707,7 +823,11 @@ export declare function renderDispatched(metaArgs: unknown, value: unknown, reso
 export declare function delegateFinalizeContent(metaArgs: unknown, result: Readonly<ToolExecutionResult>, exec: Readonly<ToolExecution>, resolveChild: (name: string) => ToolDefinition | undefined): ContentBlock[] | undefined;
 /**
  * Build the `mcp_list` meta-tool definition.
- * @param options - catalog knobs (prefix, description limit).
+ * @param options - catalog knobs (prefix, description limit). MAY be a live
+ *   options object (plain getters): the factory reads `prefix`, `servers`,
+ *   `descriptionLimit` and `getGate` through the object on EVERY execution,
+ *   so volatile config can be wired by reference — only the description text
+ *   freezes at factory time.
  * @param listSchemas - visible-schemas source (production: `ctx.tools.schemas`,
  *   called with the calling agent so restrictions are respected).
  * @returns the complete tool definition.
@@ -715,17 +835,20 @@ export declare function delegateFinalizeContent(metaArgs: unknown, result: Reado
 export declare function createMcpListTool(options: McpListOptions, listSchemas: (scope?: ScopeKey) => readonly ToolSchema[]): ToolDefinition;
 /**
  * Build the `mcp_call` meta-tool definition.
- * @param prefix - the configured MCP prefix (dispatch boundary).
+ * @param prefix - the configured MCP prefix (dispatch boundary). A thunk is
+ *   accepted so volatile config is re-read on every dispatch; a plain string
+ *   freezes the boundary at factory time.
  * @param resolve - scope-aware definition resolver (production:
  *   `ctx.tools.get`, called with the calling agent).
- * @param servers - server-name whitelist (default: no filtering).
- * @param getGate - live disabled-server reader (production: fresh
- *   `settingsScope.get()` snapshot per dispatch; default/omitted: nothing is
- *   disabled). Deliberately a callback — the definition object outlives any
- *   one settings snapshot and must observe later /mcp enable/disable writes.
+ * @param servers - server-name whitelist (default: no filtering). A thunk is
+ *   accepted for live volatile config, same as `prefix`.
+ * @param getGate - live disabled-server reader (production: the file-backed
+ *   gate store's current mirror; default/omitted: nothing is disabled).
+ *   Deliberately a callback — the definition object outlives any one gate
+ *   snapshot and must observe later /mcp enable/disable writes.
  * @returns the complete tool definition.
  */
-export declare function createMcpCallTool(prefix: string, resolve: (name: string, scope?: ScopeKey) => ToolDefinition | undefined, servers?: readonly string[], getGate?: () => ServerGateState | undefined): ToolDefinition;
+export declare function createMcpCallTool(prefix: string | (() => string), resolve: (name: string, scope?: ScopeKey) => ToolDefinition | undefined, servers?: readonly string[] | (() => readonly string[]), getGate?: () => ServerGateState | undefined): ToolDefinition;
 /**
  * Register the two meta-tools and install the assembly folding listener.
  *
@@ -733,19 +856,25 @@ export declare function createMcpCallTool(prefix: string, resolve: (name: string
  * both registrations are rolled back, a warning is logged, and NO listener
  * is installed — the official full-schema passthrough stays intact.
  *
- * Server gating: when a dsh settings service is composed, the `mcp-adapter`
- * namespace is registered on it and every gate consumer reads FRESH resolved
- * values through small callbacks — the plugin keeps no in-memory copy that
- * could drift from settings. The read itself is defended too: if the
- * resolved-value lookup throws, consumers see an absent gate (everything
- * enabled) instead of the error, keeping the assemble waterfall alive.
+ * Server gating: the gate mirror loads synchronously once from the plugin's
+ * gate file (`resolveGateDir(config.storageDir.get())`), and every gate
+ * consumer reads the CURRENT mirror through {@link getGate} — the plugin
+ * keeps no stale copy that could drift from /mcp writes. A corrupt or
+ * unreadable document degrades to the empty gate (everything enabled) at
+ * load time, keeping the assemble waterfall alive.
+ *
+ * Config volatility: every knob (prefix/keep/servers/descriptionLimit) is a
+ * volatile reference — 0.1.7 settings-page writes swap values in place
+ * WITHOUT remounting the plugin, so nothing captured at apply time may go
+ * stale: the waterfall, both meta-tools and the /mcp command all re-read
+ * through {@link cfgNow} per use.
  *
- * Commands: `/mcp` mounts through a runtime `ctx.inject(['commands'], ...)`
- * (same seam as settings), so hosts without the commands service keep this
- * plugin fully functional — one warning, no command. A registration name
- * conflict degrades to the same warning independently.
+ * Commands: `/mcp` mounts through a runtime `ctx.inject(['commands'], ...)`,
+ * so hosts without the commands service keep this plugin fully functional —
+ * one warning, no command. A registration name conflict degrades to the same
+ * warning independently.
  *
  * @param ctx - plugin context carrying the tool registry.
- * @param config - resolved adapter configuration.
+ * @param config - resolved adapter configuration (volatile live references).
  */
 export declare function apply(ctx: Context, config: AdapterConfig): void;