@aiwayds/dsh-mcp-adapter 0.1.0 → 0.2.0

package/lib/index.js

@@ -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
@@ -42,10 +53,22 @@
  * @module @aiwayds/dsh-mcp-adapter
  */
 import z from '@deepseek-ai/schemastery';
+// `settingsNamespace` is the one RUNTIME import from dsh-settings: cheap
+// kebab-case validation of our namespace string at module load.
+import { settingsNamespace } from '@deepseek-ai/dsh-settings';
 /** Cordis plugin name used by loader diagnostics. */
 export 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 const inject = ['tools'];
+/** Registered slash-command name (read-only status surface). */
+export const MCP_COMMAND_NAME = 'mcp';
+/** Max rendered lines of any /mcp output before truncation kicks in. */
+export const MCP_OUTPUT_LINE_LIMIT = 400;
 /** Registered name of the catalog meta-tool. */
 export const MCP_LIST_TOOL_NAME = 'mcp_list';
 /** Registered name of the dispatch meta-tool. */
@@ -56,6 +79,130 @@ const DEFAULT_DESCRIPTION_LIMIT = 200;
 const DEFAULT_PREFIX = 'mcp__';
 /** Valid fold prefix: non-empty, tool-name characters only. */
 const PREFIX_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+// ---- Server enable/disable (pure) ----
+/** Upper bound of the stable per-server id space. */
+export const MCP_SERVER_ID_LIMIT = 99;
+/** dsh settings namespace persisting the stable ids and the disabled set. */
+export const MCP_ADAPTER_SETTINGS_NAMESPACE = settingsNamespace('mcp-adapter');
+/** Gate snapshot meaning "nothing observed, nothing disabled". */
+export const EMPTY_SERVER_GATE = { serverIds: {}, disabled: [] };
+/** Schema of the persisted `mcp-adapter` settings section. */
+export const SERVER_ID_REGISTRY_SCHEMA = z.object({
+    serverIds: z.dict(z.number().step(1).min(1).max(MCP_SERVER_ID_LIMIT)).default({}),
+    disabled: z.array(z.number().step(1).min(1).max(MCP_SERVER_ID_LIMIT)).default([]),
+});
+/** Whether one number is an allocatable server id. */
+function isValidServerId(id) {
+    return typeof id === 'number' && Number.isInteger(id) && id >= 1 && id <= MCP_SERVER_ID_LIMIT;
+}
+/**
+ * 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 function normalizeServerGate(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return EMPTY_SERVER_GATE;
+    const rawIds = raw.serverIds;
+    const rawDisabled = raw.disabled;
+    // One id must name exactly one server: on duplicate ids first mapping wins.
+    const taken = new Set();
+    const serverIds = {};
+    if (typeof rawIds === 'object' && rawIds !== null && !Array.isArray(rawIds)) {
+        for (const [name, id] of Object.entries(rawIds)) {
+            if (name !== '' && isValidServerId(id) && !taken.has(id)) {
+                taken.add(id);
+                serverIds[name] = id;
+            }
+        }
+    }
+    const seen = new Set();
+    const disabled = [];
+    if (Array.isArray(rawDisabled)) {
+        for (const entry of rawDisabled) {
+            if (isValidServerId(entry) && !seen.has(entry)) {
+                seen.add(entry);
+                disabled.push(entry);
+            }
+        }
+    }
+    return { serverIds, disabled };
+}
+/**
+ * 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 function isServerDisabled(server, gate) {
+    if (gate === undefined || server === '')
+        return false;
+    const id = gate.serverIds[server];
+    return id !== undefined && gate.disabled.includes(id);
+}
+/**
+ * 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 function allocateMissingServerIds(state, servers) {
+    const source = normalizeServerGate(state);
+    const serverIds = { ...source.serverIds };
+    // Disabled ids stay burned even when their server vanished from the map
+    // (hand-edited documents): a fresh assignment must never inherit a stale
+    // disabled flag it did not ask for.
+    const used = new Set([...Object.values(serverIds), ...source.disabled]);
+    const added = [];
+    const unassigned = [];
+    for (const server of servers) {
+        if (server === '' || serverIds[server] !== undefined)
+            continue;
+        let id = 1;
+        while (used.has(id))
+            id += 1;
+        if (id > MCP_SERVER_ID_LIMIT) {
+            unassigned.push(server);
+            continue;
+        }
+        used.add(id);
+        serverIds[server] = id;
+        added.push(server);
+    }
+    return { registry: { serverIds, disabled: [...source.disabled] }, unassigned, added };
+}
+/** Reverse lookup: which server (if any) carries this id today. */
+export function serverNameById(registry, id) {
+    if (registry === undefined)
+        return undefined;
+    for (const [name, mapped] of Object.entries(registry.serverIds)) {
+        if (mapped === id)
+            return name;
+    }
+    return undefined;
+}
+/**
+ * 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 function setServerDisabledState(state, server, disable) {
+    const source = normalizeServerGate(state);
+    const id = source.serverIds[server];
+    const has = id !== undefined && source.disabled.includes(id);
+    // Disable without a mapping (or already disabled) is inert; enable just
+    // filters — both keep the id mapping untouched.
+    const nextDisabled = disable
+        ? id === undefined || has ? [...source.disabled] : [...source.disabled, id].sort((a, b) => a - b)
+        : source.disabled.filter(entry => entry !== id);
+    return {
+        registry: { serverIds: { ...source.serverIds }, disabled: nextDisabled },
+        changed: disable ? id !== undefined && !has : has,
+    };
+}
 export const Config = z.object({
     prefix: z.string().pattern(PREFIX_PATTERN).default(DEFAULT_PREFIX),
     keep: z.array(String).default([]),
@@ -112,17 +259,26 @@ export function isAllowedServer(name, prefix, servers) {
  * 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 function shouldFold(name, prefix, keep, servers = []) {
+export function shouldFold(name, prefix, keep, servers = [], gate) {
     if (name === MCP_LIST_TOOL_NAME || name === MCP_CALL_TOOL_NAME)
         return false;
-    return prefix !== '' && name.startsWith(prefix) && !matchesKeep(name, keep)
-        && isAllowedServer(name, prefix, servers);
+    if (prefix === '' || !name.startsWith(prefix))
+        return false;
+    if (isServerDisabled(serverOfToolName(name, prefix), gate))
+        return true;
+    return !matchesKeep(name, keep) && isAllowedServer(name, prefix, servers);
 }
 /**
  * Rewrite one assembled prompt: drop the schemas of foldable tools, keep
@@ -137,13 +293,15 @@ export function shouldFold(name, prefix, keep, servers = []) {
  * @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 function foldPromptAssembly(assembly, options, metaToolsLive) {
+export function foldPromptAssembly(assembly, options, metaToolsLive, gate) {
     if (!metaToolsLive)
         return assembly;
     const servers = options.servers ?? [];
-    const tools = assembly.tools.filter(tool => !shouldFold(tool.name, options.prefix, options.keep, servers));
+    const tools = assembly.tools.filter(tool => !shouldFold(tool.name, options.prefix, options.keep, servers, gate));
     if (tools.length === assembly.tools.length)
         return assembly;
     return { ...assembly, tools };
@@ -207,9 +365,10 @@ export function truncateDescription(text, limit) {
  * @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 function buildMcpListResult(args, schemas, options) {
+export function buildMcpListResult(args, schemas, options, gate) {
     const { prefix, descriptionLimit } = options;
     const servers = options.servers ?? [];
     if (args.tool !== undefined) {
@@ -225,6 +384,11 @@ export function buildMcpListResult(args, schemas, options) {
         if (!isAllowedServer(args.tool, prefix, servers)) {
             return { error: `"${args.tool}" belongs to server "${serverOfToolName(args.tool, prefix)}", which is not in the configured servers list` };
         }
+        const gatedServer = serverOfToolName(args.tool, prefix);
+        if (isServerDisabled(gatedServer, gate)) {
+            const id = gate?.serverIds[gatedServer];
+            return { error: `refusing to expand "${args.tool}": server "${gatedServer}" is disabled — it can be restored with "/mcp enable ${String(id)}"` };
+        }
         const schema = schemas.find(candidate => candidate.name === args.tool);
         if (schema === undefined) {
             return { error: `unknown MCP tool "${args.tool}" — the server may have re-synced; call ${MCP_LIST_TOOL_NAME} to refresh` };
@@ -233,6 +397,8 @@ export function buildMcpListResult(args, schemas, options) {
         return { tool: { name: schema.name, description: schema.description, parameters: schema.parameters } };
     }
     const serversOut = [];
+    // Servers that passed prefix/whitelist checks but were hidden by the gate.
+    const gatedAway = [];
     for (const schema of schemas) {
         // Never catalog the meta-tools themselves, even under a prefix that
         // matches their names.
@@ -243,6 +409,13 @@ export function buildMcpListResult(args, schemas, options) {
         if (!isAllowedServer(schema.name, prefix, servers))
             continue;
         const server = serverOfToolName(schema.name, prefix);
+        // Disabled servers vanish from the directory entirely; point-name
+        // expansion above remains the structured way to learn why.
+        if (isServerDisabled(server, gate)) {
+            if (!gatedAway.includes(server))
+                gatedAway.push(server);
+            continue;
+        }
         if (args.server !== undefined && server !== args.server)
             continue;
         let group = serversOut.find(entry => entry.server === server);
@@ -257,6 +430,17 @@ export function buildMcpListResult(args, schemas, options) {
         });
     }
     if (serversOut.length === 0) {
+        if (args.server !== undefined && isServerDisabled(args.server, gate)) {
+            const id = gate?.serverIds[args.server];
+            return { error: `server "${args.server}" is disabled and hidden from the catalog — restore it with "/mcp enable ${String(id)}"` };
+        }
+        // An unfiltered catalog that found prefix tools but lost ALL of them to
+        // the gate must not claim "nothing is registered" (same facts as the
+        // filtered path above): name each hidden server with its restore hint.
+        if (args.server === undefined && gatedAway.length > 0) {
+            const named = gatedAway.map(name => `"${name}" ("/mcp enable ${String(gate?.serverIds[name])}")`).join(', ');
+            return { error: `every MCP tool under the "${prefix}" prefix belongs to a disabled server and is hidden from the catalog: ${named}` };
+        }
         return args.server === undefined
             ? { error: `no MCP tools are registered under the "${prefix}" prefix` }
             : { error: `no MCP tools match server "${args.server}"` };
@@ -294,9 +478,13 @@ export function buildMcpListResult(args, schemas, options) {
  * @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 async function dispatchMcpCall(args, prefix, resolve, exec, servers = []) {
+export async function dispatchMcpCall(args, prefix, resolve, exec, servers = [], gate) {
     if (typeof args !== 'object' || args === null || Array.isArray(args)) {
         return { error: `${MCP_CALL_TOOL_NAME} expects an object { "tool": string, "arguments"?: object }` };
     }
@@ -314,6 +502,11 @@ export async function dispatchMcpCall(args, prefix, resolve, exec, servers = [])
     if (!isAllowedServer(tool, prefix, servers)) {
         return { error: `refusing to call "${tool}": server "${serverOfToolName(tool, prefix)}" is not in the configured servers list` };
     }
+    const gatedServer = serverOfToolName(tool, prefix);
+    if (isServerDisabled(gatedServer, gate)) {
+        const id = gate?.serverIds[gatedServer];
+        return { error: `refusing to call "${tool}": server "${gatedServer}" is disabled — ask the operator to run "/mcp enable ${String(id)}" to restore it` };
+    }
     const definition = resolve(tool);
     if (definition === undefined) {
         return { error: `tool "${tool}" is not registered or not visible in this scope — call ${MCP_LIST_TOOL_NAME} to see the catalog` };
@@ -351,7 +544,513 @@ async function raceToolTimeout(definition, timeoutMs, args, exec) {
             clearTimeout(timer);
     }
 }
-// ---- Meta-tool definitions (factories; Cordis-free) ----
+/** Usage text returned for unparseable /mcp invocations. */
+export const MCP_COMMAND_USAGE = [
+    'Usage: /mcp [list [server|tool] | config | disable <id> | enable <id>]',
+    '',
+    '/mcp               tree of MCP servers and tools, plus folding health',
+    '/mcp list          same as /mcp',
+    '/mcp list <name>   details for one server (its full tool list), or for one',
+    '                   tool: full description + complete input schema (<name> is a',
+    '                   server name or a full registered tool name)',
+    '/mcp config        effective adapter configuration with per-pattern and',
+    '                   per-server tool matches (read-only)',
+    '/mcp disable <id>  fold one server\'s tools out of every prompt until it is',
+    '                   enabled again (<id> is the stable number shown by "/mcp";',
+    '                   keep and servers exemptions included)',
+    '/mcp enable <id>   restore a disabled server under the same stable id',
+].join('\n');
+/** Parse one positive integer token (`1`..); anything else is undefined. */
+function parsePositiveInt(token) {
+    return /^[1-9][0-9]*$/.test(token) ? Number(token) : undefined;
+}
+/**
+ * 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 function parseMcpCommandInput(rawInput) {
+    const parts = rawInput.trim().split(/\s+/);
+    switch (parts[0]) {
+        case '':
+            return { form: 'overview' };
+        case 'list':
+            if (parts.length === 1)
+                return { form: 'overview' };
+            if (parts.length === 2)
+                return { form: 'detail', name: parts[1] };
+            return { form: 'usage' };
+        case 'config':
+            return parts.length === 1 ? { form: 'config' } : { form: 'usage' };
+        case 'disable':
+        case 'enable': {
+            const id = parts.length === 2 ? parsePositiveInt(parts[1]) : undefined;
+            return id === undefined ? { form: 'usage' } : { form: parts[0], id };
+        }
+        default:
+            return { form: 'usage' };
+    }
+}
+/** The visible-schemas candidate set every /mcp view draws from: this view's
+ * prefix-matching MCP tools — never the meta-tools themselves, and never
+ * tools outside the servers whitelist (consistent with fold/catalog/dispatch).
+ */
+function mcpCommandCandidates(schemas, options) {
+    const servers = options.servers ?? [];
+    return schemas.filter(schema => schema.name !== MCP_LIST_TOOL_NAME
+        && schema.name !== MCP_CALL_TOOL_NAME
+        && schema.name.startsWith(options.prefix)
+        && isAllowedServer(schema.name, options.prefix, servers));
+}
+/**
+ * Distinct server names among one view's candidates, in first-seen order —
+ * the live set stable ids are allocated against.
+ */
+export function liveServerNames(schemas, options) {
+    const seen = new Set();
+    const names = [];
+    for (const schema of mcpCommandCandidates(schemas, options)) {
+        const server = serverOfToolName(schema.name, options.prefix);
+        if (server === '' || seen.has(server))
+            continue;
+        seen.add(server);
+        names.push(server);
+    }
+    return names;
+}
+/**
+ * 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 function collectMcpHealth(schemas, options, metaToolsLive) {
+    if (!metaToolsLive)
+        return { stats: { folded: [], kept: [] }, health: { state: 'fail-open' } };
+    const servers = options.servers ?? [];
+    const folded = [];
+    const kept = [];
+    let matched = 0;
+    for (const schema of schemas) {
+        if (schema.name === MCP_LIST_TOOL_NAME || schema.name === MCP_CALL_TOOL_NAME)
+            continue;
+        if (!schema.name.startsWith(options.prefix))
+            continue;
+        matched += 1;
+        if (shouldFold(schema.name, options.prefix, options.keep, servers, options.gate))
+            folded.push(schema);
+        else
+            kept.push(schema);
+    }
+    if (folded.length === 0)
+        return { stats: { folded, kept }, health: { state: 'idle', matched } };
+    // Schema weight removed from the standing prompt: JSON size of every folded
+    // tool's parameters object. Chars, deliberately NOT tokens.
+    const schemaChars = folded.reduce((sum, schema) => sum + (schema.parameters === undefined ? 0 : JSON.stringify(schema.parameters).length), 0);
+    return { stats: { folded, kept }, health: { state: 'folding', folded: folded.length, kept: kept.length, schemaChars } };
+}
+/**
+ * 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 function renderMcpHealthLine(health) {
+    switch (health.state) {
+        case 'folding':
+            return `meta-tools: ${MCP_LIST_TOOL_NAME}/${MCP_CALL_TOOL_NAME} live · folding ACTIVE`
+                + ` — folded ${health.folded}, kept ${health.kept}`
+                + ` · ~${health.schemaChars} chars of schema out of prompt`;
+        case 'fail-open':
+            return 'folding INACTIVE (fail-open) — full schemas are passing through';
+        case 'idle':
+            return health.matched > 0
+                ? `folding INACTIVE (nothing folded) — ${health.matched} matching tool(s) stay native via keep/servers exemptions`
+                : `folding INACTIVE (nothing folded) — no MCP tools match the configured prefix`;
+    }
+}
+/**
+ * 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 function renderServerGroupHeader(group, gate) {
+    if (gate === undefined)
+        return `${group.server} (${group.schemas.length})`;
+    const id = gate.serverIds[group.server];
+    const label = `[${id === undefined ? '-' : String(id)}] ${group.server}`;
+    if (isServerDisabled(group.server, gate)) {
+        return `${label} ⏸ disabled — hides ${group.schemas.length} tool(s)`;
+    }
+    return `${label} (${group.schemas.length})`;
+}
+/**
+ * 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 function groupSchemasByServer(schemas, options) {
+    const groups = [];
+    for (const schema of mcpCommandCandidates(schemas, options)) {
+        const server = serverOfToolName(schema.name, options.prefix);
+        let group = groups.find(entry => entry.server === server);
+        if (group === undefined) {
+            group = { server, schemas: [] };
+            groups.push(group);
+        }
+        group.schemas.push(schema);
+    }
+    return groups;
+}
+/**
+ * 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 function capRenderedLines(text, limit = MCP_OUTPUT_LINE_LIMIT) {
+    const lines = text.split('\n');
+    if (lines.length <= limit)
+        return text;
+    const dropped = lines.length - limit + 1;
+    return `${lines.slice(0, limit - 1).join('\n')}\n… output truncated at ${limit} lines (${dropped} dropped) — narrow with "/mcp list <server>"`;
+}
+/**
+ * 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 function renderIdCapNotice(unassigned) {
+    if (unassigned === undefined || unassigned.length === 0)
+        return undefined;
+    return `id space exhausted (${MCP_SERVER_ID_LIMIT}/${MCP_SERVER_ID_LIMIT}): `
+        + `${unassigned.length} server(s) beyond the cap cannot be gated`;
+}
+/**
+ * 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 function renderMcpOverview(schemas, options, metaToolsLive) {
+    const groups = groupSchemasByServer(schemas, options);
+    const total = groups.reduce((sum, group) => sum + group.schemas.length, 0);
+    const lines = [`MCP servers/tools — ${total} tool(s) across ${groups.length} server(s)`];
+    for (const group of groups) {
+        const header = renderServerGroupHeader(group, options.gate);
+        lines.push('', options.unassignedServers?.includes(group.server)
+            ? `${header} — beyond the id cap`
+            : header);
+        if (isServerDisabled(group.server, options.gate))
+            continue;
+        group.schemas.forEach((schema, index) => {
+            const connector = index === group.schemas.length - 1 ? '└─' : '├─';
+            const description = truncateDescription(schema.description, options.descriptionLimit);
+            lines.push(`${connector} ${schema.name}${description === '' ? '' : ` — ${description}`}`);
+        });
+    }
+    lines.push('', renderMcpHealthLine(collectMcpHealth(schemas, options, metaToolsLive).health));
+    const idCapNotice = renderIdCapNotice(options.unassignedServers);
+    if (idCapNotice !== undefined)
+        lines.push(idCapNotice);
+    return capRenderedLines(lines.join('\n'));
+}
+/**
+ * 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 function resolveMcpDetailTarget(name, schemas, options) {
+    const candidates = mcpCommandCandidates(schemas, options);
+    const serverSchemas = candidates.filter(schema => serverOfToolName(schema.name, options.prefix) === name);
+    if (serverSchemas.length > 0)
+        return { kind: 'server', server: name, schemas: serverSchemas };
+    const exact = candidates.find(schema => schema.name === name);
+    return exact === undefined ? undefined : { kind: 'tool', schema: exact };
+}
+/**
+ * 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 function renderMcpDetail(name, schemas, options) {
+    const target = resolveMcpDetailTarget(name, schemas, options);
+    if (target === undefined) {
+        return {
+            outcome: 'unknown',
+            text: `no MCP server or tool matches "${name}" in this scope — run "/mcp" for the current tree`,
+        };
+    }
+    if (target.kind === 'server') {
+        const lines = [`server "${target.server}" — ${target.schemas.length} tool(s)`];
+        if (isServerDisabled(target.server, options.gate)) {
+            const id = options.gate?.serverIds[target.server];
+            lines.push(`⏸ this server is disabled — its tools are folded out of every prompt; restore with "/mcp enable ${String(id)}"`);
+        }
+        target.schemas.forEach((schema, index) => {
+            const connector = index === target.schemas.length - 1 ? '└─' : '├─';
+            const description = truncateDescription(schema.description, options.descriptionLimit);
+            lines.push(`${connector} ${schema.name}${description === '' ? '' : ` — ${description}`}`);
+        });
+        return { outcome: 'server', text: capRenderedLines(lines.join('\n')) };
+    }
+    const server = serverOfToolName(target.schema.name, options.prefix);
+    const parameters = target.schema.parameters === undefined
+        ? '(none)'
+        : JSON.stringify(target.schema.parameters, null, 2);
+    let text = `${target.schema.name} (server: ${server})\n\n${target.schema.description}\n\ninputSchema:\n${parameters}`;
+    if (isServerDisabled(server, options.gate)) {
+        const id = options.gate?.serverIds[server];
+        text += `\n\nnote: server "${server}" is disabled — restore it with "/mcp enable ${String(id)}"`;
+    }
+    return { outcome: 'tool', text: capRenderedLines(text) };
+}
+/**
+ * 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 function renderMcpConfig(schemas, options) {
+    const candidates = mcpCommandCandidates(schemas, options);
+    const servers = options.servers ?? [];
+    // Inventory completeness over gating: mark gate-held tools instead of
+    // dropping them (the human inspection surface is never gated).
+    const annotateDisabled = (name) => options.gate !== undefined && isServerDisabled(serverOfToolName(name, options.prefix), options.gate)
+        ? `${name} ⏸`
+        : name;
+    const lines = [
+        `mcp-adapter configuration (read-only)`,
+        '',
+        `prefix            ${JSON.stringify(options.prefix)} — matches ${candidates.length} tool(s) in this scope`,
+        `descriptionLimit  ${options.descriptionLimit}`,
+        '',
+        `keep patterns (kept native in the prompt): ${options.keep.length}`,
+    ];
+    if (options.keep.length === 0) {
+        lines.push('  (empty — no tool is held back by name)');
+    }
+    for (const pattern of options.keep) {
+        const hits = candidates.filter(schema => matchesKeep(schema.name, [pattern]));
+        lines.push(`  - ${pattern}`, hits.length === 0 ? '      (no matching tools)' : `      matches: ${hits.map(schema => annotateDisabled(schema.name)).join(', ')}`);
+    }
+    lines.push('', `servers whitelist (fold/catalog/dispatch boundary): ${servers.length}`);
+    if (servers.length === 0) {
+        lines.push('  (empty — no filtering; every prefix-matching server folds)');
+    }
+    for (const server of servers) {
+        const hits = candidates.filter(schema => serverOfToolName(schema.name, options.prefix) === server);
+        lines.push(`  - ${server}`, hits.length === 0 ? '      (no matching tools)' : `      tools: ${hits.map(schema => annotateDisabled(schema.name)).join(', ')}`);
+    }
+    // Persistent gate inventory — only meaningful with a live settings-backed
+    // snapshot, so absent snapshots keep the legacy output untouched.
+    if (options.gate !== undefined) {
+        const mapped = Object.entries(options.gate.serverIds).sort((left, right) => left[1] - right[1]);
+        lines.push('', 'persistent enable/disable (stable ids; survives restarts):');
+        if (mapped.length === 0) {
+            lines.push('  (no servers observed yet — ids appear the first time "/mcp" sees them)');
+        }
+        for (const [server, id] of mapped) {
+            lines.push(isServerDisabled(server, options.gate)
+                ? `  - [${id}] ${server} ⏸ disabled`
+                : `  - [${id}] ${server}`);
+        }
+        const idCapNotice = renderIdCapNotice(options.unassignedServers);
+        if (idCapNotice !== undefined)
+            lines.push('', idCapNotice);
+    }
+    return capRenderedLines(lines.join('\n'));
+}
+/**
+ * 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 async function executeMcpCommand(view) {
+    const parsed = parseMcpCommandInput(view.rawInput);
+    const { config } = view;
+    // Toggle-free fast path: usage needs neither ids nor persistence.
+    if (parsed.form === 'usage')
+        return { kind: 'error', text: MCP_COMMAND_USAGE };
+    // Stable-id observation point: whatever this invocation can see gets its
+    // persistent id now (only when gating is actually wired). Failures keep the
+    // local assignment for this render and simply re-run deterministically.
+    // Servers that fit no free id travel with the view instead — the views
+    // label the exhausted cap, since a toggle cannot target an idless server.
+    let effectiveView = view;
+    let registry;
+    if (view.gate !== undefined && view.writeGate !== undefined) {
+        const allocation = allocateMissingServerIds(view.gate, liveServerNames(view.schemas, config));
+        registry = allocation.registry;
+        if (allocation.added.length > 0) {
+            try {
+                // The allocation write races the invocation signal like a toggle
+                // write: an aborted caller stops waiting while the background write
+                // still lands (re-allocation is deterministic anyway).
+                await raceWriteAck(view.writeGate(registry), view.signal);
+            }
+            catch {
+                // Persistence failures must not block a status query.
+            }
+        }
+        effectiveView = {
+            ...view,
+            config: { ...config, gate: registry, unassignedServers: allocation.unassigned },
+        };
+    }
+    switch (parsed.form) {
+        case 'overview':
+            return { kind: 'success', text: renderMcpOverview(effectiveView.schemas, effectiveView.config, effectiveView.metaToolsLive) };
+        case 'detail': {
+            const rendered = renderMcpDetail(parsed.name, effectiveView.schemas, effectiveView.config);
+            return { kind: rendered.outcome === 'unknown' ? 'error' : 'success', text: rendered.text };
+        }
+        case 'config':
+            return { kind: 'success', text: renderMcpConfig(effectiveView.schemas, effectiveView.config) };
+        case 'disable':
+        case 'enable':
+            return runServerToggle(parsed.form, parsed.id, registry, effectiveView);
+    }
+}
+/** Sentinel returned by {@link raceWriteAck} when the caller's WAIT was cut
+ * short by the invocation signal (the write itself keeps running). */
+const WRITE_ABANDONED = Symbol('mcp-adapter.write-abandoned');
+/**
+ * Await one persistence write, giving up the wait as soon as `signal` aborts.
+ * The losing write keeps running in the background — `Promise.race` only
+ * cancels the waiting, never the work — and the raced promise is subscribed
+ * either way, so a late background failure cannot surface as unhandled.
+ */
+async function raceWriteAck(write, signal) {
+    if (signal === undefined)
+        return write;
+    // An already-aborted caller must not see a raced write win the settlement
+    // race merely by subscription order: report abandonment outright and keep
+    // the background write's failure non-fatal.
+    if (signal.aborted) {
+        write.catch(() => { });
+        return WRITE_ABANDONED;
+    }
+    let onAbort;
+    const abandoned = new Promise(resolve => {
+        if (signal.aborted)
+            resolve(WRITE_ABANDONED);
+        else {
+            onAbort = () => resolve(WRITE_ABANDONED);
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+    try {
+        return await Promise.race([write, abandoned]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+/** Execute one validated /mcp disable|enable against the ensured registry. */
+async function runServerToggle(form, id, registry, view) {
+    const wantDisable = form === 'disable';
+    if (registry === undefined || view.writeGate === undefined) {
+        return {
+            kind: 'error',
+            text: `"/mcp ${form}" needs the dsh settings service to persist server state, `
+                + 'and it is not composed in this process',
+        };
+    }
+    const liveServers = new Set(liveServerNames(view.schemas, view.config));
+    const server = serverNameById(registry, id);
+    if (server === undefined || !liveServers.has(server)) {
+        const why = server === undefined
+            ? `no live MCP server carries id ${id}`
+            : `"${server}" carries id ${id} but has no visible tools in this scope right now`;
+        return { kind: 'error', text: `${why} — run "/mcp" for the assigned ids\n\n${MCP_COMMAND_USAGE}` };
+    }
+    const toggle = setServerDisabledState(registry, server, wantDisable);
+    if (!toggle.changed) {
+        return {
+            kind: 'success',
+            text: wantDisable
+                ? `server "${server}" (id ${id}) is already disabled — nothing changed ("/mcp enable ${id}" restores it)`
+                : `server "${server}" (id ${id}) is not disabled — nothing changed`,
+        };
+    }
+    try {
+        const settled = await raceWriteAck(view.writeGate(toggle.registry), view.signal);
+        if (settled === WRITE_ABANDONED) {
+            // The signal cut only the WAIT; the write keeps running to completion.
+            return {
+                kind: 'error',
+                text: `"/mcp ${form} ${id}" — persist interrupted before confirming; rerun \`/mcp config\` to check the actual state`,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            kind: 'error',
+            text: `"/mcp ${form} ${id}" could not be persisted: ${error instanceof Error ? error.message : String(error)} — state unchanged`,
+        };
+    }
+    return {
+        kind: 'success',
+        text: wantDisable
+            ? `server "${server}" (id ${id}) disabled — its tools fold out of every prompt until "/mcp enable ${id}"`
+            : `server "${server}" (id ${id}) enabled — back to normal folding/catalog/dispatch under the same id`,
+    };
+}
 /**
  * Whether a value is this plugin's structured-error wrap (single `error`
  * string key) — rendered as plain text, never delegated to a child.
@@ -520,7 +1219,7 @@ export function createMcpListTool(options, listSchemas) {
             const query = normalizeMcpListArgs(args);
             // The calling agent's view: restricted-away tools stay out of the catalog.
             const schemas = listSchemas(exec.agent);
-            return Promise.resolve(buildMcpListResult(query, schemas, options));
+            return Promise.resolve(buildMcpListResult(query, schemas, options, options.getGate?.()));
         },
     };
 }
@@ -530,9 +1229,13 @@ export function createMcpListTool(options, 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 function createMcpCallTool(prefix, resolve, servers = []) {
+export function createMcpCallTool(prefix, resolve, servers = [], getGate) {
     return {
         name: MCP_CALL_TOOL_NAME,
         description: [
@@ -559,7 +1262,7 @@ export function createMcpCallTool(prefix, resolve, servers = []) {
             schema: {},
             render: (args, value) => renderDispatched(args, value, name => resolve(name)),
         },
-        execute: (args, exec) => dispatchMcpCall(args, prefix, name => resolve(name, exec.agent), exec, servers),
+        execute: (args, exec) => dispatchMcpCall(args, prefix, name => resolve(name, exec.agent), exec, servers, getGate?.()),
         // Restore child-owned projections (image attachments): the registry
         // invokes THIS definition's finalizer, so it must forward to the child's
         // with the same exec object dispatch passed to child.execute.
@@ -574,6 +1277,18 @@ export function createMcpCallTool(prefix, resolve, servers = []) {
  * 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.
  */
@@ -588,8 +1303,53 @@ export function apply(ctx, config) {
         descriptionLimit: config.descriptionLimit,
         servers: config.servers,
     };
-    const listDefinition = createMcpListTool(listOptions, scope => ctx.tools.schemas(scope));
-    const callDefinition = createMcpCallTool(config.prefix, (name, scope) => ctx.tools.get(name, scope), config.servers);
+    // Optional settings consumption (the canonical inject-scoped pattern): the
+    // registration rides its own child fiber, so disposing it removes exactly
+    // the namespace. Late binding over `settingsScope` means the meta-tools,
+    // waterfall, and command created below observe the mount whenever it lands.
+    let settingsScope;
+    if (typeof ctx.inject === 'function') {
+        ctx.inject(['settings'], (sctx) => {
+            settingsScope = sctx.settings.register(MCP_ADAPTER_SETTINGS_NAMESPACE, SERVER_ID_REGISTRY_SCHEMA);
+            return () => { settingsScope = undefined; };
+        });
+    }
+    // One-shot latch: a persistently broken settings provider would otherwise
+    // re-warn on EVERY assembled prompt (getGate runs per waterfall execution).
+    let gateReadWarned = false;
+    // Fresh snapshot per read; normalize guards hand-edited documents. The
+    // scope being absent is distinguishable from an empty section: undefined
+    // propagates so toggle commands can name their missing dependency.
+    const getGate = () => {
+        const scope = settingsScope;
+        if (scope === undefined)
+            return undefined;
+        try {
+            return normalizeServerGate(scope.get());
+        }
+        catch (error) {
+            // Fail-open, hard requirement: a throwing read must never blow up the
+            // system-prompt/assemble waterfall or a /mcp invocation. Gate-less
+            // means every server counts as enabled — visibility only ever grows.
+            if (!gateReadWarned) {
+                gateReadWarned = true;
+                ctx.logger.warn(`mcp-adapter: reading the persisted enable/disable state failed `
+                    + `(${error instanceof Error ? error.message : String(error)}) `
+                    + '— treating every server as enabled');
+            }
+            return undefined;
+        }
+    };
+    const writeGate = async (next) => {
+        const scope = settingsScope;
+        if (scope === undefined)
+            throw new Error('settings service went away before the write');
+        // Wholesale replace (not update): we always hold the complete next
+        // section, and replace cannot merge stale keys back under us.
+        await scope.replace({ serverIds: { ...next.serverIds }, disabled: [...next.disabled] });
+    };
+    const listDefinition = createMcpListTool({ ...listOptions, getGate }, scope => ctx.tools.schemas(scope));
+    const callDefinition = createMcpCallTool(config.prefix, (name, scope) => ctx.tools.get(name, scope), config.servers, getGate);
     const disposers = [];
     try {
         disposers.push(ctx.tools.register(listDefinition));
@@ -617,7 +1377,74 @@ export function apply(ctx, config) {
         // missing, shadowed, or foreign `mcp_list`/`mcp_call` means passthrough.
         const metaToolsLive = ctx.tools.get(MCP_LIST_TOOL_NAME, context.scope) === listDefinition
             && ctx.tools.get(MCP_CALL_TOOL_NAME, context.scope) === callDefinition;
-        return foldPromptAssembly(assembled, foldOptions, metaToolsLive);
+        return foldPromptAssembly(assembled, foldOptions, metaToolsLive, getGate());
     });
+    // Status + server toggles on the platform command service (visible in TUI
+    // completion and web slash panels). The service is mounted SOFTLY: unlike
+    // a static `inject` entry, an absent commands service only costs the
+    // command — the meta-tools, waterfall, and gating load regardless.
+    if (typeof ctx.inject !== 'function') {
+        ctx.logger.warn(`mcp-adapter: context cannot inject services — "/${MCP_COMMAND_NAME}" is unavailable; `
+            + 'folding and meta-tools keep working');
+    }
+    else {
+        let mounted = false;
+        // Deferred so a callback that fires synchronously (services already
+        // present) does not trip over the not-yet-assigned handle.
+        let mountCheck;
+        ctx.inject(['commands'], (ccmds) => {
+            mounted = true;
+            if (mountCheck !== undefined)
+                clearTimeout(mountCheck);
+            try {
+                const commandDisposer = ccmds.commands.register({
+                    name: MCP_COMMAND_NAME,
+                    description: 'Show MCP status; disable/enable MCP servers',
+                    input: { hint: '[list [server|tool] | config | disable <id> | enable <id>]' },
+                    handler: invocation => {
+                        // The receiving agent's restricted view; an absent agent degrades to
+                        // the global registry view (`schemas()` without scope).
+                        const scope = invocation.agent ?? undefined;
+                        const schemas = ctx.tools.schemas(scope);
+                        const metaToolsLive = ctx.tools.get(MCP_LIST_TOOL_NAME, scope) === listDefinition
+                            && ctx.tools.get(MCP_CALL_TOOL_NAME, scope) === callDefinition;
+                        // ONE snapshot per execution keeps config.gate and view.gate identical.
+                        const gate = getGate();
+                        return executeMcpCommand({
+                            rawInput: invocation.rawInput,
+                            schemas,
+                            config: {
+                                prefix: config.prefix,
+                                keep: config.keep,
+                                servers: config.servers,
+                                descriptionLimit: config.descriptionLimit,
+                                gate,
+                            },
+                            metaToolsLive,
+                            gate,
+                            signal: invocation.signal,
+                            writeGate,
+                        });
+                    },
+                });
+                // Disposing the injected fiber disposes exactly this registration;
+                // if the service restarts, cordis re-runs this callback and a fresh
+                // registration takes its place.
+                return () => commandDisposer();
+            }
+            catch (error) {
+                ccmds.logger.warn(`mcp-adapter: "/${MCP_COMMAND_NAME}" command registration failed `
+                    + `(${error instanceof Error ? error.message : String(error)}) — meta-tools keep working`);
+            }
+        });
+        // One heads-up for hosts that genuinely never compose the commands
+        // service; cancelled by the mount above whenever it lands.
+        mountCheck = setTimeout(() => {
+            if (!mounted) {
+                ctx.logger.warn(`mcp-adapter: no platform commands service — "/${MCP_COMMAND_NAME}" is unavailable; `
+                    + 'folding and meta-tools keep working');
+            }
+        }, 0);
+    }
 }
 //# sourceMappingURL=index.js.map