@plurnk/plurnk-mcp 1.6.1 → 1.7.0

package/dist/client.js

@@ -1,71 +1,312 @@
-import { Client, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
+import { Client, ClientCredentialsProvider, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client";
 import { StdioClientTransport, getDefaultEnvironment, } from "@modelcontextprotocol/client/stdio";
+import { Validator, } from "@plurnk/plurnk-contracts";
 import packageJson from "../package.json" with { type: "json" };
-import { connectTimeoutMs, requestTimeoutMs, } from "./config.js";
-export const MCP_PROTOCOL_VERSION = "2026-07-28";
-const openTransport = (config) => {
-    if (config.transport === "http") {
-        return new StreamableHTTPClientTransport(new URL(config.url), config.headers === undefined
-            ? undefined
-            : { requestInit: { headers: config.headers } });
+import { connectTimeoutMs, expandReferences, requestTimeoutMs, } from "./config.js";
+import { INPUT_REQUIRED_MAX_ROUNDS, runInputRequiredRequest, } from "./inputRequired.js";
+import InteractiveOAuthProvider from "./oauth.js";
+import ExtensionChannel from "./extensionChannel.js";
+import { mcpRoutingHeaderValue } from "./protocolHeaders.js";
+import { MCP_PROTOCOL_VERSION, MCP_TASKS_EXTENSION_ID, } from "./protocol.js";
+import Subscriptions from "./subscriptions.js";
+import { callToolWithTasks, serverSupportsTasks, } from "./tasks.js";
+const message = (error) => error instanceof Error ? error.message : String(error);
+const expandedRecord = (source, environ, field) => source === undefined
+    ? undefined
+    : Object.fromEntries(Object.entries(source).map(([key, value]) => [
+        key,
+        expandReferences(value, environ, `${field}.${key}`),
+    ]));
+const requireString = (value, field) => {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${field} must be a non-empty string.`);
+    }
+    return value;
+};
+const resolveDefinition = (source, environ) => {
+    const definition = Validator.assertMcpServerDefinition(source);
+    if (definition.transport === "stdio") {
+        return {
+            transport: "stdio",
+            command: expandReferences(requireString(definition.command, `${definition.name}.command`), environ, `${definition.name}.command`),
+            args: (definition.args ?? []).map((argument, index) => expandReferences(argument, environ, `${definition.name}.args[${index}]`)),
+            ...(definition.cwd === undefined
+                ? {}
+                : { cwd: expandReferences(definition.cwd, environ, `${definition.name}.cwd`) }),
+            ...(definition.env === undefined
+                ? {}
+                : { env: expandedRecord(definition.env, environ, `${definition.name}.env`) }),
+        };
+    }
+    const url = requireString(definition.url, `${definition.name}.url`);
+    const headers = expandedRecord(definition.headers, environ, `${definition.name}.headers`);
+    const authorizationHeader = Object.keys(headers ?? {}).find((name) => name.toLowerCase() === "authorization");
+    if (definition.authorization !== undefined && authorizationHeader !== undefined) {
+        throw new Error(`${definition.name}.authorization conflicts with the Authorization header.`);
+    }
+    if (definition.authorization === undefined) {
+        return {
+            transport: "http",
+            url,
+            ...(headers === undefined ? {} : { headers }),
+            cachePartition: "anonymous",
+        };
+    }
+    if (definition.authorization.type === "bearer") {
+        const token = expandReferences(definition.authorization.token, environ, `${definition.name}.authorization.token`);
+        if (token.length === 0)
+            throw new Error(`${definition.name}.authorization.token resolved empty.`);
+        return {
+            transport: "http",
+            url,
+            ...(headers === undefined ? {} : { headers }),
+            authProvider: { token: async () => token },
+            cachePartition: `bearer:${definition.authorization.token}`,
+        };
+    }
+    if (definition.authorization.type === "client-credentials") {
+        const secret = expandReferences(definition.authorization.clientSecret, environ, `${definition.name}.authorization.clientSecret`);
+        if (secret.length === 0) {
+            throw new Error(`${definition.name}.authorization.clientSecret resolved empty.`);
+        }
+        return {
+            transport: "http",
+            url,
+            ...(headers === undefined ? {} : { headers }),
+            authProvider: new ClientCredentialsProvider({
+                clientId: definition.authorization.clientId,
+                clientSecret: secret,
+                ...(definition.authorization.scope === undefined
+                    ? {}
+                    : { scope: definition.authorization.scope }),
+            }),
+            cachePartition: `client:${definition.authorization.clientId}`,
+        };
+    }
+    const oauthAuthorization = definition.authorization;
+    const oauthProvider = new InteractiveOAuthProvider({
+        redirectUrl: oauthAuthorization.redirectUrl,
+        ...(oauthAuthorization.scope === undefined ? {} : { scope: oauthAuthorization.scope }),
+        ...("clientMetadataUrl" in oauthAuthorization
+            ? { clientMetadataUrl: oauthAuthorization.clientMetadataUrl }
+            : {}),
+        ...("clientId" in oauthAuthorization
+            ? {
+                clientId: oauthAuthorization.clientId,
+                clientSecret: expandReferences(oauthAuthorization.clientSecret, environ, `${definition.name}.authorization.clientSecret`),
+            }
+            : {}),
+    });
+    const cachePartition = "clientMetadataUrl" in oauthAuthorization
+        ? `oauth:cimd:${oauthAuthorization.clientMetadataUrl}`
+        : "clientId" in oauthAuthorization
+            ? `oauth:client:${oauthAuthorization.clientId}`
+            : "oauth:dynamic";
+    return {
+        transport: "http",
+        url,
+        ...(headers === undefined ? {} : { headers }),
+        authProvider: oauthProvider,
+        oauthProvider,
+        cachePartition,
+    };
+};
+const openTransport = (definition) => {
+    if (definition.transport === "http") {
+        return new StreamableHTTPClientTransport(new URL(definition.url), {
+            ...(definition.headers === undefined
+                ? {}
+                : { requestInit: { headers: definition.headers } }),
+            ...(definition.authProvider === undefined
+                ? {}
+                : { authProvider: definition.authProvider }),
+            fetch: async (url, init) => {
+                const body = typeof init?.body === "string"
+                    ? (() => {
+                        try {
+                            return JSON.parse(init.body);
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    })()
+                    : undefined;
+                const request = body !== null && typeof body === "object" && !Array.isArray(body)
+                    ? body
+                    : undefined;
+                if (["tasks/get", "tasks/update", "tasks/cancel"].includes(String(request?.method))
+                    && typeof request?.params?.taskId === "string") {
+                    const headers = new Headers(init?.headers);
+                    headers.set("Mcp-Name", mcpRoutingHeaderValue(request.params.taskId));
+                    return fetch(url, { ...init, headers });
+                }
+                return fetch(url, init);
+            },
+        });
     }
     return new StdioClientTransport({
-        command: config.command,
-        args: config.args,
-        cwd: config.cwd,
+        command: definition.command,
+        args: definition.args,
+        cwd: definition.cwd,
         env: {
             ...getDefaultEnvironment(),
-            ...config.env,
+            ...definition.env,
         },
     });
 };
-const openClient = async (config, environ) => {
-    const client = new Client({
+export class AuthorizationRequiredError extends Error {
+    authorizationUrl;
+    constructor(authorizationUrl, cause) {
+        super("MCP server requires interactive OAuth authorization.", { cause });
+        this.name = "AuthorizationRequiredError";
+        this.authorizationUrl = authorizationUrl;
+    }
+}
+const openClient = async (definition, environ, options, transport) => {
+    const changed = (error) => options.onCatalogChanged?.(error ?? null);
+    const clientInfo = {
         name: packageJson.name,
         version: packageJson.version,
-    }, {
+    };
+    const clientCapabilities = {
+        elicitation: {
+            form: {},
+            url: {},
+        },
+        extensions: {
+            [MCP_TASKS_EXTENSION_ID]: {},
+        },
+    };
+    const client = new Client(clientInfo, {
+        capabilities: clientCapabilities,
         versionNegotiation: {
             mode: { pin: MCP_PROTOCOL_VERSION },
         },
         inputRequired: {
             autoFulfill: false,
+            maxRounds: INPUT_REQUIRED_MAX_ROUNDS,
+        },
+        listChanged: {
+            tools: {
+                autoRefresh: false,
+                onChanged: (error) => changed(error ?? undefined),
+            },
+            resources: {
+                autoRefresh: false,
+                onChanged: (error) => changed(error ?? undefined),
+            },
+            prompts: {
+                autoRefresh: false,
+                onChanged: (error) => changed(error ?? undefined),
+            },
         },
+        ...(definition.transport === "http"
+            ? { cachePartition: definition.cachePartition }
+            : {}),
     });
+    client.onerror = (error) => options.onInfrastructureError?.(error);
     try {
-        await client.connect(openTransport(config), {
+        await client.connect(transport, {
             timeout: connectTimeoutMs(environ),
         });
     }
     catch (cause) {
+        const authorizationUrl = definition.transport === "http"
+            ? definition.oauthProvider?.takeAuthorizationUrl()
+            : undefined;
+        let closeFailure;
         try {
             await client.close();
         }
-        catch (closeCause) {
-            throw new AggregateError([cause, closeCause], `MCP ${MCP_PROTOCOL_VERSION} connection and cleanup failed.`);
+        catch (error) {
+            closeFailure = error;
+        }
+        if (authorizationUrl !== undefined) {
+            throw new AuthorizationRequiredError(authorizationUrl.href, closeFailure === undefined ? cause : new AggregateError([cause, closeFailure]));
+        }
+        if (closeFailure !== undefined) {
+            throw new AggregateError([cause, closeFailure], `MCP ${MCP_PROTOCOL_VERSION} connection and cleanup failed.`);
         }
         throw new Error(`MCP ${MCP_PROTOCOL_VERSION} connection failed.`, { cause });
     }
+    const discover = client.getDiscoverResult();
     if (client.getProtocolEra() !== "modern"
         || client.getNegotiatedProtocolVersion() !== MCP_PROTOCOL_VERSION
-        || client.getDiscoverResult() === undefined) {
+        || discover === undefined) {
         await client.close();
         throw new Error(`MCP server did not negotiate required revision ${MCP_PROTOCOL_VERSION}.`);
     }
-    return client;
+    const extensions = new ExtensionChannel(transport, {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        clientInfo,
+        clientCapabilities,
+        cancelRequest: async (requestId) => client.notification({
+            method: "notifications/cancelled",
+            params: { requestId },
+        }),
+        onError: options.onInfrastructureError,
+    });
+    return {
+        client,
+        transport,
+        extensions,
+        subscriptions: new Subscriptions(client, {
+            timeout: requestTimeoutMs(environ),
+            tasks: serverSupportsTasks(discover.capabilities),
+            onError: options.onInfrastructureError,
+        }),
+    };
 };
 export default class ServerConnection {
-    #config;
+    #definition;
+    #resolved;
     #environ;
+    #options;
     #client;
-    #toolHints = new Map();
-    constructor(config, environ = process.env) {
-        this.#config = config;
+    #pendingAuthorization;
+    #activeRequests = 0;
+    #closed = false;
+    constructor(definition, environ = process.env, options = {}) {
+        this.#definition = structuredClone(Validator.assertMcpServerDefinition(definition));
+        this.#resolved = resolveDefinition(this.#definition, environ);
         this.#environ = environ;
+        this.#options = options;
+    }
+    get definition() {
+        return structuredClone(this.#definition);
+    }
+    get activeRequests() {
+        return this.#activeRequests;
+    }
+    get authorizationUrl() {
+        return this.#pendingAuthorization?.authorizationUrl ?? null;
     }
-    connect() {
+    assertReplaceable() {
+        if (this.#activeRequests !== 0) {
+            throw new Error(`MCP server '${this.#definition.name}' has ${this.#activeRequests} active user request(s).`);
+        }
+    }
+    async #open() {
+        if (this.#closed)
+            throw new Error(`MCP server '${this.#definition.name}' connection is closed.`);
+        if (this.#pendingAuthorization !== undefined) {
+            throw new AuthorizationRequiredError(this.#pendingAuthorization.authorizationUrl);
+        }
         if (this.#client !== undefined)
             return this.#client;
-        const pending = openClient(this.#config, this.#environ).catch((cause) => {
+        const transport = openTransport(this.#resolved);
+        const pending = openClient(this.#resolved, this.#environ, this.#options, transport).catch((cause) => {
+            if (cause instanceof AuthorizationRequiredError
+                && this.#resolved.transport === "http"
+                && this.#resolved.oauthProvider !== undefined
+                && transport instanceof StreamableHTTPClientTransport) {
+                this.#pendingAuthorization = {
+                    transport,
+                    provider: this.#resolved.oauthProvider,
+                    authorizationUrl: cause.authorizationUrl,
+                    standaloneTransport: true,
+                };
+            }
             if (this.#client === pending)
                 this.#client = undefined;
             throw cause;
@@ -73,81 +314,233 @@ export default class ServerConnection {
         this.#client = pending;
         return pending;
     }
-    readOnly(tool) {
-        return this.#toolHints.get(tool) === true;
+    async connect() {
+        return (await this.#open()).client;
     }
-    async tools(signal) {
-        const client = await this.connect();
-        const { tools } = await client.listTools(undefined, this.#requestOptions(signal));
-        this.#toolHints = new Map(tools.map((tool) => [tool.name, tool.annotations?.readOnlyHint === true]));
-        return tools;
+    async finishAuthorization(callbackUrl) {
+        const pending = this.#pendingAuthorization;
+        if (pending === undefined) {
+            throw new Error(`MCP server '${this.#definition.name}' has no pending OAuth authorization.`);
+        }
+        const callback = new URL(callbackUrl);
+        const expected = new URL(pending.provider.redirectUrl);
+        if (callback.protocol !== expected.protocol
+            || callback.host !== expected.host
+            || callback.pathname !== expected.pathname) {
+            throw new Error("OAuth callback URL does not match the configured redirect URL.");
+        }
+        pending.provider.assertCallbackState(callback);
+        await pending.transport.finishAuth(callback.searchParams);
+        this.#pendingAuthorization = undefined;
+        await this.connect();
     }
-    async catalog(signal) {
-        const client = await this.connect();
-        const discover = client.getDiscoverResult();
-        if (discover === undefined)
-            throw new Error("Modern MCP connection omitted its discovery result.");
-        const [tools, resources, resourceTemplates, prompts] = await Promise.all([
-            discover.capabilities.tools === undefined
-                ? Promise.resolve([])
-                : this.tools(signal),
-            discover.capabilities.resources === undefined
-                ? Promise.resolve([])
-                : client.listResources(undefined, this.#requestOptions(signal)).then((result) => result.resources),
-            discover.capabilities.resources === undefined
-                ? Promise.resolve([])
-                : client.listResourceTemplates(undefined, this.#requestOptions(signal)).then((result) => result.resourceTemplates),
-            discover.capabilities.prompts === undefined
-                ? Promise.resolve([])
-                : client.listPrompts(undefined, this.#requestOptions(signal)).then((result) => result.prompts),
-        ]);
-        return {
-            protocolVersion: MCP_PROTOCOL_VERSION,
-            server: client.getServerVersion(),
-            capabilities: discover.capabilities,
-            tools,
-            resources,
-            resourceTemplates,
-            prompts,
+    async #request(run) {
+        this.#activeRequests += 1;
+        try {
+            const opened = await this.#open();
+            try {
+                return await run(opened.client, opened.subscriptions, opened.extensions);
+            }
+            catch (cause) {
+                const authorization = this.#takeAuthorization(opened, cause);
+                if (authorization !== null)
+                    throw authorization;
+                throw cause;
+            }
+        }
+        finally {
+            this.#activeRequests -= 1;
+        }
+    }
+    #takeAuthorization(opened, cause) {
+        if (this.#resolved.transport !== "http"
+            || this.#resolved.oauthProvider === undefined
+            || !(opened.transport instanceof StreamableHTTPClientTransport)) {
+            return null;
+        }
+        const authorizationUrl = this.#resolved.oauthProvider.takeAuthorizationUrl();
+        if (authorizationUrl === undefined)
+            return null;
+        this.#pendingAuthorization = {
+            transport: opened.transport,
+            provider: this.#resolved.oauthProvider,
+            authorizationUrl: authorizationUrl.href,
+            standaloneTransport: false,
         };
+        return new AuthorizationRequiredError(authorizationUrl.href, cause);
     }
-    async resources(signal) {
-        const client = await this.connect();
-        const discover = client.getDiscoverResult();
-        if (discover?.capabilities.resources === undefined) {
+    async tools(signal) {
+        return this.#request(async (client) => {
+            if (client.getDiscoverResult()?.capabilities.tools === undefined)
+                return [];
+            const { tools } = await client.listTools(undefined, this.#requestOptions(signal));
+            return tools;
+        });
+    }
+    async catalog(signal) {
+        return this.#request(async (client) => {
+            const discover = client.getDiscoverResult();
+            if (discover === undefined)
+                throw new Error("Modern MCP connection omitted its discovery result.");
+            const [tools, resources, resourceTemplates, prompts] = await Promise.all([
+                discover.capabilities.tools === undefined
+                    ? Promise.resolve([])
+                    : client.listTools(undefined, this.#requestOptions(signal)).then((result) => result.tools),
+                discover.capabilities.resources === undefined
+                    ? Promise.resolve([])
+                    : client.listResources(undefined, this.#requestOptions(signal)).then((result) => result.resources),
+                discover.capabilities.resources === undefined
+                    ? Promise.resolve([])
+                    : client.listResourceTemplates(undefined, this.#requestOptions(signal))
+                        .then((result) => result.resourceTemplates),
+                discover.capabilities.prompts === undefined
+                    ? Promise.resolve([])
+                    : client.listPrompts(undefined, this.#requestOptions(signal)).then((result) => result.prompts),
+            ]);
             return {
-                resources: [],
-                resourceTemplates: [],
+                protocolVersion: MCP_PROTOCOL_VERSION,
+                server: client.getServerVersion(),
+                capabilities: discover.capabilities,
+                tools,
+                resources,
+                resourceTemplates,
+                prompts,
             };
-        }
-        const [resources, resourceTemplates] = await Promise.all([
-            client.listResources(undefined, this.#requestOptions(signal))
-                .then((result) => result.resources),
-            client.listResourceTemplates(undefined, this.#requestOptions(signal))
-                .then((result) => result.resourceTemplates),
-        ]);
-        return {
-            resources,
-            resourceTemplates,
-        };
+        });
+    }
+    async resources(signal) {
+        return this.#request(async (client) => {
+            if (client.getDiscoverResult()?.capabilities.resources === undefined) {
+                return { resources: [], resourceTemplates: [] };
+            }
+            const [resources, resourceTemplates] = await Promise.all([
+                client.listResources(undefined, this.#requestOptions(signal))
+                    .then((result) => result.resources),
+                client.listResourceTemplates(undefined, this.#requestOptions(signal))
+                    .then((result) => result.resourceTemplates),
+            ]);
+            return { resources, resourceTemplates };
+        });
     }
-    async callTool(name, args, signal) {
-        return (await this.connect()).callTool({ name, arguments: args }, this.#requestOptions(signal));
+    async prompts(signal) {
+        return this.#request(async (client) => {
+            if (client.getDiscoverResult()?.capabilities.prompts === undefined)
+                return [];
+            return (await client.listPrompts(undefined, this.#requestOptions(signal))).prompts;
+        });
     }
-    async readResource(uri, signal) {
-        return (await this.connect()).readResource({ uri }, this.#requestOptions(signal));
+    async callTool(name, args, signal, onProgress, interact, toolDefinition) {
+        return this.#request(async (client, subscriptions, extensions) => {
+            const timeout = requestTimeoutMs(this.#environ);
+            if (serverSupportsTasks(client.getDiscoverResult()?.capabilities)) {
+                const tool = toolDefinition ?? (await client.listTools(undefined, this.#requestOptions(signal))).tools.find((candidate) => candidate.name === name);
+                if (tool === undefined) {
+                    throw new Error(`MCP server '${this.#definition.name}' did not list tool '${name}'.`);
+                }
+                return callToolWithTasks({
+                    server: this.#definition.name,
+                    name,
+                    args,
+                    tool,
+                    signal,
+                    onProgress,
+                    interact,
+                    timeout,
+                    channel: extensions,
+                    subscriptions,
+                });
+            }
+            return runInputRequiredRequest({
+                server: this.#definition.name,
+                operation: "tools/call",
+                originalParams: { name, arguments: args },
+                signal,
+                interact,
+                onProgress,
+                timeout,
+                requestLeg: (params, options) => client.callTool(params, {
+                    ...options,
+                    ...(toolDefinition === undefined ? {} : { toolDefinition }),
+                }),
+            });
+        });
     }
-    #requestOptions(signal) {
-        return {
+    async readResource(uri, signal, interact) {
+        return this.#request(async (client, subscriptions) => {
+            await subscriptions.selectResource(uri);
+            return runInputRequiredRequest({
+                server: this.#definition.name,
+                operation: "resources/read",
+                originalParams: { uri },
+                signal,
+                interact,
+                timeout: requestTimeoutMs(this.#environ),
+                requestLeg: (params, options, retry) => client.readResource(params, retry ? { ...options, cacheMode: "refresh" } : options),
+            });
+        });
+    }
+    async getPrompt(name, args, signal, interact) {
+        return this.#request(async (client) => runInputRequiredRequest({
+            server: this.#definition.name,
+            operation: "prompts/get",
+            originalParams: { name, ...(args === undefined ? {} : { arguments: args }) },
             signal,
+            interact,
             timeout: requestTimeoutMs(this.#environ),
+            requestLeg: (params, options) => client.getPrompt(params, options),
+        }));
+    }
+    async complete(params, signal) {
+        return this.#request(async (client) => client.complete(params, this.#requestOptions(signal)));
+    }
+    #requestOptions(signal, onProgress) {
+        const timeout = requestTimeoutMs(this.#environ);
+        return {
+            signal,
+            timeout,
+            maxTotalTimeout: timeout,
+            ...(onProgress === undefined ? {} : { onprogress: onProgress }),
         };
     }
     async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
         const client = this.#client;
         this.#client = undefined;
-        if (client !== undefined)
-            await (await client).close();
+        const pending = this.#pendingAuthorization;
+        this.#pendingAuthorization = undefined;
+        const closures = [];
+        if (client !== undefined) {
+            closures.push(client.then(async ({ client: connected, extensions, subscriptions }) => {
+                const failures = [];
+                extensions.close();
+                // A full connection close terminates its listen request. Retiring first
+                // avoids a redundant cancellation racing the SDK's removed listen ID.
+                const settled = await Promise.allSettled([
+                    subscriptions.retire(),
+                    connected.close(),
+                ]);
+                failures.push(...settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []));
+                if (failures.length === 1)
+                    throw failures[0];
+                if (failures.length > 1) {
+                    throw new AggregateError(failures, `MCP server '${this.#definition.name}' connection shutdown failed.`);
+                }
+            }));
+        }
+        if (pending?.standaloneTransport === true)
+            closures.push(pending.transport.close());
+        const settled = await Promise.allSettled(closures);
+        const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1) {
+            throw new AggregateError(failures, `MCP server '${this.#definition.name}' shutdown failed.`);
+        }
+    }
+    describeError(error) {
+        return message(error);
     }
 }
 //# sourceMappingURL=client.js.map