toolnexus 0.23.0 → 0.25.0

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

package/dist/mcphandler.d.ts

@@ -0,0 +1,169 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Tool, ToolContext, ToolResult, ToolSource } from "./types.js";
+import type { McpSkill } from "./skill.js";
+/** The MCP 2026-07-28 protocol version: an opt-in stateless wire (SPEC §7C.2), never a default. */
+export declare const MCP_PROTOCOL_2026 = "2026-07-28";
+/** The SEP-2640 skills extension id advertised by `server/discover` when `listSkills` is set. */
+export declare const MCP_SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
+/**
+ * The MCP protocol versions whose wire this handler implements (ADR 0039 §versions).
+ * 2026-07-28 is opt-in only (list it in `protocolVersions`): the stateless wire of SPEC §7C.2.
+ */
+export declare const MCP_HANDLER_IMPLEMENTED_VERSIONS: readonly string[];
+export type McpDecisionKind = "allow" | "deny" | "confirm";
+/**
+ * What `beforeCall` returns. `undefined` / `{}` allows. deny ⇒ `result` when set, else isError
+ * `message` (default "denied"). confirm ⇒ elicitation when the client can, else `result` when
+ * set, else isError "confirmation required: <message>".
+ */
+export interface McpDecision {
+    kind?: McpDecisionKind;
+    message?: string;
+    result?: ToolResult;
+}
+export interface McpServerInfo {
+    name?: string;
+    /** serverInfo.title; empty ⇒ omitted. */
+    title?: string;
+    version?: string;
+    instructions?: string;
+}
+export interface McpResource {
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+/** One entry of resources/read: set `text`, or `blob` (base64). */
+export interface McpResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+}
+export interface McpPromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+export interface McpPrompt {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: McpPromptArgument[];
+}
+export interface McpPromptMessage {
+    role: "user" | "assistant";
+    text: string;
+}
+export interface McpPromptResult {
+    description?: string;
+    messages: McpPromptMessage[];
+}
+/** The inbound request a hook or tool is serving. Read it with the `*From(ctx)` helpers. */
+export interface McpContext {
+    /** What `authenticate` returned (undefined without one). */
+    identity?: unknown;
+    request: IncomingMessage;
+    /** Mcp-Session-Id ("" when stateless / none). */
+    sessionId: string;
+    /** The JSON-RPC request's `params._meta`, when present. */
+    meta?: Record<string, unknown>;
+    /** Aborted when the HTTP request goes away. */
+    signal: AbortSignal;
+}
+type Awaitable<T> = T | Promise<T>;
+/** Issues and checks Mcp-Session-Id values. Default: an in-memory set. */
+export interface McpSessionIds {
+    generate(ctx: McpContext): Awaitable<string>;
+    /** false ⇒ HTTP 404. */
+    validate(ctx: McpContext, id: string): Awaitable<boolean>;
+    terminate(ctx: McpContext, id: string): Awaitable<void>;
+}
+/**
+ * An `authenticate` failure with an explicit HTTP status and challenge (`McpServerAuth` throws
+ * it; any hook may). On any wire the handler answers `status` (default 401) with
+ * `WWW-Authenticate` = `challenge` (a non-empty `wwwAuthenticate` result wins) and the body
+ * `{"error":"unauthorized"}`. `reason` is never sent on the wire.
+ */
+export declare class McpAuthError extends Error {
+    readonly status: number;
+    readonly challenge: string;
+    readonly reason: string;
+    constructor(status: number, challenge: string, reason?: string);
+}
+/** Surfaced once per inbound tools/call. */
+export interface McpCallEvent {
+    name: string;
+    source: ToolSource;
+    ms: number;
+    isError: boolean;
+    /** The execute() failure, when it threw. */
+    err?: unknown;
+    /** Size in bytes of the JSON CallToolResult sent back. */
+    resultBytes: number;
+    decision: McpDecisionKind;
+    identity: unknown;
+    sessionId: string;
+}
+/** Configures `toolkit.mcpHandler`. Every field is optional. */
+export interface McpHandlerConfig {
+    name?: string;
+    title?: string;
+    version?: string;
+    instructions?: string;
+    /** Resolved at initialize; wins over the static fields. */
+    serverInfo?: (ctx: McpContext) => Awaitable<McpServerInfo>;
+    /** Accepted versions, newest first; unimplemented entries dropped. Default ["2025-06-18"]. */
+    protocolVersions?: string[];
+    /** Every HTTP request, before JSON-RPC parsing. Throw / reject ⇒ HTTP 401. */
+    authenticate?: (req: IncomingMessage) => Awaitable<unknown>;
+    /** WWW-Authenticate header for the 401 (when non-empty). */
+    wwwAuthenticate?: (req: IncomingMessage, err: unknown) => string | undefined;
+    /** Per request, for tools/list AND the tools/call lookup. Omit ⇒ the toolkit's tools. */
+    listTools?: (ctx: McpContext) => Awaitable<Tool[]>;
+    /** Gate per tools/call. A throw is a deny with its message. */
+    beforeCall?: (ctx: McpContext, tool: Tool, args: Record<string, unknown>) => Awaitable<McpDecision | void>;
+    /** Elicitation round-trip bound in ms. Default 5 minutes. */
+    confirmTimeout?: number;
+    /** Fires once per tools/call; its throws are isolated. */
+    onCall?: (ev: McpCallEvent) => void;
+    listResources?: (ctx: McpContext) => Awaitable<McpResource[]>;
+    readResource?: (ctx: McpContext, uri: string) => Awaitable<McpResourceContent[]>;
+    listPrompts?: (ctx: McpContext) => Awaitable<McpPrompt[]>;
+    getPrompt?: (ctx: McpContext, name: string, args: Record<string, string>) => Awaitable<McpPromptResult>;
+    /**
+     * §7C.2: skills published through the SEP-2640 skills extension on the 2026-07-28 wire
+     * (skills/list, skills/get, resources/read of skill:// URIs). Omit ⇒ not advertised.
+     * `loadMcpSkills(dir)` builds the list from a skills directory.
+     */
+    listSkills?: (ctx: McpContext) => Awaitable<McpSkill[]>;
+    sessionIds?: McpSessionIds;
+    /** No Mcp-Session-Id issued or checked; elicitation never used. */
+    stateless?: boolean;
+    /** Stateless only: echoed as Mcp-Session-Id on initialize, never validated. */
+    statelessSessionId?: string;
+    /** POST body cap in bytes. Default 4 MiB. */
+    maxBodyBytes?: number;
+}
+/** The embeddable handler: a Node request listener plus `notifyToolsChanged()`. */
+export interface McpHandler {
+    (req: IncomingMessage, res: ServerResponse): void;
+    /** Sends notifications/tools/list_changed on every open GET stream. */
+    notifyToolsChanged(): void;
+}
+type AnyCtx = McpContext | ToolContext | undefined | null;
+/** The value `authenticate` produced for this request (hook ctx or tool ctx). */
+export declare const identityFrom: (ctx: AnyCtx) => unknown;
+/** The inbound IncomingMessage being served. */
+export declare const requestFrom: (ctx: AnyCtx) => IncomingMessage | undefined;
+/** The request's Mcp-Session-Id ("" if none). */
+export declare const mcpSessionIdFrom: (ctx: AnyCtx) => string;
+/** The JSON-RPC request's `params._meta` (undefined when absent). */
+export declare const mcpRequestMetaFrom: (ctx: AnyCtx) => Record<string, unknown> | undefined;
+/** The tools/list entry: name, description, inputSchema, outputSchema?, annotations?. */
+export declare function mcpWireTool(t: Tool): Record<string, unknown>;
+/** Builds the handler (`toolkit.mcpHandler(cfg)` calls this with the toolkit's tools). */
+export declare function createMcpHandler(toolkitTools: () => Tool[], cfg?: McpHandlerConfig): McpHandler;
+export {};