toolnexus 0.24.0 → 0.26.0

package/dist/mcp.js

@@ -11,6 +11,9 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { sanitize } from "./types.js";
 import { summarizePart } from "./content.js";
+import { probe, newOAuth, defaultTokenStore } from "./mcp2026/source.js";
+import { PendingError } from "./mcp2026/auth.js";
+export { Token, MemoryTokenStore } from "./mcp2026/auth.js";
 // ---------------------------------------------------------------------------
 // MCP elicitation bridge (§10). A server can ask US for input mid-`tools/call`
 // (a reverse-request). We map it onto the one `waitFor`: form mode → kind:"input",
@@ -224,6 +227,22 @@ async function paginateTools(client, timeout) {
     }
     throw new Error(`MCP list exceeded ${MAX_LIST_PAGES} pages`);
 }
+/** §2 `tools/call` result → ToolResult (shared by the 2026 path and the frozen fallback). */
+export function mapCallToolResult(result, server) {
+    // Parts are collected BEFORE any branch returns: the isError and structuredContent
+    // short-circuits both read `content[]` on the way past, so neither reintroduces the
+    // silent drop this mapping exists to remove (§2).
+    const parts = mcpContentToParts(result.content);
+    const withParts = (r) => (parts ? { ...r, parts } : r);
+    if (result.isError) {
+        return withParts({ output: formatToolErrorContent(result.content), isError: true, metadata: { server } });
+    }
+    if (result.structuredContent !== undefined && result.structuredContent !== null) {
+        return withParts({ output: JSON.stringify(result.structuredContent), isError: false, metadata: { server } });
+    }
+    const text = joinTextContent(result.content);
+    return withParts({ output: text || describeMcpParts(parts), isError: false, metadata: { server } });
+}
 function convertTool(server, def, client, timeout) {
     const inputSchema = {
         ...def.inputSchema,
@@ -244,19 +263,7 @@ function convertTool(server, def, client, timeout) {
                 // `resetTimeoutOnProgress` never fires (add-mcp-progress-timeout). Notifications for a
                 // token that matches no in-flight request are dropped by the SDK, so they never reset.
                 { onprogress: () => { }, resetTimeoutOnProgress: true, signal: ctx?.signal, timeout: ctx?.timeout ?? timeout });
-                // Parts are collected BEFORE any branch returns: the isError and structuredContent
-                // short-circuits both read `content[]` on the way past, so neither reintroduces the
-                // silent drop this mapping exists to remove (§2).
-                const parts = mcpContentToParts(result.content);
-                const withParts = (r) => (parts ? { ...r, parts } : r);
-                if (result.isError) {
-                    return withParts({ output: formatToolErrorContent(result.content), isError: true, metadata: { server } });
-                }
-                if (result.structuredContent !== undefined && result.structuredContent !== null) {
-                    return withParts({ output: JSON.stringify(result.structuredContent), isError: false, metadata: { server } });
-                }
-                const text = joinTextContent(result.content);
-                return withParts({ output: text || describeMcpParts(parts), isError: false, metadata: { server } });
+                return mapCallToolResult(result, server);
             }
             catch (e) {
                 return { output: e instanceof Error ? e.message : String(e), isError: true, metadata: { server } };
@@ -276,6 +283,15 @@ export function mcpHints(a) {
         h.destructive = false;
     return h;
 }
+function sdkConn(client, timeout) {
+    return {
+        listResources: async (signal) => (await client.listResources({}, { timeout, signal })).resources ?? [],
+        readResource: async (uri, signal) => (await client.readResource({ uri }, { timeout, signal })).contents ?? [],
+    };
+}
+function modernConn(s) {
+    return { listResources: (signal) => s.listResources(signal), readResource: (uri, signal) => s.readResource(uri, signal) };
+}
 function resourceTools(servers) {
     const ro = { readOnly: true, destructive: false, openWorld: false };
     const names = () => [...servers.keys()].sort();
@@ -312,8 +328,7 @@ function resourceTools(servers) {
             for (const name of targets) {
                 const c = conn(name);
                 try {
-                    const res = await c.client.listResources({}, { timeout: c.timeout, signal: ctx?.signal });
-                    for (const r of res.resources ?? []) {
+                    for (const r of await c.listResources(ctx?.signal)) {
                         let line = `${name} ${r.uri}`;
                         if (r.name)
                             line += ` — ${r.name}`;
@@ -361,9 +376,8 @@ function resourceTools(servers) {
             if (!uri)
                 return { output: "read_mcp_resource: uri is required", isError: true };
             try {
-                const res = await c.client.readResource({ uri }, { timeout: c.timeout, signal: ctx?.signal });
                 const parts = [];
-                for (const rc of res.contents ?? []) {
+                for (const rc of await c.readResource(uri, ctx?.signal)) {
                     if (typeof rc.text === "string")
                         parts.push(rc.text);
                     else if (typeof rc.blob === "string")
@@ -390,16 +404,17 @@ function newMcpClient(waitFor) {
     return client;
 }
 /** Connect an existing client's transport (remote streamable-HTTP with SSE fallback, or local stdio). */
-async function connectTransport(client, cfg) {
+async function connectTransport(client, cfg, auth) {
     if (isRemote(cfg)) {
         const url = new URL(cfg.url);
         const expanded = expandEnvHeaders(cfg.headers);
         const requestInit = expanded ? { headers: expanded } : undefined;
+        const fetch = auth ? bearerFetch(cfg.url, auth) : undefined;
         try {
-            await client.connect(new StreamableHTTPClientTransport(url, { requestInit }));
+            await client.connect(new StreamableHTTPClientTransport(url, { requestInit, ...(fetch ? { fetch } : {}) }));
         }
         catch {
-            await client.connect(new SSEClientTransport(url, { requestInit }));
+            await client.connect(new SSEClientTransport(url, { requestInit, ...(fetch ? { fetch } : {}) }));
         }
     }
     else {
@@ -414,6 +429,66 @@ async function connectTransport(client, cfg) {
         }));
     }
 }
+/**
+ * §2A.1a frozen fallback + OAuth: the SDK transport's fetch attaches the current bearer token
+ * (refreshing as needed); a 401/403 challenge runs the same OAuth flow once, then the request is
+ * re-sent. A pause is answered through waitFor, else the request fails ("authorization pending").
+ */
+function bearerFetch(resource, a) {
+    return async (input, init) => {
+        for (let attempt = 0;; attempt++) {
+            const headers = new Headers(init?.headers);
+            const tok = await a.oauth.bearer(resource);
+            if (tok)
+                headers.set("Authorization", "Bearer " + tok);
+            const res = await globalThis.fetch(input, { ...init, headers });
+            const www = res.headers.get("www-authenticate") ?? "";
+            if (attempt > 0 || (res.status !== 401 && res.status !== 403) || !www)
+                return res;
+            try {
+                await a.oauth.challenge(resource, res.status, www, tok, async () => ({}));
+            }
+            catch (e) {
+                if (!(e instanceof PendingError))
+                    throw e;
+                if (!a.waitFor)
+                    throw new Error("authorization pending");
+                const ans = await a.waitFor({ ...e.pending });
+                if (!ans?.ok)
+                    throw new Error(`authorization denied: ${ans?.reason ?? "cancelled"}`);
+                const cb = ans.data?.callbackUrl;
+                if (typeof cb !== "string")
+                    throw new Error("authorization answer carries no data.callbackUrl");
+                await a.oauth.resume(e.pending.id, cb);
+            }
+        }
+    };
+}
+/**
+ * Discover first (§2.2): a 2026 server is used directly; an old one (§2.2a) gets the frozen SDK
+ * path, with the OAuth bearer attached for remote servers. Throws ⇒ the server failed.
+ */
+async function connectServer(name, cfg, timeout, opts, store, sdkClient, onSdk) {
+    const o = { waitFor: opts.waitFor, tokenStore: store, openUrl: opts.openUrl, signal: opts.signal, disableTools: opts.disableTools };
+    const remote = isRemote(cfg);
+    const oauth = remote ? newOAuth(cfg.auth, o, store) : undefined;
+    const p = await probe({
+        name, timeout, tools: cfg.tools, toolSearch: cfg.toolSearch === true, description: cfg.description,
+        remote: remote ? { url: cfg.url, headers: expandEnvHeaders(cfg.headers), oauth: oauth } : undefined,
+        local: remote ? undefined : {
+            argv: cfg.command,
+            env: { ...process.env, ...(cfg.environment ?? cfg.env ?? {}) },
+            cwd: cfg.cwd,
+        },
+    }, o);
+    if (p.kind === "modern")
+        return p;
+    const client = sdkClient();
+    onSdk(client);
+    await raceTimeout(connectTransport(client, cfg, oauth ? { oauth, waitFor: opts.waitFor } : undefined), timeout, opts.signal);
+    const defs = await raceTimeout(paginateTools(client, timeout), timeout, opts.signal);
+    return { kind: "sdk", client, defs };
+}
 /** Connect to every enabled server, list + convert tools. Failures are isolated.
  *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
  *  whole load promptly on parent cancellation. */
@@ -423,6 +498,8 @@ export async function loadMcp(input, opts) {
     const status = {};
     const clients = [];
     const servers = new Map();
+    const skills = [];
+    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
     const waitFor = opts?.waitFor;
     const signal = opts?.signal;
     const onServer = opts?.onServer;
@@ -447,23 +524,31 @@ export async function loadMcp(input, opts) {
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        // Create the client up front so a timed-out/aborted connect still has a closeable handle
-        // (its stdio child is killed by close() — never orphaned).
-        const client = newMcpClient(waitFor);
+        // The fallback SDK client is created before its connect so a timed-out/aborted connect
+        // still has a closeable handle (its stdio child is killed by close() — never orphaned).
+        let client;
         try {
-            await raceTimeout(connectTransport(client, cfg), timeout, signal);
-            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
-            const kept = applyToolsFilter(name, defs, cfg.tools);
-            const converted = kept.map((def) => convertTool(name, def, client, timeout));
+            const c = await connectServer(name, cfg, timeout, opts ?? {}, store, () => newMcpClient(waitFor), (cl) => (client = cl));
+            let converted;
+            if (c.kind === "modern") {
+                converted = c.server.tools();
+                skills.push(...c.server.skills);
+                clients.push(c.server);
+                servers.set(name, modernConn(c.server));
+            }
+            else {
+                const kept = applyToolsFilter(name, c.defs, cfg.tools);
+                converted = kept.map((def) => convertTool(name, def, c.client, timeout));
+                clients.push(c.client);
+                servers.set(name, sdkConn(c.client, timeout));
+            }
             tools.push(...converted);
-            clients.push(client);
-            servers.set(name, { client, timeout });
             status[name] = "connected";
             report({ name, status: "connected", tools: converted });
         }
         catch (e) {
             status[name] = "failed";
-            await client.close().catch(() => { });
+            await client?.close().catch(() => { });
             // Parent cancellation/deadline aborts the whole load (§2 Gap 3, A1); a per-server timeout
             // within budget isolates just this server.
             if (signal?.aborted)
@@ -493,6 +578,7 @@ export async function loadMcp(input, opts) {
             await Promise.all(clients.map((c) => c.close().catch(() => { })));
         },
         resourceTools: () => resourceTools(servers),
+        skills,
     };
 }
 /**
@@ -504,17 +590,20 @@ export async function listMcpTools(input, opts) {
     const toolsByServer = {};
     const status = {};
     const signal = opts?.signal;
+    const store = defaultTokenStore({ tokenStore: opts?.tokenStore });
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        // Client created up front so an aborted/timed-out connect is still closed (no orphaned child).
-        const client = newMcpClient();
+        // The fallback client is created before its connect so an aborted/timed-out connect is still closed.
+        let client;
         try {
-            await raceTimeout(connectTransport(client, cfg), timeout, signal);
-            const defs = await raceTimeout(paginateTools(client, timeout), timeout, signal);
+            const c = await connectServer(name, cfg, timeout, { ...opts, waitFor: opts?.waitFor }, store, () => newMcpClient(), (cl) => (client = cl));
+            const defs = c.kind === "modern" ? c.server.rawDefs() : c.defs;
+            if (c.kind === "modern")
+                await c.server.close().catch(() => { });
             toolsByServer[name] = defs.map((d) => ({
                 name: d.name,
                 description: d.description ?? "",
@@ -529,13 +618,13 @@ export async function listMcpTools(input, opts) {
         catch (e) {
             status[name] = "failed";
             if (signal?.aborted) {
-                await client.close().catch(() => { });
+                await client?.close().catch(() => { });
                 throw e;
             }
             console.warn(`[toolnexus] MCP server "${name}" failed: ${e instanceof Error ? e.message : String(e)}`);
         }
         finally {
-            await client.close().catch(() => { });
+            await client?.close().catch(() => { });
         }
     }));
     return { tools: toolsByServer, status };

package/dist/mcp2026/auth.d.ts

@@ -0,0 +1,137 @@
+import { type HttpFn, type Obj } from "./protocol.js";
+declare const inspect: unique symbol;
+/** Bound to the issuer that minted it and the resource it is for. Never log it (it prints redacted). */
+export declare class Token {
+    accessToken: string;
+    refreshToken: string;
+    /** ms since epoch; 0 = no expiry. */
+    expiresAt: number;
+    scopes: string[];
+    issuer: string;
+    clientId: string;
+    /** The protected resource (server URI) the token is bound to. */
+    resource: string;
+    constructor(init?: Partial<Token>);
+    toString(): string;
+    toJSON(): string;
+    [inspect](): string;
+}
+/** Persists tokens per resource. Implementations must keep them confidential. Sync or async. */
+export interface TokenStore {
+    load(resource: string): Token | null | undefined | Promise<Token | null | undefined>;
+    save(resource: string, t: Token): void | Promise<void>;
+    delete(resource: string): void | Promise<void>;
+}
+export declare class MemoryTokenStore implements TokenStore {
+    private m;
+    load(r: string): Token | undefined;
+    save(r: string, t: Token): void;
+    delete(r: string): void;
+}
+/** Mirrors toolnexus SPEC §10 Request (kind "authorization"). */
+export interface Pending {
+    id: string;
+    kind: "authorization";
+    prompt: string;
+    url: string;
+    expiresAt: string;
+}
+/** Thrown instead of blocking when the authorizer pauses. Call oauth.resume(id, callbackURL). */
+export declare class PendingError extends Error {
+    pending: Pending;
+    constructor(p: Pending);
+}
+/** The Pending inside err, or undefined. */
+export declare function pendingOf(err: unknown): Pending | undefined;
+/** What a pausing AuthSession.wait throws. */
+export declare const PAUSE: Error;
+/** Decides how the user reaches the authorization URL and how the callback comes back. */
+export interface Authorizer {
+    begin(): Promise<AuthSession>;
+}
+export interface AuthSession {
+    redirectUri: string;
+    /** Resolves with the full callback URL, or throws PAUSE to hand a Pending to the caller. */
+    wait(p: Pending): Promise<string>;
+    close(): void | Promise<void>;
+}
+/** Never blocks: every authorization becomes a Pending. */
+export declare class PauseAuthorizer implements Authorizer {
+    redirect: string;
+    constructor(o: {
+        redirect: string;
+    });
+    begin(): Promise<AuthSession>;
+}
+/** Opens a browser and listens on 127.0.0.1:<random>/callback (RFC 8252 §7.3). */
+export declare class LoopbackAuthorizer implements Authorizer {
+    open: (url: string) => unknown | Promise<unknown>;
+    timeoutMs: number;
+    constructor(o?: {
+        open?: (url: string) => unknown | Promise<unknown>;
+    });
+    begin(): Promise<AuthSession>;
+}
+export interface OAuthOptions {
+    authorizer?: Authorizer;
+    clientId?: string;
+    clientSecret?: string;
+    tokenAuthMethod?: "" | "none" | "client_secret_basic" | "client_secret_post";
+    /** Drops the RFC 8707 `resource` from refresh_token requests (Entra rejects it; python-sdk #2578). */
+    omitRefreshResource?: boolean;
+    store?: TokenStore;
+    clientIds?: Record<string, string>;
+    clientMetadataUrl?: string;
+    http?: HttpFn;
+    allowHttp?: boolean;
+}
+interface AuthFlow {
+    resource: string;
+    issuer: string;
+    clientId: string;
+    redirect: string;
+    verifier: string;
+    state: string;
+    tokenEndpoint: string;
+    issSupported: boolean;
+    scopes: string[];
+    expires: number;
+    retry: () => Promise<Obj>;
+}
+/** The client-side auth engine; attach it as client.auth. */
+export declare class OAuth {
+    authorizer: Authorizer;
+    clientId: string;
+    clientSecret: string;
+    tokenAuthMethod: string;
+    omitRefreshResource: boolean;
+    store: TokenStore;
+    clientIds: Record<string, string>;
+    clientMetadataUrl: string;
+    http: HttpFn;
+    allowHttp: boolean;
+    private authMu;
+    private issuer;
+    /** @internal paused flows by pending id (exposed for tests) */
+    flows: Map<string, AuthFlow>;
+    constructor(o?: OAuthOptions);
+    /** The token to send for resource, refreshing if expired. "" = send none. */
+    bearer(resource: string): Promise<string>;
+    private refresh;
+    /** @internal Handles a 401/403. Resolves = retry the request now; throws PendingError = paused. */
+    challenge(resource: string, status: number, www: string, sent: string, retry: () => Promise<Obj>): Promise<void>;
+    /** @internal */
+    setRetry(id: string, f: () => Promise<Obj>): void;
+    /** Finishes a paused authorization and re-runs the original operation, returning its result. */
+    resume(id: string, callbackUrl: string): Promise<Obj>;
+    private complete;
+    private tokenRequest;
+    /** PRM: header URL if present, else path-inserted well-known, else root (spec: PRM Discovery Requirements). */
+    fetchPRM(resource: string, hinted: string): Promise<Obj>;
+}
+/** RFC 8414 then OIDC endpoints in the spec's order, with an issuer equality check. */
+export declare function discoverAS(httpFn: HttpFn, issuer: string): Promise<Obj>;
+/** Parses `Bearer k="v", k2=v2` (RFC 6750 §3 / RFC 9110 auth-param). */
+export declare function parseChallenge(h: string): Record<string, string>;
+export declare function randStr(n: number): string;
+export {};