@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/mcp/client-factory.js

@@ -0,0 +1,76 @@
+import { Client, SUPPORTED_PROTOCOL_VERSIONS, } from "@modelcontextprotocol/client";
+import { SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, } from "../skills/sep2640/spec.js";
+export const MCP_CLIENT_IDENTITY = {
+    name: "@sammorrowdrums/mcpi-ext",
+    version: "1.0.0",
+};
+export const MCP_CLIENT_POLICY = {
+    listMaxPages: 64,
+    maxInputRequiredRounds: 4,
+    probeTimeoutMs: 5_000,
+    requestTimeoutMs: 60_000,
+    maxTotalTimeoutMs: 10 * 60_000,
+};
+export const MCP_SUPPORTED_PROTOCOL_VERSIONS = [
+    "2026-07-28",
+    ...SUPPORTED_PROTOCOL_VERSIONS,
+];
+/**
+ * Creates every MCP client with the same identity, negotiated protocol policy,
+ * capabilities, pagination limit, and SDK-managed input_required handling.
+ */
+export function createMcpClient(options) {
+    const client = new Client(MCP_CLIENT_IDENTITY, {
+        supportedProtocolVersions: [...MCP_SUPPORTED_PROTOCOL_VERSIONS],
+        capabilities: {
+            elicitation: { form: {} },
+            // Per SEP-2133 the extension is offered here, at initialize, and the
+            // server answers with its own settings. Every later skills request
+            // re-reads that answer instead of trusting a cached yes.
+            extensions: options.skillsExtension ? { [SKILLS_EXTENSION_NAME]: {} } : {},
+        },
+        versionNegotiation: {
+            mode: "auto",
+            probe: {
+                timeoutMs: MCP_CLIENT_POLICY.probeTimeoutMs,
+                maxRetries: 0,
+            },
+        },
+        inputRequired: {
+            autoFulfill: true,
+            maxRounds: MCP_CLIENT_POLICY.maxInputRequiredRounds,
+        },
+        listChanged: options.listChanged,
+        listMaxPages: MCP_CLIENT_POLICY.listMaxPages,
+        defaultCacheTtlMs: 0,
+    });
+    client.setRequestHandler("elicitation/create", (request) => options.elicitation.elicit(request.params));
+    return client;
+}
+export function getMcpClientDiagnostics(client, options = {}) {
+    // Diagnostics run inside `connectOne`, so this must never be able to fail a
+    // connection. `getServerCapabilities` is absent on minimal client doubles and
+    // returns undefined before initialize completes; either way an unavailable
+    // capability is reported as "not declared", never thrown.
+    const serverCapabilities = typeof client.getServerCapabilities === "function" ? client.getServerCapabilities() : undefined;
+    const declared = serverCapabilities?.extensions?.[SKILLS_EXTENSION_NAME];
+    const capability = declared !== undefined && declared !== null && typeof declared === "object"
+        ? declared
+        : undefined;
+    return {
+        protocolVersion: typeof client.getNegotiatedProtocolVersion === "function"
+            ? client.getNegotiatedProtocolVersion()
+            : undefined,
+        protocolEra: client.getProtocolEra(),
+        discoverResult: client.getDiscoverResult(),
+        serverImplementation: typeof client.getServerVersion === "function" ? client.getServerVersion() : undefined,
+        serverCapabilities,
+        skillsExtension: {
+            requested: options.skillsExtensionRequested === true,
+            revision: SKILLS_EXTENSION_REVISION,
+            status: SKILLS_EXTENSION_STATUS,
+            serverDeclared: capability !== undefined,
+            serverCapability: capability,
+        },
+    };
+}

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

@@ -0,0 +1,88 @@
+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";
+/** 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 mcpi
+ * automatically — that responsibility belongs to the access tiers.
+ */
+export declare class McpClientManager {
+    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.
+     */
+    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. */
+    disconnectAll(): Promise<void>;
+    /** Get all discovered tools across all connected servers. */
+    getTools(): McpTool[];
+    /** Get tools from a specific server. */
+    getToolsForServer(name: string): McpTool[];
+    /** Get the MCP Client for discovery APIs that are not tool calls. */
+    getClient(name: string): Client | undefined;
+    getDiagnostics(name: string): McpClientDiagnostics | undefined;
+    /** List connected server names in deterministic order. */
+    getConnectedServers(): string[];
+}
+/** 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

@@ -0,0 +1,307 @@
+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 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).sort(([left], [right]) => compareStrings(left, right));
+        const results = await Promise.allSettled(entries.map(([name, serverConfig]) => this.connectOne(name, serverConfig, log)));
+        for (let index = 0; index < results.length; index++) {
+            const result = results[index];
+            if (result.status === "rejected") {
+                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) {
+        if (this.connections.has(name)) {
+            await this.disconnectOne(name);
+        }
+        const transport = this.transportFactory(serverConfig);
+        const client = this.clientFactory({
+            elicitation: this.elicitation,
+            skillsExtension: this.skillsExtensionRequested,
+            listChanged: {
+                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)`);
+                        }
+                    },
+                },
+            },
+        });
+        this.connections.set(name, { client, transport, tools: [] });
+        try {
+            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 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)}`);
+            }
+        }
+        catch (error) {
+            const connection = this.connections.get(name);
+            if (connection?.client === client) {
+                this.connections.delete(name);
+            }
+            try {
+                await client.close();
+            }
+            catch {
+                // 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 connection = this.connections.get(name);
+        if (!connection)
+            return;
+        this.connections.delete(name);
+        try {
+            await connection.client.close();
+        }
+        catch {
+            // The connection is already removed; shutdown is best-effort.
+        }
+    }
+    /** Disconnect all servers. */
+    async disconnectAll() {
+        const names = this.getConnectedServers();
+        await Promise.allSettled(names.map((name) => this.disconnectOne(name)));
+    }
+    /** Get all discovered tools across all connected servers. */
+    getTools() {
+        return [...this.connections.values()]
+            .flatMap((connection) => connection.tools)
+            .sort(compareTools);
+    }
+    /** Get tools from a specific server. */
+    getToolsForServer(name) {
+        return [...(this.connections.get(name)?.tools ?? [])].sort(compareTools);
+    }
+    /** Get the MCP Client for discovery APIs that are not tool calls. */
+    getClient(name) {
+        return this.connections.get(name)?.client;
+    }
+    getDiagnostics(name) {
+        return this.connections.get(name)?.diagnostics;
+    }
+    /** List connected server names in deterministic order. */
+    getConnectedServers() {
+        return [...this.connections.keys()].sort(compareStrings);
+    }
+}
+function createTransport(config) {
+    if (config.type === "stdio") {
+        return new StdioClientTransport({
+            command: config.command,
+            args: config.args,
+            env: buildStdioEnvironment(config.env),
+            cwd: config.cwd,
+        });
+    }
+    return new StreamableHTTPClientTransport(new URL(config.url), {
+        requestInit: {
+            headers: config.headers ?? {},
+        },
+    });
+}
+/** 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((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);
+}

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

@@ -0,0 +1,7 @@
+import { McpConfig } from "./config.js";
+/**
+ * Load and validate an MCP config file.
+ * Returns an empty config if the file doesn't exist.
+ * Throws on invalid JSON or schema violations.
+ */
+export declare function loadMcpConfig(configPath?: string): Promise<McpConfig>;

package/dist/mcp/config-loader.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { Value } from "typebox/value";
+import { McpConfig } from "./config.js";
+const DEFAULT_CONFIG_PATH = join(homedir(), ".config", "mcpi-ext", "mcp.json");
+/**
+ * Load and validate an MCP config file.
+ * Returns an empty config if the file doesn't exist.
+ * Throws on invalid JSON or schema violations.
+ */
+export async function loadMcpConfig(configPath) {
+    const path = configPath ?? DEFAULT_CONFIG_PATH;
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            return { mcpServers: {} };
+        }
+        throw new Error(`Failed to read MCP config at ${path}: ${err.message}`, {
+            cause: err,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid JSON in MCP config at ${path}`);
+    }
+    if (!Value.Check(McpConfig, parsed)) {
+        const errors = Value.Errors(McpConfig, parsed);
+        const details = errors
+            .slice(0, 5)
+            .map((e) => `  ${e.instancePath || "/"}: ${e.message}`)
+            .join("\n");
+        throw new Error(`Invalid MCP config at ${path}:\n${details}`);
+    }
+    return parsed;
+}

package/dist/mcp/config.d.ts

@@ -0,0 +1,56 @@
+import { Type, type Static } from "typebox";
+/** Configuration for a stdio-based MCP server (spawns a child process). */
+export declare const StdioServerConfig: Type.TObject<{
+    type: Type.TLiteral<"stdio">;
+    command: Type.TString;
+    args: Type.TOptional<Type.TArray<Type.TString>>;
+    env: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+    cwd: Type.TOptional<Type.TString>;
+}>;
+/** Configuration for a remote MCP server (Streamable HTTP). */
+export declare const RemoteServerConfig: Type.TObject<{
+    type: Type.TLiteral<"remote">;
+    url: Type.TString;
+    headers: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+}>;
+/** A single MCP server entry — either stdio or remote. */
+export declare const ServerConfig: Type.TUnion<[Type.TObject<{
+    type: Type.TLiteral<"stdio">;
+    command: Type.TString;
+    args: Type.TOptional<Type.TArray<Type.TString>>;
+    env: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+    cwd: Type.TOptional<Type.TString>;
+}>, Type.TObject<{
+    type: Type.TLiteral<"remote">;
+    url: Type.TString;
+    headers: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+}>]>;
+/** Top-level configuration file schema. */
+export declare const McpConfig: Type.TObject<{
+    mcpServers: Type.TRecord<"^.*$", Type.TUnion<[Type.TObject<{
+        type: Type.TLiteral<"stdio">;
+        command: Type.TString;
+        args: Type.TOptional<Type.TArray<Type.TString>>;
+        env: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+        cwd: Type.TOptional<Type.TString>;
+    }>, Type.TObject<{
+        type: Type.TLiteral<"remote">;
+        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>;
+/**
+ * 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

@@ -0,0 +1,42 @@
+import { Type } from "typebox";
+/** Configuration for a stdio-based MCP server (spawns a child process). */
+export const StdioServerConfig = Type.Object({
+    type: Type.Literal("stdio"),
+    command: Type.String({ description: "Executable to run" }),
+    args: Type.Optional(Type.Array(Type.String(), { description: "Command-line arguments" })),
+    env: Type.Optional(Type.Record(Type.String(), Type.String(), {
+        description: "Extra environment variables for the child process",
+    })),
+    cwd: Type.Optional(Type.String({ description: "Working directory for the child process" })),
+});
+/** Configuration for a remote MCP server (Streamable HTTP). */
+export const RemoteServerConfig = Type.Object({
+    type: Type.Literal("remote"),
+    url: Type.String({ description: "HTTP(S) endpoint URL" }),
+    headers: Type.Optional(Type.Record(Type.String(), Type.String(), {
+        description: "Extra HTTP headers (e.g. Authorization)",
+    })),
+});
+/** A single MCP server entry — either stdio or remote. */
+export const ServerConfig = Type.Union([StdioServerConfig, RemoteServerConfig]);
+/** Top-level configuration file schema. */
+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" })),
+});
+/**
+ * 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.`;
+}