mcp-trellis 0.2.1 → 2.1.0

package/dist/mcp/protocol.js

@@ -0,0 +1,22 @@
+export const PROTOCOL_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
+/**
+ * Answered on `initialize` when the client's requested version is missing
+ * or unrecognized: per the spec, the latest version this server supports.
+ */
+export const DEFAULT_PROTOCOL_VERSION = "2025-06-18";
+/**
+ * The assumed protocol version for a request that omits the
+ * `MCP-Protocol-Version` header — distinct from `DEFAULT_PROTOCOL_VERSION`
+ * above. This is the 2025-06-18 spec's own backwards-compatibility rule
+ * for the header specifically (introduced in that revision, so a header-less
+ * request predates it), not a "pick the newest" preference.
+ */
+export const ASSUMED_HEADER_PROTOCOL_VERSION = "2025-03-26";
+export const pickProtocolVersion = (params) => {
+    const requested = params?.protocolVersion;
+    if (typeof requested === "string" && PROTOCOL_VERSIONS.has(requested)) {
+        return requested;
+    }
+    return DEFAULT_PROTOCOL_VERSION;
+};
+//# sourceMappingURL=protocol.js.map

package/dist/mcp/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/mcp/protocol.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC;AAErF;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,YAAY,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,YAAY,CAAC;AAE5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAAgC,EAAU,EAAE;IAC9E,MAAM,SAAS,GAAG,MAAM,EAAE,eAAe,CAAC;IAC1C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACtE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,wBAAwB,CAAC;AAClC,CAAC,CAAC"}

package/dist/mcp/registry.d.ts

@@ -0,0 +1,58 @@
+import type { JsonSchema } from "./validate.js";
+export type ToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean | undefined;
+};
+export type ToolHandler<TCtx> = (ctx: TCtx, args: Record<string, unknown>) => Promise<ToolResult | string> | ToolResult | string;
+export type ToolDef<TCtx> = {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    /**
+     * Required scope, or `undefined`/omitted for "any authenticated
+     * principal, whatever its scopes." On a `createMcpApp` server advertising
+     * more than one scope, an omitted `scope` is a construction-time error —
+     * see `assertToolScopesConfigured` — precisely because "any authenticated
+     * principal" silently includes a principal with zero scopes, which is
+     * rarely the intent on a multi-scope server. Pass `scope: null` to state
+     * that intentionally instead of by omission.
+     */
+    scope?: string | null | undefined;
+    handler: ToolHandler<TCtx>;
+};
+export type ToolListEntry = {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+};
+export type ToolRegistry<TCtx> = {
+    /**
+     * `allowScope`, when passed, is consulted per tool with that tool's
+     * `scope` — omit a tool by returning `false`. Lets a caller (see
+     * `McpHandlerOptions.hideToolsOutsideScope`) filter `tools/list` by a
+     * principal's granted scopes without the registry itself knowing what a
+     * "principal" or "scope check" is — it only ever sees the raw `scope`
+     * value already on each `ToolDef`.
+     */
+    list: (allowScope?: (scope: string | null | undefined) => boolean) => ToolListEntry[];
+    get: (name: string) => ToolDef<TCtx> | undefined;
+    call: (name: string, ctx: TCtx, args: Record<string, unknown>) => Promise<ToolResult>;
+};
+export type RegistryOptions = {
+    /**
+     * Validate tools/call args against inputSchema. Default **true** since 2.0 —
+     * forgetting this was a silent injection path into handlers. Set `false`
+     * only when you intentionally skip schema checks.
+     */
+    validateArgs?: boolean | undefined;
+    /**
+     * Map tool exceptions to client-visible text.
+     * Default: `"Tool execution failed"` (no exception leakage).
+     */
+    onToolError?: ((error: unknown) => string) | undefined;
+};
+export declare const createToolRegistry: <TCtx>(tools: ToolDef<TCtx>[], options?: RegistryOptions) => ToolRegistry<TCtx>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/mcp/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/mcp/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,CAAC,IAAI,IAAI,CAC9B,GAAG,EAAE,IAAI,EACT,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,UAAU,GAAG,MAAM,CAAC,GAAG,UAAU,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,OAAO,CAAC,IAAI,IAAI;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,IAAI,IAAI;IAC/B;;;;;;;OAOG;IACH,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,KAAK,aAAa,EAAE,CAAC;IACtF,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;IACjD,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CACvF,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;CACxD,CAAC;AA8DF,eAAO,MAAM,kBAAkB,GAAI,IAAI,EACrC,OAAO,OAAO,CAAC,IAAI,CAAC,EAAE,EACtB,UAAS,eAAoB,KAC5B,YAAY,CAAC,IAAI,CAqCnB,CAAC"}

package/dist/mcp/registry.js

@@ -0,0 +1,81 @@
+import { missingObjectType, unsupportedKeywords, validateAgainstSchema } from "./validate.js";
+const DEFAULT_TOOL_ERROR = "Tool execution failed";
+/**
+ * Map a tool exception to client-visible text.
+ * A throwing or non-string `onToolError` falls back to the redacted default —
+ * a mapper must never turn a tool failure into a transport failure.
+ */
+const resolveToolError = (caught, onToolError) => {
+    if (!onToolError)
+        return DEFAULT_TOOL_ERROR;
+    try {
+        const mapped = onToolError(caught);
+        return typeof mapped === "string" && mapped.length > 0 ? mapped : DEFAULT_TOOL_ERROR;
+    }
+    catch {
+        return DEFAULT_TOOL_ERROR;
+    }
+};
+const asToolResult = (out) => {
+    if (typeof out === "string") {
+        return { content: [{ type: "text", text: out }], isError: false };
+    }
+    return out;
+};
+const errorResult = (message) => ({
+    content: [{ type: "text", text: message }],
+    isError: true,
+});
+/** Throws with every violation listed at once, rather than failing on the first tool found. */
+const assertToolSchemasValid = (tools) => {
+    const keywordViolations = tools.flatMap((tool) => unsupportedKeywords(tool.inputSchema).map((path) => `${tool.name}: unsupported JSON Schema keyword at ${path}`));
+    if (keywordViolations.length > 0) {
+        throw new Error(`validateArgs: true but inputSchema uses unsupported keywords:\n` +
+            keywordViolations.join("\n") +
+            "\nRemove the keyword, enforce it in the handler, or set validateArgs: false");
+    }
+    // `properties`/`required` without `type: "object"` validates nothing at
+    // that node, and passes the keyword check above. See `missingObjectType`.
+    const typeViolations = tools.flatMap((tool) => missingObjectType(tool.inputSchema).map((path) => `${tool.name}: ${path} uses properties/required without type: "object"`));
+    if (typeViolations.length > 0) {
+        throw new Error(`validateArgs: true but inputSchema implies an object shape without declaring it:\n` +
+            typeViolations.join("\n") +
+            '\nAdd type: "object" (or include it in a union), or set validateArgs: false');
+    }
+};
+export const createToolRegistry = (tools, options = {}) => {
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    if (byName.size !== tools.length) {
+        throw new Error("duplicate tool names in registry");
+    }
+    const validateArgs = options.validateArgs !== false;
+    if (validateArgs)
+        assertToolSchemasValid(tools);
+    return {
+        list: (allowScope) => tools
+            .filter((tool) => !allowScope || allowScope(tool.scope))
+            .map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+        })),
+        get: (name) => byName.get(name),
+        call: async (name, ctx, args) => {
+            const tool = byName.get(name);
+            if (!tool)
+                return errorResult(`Unknown tool: ${name}`);
+            if (validateArgs) {
+                const errors = validateAgainstSchema(args, tool.inputSchema);
+                if (errors.length > 0)
+                    return errorResult(errors.join("; "));
+            }
+            try {
+                return asToolResult(await tool.handler(ctx, args));
+            }
+            catch (caught) {
+                return errorResult(resolveToolError(caught, options.onToolError));
+            }
+        },
+    };
+};
+//# sourceMappingURL=registry.js.map

package/dist/mcp/registry.js.map

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

package/dist/mcp/rpc-handlers.d.ts

@@ -0,0 +1,11 @@
+/** JSON-RPC method handlers and authenticated dispatch. */
+import { type JsonRpcRequest } from "./jsonrpc.js";
+import { type ResolvedMcpHandlerOptions } from "./methods.js";
+export declare const dispatchRpc: <TCtx>(input: {
+    req: Request;
+    body: JsonRpcRequest;
+    options: ResolvedMcpHandlerOptions<TCtx>;
+    /** Request start (captured in `createMcpHandler.fetch`), for denial-path audit timing. */
+    startedAt: number;
+}) => Promise<Response>;
+//# sourceMappingURL=rpc-handlers.d.ts.map

package/dist/mcp/rpc-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-handlers.d.ts","sourceRoot":"","sources":["../../src/mcp/rpc-handlers.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAI3D,OAAO,EAIL,KAAK,cAAc,EAGpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAOL,KAAK,yBAAyB,EAI/B,MAAM,cAAc,CAAC;AA8ItB,eAAO,MAAM,WAAW,GAAU,IAAI,EAAE,OAAO;IAC7C,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,yBAAyB,CAAC,IAAI,CAAC,CAAC;IACzC,0FAA0F;IAC1F,SAAS,EAAE,MAAM,CAAC;CACnB,KAAG,OAAO,CAAC,QAAQ,CAkCnB,CAAC"}

package/dist/mcp/rpc-handlers.js

@@ -0,0 +1,133 @@
+/** JSON-RPC method handlers and authenticated dispatch. */
+import { jsonResponse } from "../http/http.js";
+import { isJsonObject } from "../util/json.js";
+import { JSONRPC_INVALID_PARAMS, JSONRPC_METHOD_NOT_FOUND, rpcError, rpcResult, } from "./jsonrpc.js";
+import { DENIAL_REASONS, hasScope, insufficientScope, resolveWwwAuthenticate, safeAudit, unauthorized, } from "./methods.js";
+import { pickProtocolVersion } from "./protocol.js";
+/** The one shape every "tools/call" outcome — unknown tool, missing scope, or a real call — audits. */
+const auditToolCall = (options, input) => safeAudit(options, {
+    method: "tools/call",
+    tool: input.tool,
+    principalId: input.principal?.id,
+    ok: input.ok,
+    error: input.error,
+    durationMs: Date.now() - input.startedAt,
+});
+const parseToolCallArgs = (body) => {
+    const params = body.params ?? {};
+    const name = String(params.name ?? "");
+    const args = isJsonObject(params.arguments) ? params.arguments : {};
+    return { name, args };
+};
+/**
+ * A name that doesn't refer to any registered tool is a malformed request,
+ * not a tool execution outcome — MCP distinguishes protocol errors (a
+ * standard JSON-RPC error response) from a tool's own isError: true result,
+ * and "no such tool" belongs to the former. `ToolRegistry.call`'s own
+ * "Unknown tool: …" text-result fallback stays as is for direct callers of
+ * that API outside this dispatch.
+ */
+const unknownToolResponse = async (options, input) => {
+    await auditToolCall(options, {
+        ...input,
+        tool: input.name,
+        ok: false,
+        error: DENIAL_REASONS.unknownTool,
+    });
+    return jsonResponse({
+        data: rpcError(input.id, JSONRPC_INVALID_PARAMS, `Unknown tool: ${input.name}`),
+    });
+};
+const missingScopeResponse = async (req, options, input) => {
+    await auditToolCall(options, {
+        ...input,
+        tool: input.name,
+        ok: false,
+        error: DENIAL_REASONS.missingScope,
+    });
+    const wwwAuthenticate = resolveWwwAuthenticate(options, req);
+    // No principal at all (only reachable when a host adds "tools/call" to
+    // `publicMethods`) → 401, nothing was presented to authenticate with.
+    // A principal that authenticated but lacks the tool's scope → 403
+    // insufficient_scope (RFC 6750 §3.1) — see `insufficientScope`'s doc.
+    return input.principal
+        ? insufficientScope(wwwAuthenticate, input.scope, input.id)
+        : unauthorized(wwwAuthenticate, `Missing scope: ${input.scope}`, input.id);
+};
+const METHODS = {
+    initialize: async ({ id, body, options }) => jsonResponse({
+        data: rpcResult(id, {
+            protocolVersion: pickProtocolVersion(body.params),
+            capabilities: { tools: {} },
+            serverInfo: options.serverInfo,
+            instructions: options.instructions ?? "",
+        }),
+    }),
+    ping: async ({ id }) => jsonResponse({ data: rpcResult(id, {}) }),
+    "tools/list": async ({ id, options, principal }) => {
+        const allowScope = options.hideToolsOutsideScope
+            ? (scope) => !scope || (principal ? hasScope(principal, scope) : false)
+            : undefined;
+        return jsonResponse({ data: rpcResult(id, { tools: options.registry.list(allowScope) }) });
+    },
+    "tools/call": async ({ req, body, id, principal, options, startedAt }) => {
+        const { name, args } = parseToolCallArgs(body);
+        const tool = options.registry.get(name);
+        if (!tool)
+            return unknownToolResponse(options, { name, principal, id, startedAt });
+        if (tool.scope && (!principal || !hasScope(principal, tool.scope))) {
+            return missingScopeResponse(req, options, {
+                name,
+                principal,
+                id,
+                startedAt,
+                scope: tool.scope,
+            });
+        }
+        // Built only for a call that will actually run: `initialize`, `ping`,
+        // `tools/list` and denied calls never reach the host's `context` port.
+        const ctx = await options.ports.context(req, principal);
+        const toolStartedAt = Date.now();
+        const result = await options.registry.call(name, ctx, args);
+        await auditToolCall(options, {
+            tool: name,
+            principal,
+            ok: !result.isError,
+            error: result.isError ? result.content[0]?.text : undefined,
+            startedAt: toolStartedAt,
+        });
+        return jsonResponse({ data: rpcResult(id, result) });
+    },
+};
+export const dispatchRpc = async (input) => {
+    const { req, body, options, startedAt } = input;
+    // Shape-validated in `handlePost` before routing — method is a non-empty string.
+    const method = typeof body.method === "string" ? body.method : "";
+    // Notifications omit `id`; explicit null is a valid request id (JSON-RPC).
+    const id = body.id === undefined ? null : body.id;
+    const toolName = method === "tools/call" ? String(body.params?.name ?? "") : undefined;
+    // Notifications (including every `notifications/*`) already got 202 in `handlePost`.
+    const isPublic = options.publicMethods.has(method);
+    let principal = null;
+    if (!isPublic) {
+        principal = await options.ports.authenticate(req, method, toolName);
+        if (!principal) {
+            await safeAudit(options, {
+                method,
+                tool: toolName,
+                ok: false,
+                error: DENIAL_REASONS.unauthorized,
+                durationMs: Date.now() - startedAt,
+            });
+            return unauthorized(resolveWwwAuthenticate(options, req), undefined, id);
+        }
+    }
+    const handler = METHODS[method];
+    if (!handler) {
+        return jsonResponse({
+            data: rpcError(id, JSONRPC_METHOD_NOT_FOUND, `Method not found: ${method}`),
+        });
+    }
+    return handler({ req, body, id, principal, options, startedAt });
+};
+//# sourceMappingURL=rpc-handlers.js.map

package/dist/mcp/rpc-handlers.js.map

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

package/dist/{tools.d.ts → mcp/tools.d.ts}

@@ -7,8 +7,8 @@
  * an arbitrary Standard Schema validator. `input`, when supplied, is what
  * actually parses and types `args` at call time — keep the two in sync.
  */
-import type { JsonSchema } from "./validate.js";
 import type { ToolDef, ToolResult } from "./registry.js";
+import type { JsonSchema } from "./validate.js";
 /**
  * Minimal Standard Schema v1 surface (https://standardschema.dev).
  * Any compliant validator works here with zero adapter code. This is a
@@ -42,7 +42,8 @@ type ToolCore = {
     description: string;
     /** Advertised via tools/list. Required — see module doc for why. */
     inputSchema: JsonSchema;
-    scope?: string;
+    /** See `ToolDef.scope` — pass `null` to explicitly opt out of a scope check. */
+    scope?: string | null | undefined;
 };
 type ToolHandler<TCtx, Args> = (ctx: TCtx, args: Args) => Promise<ToolResult | string> | ToolResult | string;
 type ValidatedInput<Input> = {
@@ -66,7 +67,34 @@ export type ApiRequest = string | URL | Request;
 type ApiExtra<TCtx, Args> = {
     request: (ctx: TCtx, args: Args) => ApiRequest | Promise<ApiRequest>;
     respond?: (res: Response) => Promise<ToolResult | string> | ToolResult | string;
+    /**
+     * Shape a non-2xx response yourself — you get the raw `Response`, so read
+     * `res.text()`/`res.json()` if you want the body. Omit for the default:
+     * status only, upstream body never forwarded. A returned bare `string` is
+     * **not** automatically marked as an error (same as any other tool
+     * handler) — return `{ content: [...], isError: true }` explicitly if
+     * that's what you want the model to see.
+     */
+    onError?: (res: Response) => Promise<ToolResult | string> | ToolResult | string;
     fetch?: typeof fetch;
+    /**
+     * Abort the upstream request after this many ms. Default 30000. An
+     * upstream that never responds otherwise hangs the tool call (and the
+     * MCP request behind it) indefinitely. Pass `false` to disable — the
+     * request then relies entirely on whatever signal (if any) is already on
+     * the `Request` your `request` callback returns; a timeout firing surfaces
+     * as `isError: true`, not a thrown exception `onToolError` would redact.
+     */
+    timeoutMs?: number | false;
+    /**
+     * Cap the upstream response body at this many bytes before it ever
+     * reaches `respond`/`onError`/the default error path — an unbounded
+     * `res.text()` on an attacker-influenced or merely oversized upstream
+     * response is the same memory-exhaustion shape an unbounded *incoming*
+     * request body is (see `body.ts`). Default 1 MiB. Exceeding it surfaces
+     * as `isError: true`, not a thrown exception `onToolError` would redact.
+     */
+    maxResponseBytes?: number;
 };
 export type ApiToolOptions<TCtx, Input = Record<string, unknown>> = (ToolCore & ValidatedInput<Input> & ApiExtra<TCtx, Input>) | (ToolCore & RawInput & ApiExtra<TCtx, Record<string, unknown>>);
 /**

package/dist/mcp/tools.d.ts.map

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

package/dist/mcp/tools.js

@@ -0,0 +1,166 @@
+/**
+ * Ergonomic tool authoring on top of `ToolDef` — turning "I have an API" into
+ * "I have an MCP tool" without hand-rolling validation or fetch plumbing.
+ *
+ * `inputSchema` (JSON Schema) stays required: it's what `tools/list` actually
+ * advertises to clients, and no library-agnostic way exists to derive it from
+ * an arbitrary Standard Schema validator. `input`, when supplied, is what
+ * actually parses and types `args` at call time — keep the two in sync.
+ */
+import { BodyTooLargeError, DEFAULT_MCP_BODY_LIMIT, readBoundedBytes } from "../http/body.js";
+import { pickDefined } from "../util/defined.js";
+const pathToString = (path) => (path ?? [])
+    .map((segment) => segment && typeof segment === "object" && "key" in segment
+    ? String(segment.key)
+    : String(segment))
+    .join(".");
+const parseWithSchema = async (schema, raw) => {
+    const result = await schema["~standard"].validate(raw);
+    const issues = result.issues;
+    if (issues?.length) {
+        return {
+            issues: issues.map((issue) => {
+                const path = pathToString(issue.path);
+                return path ? `${path}: ${issue.message}` : issue.message;
+            }),
+        };
+    }
+    return { value: result.value };
+};
+const issuesResult = (issues) => ({
+    content: [{ type: "text", text: issues.join("; ") }],
+    isError: true,
+});
+/**
+ * A `ToolDef` with typed, validated `args` — drop straight into
+ * `createToolRegistry` / `createMcpApp`'s `tools` array like any other tool.
+ */
+export const defineTool = (options) => ({
+    name: options.name,
+    description: options.description,
+    inputSchema: options.inputSchema,
+    ...pickDefined(options, ["scope"]),
+    handler: async (ctx, rawArgs) => {
+        if (!options.input)
+            return options.handler(ctx, rawArgs);
+        const parsed = await parseWithSchema(options.input, rawArgs);
+        if ("issues" in parsed)
+            return issuesResult(parsed.issues);
+        return options.handler(ctx, parsed.value);
+    },
+});
+const defaultRespond = (res) => res.text();
+/**
+ * Status only — the upstream body is never forwarded by default. This is a
+ * return value, not a thrown exception, so `onToolError` redaction never
+ * sees it; an upstream error page can echo internal detail, tokens or SQL
+ * into the tool result and audit log. Use `onError` to forward (a redacted
+ * version of) the body on purpose.
+ */
+const defaultErrorResult = (res) => {
+    const status = [res.status, res.statusText].filter(Boolean).join(" ");
+    return {
+        content: [{ type: "text", text: `Request failed: ${status}` }],
+        isError: true,
+    };
+};
+const DEFAULT_API_TOOL_TIMEOUT_MS = 30_000;
+const isTimeoutError = (caught) => {
+    if (!(caught instanceof Error))
+        return false;
+    return (caught.name === "TimeoutError" ||
+        caught.name === "AbortError" ||
+        caught.message === "body read aborted");
+};
+const timedOutResult = (timeoutMs) => ({
+    content: [{ type: "text", text: `Request timed out after ${timeoutMs}ms` }],
+    isError: true,
+});
+/** A timed-out fetch becomes a `ToolResult`; every other throw still propagates. */
+const fetchWithTimeout = async (fetchImpl, input, timeoutMs) => {
+    if (timeoutMs === false)
+        return { response: await fetchImpl(input) };
+    const signal = AbortSignal.timeout(timeoutMs);
+    try {
+        return { response: await fetchImpl(input, { signal }), signal };
+    }
+    catch (caught) {
+        if (isTimeoutError(caught))
+            return timedOutResult(timeoutMs);
+        throw caught;
+    }
+};
+/**
+ * Capped before `respond`/`onError` ever see it — an unbounded res.text()
+ * on the upstream body is the same memory-exhaustion shape an unbounded
+ * *incoming* body is (see body.ts). Rebuilt as a fresh Response from the
+ * raw bytes — not decoded text — so `respond`/`onError` can still call
+ * res.arrayBuffer()/res.blob() on binary bodies as well as res.text()/
+ * res.json(), exactly as if they'd read the original response themselves.
+ * An oversized body, or the timeout signal firing mid-body, becomes a
+ * `ToolResult`; every other throw still propagates.
+ */
+const boundResponse = async (res, maxResponseBytes, timeoutMs, signal) => {
+    let bytes;
+    try {
+        bytes = (await readBoundedBytes(res, maxResponseBytes, signal));
+    }
+    catch (caught) {
+        if (caught instanceof BodyTooLargeError) {
+            return {
+                content: [{ type: "text", text: `Response exceeded ${maxResponseBytes} bytes` }],
+                isError: true,
+            };
+        }
+        if (isTimeoutError(caught))
+            return timedOutResult(timeoutMs);
+        throw caught;
+    }
+    // The buffered body is already decoded and re-framed — the upstream
+    // encoding/length headers no longer describe it.
+    const headers = new Headers(res.headers);
+    headers.delete("content-encoding");
+    headers.delete("content-length");
+    return new Response(bytes, { status: res.status, statusText: res.statusText, headers });
+};
+const runApi = async (options, ctx, args) => {
+    const fetchImpl = options.fetch ?? fetch;
+    const input = await options.request(ctx, args);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_API_TOOL_TIMEOUT_MS;
+    const fetched = await fetchWithTimeout(fetchImpl, input, timeoutMs);
+    if (!("response" in fetched))
+        return fetched;
+    const maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MCP_BODY_LIMIT;
+    const bounded = await boundResponse(fetched.response, maxResponseBytes, timeoutMs, fetched.signal);
+    if (!(bounded instanceof Response))
+        return bounded;
+    if (!bounded.ok)
+        return options.onError ? options.onError(bounded) : defaultErrorResult(bounded);
+    return (options.respond ?? defaultRespond)(bounded);
+};
+/**
+ * Wrap a single REST call as an MCP tool in one call: build the request from
+ * typed args, run it, and shape the response — no hand-rolled fetch/error
+ * plumbing per tool. Built on `defineTool`, so `input` gets the same
+ * validation-before-call treatment.
+ */
+export const apiTool = (options) => {
+    const core = {
+        name: options.name,
+        description: options.description,
+        inputSchema: options.inputSchema,
+        ...pickDefined(options, ["scope"]),
+    };
+    if (options.input) {
+        return defineTool({
+            ...core,
+            input: options.input,
+            handler: (ctx, args) => runApi(options, ctx, args),
+        });
+    }
+    return defineTool({
+        ...core,
+        handler: (ctx, args) => runApi(options, ctx, args),
+    });
+};
+//# sourceMappingURL=tools.js.map

package/dist/mcp/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA2BjD,MAAM,YAAY,GAAG,CAAC,IAAwC,EAAU,EAAE,CACxE,CAAC,IAAI,IAAI,EAAE,CAAC;KACT,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,KAAK,IAAI,OAAO;IACxD,CAAC,CAAC,MAAM,CAAE,OAA4B,CAAC,GAAG,CAAC;IAC3C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CACpB;KACA,IAAI,CAAC,GAAG,CAAC,CAAC;AAEf,MAAM,eAAe,GAAG,KAAK,EAC3B,MAAyC,EACzC,GAAY,EACkB,EAAE;IAChC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;gBAC3B,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACtC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;YAC5D,CAAC,CAAC;SACH,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAG,MAA4B,CAAC,KAAK,EAAE,CAAC;AACxD,CAAC,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,MAAgB,EAAc,EAAE,CAAC,CAAC;IACtD,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACpD,OAAO,EAAE,IAAI;CACd,CAAC,CAAC;AA2BH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,OAAuC,EACxB,EAAE,CAAC,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,WAAW,EAAE,OAAO,CAAC,WAAW;IAChC,WAAW,EAAE,OAAO,CAAC,WAAW;IAChC,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;QAC9B,IAAI,CAAC,OAAO,CAAC,KAAK;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC7D,IAAI,QAAQ,IAAI,MAAM;YAAE,OAAO,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3D,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5C,CAAC;CACF,CAAC,CAAC;AAyCH,MAAM,cAAc,GAAG,CAAC,GAAa,EAAmB,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,CAAC,GAAa,EAAc,EAAE;IACvD,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtE,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,MAAM,EAAE,EAAE,CAAC;QAC9D,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAE3C,MAAM,cAAc,GAAG,CAAC,MAAe,EAAW,EAAE;IAClD,IAAI,CAAC,CAAC,MAAM,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,OAAO,CACL,MAAM,CAAC,IAAI,KAAK,cAAc;QAC9B,MAAM,CAAC,IAAI,KAAK,YAAY;QAC5B,MAAM,CAAC,OAAO,KAAK,mBAAmB,CACvC,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,SAAyB,EAAc,EAAE,CAAC,CAAC;IACjE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,2BAA2B,SAAS,IAAI,EAAE,CAAC;IAC3E,OAAO,EAAE,IAAI;CACd,CAAC,CAAC;AAEH,oFAAoF;AACpF,MAAM,gBAAgB,GAAG,KAAK,EAC5B,SAAuB,EACvB,KAAiB,EACjB,SAAyB,EAC2C,EAAE;IACtE,IAAI,SAAS,KAAK,KAAK;QAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;IACrE,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAClE,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,IAAI,cAAc,CAAC,MAAM,CAAC;YAAE,OAAO,cAAc,CAAC,SAAS,CAAC,CAAC;QAC7D,MAAM,MAAM,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,aAAa,GAAG,KAAK,EACzB,GAAa,EACb,gBAAwB,EACxB,SAAyB,EACzB,MAAoB,EACY,EAAE;IAClC,IAAI,KAA8B,CAAC;IACnC,IAAI,CAAC;QACH,KAAK,GAAG,CAAC,MAAM,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAA4B,CAAC;IAC7F,CAAC;IAAC,OAAO,MAAM,EAAE,CAAC;QAChB,IAAI,MAAM,YAAY,iBAAiB,EAAE,CAAC;YACxC,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,gBAAgB,QAAQ,EAAE,CAAC;gBAChF,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QACD,IAAI,cAAc,CAAC,MAAM,CAAC;YAAE,OAAO,cAAc,CAAC,SAAS,CAAC,CAAC;QAC7D,MAAM,MAAM,CAAC;IACf,CAAC;IACD,oEAAoE;IACpE,iDAAiD;IACjD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACnC,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACjC,OAAO,IAAI,QAAQ,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;AAC1F,CAAC,CAAC;AAEF,MAAM,MAAM,GAAG,KAAK,EAClB,OAA6B,EAC7B,GAAS,EACT,IAAU,EACoB,EAAE;IAChC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,2BAA2B,CAAC;IAEnE,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,CAAC,UAAU,IAAI,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAE7C,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,sBAAsB,CAAC;IAC5E,MAAM,OAAO,GAAG,MAAM,aAAa,CACjC,OAAO,CAAC,QAAQ,EAChB,gBAAgB,EAChB,SAAS,EACT,OAAO,CAAC,MAAM,CACf,CAAC;IACF,IAAI,CAAC,CAAC,OAAO,YAAY,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC;IAEnD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACjG,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC;AACtD,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,OAAoC,EACrB,EAAE;IACjB,MAAM,IAAI,GAAG;QACX,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;KACnC,CAAC;IACF,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,OAAO,UAAU,CAAc;YAC7B,GAAG,IAAI;YACP,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;SACnD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,UAAU,CAAO;QACtB,GAAG,IAAI;QACP,OAAO,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;KACnD,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/{validate.d.ts → mcp/validate.d.ts}

@@ -1,21 +1,33 @@
 export type JsonSchema = {
-    type?: string;
+    /** A single type, or a union (`["string", "null"]`) — both are evaluated. */
+    type?: string | string[];
     properties?: Record<string, JsonSchema>;
     required?: string[];
     enum?: unknown[];
     items?: JsonSchema;
     minimum?: number;
     maximum?: number;
+    /** Only the boolean form is evaluated; a schema-valued form is unsupported. */
+    additionalProperties?: boolean | JsonSchema;
     description?: string;
     title?: string;
     [key: string]: unknown;
 };
+export declare const JSON_SCHEMA_TYPES: {
+    readonly string: "string";
+    readonly number: "number";
+    readonly integer: "integer";
+    readonly boolean: "boolean";
+    readonly object: "object";
+    readonly array: "array";
+    readonly null: "null";
+};
 /** Keywords `validateAgainstSchema` actually evaluates. */
 export declare const SUPPORTED_SCHEMA_KEYWORDS: ReadonlySet<string>;
 /**
  * Allowed on inputSchema but never evaluated (tools/list / generator metadata).
- * Semantically-enforcing keywords (`pattern`, `additionalProperties`, …) are
- * not ignored — with `validateArgs: true` they throw at construction.
+ * Semantically-enforcing keywords (`pattern`, `oneOf`, …) are not ignored —
+ * with `validateArgs: true` they throw at construction.
  */
 export declare const IGNORED_SCHEMA_KEYWORDS: ReadonlySet<string>;
 /**
@@ -23,15 +35,15 @@ export declare const IGNORED_SCHEMA_KEYWORDS: ReadonlySet<string>;
  * Walks nested `properties` / `items`.
  */
 export declare const unsupportedKeywords: (schema: JsonSchema, path?: string) => string[];
-export declare const JSON_SCHEMA_TYPES: {
-    readonly string: "string";
-    readonly number: "number";
-    readonly integer: "integer";
-    readonly boolean: "boolean";
-    readonly object: "object";
-    readonly array: "array";
-    readonly null: "null";
-};
+/**
+ * Paths where `properties`/`required` implies an object shape but `type`
+ * doesn't say so — absent, or a type/union without `"object"`. Such a
+ * schema would otherwise accept any input, `{}` included. Under
+ * `validateArgs: true` this throws at construction; `validateNode`'s
+ * dispatch on the value's runtime type is the backstop for schemas that
+ * reach validation unchecked.
+ */
+export declare const missingObjectType: (schema: JsonSchema, path?: string) => string[];
 /** Minimal JSON Schema subset used by MCP tool inputSchema. Empty = valid. */
 export declare const validateAgainstSchema: (value: unknown, schema: JsonSchema) => string[];
 //# sourceMappingURL=validate.d.ts.map

package/dist/mcp/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/mcp/validate.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG;IACvB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;CAQpB,CAAC;AAkBX,2DAA2D;AAC3D,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CASxD,CAAC;AAUH;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAYtD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,UAAU,EAAE,aAAa,KAAG,MAAM,EAU7E,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,UAAU,EAAE,aAAa,KAAG,MAAM,EAS3E,CAAC;AAiHF,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,GAAI,OAAO,OAAO,EAAE,QAAQ,UAAU,KAAG,MAAM,EAC5C,CAAC"}