@miragon/mcp-toolkit-core 0.10.1

package/dist/rest/client.js

@@ -0,0 +1,155 @@
+import { RestError } from "./errors.js";
+/**
+ * Build a `RestClient` with the given base URL, auth mode, and default
+ * headers. The returned client handles URL-template expansion, query-string
+ * encoding, auth header stamping, JSON serialization, and error mapping
+ * (non-2xx responses throw `RestError`).
+ *
+ * Consumers typically instantiate one client per upstream backend and pass
+ * it into `createToolRegistrar` so every tool handler receives the typed
+ * client instance.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+export function createRestClient(config) {
+    const baseUrl = stripTrailingSlash(config.baseUrl);
+    const authHeaders = buildAuthHeaders(config.auth ?? { mode: "none" });
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    const defaultTimeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (typeof fetchImpl !== "function") {
+        throw new Error("createRestClient: no fetch implementation available");
+    }
+    async function request(options) {
+        const url = buildUrl(baseUrl, options.path, options.pathParams, options.query);
+        const headers = mergeHeaders({ accept: "application/json" }, config.defaultHeaders, authHeaders, options.headers);
+        const init = {
+            method: options.method,
+            headers,
+        };
+        if (options.body !== undefined && options.body !== null && methodAllowsBody(options.method)) {
+            init.body = typeof options.body === "string" ? options.body : JSON.stringify(options.body);
+            if (typeof options.body !== "string" && !hasContentType(headers)) {
+                ;
+                init.headers["content-type"] = "application/json";
+            }
+        }
+        // A hung upstream must not block the tool call (and its MCP connection)
+        // forever. Abort on timeout, and combine with the caller's signal so an
+        // explicit cancellation still works. A dedicated timeout signal lets us
+        // tell "timed out" from "caller aborted" in the catch below.
+        const timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+        const timeoutSignal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+        const signal = combineSignals(options.signal, timeoutSignal);
+        if (signal)
+            init.signal = signal;
+        let response;
+        try {
+            response = await fetchImpl(url, init);
+        }
+        catch (err) {
+            if (timeoutSignal?.aborted && !options.signal?.aborted) {
+                throw new Error(`REST request to ${url} timed out after ${timeoutMs}ms`, { cause: err });
+            }
+            throw err;
+        }
+        if (!response.ok) {
+            const body = await safeReadText(response);
+            throw new RestError(response.status, response.statusText, body, url);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            return (await response.json());
+        }
+        return (await response.text());
+    }
+    return { request, baseUrl };
+}
+/**
+ * Combine an optional caller signal with an optional timeout signal into the
+ * single `AbortSignal` fetch accepts. Returns `undefined` when neither is
+ * present (no abort behaviour), the sole signal when only one is, or
+ * `AbortSignal.any([...])` when both are — so whichever fires first aborts the
+ * request.
+ */
+function combineSignals(caller, timeout) {
+    if (caller && timeout)
+        return AbortSignal.any([caller, timeout]);
+    return caller ?? timeout;
+}
+function buildAuthHeaders(auth) {
+    switch (auth.mode) {
+        case "none":
+            return {};
+        case "bearer":
+            return { authorization: `Bearer ${auth.token}` };
+        case "header":
+            return { [auth.headerName.toLowerCase()]: auth.value };
+    }
+}
+function buildUrl(baseUrl, path, pathParams, query) {
+    const expandedPath = expandPathTemplate(path, pathParams);
+    const joined = expandedPath.startsWith("/")
+        ? `${baseUrl}${expandedPath}`
+        : `${baseUrl}/${expandedPath}`;
+    const queryString = encodeQuery(query);
+    return queryString ? `${joined}?${queryString}` : joined;
+}
+function expandPathTemplate(path, params) {
+    return path.replace(/\{([^}]+)\}/g, (_, key) => {
+        if (!params || !(key in params)) {
+            throw new Error(`Missing path parameter "${key}" for template "${path}"`);
+        }
+        return encodeURIComponent(String(params[key]));
+    });
+}
+function encodeQuery(query) {
+    if (!query)
+        return "";
+    const params = [];
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const entry of value) {
+                if (entry === undefined || entry === null)
+                    continue;
+                params.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(entry))}`);
+            }
+        }
+        else {
+            params.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        }
+    }
+    return params.join("&");
+}
+function mergeHeaders(...sources) {
+    const out = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const [key, value] of Object.entries(source)) {
+            out[key.toLowerCase()] = value;
+        }
+    }
+    return out;
+}
+function hasContentType(headers) {
+    return "content-type" in headers;
+}
+function methodAllowsBody(method) {
+    return method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+}
+function stripTrailingSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+async function safeReadText(response) {
+    try {
+        return await response.text();
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/rest/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/rest/client.ts"],"names":[],"mappings":"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"}

package/dist/rest/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Thrown by `RestClient.request` on non-2xx responses.
+ *
+ * `status` is picked up by `createToolRegistrar`'s error handler and
+ * rendered as `[<status>] <message>` in the MCP tool response, so tool
+ * authors do not need to translate HTTP errors manually.
+ */
+export declare class RestError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    constructor(status: number, statusText: string, body: string, url: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/rest/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/rest/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAQ1E"}

package/dist/rest/errors.js

@@ -0,0 +1,21 @@
+/**
+ * Thrown by `RestClient.request` on non-2xx responses.
+ *
+ * `status` is picked up by `createToolRegistrar`'s error handler and
+ * rendered as `[<status>] <message>` in the MCP tool response, so tool
+ * authors do not need to translate HTTP errors manually.
+ */
+export class RestError extends Error {
+    status;
+    statusText;
+    body;
+    constructor(status, statusText, body, url) {
+        const snippet = body.length > 200 ? `${body.slice(0, 200)}…` : body;
+        super(`HTTP ${status} ${statusText} for ${url}${snippet ? `: ${snippet}` : ""}`);
+        this.name = "RestError";
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/rest/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/rest/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,MAAM,CAAQ;IACd,UAAU,CAAQ;IAClB,IAAI,CAAQ;IAErB,YAAY,MAAc,EAAE,UAAkB,EAAE,IAAY,EAAE,GAAW;QACvE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;QACnE,KAAK,CAAC,QAAQ,MAAM,IAAI,UAAU,QAAQ,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QAChF,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF"}

package/dist/rest/index.d.ts

@@ -0,0 +1,6 @@
+export { createRestClient } from "./client.js";
+export { createRestTool } from "./tool.js";
+export { RestError } from "./errors.js";
+export type { HttpMethod, QueryValue, RestAuthConfig, RestClient, RestClientConfig, RestRequestOptions, } from "./types.js";
+export type { RestToolConfig, RequestParts } from "./tool.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/rest/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rest/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA"}

package/dist/rest/index.js

@@ -0,0 +1,4 @@
+export { createRestClient } from "./client.js";
+export { createRestTool } from "./tool.js";
+export { RestError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/rest/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rest/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA"}

package/dist/rest/tool.d.ts

@@ -0,0 +1,60 @@
+import type { z } from "zod";
+import type { ToolConfig } from "../tools/register-tool.js";
+import type { HttpMethod, RestClient, RestRequestOptions } from "./types.js";
+type ZodRawShape = Record<string, z.ZodTypeAny>;
+type ToolArgs = Record<string, any>;
+/**
+ * Subset of `RestRequestOptions` that a `buildRequest` callback may return.
+ * `method` and `path` are fixed by the tool definition.
+ */
+export type RequestParts = Pick<RestRequestOptions, "pathParams" | "query" | "body" | "headers">;
+export interface RestToolConfig<TArgs extends ToolArgs = ToolArgs, TRaw = unknown, TOut = unknown> {
+    name: string;
+    description: string;
+    category?: string;
+    method: HttpMethod;
+    /** URL template relative to the client's baseUrl, e.g. `/orders/{orderId}`. */
+    path: string;
+    inputSchema?: ZodRawShape;
+    /**
+     * Map validated args to request parts. If omitted, a method-dependent
+     * default is used: path placeholders consume matching args, the rest
+     * become `query` (GET/DELETE) or `body` (POST/PUT/PATCH).
+     */
+    buildRequest?: (args: TArgs) => RequestParts;
+    /**
+     * Transform the raw response before handing it to the LLM. Use this to
+     * reduce field surface — the main context-hygiene lever.
+     */
+    projection?: (raw: TRaw, args: TArgs) => TOut;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    formatResult?: (result: TOut, args: TArgs) => string;
+}
+/**
+ * Produce a `ToolConfig<RestClient>` that the standard `createToolRegistrar`
+ * can register. This keeps REST tools on the same registration path as
+ * hand-written tools — same error handling, same result formatting.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * const client = createRestClient({ baseUrl, auth: { mode: "bearer", token } })
+ * const register = createToolRegistrar(server, client)
+ * register(createRestTool({
+ *   name: "get_order",
+ *   description: "Fetch an order by ID.",
+ *   method: "GET",
+ *   path: "/orders/{orderId}",
+ *   inputSchema: { orderId: z.string() },
+ *   projection: (raw: Order) => ({ id: raw.id, total: raw.totalAmount }),
+ * }))
+ * ```
+ */
+export declare function createRestTool<TArgs extends ToolArgs = ToolArgs, TRaw = unknown, TOut = unknown>(config: RestToolConfig<TArgs, TRaw, TOut>): ToolConfig<RestClient>;
+export {};
+//# sourceMappingURL=tool.d.ts.map

package/dist/rest/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/rest/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAc,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAExF,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAA;AAG/C,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAEnC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,EAAE,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC,CAAA;AAEhG,MAAM,WAAW,cAAc,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,EAAE,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO;IAC/F,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,UAAU,CAAA;IAClB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,YAAY,CAAA;IAC5C;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,KAAK,IAAI,CAAA;IAC7C,WAAW,CAAC,EAAE;QACZ,YAAY,CAAC,EAAE,OAAO,CAAA;QACtB,eAAe,CAAC,EAAE,OAAO,CAAA;QACzB,cAAc,CAAC,EAAE,OAAO,CAAA;QACxB,aAAa,CAAC,EAAE,OAAO,CAAA;KACxB,CAAA;IACD,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,KAAK,MAAM,CAAA;CACrD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,QAAQ,GAAG,QAAQ,EAAE,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EAC9F,MAAM,EAAE,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,GACxC,UAAU,CAAC,UAAU,CAAC,CA8BxB"}

package/dist/rest/tool.js

@@ -0,0 +1,81 @@
+/**
+ * Produce a `ToolConfig<RestClient>` that the standard `createToolRegistrar`
+ * can register. This keeps REST tools on the same registration path as
+ * hand-written tools — same error handling, same result formatting.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * const client = createRestClient({ baseUrl, auth: { mode: "bearer", token } })
+ * const register = createToolRegistrar(server, client)
+ * register(createRestTool({
+ *   name: "get_order",
+ *   description: "Fetch an order by ID.",
+ *   method: "GET",
+ *   path: "/orders/{orderId}",
+ *   inputSchema: { orderId: z.string() },
+ *   projection: (raw: Order) => ({ id: raw.id, total: raw.totalAmount }),
+ * }))
+ * ```
+ */
+export function createRestTool(config) {
+    const placeholders = extractPathPlaceholders(config.path);
+    const method = config.method;
+    return {
+        name: config.name,
+        description: config.description,
+        category: config.category,
+        inputSchema: config.inputSchema,
+        annotations: config.annotations,
+        handler: async (client, args) => {
+            const typedArgs = args;
+            const parts = config.buildRequest
+                ? config.buildRequest(typedArgs)
+                : defaultBuildRequest(method, placeholders, typedArgs);
+            const raw = await client.request({
+                method,
+                path: config.path,
+                pathParams: parts.pathParams,
+                query: parts.query,
+                body: parts.body,
+                headers: parts.headers,
+            });
+            if (raw === undefined)
+                return undefined;
+            return config.projection ? config.projection(raw, typedArgs) : raw;
+        },
+        formatResult: config.formatResult
+            ? (result, args) => config.formatResult(result, args)
+            : undefined,
+    };
+}
+function extractPathPlaceholders(path) {
+    const out = new Set();
+    for (const match of path.matchAll(/\{([^}]+)\}/g)) {
+        const name = match[1];
+        if (name)
+            out.add(name);
+    }
+    return out;
+}
+function defaultBuildRequest(method, placeholders, args) {
+    const pathParams = {};
+    const rest = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (placeholders.has(key)) {
+            pathParams[key] = value;
+        }
+        else {
+            rest[key] = value;
+        }
+    }
+    const hasRest = Object.keys(rest).length > 0;
+    if (method === "GET" || method === "DELETE") {
+        return {
+            pathParams,
+            query: hasRest ? rest : undefined,
+        };
+    }
+    return { pathParams, body: hasRest ? rest : undefined };
+}
+//# sourceMappingURL=tool.js.map

package/dist/rest/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/rest/tool.ts"],"names":[],"mappings":"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"}

package/dist/rest/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Auth configuration for a REST upstream.
+ *
+ * Modes: `none`, `bearer`, and custom `header`. `oauth2` is out of scope —
+ * it requires per-user session plumbing (callback routes, token store) and
+ * is a future iteration.
+ *
+ * - `none`    — no auth headers added
+ * - `bearer`  — stamps `Authorization: Bearer <token>`
+ * - `header`  — stamps a custom header on every request
+ */
+export type RestAuthConfig = {
+    mode: "none";
+} | {
+    mode: "bearer";
+    token: string;
+} | {
+    mode: "header";
+    headerName: string;
+    value: string;
+};
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type QueryValue = string | number | boolean | null | undefined;
+export interface RestRequestOptions {
+    method: HttpMethod;
+    path: string;
+    pathParams?: Record<string, string | number>;
+    query?: Record<string, QueryValue | QueryValue[]>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /**
+     * Abort the request when this signal fires, in addition to the timeout. Use
+     * it to cancel a request from the caller (e.g. a tool handler that received
+     * its own abort signal).
+     */
+    signal?: AbortSignal;
+    /**
+     * Override {@link RestClientConfig.timeoutMs} for this request. `0` disables
+     * the timeout for this call only.
+     */
+    timeoutMs?: number;
+}
+export interface RestClientConfig {
+    baseUrl: string;
+    auth?: RestAuthConfig;
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Optional fetch implementation. Defaults to `globalThis.fetch`. Useful
+     * for tests and for runtimes that require a custom fetch.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Default per-request timeout in milliseconds. A request that doesn't settle
+     * within this window is aborted, so a hung upstream can't block a tool call
+     * (and its MCP connection) indefinitely. Defaults to `30000`. Set to `0` to
+     * disable the default timeout entirely.
+     */
+    timeoutMs?: number;
+}
+export interface RestClient {
+    /** Execute a request; throws `RestError` on non-2xx responses. */
+    request<T = unknown>(options: RestRequestOptions): Promise<T>;
+    /** Exposed so tools can share the base URL (e.g. for link formatting). */
+    readonly baseUrl: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rest/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rest/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEzD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEpE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;AAErE,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC,CAAA;IACjD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC7D,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB"}

package/dist/rest/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/rest/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/rest/types.ts"],"names":[],"mappings":""}

package/dist/tools/app-resource-uri.d.ts

@@ -0,0 +1,28 @@
+export interface DeriveAppResourceUriInput {
+    /** Server / app name used as the resource URI authority (`ui://<appName>/...`). */
+    appName: string;
+    /** Absolute path to the bundled `mcp-app.html` served under the URI. */
+    htmlPath: string;
+    /**
+     * Resource URI used when the bundle file is missing (e.g. `dist` not built
+     * yet in a dev loop). Defaults to `ui://<appName>/mcp-app.dev.html` so a
+     * stable, obviously-non-production URI is still served. Pass a custom value
+     * only when a different placeholder is needed.
+     */
+    devFallback?: string;
+}
+/**
+ * Derives a content-hashed MCP UI resource URI for the widget bundle.
+ *
+ * MCP hosts cache the widget bundle by its resource URI; with a fixed URI a
+ * host keeps serving a stale bundle even across server restarts. Hashing the
+ * file content into the URI (`ui://<appName>/mcp-app.<hash>.html`) forces a
+ * fresh fetch whenever the bundle actually changes — and only then.
+ *
+ * When the bundle file cannot be read (commonly `dist` not built yet), it
+ * falls back to {@link DeriveAppResourceUriInput.devFallback} — a stable
+ * `ui://<appName>/mcp-app.dev.html` by default — and emits a boot warning so
+ * the missing file is visible in logs rather than silently degrading.
+ */
+export declare function deriveAppResourceUri(input: DeriveAppResourceUriInput): string;
+//# sourceMappingURL=app-resource-uri.d.ts.map

package/dist/tools/app-resource-uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-resource-uri.d.ts","sourceRoot":"","sources":["../../src/tools/app-resource-uri.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,yBAAyB;IACxC,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAA;IACf,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,MAAM,CAc7E"}

package/dist/tools/app-resource-uri.js

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+/**
+ * Derives a content-hashed MCP UI resource URI for the widget bundle.
+ *
+ * MCP hosts cache the widget bundle by its resource URI; with a fixed URI a
+ * host keeps serving a stale bundle even across server restarts. Hashing the
+ * file content into the URI (`ui://<appName>/mcp-app.<hash>.html`) forces a
+ * fresh fetch whenever the bundle actually changes — and only then.
+ *
+ * When the bundle file cannot be read (commonly `dist` not built yet), it
+ * falls back to {@link DeriveAppResourceUriInput.devFallback} — a stable
+ * `ui://<appName>/mcp-app.dev.html` by default — and emits a boot warning so
+ * the missing file is visible in logs rather than silently degrading.
+ */
+export function deriveAppResourceUri(input) {
+    const { appName, htmlPath } = input;
+    const devFallback = input.devFallback ?? `ui://${appName}/mcp-app.dev.html`;
+    try {
+        const hash = createHash("sha256").update(readFileSync(htmlPath)).digest("hex").slice(0, 10);
+        return `ui://${appName}/mcp-app.${hash}.html`;
+    }
+    catch {
+        console.warn(`[mcp-toolkit] could not read widget bundle at "${htmlPath}" — ` +
+            `serving the dev fallback resource URI "${devFallback}". ` +
+            `Build the bundle (dist/mcp-app.html) before shipping to production.`);
+        return devFallback;
+    }
+}
+//# sourceMappingURL=app-resource-uri.js.map

package/dist/tools/app-resource-uri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-resource-uri.js","sourceRoot":"","sources":["../../src/tools/app-resource-uri.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAgBtC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IACnE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAA;IACnC,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,QAAQ,OAAO,mBAAmB,CAAA;IAC3E,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;QAC3F,OAAO,QAAQ,OAAO,YAAY,IAAI,OAAO,CAAA;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CACV,kDAAkD,QAAQ,MAAM;YAC9D,0CAA0C,WAAW,KAAK;YAC1D,qEAAqE,CACxE,CAAA;QACD,OAAO,WAAW,CAAA;IACpB,CAAC;AACH,CAAC"}

package/dist/tools/backend-registry.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Default backend-selection TTL: how long a session's sticky pick survives
+ * without being re-set. `mcp-use` exposes no session-close hook to plugins, so
+ * without eviction the per-session selection map would grow with every MCP
+ * session that ever selected a backend. 24h comfortably outlives any real
+ * session.
+ */
+export declare const DEFAULT_BACKEND_SESSION_TTL_MS: number;
+/** A single addressable backend: a stable `id`, its `client`, and free-form `meta`. */
+export interface BackendEntry<TClient, TMeta = undefined> {
+    id: string;
+    client: TClient;
+    meta?: TMeta;
+}
+/** A resolved backend handed to a tool handler. */
+export interface ResolvedBackend<TClient, TMeta = undefined> {
+    id: string;
+    client: TClient;
+    meta: TMeta | undefined;
+}
+export interface CreateBackendRegistryOptions {
+    /** Sticky-selection TTL in ms (default: {@link DEFAULT_BACKEND_SESSION_TTL_MS}). */
+    sessionTtlMs?: number;
+    /**
+     * Noun used in error messages and the select-instruction hint, e.g.
+     * `"engine"` → "No engine selected for this session." Defaults to
+     * `"backend"`.
+     */
+    label?: string;
+    /**
+     * Resolves the current MCP session id. Defaults to reading the
+     * `Mcp-Session-Id` header off the request context. Injectable for tests and
+     * for hosts that key sessions differently.
+     */
+    getSessionId?: () => string | undefined;
+    /**
+     * Clock used for TTL bookkeeping, in ms. Defaults to `Date.now`. Injectable
+     * so tests can drive eviction deterministically.
+     */
+    now?: () => number;
+}
+/**
+ * Thrown when a tool is invoked but no backend has been selected for the
+ * current MCP session and the registry holds more than one backend.
+ *
+ * The message lists the available ids because the error path commonly only
+ * serialises `code` + `message` (the structured `availableIds` field may not
+ * reach the model) — naming them saves the model a discovery roundtrip before
+ * it can pick one and select it.
+ */
+export declare class BackendNotSelectedError extends Error {
+    readonly code: "BACKEND_NOT_SELECTED";
+    readonly availableIds: string[];
+    constructor(availableIds: string[], label: string);
+}
+/** Thrown when an override or sticky selection names a backend that isn't registered. */
+export declare class UnknownBackendError extends Error {
+    readonly code: "UNKNOWN_BACKEND";
+    readonly requestedId: string;
+    readonly availableIds: string[];
+    constructor(requestedId: string, availableIds: string[], label: string);
+}
+/**
+ * A session-aware registry of interchangeable backends (Camunda engines, REST
+ * hosts, tenants, …). Resolves the backend for a tool call by precedence:
+ *   1. an explicit per-call `override` wins,
+ *   2. otherwise the sticky session selection,
+ *   3. otherwise, if exactly one backend is configured, that one,
+ *   4. otherwise throws {@link BackendNotSelectedError}.
+ *
+ * Sticky selections are kept per MCP session and evicted by a lazy TTL sweep
+ * (no timer): expired entries are dropped on read and on the next `select`.
+ */
+export interface BackendRegistry<TClient, TMeta = undefined> {
+    /** Resolve the backend for the current call (precedence: override > sticky > single default). */
+    resolve(override?: string): ResolvedBackend<TClient, TMeta>;
+    /** Pin `id` as the sticky selection for the current MCP session. */
+    select(id: string): void;
+    /** Clear the sticky selection for a given session id (no-op if none). */
+    clear(sessionId: string): void;
+    /** List every registered backend (id + meta), in registration order. */
+    list(): {
+        id: string;
+        meta: TMeta | undefined;
+    }[];
+    /**
+     * The id sticky-selected for the current session, or `undefined` when none
+     * is selected (or the selection has outlived the TTL). Unlike {@link resolve},
+     * it never falls back to a single configured default and never throws — it
+     * reports only an explicit sticky selection, which is what a "what is
+     * currently selected?" reader needs: a select-tool's `current` action, or
+     * surfacing the active pick alongside `list`.
+     */
+    getSelected(): string | undefined;
+}
+/**
+ * Builds a {@link BackendRegistry} from a non-empty list of backend entries.
+ * Throws if `entries` is empty or contains duplicate ids — both are
+ * programmer errors that should fail at boot rather than at the first tool
+ * call.
+ */
+export declare function createBackendRegistry<TClient, TMeta = undefined>(entries: BackendEntry<TClient, TMeta>[], opts?: CreateBackendRegistryOptions): BackendRegistry<TClient, TMeta>;
+/**
+ * Lifts a handler written against a single resolved backend into one that
+ * resolves the backend from `registry` (override > sticky > single default)
+ * before delegating. The override is read from `args[paramName]`, so a tool
+ * adds backend selection by spreading an optional `{ [paramName]: z.string() }`
+ * into its input schema and wrapping its handler in `withBackend(...)`.
+ */
+export declare function withBackend<TClient, TMeta, TArgs extends Record<string, unknown>, TResult>(registry: BackendRegistry<TClient, TMeta>, paramName: string, fn: (backend: ResolvedBackend<TClient, TMeta>, args: TArgs) => Promise<TResult>): (args: TArgs) => Promise<TResult>;
+//# sourceMappingURL=backend-registry.d.ts.map

package/dist/tools/backend-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-registry.d.ts","sourceRoot":"","sources":["../../src/tools/backend-registry.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,8BAA8B,QAAsB,CAAA;AAEjE,uFAAuF;AACvF,MAAM,WAAW,YAAY,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS;IACtD,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,KAAK,CAAA;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS;IACzD,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,OAAO,CAAA;IACf,IAAI,EAAE,KAAK,GAAG,SAAS,CAAA;CACxB;AAkBD,MAAM,WAAW,4BAA4B;IAC3C,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IACvC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,QAAQ,CAAC,IAAI,EAAG,sBAAsB,CAAS;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAA;gBACnB,YAAY,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM;CAQlD;AAED,yFAAyF;AACzF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,iBAAiB,CAAS;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,CAAA;gBACnB,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM;CAMvE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS;IACzD,iGAAiG;IACjG,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;IAC3D,oEAAoE;IACpE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,yEAAyE;IACzE,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,wEAAwE;IACxE,IAAI,IAAI;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAA;KAAE,EAAE,CAAA;IACjD;;;;;;;OAOG;IACH,WAAW,IAAI,MAAM,GAAG,SAAS,CAAA;CAClC;AAOD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS,EAC9D,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EACvC,IAAI,GAAE,4BAAiC,GACtC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,CAmFjC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EACxF,QAAQ,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EACzC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,GAC9E,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAMnC"}