@devlab.group/agent-commerce 2.1.0 → 2.2.1

package/dist/cli/mcp-HFD7ZNCQ.js

@@ -0,0 +1,559 @@
+import { readCappedBody, x402ErrorCode, settlementFailure, settlementResponseFromDetails, x402McpPaymentSubmission, X402_MCP_PAYMENT_META_KEY, X402_MCP_PAYMENT_RESPONSE_META_KEY, settlementResponse, X402_MCP_ERROR_META_KEY } from './chunk-SPAYKVUP.js';
+import { MCP_TOOL_NAME_PATTERN, MCP_MODERN_PROTOCOL_REVISION } from './chunk-TPC4EJLT.js';
+import { mcpPaymentRequired, MPP_MCP_CREDENTIAL_META_KEY, receiptObject, MPP_MCP_RECEIPT_META_KEY, MPP_MCP_PAYMENT_REQUIRED_META_KEY } from './chunk-5K4XEAZV.js';
+import { PACKAGE_VERSION } from './chunk-QY3K6PEQ.js';
+import { toLogInfo, toCommerceError, CommerceError, extractReservedInputFields, PAYMENT_INPUT_FIELD, AUTHORIZATION_INPUT_FIELD, toErrorEnvelope, DELIVERY_SUMMARY_META_KEY, toDeliverySummary, toPaymentRequiredEnvelope } from './chunk-QQ3WY5L3.js';
+import { isRecord } from './chunk-3M6U7ILB.js';
+import { createMcpHandler, Server, ProtocolError, ProtocolErrorCode, LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/server';
+
+var MCP_SUPPORTED_SPEC = `${MCP_MODERN_PROTOCOL_REVISION}, ${LATEST_PROTOCOL_VERSION}`;
+var MCP_CAPABILITIES = ["tools/list", "tools/call"];
+var MCP_UNSUPPORTED = [
+  "resources",
+  "prompts",
+  "sampling",
+  "completions",
+  "elicitation",
+  "roots",
+  "logging",
+  "notifications/tools/list_changed",
+  "tasks",
+  "dns-rebinding-protection",
+  "authorization",
+  "sessions",
+  "subscriptions",
+  "pagination",
+  "HTTP+SSE transport",
+  // mppx reads challenges and refusals from tool-result `_meta`.
+  "MPP payment-required as JSON-RPC error -32042",
+  "MPP verification failure as JSON-RPC error -32043"
+];
+function buildDescriptor(implementationVersion) {
+  return {
+    name: "mcp",
+    kind: "protocol",
+    implementationVersion,
+    supportedSpec: MCP_SUPPORTED_SPEC,
+    capabilities: MCP_CAPABILITIES,
+    status: "stable",
+    unsupported: MCP_UNSUPPORTED
+  };
+}
+
+// src/protocols/mcp/tool-mapping.ts
+function isValidToolName(id) {
+  return MCP_TOOL_NAME_PATTERN.test(id);
+}
+function isPaidResource(resource) {
+  return resource.pricing.type !== "free";
+}
+function primaryPaymentMethod(resource) {
+  return resource.paymentMethods[0];
+}
+function proofCarriers(method) {
+  const field = `the "${PAYMENT_INPUT_FIELD}" argument`;
+  if (method === "x402") return `_meta["${X402_MCP_PAYMENT_META_KEY}"] or ${field}`;
+  if (method === "mpp") return `_meta["${MPP_MCP_CREDENTIAL_META_KEY}"] or ${field}`;
+  return field;
+}
+function paymentProofNote(resource) {
+  const method = primaryPaymentMethod(resource);
+  const rail = method !== void 0 ? `an ${method}` : "a";
+  return `Requires ${rail} payment proof in ${proofCarriers(method)}, built from the payment-required response.`;
+}
+var OMIT_NOTE = "Omit it when the client sends the proof in _meta.";
+function paymentInputFieldDescription(resource) {
+  const method = primaryPaymentMethod(resource);
+  if (method === "x402") {
+    return `x402 payment proof (base64 PAYMENT-SIGNATURE value) for a previous payment-required response. ${OMIT_NOTE}`;
+  }
+  if (method === "mpp") {
+    return `MPP credential (the full "Authorization: Payment ..." value) for the challenge in a previous payment-required response. ${OMIT_NOTE}`;
+  }
+  if (method !== void 0) {
+    return `${method} payment proof (base64-encoded) returned from a previous payment-required response.`;
+  }
+  return "Payment proof returned from a previous payment-required response.";
+}
+function requiredAuthorization(resource) {
+  return resource.authorization?.required ?? [];
+}
+function authorizationNote(resource) {
+  const methods = requiredAuthorization(resource);
+  return methods.length > 0 ? ` Also requires ${methods.join(" and ")} authorization in the "${AUTHORIZATION_INPUT_FIELD}" input field.` : "";
+}
+function buildToolDescription(resource) {
+  const base = resource.description ?? resource.name;
+  switch (resource.pricing.type) {
+    case "free":
+      return base;
+    case "fixed": {
+      const { amount, currency } = resource.pricing;
+      return `${base} Costs ${amount} ${currency} per call. ${paymentProofNote(resource)}${authorizationNote(resource)}`;
+    }
+    case "dynamic":
+      return `${base} Requires payment (amount determined at request time). ${paymentProofNote(resource)}${authorizationNote(resource)}`;
+  }
+}
+function buildInputSchema(resource) {
+  const base = resource.inputSchema;
+  const baseIsObject = isRecord(base);
+  const basePropertyEntries = baseIsObject && isRecord(base.properties) ? Object.entries(base.properties).filter(
+    (entry) => isRecord(entry[1])
+  ) : [];
+  const properties = Object.fromEntries(basePropertyEntries);
+  if (isPaidResource(resource)) {
+    properties[PAYMENT_INPUT_FIELD] = {
+      type: "string",
+      description: paymentInputFieldDescription(resource)
+    };
+  }
+  const methods = requiredAuthorization(resource);
+  if (methods.length > 0) {
+    properties[AUTHORIZATION_INPUT_FIELD] = {
+      type: "object",
+      description: "Authorization this resource requires in addition to payment: the method and its serialized proof.",
+      properties: {
+        method: { type: "string", enum: [...methods] },
+        payload: { type: "string", minLength: 1 }
+      },
+      required: ["method", "payload"]
+    };
+  }
+  const required = baseIsObject && Array.isArray(base.required) ? base.required.filter((v) => typeof v === "string") : [];
+  const extra = baseIsObject ? Object.fromEntries(
+    Object.entries(base).filter(
+      ([key]) => key !== "type" && key !== "properties" && key !== "required"
+    )
+  ) : {};
+  return {
+    ...extra,
+    type: "object",
+    properties,
+    ...required.length > 0 ? { required } : {}
+  };
+}
+
+// src/protocols/mcp/result-mapping.ts
+function toRecord(value) {
+  return value;
+}
+function deliveredResult(outcome) {
+  const body = outcome.body;
+  const text = typeof body === "string" ? body : JSON.stringify(body ?? null);
+  const payment = outcome.payment;
+  const receipt = payment?.provider === "mpp" ? receiptObject(payment.metadata?.["receipt"]) : void 0;
+  return {
+    content: [{ type: "text", text }],
+    ...isRecord(body) ? { structuredContent: body } : {},
+    _meta: {
+      [DELIVERY_SUMMARY_META_KEY]: toRecord(toDeliverySummary(outcome)),
+      ...payment?.provider === "x402" ? { [X402_MCP_PAYMENT_RESPONSE_META_KEY]: settlementResponse(payment) } : {},
+      ...receipt !== void 0 ? { [MPP_MCP_RECEIPT_META_KEY]: receipt } : {}
+    }
+  };
+}
+function structuredError(structured, sentence, meta) {
+  return {
+    isError: true,
+    content: [
+      { type: "text", text: JSON.stringify(structured) },
+      { type: "text", text: sentence }
+    ],
+    structuredContent: structured,
+    ...meta !== void 0 ? { _meta: meta } : {}
+  };
+}
+function withX402Challenge(envelope, challenge) {
+  return { ...challenge, ...envelope };
+}
+function paymentRequiredResult(outcome) {
+  const envelope = toPaymentRequiredEnvelope(outcome);
+  const p = envelope.payment;
+  const x402Required = p.provider === "x402" ? p.envelope : void 0;
+  const structured = x402Required !== void 0 ? withX402Challenge(toRecord(envelope), x402Required) : toRecord(envelope);
+  const mppRequired = p.provider === "mpp" ? mcpPaymentRequired(p.envelope) : void 0;
+  let meta;
+  if (x402Required !== void 0) meta = { [X402_MCP_ERROR_META_KEY]: x402Required };
+  else if (mppRequired !== void 0) meta = { [MPP_MCP_PAYMENT_REQUIRED_META_KEY]: mppRequired };
+  return structuredError(
+    structured,
+    // A challenge with several offers names no single destination
+    `Payment required: ${p.amount} ${p.currency}${p.destination !== void 0 ? ` to ${p.destination}` : ""} for resource "${outcome.resourceId}". Retry with an ${p.provider} payment proof in ${proofCarriers(p.provider)}.`,
+    meta
+  );
+}
+function errorResult(error, rail) {
+  const envelope = toErrorEnvelope(error);
+  const details = error.details;
+  const challenge = details?.["challenge"];
+  const refused = error.httpStatus === 402 && isRecord(challenge);
+  const x402Required = rail === "x402" && refused ? {
+    ...challenge,
+    error: x402ErrorCode(error.code, details?.["reason"], details?.["network"])
+  } : void 0;
+  const structured = x402Required !== void 0 ? withX402Challenge(toRecord(envelope), x402Required) : toRecord(envelope);
+  let meta;
+  if (rail === "x402") {
+    const settlement = error.code === "PAYMENT_SETTLEMENT_FAILED" ? settlementFailure(details) : settlementResponseFromDetails(details);
+    if (settlement !== void 0 || x402Required !== void 0) {
+      meta = {
+        ...x402Required !== void 0 ? { [X402_MCP_ERROR_META_KEY]: x402Required } : {},
+        ...settlement !== void 0 ? { [X402_MCP_PAYMENT_RESPONSE_META_KEY]: settlement } : {}
+      };
+    }
+  } else if (rail === "mpp" && refused) {
+    const required = mcpPaymentRequired(challenge, {
+      code: error.code,
+      reason: details?.["reason"],
+      detail: error.message
+    });
+    if (required !== void 0) meta = { [MPP_MCP_PAYMENT_REQUIRED_META_KEY]: required };
+  }
+  return structuredError(structured, `${envelope.code}: ${envelope.message}`, meta);
+}
+function mapOutcome(outcome) {
+  return outcome.kind === "delivered" ? deliveredResult(outcome) : paymentRequiredResult(outcome);
+}
+
+// src/protocols/mcp/adapter.ts
+var DEFAULT_MOUNT_PATH = "/mcp";
+var DEFAULT_SERVER_NAME = "agent-commerce";
+var MAX_CONCURRENT_TOOL_CALLS = 8;
+var MAX_REQUEST_BODY_BYTES = 256 * 1024;
+var MAX_QUEUED_TOOL_CALLS = 64;
+var MCP_BATCH_PROTOCOL_REVISION = "2025-03-26";
+var TOOLS_LIST_CACHE_HINT = { ttlMs: 6e4, cacheScope: "public" };
+var McpProtocolAdapter = class {
+  name = "mcp";
+  mountPath;
+  descriptor;
+  serverName;
+  serverVersion;
+  context;
+  started = false;
+  tools = [];
+  toolsByResourceId = /* @__PURE__ */ new Map();
+  skipped = [];
+  handler;
+  // Counting semaphore on `pipeline.execute()`. It lives on the adapter, not
+  // the request, so the cap holds across concurrent `/mcp` requests as well
+  // as within one batch.
+  inFlightToolCalls = 0;
+  toolCallWaiters = [];
+  constructor(options = {}) {
+    this.mountPath = options.mountPath ?? DEFAULT_MOUNT_PATH;
+    this.serverName = options.serverName ?? DEFAULT_SERVER_NAME;
+    this.serverVersion = options.serverVersion ?? PACKAGE_VERSION;
+    this.descriptor = buildDescriptor(PACKAGE_VERSION);
+  }
+  async start(context) {
+    this.context = context;
+    this.started = false;
+    let resources = [];
+    try {
+      resources = context.resources.listExposedVia("mcp");
+    } catch (err) {
+      context.logger.error(
+        { err: toLogInfo(err) },
+        "mcp adapter: failed to list mcp-exposed resources"
+      );
+      resources = [];
+    }
+    const tools = [];
+    const toolsByResourceId = /* @__PURE__ */ new Map();
+    const skipped = [];
+    for (const resource of resources) {
+      try {
+        if (!isValidToolName(resource.id)) {
+          skipped.push({
+            id: resource.id,
+            reason: `resource id is not a legal MCP tool name (must match ${MCP_TOOL_NAME_PATTERN.source})`
+          });
+          continue;
+        }
+        if (toolsByResourceId.has(resource.id)) {
+          skipped.push({ id: resource.id, reason: "duplicate tool name" });
+          continue;
+        }
+        const tool = {
+          name: resource.id,
+          description: buildToolDescription(resource),
+          inputSchema: buildInputSchema(resource)
+        };
+        tools.push({ resource, tool });
+        toolsByResourceId.set(resource.id, resource);
+      } catch (err) {
+        skipped.push({
+          id: resource.id,
+          reason: `failed to build MCP tool: ${toCommerceError(err).message}`
+        });
+      }
+    }
+    for (const s of skipped) {
+      context.logger.warn({ resourceId: s.id, reason: s.reason }, "mcp adapter: resource skipped");
+    }
+    this.tools = tools;
+    this.toolsByResourceId = toolsByResourceId;
+    this.skipped = skipped;
+    this.handler = createMcpHandler(
+      (ctx) => this.buildServer(ctx.requestInfo?.signal ?? new AbortController().signal),
+      {
+        legacy: "stateless",
+        // Reporting only: a request the SDK rejects is already answered
+        onerror: (err) => context.logger.debug({ err: toLogInfo(err) }, "mcp adapter: SDK error")
+      }
+    );
+    this.started = true;
+    context.logger.info(
+      {
+        mountPath: this.mountPath,
+        toolCount: tools.length,
+        skippedCount: skipped.length
+      },
+      "mcp adapter started"
+    );
+  }
+  async handleHttp(req, res) {
+    try {
+      if (!this.started || !this.context || !this.handler) {
+        this.writeJsonRpcError(res, 503, "MCP adapter is not running.");
+        return;
+      }
+      if (req.method !== "POST") {
+        this.writeJsonRpcError(res, 405, "Method not allowed. This endpoint only accepts POST.");
+        return;
+      }
+      const abortController = new AbortController();
+      res.once("close", () => abortController.abort());
+      const read = await readCappedBody(req, MAX_REQUEST_BODY_BYTES);
+      if (read.kind === "too-large") {
+        this.writeJsonRpcError(
+          res,
+          413,
+          `Request body exceeds the ${MAX_REQUEST_BODY_BYTES}-byte limit.`
+        );
+        return;
+      }
+      if (read.kind !== "ok") {
+        this.writeJsonRpcError(res, 400, "Could not read the request body.");
+        return;
+      }
+      const body = parseJson(read.text);
+      const version = req.headers["mcp-protocol-version"];
+      if (Array.isArray(body) && version !== void 0 && version !== MCP_BATCH_PROTOCOL_REVISION) {
+        this.writeJsonRpcError(
+          res,
+          400,
+          `Invalid Request: JSON-RPC batches are supported only in MCP ${MCP_BATCH_PROTOCOL_REVISION}.`
+        );
+        return;
+      }
+      const malformed = isModernRequest(req) ? void 0 : malformedToolCall(body);
+      if (malformed !== void 0) {
+        this.writeJsonRpcError(res, 200, malformed.message, -32602, malformed.id);
+        return;
+      }
+      const response = await this.handler.fetch(
+        toWebRequest(req, read.text, abortController.signal)
+      );
+      await writeWebResponse(response, res);
+    } catch (err) {
+      this.context?.logger.error({ err: toLogInfo(err) }, "mcp adapter: request handling failed");
+      this.writeJsonRpcError(res, 500, "Internal server error.");
+    }
+  }
+  async health() {
+    const checkedAt = this.context?.clock.nowIso() ?? (/* @__PURE__ */ new Date()).toISOString();
+    if (!this.started || !this.context) {
+      return { status: "fail", detail: "MCP adapter has not been started.", checkedAt };
+    }
+    const toolCount = this.tools.length;
+    if (this.skipped.length > 0) {
+      const detail = `${toolCount} tool(s) registered; ${this.skipped.length} resource(s) skipped: ${this.skipped.map((s) => `${s.id} (${s.reason})`).join("; ")}`;
+      return { status: "warn", detail, checkedAt };
+    }
+    return { status: "pass", detail: `${toolCount} tool(s) registered.`, checkedAt };
+  }
+  async stop() {
+    this.started = false;
+    const handler = this.handler;
+    this.handler = void 0;
+    try {
+      await handler?.close();
+    } catch {
+    }
+    this.context = void 0;
+  }
+  // Use general JSON-RPC codes for transport errors
+  writeJsonRpcError(res, status, message, code = status >= 500 ? -32603 : -32600, id = null) {
+    if (res.headersSent) return;
+    res.writeHead(status, {
+      "content-type": "application/json",
+      // RFC 9110 requires Allow on a 405, and this endpoint takes only POST
+      ...status === 405 ? { allow: "POST" } : {}
+    });
+    res.end(JSON.stringify({ jsonrpc: "2.0", error: { code, message }, id }));
+  }
+  buildServer(signal) {
+    const server = new Server(
+      { name: this.serverName, version: this.serverVersion },
+      { capabilities: { tools: {} }, cacheHints: { "tools/list": TOOLS_LIST_CACHE_HINT } }
+    );
+    server.setRequestHandler("tools/list", async (request) => {
+      if (request.params?.cursor !== void 0) {
+        throw new ProtocolError(ProtocolErrorCode.InvalidParams, "Invalid cursor.");
+      }
+      return { tools: this.tools.map((t) => t.tool) };
+    });
+    server.setRequestHandler(
+      "tools/call",
+      async (request) => this.handleToolCall(
+        request.params.name,
+        request.params.arguments ?? {},
+        request.params._meta,
+        signal
+      )
+    );
+    return server;
+  }
+  async handleToolCall(resourceId, rawArgs, meta, signal) {
+    const context = this.context;
+    if (!context) {
+      return errorResult(new CommerceError("INTERNAL_ERROR", "MCP adapter is not running."));
+    }
+    const resource = this.toolsByResourceId.get(resourceId);
+    if (!resource) {
+      throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool "${resourceId}".`);
+    }
+    try {
+      const requestId = context.ids.next("mcp");
+      const fields = extractReservedInputFields(rawArgs, resource, requestId);
+      const { input, authorization } = fields;
+      const payment = paymentFromMeta(meta, resource) ?? fields.payment;
+      const request = {
+        requestId,
+        resourceId,
+        input,
+        protocol: "mcp",
+        receivedAt: context.clock.nowIso(),
+        ...payment !== void 0 ? { payment } : {},
+        ...authorization !== void 0 ? { authorization } : {}
+      };
+      await this.acquireToolCallSlot(signal);
+      try {
+        if (signal.aborted) {
+          return errorResult(
+            new CommerceError(
+              "PROTOCOL_UNSUPPORTED",
+              "Client disconnected before this call started."
+            )
+          );
+        }
+        const outcome = await context.pipeline.execute(request);
+        return mapOutcome(outcome);
+      } finally {
+        this.releaseToolCallSlot();
+      }
+    } catch (err) {
+      const error = toCommerceError(err);
+      context.logger.warn({ resourceId, err: toLogInfo(error) }, "mcp adapter: execution failed");
+      return errorResult(error, resource.paymentMethods[0]);
+    }
+  }
+  /**
+   * Takes a permit, or queues for one when MAX_CONCURRENT_TOOL_CALLS are in
+   * flight. Throws when the queue is full or the caller disconnected while
+   * queued; a throw never leaks a permit.
+   */
+  async acquireToolCallSlot(signal) {
+    if (this.inFlightToolCalls < MAX_CONCURRENT_TOOL_CALLS) {
+      this.inFlightToolCalls++;
+      return;
+    }
+    if (this.toolCallWaiters.length >= MAX_QUEUED_TOOL_CALLS) {
+      throw new CommerceError(
+        "GATEWAY_BUSY",
+        "Too many tool calls already queued on this adapter; retry later."
+      );
+    }
+    await new Promise((resolve) => this.toolCallWaiters.push(resolve));
+    if (signal.aborted) {
+      this.releaseToolCallSlot();
+      throw new CommerceError("PROTOCOL_UNSUPPORTED", "Client disconnected while queued.");
+    }
+  }
+  releaseToolCallSlot() {
+    const next = this.toolCallWaiters.shift();
+    if (next !== void 0) next();
+    else this.inFlightToolCalls--;
+  }
+};
+function toWebRequest(req, body, signal) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+  }
+  return new Request(new URL(req.url ?? "/", "http://localhost"), {
+    method: req.method ?? "POST",
+    headers,
+    body,
+    signal
+  });
+}
+function isModernRequest(req) {
+  if (req.headers["mcp-method"] !== void 0) return true;
+  const version = req.headers["mcp-protocol-version"];
+  return typeof version === "string" && version >= MCP_MODERN_PROTOCOL_REVISION;
+}
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return void 0;
+  }
+}
+function malformedToolCall(message) {
+  if (!isRecord(message) || message["method"] !== "tools/call") return void 0;
+  const id = message["id"];
+  if (typeof id !== "string" && typeof id !== "number") return void 0;
+  const params = message["params"];
+  let problem;
+  if (!isRecord(params)) problem = "params must be an object";
+  else if (typeof params["name"] !== "string") problem = '"name" must be a string';
+  else if (params["arguments"] !== void 0 && !isRecord(params["arguments"])) {
+    problem = '"arguments" must be an object';
+  } else if (params["_meta"] !== void 0 && !isRecord(params["_meta"])) {
+    problem = '"_meta" must be an object';
+  }
+  return problem === void 0 ? void 0 : { id, message: `Invalid tools/call params: ${problem}.` };
+}
+async function writeWebResponse(response, res) {
+  res.writeHead(response.status, Object.fromEntries(response.headers));
+  if (response.body !== null) {
+    for await (const chunk of response.body) {
+      if (res.destroyed) break;
+      res.write(chunk);
+    }
+  }
+  res.end();
+}
+function paymentFromMeta(meta, resource) {
+  const method = resource.paymentMethods[0];
+  if (method === "x402") {
+    const payload = x402McpPaymentSubmission(meta?.[X402_MCP_PAYMENT_META_KEY]);
+    if (payload !== void 0) return { method, payload };
+  }
+  const credential = meta?.[MPP_MCP_CREDENTIAL_META_KEY];
+  if (method === "mpp" && isRecord(credential)) {
+    return { method, payload: JSON.stringify(credential) };
+  }
+  return void 0;
+}
+function createMcpAdapter(options) {
+  return new McpProtocolAdapter(options);
+}
+
+export { createMcpAdapter };
+//# sourceMappingURL=mcp-HFD7ZNCQ.js.map
+//# sourceMappingURL=mcp-HFD7ZNCQ.js.map