toolnexus 0.24.0 → 0.25.0

package/dist/mcp2026/source.js

@@ -0,0 +1,372 @@
+/**
+ * The 2026-07-28 direct path behind loadMcp (SPEC §2.2–§2.8, §2A): discover first, then tools,
+ * skills and tool search; MRTR and OAuth pauses surface through §10 (waitFor inline, or a
+ * `{status:"pending"}` suspension resumed via `ctx.answer`). `probe` reports `fallback` when the
+ * server is pre-2026 so loadMcp takes the frozen SDK path (§2.F).
+ */
+import { randomBytes } from "node:crypto";
+import { Mcp2026Client } from "./client.js";
+import { HttpStatusError, NotJsonRpcError, PROTOCOL_VERSION, RpcError, SKILLS_EXT } from "./protocol.js";
+import { LoopbackAuthorizer, MemoryTokenStore, OAuth, PauseAuthorizer, PendingError } from "./auth.js";
+import { spawnStdio, StdioClosedError } from "./stdio.js";
+import { rank } from "./toolsearch.js";
+import { sanitize } from "../types.js";
+import { answerToElicitResult, elicitationToRequest, mapCallToolResult, mcpHints } from "../mcp.js";
+/** The OAuth engine for one remote server (§2A.1). */
+export function newOAuth(auth, o, store) {
+    const a = auth ?? {};
+    const mode = a.mode ?? "auto";
+    let authorizer;
+    if (mode === "pause") {
+        if (!a.redirectUri)
+            throw new Error("auth.redirectUri is required for pause mode");
+        authorizer = new PauseAuthorizer({ redirect: a.redirectUri });
+    }
+    else {
+        authorizer = new LoopbackAuthorizer(o.openUrl ? { open: o.openUrl } : {});
+    }
+    return new OAuth({
+        authorizer, store,
+        clientId: a.clientId, clientSecret: a.clientSecret, tokenAuthMethod: a.tokenAuthMethod,
+        clientIds: a.clientIds, clientMetadataUrl: a.clientMetadataUrl,
+        omitRefreshResource: a.omitRefreshResource, allowHttp: a.allowHttp,
+    });
+}
+export function defaultTokenStore(o) {
+    return o.tokenStore ?? new MemoryTokenStore();
+}
+function deniedError(a) {
+    return new Error(`authorization denied: ${a?.reason ?? "cancelled"}`);
+}
+function callbackUrlOf(a) {
+    const u = a.data?.callbackUrl;
+    if (typeof u !== "string" || !u)
+        throw new Error("authorization answer carries no data.callbackUrl");
+    return u;
+}
+/** Runs f; an OAuth pause is answered inline through waitFor, else it is a load failure. */
+async function authed(oauth, waitFor, f) {
+    try {
+        return await f();
+    }
+    catch (e) {
+        if (!(e instanceof PendingError) || !oauth)
+            throw e;
+        if (!waitFor)
+            throw new Error("authorization pending");
+        const a = await waitFor({ ...e.pending });
+        if (!a?.ok)
+            throw deniedError(a);
+        // resume() stores the token (and re-sends the paused read); f() then runs again, authorized.
+        await oauth.resume(e.pending.id, callbackUrlOf(a));
+        return f();
+    }
+}
+/** §2.2a: which discover failures mean "old server". */
+function isFallbackError(e) {
+    if (e instanceof RpcError)
+        return true;
+    if (e instanceof HttpStatusError)
+        return e.status === 400 || e.status === 404 || e.status === 405 || e.status >= 500;
+    if (e instanceof NotJsonRpcError)
+        return true;
+    return false;
+}
+function supports2026(r) {
+    return Array.isArray(r.supportedVersions) && r.supportedVersions.includes(PROTOCOL_VERSION);
+}
+/** Discover first (§2.2). Resolves `modern` (tools listed) or `fallback`; throws on a load failure. */
+export async function probe(t, o) {
+    let client;
+    if (t.remote) {
+        client = new Mcp2026Client(t.remote.url, { headers: t.remote.headers, auth: t.remote.oauth, timeoutMs: t.timeout });
+    }
+    else {
+        const tr = await spawnStdio(t.local.argv, t.local.env, t.local.cwd);
+        client = new Mcp2026Client("", { transport: tr, timeoutMs: t.timeout });
+    }
+    const oauth = t.remote?.oauth;
+    let disc;
+    try {
+        // stdio: an old server may ignore a pre-initialize request ⇒ min(timeout, 5 s) then fall back.
+        const timeoutMs = t.local ? Math.min(t.timeout, 5000) : t.timeout;
+        disc = await authed(oauth, o.waitFor, () => client.call("server/discover", {}, { timeoutMs, signal: o.signal }));
+    }
+    catch (e) {
+        const stdioTimeout = !!t.local && e instanceof Error && e.message === "stdio request timed out";
+        await client.close().catch(() => { });
+        if (o.signal?.aborted)
+            throw e;
+        if (e instanceof StdioClosedError)
+            throw e;
+        if (isFallbackError(e) || stdioTimeout)
+            return { kind: "fallback" };
+        throw e;
+    }
+    if (!supports2026(disc)) {
+        await client.close().catch(() => { });
+        return { kind: "fallback" };
+    }
+    try {
+        const server = new ModernServer(t, client, disc, o);
+        await server.load();
+        return { kind: "modern", server };
+    }
+    catch (e) {
+        await client.close().catch(() => { });
+        throw e;
+    }
+}
+/** §2 Gap 7 filter over raw defs (same semantics as the frozen path). */
+function filterDefs(server, defs, filter) {
+    if (!filter)
+        return defs;
+    const keys = Object.keys(filter);
+    if (keys.length === 0)
+        return defs;
+    const hasTrue = keys.some((k) => filter[k] === true);
+    const present = new Set(defs.map((d) => d.name));
+    for (const k of keys)
+        if (!present.has(k))
+            console.warn(`[toolnexus] server "${server}" tools filter name "${k}" matched no tool`);
+    return defs.filter((d) => (hasTrue ? filter[d.name] === true : filter[d.name] !== false));
+}
+function parseFrontmatter(md) {
+    const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!m)
+        return { data: {}, body: md };
+    const data = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        if (/^\s/.test(line))
+            continue;
+        const i = line.indexOf(":");
+        if (i <= 0)
+            continue;
+        let v = line.slice(i + 1).trim();
+        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))
+            v = v.slice(1, -1);
+        data[line.slice(0, i).trim()] = v;
+    }
+    return { data, body: m[2] };
+}
+const MAX_ROUNDS = 8;
+export class ModernServer {
+    t;
+    o;
+    client;
+    discover;
+    defs = [];
+    skills = [];
+    all = [];
+    cacheUntil = Infinity;
+    pend = new Map();
+    constructor(t, client, disc, o) {
+        this.t = t;
+        this.o = o;
+        this.client = client;
+        this.discover = disc;
+    }
+    get oauth() {
+        return this.t.remote?.oauth;
+    }
+    req(f) {
+        return authed(this.oauth, this.o.waitFor, f);
+    }
+    async load() {
+        await this.refreshTools();
+        if (this.discover.capabilities?.extensions?.[SKILLS_EXT] !== undefined)
+            await this.loadSkills();
+    }
+    async refreshTools() {
+        const r = await this.req(() => this.client.listTools({ signal: this.o.signal }));
+        this.all = r.tools;
+        const off = new Set(this.o.disableTools ?? []);
+        const prefix = sanitize(this.t.name) + "_";
+        this.defs = filterDefs(this.t.name, r.tools, this.t.tools).filter((d) => !off.has(prefix + sanitize(d.name)));
+        this.cacheUntil = typeof r.ttlMs === "number" ? Date.now() + r.ttlMs : Infinity;
+    }
+    async loadSkills() {
+        const r = await this.req(() => this.client.call("skills/list", {}, { signal: this.o.signal }));
+        for (const s of Array.isArray(r.skills) ? r.skills : []) {
+            const uri = String(s?.uri ?? "");
+            try {
+                const f = await this.req(() => this.client.fetchSkill(uri, { signal: this.o.signal }));
+                const { data, body } = parseFrontmatter(f.markdown);
+                const name = data.name || f.name;
+                this.skills.push({ name, description: data.description ?? "", content: body, resources: f.resources, base: `skill://${f.name}/` });
+            }
+            catch (e) {
+                console.warn(`[toolnexus] MCP server "${this.t.name}" skill ${JSON.stringify(uri)} skipped: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+    /** The toolkit tools for this server: every (filtered) server tool, or the two tool-search tools. */
+    tools() {
+        const server = this.t.name;
+        if (!this.t.toolSearch)
+            return this.defs.map((d) => this.convert(d));
+        const about = this.t.description || server;
+        const search = {
+            name: sanitize(server) + "_search_tools",
+            description: `Search the tools of ${about} by keywords. Returns name, description and inputSchema of the best matches; run one with call_tool.`,
+            inputSchema: { type: "object", properties: { query: { type: "string" }, limit: { type: "integer" } }, required: ["query"] },
+            source: "mcp",
+            execute: async (args, ctx) => {
+                try {
+                    if (Date.now() >= this.cacheUntil)
+                        await this.refreshTools();
+                    const limit = typeof args?.limit === "number" && args.limit > 0 ? Math.trunc(args.limit) : 5;
+                    const hits = rank(this.defs, String(args?.query ?? ""), limit).map((d) => ({
+                        name: d.name, description: d.description, inputSchema: d.inputSchema, server: this.t.description ?? "",
+                    }));
+                    return { output: JSON.stringify(hits), isError: false, metadata: { server } };
+                }
+                catch (e) {
+                    return { output: e instanceof Error ? e.message : String(e), isError: true, metadata: { server } };
+                }
+            },
+        };
+        const call = {
+            name: sanitize(server) + "_call_tool",
+            description: "Run a tool found with search_tools.",
+            inputSchema: { type: "object", properties: { name: { type: "string" }, arguments: { type: "object" } }, required: ["name"] },
+            source: "mcp",
+            execute: async (args, ctx) => {
+                const name = String(args?.name ?? "");
+                const a = args?.arguments && typeof args.arguments === "object" && !Array.isArray(args.arguments) ? args.arguments : {};
+                if (!(ctx?.answer && this.pend.has(ctx.answer.id)) && !this.defs.some((d) => d.name === name)) {
+                    return { output: `unknown tool "${name}" on ${server}`, isError: true, metadata: { server } };
+                }
+                return this.run(name, a, ctx);
+            },
+        };
+        return [search, call];
+    }
+    convert(def) {
+        const inputSchema = {
+            ...def.inputSchema,
+            type: "object",
+            properties: (def.inputSchema?.properties ?? {}),
+            additionalProperties: false,
+        };
+        const hints = mcpHints(def.annotations);
+        return {
+            name: sanitize(this.t.name) + "_" + sanitize(def.name),
+            description: def.description ?? "",
+            inputSchema,
+            source: "mcp",
+            ...(hints ? { hints } : {}),
+            execute: (args, ctx) => this.run(def.name, args ?? {}, ctx),
+        };
+    }
+    /** tools/call with MRTR rounds (§2.5) and OAuth pauses (§2A.1 10); never re-sends after a failure (§2.6). */
+    async run(name, args, ctx) {
+        const server = this.t.name;
+        try {
+            const answer = ctx?.answer;
+            const cont = answer ? this.pend.get(answer.id) : undefined;
+            if (cont && answer) {
+                this.pend.delete(answer.id);
+                return await this.drive(cont, answer, ctx);
+            }
+            return await this.drive({ name, args, round: 0, reqs: {}, keys: [], idx: 0 }, undefined, ctx);
+        }
+        catch (e) {
+            return { output: e instanceof Error ? e.message : String(e), isError: true, metadata: { server } };
+        }
+    }
+    suspend(cont, req) {
+        this.pend.set(req.id, cont);
+        const output = req.url ? `${req.prompt}: ${req.url}` : req.prompt;
+        return { output, isError: true, metadata: { pending: req, server: this.t.name } };
+    }
+    async drive(cont, answer, ctx) {
+        const waitFor = this.o.waitFor;
+        let res;
+        if (answer) {
+            if (cont.authId) {
+                if (!answer.ok)
+                    throw deniedError(answer);
+                const id = cont.authId;
+                cont.authId = undefined;
+                res = await this.oauth.resume(id, callbackUrlOf(answer));
+            }
+            else {
+                cont.responses[cont.keys[cont.idx]] = answerToElicitResult(answer);
+                cont.idx++;
+            }
+        }
+        for (;;) {
+            if (!res) {
+                while (cont.idx < cont.keys.length) {
+                    const key = cont.keys[cont.idx];
+                    const req = this.toRequest(key, cont.reqs[key]);
+                    if (!waitFor)
+                        return this.suspend(cont, req);
+                    cont.responses[key] = answerToElicitResult(await waitFor(req));
+                    cont.idx++;
+                }
+                if (cont.round >= MAX_ROUNDS)
+                    throw new Error(`tools/call ${cont.name}: too many input_required rounds`);
+                const p = { name: cont.name, arguments: cont.args };
+                if (cont.responses)
+                    p.inputResponses = cont.responses;
+                if (cont.state !== undefined && cont.state !== null)
+                    p.requestState = cont.state;
+                try {
+                    res = await this.client.call("tools/call", p, { timeoutMs: ctx?.timeout, signal: ctx?.signal });
+                }
+                catch (e) {
+                    if (!(e instanceof PendingError) || !this.oauth)
+                        throw e;
+                    // Rejected before dispatch (401/403): this round has NOT run. Resume sends it once.
+                    if (!waitFor) {
+                        cont.authId = e.pending.id;
+                        return this.suspend(cont, { ...e.pending });
+                    }
+                    const a = await waitFor({ ...e.pending });
+                    if (!a?.ok)
+                        throw deniedError(a);
+                    res = await this.oauth.resume(e.pending.id, callbackUrlOf(a));
+                }
+            }
+            if (res.resultType !== "input_required")
+                return mapCallToolResult(res, this.t.name);
+            const reqs = res.inputRequests && typeof res.inputRequests === "object" && !Array.isArray(res.inputRequests) ? res.inputRequests : {};
+            for (const [k, v] of Object.entries(reqs)) {
+                if (!v || typeof v !== "object" || Array.isArray(v))
+                    throw new Error(`tools/call ${cont.name}: malformed input request "${k}"`);
+            }
+            cont.round++;
+            cont.state = res.requestState;
+            cont.responses = {};
+            cont.reqs = reqs;
+            cont.keys = Object.keys(reqs);
+            cont.idx = 0;
+            res = undefined;
+        }
+    }
+    toRequest(key, ir) {
+        if (ir.method !== "elicitation/create")
+            throw new Error(`unsupported input request method ${JSON.stringify(ir.method)} ("${key}")`);
+        const req = elicitationToRequest(ir.params ?? {});
+        req.id = "mrtr-" + randomBytes(9).toString("base64url");
+        return req;
+    }
+    /** resources/list for list_mcp_resources (§4C). */
+    async listResources(signal) {
+        const r = await this.req(() => this.client.call("resources/list", {}, { signal }));
+        return Array.isArray(r.resources) ? r.resources : [];
+    }
+    async readResource(uri, signal) {
+        const r = await this.req(() => this.client.call("resources/read", { uri }, { signal }));
+        return Array.isArray(r.contents) ? r.contents : [];
+    }
+    /** Raw (unfiltered) tool defs, for listMcpTools. */
+    rawDefs() {
+        return this.all;
+    }
+    close() {
+        return this.client.close();
+    }
+}

package/dist/mcp2026/stdio.d.ts

@@ -0,0 +1,24 @@
+/**
+ * stdio transport for the 2026 path (§2.3): one JSON-RPC message per line, responses demultiplexed
+ * by id (concurrent calls allowed), stderr passed through and never parsed, a dead child fails every
+ * pending call instead of hanging. No headers, no auth.
+ */
+import { type ChildProcess } from "node:child_process";
+import type { Transport } from "./client.js";
+import type { Obj } from "./protocol.js";
+/** The child exited / closed stdout before answering. */
+export declare class StdioClosedError extends Error {
+}
+export declare class StdioTransport implements Transport {
+    private pending;
+    private err?;
+    private done;
+    private child;
+    constructor(child: ChildProcess);
+    /** Writes one line and waits for the response with the same id. Never retried. */
+    roundTrip(id: number, body: string, timeoutMs: number, signal?: AbortSignal): Promise<Obj>;
+    /** Close stdin, then SIGKILL after 2 s if the child is still alive. */
+    close(): Promise<void>;
+}
+/** Spawns argv (no shell) and returns its transport; rejects if the spawn itself fails. */
+export declare function spawnStdio(argv: string[], env: NodeJS.ProcessEnv, cwd?: string): Promise<StdioTransport>;

package/dist/mcp2026/stdio.js

@@ -0,0 +1,99 @@
+/**
+ * stdio transport for the 2026 path (§2.3): one JSON-RPC message per line, responses demultiplexed
+ * by id (concurrent calls allowed), stderr passed through and never parsed, a dead child fails every
+ * pending call instead of hanging. No headers, no auth.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+/** The child exited / closed stdout before answering. */
+export class StdioClosedError extends Error {
+}
+export class StdioTransport {
+    pending = new Map();
+    err;
+    done;
+    child;
+    constructor(child) {
+        this.child = child;
+        const rl = createInterface({ input: child.stdout, crlfDelay: Infinity });
+        rl.on("line", (line) => {
+            let m;
+            try {
+                m = JSON.parse(line);
+            }
+            catch {
+                return; // noise
+            }
+            if (!m || typeof m !== "object" || m.method !== undefined || m.id === undefined || m.id === null)
+                return; // not a response
+            const key = JSON.stringify(m.id);
+            const f = this.pending.get(key);
+            this.pending.delete(key);
+            f?.(m);
+        });
+        this.done = new Promise((r) => rl.once("close", () => {
+            this.err ??= new StdioClosedError("stdio server closed its stdout");
+            for (const f of this.pending.values())
+                f({ __closed: true });
+            this.pending.clear();
+            r();
+        }));
+        child.stdin?.on("error", () => { }); // EPIPE after the server died surfaces as a closed stdout
+    }
+    /** Writes one line and waits for the response with the same id. Never retried. */
+    roundTrip(id, body, timeoutMs, signal) {
+        if (this.err)
+            return Promise.reject(this.err);
+        const key = JSON.stringify(id);
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                this.pending.delete(key);
+            };
+            const onAbort = () => {
+                cleanup();
+                reject(signal?.reason ?? new Error("aborted"));
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("stdio request timed out"));
+            }, timeoutMs);
+            if (signal) {
+                if (signal.aborted)
+                    return onAbort();
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            this.pending.set(key, (m) => {
+                cleanup();
+                if (m.__closed)
+                    return reject(this.err);
+                if (m.result == null && m.error == null)
+                    return reject(new Error("response has neither result nor error"));
+                resolve(m);
+            });
+            this.child.stdin?.write(body + "\n");
+        });
+    }
+    /** Close stdin, then SIGKILL after 2 s if the child is still alive. */
+    async close() {
+        if (this.child.exitCode === null && this.child.signalCode === null) {
+            this.child.stdin?.end();
+            const exited = new Promise((r) => this.child.once("exit", () => r()));
+            const t = setTimeout(() => this.child.kill("SIGKILL"), 2000);
+            await exited;
+            clearTimeout(t);
+        }
+        this.child.stdout?.destroy();
+        await this.done;
+    }
+}
+/** Spawns argv (no shell) and returns its transport; rejects if the spawn itself fails. */
+export function spawnStdio(argv, env, cwd) {
+    const [cmd, ...args] = argv;
+    const child = spawn(cmd, args, { env, cwd, stdio: ["pipe", "pipe", "inherit"] });
+    return new Promise((resolve, reject) => {
+        child.once("error", reject);
+        child.once("spawn", () => resolve(new StdioTransport(child)));
+    });
+}

package/dist/mcp2026/toolsearch.d.ts

@@ -0,0 +1,5 @@
+import type { Obj } from "./protocol.js";
+/** BM25 (k1 1.2, b 0.75) over name tokens twice + description tokens; best first, ties keep list order. */
+export declare function rank(tools: Obj[], query: string, limit: number): Obj[];
+/** Lowercases and splits on non-alphanumerics and camelCase boundaries. */
+export declare function tokens(s: string): string[];

package/dist/mcp2026/toolsearch.js

@@ -0,0 +1,58 @@
+/** BM25 (k1 1.2, b 0.75) over name tokens twice + description tokens; best first, ties keep list order. */
+export function rank(tools, query, limit) {
+    const docs = tools.map((t) => {
+        const nt = tokens(String(t.name ?? ""));
+        return [...nt, ...nt, ...tokens(String(t.description ?? ""))];
+    });
+    const df = new Map();
+    let total = 0;
+    for (const d of docs) {
+        total += d.length;
+        for (const w of new Set(d))
+            df.set(w, (df.get(w) ?? 0) + 1);
+    }
+    const avg = total / Math.max(1, tools.length);
+    const qs = tokens(query);
+    const hits = [];
+    docs.forEach((d, i) => {
+        const tf = new Map();
+        for (const w of d)
+            tf.set(w, (tf.get(w) ?? 0) + 1);
+        let s = 0;
+        for (const q of qs) {
+            const f = tf.get(q) ?? 0;
+            if (f === 0)
+                continue;
+            const n = df.get(q) ?? 0;
+            const idf = Math.log(1 + (tools.length - n + 0.5) / (n + 0.5));
+            s += (idf * f * 2.2) / (f + 1.2 * (0.25 + (0.75 * d.length) / avg));
+        }
+        if (s > 0)
+            hits.push({ i, score: s });
+    });
+    hits.sort((a, b) => b.score - a.score); // stable
+    return hits.slice(0, Math.max(0, limit)).map((h) => tools[h.i]);
+}
+/** Lowercases and splits on non-alphanumerics and camelCase boundaries. */
+export function tokens(s) {
+    const out = [];
+    let cur = "";
+    let prevLower = false;
+    for (const r of s) {
+        if (/\p{Lu}/u.test(r) && prevLower) {
+            if (cur)
+                out.push(cur.toLowerCase());
+            cur = r;
+        }
+        else if (/[\p{L}\p{N}]/u.test(r))
+            cur += r;
+        else if (cur) {
+            out.push(cur.toLowerCase());
+            cur = "";
+        }
+        prevLower = /\p{Ll}/u.test(r);
+    }
+    if (cur)
+        out.push(cur.toLowerCase());
+    return out;
+}