toolnexus 0.24.0 → 0.25.0

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();
+    }
+}

package/dist/mcp2026/protocol.d.ts

@@ -0,0 +1,54 @@
+export declare const PROTOCOL_VERSION = "2026-07-28";
+export declare const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const META_CLIENT_CAPS = "io.modelcontextprotocol/clientCapabilities";
+export declare const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+export declare const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+export declare const SKILLS_EXT = "io.modelcontextprotocol/skills";
+export declare const CODE_METHOD_NOT_FOUND = -32601;
+export declare const CODE_INVALID_PARAMS = -32602;
+export declare const CODE_HEADER_MISMATCH = -32020;
+export declare const CODE_UNSUPPORTED_PROTOCOL = -32022;
+/** A JSON object. */
+export type Obj = Record<string, any>;
+/** A JSON-RPC error returned by the server. `httpStatus` is set when it came over HTTP. */
+export declare class RpcError extends Error {
+    code: number;
+    data?: unknown;
+    httpStatus?: number;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** A non-2xx HTTP reply that carried no JSON-RPC message. */
+export declare class HttpStatusError extends Error {
+    status: number;
+    constructor(status: number, message?: string);
+}
+/** A 2xx reply that is not a JSON-RPC response for the request (§2.2a: falls back on discover). */
+export declare class NotJsonRpcError extends Error {
+}
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface HttpRequest {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/** The seam for every outbound HTTP call. */
+export type HttpFn = (r: HttpRequest) => Promise<HttpResponse>;
+export declare function trustDevCert(pem: string): void;
+/** node:http(s) request; reads the whole body (capped at 16 MiB). Never follows redirects. */
+export declare const defaultHttp: HttpFn;
+export declare function getJSON(httpFn: HttpFn, url: string): Promise<Obj>;
+/** A small async mutex (one login / one refresh at a time). */
+export declare class Mutex {
+    private tail;
+    lock<T>(f: () => Promise<T>): Promise<T>;
+}
+/** Plain value if printable ASCII without edge whitespace, else the =?base64?…?= sentinel (§2.3). */
+export declare function encodeHeader(v: string): string;

package/dist/mcp2026/protocol.js

@@ -0,0 +1,113 @@
+/**
+ * MCP 2026-07-28 wire constants + a tiny node:http(s) layer (SPEC §2.1, §2.3). No MCP SDK.
+ * node:http instead of fetch so a per-request trust store is possible (dev authorization servers).
+ */
+import http from "node:http";
+import https from "node:https";
+import tls from "node:tls";
+export const PROTOCOL_VERSION = "2026-07-28";
+export const META_VERSION = "io.modelcontextprotocol/protocolVersion";
+export const META_CLIENT_CAPS = "io.modelcontextprotocol/clientCapabilities";
+export const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+export const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+export const SKILLS_EXT = "io.modelcontextprotocol/skills";
+export const CODE_METHOD_NOT_FOUND = -32601;
+export const CODE_INVALID_PARAMS = -32602;
+export const CODE_HEADER_MISMATCH = -32020;
+export const CODE_UNSUPPORTED_PROTOCOL = -32022;
+/** A JSON-RPC error returned by the server. `httpStatus` is set when it came over HTTP. */
+export class RpcError extends Error {
+    code;
+    data;
+    httpStatus;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        if (data !== undefined)
+            this.data = data;
+    }
+}
+/** A non-2xx HTTP reply that carried no JSON-RPC message. */
+export class HttpStatusError extends Error {
+    status;
+    constructor(status, message) {
+        super(message ?? `HTTP ${status}`);
+        this.status = status;
+    }
+}
+/** A 2xx reply that is not a JSON-RPC response for the request (§2.2a: falls back on discover). */
+export class NotJsonRpcError extends Error {
+}
+export const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_BYTES = 16 << 20;
+// Test/dev only: extra CA certificates trusted by defaultHttp (a dev authorization server's
+// self-signed certificate). Not exported from the package index.
+const extraCAs = [];
+export function trustDevCert(pem) {
+    extraCAs.push(pem);
+}
+/** node:http(s) request; reads the whole body (capped at 16 MiB). Never follows redirects. */
+export const defaultHttp = (r) => new Promise((resolve, reject) => {
+    const u = new URL(r.url);
+    const opts = { method: r.method, headers: r.headers ?? {}, agent: false };
+    if (u.protocol === "https:" && extraCAs.length)
+        opts.ca = [...tls.rootCertificates, ...extraCAs];
+    if (r.signal?.aborted)
+        return reject(r.signal.reason ?? new Error("aborted"));
+    const req = (u.protocol === "https:" ? https : http).request(u, opts, (res) => {
+        const chunks = [];
+        let n = 0;
+        res.on("data", (c) => {
+            n += c.length;
+            if (n > MAX_RESPONSE_BYTES) {
+                req.destroy(new Error("response too large"));
+                return;
+            }
+            chunks.push(c);
+        });
+        res.on("end", () => {
+            const headers = {};
+            for (const [k, v] of Object.entries(res.headers))
+                if (v !== undefined)
+                    headers[k] = Array.isArray(v) ? v.join(", ") : v;
+            resolve({ status: res.statusCode ?? 0, headers, body: Buffer.concat(chunks).toString("utf8") });
+        });
+        res.on("error", reject);
+    });
+    const onAbort = () => req.destroy(r.signal?.reason instanceof Error ? r.signal.reason : new Error("aborted"));
+    r.signal?.addEventListener("abort", onAbort, { once: true });
+    req.on("close", () => r.signal?.removeEventListener("abort", onAbort));
+    req.setTimeout(r.timeoutMs ?? DEFAULT_TIMEOUT_MS, () => req.destroy(new Error(`request to ${u.host} timed out`)));
+    req.on("error", reject);
+    req.end(r.body);
+});
+export async function getJSON(httpFn, url) {
+    const res = await httpFn({ method: "GET", url, headers: { Accept: "application/json" } });
+    if (res.status !== 200)
+        throw new Error(`GET ${url}: HTTP ${res.status}`);
+    const v = JSON.parse(res.body);
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw new Error(`GET ${url}: not a JSON object`);
+    return v;
+}
+/** A small async mutex (one login / one refresh at a time). */
+export class Mutex {
+    tail = Promise.resolve();
+    async lock(f) {
+        let release;
+        const prev = this.tail;
+        this.tail = new Promise((r) => (release = r));
+        await prev;
+        try {
+            return await f();
+        }
+        finally {
+            release();
+        }
+    }
+}
+/** Plain value if printable ASCII without edge whitespace, else the =?base64?…?= sentinel (§2.3). */
+export function encodeHeader(v) {
+    const safe = v === v.trim() && !(v.startsWith("=?base64?") && v.endsWith("?=")) && /^[\x20-\x7e]*$/.test(v);
+    return safe ? v : "=?base64?" + Buffer.from(v, "utf8").toString("base64") + "?=";
+}

package/dist/mcp2026/skills.d.ts

@@ -0,0 +1,5 @@
+/** Splits skill://<name>/<path> into a validated name and slash-separated relative path. Throws on anything unsafe. */
+export declare function parseSkillURI(uri: string): {
+    name: string;
+    rel: string;
+};

package/dist/mcp2026/skills.js

@@ -0,0 +1,25 @@
+// Skill URI safety (python-sdk #3685): a skill:// URI is percent-decoded ONCE, then rejected if it
+// still contains '%' (double encoding), a backslash, NUL, an absolute/empty path, or a "."/".."
+// segment. Both the server (before lookup) and the client (before writing files) use it.
+/** Splits skill://<name>/<path> into a validated name and slash-separated relative path. Throws on anything unsafe. */
+export function parseSkillURI(uri) {
+    if (typeof uri !== "string" || !uri.startsWith("skill://"))
+        throw new Error("not a skill:// URI");
+    let dec;
+    try {
+        dec = decodeURIComponent(uri.slice("skill://".length));
+    }
+    catch {
+        throw new Error("bad percent-encoding");
+    }
+    if (/[%\\\x00]/.test(dec))
+        throw new Error("skill URI has encoded, backslash or NUL characters");
+    const segs = dec.split("/");
+    if (segs.length < 2)
+        throw new Error("skill URI needs skill://<name>/<path>");
+    for (const s of segs) {
+        if (s === "" || s === "." || s === ".." || s.includes(":"))
+            throw new Error("skill URI path escapes the skill (empty, '.', '..' or ':' segment)");
+    }
+    return { name: segs[0], rel: segs.slice(1).join("/") };
+}

package/dist/mcp2026/source.d.ts

@@ -0,0 +1,86 @@
+import { Mcp2026Client } from "./client.js";
+import { type Obj } from "./protocol.js";
+import { OAuth, type TokenStore } from "./auth.js";
+import type { Answer, Request, Tool, ToolContext, ToolResult } from "../types.js";
+import type { SkillDef } from "../skill.js";
+export type WaitFor = (request: Request) => Promise<Answer>;
+/** Per-server `auth` (§2A.1; keys camelCase as in mcp.json). */
+export interface AuthConfig {
+    clientId?: string;
+    clientSecret?: string;
+    tokenAuthMethod?: "client_secret_basic" | "client_secret_post";
+    clientIds?: Record<string, string>;
+    clientMetadataUrl?: string;
+    redirectUri?: string;
+    mode?: "auto" | "pause";
+    omitRefreshResource?: boolean;
+    allowHttp?: boolean;
+}
+export interface Load2026Options {
+    waitFor?: WaitFor;
+    tokenStore?: TokenStore;
+    openUrl?: (url: string) => unknown | Promise<unknown>;
+    signal?: AbortSignal;
+    /** Final exposed names to drop (Toolkit `disableTools`); applied before tool search too. */
+    disableTools?: string[];
+}
+/** The OAuth engine for one remote server (§2A.1). */
+export declare function newOAuth(auth: AuthConfig | undefined, o: Load2026Options, store: TokenStore): OAuth;
+export declare function defaultTokenStore(o: Load2026Options): TokenStore;
+/** What the probe decided. `fallback` ⇒ take the frozen SDK path; anything thrown ⇒ status failed. */
+export type Probe = {
+    kind: "modern";
+    server: ModernServer;
+} | {
+    kind: "fallback";
+};
+export interface ProbeTarget {
+    name: string;
+    timeout: number;
+    tools?: Record<string, boolean>;
+    toolSearch?: boolean;
+    description?: string;
+    remote?: {
+        url: string;
+        headers?: Record<string, string>;
+        oauth: OAuth;
+    };
+    local?: {
+        argv: string[];
+        env: NodeJS.ProcessEnv;
+        cwd?: string;
+    };
+}
+/** Discover first (§2.2). Resolves `modern` (tools listed) or `fallback`; throws on a load failure. */
+export declare function probe(t: ProbeTarget, o: Load2026Options): Promise<Probe>;
+export declare class ModernServer {
+    private t;
+    private o;
+    readonly client: Mcp2026Client;
+    readonly discover: Obj;
+    defs: Obj[];
+    skills: SkillDef[];
+    private all;
+    private cacheUntil;
+    private pend;
+    constructor(t: ProbeTarget, client: Mcp2026Client, disc: Obj, o: Load2026Options);
+    private get oauth();
+    private req;
+    load(): Promise<void>;
+    private refreshTools;
+    private loadSkills;
+    /** The toolkit tools for this server: every (filtered) server tool, or the two tool-search tools. */
+    tools(): Tool[];
+    private convert;
+    /** tools/call with MRTR rounds (§2.5) and OAuth pauses (§2A.1 10); never re-sends after a failure (§2.6). */
+    run(name: string, args: Obj, ctx?: ToolContext): Promise<ToolResult>;
+    private suspend;
+    private drive;
+    private toRequest;
+    /** resources/list for list_mcp_resources (§4C). */
+    listResources(signal?: AbortSignal): Promise<Obj[]>;
+    readResource(uri: string, signal?: AbortSignal): Promise<Obj[]>;
+    /** Raw (unfiltered) tool defs, for listMcpTools. */
+    rawDefs(): Obj[];
+    close(): Promise<void>;
+}