@sammorrowdrums/mcpi-ext 0.2.1 → 1.0.0

package/dist/mcp/client-manager.d.ts

@@ -1,28 +1,48 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { Client, type ReadResourceResult, type Resource, type ResourceTemplateType, type Tool, type Transport } from "@modelcontextprotocol/client";
+import { type DirectoryReadResult, type SkillsGetResult, type SkillsListResult } from "../skills/sep2640/protocol.js";
+import { type TerminalCallToolResult } from "./call-tool-result.js";
+import { type CreateMcpClientOptions, type McpClientDiagnostics, type McpElicitationHandler } from "./client-factory.js";
 import type { McpConfig, ServerConfig } from "./config.js";
-/** An MCP tool as discovered from a server. */
-export interface McpTool {
-    /** Tool name as reported by the server. */
-    name: string;
-    description?: string;
-    /** JSON Schema for the tool's parameters. */
-    inputSchema: Record<string, unknown>;
-    /** JSON Schema for structured output, if declared. */
-    outputSchema?: Record<string, unknown>;
-    /** Tool annotations (readOnlyHint, destructiveHint, etc.). */
-    annotations?: Record<string, unknown>;
+/** A lossless MCP tool as discovered from a server, tagged with its origin. */
+export type McpTool = Tool & {
     /** Which configured server this tool came from. */
     serverName: string;
+};
+export interface McpClientManagerOptions {
+    elicitation?: McpElicitationHandler;
+    clientFactory?: (options: CreateMcpClientOptions) => Client;
+    transportFactory?: (config: ServerConfig) => Transport;
+    /**
+     * Advertise the draft skills extension (SEP-2640) at initialize.
+     *
+     * Off by default; the host turns it on from config. When off, no connection
+     * this manager opens mentions the extension at all.
+     */
+    skillsExtension?: boolean;
 }
 /**
  * Manages connections to multiple MCP servers and aggregates their tools.
  *
- * Tools are discovered and stored internally. They are NOT registered with pi
- * automatically — that responsibility belongs to the access tiers (Skills,
- * Football, Code Mode).
+ * Tools are discovered and stored internally. They are NOT registered with mcpi
+ * automatically — that responsibility belongs to the access tiers.
  */
 export declare class McpClientManager {
-    private connections;
+    private readonly connections;
+    private readonly elicitation;
+    private readonly clientFactory;
+    private readonly transportFactory;
+    private skillsExtensionRequested;
+    constructor(options?: McpClientManagerOptions);
+    /** Whether this manager advertises the draft skills extension. */
+    requestsSkillsExtension(): boolean;
+    /**
+     * Turn the draft skills extension on or off for future connections.
+     *
+     * The host reads the gate from config, which loads after this manager is
+     * constructed. Already-open connections keep whatever they negotiated at
+     * initialize, because the capability set is fixed for a session.
+     */
+    enableSkillsExtension(enabled: boolean): void;
     /**
      * Connect to all servers defined in the config.
      * Connections that fail are logged and skipped — partial success is fine.
@@ -30,6 +50,26 @@ export declare class McpClientManager {
     connectAll(config: McpConfig, log?: (msg: string) => void): Promise<void>;
     /** Connect to a single server by name. */
     connectOne(name: string, serverConfig: ServerConfig, log?: (msg: string) => void): Promise<void>;
+    /** Call a tool and return only its terminal protocol result. */
+    callTool(serverName: string, toolName: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<TerminalCallToolResult>;
+    /** List a server's resources. Discovery only; authorization lives in McpPolicy. */
+    listResources(serverName: string, signal?: AbortSignal): Promise<Resource[]>;
+    /** List a server's resource templates. Authorization lives in McpPolicy. */
+    listResourceTemplates(serverName: string, signal?: AbortSignal): Promise<ResourceTemplateType[]>;
+    /** Read a single resource. Authorization is the caller-side policy's responsibility. */
+    readResource(serverName: string, uri: string, signal?: AbortSignal): Promise<ReadResourceResult>;
+    /**
+     * The settings a server declared for one extension during `initialize`, or
+     * `undefined` if it declared no such extension.
+     */
+    getExtensionCapability(serverName: string, extensionName: string): Record<string, unknown> | undefined;
+    /** Draft SEP-2640 `skills/list`. */
+    requestSkillsList(serverName: string, cursor?: string, signal?: AbortSignal): Promise<SkillsListResult>;
+    /** Draft SEP-2640 `skills/get`. */
+    requestSkillsGet(serverName: string, uri: string, signal?: AbortSignal): Promise<SkillsGetResult>;
+    /** Draft SEP-2640 `resources/directory/read`. */
+    requestDirectoryRead(serverName: string, uri: string, cursor?: string, signal?: AbortSignal): Promise<DirectoryReadResult>;
+    private requestExtension;
     /** Disconnect a single server. */
     disconnectOne(name: string): Promise<void>;
     /** Disconnect all servers. */
@@ -38,9 +78,11 @@ export declare class McpClientManager {
     getTools(): McpTool[];
     /** Get tools from a specific server. */
     getToolsForServer(name: string): McpTool[];
-    /** Get the MCP Client for a specific server (needed to call tools). */
+    /** Get the MCP Client for discovery APIs that are not tool calls. */
     getClient(name: string): Client | undefined;
-    /** List connected server names. */
+    getDiagnostics(name: string): McpClientDiagnostics | undefined;
+    /** List connected server names in deterministic order. */
     getConnectedServers(): string[];
 }
-//# sourceMappingURL=client-manager.d.ts.map
+/** Build the SDK's safe child environment without leaking this or a parent bridge endpoint. */
+export declare function buildStdioEnvironment(configured: Readonly<Record<string, string>> | undefined): Record<string, string>;

package/dist/mcp/client-manager.js

@@ -1,148 +1,307 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { getDefaultEnvironment, StdioClientTransport } from "@modelcontextprotocol/client/stdio";
+import { DirectoryReadResultSchema, SkillsGetResultSchema, SkillsListResultSchema, } from "../skills/sep2640/protocol.js";
+import { describeNegotiation, SKILLS_METHODS } from "../skills/sep2640/spec.js";
+import { adaptTerminalCallToolResult } from "./call-tool-result.js";
+import { createMcpClient, getMcpClientDiagnostics, MCP_CLIENT_POLICY, } from "./client-factory.js";
+import { McpHostElicitationError } from "./host-elicitation.js";
+const unavailableElicitation = {
+    elicit: () => Promise.reject(new McpHostElicitationError("The MCP server requested user input, but no host elicitation integration is configured. The request was not approved.")),
+};
 /**
  * Manages connections to multiple MCP servers and aggregates their tools.
  *
- * Tools are discovered and stored internally. They are NOT registered with pi
- * automatically — that responsibility belongs to the access tiers (Skills,
- * Football, Code Mode).
+ * Tools are discovered and stored internally. They are NOT registered with mcpi
+ * automatically — that responsibility belongs to the access tiers.
  */
 export class McpClientManager {
     connections = new Map();
+    elicitation;
+    clientFactory;
+    transportFactory;
+    skillsExtensionRequested;
+    constructor(options = {}) {
+        this.elicitation = options.elicitation ?? unavailableElicitation;
+        this.clientFactory = options.clientFactory ?? createMcpClient;
+        this.transportFactory = options.transportFactory ?? createTransport;
+        this.skillsExtensionRequested = options.skillsExtension === true;
+    }
+    /** Whether this manager advertises the draft skills extension. */
+    requestsSkillsExtension() {
+        return this.skillsExtensionRequested;
+    }
+    /**
+     * Turn the draft skills extension on or off for future connections.
+     *
+     * The host reads the gate from config, which loads after this manager is
+     * constructed. Already-open connections keep whatever they negotiated at
+     * initialize, because the capability set is fixed for a session.
+     */
+    enableSkillsExtension(enabled) {
+        this.skillsExtensionRequested = enabled;
+    }
     /**
      * Connect to all servers defined in the config.
      * Connections that fail are logged and skipped — partial success is fine.
      */
     async connectAll(config, log = console.error) {
-        const entries = Object.entries(config.mcpServers);
+        const entries = Object.entries(config.mcpServers).sort(([left], [right]) => compareStrings(left, right));
         const results = await Promise.allSettled(entries.map(([name, serverConfig]) => this.connectOne(name, serverConfig, log)));
-        for (let i = 0; i < results.length; i++) {
-            const result = results[i];
+        for (let index = 0; index < results.length; index++) {
+            const result = results[index];
             if (result.status === "rejected") {
-                log(`[mcp] Failed to connect to "${entries[i][0]}": ${result.reason}`);
+                log(`[mcp] Failed to connect to "${entries[index][0]}": ${formatError(result.reason)}`);
             }
         }
     }
     /** Connect to a single server by name. */
     async connectOne(name, serverConfig, log = console.error) {
-        // Disconnect existing connection with this name if any
         if (this.connections.has(name)) {
             await this.disconnectOne(name);
         }
-        const transport = createTransport(serverConfig);
-        const client = new Client({ name: "mcpi-ext", version: "0.1.0" }, {
-            capabilities: {},
+        const transport = this.transportFactory(serverConfig);
+        const client = this.clientFactory({
+            elicitation: this.elicitation,
+            skillsExtension: this.skillsExtensionRequested,
             listChanged: {
                 tools: {
-                    onChanged: (_error, tools) => {
-                        if (tools) {
-                            const conn = this.connections.get(name);
-                            if (conn && conn.client === client) {
-                                conn.tools = toMcpTools(name, tools);
-                                log(`[mcp] Tools updated for "${name}" (${conn.tools.length} tools)`);
-                            }
+                    onChanged: (error, tools) => {
+                        if (error) {
+                            log(`[mcp] Failed to refresh tools for "${name}": ${formatError(error)}`);
+                            return;
+                        }
+                        if (tools === null)
+                            return;
+                        const connection = this.connections.get(name);
+                        if (connection?.client === client) {
+                            connection.tools = toMcpTools(name, tools);
+                            log(`[mcp] Tools updated for "${name}" (${connection.tools.length} tools)`);
                         }
                     },
                 },
             },
         });
-        // Insert placeholder so listChanged notifications during connect aren't dropped
         this.connections.set(name, { client, transport, tools: [] });
         try {
-            await client.connect(transport);
-            const toolsResult = await client.listTools();
+            await client.connect(transport, {
+                timeout: MCP_CLIENT_POLICY.requestTimeoutMs,
+                maxTotalTimeout: MCP_CLIENT_POLICY.maxTotalTimeoutMs,
+            });
+            const toolsResult = await client.listTools(undefined, {
+                timeout: MCP_CLIENT_POLICY.requestTimeoutMs,
+                maxTotalTimeout: MCP_CLIENT_POLICY.maxTotalTimeoutMs,
+            });
             const tools = toMcpTools(name, toolsResult.tools);
-            const conn = this.connections.get(name);
-            if (conn && conn.client === client) {
-                conn.tools = tools;
+            const diagnostics = getMcpClientDiagnostics(client, {
+                skillsExtensionRequested: this.skillsExtensionRequested,
+            });
+            const connection = this.connections.get(name);
+            if (connection?.client === client) {
+                connection.tools = tools;
+                connection.diagnostics = diagnostics;
+            }
+            log(`[mcp] Connected to "${name}" (${tools.length} tools, protocol era: ${diagnostics.protocolEra ?? "unknown"})`);
+            if (this.skillsExtensionRequested) {
+                log(`[mcp] "${name}": ${describeNegotiation(name, diagnostics.skillsExtension.serverCapability)}`);
             }
-            log(`[mcp] Connected to "${name}" (${tools.length} tools)`);
         }
         catch (error) {
-            // Clean up on failure so we don't leak a partially connected client
-            const conn = this.connections.get(name);
-            if (conn && conn.client === client) {
+            const connection = this.connections.get(name);
+            if (connection?.client === client) {
                 this.connections.delete(name);
             }
             try {
                 await client.close();
             }
             catch {
-                // best-effort cleanup
+                // Preserve the original connection failure.
             }
             throw error;
         }
     }
+    /** Call a tool and return only its terminal protocol result. */
+    async callTool(serverName, toolName, args, signal) {
+        const connection = this.connections.get(serverName);
+        if (!connection) {
+            throw new Error(`MCP server "${serverName}" is not connected`);
+        }
+        const result = await connection.client.callTool({ name: toolName, arguments: args }, {
+            timeout: MCP_CLIENT_POLICY.requestTimeoutMs,
+            maxTotalTimeout: MCP_CLIENT_POLICY.maxTotalTimeoutMs,
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        return adaptTerminalCallToolResult(result);
+    }
+    /** List a server's resources. Discovery only; authorization lives in McpPolicy. */
+    async listResources(serverName, signal) {
+        const connection = this.connections.get(serverName);
+        if (!connection) {
+            throw new Error(`MCP server "${serverName}" is not connected`);
+        }
+        const result = await connection.client.listResources(undefined, {
+            timeout: MCP_CLIENT_POLICY.requestTimeoutMs,
+            maxTotalTimeout: MCP_CLIENT_POLICY.maxTotalTimeoutMs,
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        return [...result.resources].sort(compareResources);
+    }
+    /** List a server's resource templates. Authorization lives in McpPolicy. */
+    async listResourceTemplates(serverName, signal) {
+        const connection = this.connections.get(serverName);
+        if (!connection) {
+            throw new Error(`MCP server "${serverName}" is not connected`);
+        }
+        const result = await connection.client.listResourceTemplates(undefined, {
+            timeout: MCP_CLIENT_POLICY.requestTimeoutMs,
+            maxTotalTimeout: MCP_CLIENT_POLICY.maxTotalTimeoutMs,
+            ...(signal !== undefined ? { signal } : {}),
+        });
+        return [...result.resourceTemplates].sort(compareResourceTemplates);
+    }
+    /** Read a single resource. Authorization is the caller-side policy's responsibility. */
+    async readResource(serverName, uri, signal) {
+        const connection = this.connections.get(serverName);
+        if (!connection) {
+            throw new Error(`MCP server "${serverName}" is not connected`);
+        }
+        return connection.client.readResource({ uri }, {
+            timeout: MCP_CLIENT_POLICY.requestTimeoutMs,
+            maxTotalTimeout: MCP_CLIENT_POLICY.maxTotalTimeoutMs,
+            ...(signal !== undefined ? { signal } : {}),
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Draft SEP-2640 skills extension transport
+    //
+    // These are transport methods, not authorization. `McpPolicy` decides whether
+    // a call may happen; this class only knows how to put it on the wire and how
+    // to refuse to hand back a payload that does not match the draft schema.
+    // ---------------------------------------------------------------------------
+    /**
+     * The settings a server declared for one extension during `initialize`, or
+     * `undefined` if it declared no such extension.
+     */
+    getExtensionCapability(serverName, extensionName) {
+        const capability = this.connections.get(serverName)?.client.getServerCapabilities()
+            ?.extensions?.[extensionName];
+        if (capability === undefined) {
+            return undefined;
+        }
+        if (capability === null || typeof capability !== "object" || Array.isArray(capability)) {
+            // An extension declared with a non-object body is still "declared"; treat
+            // it as declared-with-no-settings rather than inventing settings for it.
+            return {};
+        }
+        return capability;
+    }
+    /** Draft SEP-2640 `skills/list`. */
+    async requestSkillsList(serverName, cursor, signal) {
+        return this.requestExtension(serverName, SKILLS_METHODS.list, cursor !== undefined ? { cursor } : {}, SkillsListResultSchema, signal);
+    }
+    /** Draft SEP-2640 `skills/get`. */
+    async requestSkillsGet(serverName, uri, signal) {
+        return this.requestExtension(serverName, SKILLS_METHODS.get, { uri }, SkillsGetResultSchema, signal);
+    }
+    /** Draft SEP-2640 `resources/directory/read`. */
+    async requestDirectoryRead(serverName, uri, cursor, signal) {
+        return this.requestExtension(serverName, SKILLS_METHODS.directoryRead, cursor !== undefined ? { uri, cursor } : { uri }, DirectoryReadResultSchema, signal);
+    }
+    async requestExtension(serverName, method, params, schema, signal) {
+        const connection = this.connections.get(serverName);
+        if (!connection) {
+            throw new Error(`MCP server "${serverName}" is not connected`);
+        }
+        return connection.client.request({ method, params }, schema, {
+            timeout: MCP_CLIENT_POLICY.requestTimeoutMs,
+            maxTotalTimeout: MCP_CLIENT_POLICY.maxTotalTimeoutMs,
+            ...(signal !== undefined ? { signal } : {}),
+        });
+    }
     /** Disconnect a single server. */
     async disconnectOne(name) {
-        const conn = this.connections.get(name);
-        if (!conn)
+        const connection = this.connections.get(name);
+        if (!connection)
             return;
         this.connections.delete(name);
         try {
-            await conn.client.close();
+            await connection.client.close();
         }
         catch {
-            // best-effort
+            // The connection is already removed; shutdown is best-effort.
         }
     }
     /** Disconnect all servers. */
     async disconnectAll() {
-        const names = [...this.connections.keys()];
-        await Promise.allSettled(names.map((n) => this.disconnectOne(n)));
+        const names = this.getConnectedServers();
+        await Promise.allSettled(names.map((name) => this.disconnectOne(name)));
     }
     /** Get all discovered tools across all connected servers. */
     getTools() {
-        const tools = [];
-        for (const conn of this.connections.values()) {
-            tools.push(...conn.tools);
-        }
-        return tools;
+        return [...this.connections.values()]
+            .flatMap((connection) => connection.tools)
+            .sort(compareTools);
     }
     /** Get tools from a specific server. */
     getToolsForServer(name) {
-        return this.connections.get(name)?.tools ?? [];
+        return [...(this.connections.get(name)?.tools ?? [])].sort(compareTools);
     }
-    /** Get the MCP Client for a specific server (needed to call tools). */
+    /** Get the MCP Client for discovery APIs that are not tool calls. */
     getClient(name) {
         return this.connections.get(name)?.client;
     }
-    /** List connected server names. */
+    getDiagnostics(name) {
+        return this.connections.get(name)?.diagnostics;
+    }
+    /** List connected server names in deterministic order. */
     getConnectedServers() {
-        return [...this.connections.keys()];
+        return [...this.connections.keys()].sort(compareStrings);
     }
 }
 function createTransport(config) {
     if (config.type === "stdio") {
-        const env = config.env
-            ? Object.fromEntries(Object.entries({ ...process.env, ...config.env }).filter((entry) => entry[1] !== undefined))
-            : undefined;
         return new StdioClientTransport({
             command: config.command,
             args: config.args,
-            env,
+            env: buildStdioEnvironment(config.env),
             cwd: config.cwd,
         });
     }
-    const headers = {
-        ...(config.headers ?? {}),
-    };
     return new StreamableHTTPClientTransport(new URL(config.url), {
         requestInit: {
-            headers,
+            headers: config.headers ?? {},
         },
     });
 }
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+/** Build the SDK's safe child environment without leaking this or a parent bridge endpoint. */
+export function buildStdioEnvironment(configured) {
+    const environment = { ...getDefaultEnvironment(), ...configured };
+    for (const name of Object.keys(environment)) {
+        if (name.startsWith("TOOL_CLI_")) {
+            Reflect.deleteProperty(environment, name);
+        }
+    }
+    return environment;
+}
 function toMcpTools(serverName, tools) {
-    return tools.map((t) => ({
-        name: t.name,
-        description: t.description,
-        inputSchema: t.inputSchema,
-        outputSchema: t.outputSchema,
-        annotations: t.annotations,
+    return tools
+        .map((tool) => ({
+        ...tool,
         serverName,
-    }));
+    }))
+        .sort(compareTools);
+}
+function compareTools(left, right) {
+    return compareStrings(left.serverName, right.serverName) || compareStrings(left.name, right.name);
+}
+function compareResources(left, right) {
+    return compareStrings(left.uri, right.uri) || compareStrings(left.name, right.name);
+}
+function compareResourceTemplates(left, right) {
+    return (compareStrings(left.uriTemplate, right.uriTemplate) || compareStrings(left.name, right.name));
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-//# sourceMappingURL=client-manager.js.map

package/dist/mcp/config-loader.d.ts

@@ -5,4 +5,3 @@ import { McpConfig } from "./config.js";
  * Throws on invalid JSON or schema violations.
  */
 export declare function loadMcpConfig(configPath?: string): Promise<McpConfig>;
-//# sourceMappingURL=config-loader.d.ts.map

package/dist/mcp/config-loader.js

@@ -40,4 +40,3 @@ export async function loadMcpConfig(configPath) {
     }
     return parsed;
 }
-//# sourceMappingURL=config-loader.js.map

package/dist/mcp/config.d.ts

@@ -38,9 +38,19 @@ export declare const McpConfig: Type.TObject<{
         url: Type.TString;
         headers: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
     }>]>>;
+    experimental: Type.TOptional<Type.TObject<{
+        skillsExtension: Type.TOptional<Type.TBoolean>;
+    }>>;
 }>;
 export type StdioServerConfig = Static<typeof StdioServerConfig>;
 export type RemoteServerConfig = Static<typeof RemoteServerConfig>;
 export type ServerConfig = Static<typeof ServerConfig>;
 export type McpConfig = Static<typeof McpConfig>;
-//# sourceMappingURL=config.d.ts.map
+/**
+ * Whether the draft skills extension is enabled.
+ *
+ * Defaults to **off**. SEP-2640 is a draft: nothing here should start speaking
+ * it because a config file happened to omit a key, and a host that quietly
+ * enabled a proposal would make it indistinguishable from ratified support.
+ */
+export declare function isSkillsExtensionEnabled(config: Pick<McpConfig, "experimental">): boolean;

package/dist/mcp/config.js

@@ -24,5 +24,19 @@ export const McpConfig = Type.Object({
     mcpServers: Type.Record(Type.String(), ServerConfig, {
         description: "Named MCP server configurations",
     }),
+    experimental: Type.Optional(Type.Object({
+        skillsExtension: Type.Optional(Type.Boolean({
+            description: "Opt in to the DRAFT MCP skills extension (SEP-2640). Unratified and subject to change; off by default.",
+        })),
+    }, { description: "Opt-in support for unratified MCP proposals" })),
 });
-//# sourceMappingURL=config.js.map
+/**
+ * Whether the draft skills extension is enabled.
+ *
+ * Defaults to **off**. SEP-2640 is a draft: nothing here should start speaking
+ * it because a config file happened to omit a key, and a host that quietly
+ * enabled a proposal would make it indistinguishable from ratified support.
+ */
+export function isSkillsExtensionEnabled(config) {
+    return config.experimental?.skillsExtension === true;
+}

package/dist/mcp/gateway-defaults.d.ts

@@ -0,0 +1,14 @@
+import type { McpPolicyGateway } from "./policy.js";
+/**
+ * Gateway behaviour for a server that does not speak the draft SEP-2640 skills
+ * extension.
+ *
+ * `getExtensionCapability` returns `undefined` — the honest answer for a server
+ * that declared nothing — and the three request methods reject. They reject
+ * rather than return empty results because reaching them at all would mean the
+ * policy dispatched an extension request to a server that never declared the
+ * extension, and a silent empty result would hide that bug.
+ *
+ * Spread this into any gateway that only implements the classic MCP surface.
+ */
+export declare const noSkillsExtensionGateway: Pick<McpPolicyGateway, "getExtensionCapability" | "requestSkillsList" | "requestSkillsGet" | "requestDirectoryRead">;

package/dist/mcp/gateway-defaults.js

@@ -0,0 +1,21 @@
+/**
+ * Gateway behaviour for a server that does not speak the draft SEP-2640 skills
+ * extension.
+ *
+ * `getExtensionCapability` returns `undefined` — the honest answer for a server
+ * that declared nothing — and the three request methods reject. They reject
+ * rather than return empty results because reaching them at all would mean the
+ * policy dispatched an extension request to a server that never declared the
+ * extension, and a silent empty result would hide that bug.
+ *
+ * Spread this into any gateway that only implements the classic MCP surface.
+ */
+export const noSkillsExtensionGateway = {
+    getExtensionCapability: () => undefined,
+    requestSkillsList: () => Promise.reject(new Error(unsupported("skills/list"))),
+    requestSkillsGet: () => Promise.reject(new Error(unsupported("skills/get"))),
+    requestDirectoryRead: () => Promise.reject(new Error(unsupported("resources/directory/read"))),
+};
+function unsupported(method) {
+    return `This MCP server does not declare the skills extension, so ${method} is unavailable.`;
+}

package/dist/mcp/host-approval.d.ts

@@ -0,0 +1,16 @@
+import type { ExtensionContext } from "@sammorrowdrums/mcpi";
+import type { McpApprovalPrompt, McpApprovalRequest } from "./policy.js";
+type ApprovalContext = Pick<ExtensionContext, "hasUI" | "ui">;
+/**
+ * Bridges policy approval requests to mcpi's explicit user-facing confirmation.
+ *
+ * Mirrors {@link McpiHostElicitation}: without an interactive UI the request is
+ * reported as undecided rather than approved, so nothing is ever silently
+ * enabled.
+ */
+export declare class McpiHostApproval implements McpApprovalPrompt {
+    private context;
+    setContext(context: ApprovalContext | undefined): void;
+    confirm(request: McpApprovalRequest): Promise<boolean | undefined>;
+}
+export {};

package/dist/mcp/host-approval.js

@@ -0,0 +1,19 @@
+/**
+ * Bridges policy approval requests to mcpi's explicit user-facing confirmation.
+ *
+ * Mirrors {@link McpiHostElicitation}: without an interactive UI the request is
+ * reported as undecided rather than approved, so nothing is ever silently
+ * enabled.
+ */
+export class McpiHostApproval {
+    context;
+    setContext(context) {
+        this.context = context;
+    }
+    async confirm(request) {
+        const context = this.context;
+        if (!context?.hasUI)
+            return undefined;
+        return context.ui.confirm(request.title, request.message, request.signal ? { signal: request.signal } : undefined);
+    }
+}

package/dist/mcp/host-elicitation.d.ts

@@ -0,0 +1,19 @@
+import type { ElicitRequestParams, ElicitResult } from "@modelcontextprotocol/client";
+import type { ExtensionContext } from "@sammorrowdrums/mcpi";
+import type { McpElicitationHandler } from "./client-factory.js";
+type ElicitationContext = Pick<ExtensionContext, "hasUI" | "ui">;
+export declare class McpHostElicitationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Bridges MCP form elicitation to mcpi's explicit user-facing UI.
+ *
+ * URL elicitation is intentionally unsupported and is not advertised by the
+ * client. Form requests never receive an implicit approval.
+ */
+export declare class McpiHostElicitation implements McpElicitationHandler {
+    private context;
+    setContext(context: ElicitationContext | undefined): void;
+    elicit(params: ElicitRequestParams): Promise<ElicitResult>;
+}
+export {};