@aiwayds/dsh-mcp-adapter 0.1.1 → 0.2.1

package/README.md

@@ -81,6 +81,26 @@ config:
 - Coexists with [ben7am1n/dsh-mcp-proxy](https://github.com/ben7am1n/dsh-mcp-proxy) (connection-side proxy with its own servers — different, non-colliding tool names). That project credits pi-mcp-adapter as prior art too; this repo is an independent prompt-side take that reuses the official client instead of re-implementing connections.
 - Trade-offs (same as pi-mcp-adapter): one extra discovery round-trip before the first call, and expanded schemas still occupy context once the model pulls them in.
 
+## Commands
+
+The plugin registers one slash command on the platform `commands` service — consumed softly, so a host without that service still gets folding and both meta-tools (one log warning instead of `/mcp`). `/mcp` reports status, and since v0.2.0 it is also the control surface for taking a whole MCP server in or out of the adapter:
+
+| Form | Output |
+|---|---|
+| `/mcp` or `/mcp list` | Tree overview — every server line carries its stable `[<id>]`; disabled ones show `⏸ disabled` and hide their tools; closed by a folding-health footer |
+| `/mcp list <name>` | `<name>` matching a server → that server's full tool list (a disabled server adds a `⏸` note); matching a full tool name → full description + complete input schema |
+| `/mcp config` | The effective `prefix` / `keep` / `servers` / `descriptionLimit`, each with its hitting tools, plus the persistent enable/disable inventory |
+| `/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).
+
+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.
+
+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()`.
+
+Status remains **two-state**: a server appears when its tools are visible in your scope — absence does not prove it is disabled (it may be reconnecting); the official client exposes no connection state. The footer reads `meta-tools: mcp_list/mcp_call live · folding ACTIVE — folded N, kept M · ~X chars of schema out of prompt` while the meta-tools are live and at least one tool folds, degrading to a fail-open (or nothing-to-fold) notice otherwise. X counts raw JSON-schema characters, deliberately not tokens. Output beyond 400 lines is truncated with a hint to narrow via `/mcp list <server>`.
+
 ## Acknowledgments
 
 With full credit to **[pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter)** by [@nicobailon](https://github.com/nicobailon): the core idea behind this plugin — collapsing an unbounded MCP tool surface into constant meta-tools whose schemas expand on demand, so the standing prompt cost stays O(1) no matter how many servers you run — is entirely theirs, and it reframed what MCP integration should cost. This repository is our port of that idea to DeepSeek Harness; the prompt-side-shim mechanism differs (by design), but the inspiration and the concept belong to the original. If you are on pi, go use theirs.

package/README.zh.md

@@ -73,6 +73,26 @@ config:
 - 与 [ben7am1n/dsh-mcp-proxy](https://github.com/ben7am1n/dsh-mcp-proxy) 可共存（它是 connection-side 代理、自带连接管理，工具名互不冲突）。该项目同样致谢 pi-mcp-adapter；本仓库是独立的 prompt-side 实现：复用官方 client 而不是重造连接层。
 - 权衡（与 pi-mcp-adapter 相同）：首次调用多一次发现往返；模型展开过的 schema 会占据后续上下文。
 
+## 命令
+
+本插件在平台 `commands` 服务上注册一条斜杠命令——该依赖是软性的：宿主若没有命令服务，折叠与两个 meta-tool 照常工作（只记一条日志警告，代价是没有 `/mcp`）。`/mcp` 展示状态；v0.2.0 起它同时也是整个 MCP server 进/出适配器的唯一控制面：
+
+| 形态 | 输出 |
+|---|---|
+| `/mcp` 或 `/mcp list` | 树形总览——每行 server 带 stable `[<id>]` 前缀；disabled 的标 `⏸ disabled` 且不列工具；尾部附折叠健康行 |
+| `/mcp list <name>` | `<name>` 匹配某 server → 该 server 全部工具（disabled 的附加 `⏸` 说明行）；匹配完整工具名 → 完整描述 + 完整 input schema |
+| `/mcp config` | 当前生效的 `prefix` / `keep` / `servers` / `descriptionLimit` 及各自命中清单，外加持久 enable/disable 台账 |
+| `/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`，受影响的分组行会带标记）。
+
+disable 是**门闩式开关，不是真断连**：官方 client 不提供断连 API，工具仍留在注册表里、连接照常运行——门闩只把它请出 prompt、目录与分发。三层门闩共用同一个判定函数，彼此之间以及与 `/mcp` 的展示永远不会口径不一。enable/disable 经 settings 服务持久化；没有 settings 服务时其余功能照常，只有 toggle 会回一条说明性报错。
+
+一条真实边界：门闩生效在 prompt 侧（目录/分发层）；记得完整工具名的模型仍可能原生直调 `mcp__server__tool` 成功——需要硬性拦截时，请配合管线 guard 或 `tools.restrict()`。
+
+状态是**二态语义**：server 出现在列表里 = 它的工具在本 scope 可见——不可见不代表未启用（可能正在重连退避）；官方 client 不暴露连接状态。健康行形如 `meta-tools: mcp_list/mcp_call live · folding ACTIVE — folded N, kept M · ~X chars of schema out of prompt`（meta-tools 存活且至少折叠一个工具时），否则降级为 fail-open（或无可折叠）提示。X 是被折叠 schema 的 JSON 字符数，刻意标注为字符而非 token。输出超过 400 行会被截断，并提示用 `/mcp list <server>` 收窄。
+
 ## 致谢
 
 特别致敬 **[pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter)** 及其作者 [@nicobailon](https://github.com/nicobailon)：本插件的核心思想——把无界的 MCP 工具面折叠为恒定的 meta-tool、schema 按需展开，从而无论挂多少 server 常驻 prompt 成本都是 O(1)——完全来自该项目；正是它重新定义了 MCP 集成应有的代价。本仓库是这个理念在 DeepSeek Harness 上的移植，机制上刻意走了不同的路线（复用官方连接层的 prompt-side shim），但灵感与理念的功劳归于原作。如果你用的是 pi，请直接用原版。

package/lib/index.d.ts

@@ -25,6 +25,17 @@
  * child tool's name never fire for folded calls (the registry only sees the
  * outer `mcp_call`) — gate MCP usage by guarding `mcp_call` itself.
  *
+ * A read-only `/mcp` slash command (platform `commands` service) surfaces the
+ * live state human-side: the server/tool tree, per-server/per-tool details,
+ * the effective configuration, and whether folding is active, idle, or in
+ * fail-open passthrough. The same command carries the one mutating surface:
+ * `/mcp disable <id>` / `/mcp enable <id>` gate a whole server behind all
+ * 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.
+ *
  * Child-owned projections are preserved: `mcp_call` delegates its
  * `output.render` to the dispatched child and forwards the child's
  * `finalizeContent` with the exact same run-execution object, so
@@ -46,14 +57,108 @@ import z from '@deepseek-ai/schemastery';
 import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm';
 import type { ToolDefinition, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools';
 import type { ScopeKey } from '@deepseek-ai/dsh-scope';
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "mcp-adapter";
-/** Services required by this plugin. */
+/**
+ * Services required by this plugin — deliberately just `tools`. The platform
+ * `commands` service is consumed SOFTLY at runtime ({@link apply} mounts it
+ * via `ctx.inject`): listing it here would refuse to load the whole plugin on
+ * hosts that do not compose commands, taking folding down with the command.
+ */
 export declare const inject: string[];
+/** Registered slash-command name (read-only status surface). */
+export declare const MCP_COMMAND_NAME = "mcp";
+/** Max rendered lines of any /mcp output before truncation kicks in. */
+export declare const MCP_OUTPUT_LINE_LIMIT = 400;
+/**
+ * Description cap for TREE views (`/mcp` overview and server listing): keep
+ * each tool to one readable line. The configurable `descriptionLimit`
+ * remains the ceiling for catalog-shaped data (`mcp_list`, `/mcp config`);
+ * full multi-paragraph descriptions belong in `/mcp list <tool>` detail.
+ */
+export declare const TREE_DESCRIPTION_LIMIT = 100;
 /** Registered name of the catalog meta-tool. */
 export declare const MCP_LIST_TOOL_NAME = "mcp_list";
 /** Registered name of the dispatch meta-tool. */
 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. */
+export declare const MCP_ADAPTER_SETTINGS_NAMESPACE: SettingsNamespace;
+/**
+ * The persisted gate state (one settings section). `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.
+ */
+export interface ServerIdRegistry {
+    /** Observed server name -> stable id (1..99), assigned smallest-free-first. */
+    serverIds: Record<string, number>;
+    /** Ids currently gated off; entries whose mapping exists nowhere are inert. */
+    disabled: number[];
+}
+/**
+ * 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.
+ */
+export interface ServerGateState {
+    readonly serverIds: Readonly<Record<string, number>>;
+    readonly disabled: readonly number[];
+}
+/** 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
+ * function's output, so corrupt or hand-edited documents degrade to "some
+ * entries ignored" instead of wedging folding or dispatch.
+ */
+export declare function normalizeServerGate(raw: unknown): ServerGateState;
+/**
+ * THE shared disabled verdict — all three latches (waterfall fold, catalog,
+ * mcp_call dispatch) and every /mcp renderer judge through this one function,
+ * so the gating can never disagree with itself. An unmapped server (or an
+ * absent snapshot, or the degenerate empty server segment) is ENABLED:
+ * gating requires positive evidence, keeping fail-open direction.
+ */
+export declare function isServerDisabled(server: string, gate?: ServerGateState): boolean;
+/** Outcome of {@link allocateMissingServerIds}. */
+export interface ServerIdAllocation {
+    /** Next registry: a fresh object; inputs are never mutated. */
+    registry: ServerIdRegistry;
+    /** Servers left unassigned because the 1..99 space ran out. */
+    unassigned: string[];
+    /** Names that received a NEW id in this pass (empty in steady state). */
+    added: string[];
+}
+/**
+ * Assign the smallest free id (1..99) to every listed server not yet mapped.
+ * Existing mappings are kept verbatim (id stability across restarts); the
+ * allocation never mutates its input. Call this whenever /mcp observes the
+ * live server set, then persist `{@link ServerIdAllocation.registry}` when
+ * `added` is non-empty.
+ */
+export declare function allocateMissingServerIds(state: ServerGateState | undefined, servers: readonly string[]): ServerIdAllocation;
+/** Reverse lookup: which server (if any) carries this id today. */
+export declare function serverNameById(registry: ServerGateState | undefined, id: number): string | undefined;
+/** Outcome of {@link setServerDisabledState}. */
+export interface ServerToggleOutcome {
+    /** Next registry (fresh object); unchanged content when nothing applied. */
+    registry: ServerIdRegistry;
+    /** Whether the disabled set actually moved. */
+    changed: boolean;
+}
+/**
+ * Apply one enable/disable toggle for a MAPPED server onto a copy of the
+ * registry. Unmapped servers are no-ops (`changed: false`). Enabling never
+ * 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. */
 export interface AdapterConfig {
     /** Tool-name prefix to fold out of assembled prompts. */
@@ -96,13 +201,19 @@ export declare function isAllowedServer(name: string, prefix: string, servers: r
  * keep list — and it must never be one of this plugin's own meta-tools,
  * whatever the prefix is configured to (folding them would make every folded
  * MCP tool undiscoverable).
+ *
+ * Gate override: when the tool's server is DISABLED
+ * ({@link isServerDisabled}, shared with catalog/dispatch), its schema folds
+ * OUT regardless of keep patterns or the servers whitelist — disablement is
+ * strictly stronger than any config exemption.
  * @param name - the registered tool name.
  * @param prefix - tool-name prefix to fold.
  * @param keep - keep patterns from config.
  * @param servers - server-name whitelist from config (default: no filtering).
+ * @param gate - live disabled-server snapshot (default/undefined: none).
  * @returns whether the schema leaves the prompt (the tool stays callable).
  */
-export declare function shouldFold(name: string, prefix: string, keep: readonly string[], servers?: readonly string[]): boolean;
+export declare function shouldFold(name: string, prefix: string, keep: readonly string[], servers?: readonly string[], gate?: ServerGateState): boolean;
 /** Folding knobs resolved from config. */
 export interface FoldOptions {
     /** Tool-name prefix to fold. */
@@ -135,9 +246,11 @@ export interface AssemblyWithTools {
  * @param options - folding knobs.
  * @param metaToolsLive - whether both meta-tools currently resolve to this
  *   plugin's own definitions in the assembling scope.
+ * @param gate - live disabled-server snapshot, fresh per assembly (default:
+ *   none disabled).
  * @returns the folded assembly, or the input unchanged when nothing folds.
  */
-export declare function foldPromptAssembly<T extends AssemblyWithTools>(assembly: T, options: FoldOptions, metaToolsLive: boolean): T;
+export declare function foldPromptAssembly<T extends AssemblyWithTools>(assembly: T, options: FoldOptions, metaToolsLive: boolean, gate?: ServerGateState): T;
 /** Options for the catalog builder. */
 export interface McpListOptions {
     /** Tool-name prefix identifying MCP tools. */
@@ -146,6 +259,12 @@ export interface McpListOptions {
     descriptionLimit: number;
     /** 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.
+     */
+    getGate?: () => ServerGateState | undefined;
 }
 /** Normalized `mcp_list` arguments. */
 export interface McpListArgs {
@@ -200,10 +319,13 @@ export declare function serverOfToolName(name: string, prefix: string): string;
  * Truncate one description to the catalog limit, marking the cut with an
  * ellipsis character (so one char of headroom is reserved). A cut that would
  * land on the LOW half of a surrogate pair backs off one code unit so no
- * orphaned high surrogate is emitted.
+ * orphaned high surrogate is emitted. Whitespace runs (newlines, indents)
+ * are collapsed to single spaces FIRST — MCP vendors routinely ship
+ * multi-paragraph usage guides as descriptions and catalog lines must stay
+ * single-line.
  * @param text - the full tool description.
  * @param limit - max chars in the catalog.
- * @returns the truncated description.
+ * @returns the single-line truncated description.
  */
 export declare function truncateDescription(text: string, limit: number): string;
 /**
@@ -217,9 +339,10 @@ export declare function truncateDescription(text: string, limit: number): string
  * @param args - the normalized catalog query.
  * @param schemas - schemas visible to the calling agent.
  * @param options - catalog knobs.
+ * @param gate - live disabled-server snapshot (default: none disabled).
  * @returns the canonical result value.
  */
-export declare function buildMcpListResult(args: McpListArgs, schemas: readonly ToolSchema[], options: McpListOptions): McpListResult;
+export declare function buildMcpListResult(args: McpListArgs, schemas: readonly ToolSchema[], options: McpListOptions, gate?: ServerGateState): McpListResult;
 /** Structural slice of a resolvable tool: what dispatch actually consumes. */
 export interface DispatchableTool<E> {
     /** Cooperative timeout budget declared by the tool, if any. */
@@ -258,9 +381,275 @@ export interface DispatchableTool<E> {
  * @param resolve - scope-aware tool resolver (production: `ctx.tools.get`).
  * @param exec - the meta-tool's run context, forwarded to the child.
  * @param servers - server-name whitelist (default: no filtering).
+ * @param gate - live disabled-server snapshot (default: none disabled). The
+ *   disabled branch sits after the prefix/whitelist validation: a disabled
+ *   server's tools are refused with an explicit `/mcp enable <id>` hint
+ *   before the child is ever resolved.
  * @returns the child's resolved value verbatim, or a structured error.
  */
-export declare function dispatchMcpCall<E>(args: unknown, prefix: string, resolve: (name: string) => DispatchableTool<E> | undefined, exec: E, servers?: readonly string[]): Promise<unknown>;
+export declare function dispatchMcpCall<E>(args: unknown, prefix: string, resolve: (name: string) => DispatchableTool<E> | undefined, exec: E, servers?: readonly string[], gate?: ServerGateState): Promise<unknown>;
+/** Knobs shared by every /mcp renderer — plain data, no Cordis. */
+export interface McpCommandOptions {
+    /** Tool-name prefix identifying MCP tools. */
+    prefix: string;
+    /** Name patterns kept native in the prompt ("*" wildcard). */
+    keep: readonly string[];
+    /** Server-name whitelist; empty or omitted admits every server. */
+    servers?: readonly string[];
+    /** 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.
+     */
+    gate?: ServerGateState;
+    /**
+     * Live server names left WITHOUT a stable id because the 1..99 space was
+     * full when they appeared (production:
+     * {@link ServerIdAllocation.unassigned}). Views — not an erroring toggle —
+     * surface that fact, since a server without an id cannot be targeted by
+     * one in the first place.
+     */
+    unassignedServers?: readonly string[];
+}
+/** Usage text returned for unparseable /mcp invocations. */
+export declare const MCP_COMMAND_USAGE: string;
+/** One parsed /mcp invocation. */
+export type ParsedMcpCommandInput = {
+    form: 'overview';
+} | {
+    form: 'detail';
+    name: string;
+} | {
+    form: 'config';
+} | {
+    form: 'disable';
+    id: number;
+} | {
+    form: 'enable';
+    id: number;
+} | {
+    form: 'usage';
+};
+/**
+ * Parse one /mcp raw input into its form. `''` and `'list'` are the tree
+ * overview; `'list <name>'` is a server/tool detail; `'config'` shows the
+ * effective configuration; `'disable <n>'` / `'enable <n>'` are whole-server
+ * toggles (n is the stable id shown by `/mcp`, so a bare `0` or non-numeric
+ * token is already usage). Everything else parses to the usage error.
+ * @param rawInput - exact text following the command name.
+ * @returns the normalized command form.
+ */
+export declare function parseMcpCommandInput(rawInput: string): ParsedMcpCommandInput;
+/**
+ * Distinct server names among one view's candidates, in first-seen order —
+ * the live set stable ids are allocated against.
+ */
+export declare function liveServerNames(schemas: readonly ToolSchema[], options: Pick<McpCommandOptions, 'prefix' | 'servers'>): string[];
+/** Three-state folding health of the /mcp overview footer. */
+export type McpFoldingHealth = {
+    state: 'folding';
+    folded: number;
+    kept: number;
+    schemaChars: number;
+} | {
+    state: 'fail-open';
+} | {
+    state: 'idle';
+    matched: number;
+};
+/** Which tools count toward which health bucket. */
+export interface McpHealthStats {
+    /** Prefix-matching tools whose schema was folded out of the prompt. */
+    folded: ToolSchema[];
+    /**
+     * Prefix-matching tools that stay native despite matching the prefix —
+     * exempted either by a keep pattern or by the servers whitelist decision.
+     */
+    kept: ToolSchema[];
+}
+/**
+ * Partition one scope's schemas into folded vs kept MCP tools and measure
+ * how many schema characters leave the prompt. Mirrors {@link shouldFold}
+ * exactly; the meta-tools themselves are never counted.
+ *
+ * Health semantics follow the waterfall: folding counts as ACTIVE only when
+ * the meta-tools are live AND at least one tool actually folds. Live but
+ * nothing to fold is the idle state; not-live is fail-open.
+ *
+ * @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.
+ * @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.
+ */
+export declare function collectMcpHealth(schemas: readonly ToolSchema[], options: McpCommandOptions, metaToolsLive: boolean): {
+    stats: McpHealthStats;
+    health: McpFoldingHealth;
+};
+/**
+ * Render the overview footer line for one health reading. Exactly one of:
+ * `meta-tools: ... live · folding ACTIVE — folded N, kept M · ~X chars of
+ * schema out of prompt`, the fail-open notice, or the nothing-to-fold notice.
+ * @param health - the collected health reading.
+ * @returns the single footer line.
+ */
+export declare function renderMcpHealthLine(health: McpFoldingHealth): string;
+/** One server group in the /mcp views. */
+export interface McpServerGroup {
+    server: string;
+    schemas: ToolSchema[];
+}
+/**
+ * Header line of one server group in the tree views. Without a gate snapshot
+ * the line is the plain legacy form (`name (n)`); with one, every group is
+ * prefixed by its stable id — `[1] fs (4)` — and a DISABLED group renders as
+ * `[2] gh ⏸ disabled — hides 3 tool(s)` and lists no tools at all.
+ */
+export declare function renderServerGroupHeader(group: Pick<McpServerGroup, 'server' | 'schemas'>, gate?: ServerGateState): string;
+/**
+ * Group one scope's candidate schemas by server, first-seen order — the same
+ * filtering contract as the `mcp_list` catalog loop.
+ * @param schemas - schemas visible to the receiving agent.
+ * @param options - adapter knobs (prefix/servers).
+ * @returns server groups in first-seen order.
+ */
+export declare function groupSchemasByServer(schemas: readonly ToolSchema[], options: Pick<McpCommandOptions, 'prefix' | 'servers'>): McpServerGroup[];
+/**
+ * Cap rendered /mcp output so a giant deployment cannot flood the transcript.
+ * At most `limit` lines survive; the last becomes a truncation notice naming
+ * the narrowing subcommand.
+ * @param text - the rendered multi-line output.
+ * @param limit - max output lines (default {@link MCP_OUTPUT_LINE_LIMIT}).
+ * @returns the capped text (identical when already within the limit).
+ */
+export declare function capRenderedLines(text: string, limit?: number): string;
+/**
+ * The one-line id-exhaustion notice for /mcp views. `undefined` while the
+ * stable id space has room. This is where the 99-cap promise lands: a server
+ * beyond the cap never gets an id, so no toggle could ever target it — the
+ * views say so explicitly instead of pretending otherwise.
+ * @param unassigned - live servers observed without an assignable id.
+ * @returns the notice line, or nothing when the space is not exhausted.
+ */
+export declare function renderIdCapNotice(unassigned?: readonly string[]): string | undefined;
+/**
+ * Render the `/mcp` / `/mcp list` tree overview: one block per server with
+ * each tool's name and truncated description (disabled servers show only a
+ * `⏸ disabled` header line — their tools are hidden), closed by the
+ * folding-health footer line. Servers beyond the id cap carry a marker on
+ * their group header, and full exhaustion appends an explicit notice after
+ * the footer. Output is line-capped defensively.
+ * @param schemas - schemas visible to the receiving agent.
+ * @param options - adapter knobs (prefix/keep/servers/descriptionLimit/gate/
+ *   unassignedServers).
+ * @param metaToolsLive - whether both meta-tools are live in that scope.
+ * @returns the complete overview text.
+ */
+export declare function renderMcpOverview(schemas: readonly ToolSchema[], options: McpCommandOptions, metaToolsLive: boolean): string;
+/** One resolved `/mcp list <name>` target. */
+export type McpDetailTarget = {
+    kind: 'server';
+    server: string;
+    schemas: ToolSchema[];
+} | {
+    kind: 'tool';
+    schema: ToolSchema;
+};
+/**
+ * Resolve `<name>` against one scope's candidates: a server segment first
+ * (all of its tools), then an exact registered tool name.
+ * @param name - server name or full registered tool name.
+ * @param schemas - schemas visible to the receiving agent.
+ * @param options - adapter knobs (prefix/servers).
+ * @returns the resolved target, or undefined when nothing matches.
+ */
+export declare function resolveMcpDetailTarget(name: string, schemas: readonly ToolSchema[], options: Pick<McpCommandOptions, 'prefix' | 'servers'>): McpDetailTarget | undefined;
+/** Outcome of rendering `/mcp list <name>`; `unknown` maps to an error result. */
+export interface McpDetailView {
+    outcome: 'server' | 'tool' | 'unknown';
+    text: string;
+}
+/**
+ * Render `/mcp list <name>`: for a server, its full tool list (names +
+ * truncated descriptions); for a single tool, the FULL untruncated
+ * description plus the complete input schema. Unknown names produce a
+ * descriptive miss rather than generic usage. Human inspection is never
+ * gated, but a target belonging to a disabled server says so — with its
+ * `/mcp enable <id>` hint.
+ * @param name - the requested server or tool name.
+ * @param schemas - schemas visible to the receiving agent.
+ * @param options - adapter knobs (prefix/keep/servers/descriptionLimit/gate).
+ * @returns the rendered view.
+ */
+export declare function renderMcpDetail(name: string, schemas: readonly ToolSchema[], options: McpCommandOptions): McpDetailView;
+/**
+ * Render the effective configuration with each knob's hitting tools:
+ * which names match the prefix, what each keep pattern holds back, and what
+ * each whitelisted server contributes. Read-only inventory, no mutations.
+ * Tools of disabled servers stay LISTED but carry a `⏸` marker — views
+ * inform, they never hide.
+ * @param schemas - schemas visible to the receiving agent.
+ * @param options - adapter knobs (prefix/keep/servers/descriptionLimit/gate/
+ *   unassignedServers).
+ * @returns the rendered configuration view.
+ */
+export declare function renderMcpConfig(schemas: readonly ToolSchema[], options: McpCommandOptions): string;
+/** Plain-data view one /mcp handler execution reads; production wiring fills
+ * it from the receiving agent's scope before calling {@link executeMcpCommand}.
+ */
+export interface McpCommandView {
+    /** Exact text following the command name. */
+    rawInput: string;
+    /** Schemas visible to the receiving agent (`ctx.tools.schemas(scope)`). */
+    schemas: readonly ToolSchema[];
+    /** Effective adapter knobs plus the invocation-time gate snapshot (`gate`). */
+    config: McpCommandOptions;
+    /** 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?: 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.
+     */
+    writeGate?: (next: ServerIdRegistry) => Promise<void>;
+    /**
+     * Cancellation signal owned by the dispatching UI request (production:
+     * `invocation.signal`). Only the WAIT rides it: an aborted toggle answers
+     * immediately that the outcome is unconfirmed while the write still
+     * finishes in the background — same-process code cannot hard-kill it.
+     */
+    signal?: AbortSignal;
+}
+/** CommandResult-compatible outcome (platform shape: success may omit text). */
+export interface McpCommandOutcome {
+    kind: 'success' | 'error';
+    text: string;
+}
+/**
+ * Execute one /mcp invocation over plain data. Read forms stay side-effect-
+ * free except for stable-id bookkeeping: any form that displays ids ensures
+ * every newly observed server has one and persists fresh assignments through
+ * `writeGate` (best-effort — a failed persistence still renders, ids merely
+ * reallocate identically next time). The mutating forms validate their target
+ * against the LIVE server set, then persist one combined write (allocations +
+ * toggle); every failure surfaces as a structured `{ kind: 'error', text }`
+ * outcome, never a throw.
+ *
+ * @param view - the invocation's resolved inputs.
+ * @returns a platform-shaped command outcome.
+ */
+export declare function executeMcpCommand(view: McpCommandView): Promise<McpCommandOutcome>;
 /**
  * Render one mcp_call outcome by delegating to the dispatched child's own
  * `output.render`, so model-facing text is exactly what a native call of the
@@ -326,9 +715,13 @@ export declare function createMcpListTool(options: McpListOptions, listSchemas:
  * @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.
  * @returns the complete tool definition.
  */
-export declare function createMcpCallTool(prefix: string, resolve: (name: string, scope?: ScopeKey) => ToolDefinition | undefined, servers?: readonly string[]): ToolDefinition;
+export declare function createMcpCallTool(prefix: string, resolve: (name: string, scope?: ScopeKey) => ToolDefinition | undefined, servers?: readonly string[], getGate?: () => ServerGateState | undefined): ToolDefinition;
 /**
  * Register the two meta-tools and install the assembly folding listener.
  *
@@ -336,6 +729,18 @@ 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.
+ *
+ * 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.
+ *
  * @param ctx - plugin context carrying the tool registry.
  * @param config - resolved adapter configuration.
  */