@dsh-cc/mcp-client 0.5.0

package/lib/prompts.js

@@ -0,0 +1,166 @@
+/**
+ * Prompt bridge: exposes an MCP server's `prompts` capability to the model as
+ * discoverable skills on the `ctx.skills` registry, one runtime skill per MCP
+ * prompt, when the server declares the capability.
+ *
+ * The harness's skill registry enforces a lowercase-kebab name grammar
+ * (`[a-z0-9]+(?:-[a-z0-9]+)*`), which `mcp__<server>__<prompt>` (with its
+ * double underscores) cannot satisfy. Names are therefore mapped to kebab-case
+ * (`mcp-<server>-<prompt>`); see {@link promptSkillName}. The body is the
+ * prompt's rendered text (or, for prompts that require arguments, the argument
+ * contract) — plain prose only. MCP-sourced skills must never embed or invoke
+ * shell; the body is always inert text.
+ *
+ * @module
+ */
+import { GetPromptRequestSchema, ListPromptsResultSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { isSkillName } from '@deepseek-ai/dsh-skill';
+/**
+ * Map an MCP prompt identity to a registry-valid skill name. The registry's
+ * grammar rejects underscores, so the `mcp__<server>__<prompt>` shape becomes
+ * lowercase kebab-case: non-alphanumeric runs collapse to single dashes, and a
+ * leading `mcp` prefix is guaranteed. Distinct identities may rarely collapse;
+ * the first registration wins and later duplicates log a registry warning.
+ *
+ * @param serverName - MCP server namespace.
+ * @param promptName - the MCP prompt's own name.
+ * @returns a valid lowercase-kebab skill name.
+ */
+export function promptSkillName(serverName, promptName) {
+    const raw = `mcp-${serverName}-${promptName}`;
+    const kebab = raw.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (kebab.length === 0)
+        return 'mcp';
+    return kebab;
+}
+/** Whether an MCP prompt can be fetched without arguments. */
+function argumentless(prompt) {
+    return (prompt.arguments ?? []).every(a => a.required !== true);
+}
+/**
+ * Render an MCP prompt's messages into plain text. Each message's content block
+ * contributes its text; non-text blocks become a short marker. The output is
+ * inert prose — never executable code.
+ *
+ * @param messages - the prompt's message list from `prompts/get`.
+ * @returns the joined prompt body.
+ */
+function renderMessages(messages) {
+    const list = Array.isArray(messages) ? messages : [];
+    const parts = [];
+    for (const message of list) {
+        const record = message;
+        const role = record?.role ?? 'user';
+        const content = record?.content;
+        parts.push(renderBlock(content, role));
+    }
+    return parts.filter(p => p.length > 0).join('\n');
+}
+/** Render one content block (array or single) to text. */
+function renderBlock(content, role) {
+    const blocks = Array.isArray(content) ? content : [content];
+    const text = [];
+    for (const block of blocks) {
+        if (block === null || typeof block !== 'object') {
+            text.push('[unsupported prompt content]');
+            continue;
+        }
+        const item = block;
+        if (item.type === 'text' && item.text !== undefined)
+            text.push(item.text);
+        else if (item.type === 'text')
+            text.push('');
+        else if (item.type === 'image')
+            text.push('[image content]');
+        else
+            text.push(`[${item.type ?? 'unsupported'} content]`);
+    }
+    const joined = text.join('');
+    if (joined.length === 0)
+        return `[${role} message, no text]`;
+    return `${role === 'user' ? 'User' : 'Assistant'}: ${joined}`;
+}
+/**
+ * Load one MCP prompt body. Argumentless prompts are resolved via `prompts/get`
+ * and their rendered text becomes the skill body. Prompts requiring arguments
+ * cannot be fetched on demand (there is no prompt-call tool); their body
+ * documents the prompt and its argument contract instead, in prose.
+ *
+ * @param client - connected MCP client.
+ * @param prompt - the MCP prompt to load.
+ * @returns the skill body text.
+ */
+async function loadPromptBody(client, prompt) {
+    if (argumentless(prompt)) {
+        try {
+            const result = await client.request({ method: 'prompts/get', params: { name: prompt.name } }, GetPromptRequestSchema);
+            return renderMessages(result.messages);
+        }
+        catch {
+            // Fall through to the static contract below on a get failure.
+        }
+    }
+    const args = (prompt.arguments ?? []).map((a) => {
+        const required = a.required === true ? ' (required)' : '';
+        return `- ${a.name}${required}${a.description !== undefined ? ': ' + a.description : ''}`;
+    });
+    const flag = (prompt.arguments ?? []).length > 0
+        ? `\n\nThis MCP prompt requires the following arguments:\n${args.join('\n')}`
+        : '';
+    const description = prompt.description !== undefined && prompt.description.length > 0
+        ? `${prompt.description}\n\n`
+        : '';
+    return `${description}This is an MCP prompt named "${prompt.name}"${flag}. The model should use it to structure its response.`;
+}
+/**
+ * Register one skill per MCP prompt for a server on `ctx.skills`. Runs only
+ * when the server declared the `prompts` capability. Registering requires the
+ * `ctx.skills` service; when it is absent this is a no-op (the harness offers
+ * no prompt surface for that server).
+ *
+ * @param client - connected MCP client used to load prompt bodies.
+ * @param ctx - Cordis context; `ctx.skills` is read optionally.
+ * @param serverName - server namespace used to derive skill names.
+ * @returns disposers for every registered skill (never rejects).
+ */
+export async function syncPrompts(client, ctx, serverName) {
+    const skills = ctx.get('skills');
+    const disposers = new Map();
+    if (skills === undefined)
+        return disposers;
+    const prompts = [];
+    let cursor;
+    try {
+        do {
+            const page = await client.request({ method: 'prompts/list', ...cursor === undefined ? {} : { params: { cursor } } }, ListPromptsResultSchema);
+            prompts.push(...page.prompts);
+            cursor = page.nextCursor;
+        } while (cursor !== undefined);
+    }
+    catch (error) {
+        ctx.logger.warn(`mcp-client(${serverName}): prompts/list failed, no prompts registered: ${String(error)}`);
+        return disposers;
+    }
+    for (const prompt of prompts) {
+        const name = promptSkillName(serverName, prompt.name);
+        if (!isSkillName(name) || disposers.has(name))
+            continue;
+        const body = await loadPromptBody(client, prompt);
+        if (body.length === 0)
+            continue;
+        try {
+            const definition = {
+                name,
+                description: prompt.description ?? `MCP prompt "${prompt.name}" from server "${serverName}"`,
+                source: 'runtime',
+                content: body,
+            };
+            disposers.set(name, skills.register(definition));
+        }
+        catch (error) {
+            ctx.logger.warn(`mcp-client(${serverName}): could not register prompt skill "${name}": ${String(error)}`);
+        }
+    }
+    return disposers;
+}
+//# sourceMappingURL=prompts.js.map

package/lib/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"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"}

package/lib/registry.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Central MCP connection registry for the mcp-client package.
+ *
+ * Each mcp-client plugin instance bridges one MCP server, and previously
+ * nothing central could enumerate them. This module defines an optional
+ * `mcpConnections` service that gathers every live instance under one roof so
+ * host plugins (slash commands such as `/mcp`) can list servers, their
+ * connection state, and drive disconnect/reconnect. The service is provided by
+ * mcp-client itself; an instance running standalone provides it lazily, while
+ * instances sharing a scope reuse the first-provided one, so the registry stays
+ * optional (mcp-client keeps working without a consumer).
+ *
+ * @module
+ */
+import { Service, type Context } from '@deepseek-ai/cordis';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The live MCP connection registry, when an mcp-client instance provided it. */
+        mcpConnections: McpConnectionsService;
+    }
+}
+/** The connection lifecycle state of one MCP server instance. */
+export type McpConnectionState = 'connecting' | 'ready' | 'error' | 'disconnected';
+/** A public snapshot of one registered MCP server. */
+export interface McpConnectionEntry {
+    /** The mcp-client `serverName` this instance bridges. */
+    name: string;
+    /** Current connection lifecycle state. */
+    state: McpConnectionState;
+    /** The last error message, when the state is `error`. */
+    error?: string;
+    /** The number of tools this server currently exposes, when known. */
+    toolCount?: number;
+    /** Number of tools registered eagerly (including resource-bridge tools), when known. */
+    eagerCount?: number;
+    /** Number of tools registered deferred (hidden until ToolSearch activation), when known. */
+    deferredCount?: number;
+    /** Whether interacting with this server requires OAuth authorization. */
+    authRequired?: boolean;
+}
+/** Per-instance control surface the owning mcp-client plugin wires to its supervisor. */
+export interface McpConnectionControl {
+    /** Stop the current connection and unregister its tools; the entry is marked `disconnected`. */
+    disconnect(): Promise<void>;
+    /** Tear down the current connection and establish a fresh one; the entry is marked `connecting` then `ready`/`error`. */
+    reconnect(): Promise<void>;
+}
+/** The `mcpConnections` service: enumerate and drive the registered MCP servers. */
+export declare class McpConnectionsService extends Service {
+    /** Live instances keyed by `serverName`. */
+    private readonly managed;
+    constructor(ctx: Context);
+    /**
+     * Register a live mcp-client instance's control surface, initially `connecting`.
+     * @param name - the instance `serverName`.
+     * @param control - the disconnect/reconnect control the instance wires.
+     * @throws when `name` is already registered (a live duplicate is a config error).
+     */
+    register(name: string, control: McpConnectionControl, authRequired?: boolean): void;
+    /** Remove an instance (on teardown / full disconnect). */
+    unregister(name: string): void;
+    /** Report a lifecycle transition for a registered instance. */
+    report(name: string, state: McpConnectionState, info?: {
+        error?: string;
+    }): void;
+    /** Record the current tool count for a registered instance. */
+    setToolCount(name: string, toolCount: number): void;
+    /**
+     * Record the eager/deferred tool breakdown for a registered instance.
+     * Also overwrites `toolCount` with `eager + deferred`, keeping the
+     * invariant `eagerCount + deferredCount === toolCount`.
+     */
+    setToolBreakdown(name: string, breakdown: {
+        eager: number;
+        deferred: number;
+    }): void;
+    /** A snapshot of every registered server today. */
+    entries(): McpConnectionEntry[];
+    /**
+     * Disconnect a registered server: stop its connection and unregister its
+     * tools, leaving the entry marked `disconnected`.
+     * @param name - the instance `serverName`.
+     * @throws when no such server is registered or its control rejects.
+     */
+    disconnect(name: string): Promise<void>;
+    /**
+     * Reconnect a registered server: tear down and establish a fresh connection.
+     * @param name - the instance `serverName`.
+     * @throws when no such server is registered or its control rejects.
+     */
+    reconnect(name: string): Promise<void>;
+    private require;
+}
+//# sourceMappingURL=registry.d.ts.map

package/lib/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,iFAAiF;QACjF,cAAc,EAAE,qBAAqB,CAAA;KACtC;CACF;AAED,iEAAiE;AACjE,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,cAAc,CAAA;AAElF,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,KAAK,EAAE,kBAAkB,CAAA;IACzB,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,yFAAyF;AACzF,MAAM,WAAW,oBAAoB;IACnC,gGAAgG;IAChG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,yHAAyH;IACzH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B;AAQD,oFAAoF;AACpF,qBAAa,qBAAsB,SAAQ,OAAO;IAChD,4CAA4C;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;gBAEzC,GAAG,EAAE,OAAO;IAIxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,IAAI;IAOnF,0DAA0D;IAC1D,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,+DAA+D;IAC/D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IAQpF,+DAA+D;IAC/D,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKnD;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAQpF,mDAAmD;IACnD,OAAO,IAAI,kBAAkB,EAAE;IAI/B;;;;;OAKG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM7C;;;;OAIG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C,OAAO,CAAC,OAAO;CAKhB"}

package/lib/registry.js

@@ -0,0 +1,101 @@
+/**
+ * Central MCP connection registry for the mcp-client package.
+ *
+ * Each mcp-client plugin instance bridges one MCP server, and previously
+ * nothing central could enumerate them. This module defines an optional
+ * `mcpConnections` service that gathers every live instance under one roof so
+ * host plugins (slash commands such as `/mcp`) can list servers, their
+ * connection state, and drive disconnect/reconnect. The service is provided by
+ * mcp-client itself; an instance running standalone provides it lazily, while
+ * instances sharing a scope reuse the first-provided one, so the registry stays
+ * optional (mcp-client keeps working without a consumer).
+ *
+ * @module
+ */
+import { Service } from '@deepseek-ai/cordis';
+/** The `mcpConnections` service: enumerate and drive the registered MCP servers. */
+export class McpConnectionsService extends Service {
+    /** Live instances keyed by `serverName`. */
+    managed = new Map();
+    constructor(ctx) {
+        super(ctx, 'mcpConnections');
+    }
+    /**
+     * Register a live mcp-client instance's control surface, initially `connecting`.
+     * @param name - the instance `serverName`.
+     * @param control - the disconnect/reconnect control the instance wires.
+     * @throws when `name` is already registered (a live duplicate is a config error).
+     */
+    register(name, control, authRequired) {
+        if (this.managed.has(name)) {
+            throw new Error(`mcpConnections: server "${name}" is already registered by another mcp-client instance`);
+        }
+        this.managed.set(name, { entry: { name, state: 'connecting', ...authRequired === undefined ? {} : { authRequired } }, control });
+    }
+    /** Remove an instance (on teardown / full disconnect). */
+    unregister(name) {
+        this.managed.delete(name);
+    }
+    /** Report a lifecycle transition for a registered instance. */
+    report(name, state, info = {}) {
+        const managed = this.managed.get(name);
+        if (!managed)
+            return;
+        managed.entry.state = state;
+        if (info.error !== undefined)
+            managed.entry.error = info.error;
+        if (state === 'ready' || state === 'connecting')
+            delete managed.entry.error;
+    }
+    /** Record the current tool count for a registered instance. */
+    setToolCount(name, toolCount) {
+        const managed = this.managed.get(name);
+        if (managed)
+            managed.entry.toolCount = toolCount;
+    }
+    /**
+     * Record the eager/deferred tool breakdown for a registered instance.
+     * Also overwrites `toolCount` with `eager + deferred`, keeping the
+     * invariant `eagerCount + deferredCount === toolCount`.
+     */
+    setToolBreakdown(name, breakdown) {
+        const managed = this.managed.get(name);
+        if (!managed)
+            return;
+        managed.entry.eagerCount = breakdown.eager;
+        managed.entry.deferredCount = breakdown.deferred;
+        managed.entry.toolCount = breakdown.eager + breakdown.deferred;
+    }
+    /** A snapshot of every registered server today. */
+    entries() {
+        return Array.from(this.managed.values()).map(({ entry }) => ({ ...entry }));
+    }
+    /**
+     * Disconnect a registered server: stop its connection and unregister its
+     * tools, leaving the entry marked `disconnected`.
+     * @param name - the instance `serverName`.
+     * @throws when no such server is registered or its control rejects.
+     */
+    async disconnect(name) {
+        const managed = this.require(name);
+        await managed.control.disconnect();
+        this.report(name, 'disconnected');
+    }
+    /**
+     * Reconnect a registered server: tear down and establish a fresh connection.
+     * @param name - the instance `serverName`.
+     * @throws when no such server is registered or its control rejects.
+     */
+    async reconnect(name) {
+        const managed = this.require(name);
+        this.report(name, 'connecting');
+        await managed.control.reconnect();
+    }
+    require(name) {
+        const managed = this.managed.get(name);
+        if (!managed)
+            throw new Error(`mcpConnections: no server "${name}" is registered`);
+        return managed;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/lib/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}

package/lib/resources.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resource bridge: exposes an MCP server's `resources` capability to the model
+ * as two model tools when the server declares the capability and every other
+ * pathway is unavailable.
+ *
+ * The preferred seam for read-only resources is a filesystem Provider, but the
+ * `ctx.fs` seam abstracts *real* filesystems over `FsTarget` / `processPath` /
+ * `readBytes` — it cannot represent virtual MCP resources (arbitrary URIs with
+ * server-owned contents). So this module registers the next best fallback: two
+ * server-qualified model tools, `mcp__<server>__list_mcp_resources` and
+ * `mcp__<server>__read_mcp_resource`, that call `resources/list` and
+ * `resources/read`. They share the tool-generation disposer map so disconnect
+ * and re-sync unregister them together.
+ *
+ * @module
+ */
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Context } from '@deepseek-ai/cordis';
+import type { JsonValue } from '@dsh-cc/tools';
+/** Registered disposers for the two resource bridges; shared shape with tools. */
+export type ResourceDisposers = Map<string, () => void>;
+/**
+ * Register the two resource bridge tools on `ctx.tools` if they are not already
+ * present. Registration conflicts (a server tool already owning the public
+ * name) are contained and logged; the bridge should never shadow another tool.
+ *
+ * @param client - connected MCP client.
+ * @param ctx - Cordis context providing the `tools` registry.
+ * @param serverName - server namespace for the public tool names.
+ * @returns the registered disposers (empty when the bridge could not register).
+ */
+export declare function syncResources(client: Client, ctx: Context, serverName: string): ResourceDisposers;
+/**
+ * Public name for one resource bridge tool under a server's namespace.
+ * @param serverName - server namespace.
+ * @param kind - `list_mcp_resources` or `read_mcp_resource`.
+ * @returns the model-facing tool name `mcp__<serverName>__<kind>`.
+ */
+export declare function resourcePublicName(serverName: string, kind: string): string;
+/** Re-exported canonically for callers that want the URL type. */
+export type { JsonValue };
+//# sourceMappingURL=resources.d.ts.map

package/lib/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAKvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,CAAC,CAAA;AAmBvD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,OAAO,EACZ,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAgBnB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E;AAyED,kEAAkE;AAClE,YAAY,EAAE,SAAS,EAAE,CAAA"}

package/lib/resources.js

@@ -0,0 +1,136 @@
+/**
+ * Resource bridge: exposes an MCP server's `resources` capability to the model
+ * as two model tools when the server declares the capability and every other
+ * pathway is unavailable.
+ *
+ * The preferred seam for read-only resources is a filesystem Provider, but the
+ * `ctx.fs` seam abstracts *real* filesystems over `FsTarget` / `processPath` /
+ * `readBytes` — it cannot represent virtual MCP resources (arbitrary URIs with
+ * server-owned contents). So this module registers the next best fallback: two
+ * server-qualified model tools, `mcp__<server>__list_mcp_resources` and
+ * `mcp__<server>__read_mcp_resource`, that call `resources/list` and
+ * `resources/read`. They share the tool-generation disposer map so disconnect
+ * and re-sync unregister them together.
+ *
+ * @module
+ */
+import { ListResourcesResultSchema, ReadResourceResultSchema, } from '@modelcontextprotocol/sdk/types.js';
+/** List a page without the SDK's per-page output-validator cache. */
+function listResourcesUncached(client, cursor) {
+    return client.request({ method: 'resources/list', ...cursor === undefined ? {} : { params: { cursor } } }, ListResourcesResultSchema);
+}
+/** Read one resource without the SDK's per-page output-validator cache. */
+function readResourceUncached(client, uri, signal) {
+    return client.request({ method: 'resources/read', params: { uri } }, ReadResourceResultSchema, signal === undefined ? {} : { signal });
+}
+/**
+ * Register the two resource bridge tools on `ctx.tools` if they are not already
+ * present. Registration conflicts (a server tool already owning the public
+ * name) are contained and logged; the bridge should never shadow another tool.
+ *
+ * @param client - connected MCP client.
+ * @param ctx - Cordis context providing the `tools` registry.
+ * @param serverName - server namespace for the public tool names.
+ * @returns the registered disposers (empty when the bridge could not register).
+ */
+export function syncResources(client, ctx, serverName) {
+    const listPublicName = resourcePublicName(serverName, 'list_mcp_resources');
+    const readPublicName = resourcePublicName(serverName, 'read_mcp_resource');
+    const disposers = new Map();
+    const registrations = [
+        { publicName: listPublicName, definition: listDefinition(listPublicName, client, serverName) },
+        { publicName: readPublicName, definition: readDefinition(readPublicName, client) },
+    ];
+    for (const { publicName, definition } of registrations) {
+        try {
+            disposers.set(publicName, ctx.tools.register(definition));
+        }
+        catch (error) {
+            ctx.logger.warn(`mcp-client(${serverName}): resource bridge "${publicName}" could not register: ${String(error)}`);
+        }
+    }
+    return disposers;
+}
+/**
+ * Public name for one resource bridge tool under a server's namespace.
+ * @param serverName - server namespace.
+ * @param kind - `list_mcp_resources` or `read_mcp_resource`.
+ * @returns the model-facing tool name `mcp__<serverName>__<kind>`.
+ */
+export function resourcePublicName(serverName, kind) {
+    return `mcp__${serverName}__${kind}`;
+}
+/** ToolDefinition for `resources_list`: enumerate the server's resources. */
+function listDefinition(publicName, client, serverName) {
+    return {
+        name: publicName,
+        description: `List the resources exposed by the MCP server "${serverName}".`,
+        parameters: {
+            type: 'object',
+            properties: {},
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        execute: async () => {
+            const parts = [];
+            let cursor;
+            do {
+                const page = await listResourcesUncached(client, cursor);
+                for (const r of page.resources) {
+                    parts.push({
+                        uri: r.uri,
+                        name: r.name,
+                        ...r.description !== undefined ? { description: r.description } : {},
+                    });
+                }
+                cursor = page.nextCursor;
+            } while (cursor);
+            if (parts.length === 0)
+                return '(no resources)';
+            return parts.map(r => `${r.uri}${r.name !== undefined ? ' — ' + r.name : ''}`).join('\n');
+        },
+    };
+}
+/** ToolDefinition for `resources_read`: read one resource by URI. */
+function readDefinition(publicName, client) {
+    return {
+        name: publicName,
+        description: 'Read the contents of one MCP resource by its URI.',
+        parameters: {
+            type: 'object',
+            properties: {
+                uri: { type: 'string', description: 'The resource URI to read.' },
+            },
+            required: ['uri'],
+        },
+        output: {
+            schema: { type: 'string' },
+            render: (_args, value) => [{ type: 'text', text: value }],
+        },
+        execute: async (args, exec) => {
+            const params = (typeof args === 'object' && args !== null ? args : {});
+            const uri = typeof params.uri === 'string' ? params.uri : '';
+            if (uri === '')
+                throw new Error('read_mcp_resource requires a "uri" argument');
+            const result = await readResourceUncached(client, uri, exec.signal);
+            const contents = [];
+            for (const block of result.contents) {
+                // A resource content block is either text-shaped or blob-shaped.
+                const item = block;
+                if (item.text !== undefined) {
+                    contents.push(item.text);
+                }
+                else if (item.blob !== undefined) {
+                    contents.push(`[binary blob resource: ${item.uri ?? 'unknown'}]`);
+                }
+                else {
+                    contents.push('[unsupported resource content]');
+                }
+            }
+            return contents.join('\n') || '(resource returned no contents)';
+        },
+    };
+}
+//# sourceMappingURL=resources.js.map

package/lib/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}

package/lib/stdio-stderr.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Capture stdio MCP server stderr so it cannot inherit the parent TTY.
+ * SDK default is `stderr: 'inherit'`; piping is mandatory for a TUI host.
+ *
+ * @module
+ */
+import type { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+/** Ring capacity for the in-memory tail used in connection-failure warns. */
+export declare const STDERR_TAIL_CAPACITY: number;
+/** Max characters of that tail embedded in a single-line `ctx.logger.warn`. */
+export declare const STDERR_WARN_CAPACITY = 1024;
+/** Default size cap for the stdio stderr log; ONE backup generation is kept. */
+export declare const STDIO_LOG_MAX_BYTES: number;
+/**
+ * Append-only ring of the newest `capacity` characters. Used so a noisy
+ * server cannot grow memory without bound while still leaving a crash banner
+ * for the supervisor's warn line.
+ */
+export declare class BoundedTail {
+    private readonly capacity;
+    private buffer;
+    constructor(capacity: number);
+    push(chunk: string): void;
+    snapshot(): string;
+}
+/**
+ * Last ≤1 KB of a captured tail, newlines collapsed, for a one-line logger.
+ * @returns `undefined` when the tail is empty so callers can omit the suffix.
+ */
+export declare function formatStdioStderrForWarn(tail: string): string | undefined;
+/** Snapshot of the ring attached to `transport`, or `''` when none. */
+export declare function stdioStderrTail(transport: Transport): string;
+/**
+ * Pipe `transport.stderr`, drain into a 4 KB ring, and append raw bytes to
+ * `$DSH_HOME/mcp-logs/<serverName>.log` (or `logDir` when given), rotating at
+ * `maxBytes` (default {@link STDIO_LOG_MAX_BYTES}; `maxBytes <= 0` disables)
+ * into a single `<serverName>.log.1` backup generation, both at open time and
+ * mid-stream.
+ *
+ * Must run before `start()`: SDK 1.29 creates the PassThrough in the
+ * constructor when `stderr: 'pipe'`. An undrained pipe back-pressures the
+ * child until it blocks in `write(2)`.
+ *
+ * No-ops when `stderr` is missing so `vi.fn()` SDK mocks stay constructible.
+ *
+ * ponytail: rotation is size-based with one backup generation (the previous
+ * `.log.1` is discarded on each rotation); concurrent dsh-cc sessions sharing
+ * a serverName may interleave (session header marks each generation);
+ * WriteStream buffer grows if the disk stalls — log must never block MCP.
+ * Documented rotation edges: (a) bytes buffered in the old stream at rotation
+ * time flush into `.log.1` after the rename — a crash between rename and
+ * flush loses at most one stream buffer; (b) another session holding the
+ * renamed `.log.1` writes into an anonymous inode whose bytes vanish on
+ * close — worst-case extra disk ≈ maxBytes × live sessions. A failed
+ * rotation rename (e.g. `.log.1` is a directory) sets `rotationDisabled` so
+ * appending cannot become a rename-retry storm per chunk; appending then
+ * grows unbounded, which is exactly the pre-rotation worst case.
+ *
+ * INVARIANT: all rotation fs ops (`statSync`/`renameSync`/`createWriteStream`)
+ * are SYNCHRONOUS and run inside the `data` handler / open path. PassThrough
+ * `data` events cannot interleave, and the `end` handler cannot fire
+ * mid-rotation; async fs here would reintroduce real races.
+ */
+export declare function attachStdioStderrDrain(transport: StdioClientTransport, serverName: string, logDir?: string, maxBytes?: number): void;
+//# sourceMappingURL=stdio-stderr.d.ts.map

package/lib/stdio-stderr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio-stderr.d.ts","sourceRoot":"","sources":["../src/stdio-stderr.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AACrF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAA;AAE9E,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,QAAW,CAAA;AAC5C,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,OAAO,CAAA;AACxC,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,QAAkB,CAAA;AAIlD;;;;GAIG;AACH,qBAAa,WAAW;IAEV,OAAO,CAAC,QAAQ,CAAC,QAAQ;IADrC,OAAO,CAAC,MAAM,CAAK;gBACU,QAAQ,EAAE,MAAM;IAE7C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOzB,QAAQ,IAAI,MAAM;CAGnB;AAUD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMzE;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,oBAAoB,EAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,GAAE,MAA4B,GACrC,IAAI,CAiDN"}