stitchkit 0.103.12 → 0.104.0

package/dist/index-bhb950qs.js

@@ -0,0 +1,1145 @@
+import {
+  toJsonSchema
+} from "./index-ct75c3at.js";
+import {
+  AppError2
+} from "./index-x928baz2.js";
+import {
+  resolvePropagationContext2
+} from "./index-yex7eg1v.js";
+import {
+  toolSurfaceOutputSchema,
+  staticInputRounds,
+  validateMcpRoundPolicy,
+  validateResolvedInputRounds,
+  presentationMetadata,
+  prepareProjectedMcpTools
+} from "./index-77nxk6ay.js";
+import {
+  parseToolCallArguments,
+  toolResultFromError,
+  observed
+} from "./index-2vnh05w4.js";
+import {
+  collectTools2,
+  createToolRunner,
+  formatToolError
+} from "./index-2hyavjjj.js";
+import {
+  redact2
+} from "./index-e6c2spsd.js";
+import {
+  DEFAULT_CORS_ALLOW_HEADERS2,
+  DEFAULT_PROCESS_SIGNALS,
+  defaultSignalSource,
+  reportSignalError,
+  guardSignalCallback
+} from "./index-yk4g8805.js";
+import {
+  collectToolSurface
+} from "./index-a0zzh8ak.js";
+import {
+  argumentsDigest
+} from "./index-r7a7r7ha.js";
+import {
+  runWithRequestContext2,
+  getRequestContext2
+} from "./index-7n68nmc6.js";
+import {
+  compareCodeUnits,
+  serializeCanonicalJson
+} from "./index-zsvzhjtk.js";
+import {
+  isRecord
+} from "./index-9jfdm5tg.js";
+
+// src/server/oauth/metadata.ts
+var PROTECTED_RESOURCE_PATH2 = "/.well-known/oauth-protected-resource";
+function metadataPath(resource) {
+  const { pathname } = new URL(resource);
+  return pathname === "/" ? PROTECTED_RESOURCE_PATH2 : `${PROTECTED_RESOURCE_PATH2}${pathname}`;
+}
+function protectedResourceMetadataUrl2(resource) {
+  return `${new URL(resource).origin}${metadataPath(resource)}`;
+}
+function wwwAuthenticateHeader2(resource) {
+  return `Bearer resource_metadata="${protectedResourceMetadataUrl2(resource)}"`;
+}
+var PUBLIC_CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": DEFAULT_CORS_ALLOW_HEADERS2
+};
+function oauthProtectedResourceRoute2(config) {
+  const body = JSON.stringify({
+    resource: config.resource,
+    authorization_servers: config.authorizationServers,
+    ...config.scopesSupported && { scopes_supported: config.scopesSupported },
+    bearer_methods_supported: ["header"]
+  });
+  return {
+    method: "ALL",
+    path: metadataPath(config.resource),
+    handler: (req) => {
+      if (req.method === "OPTIONS")
+        return new Response(null, { status: 204, headers: PUBLIC_CORS });
+      if (req.method !== "GET")
+        return new Response("Method Not Allowed", { status: 405 });
+      return new Response(body, {
+        status: 200,
+        headers: { "Content-Type": "application/json", ...PUBLIC_CORS }
+      });
+    }
+  };
+}
+
+// src/tools/mcp/app.ts
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+var RESOURCE_MIME_TYPE2 = "text/html;profile=mcp-app";
+var EXT_APPS_BUNDLE_PLACEHOLDER2 = "/*__EXT_APPS_BUNDLE__*/";
+function inlineMcpAppBundle2(html) {
+  if (!html.includes(EXT_APPS_BUNDLE_PLACEHOLDER2))
+    return html;
+  let bundlePath;
+  try {
+    bundlePath = fileURLToPath(import.meta.resolve("@modelcontextprotocol/ext-apps/app-with-deps"));
+  } catch {
+    throw new Error("[stitchkit] inlineMcpAppBundle: '@modelcontextprotocol/ext-apps' is not installed. " + "Add it as a dependency to serve MCP App widgets.");
+  }
+  const bundle = readFileSync(bundlePath, "utf8").replace(/export\{([^}]+)\};?\s*$/, (_match, body) => `globalThis.ExtApps={${body.split(",").map((pair) => {
+    const [local, exported] = pair.split(" as ").map((s) => s.trim());
+    return `${exported ?? local}:${local}`;
+  }).join(",")}};`);
+  return html.replace(EXT_APPS_BUNDLE_PLACEHOLDER2, () => bundle);
+}
+
+// src/tools/mcp/catalog.ts
+import { createHash } from "node:crypto";
+var MCP_CATALOG_META_KEY2 = "stitchkit/catalog";
+var stampCache = new WeakMap;
+function toolFingerprint(descriptor) {
+  const { mountable } = descriptor;
+  return {
+    name: mountable.name,
+    description: mountable.method.desc,
+    input: descriptor.inputSchema,
+    output: descriptor.outputSchema ? toJsonSchema(descriptor.outputSchema, "output", "any") : null,
+    annotations: mountable.method.annotations ?? null
+  };
+}
+function mcpCatalogStamp(surface) {
+  const cached = stampCache.get(surface);
+  if (cached)
+    return cached;
+  const descriptors = [
+    ...surface.contractTools,
+    ...surface.runtimeTools.map((entry) => entry.descriptor)
+  ].sort((left, right) => compareCodeUnits(left.mountable.name, right.mountable.name));
+  const bytes = serializeCanonicalJson(descriptors.map(toolFingerprint));
+  const stamp = {
+    digest: createHash("sha256").update(bytes).digest("hex").slice(0, 16),
+    tools: descriptors.length
+  };
+  stampCache.set(surface, stamp);
+  return stamp;
+}
+function mcpCatalogMeta2(stamp) {
+  return { [MCP_CATALOG_META_KEY2]: { ...stamp } };
+}
+function readMcpCatalogStamp2(meta) {
+  if (!isRecord(meta))
+    return null;
+  const value = meta[MCP_CATALOG_META_KEY2];
+  if (!isRecord(value))
+    return null;
+  const { digest, tools } = value;
+  if (typeof digest !== "string" || digest.length === 0)
+    return null;
+  if (typeof tools !== "number" || !Number.isInteger(tools) || tools < 0)
+    return null;
+  return { digest, tools };
+}
+function stampToolRegistration(config, stamp) {
+  if (!stamp)
+    return config;
+  return { ...config, _meta: { ...config._meta, ...mcpCatalogMeta2(stamp) } };
+}
+function stampToolResult(result, stamp) {
+  if (!stamp)
+    return result;
+  return { ...result, _meta: { ...result._meta, ...mcpCatalogMeta2(stamp) } };
+}
+
+// src/tools/mcp/mount.ts
+import {
+  createRequestStateCodec,
+  McpServer
+} from "@modelcontextprotocol/server";
+
+// src/tools/mcp/prepare.ts
+function textBlock(text) {
+  return [{ type: "text", text }];
+}
+function formatMcpResult(result, mode, toolName, errorHint) {
+  if (result.ok) {
+    if (mode === "none")
+      return { content: [] };
+    let serialized;
+    try {
+      serialized = JSON.stringify(result.data, null, 2);
+    } catch {
+      serialized = undefined;
+    }
+    if (serialized === undefined) {
+      const safe = redact2(result.data, { sensitiveKeys: /(?!)/ });
+      return { content: textBlock(JSON.stringify(safe, null, 2)), structuredContent: safe };
+    }
+    return { content: textBlock(serialized), structuredContent: result.data };
+  }
+  return {
+    content: textBlock(JSON.stringify(formatToolError(result, toolName, errorHint), null, 2)),
+    isError: true
+  };
+}
+function prepareMcpSurface(services, config = {}) {
+  const serviceList = Array.isArray(services) ? services : [services];
+  const tools = serviceList.flatMap((service) => collectTools2(service, "MCP", config));
+  return prepareMcpTools(tools, config);
+}
+function prepareMcpTools(tools, config = {}) {
+  const prepared = prepareProjectedMcpTools(tools.map((mountable) => {
+    const outputSchema = toolSurfaceOutputSchema(mountable.method);
+    return {
+      tool: mountable,
+      name: mountable.name,
+      ...mountable.method.paramsSchema !== undefined && {
+        paramsSchema: mountable.method.paramsSchema
+      },
+      ...mountable.method.inputSchema !== undefined && {
+        inputSchema: mountable.method.inputSchema
+      },
+      ...mountable.method.toolView?.defaults !== undefined && {
+        inputDefaults: mountable.method.toolView.defaults
+      },
+      ...outputSchema !== undefined && { outputSchema },
+      shouldExtend: mountable.shouldExtend,
+      ...mountable.method.mcp !== undefined && { mcp: mountable.method.mcp }
+    };
+  }), config).map((entry) => {
+    Object.freeze(entry.tool);
+    return Object.freeze({
+      mountable: entry.tool,
+      inputSchema: entry.inputSchema,
+      ...entry.outputSchema !== undefined && { outputSchema: entry.outputSchema },
+      outputMode: entry.outputSchema === undefined ? "none" : "direct"
+    });
+  });
+  return Object.freeze(prepared);
+}
+function prepareMcpServerSurface(surface, config = {}) {
+  const contractMountables = [];
+  const definitions = [];
+  const runtimeMountables = [];
+  for (const entry of collectToolSurface({
+    surface,
+    transport: "MCP",
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput
+  })) {
+    if (entry.kind === "contract") {
+      contractMountables.push(entry.mountable);
+    } else {
+      definitions.push(entry.definition);
+      runtimeMountables.push(entry.mountable);
+    }
+  }
+  const contractTools = prepareMcpTools(contractMountables, config);
+  const runtimeDescriptors = prepareMcpTools(runtimeMountables, {
+    schemaValidation: config.schemaValidation,
+    logger: config.logger,
+    multiRound: config.multiRound
+  });
+  const descriptorsByName = new Map(runtimeDescriptors.map((descriptor) => [descriptor.mountable.name, descriptor]));
+  const runtimeTools = [];
+  for (const definition of definitions) {
+    const descriptor = descriptorsByName.get(definition.name);
+    if (descriptor)
+      runtimeTools.push(Object.freeze({ definition, descriptor }));
+  }
+  return Object.freeze({ contractTools, runtimeTools: Object.freeze(runtimeTools) });
+}
+
+// src/tools/mcp/register.ts
+import {
+  isCallToolResult
+} from "@modelcontextprotocol/server";
+import { z as z2 } from "zod";
+
+// src/tools/mcp/round.ts
+import {
+  acceptedContent,
+  inputRequired,
+  inputResponse
+} from "@modelcontextprotocol/server";
+import { z } from "zod";
+
+// src/tools/mcp/round-context.ts
+import {
+  CLIENT_INFO_META_KEY,
+  PROTOCOL_VERSION_META_KEY
+} from "@modelcontextprotocol/server";
+
+// src/tools/mcp/progress.ts
+function mcpProgressToken(context) {
+  const token = context.mcpReq._meta?.progressToken;
+  return typeof token === "string" || typeof token === "number" ? token : undefined;
+}
+function createMcpProgressReporter(context) {
+  const token = mcpProgressToken(context);
+  if (token === undefined)
+    return async () => {
+      return;
+    };
+  let sent = 0;
+  let highWater = 0;
+  return async (update) => {
+    sent += 1;
+    const value = update.progress ?? Math.max(sent, highWater + 1);
+    highWater = Math.max(highWater, value);
+    try {
+      await context.mcpReq.notify({
+        method: "notifications/progress",
+        params: {
+          progressToken: token,
+          progress: value,
+          ...update.total !== undefined && { total: update.total },
+          ...update.message !== undefined && { message: update.message }
+        }
+      });
+    } catch {}
+  };
+}
+
+// src/tools/mcp/round-context.ts
+function transportContext(context, toolName, outcome, round) {
+  const protocolVersionValue = isRecord(context.mcpReq.envelope) ? Reflect.get(context.mcpReq.envelope, PROTOCOL_VERSION_META_KEY) : undefined;
+  const protocolVersion = typeof protocolVersionValue === "string" ? protocolVersionValue : undefined;
+  const clientInfoValue = isRecord(context.mcpReq.envelope) ? Reflect.get(context.mcpReq.envelope, CLIENT_INFO_META_KEY) : undefined;
+  const clientInfo = isRecord(clientInfoValue) && typeof clientInfoValue.name === "string" && typeof clientInfoValue.version === "string" ? { name: clientInfoValue.name, version: clientInfoValue.version } : undefined;
+  const token = mcpProgressToken(context);
+  return {
+    signal: context.mcpReq.signal,
+    mcp: {
+      era: context.mcpReq.envelope ? "modern" : "legacy",
+      method: context.mcpReq.method,
+      toolName,
+      ...protocolVersion !== undefined && { protocolVersion },
+      ...clientInfo !== undefined && { clientInfo },
+      ...outcome !== undefined && { outcome },
+      ...round !== undefined && { round },
+      ...token !== undefined && { progressToken: token }
+    },
+    reportProgress: createMcpProgressReporter(context)
+  };
+}
+function operationIdentity(tool) {
+  return {
+    toolName: tool.name,
+    serviceName: tool.method.serviceName,
+    action: tool.method.key,
+    method: tool.method.method,
+    ...tool.method.scope !== undefined && { scope: tool.method.scope }
+  };
+}
+function sameIdentity(left, right) {
+  return left.toolName === right.toolName && left.serviceName === right.serviceName && left.action === right.action && left.method === right.method && left.scope === right.scope;
+}
+async function runRoundSuccess(tool, rawArgs, runTool, context) {
+  return runTool({
+    ...tool,
+    method: {
+      ...tool.method,
+      outputSchema: undefined,
+      handler: () => {
+        return;
+      }
+    }
+  }, rawArgs, context);
+}
+async function runRoundFailure(tool, rawArgs, runTool, context, code, message) {
+  return runTool({
+    ...tool,
+    method: {
+      ...tool.method,
+      outputSchema: undefined,
+      handler: () => {
+        throw new AppError2(code, message, 400);
+      }
+    }
+  }, rawArgs, context);
+}
+async function failedResolution(options) {
+  const result = await runRoundFailure(options.tool, options.rawArgs, options.runTool, options.context, options.code, options.message);
+  return { kind: "response", response: options.formatFailure(result) };
+}
+
+// src/tools/mcp/round.ts
+function roundPlanDigest(requests) {
+  return argumentsDigest({
+    plan: requests.map((request) => ({
+      key: request.key,
+      message: request.message,
+      schema: z.toJSONSchema(request.schema, { io: "input", unrepresentable: "any" })
+    }))
+  });
+}
+async function resolveRequests(options, policy) {
+  const declared = staticInputRounds(policy);
+  if (declared)
+    return { requests: declared, guarded: false };
+  const parsed = parseToolCallArguments(options.tool.method, options.rawArgs, {
+    coerceJson: options.coerceJsonArgs ?? true,
+    toolSurface: true
+  });
+  if (!parsed.ok) {
+    return { requests: [], guarded: false };
+  }
+  const resolver = policy.inputRequired;
+  const resolved = await resolver({ params: parsed.params, input: parsed.input });
+  validateResolvedInputRounds(options.tool, resolved, options.runtime?.maxRounds ?? 1);
+  return { requests: resolved, guarded: false };
+}
+async function askRound(runtime, context, request, state) {
+  const requestState = await runtime.codec.mint(state, context);
+  return {
+    kind: "response",
+    response: inputRequired({
+      inputRequests: {
+        [request.key]: inputRequired.elicit({
+          message: request.message,
+          requestedSchema: request.schema
+        })
+      },
+      requestState
+    })
+  };
+}
+function readRoundAnswer(context, request) {
+  const view = inputResponse(context.mcpReq.inputResponses, request.key);
+  if (view.kind !== "elicit") {
+    return {
+      refusal: {
+        outcome: "invalid",
+        code: "INVALID_INPUT_RESPONSE",
+        message: "Expected an elicitation response for the current round"
+      }
+    };
+  }
+  if (view.action !== "accept") {
+    const declined = view.action === "decline";
+    return {
+      refusal: {
+        outcome: declined ? "declined" : "cancelled",
+        code: declined ? "INPUT_DECLINED" : "INPUT_CANCELLED",
+        message: declined ? "Required input was declined" : "Required input was cancelled"
+      }
+    };
+  }
+  const content = acceptedContent(context.mcpReq.inputResponses, request.key, request.schema);
+  if (!content) {
+    return {
+      refusal: {
+        outcome: "invalid",
+        code: "INVALID_INPUT_RESPONSE",
+        message: "Accepted input failed its declared schema"
+      }
+    };
+  }
+  return { content };
+}
+async function resolveMcpRound(options) {
+  const { policy } = options;
+  if (!policy) {
+    return {
+      kind: "continue",
+      context: transportContext(options.context, options.tool.name)
+    };
+  }
+  if (!options.runtime) {
+    throw new Error(`[stitchkit] MCP tool "${options.tool.name}" declares inputRequired but no multiRound.state key is configured`);
+  }
+  validateMcpRoundPolicy(options.tool, policy, {
+    stateConfigured: true,
+    maxRounds: options.runtime.maxRounds
+  });
+  const state = options.context.mcpReq.requestState();
+  const digest = argumentsDigest(options.rawArgs);
+  if (state) {
+    const mismatched = !sameIdentity(state.identity, operationIdentity(options.tool)) || state.argumentsDigest !== digest || !Number.isInteger(state.round) || state.round < 0 || state.round >= options.runtime.maxRounds || !isRecord(state.accepted);
+    if (mismatched) {
+      return failedResolution({
+        ...options,
+        context: transportContext(options.context, options.tool.name, "invalid", Number.isInteger(state.round) ? state.round : 0),
+        code: "INVALID_REQUEST_STATE",
+        message: "Continuation state does not match this operation, arguments or round"
+      });
+    }
+  }
+  const dynamic = staticInputRounds(policy) === undefined;
+  if (dynamic) {
+    const guarded = await runRoundSuccess(options.tool, options.rawArgs, options.runTool, transportContext(options.context, options.tool.name, "input_required", state?.round ?? 0));
+    if (!guarded.ok)
+      return { kind: "response", response: options.formatFailure(guarded) };
+  }
+  const resolution = await resolveRequests(options, policy);
+  if ("failure" in resolution)
+    return resolution.failure;
+  const requests = resolution.requests;
+  const alreadyGuarded = dynamic;
+  const planDigest = roundPlanDigest(requests);
+  if (requests.length === 0 && !state) {
+    return {
+      kind: "continue",
+      context: transportContext(options.context, options.tool.name)
+    };
+  }
+  if (!state) {
+    if (isRecord(options.context.mcpReq.inputResponses)) {
+      return failedResolution({
+        ...options,
+        context: transportContext(options.context, options.tool.name, "invalid", 0),
+        code: "INVALID_REQUEST_STATE",
+        message: "Input responses require a valid continuation state"
+      });
+    }
+    if (!alreadyGuarded) {
+      const guarded = await runRoundSuccess(options.tool, options.rawArgs, options.runTool, transportContext(options.context, options.tool.name, "input_required", 0));
+      if (!guarded.ok) {
+        return { kind: "response", response: options.formatFailure(guarded) };
+      }
+    }
+    const request = requests[0];
+    if (!request)
+      throw new Error("[stitchkit] validated MRTR policy has no first round");
+    return askRound(options.runtime, options.context, request, {
+      identity: operationIdentity(options.tool),
+      argumentsDigest: digest,
+      round: 0,
+      accepted: {},
+      planDigest
+    });
+  }
+  if (state.planDigest !== planDigest || state.round >= requests.length) {
+    return failedResolution({
+      ...options,
+      context: transportContext(options.context, options.tool.name, "invalid", state.round),
+      code: "INVALID_REQUEST_STATE",
+      message: state.round >= requests.length ? "Continuation state does not match this operation, arguments or round" : "The questions for this call changed between rounds"
+    });
+  }
+  const request = requests[state.round];
+  if (!request)
+    throw new Error("[stitchkit] validated MRTR state points outside its policy");
+  const answer = readRoundAnswer(options.context, request);
+  if ("refusal" in answer) {
+    return failedResolution({
+      ...options,
+      context: transportContext(options.context, options.tool.name, answer.refusal.outcome, state.round),
+      code: answer.refusal.code,
+      message: answer.refusal.message
+    });
+  }
+  const { content } = answer;
+  const accepted = { ...state.accepted, [request.key]: content };
+  const nextRound = state.round + 1;
+  const nextRequest = requests[nextRound];
+  if (nextRequest) {
+    if (!alreadyGuarded) {
+      const guarded = await runRoundSuccess(options.tool, options.rawArgs, options.runTool, transportContext(options.context, options.tool.name, "input_required", nextRound));
+      if (!guarded.ok) {
+        return { kind: "response", response: options.formatFailure(guarded) };
+      }
+    }
+    return askRound(options.runtime, options.context, nextRequest, {
+      identity: state.identity,
+      argumentsDigest: state.argumentsDigest,
+      round: nextRound,
+      accepted,
+      planDigest
+    });
+  }
+  return {
+    kind: "continue",
+    context: {
+      ...transportContext(options.context, options.tool.name, "complete", state.round),
+      mcpInput: accepted
+    }
+  };
+}
+
+// src/tools/mcp/trace.ts
+import {
+  BAGGAGE_META_KEY,
+  TRACEPARENT_META_KEY,
+  TRACESTATE_META_KEY
+} from "@modelcontextprotocol/server";
+function runInMcpRequestContext(context, toolName, body) {
+  const ambient = getRequestContext2();
+  const metadata = context.mcpReq._meta;
+  const propagation = metadata ? {
+    traceparent: metadata[TRACEPARENT_META_KEY],
+    tracestate: metadata[TRACESTATE_META_KEY],
+    baggage: metadata[BAGGAGE_META_KEY]
+  } : undefined;
+  const request = {
+    ...ambient ?? {
+      source: "mcp",
+      method: "MCP",
+      path: `/mcp/${toolName}`,
+      startedAt: process.hrtime.bigint()
+    },
+    trace: resolvePropagationContext2(propagation, ambient?.trace),
+    source: "mcp",
+    method: "MCP",
+    path: `/mcp/${toolName}`,
+    startedAt: process.hrtime.bigint(),
+    dimensions: ambient?.dimensions ? { ...ambient.dimensions } : undefined,
+    error: undefined
+  };
+  return runWithRequestContext2(request, body);
+}
+
+// src/tools/mcp/register.ts
+function registerMcpTool(server, presentation, descriptor, config) {
+  const { mountable } = descriptor;
+  const toolConfig = {
+    description: presentation.description,
+    inputSchema: z2.looseObject({}).meta(presentationMetadata(descriptor.inputSchema))
+  };
+  if (descriptor.outputSchema)
+    toolConfig.outputSchema = descriptor.outputSchema;
+  if (presentation.annotations)
+    toolConfig.annotations = presentation.annotations;
+  if (presentation.ui) {
+    toolConfig._meta = {
+      ui: presentation.ui,
+      "ui/resourceUri": presentation.ui.resourceUri
+    };
+  }
+  const { name } = presentation;
+  const format = config.formatResult;
+  server.registerTool(name, stampToolRegistration(toolConfig, config.catalog), async (rawArgs, mcpContext) => stampToolResult(await runInMcpRequestContext(mcpContext, name, async () => {
+    const args = isRecord(rawArgs) ? rawArgs : {};
+    const startedAt = Date.now();
+    try {
+      const round = await resolveMcpRound({
+        tool: mountable,
+        rawArgs: args,
+        context: mcpContext,
+        policy: mountable.method.mcp,
+        runtime: config.multiRoundRuntime,
+        runTool: config.runTool,
+        formatFailure: (result) => format(result, "none", name)
+      });
+      if (round.kind === "response")
+        return round.response;
+      const { present } = presentation;
+      if (!present) {
+        const result = await config.runTool(mountable, args, round.context);
+        return format(result, descriptor.outputMode, name);
+      }
+      const result = await config.runTool(mountable, args, round.context, {
+        finalizeOutput: async (data) => {
+          const presented = await present(data);
+          if (!isRecord(presented)) {
+            throw new AppError2("INTERNAL_SERVER_ERROR", "Runtime MCP presenter did not return a result", 500);
+          }
+          if ("structuredContent" in presented || "isError" in presented) {
+            throw new AppError2("INTERNAL_SERVER_ERROR", "Runtime MCP presenter cannot set framework-owned structuredContent or isError", 500);
+          }
+          const structured = format({ ok: true, data }, descriptor.outputMode, name).structuredContent;
+          const response = structured === undefined ? presented : { ...presented, structuredContent: structured };
+          if (!isCallToolResult(response)) {
+            throw new AppError2("INTERNAL_SERVER_ERROR", "Runtime MCP presenter returned an invalid CallToolResult", 500);
+          }
+          return response;
+        }
+      });
+      if (!result.ok)
+        return format(result, "none", name);
+      if (!isCallToolResult(result.data)) {
+        throw new Error("[stitchkit] Runtime MCP presenter invariant failed");
+      }
+      return result.data;
+    } catch (err) {
+      const context = {
+        ...config.context,
+        ...transportContext(mcpContext, name),
+        source: "mcp"
+      };
+      const result = toolResultFromError(err);
+      await observed("onToolError", () => config.hooks?.onToolError?.({
+        toolName: name,
+        error: err,
+        context,
+        endpoint: mountable.method
+      }));
+      await observed("afterToolCall", () => config.hooks?.afterToolCall?.({
+        toolName: name,
+        args,
+        result,
+        durationMs: Date.now() - startedAt,
+        error: err,
+        context,
+        endpoint: mountable.method
+      }));
+      return format(result, "none", name);
+    }
+  }), config.catalog));
+}
+
+// src/tools/mcp/runtime-tools.ts
+function mountPreparedRuntimeMcp(server, tools, config) {
+  const runTool = createToolRunner({
+    source: "mcp",
+    toolSurface: true,
+    context: config.context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    coerceJsonArgs: config.coerceJsonArgs,
+    onOutputStrip: config.onOutputStrip
+  });
+  for (const { definition, descriptor } of tools) {
+    const present = definition.present?.mcp;
+    registerMcpTool(server, {
+      name: definition.name,
+      description: definition.description,
+      annotations: definition.annotations,
+      ui: definition.ui,
+      ...present && { present }
+    }, descriptor, {
+      runTool,
+      formatResult: config.formatResult,
+      catalog: config.catalog,
+      multiRoundRuntime: config.multiRoundRuntime,
+      hooks: config.hooks,
+      context: config.context
+    });
+  }
+}
+
+// src/tools/mcp/mount.ts
+function validateMcpSchemas2(config) {
+  prepareMcpSurface(config.services, {
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config,
+    logger: config.logger
+  });
+}
+function mountMcp2(mcpServer, services, config = {}) {
+  const prepared = prepareMcpSurface(services, {
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config.schemaValidation,
+    logger: config.logger
+  });
+  mountPreparedMcp(mcpServer, prepared, {
+    ...config,
+    catalog: mcpCatalogStamp({ contractTools: prepared, runtimeTools: [] })
+  });
+}
+function mountPreparedMcp(mcpServer, prepared, config = {}) {
+  const runTool = createToolRunner({
+    source: "mcp",
+    toolSurface: true,
+    extend: config.extend,
+    context: config.context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    coerceJsonArgs: config.coerceJsonArgs,
+    onOutputStrip: config.onOutputStrip
+  });
+  for (const descriptor of prepared) {
+    const { method, name } = descriptor.mountable;
+    registerMcpTool(mcpServer, {
+      name,
+      description: method.desc,
+      annotations: method.annotations,
+      ui: method.ui
+    }, descriptor, {
+      runTool,
+      formatResult: (result, mode, toolName) => formatMcpResult(result, mode, toolName, config.errorHint),
+      catalog: config.catalog,
+      multiRoundRuntime: config.multiRoundRuntime,
+      hooks: config.hooks,
+      context: config.context
+    });
+  }
+}
+function buildMcpServer2(config, auth) {
+  if (!isMcpServerBuildConfig(config)) {
+    throw new TypeError("[stitchkit] buildMcpServer requires a valid config object");
+  }
+  let surface;
+  if (config.surfaces) {
+    const key = config.selectSurface(auth);
+    if (!Object.hasOwn(config.surfaces, key)) {
+      throw new Error(`[stitchkit] Unknown MCP surface "${key}"`);
+    }
+    const selected = config.surfaces[key];
+    if (!selected)
+      throw new Error(`[stitchkit] Unknown MCP surface "${key}"`);
+    surface = selected;
+  } else {
+    const services = typeof config.services === "function" ? config.services(auth) : config.services;
+    const runtimeTools = typeof config.runtimeTools === "function" ? config.runtimeTools(auth) : config.runtimeTools;
+    surface = { services, runtimeTools };
+  }
+  const prepared = prepareMcpServerSurface(surface, {
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config.schemaValidation,
+    logger: config.logger,
+    multiRound: {
+      stateConfigured: config.multiRound !== undefined,
+      maxRounds: config.multiRound?.serving?.maxRounds ?? 10
+    }
+  });
+  return buildMcpServerFromPrepared(config, auth, prepared);
+}
+function isMcpServerBuildConfig(value) {
+  return isRecord(value) && isRecord(value.serverInfo);
+}
+function buildMcpServerFromPrepared(config, auth, prepared) {
+  let roundCodec;
+  if (config.multiRound) {
+    const principal = config.multiRound.state.principal(auth);
+    roundCodec = createRequestStateCodec({
+      key: config.multiRound.state.key,
+      ttlSeconds: config.multiRound.state.ttlSeconds,
+      bind: (mcpContext) => `${mcpContext.mcpReq.method}\x00${principal}`
+    });
+  }
+  const dynamicSurface = !config.surfaces && (typeof config.services === "function" || typeof config.runtimeTools === "function");
+  const serverOptions = {
+    ...config.instructions !== undefined && { instructions: config.instructions },
+    ...!dynamicSurface && config.cache?.operations !== undefined && {
+      cacheHints: config.cache.operations
+    },
+    ...config.multiRound?.serving !== undefined && {
+      inputRequired: config.multiRound.serving
+    },
+    ...roundCodec !== undefined && {
+      requestState: { verify: roundCodec.verify }
+    }
+  };
+  const server = new McpServer(config.serverInfo, serverOptions);
+  const context = config.context?.(auth);
+  const catalog = mcpCatalogStamp(prepared);
+  mountPreparedMcp(server, prepared.contractTools, {
+    catalog,
+    context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    extend: config.extend,
+    schemaValidation: config.schemaValidation,
+    logger: config.logger,
+    coerceJsonArgs: config.coerceJsonArgs,
+    flattenUnionInput: config.flattenUnionInput,
+    errorHint: config.errorHint,
+    onOutputStrip: config.onOutputStrip,
+    ...roundCodec !== undefined && {
+      multiRoundRuntime: {
+        codec: roundCodec,
+        maxRounds: config.multiRound?.serving?.maxRounds ?? 10
+      }
+    }
+  });
+  mountPreparedRuntimeMcp(server, prepared.runtimeTools, {
+    catalog,
+    context,
+    hooks: config.hooks,
+    lifecycle: config.lifecycle,
+    coerceJsonArgs: config.coerceJsonArgs,
+    onOutputStrip: config.onOutputStrip,
+    formatResult: (result, mode, toolName) => formatMcpResult(result, mode, toolName, config.errorHint),
+    ...roundCodec !== undefined && {
+      multiRoundRuntime: {
+        codec: roundCodec,
+        maxRounds: config.multiRound?.serving?.maxRounds ?? 10
+      }
+    }
+  });
+  config.rawTools?.(server, auth);
+  for (const resource of config.resources ?? []) {
+    mountMcpResource2(server, resource);
+  }
+  return server;
+}
+function mountMcpResource2(server, resource) {
+  server.registerResource(resource.name, resource.uri, {
+    mimeType: resource.mimeType ?? RESOURCE_MIME_TYPE2,
+    ...resource.cacheHint !== undefined && { cacheHint: resource.cacheHint }
+  }, async () => ({
+    contents: [
+      {
+        uri: resource.uri,
+        mimeType: resource.mimeType ?? RESOURCE_MIME_TYPE2,
+        text: await resource.read(),
+        ...resource.ui && { _meta: { ui: resource.ui } }
+      }
+    ]
+  }));
+}
+
+// src/tools/mcp/handler.ts
+import {
+  createMcpHandler as createSdkMcpHandler,
+  hostHeaderValidationResponse,
+  localhostAllowedHostnames,
+  localhostAllowedOrigins,
+  originValidationResponse
+} from "@modelcontextprotocol/server";
+function jsonRpcError(code, message, status, headers) {
+  return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status, headers });
+}
+function hostValidationResponse(request, allowedHosts) {
+  if (request.headers.has("host")) {
+    return hostHeaderValidationResponse(request, [...allowedHosts]);
+  }
+  const hostname = new URL(request.url).hostname;
+  if (allowedHosts.includes(hostname))
+    return;
+  return jsonRpcError(-32000, "Invalid Host header", 403);
+}
+function prepareStaticSurface(config) {
+  const preparation = {
+    logger: config.logger,
+    extend: config.extend,
+    flattenUnionInput: config.flattenUnionInput,
+    schemaValidation: config.schemaValidation,
+    multiRound: {
+      stateConfigured: config.multiRound !== undefined,
+      maxRounds: config.multiRound?.serving?.maxRounds ?? 10
+    }
+  };
+  if (config.surfaces && config.selectSurface) {
+    const preparedByKey = new Map;
+    const preparedBySurface = new WeakMap;
+    for (const key in config.surfaces) {
+      if (!Object.hasOwn(config.surfaces, key))
+        continue;
+      const surface = config.surfaces[key];
+      if (!surface)
+        continue;
+      const existing = preparedBySurface.get(surface);
+      const prepared = existing ?? prepareMcpServerSurface(surface, preparation);
+      if (!existing)
+        preparedBySurface.set(surface, prepared);
+      preparedByKey.set(key, prepared);
+    }
+    return (auth) => {
+      const key = config.selectSurface(auth);
+      const prepared = preparedByKey.get(key);
+      if (!prepared)
+        throw new Error(`[stitchkit] Unknown MCP surface "${key}"`);
+      return buildMcpServerFromPrepared(config, auth, prepared);
+    };
+  }
+  if (config.services && typeof config.services !== "function" && typeof config.runtimeTools !== "function") {
+    const prepared = prepareMcpServerSurface({ services: config.services, runtimeTools: config.runtimeTools }, preparation);
+    return (auth) => buildMcpServerFromPrepared(config, auth, prepared);
+  }
+  return null;
+}
+function createMcpHandler2(config) {
+  const buildPrepared = prepareStaticSurface(config);
+  const authByCarrier = new WeakMap;
+  let closed = false;
+  let resolveClosed;
+  const closedSignal = new Promise((resolve) => {
+    resolveClosed = resolve;
+  });
+  const sdkHandler = createSdkMcpHandler(({ authInfo }) => {
+    const resolved = authInfo ? authByCarrier.get(authInfo) : undefined;
+    if (!resolved) {
+      throw new Error("[stitchkit] MCP request reached the SDK without resolved auth");
+    }
+    const auth = resolved.value;
+    return buildPrepared ? buildPrepared(auth) : buildMcpServer2(config, auth);
+  }, {
+    legacy: config.legacy === "reject" ? "reject" : "stateless",
+    maxSubscriptions: 0
+  });
+  const unauthorized = () => {
+    const headers = config.protectedResource ? { "WWW-Authenticate": wwwAuthenticateHeader2(config.protectedResource.resource) } : undefined;
+    return jsonRpcError(-32001, "Authorization required", 401, headers);
+  };
+  const observeRejection = (request, response) => {
+    if (response.status < 400 || !config.onTransportRejected)
+      return response;
+    Promise.resolve(config.onTransportRejected({ request, response: response.clone() })).catch(() => {
+      return;
+    });
+    return response;
+  };
+  return {
+    fetch: async (request) => {
+      if (closed) {
+        return observeRejection(request, jsonRpcError(-32000, "MCP handler is closed", 503));
+      }
+      const allowedHosts = config.security?.allowedHosts ?? localhostAllowedHostnames();
+      const hostRejection = hostValidationResponse(request, allowedHosts);
+      if (hostRejection)
+        return observeRejection(request, hostRejection);
+      const allowedOrigins = config.security?.allowedOrigins ?? localhostAllowedOrigins();
+      const originRejection = originValidationResponse(request, [...allowedOrigins]);
+      if (originRejection)
+        return observeRejection(request, originRejection);
+      const auth = await Promise.race([
+        Promise.resolve(config.auth(request)),
+        closedSignal.then(() => null)
+      ]);
+      if (closed) {
+        return observeRejection(request, jsonRpcError(-32000, "MCP handler is closed", 503));
+      }
+      if (auth == null)
+        return observeRejection(request, unauthorized());
+      const authCarrier = {
+        token: "",
+        clientId: config.multiRound?.state.principal(auth) ?? "stitchkit",
+        scopes: []
+      };
+      authByCarrier.set(authCarrier, { value: auth });
+      try {
+        return observeRejection(request, await sdkHandler.fetch(request, { authInfo: authCarrier }));
+      } finally {
+        authByCarrier.delete(authCarrier);
+      }
+    },
+    close: async () => {
+      if (closed)
+        return;
+      closed = true;
+      resolveClosed?.();
+      await sdkHandler.close();
+    }
+  };
+}
+function createMcpHttpRoute2(config) {
+  return {
+    method: "ALL",
+    path: config.path,
+    handler: (request) => config.handler.fetch(request)
+  };
+}
+
+// src/tools/mcp/stdio.ts
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+async function createStdioMcpServer2(config) {
+  const auth = await config.auth;
+  return serveStdio(() => buildMcpServer2(config, auth), {
+    legacy: config.legacy ?? "serve",
+    maxSubscriptions: 0
+  });
+}
+
+// src/tools/mcp/stdio-signals.ts
+var bound = new WeakSet;
+function bindStdioProcessSignals2(handle, options = {}) {
+  if (bound.has(handle)) {
+    throw new Error("[stitchkit] bindStdioProcessSignals: this stdio handle is already bound; close the first binding before creating another");
+  }
+  bound.add(handle);
+  const signals = [...new Set(options.signals ?? DEFAULT_PROCESS_SIGNALS)];
+  const source = options.signalSource ?? defaultSignalSource;
+  const handlers = [];
+  let started = false;
+  let sameTurnAsStart = false;
+  let closed = false;
+  let resolveChain = () => {
+    return;
+  };
+  let rejectChain = () => {
+    return;
+  };
+  const promise = new Promise((resolve, reject) => {
+    resolveChain = resolve;
+    rejectChain = reject;
+  });
+  promise.catch(() => {
+    return;
+  });
+  const removeListeners = () => {
+    if (closed)
+      return;
+    closed = true;
+    for (const [signal, handler] of handlers)
+      source.off(signal, handler);
+    if (!started)
+      bound.delete(handle);
+  };
+  const close = () => {
+    const hadStarted = started;
+    removeListeners();
+    if (!hadStarted)
+      resolveChain();
+  };
+  const run = async (signal) => {
+    try {
+      await options.onClose?.(signal);
+    } catch (error) {
+      reportSignalError("prepare", error, options.onError);
+    }
+    try {
+      await handle.close();
+    } catch (error) {
+      rejectChain(error);
+      reportSignalError("close", error, options.onError);
+      removeListeners();
+      return;
+    }
+    resolveChain();
+    try {
+      await options.onComplete?.();
+    } catch (error) {
+      reportSignalError("complete", error, options.onError);
+    } finally {
+      removeListeners();
+    }
+  };
+  const onSignal = (signal) => {
+    if (!started) {
+      started = true;
+      sameTurnAsStart = true;
+      queueMicrotask(() => {
+        sameTurnAsStart = false;
+      });
+      run(signal).catch((error) => reportSignalError("close", error, options.onError));
+      return;
+    }
+    if (sameTurnAsStart)
+      return;
+    removeListeners();
+    guardSignalCallback(() => options.onRepeatedSignal?.(signal), "close", options.onError);
+    let restored = false;
+    try {
+      restored = source.raiseDefault(signal);
+    } catch (error) {
+      reportSignalError("close", error, options.onError);
+    }
+    if (!restored) {
+      guardSignalCallback(() => options.onEscalationBlocked?.(signal), "close", options.onError);
+    }
+  };
+  for (const signal of signals) {
+    const handler = () => onSignal(signal);
+    handlers.push([signal, handler]);
+    source.on(signal, handler);
+  }
+  return { promise, close };
+}
+
+export { PROTECTED_RESOURCE_PATH2, protectedResourceMetadataUrl2, wwwAuthenticateHeader2, oauthProtectedResourceRoute2, RESOURCE_MIME_TYPE2, EXT_APPS_BUNDLE_PLACEHOLDER2, inlineMcpAppBundle2, MCP_CATALOG_META_KEY2, mcpCatalogMeta2, readMcpCatalogStamp2, createMcpProgressReporter, validateMcpSchemas2, mountMcp2, buildMcpServer2, mountMcpResource2, createMcpHandler2, createMcpHttpRoute2, createStdioMcpServer2, bindStdioProcessSignals2 };