toolnexus 0.24.0 → 0.26.0

package/dist/mcp2026/auth.js

@@ -0,0 +1,446 @@
+// Client-side OAuth for MCP 2026-07-28 (basic/authorization). Node stdlib only.
+// Flow: 401/403 -> WWW-Authenticate -> PRM (RFC 9728) -> AS metadata (RFC 8414 / OIDC)
+// -> client id (pre-registered | CIMD) -> code + PKCE S256 + resource (RFC 8707)
+// -> iss (RFC 9207) + state check -> token -> retry with Bearer.
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import http from "node:http";
+import { defaultHttp, getJSON, Mutex } from "./protocol.js";
+function closeServer(hs) {
+    return new Promise((r) => {
+        hs.close(() => r());
+        hs.closeAllConnections();
+    });
+}
+const inspect = Symbol.for("nodejs.util.inspect.custom");
+/** Bound to the issuer that minted it and the resource it is for. Never log it (it prints redacted). */
+export class Token {
+    accessToken = "";
+    refreshToken = "";
+    /** ms since epoch; 0 = no expiry. */
+    expiresAt = 0;
+    scopes = [];
+    issuer = "";
+    clientId = "";
+    /** The protected resource (server URI) the token is bound to. */
+    resource = "";
+    constructor(init = {}) {
+        Object.assign(this, init);
+    }
+    toString() {
+        return `Token{issuer=${this.issuer}, redacted}`;
+    }
+    toJSON() {
+        return this.toString();
+    }
+    [inspect]() {
+        return this.toString();
+    }
+}
+export class MemoryTokenStore {
+    m = new Map();
+    load(r) { return this.m.get(r); }
+    save(r, t) { this.m.set(r, t); }
+    delete(r) { this.m.delete(r); }
+}
+/** Thrown instead of blocking when the authorizer pauses. Call oauth.resume(id, callbackURL). */
+export class PendingError extends Error {
+    pending;
+    constructor(p) {
+        super("authorization pending: " + p.prompt);
+        this.pending = p;
+    }
+}
+/** The Pending inside err, or undefined. */
+export function pendingOf(err) {
+    return err instanceof PendingError ? err.pending : undefined;
+}
+/** What a pausing AuthSession.wait throws. */
+export const PAUSE = new Error("authorization paused");
+/** Never blocks: every authorization becomes a Pending. */
+export class PauseAuthorizer {
+    redirect;
+    constructor(o) {
+        this.redirect = o.redirect;
+    }
+    async begin() {
+        return { redirectUri: this.redirect, wait: async () => { throw PAUSE; }, close: () => { } };
+    }
+}
+/** Opens a browser and listens on 127.0.0.1:<random>/callback (RFC 8252 §7.3). */
+export class LoopbackAuthorizer {
+    open; // default = system browser
+    timeoutMs = 5 * 60_000;
+    constructor(o = {}) {
+        this.open = o.open ?? openBrowser;
+    }
+    async begin() {
+        let deliver;
+        const cb = new Promise((r) => (deliver = r));
+        const hs = http.createServer((req, res) => {
+            if (new URL(req.url ?? "/", "http://x").pathname !== "/callback")
+                return void res.writeHead(404).end();
+            deliver(`http://${req.headers.host}${req.url}`);
+            res.end("Authorization received. You can close this window.");
+        });
+        await new Promise((r, j) => hs.once("error", j).listen(0, "127.0.0.1", () => r()));
+        const port = hs.address().port;
+        const timeoutMs = this.timeoutMs;
+        const open = this.open;
+        return {
+            redirectUri: `http://127.0.0.1:${port}/callback`,
+            close: () => closeServer(hs),
+            async wait(p) {
+                let timer;
+                const timeout = new Promise((_, j) => (timer = setTimeout(() => j(new Error("authorization timed out")), timeoutMs)));
+                // the opener may block (tests follow redirects synchronously); a failed opener must not leave
+                // us waiting 5 minutes for a callback that cannot come
+                const opened = Promise.resolve().then(() => open(p.url)).then(() => cb, (e) => { throw new Error(`open authorization URL: ${e?.message ?? e}`); });
+                try {
+                    return await Promise.race([cb, opened, timeout]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
+        };
+    }
+}
+function openBrowser(u) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [u]] : process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", u]] : ["xdg-open", [u]];
+    return new Promise((r, j) => spawn(cmd, args, { stdio: "ignore", detached: true }).once("error", j).once("spawn", r).unref());
+}
+/** The client-side auth engine; attach it as client.auth. */
+export class OAuth {
+    authorizer;
+    clientId;
+    clientSecret;
+    tokenAuthMethod;
+    omitRefreshResource;
+    store;
+    clientIds;
+    clientMetadataUrl;
+    http;
+    allowHttp;
+    authMu = new Mutex(); // serialises refresh + interactive authorization
+    issuer = new Map(); // resource -> discovered issuer (only then do we send a stored token)
+    /** @internal paused flows by pending id (exposed for tests) */
+    flows = new Map();
+    constructor(o = {}) {
+        this.authorizer = o.authorizer ?? new LoopbackAuthorizer();
+        this.clientId = o.clientId ?? "";
+        this.clientSecret = o.clientSecret ?? "";
+        this.tokenAuthMethod = o.tokenAuthMethod ?? "";
+        this.omitRefreshResource = o.omitRefreshResource ?? false;
+        this.store = o.store ?? new MemoryTokenStore();
+        this.clientIds = o.clientIds ?? {};
+        this.clientMetadataUrl = o.clientMetadataUrl ?? "";
+        this.http = o.http ?? defaultHttp;
+        this.allowHttp = o.allowHttp ?? false;
+    }
+    /** The token to send for resource, refreshing if expired. "" = send none. */
+    async bearer(resource) {
+        const iss = this.issuer.get(resource);
+        let t = (await this.store.load(resource)) ?? undefined;
+        if (!t || !iss || t.issuer !== iss)
+            return ""; // only tokens from this server's AS (spec: Token Handling)
+        if (expired(t)) {
+            // one refresh for N concurrent callers (refresh tokens rotate: a 2nd refresh would fail)
+            return this.authMu.lock(async () => {
+                let cur = (await this.store.load(resource)) ?? undefined;
+                if (!cur)
+                    return "";
+                if (expired(cur)) {
+                    try {
+                        await this.refresh(cur);
+                    }
+                    catch {
+                        return "";
+                    }
+                    cur = (await this.store.load(resource)) ?? undefined;
+                }
+                return cur?.accessToken ?? "";
+            });
+        }
+        return t.accessToken;
+    }
+    async refresh(t) {
+        if (!t.refreshToken)
+            throw new Error("no refresh token");
+        const md = await discoverAS(this.http, t.issuer);
+        const form = new URLSearchParams({ grant_type: "refresh_token", refresh_token: t.refreshToken, client_id: t.clientId });
+        if (!this.omitRefreshResource)
+            form.set("resource", t.resource);
+        let nt;
+        try {
+            nt = await this.tokenRequest(String(md.token_endpoint ?? ""), form, t.issuer, t.resource, t.clientId, t.scopes);
+        }
+        catch (e) {
+            await this.store.delete(t.resource);
+            throw e;
+        }
+        if (!nt.refreshToken)
+            nt.refreshToken = t.refreshToken;
+        await this.store.save(t.resource, nt);
+    }
+    /** @internal Handles a 401/403. Resolves = retry the request now; throws PendingError = paused. */
+    challenge(resource, status, www, sent, retry) {
+        const params = parseChallenge(www);
+        // N concurrent 401s -> one authorization, the rest retry with its token
+        return this.authMu.lock(async () => {
+            let cur = (await this.store.load(resource)) ?? undefined;
+            const known = this.issuer.get(resource);
+            if (cur && known && cur.issuer === known && cur.accessToken !== sent && !expired(cur))
+                return; // someone else refreshed/authorized meanwhile
+            if (status === 401 && cur?.refreshToken && params.error === "invalid_token") {
+                try {
+                    await this.refresh(cur);
+                    return;
+                }
+                catch {
+                    cur = undefined;
+                }
+            }
+            if (status === 403 && params.error !== "insufficient_scope")
+                throw new Error(`forbidden: ${params.error ?? ""}`);
+            const prm = await this.fetchPRM(resource, params.resource_metadata ?? "");
+            const servers = Array.isArray(prm.authorization_servers) ? prm.authorization_servers : [];
+            if (servers.length === 0)
+                throw new Error("PRM lists no authorization_servers");
+            const issuer = String(servers[0]); // RFC 9728 §7.6: client's choice; we take the first
+            if (!this.allowHttp && !issuer.startsWith("https://"))
+                throw new Error("authorization server must use https");
+            const md = await discoverAS(this.http, issuer);
+            const methods = md.code_challenge_methods_supported;
+            if (!Array.isArray(methods) || !methods.includes("S256"))
+                throw new Error("authorization server does not advertise PKCE S256; refusing");
+            this.issuer.set(resource, issuer);
+            if (status === 401 && cur && cur.issuer === issuer && !params.error)
+                return; // first request after restart: issuer now known
+            // Scope selection: challenge scope, else scopes_supported; on step-up union with previous.
+            let scopes = (params.scope ?? "").split(/\s+/).filter(Boolean);
+            if (scopes.length === 0)
+                scopes = strings(prm.scopes_supported);
+            if (cur && status === 403)
+                for (const s of cur.scopes)
+                    if (!scopes.includes(s))
+                        scopes.push(s);
+            let clientId = this.clientIds[issuer] || this.clientId;
+            const cimd = md.client_id_metadata_document_supported === true;
+            if (!clientId && this.clientMetadataUrl && cimd)
+                clientId = this.clientMetadataUrl;
+            if (!clientId) {
+                // no DCR, ever: the user registers an app once and configures its id
+                const why = cimd ? "auth.clientMetadataUrl is not set" : "it does not support Client ID Metadata Documents";
+                throw new Error(`no client identity for ${issuer}: ${why} and no client id is configured — register an app with ${issuer} and set auth.clientId (dynamic client registration is not supported)`);
+            }
+            const sess = await this.authorizer.begin();
+            const f = {
+                resource, issuer, clientId, redirect: sess.redirectUri, verifier: randStr(32), state: randStr(16),
+                tokenEndpoint: String(md.token_endpoint ?? ""), scopes, retry,
+                issSupported: md.authorization_response_iss_parameter_supported === true, expires: Date.now() + 10 * 60_000,
+            };
+            const q = new URLSearchParams({
+                response_type: "code", client_id: clientId, redirect_uri: f.redirect, state: f.state,
+                code_challenge: createHash("sha256").update(f.verifier).digest("base64url"), code_challenge_method: "S256", resource,
+            });
+            if (scopes.length)
+                q.set("scope", scopes.join(" "));
+            const p = {
+                id: "auth-" + randStr(12), kind: "authorization", url: String(md.authorization_endpoint ?? "") + "?" + q.toString(),
+                prompt: "Authorize access to " + resource, expiresAt: new Date(f.expires).toISOString().replace(/\.\d+Z$/, "Z"),
+            };
+            let cb;
+            try {
+                cb = await sess.wait(p);
+            }
+            catch (e) {
+                if (e === PAUSE) {
+                    const now = Date.now();
+                    for (const [id, old] of this.flows)
+                        if (now > old.expires)
+                            this.flows.delete(id); // drop abandoned pendings
+                    this.flows.set(p.id, f);
+                    throw new PendingError(p);
+                }
+                await sess.close();
+                throw e;
+            }
+            await sess.close();
+            await this.complete(f, cb);
+        });
+    }
+    /** @internal */
+    setRetry(id, f) {
+        const fl = this.flows.get(id);
+        if (fl)
+            fl.retry = f;
+    }
+    /** Finishes a paused authorization and re-runs the original operation, returning its result. */
+    async resume(id, callbackUrl) {
+        const f = this.flows.get(id);
+        this.flows.delete(id);
+        if (!f)
+            throw new Error(`unknown pending authorization "${id}"`);
+        if (Date.now() > f.expires)
+            throw new Error("pending authorization expired");
+        await this.complete(f, callbackUrl);
+        return f.retry();
+    }
+    async complete(f, callbackUrl) {
+        const q = new URL(callbackUrl).searchParams;
+        // RFC 9207 §2.4 table (spec: Authorization Response Validation) — before anything else, error responses included.
+        if (q.has("iss")) {
+            if (q.get("iss") !== f.issuer)
+                throw new Error("authorization response iss mismatch (possible mix-up attack)"); // no normalization
+        }
+        else if (f.issSupported)
+            throw new Error("authorization response missing iss");
+        if ((q.get("state") ?? "") !== f.state)
+            throw new Error("authorization response state mismatch");
+        const err = q.get("error");
+        if (err)
+            throw new Error(`authorization denied: ${err}`);
+        const t = await this.tokenRequest(f.tokenEndpoint, new URLSearchParams({
+            grant_type: "authorization_code", code: q.get("code") ?? "", redirect_uri: f.redirect,
+            client_id: f.clientId, code_verifier: f.verifier, resource: f.resource,
+        }), f.issuer, f.resource, f.clientId, f.scopes);
+        await this.store.save(f.resource, t);
+    }
+    async tokenRequest(ep, form, issuer, resource, clientId, scopes) {
+        let method = this.tokenAuthMethod;
+        if (clientId === this.clientMetadataUrl || !this.clientSecret)
+            method = "none"; // CIMD + secretless clients are public
+        else if (!method)
+            method = "client_secret_basic";
+        if (method === "client_secret_post")
+            form.set("client_secret", this.clientSecret);
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json", // GitHub answers form-encoded without it
+        };
+        if (method === "client_secret_basic") {
+            form.delete("client_id"); // RFC 6749 §2.3.1: authenticate with one method only
+            headers.Authorization = "Basic " + Buffer.from(formEscape(clientId) + ":" + formEscape(this.clientSecret)).toString("base64");
+        }
+        const resp = await this.http({ method: "POST", url: ep, headers, body: form.toString() });
+        let tr;
+        try {
+            tr = JSON.parse(resp.body);
+        }
+        catch {
+            if ((resp.headers["content-type"] ?? "").startsWith("application/x-www-form-urlencoded")) {
+                // RFC 6749 §5.1 mandates JSON, but some ASes (GitHub) still default to form encoding.
+                tr = Object.fromEntries(new URLSearchParams(resp.body));
+            }
+        }
+        if (!tr || resp.status !== 200 || !tr.access_token) {
+            throw new Error(`token endpoint: HTTP ${resp.status} ${typeof tr?.error === "string" ? tr.error : ""}`); // never include the body
+        }
+        const t = new Token({ accessToken: String(tr.access_token), refreshToken: String(tr.refresh_token ?? ""), issuer, resource, clientId, scopes });
+        if (typeof tr.scope === "string" && tr.scope)
+            t.scopes = tr.scope.split(/\s+/).filter(Boolean);
+        const ei = Number(tr.expires_in);
+        if (ei > 0)
+            t.expiresAt = Date.now() + ei * 1000;
+        return t;
+    }
+    /** PRM: header URL if present, else path-inserted well-known, else root (spec: PRM Discovery Requirements). */
+    async fetchPRM(resource, hinted) {
+        let cands = [hinted];
+        if (!hinted) {
+            const u = new URL(resource);
+            const root = `${u.protocol}//${u.host}/.well-known/oauth-protected-resource`;
+            const p = u.pathname.replace(/\/$/, "");
+            cands = p ? [root + p, root] : [root];
+        }
+        let last;
+        for (const c of cands) {
+            let m;
+            try {
+                m = await getJSON(this.http, c);
+            }
+            catch (e) {
+                last = e;
+                continue;
+            }
+            if (m.resource !== resource)
+                throw new Error(`PRM resource ${m.resource} does not match ${resource}`); // RFC 9728 §3.3
+            return m;
+        }
+        throw new Error(`protected resource metadata: ${last?.message ?? last}`);
+    }
+}
+function expired(t) {
+    return t.expiresAt > 0 && Date.now() > t.expiresAt - 10_000;
+}
+/** RFC 8414 then OIDC endpoints in the spec's order, with an issuer equality check. */
+export async function discoverAS(httpFn, issuer) {
+    const u = new URL(issuer);
+    const base = `${u.protocol}//${u.host}`;
+    const p = u.pathname.replace(/\/$/, "");
+    const cands = p
+        ? [base + "/.well-known/oauth-authorization-server" + p, base + "/.well-known/openid-configuration" + p, base + p + "/.well-known/openid-configuration"]
+        : [base + "/.well-known/oauth-authorization-server", base + "/.well-known/openid-configuration"];
+    for (const c of cands) {
+        let m;
+        try {
+            m = await getJSON(httpFn, c);
+        }
+        catch {
+            continue;
+        }
+        if (m.issuer !== issuer)
+            throw new Error(`AS metadata issuer ${m.issuer} != ${issuer}`);
+        return m;
+    }
+    throw new Error(`no authorization server metadata for ${issuer}`);
+}
+/** Parses `Bearer k="v", k2=v2` (RFC 6750 §3 / RFC 9110 auth-param). */
+export function parseChallenge(h) {
+    const out = {};
+    h = h.trim();
+    if (h.startsWith("Bearer"))
+        h = h.slice(6);
+    h = h.trim();
+    while (h) {
+        const eq = h.indexOf("=");
+        if (eq < 0)
+            break;
+        const k = h.slice(0, eq).trim().toLowerCase();
+        h = h.slice(eq + 1).trim();
+        let v;
+        if (h.startsWith('"')) {
+            let end = 1;
+            while (end < h.length && h[end] !== '"') {
+                if (h[end] === "\\")
+                    end++;
+                end++;
+            }
+            v = h.slice(1, Math.min(end, h.length)).replaceAll('\\"', '"');
+            h = h.slice(Math.min(end + 1, h.length));
+        }
+        else {
+            let end = h.indexOf(",");
+            if (end < 0)
+                end = h.length;
+            v = h.slice(0, end).trim();
+            h = h.slice(end);
+        }
+        out[k] = v;
+        h = h.trim();
+        if (h.startsWith(","))
+            h = h.slice(1);
+        h = h.trim();
+    }
+    return out;
+}
+function strings(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+function formEscape(s) {
+    return new URLSearchParams({ x: s }).toString().slice(2);
+}
+export function randStr(n) {
+    return randomBytes(n).toString("base64url");
+}

package/dist/mcp2026/client.d.ts

@@ -0,0 +1,48 @@
+import { type HttpFn, type Obj } from "./protocol.js";
+import type { OAuth } from "./auth.js";
+/** The transport behind a stdio client (stdio.ts). */
+export interface Transport {
+    roundTrip(id: number, body: string, timeoutMs: number, signal?: AbortSignal): Promise<Obj>;
+    close(): Promise<void>;
+}
+export interface CallOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export declare class Mcp2026Client {
+    readonly url: string;
+    info: Obj;
+    caps: Obj;
+    http: HttpFn;
+    headers: Record<string, string>;
+    auth?: OAuth;
+    timeoutMs: number;
+    transport?: Transport;
+    private nextId;
+    constructor(url: string, o?: {
+        headers?: Record<string, string>;
+        auth?: OAuth;
+        timeoutMs?: number;
+        transport?: Transport;
+    });
+    /** Sends one request; params gets the per-request _meta merged in. Throws RpcError on a JSON-RPC error. */
+    call(method: string, params?: Obj, o?: CallOptions): Promise<Obj>;
+    private httpRoundTrip;
+    private post;
+    /** tools/list (one page — no nextCursor on the 2026 path, §2.9). Returns the tools and the ttlMs hint. */
+    listTools(o?: CallOptions): Promise<{
+        tools: Obj[];
+        ttlMs?: number;
+    }>;
+    /**
+     * One remote skill (§2.7) as a data skill: skills/get, then resources/read of its SKILL.md (sha256
+     * verified). Every resource URI must be inside the skill. Returns the raw SKILL.md text and the
+     * other resources' relative paths.
+     */
+    fetchSkill(uri: string, o?: CallOptions): Promise<{
+        name: string;
+        markdown: string;
+        resources: string[];
+    }>;
+    close(): Promise<void>;
+}

package/dist/mcp2026/client.js

@@ -0,0 +1,160 @@
+/**
+ * Stateless MCP 2026-07-28 client (SPEC §2.2–§2.7): Streamable HTTP or stdio, one API.
+ * Never sends `initialize`; no session; never re-sends a request except after a pre-dispatch
+ * 401/403 auth rejection (§2.6).
+ */
+import { createHash } from "node:crypto";
+import { defaultHttp, encodeHeader, HttpStatusError, META_CLIENT_CAPS, META_CLIENT_INFO, META_VERSION, NotJsonRpcError, PROTOCOL_VERSION, RpcError, DEFAULT_TIMEOUT_MS, } from "./protocol.js";
+import { parseSkillURI } from "./skills.js";
+export class Mcp2026Client {
+    url;
+    info = { name: "toolnexus", version: "0.1.0" };
+    caps = { elicitation: { form: {} } };
+    http = defaultHttp;
+    headers;
+    auth;
+    timeoutMs;
+    transport;
+    nextId = 0;
+    constructor(url, o = {}) {
+        this.url = url;
+        this.headers = o.headers ?? {};
+        this.auth = o.auth;
+        this.timeoutMs = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.transport = o.transport;
+    }
+    /** Sends one request; params gets the per-request _meta merged in. Throws RpcError on a JSON-RPC error. */
+    async call(method, params = {}, o = {}) {
+        params = { ...params, _meta: { ...(params._meta ?? {}), [META_VERSION]: PROTOCOL_VERSION, [META_CLIENT_CAPS]: this.caps, [META_CLIENT_INFO]: this.info } };
+        const id = ++this.nextId;
+        const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+        const timeoutMs = o.timeoutMs ?? this.timeoutMs;
+        const msg = this.transport ? await this.transport.roundTrip(id, body, timeoutMs, o.signal) : await this.httpRoundTrip(method, params, body, timeoutMs, o.signal);
+        if (msg.error != null) {
+            const e = msg.error;
+            const err = new RpcError(Number(e.code), String(e.message ?? ""), e.data);
+            if (msg.__status)
+                err.httpStatus = msg.__status;
+            throw err;
+        }
+        const r = msg.result;
+        if (!r || typeof r !== "object" || Array.isArray(r))
+            throw new NotJsonRpcError("response has neither result nor error");
+        if (!("resultType" in r))
+            r.resultType = "complete";
+        if (r.resultType !== "complete" && r.resultType !== "input_required")
+            throw new Error(`unsupported resultType "${String(r.resultType)}"`);
+        return r;
+    }
+    async httpRoundTrip(method, params, body, timeoutMs, signal) {
+        let resp;
+        for (let attempt = 0;; attempt++) {
+            const sent = this.auth ? await this.auth.bearer(this.url) : "";
+            resp = await this.post(method, params, body, sent, timeoutMs, signal); // a network error is never retried
+            const www = resp.headers["www-authenticate"] ?? "";
+            if (!this.auth || (resp.status !== 401 && resp.status !== 403) || !www)
+                break;
+            if (attempt >= 3)
+                throw new Error(`authorization failed: HTTP ${resp.status} after ${attempt + 1} attempts`);
+            await this.auth.challenge(this.url, resp.status, www, sent, () => this.call(method, params, { timeoutMs, signal }));
+        }
+        let msg;
+        if ((resp.headers["content-type"] ?? "").startsWith("text/event-stream")) {
+            // The last data: payload carrying a result or error is the final response.
+            for (const line of resp.body.split(/\r?\n/)) {
+                if (!line.startsWith("data:"))
+                    continue;
+                try {
+                    const m = JSON.parse(line.slice(5));
+                    if (m && (m.result !== undefined || m.error !== undefined))
+                        msg = m;
+                }
+                catch {
+                    /* not JSON: ignore */
+                }
+            }
+        }
+        else {
+            try {
+                msg = JSON.parse(resp.body);
+            }
+            catch {
+                msg = undefined;
+            }
+        }
+        const ok = resp.status >= 200 && resp.status < 300;
+        const isMsg = !!msg && typeof msg === "object" && (msg.result != null || (msg.error != null && typeof msg.error === "object" && typeof msg.error.code === "number"));
+        if (!isMsg) {
+            if (!ok)
+                throw new HttpStatusError(resp.status);
+            throw new NotJsonRpcError(`HTTP ${resp.status}: response is not a JSON-RPC response`);
+        }
+        if (!ok && msg.error == null)
+            throw new HttpStatusError(resp.status);
+        return { ...msg, __status: ok ? undefined : resp.status };
+    }
+    post(method, params, body, bearer, timeoutMs, signal) {
+        const h = {
+            ...this.headers,
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            "MCP-Protocol-Version": PROTOCOL_VERSION,
+            "Mcp-Method": method,
+        };
+        if (method === "tools/call" || method === "prompts/get")
+            h["Mcp-Name"] = encodeHeader(String(params.name ?? ""));
+        if (method === "resources/read")
+            h["Mcp-Name"] = encodeHeader(String(params.uri ?? ""));
+        if (bearer)
+            h.Authorization = "Bearer " + bearer;
+        return this.http({ method: "POST", url: this.url, headers: h, body, timeoutMs, signal });
+    }
+    /** tools/list (one page — no nextCursor on the 2026 path, §2.9). Returns the tools and the ttlMs hint. */
+    async listTools(o = {}) {
+        const r = await this.call("tools/list", {}, o);
+        const tools = (Array.isArray(r.tools) ? r.tools : []).filter((t) => t && typeof t === "object" && typeof t.name === "string");
+        return { tools, ttlMs: typeof r.ttlMs === "number" ? r.ttlMs : undefined };
+    }
+    /**
+     * One remote skill (§2.7) as a data skill: skills/get, then resources/read of its SKILL.md (sha256
+     * verified). Every resource URI must be inside the skill. Returns the raw SKILL.md text and the
+     * other resources' relative paths.
+     */
+    async fetchSkill(uri, o = {}) {
+        const { name } = parseSkillURI(uri);
+        const r = await this.call("skills/get", { uri }, o);
+        const res = Array.isArray(r.skill?.resources) ? r.skill.resources : [];
+        const others = [];
+        let md;
+        for (const m of res) {
+            const fu = String(m?.uri ?? "");
+            let rel;
+            try {
+                const p = parseSkillURI(fu);
+                if (p.name !== name)
+                    throw new Error();
+                rel = p.rel;
+            }
+            catch {
+                throw new Error(`refusing skill resource "${fu}": outside skill ${name}`);
+            }
+            if (rel === "SKILL.md")
+                md = m;
+            else
+                others.push(rel);
+        }
+        const mdUri = md ? String(md.uri) : uri;
+        const rr = await this.call("resources/read", { uri: mdUri }, o);
+        const cs = Array.isArray(rr.contents) ? rr.contents : [];
+        if (cs.length === 0)
+            throw new Error(`${mdUri}: empty resources/read`);
+        const text = typeof cs[0]?.text === "string" ? cs[0].text : "";
+        const d = typeof md?.digest === "string" ? md.digest : "";
+        if (d && d !== "sha256:" + createHash("sha256").update(text).digest("hex"))
+            throw new Error(`${mdUri}: digest mismatch`);
+        return { name, markdown: text, resources: others.sort() };
+    }
+    async close() {
+        await this.transport?.close();
+    }
+}