@x402/mcp 2.3.0-alpha

package/dist/esm/index.mjs

@@ -0,0 +1,782 @@
+// src/client/x402MCPClient.ts
+import { isPaymentRequired } from "@x402/core/schemas";
+import { x402Client } from "@x402/core/client";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+
+// src/utils/encoding.ts
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isPaymentPayloadStructure(value) {
+  if (!isObject(value)) {
+    return false;
+  }
+  return "x402Version" in value && "payload" in value;
+}
+function isSettleResponseStructure(value) {
+  if (!isObject(value)) {
+    return false;
+  }
+  return "success" in value;
+}
+function isPaymentRequiredStructure(value) {
+  if (!isObject(value)) {
+    return false;
+  }
+  return "x402Version" in value && "accepts" in value && Array.isArray(value.accepts);
+}
+function extractPaymentFromMeta(params) {
+  if (!(params == null ? void 0 : params._meta)) {
+    return null;
+  }
+  const payment = params._meta[MCP_PAYMENT_META_KEY];
+  if (!isPaymentPayloadStructure(payment)) {
+    return null;
+  }
+  return payment;
+}
+function attachPaymentToMeta(params, paymentPayload) {
+  return {
+    ...params,
+    _meta: {
+      [MCP_PAYMENT_META_KEY]: paymentPayload
+    }
+  };
+}
+function extractPaymentResponseFromMeta(result) {
+  if (!(result == null ? void 0 : result._meta)) {
+    return null;
+  }
+  const response = result._meta[MCP_PAYMENT_RESPONSE_META_KEY];
+  if (!isSettleResponseStructure(response)) {
+    return null;
+  }
+  return response;
+}
+function attachPaymentResponseToMeta(result, settleResponse) {
+  return {
+    ...result,
+    _meta: {
+      [MCP_PAYMENT_RESPONSE_META_KEY]: settleResponse
+    }
+  };
+}
+function createPaymentRequiredError(paymentRequired, message) {
+  return {
+    code: MCP_PAYMENT_REQUIRED_CODE,
+    message: message || "Payment required",
+    data: paymentRequired
+  };
+}
+function extractPaymentRequiredFromError(error) {
+  if (!isObject(error)) {
+    return null;
+  }
+  if (error.code !== MCP_PAYMENT_REQUIRED_CODE) {
+    return null;
+  }
+  const data = error.data;
+  if (!isPaymentRequiredStructure(data)) {
+    return null;
+  }
+  return data;
+}
+function createToolResourceUrl(toolName, customUrl) {
+  if (customUrl) {
+    return customUrl;
+  }
+  return `mcp://tool/${toolName}`;
+}
+
+// src/types/mcp.ts
+var MCP_PAYMENT_REQUIRED_CODE = 402;
+var MCP_PAYMENT_META_KEY = "x402/payment";
+var MCP_PAYMENT_RESPONSE_META_KEY = "x402/payment-response";
+function isPaymentRequiredError(error) {
+  if (!isObject(error)) {
+    return false;
+  }
+  if (error.code !== MCP_PAYMENT_REQUIRED_CODE || typeof error.message !== "string") {
+    return false;
+  }
+  if (!isObject(error.data)) {
+    return false;
+  }
+  return "x402Version" in error.data && "accepts" in error.data;
+}
+
+// src/client/x402MCPClient.ts
+function isMCPTextContent(content) {
+  return content.type === "text" && typeof content.text === "string";
+}
+function isMCPCallToolResult(result) {
+  if (typeof result !== "object" || result === null) {
+    return false;
+  }
+  const obj = result;
+  return Array.isArray(obj.content);
+}
+var x402MCPClient = class {
+  /**
+   * Creates a new x402MCPClient instance.
+   *
+   * @param mcpClient - The underlying MCP client instance
+   * @param paymentClient - The x402 client for creating payment payloads
+   * @param options - Configuration options
+   */
+  constructor(mcpClient, paymentClient, options = {}) {
+    this.paymentRequiredHooks = [];
+    this.beforePaymentHooks = [];
+    this.afterPaymentHooks = [];
+    this.mcpClient = mcpClient;
+    this._paymentClient = paymentClient;
+    this.options = {
+      autoPayment: options.autoPayment ?? true,
+      onPaymentRequested: options.onPaymentRequested ?? (() => true)
+    };
+  }
+  /**
+   * Get the underlying MCP client instance.
+   *
+   * @returns The MCP client instance
+   */
+  get client() {
+    return this.mcpClient;
+  }
+  /**
+   * Get the underlying x402 payment client instance.
+   *
+   * @returns The x402 client instance
+   */
+  get paymentClient() {
+    return this._paymentClient;
+  }
+  /**
+   * Connect to an MCP server transport.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param transport - The transport to connect to
+   * @returns Promise that resolves when connected
+   */
+  async connect(transport) {
+    await this.mcpClient.connect(transport);
+  }
+  /**
+   * Close the MCP connection.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Promise that resolves when closed
+   */
+  async close() {
+    await this.mcpClient.close();
+  }
+  /**
+   * List available tools from the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Promise resolving to the list of tools
+   */
+  async listTools() {
+    return this.mcpClient.listTools();
+  }
+  /**
+   * List available resources from the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Promise resolving to the list of resources
+   */
+  async listResources() {
+    return this.mcpClient.listResources();
+  }
+  /**
+   * List available prompts from the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Promise resolving to the list of prompts
+   */
+  async listPrompts() {
+    return this.mcpClient.listPrompts();
+  }
+  /**
+   * Get a specific prompt from the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for getPrompt method
+   * @returns Promise resolving to the prompt
+   */
+  async getPrompt(...args) {
+    return this.mcpClient.getPrompt(...args);
+  }
+  /**
+   * Read a resource from the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for readResource method
+   * @returns Promise resolving to the resource content
+   */
+  async readResource(...args) {
+    return this.mcpClient.readResource(...args);
+  }
+  /**
+   * List resource templates from the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for listResourceTemplates method
+   * @returns Promise resolving to the list of resource templates
+   */
+  async listResourceTemplates(...args) {
+    return this.mcpClient.listResourceTemplates(...args);
+  }
+  /**
+   * Subscribe to resource updates.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for subscribeResource method
+   * @returns Promise resolving when subscribed
+   */
+  async subscribeResource(...args) {
+    return this.mcpClient.subscribeResource(...args);
+  }
+  /**
+   * Unsubscribe from resource updates.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for unsubscribeResource method
+   * @returns Promise resolving when unsubscribed
+   */
+  async unsubscribeResource(...args) {
+    return this.mcpClient.unsubscribeResource(...args);
+  }
+  /**
+   * Ping the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for ping method
+   * @returns Promise resolving to ping response
+   */
+  async ping(...args) {
+    return this.mcpClient.ping(...args);
+  }
+  /**
+   * Request completion suggestions.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for complete method
+   * @returns Promise resolving to completion suggestions
+   */
+  async complete(...args) {
+    return this.mcpClient.complete(...args);
+  }
+  /**
+   * Set the logging level on the server.
+   * Passthrough to the underlying MCP client.
+   *
+   * @param args - Arguments for setLoggingLevel method
+   * @returns Promise resolving when level is set
+   */
+  async setLoggingLevel(...args) {
+    return this.mcpClient.setLoggingLevel(...args);
+  }
+  /**
+   * Get server capabilities after initialization.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Server capabilities or undefined if not initialized
+   */
+  getServerCapabilities() {
+    return this.mcpClient.getServerCapabilities();
+  }
+  /**
+   * Get server version information after initialization.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Server version info or undefined if not initialized
+   */
+  getServerVersion() {
+    return this.mcpClient.getServerVersion();
+  }
+  /**
+   * Get server instructions after initialization.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Server instructions or undefined if not initialized
+   */
+  getInstructions() {
+    return this.mcpClient.getInstructions();
+  }
+  /**
+   * Send notification that roots list has changed.
+   * Passthrough to the underlying MCP client.
+   *
+   * @returns Promise resolving when notification is sent
+   */
+  async sendRootsListChanged() {
+    return this.mcpClient.sendRootsListChanged();
+  }
+  /**
+   * Register a hook to run when a 402 payment required is received.
+   * Hooks run in order; first to return a result wins.
+   *
+   * This can be used to:
+   * - Provide pre-existing payment payloads (implementation-specific, not part of x402 spec)
+   * - Abort the payment flow for certain tools
+   * - Log or track payment required events
+   *
+   * Note: Payment caching is an implementation pattern and not defined in the x402 MCP
+   * transport specification. Implementations that cache payments should ensure cached
+   * payloads are still valid (not expired, correct nonce, etc.).
+   *
+   * @param hook - Hook function
+   * @returns This instance for chaining
+   *
+   * @example
+   * ```typescript
+   * // Example: Custom payment handling (implementation-specific)
+   * client.onPaymentRequired(async ({ toolName, paymentRequired }) => {
+   *   // Custom logic to provide a payment or abort
+   *   if (shouldAbort(toolName)) {
+   *     return { abort: true };
+   *   }
+   *   // Return undefined to proceed with normal payment flow
+   * });
+   * ```
+   */
+  onPaymentRequired(hook) {
+    this.paymentRequiredHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to run before payment is created.
+   *
+   * @param hook - Hook function
+   * @returns This instance for chaining
+   */
+  onBeforePayment(hook) {
+    this.beforePaymentHooks.push(hook);
+    return this;
+  }
+  /**
+   * Register a hook to run after payment is submitted.
+   *
+   * @param hook - Hook function
+   * @returns This instance for chaining
+   */
+  onAfterPayment(hook) {
+    this.afterPaymentHooks.push(hook);
+    return this;
+  }
+  /**
+   * Calls a tool, automatically handling 402 payment required errors.
+   *
+   * If the tool returns a 402 error and autoPayment is enabled, this method
+   * will automatically create a payment payload and retry the tool call.
+   *
+   * @param name - The name of the tool to call
+   * @param args - Arguments to pass to the tool
+   * @param options - Optional MCP request options (timeout, signal, etc.)
+   * @param options.timeout - Request timeout in milliseconds (default: 60000)
+   * @param options.signal - AbortSignal for cancellation
+   * @param options.resetTimeoutOnProgress - If true, progress notifications reset the timeout
+   * @returns The tool result with payment metadata
+   * @throws Error if payment is required but autoPayment is disabled and no payment provided
+   * @throws Error if payment approval is denied
+   * @throws Error if payment creation fails
+   */
+  async callTool(name, args = {}, options) {
+    const result = await this.mcpClient.callTool({ name, arguments: args }, void 0, options);
+    if (!isMCPCallToolResult(result)) {
+      throw new Error("Invalid MCP tool result: missing content array");
+    }
+    const paymentRequired = this.extractPaymentRequiredFromResult(result);
+    if (!paymentRequired) {
+      return {
+        content: result.content,
+        isError: result.isError,
+        paymentMade: false
+      };
+    }
+    const paymentRequiredContext = {
+      toolName: name,
+      arguments: args,
+      paymentRequired
+    };
+    for (const hook of this.paymentRequiredHooks) {
+      const hookResult = await hook(paymentRequiredContext);
+      if (hookResult) {
+        if (hookResult.abort) {
+          throw new Error("Payment aborted by hook");
+        }
+        if (hookResult.payment) {
+          return this.callToolWithPayment(name, args, hookResult.payment, options);
+        }
+      }
+    }
+    if (!this.options.autoPayment) {
+      const err = new Error("Payment required");
+      err.code = MCP_PAYMENT_REQUIRED_CODE;
+      err.paymentRequired = paymentRequired;
+      throw err;
+    }
+    const paymentRequestedContext = {
+      toolName: name,
+      arguments: args,
+      paymentRequired
+    };
+    const approved = await this.options.onPaymentRequested(paymentRequestedContext);
+    if (!approved) {
+      throw new Error("Payment request denied");
+    }
+    for (const hook of this.beforePaymentHooks) {
+      await hook(paymentRequestedContext);
+    }
+    const paymentPayload = await this._paymentClient.createPaymentPayload(paymentRequired);
+    return this.callToolWithPayment(name, args, paymentPayload, options);
+  }
+  /**
+   * Calls a tool with an explicit payment payload.
+   *
+   * Use this method when you want to provide payment upfront or when
+   * implementing custom payment handling.
+   *
+   * @param name - The name of the tool to call
+   * @param args - Arguments to pass to the tool
+   * @param paymentPayload - The payment payload to include
+   * @param options - Optional MCP request options (timeout, signal, etc.)
+   * @param options.timeout - Request timeout in milliseconds (default: 60000)
+   * @param options.signal - AbortSignal for cancellation
+   * @param options.resetTimeoutOnProgress - If true, progress notifications reset the timeout
+   * @returns The tool result with payment metadata
+   */
+  async callToolWithPayment(name, args, paymentPayload, options) {
+    const callParams = {
+      name,
+      arguments: args,
+      _meta: {
+        [MCP_PAYMENT_META_KEY]: paymentPayload
+      }
+    };
+    const result = await this.mcpClient.callTool(callParams, void 0, options);
+    if (!isMCPCallToolResult(result)) {
+      throw new Error("Invalid MCP tool result: missing content array");
+    }
+    const resultWithMeta = {
+      content: result.content,
+      isError: result.isError,
+      _meta: result._meta
+    };
+    const paymentResponse = extractPaymentResponseFromMeta(resultWithMeta);
+    for (const hook of this.afterPaymentHooks) {
+      await hook({
+        toolName: name,
+        paymentPayload,
+        result: resultWithMeta,
+        settleResponse: paymentResponse
+      });
+    }
+    return {
+      content: result.content,
+      isError: result.isError,
+      paymentResponse: paymentResponse ?? void 0,
+      paymentMade: true
+    };
+  }
+  /**
+   * Probes a tool to discover its payment requirements.
+   *
+   * **WARNING: Side Effects** - This method actually calls the tool to trigger a 402 response.
+   * If the tool is free (no payment required), it will execute and return null.
+   * Use with caution on tools that have side effects or are expensive to run.
+   *
+   * Useful for displaying pricing information to users before calling paid tools.
+   *
+   * @param name - The name of the tool to probe
+   * @param args - Arguments that may affect pricing (for dynamic pricing scenarios)
+   * @returns The payment requirements if the tool requires payment, null if the tool is free
+   *
+   * @example
+   * ```typescript
+   * // Check if a tool requires payment before calling
+   * const requirements = await client.getToolPaymentRequirements("expensive_analysis");
+   *
+   * if (requirements) {
+   *   const price = requirements.accepts[0];
+   *   console.log(`This tool costs ${price.amount} on ${price.network}`);
+   *   // Optionally show user and get confirmation before calling
+   * } else {
+   *   console.log("This tool is free");
+   *   // Note: the tool has already executed!
+   * }
+   * ```
+   */
+  async getToolPaymentRequirements(name, args = {}) {
+    const result = await this.mcpClient.callTool({ name, arguments: args });
+    if (!isMCPCallToolResult(result)) {
+      return null;
+    }
+    return this.extractPaymentRequiredFromResult(result);
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  /**
+   * Extracts PaymentRequired from a tool result (structured 402 response).
+   *
+   * Per MCP transport spec, supports:
+   * 1. structuredContent with direct PaymentRequired object (optional, preferred)
+   * 2. content[0].text with JSON-encoded PaymentRequired object (required)
+   *
+   * @param result - The tool call result
+   * @returns PaymentRequired if this is a 402 response, null otherwise
+   */
+  extractPaymentRequiredFromResult(result) {
+    if (!result.isError) {
+      return null;
+    }
+    if (result.structuredContent) {
+      const extracted = this.extractPaymentRequiredFromObject(result.structuredContent);
+      if (extracted) {
+        return extracted;
+      }
+    }
+    const content = result.content;
+    if (content.length === 0) {
+      return null;
+    }
+    const firstItem = content[0];
+    if (!isMCPTextContent(firstItem)) {
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(firstItem.text);
+      if (typeof parsed === "object" && parsed !== null) {
+        const extracted = this.extractPaymentRequiredFromObject(
+          parsed
+        );
+        if (extracted) {
+          return extracted;
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
+  /**
+   * Extracts PaymentRequired from an object.
+   * Expects direct PaymentRequired format (per MCP transport spec).
+   *
+   * @param obj - The object to extract from
+   * @returns PaymentRequired if found, null otherwise
+   */
+  extractPaymentRequiredFromObject(obj) {
+    if (isPaymentRequired(obj)) {
+      return obj;
+    }
+    return null;
+  }
+};
+function wrapMCPClientWithPayment(mcpClient, paymentClient, options) {
+  return new x402MCPClient(mcpClient, paymentClient, options);
+}
+function wrapMCPClientWithPaymentFromConfig(mcpClient, config, options) {
+  const paymentClient = x402Client.fromConfig(config);
+  return new x402MCPClient(mcpClient, paymentClient, options);
+}
+function createx402MCPClient(config) {
+  const mcpClient = new Client(
+    {
+      name: config.name,
+      version: config.version
+    },
+    config.mcpClientOptions
+  );
+  const paymentClient = new x402Client();
+  for (const scheme of config.schemes) {
+    if (scheme.x402Version === 1) {
+      paymentClient.registerV1(scheme.network, scheme.client);
+    } else {
+      paymentClient.register(scheme.network, scheme.client);
+    }
+  }
+  return new x402MCPClient(mcpClient, paymentClient, {
+    autoPayment: config.autoPayment,
+    onPaymentRequested: config.onPaymentRequested
+  });
+}
+
+// src/server/paymentWrapper.ts
+function createPaymentWrapper(resourceServer, config) {
+  if (!config.accepts || config.accepts.length === 0) {
+    throw new Error("PaymentWrapperConfig.accepts must have at least one payment requirement");
+  }
+  return (handler) => {
+    return async (args, extra) => {
+      var _a, _b, _c, _d, _e;
+      const _meta = extra == null ? void 0 : extra._meta;
+      const toolName = ((_b = (_a = config.resource) == null ? void 0 : _a.url) == null ? void 0 : _b.replace("mcp://tool/", "")) || "paid_tool";
+      const context = {
+        toolName,
+        arguments: args,
+        meta: _meta
+      };
+      const paymentPayload = extractPaymentFromMeta({
+        name: toolName,
+        arguments: args,
+        _meta
+      });
+      const paymentRequirements = config.accepts[0];
+      if (!paymentPayload) {
+        return createPaymentRequiredResult(
+          resourceServer,
+          toolName,
+          config,
+          "Payment required to access this tool"
+        );
+      }
+      const verifyResult = await resourceServer.verifyPayment(paymentPayload, paymentRequirements);
+      if (!verifyResult.isValid) {
+        return createPaymentRequiredResult(
+          resourceServer,
+          toolName,
+          config,
+          verifyResult.invalidReason || "Payment verification failed"
+        );
+      }
+      const hookContext = {
+        toolName,
+        arguments: args,
+        paymentRequirements,
+        paymentPayload
+      };
+      if ((_c = config.hooks) == null ? void 0 : _c.onBeforeExecution) {
+        const hookResult = await config.hooks.onBeforeExecution(hookContext);
+        if (hookResult === false) {
+          return createPaymentRequiredResult(
+            resourceServer,
+            toolName,
+            config,
+            "Execution blocked by hook"
+          );
+        }
+      }
+      const result = await handler(args, context);
+      const afterExecContext = {
+        ...hookContext,
+        result
+      };
+      if ((_d = config.hooks) == null ? void 0 : _d.onAfterExecution) {
+        await config.hooks.onAfterExecution(afterExecContext);
+      }
+      if (result.isError) {
+        return result;
+      }
+      try {
+        const settleResult = await resourceServer.settlePayment(
+          paymentPayload,
+          paymentRequirements
+        );
+        if ((_e = config.hooks) == null ? void 0 : _e.onAfterSettlement) {
+          const settlementContext = {
+            ...hookContext,
+            settlement: settleResult
+          };
+          await config.hooks.onAfterSettlement(settlementContext);
+        }
+        return {
+          content: result.content,
+          isError: result.isError,
+          _meta: {
+            [MCP_PAYMENT_RESPONSE_META_KEY]: settleResult
+          }
+        };
+      } catch (settleError) {
+        return createSettlementFailedResult(
+          resourceServer,
+          toolName,
+          config,
+          settleError instanceof Error ? settleError.message : "Settlement failed"
+        );
+      }
+    };
+  };
+}
+async function createPaymentRequiredResult(resourceServer, toolName, config, errorMessage) {
+  var _a, _b, _c;
+  const resourceInfo = {
+    url: createToolResourceUrl(toolName, (_a = config.resource) == null ? void 0 : _a.url),
+    description: ((_b = config.resource) == null ? void 0 : _b.description) || `Tool: ${toolName}`,
+    mimeType: ((_c = config.resource) == null ? void 0 : _c.mimeType) || "application/json"
+  };
+  const paymentRequired = await resourceServer.createPaymentRequiredResponse(
+    config.accepts,
+    resourceInfo,
+    errorMessage
+  );
+  return {
+    structuredContent: paymentRequired,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(paymentRequired)
+      }
+    ],
+    isError: true
+  };
+}
+async function createSettlementFailedResult(resourceServer, toolName, config, errorMessage) {
+  var _a, _b, _c;
+  const resourceInfo = {
+    url: createToolResourceUrl(toolName, (_a = config.resource) == null ? void 0 : _a.url),
+    description: ((_b = config.resource) == null ? void 0 : _b.description) || `Tool: ${toolName}`,
+    mimeType: ((_c = config.resource) == null ? void 0 : _c.mimeType) || "application/json"
+  };
+  const paymentRequired = await resourceServer.createPaymentRequiredResponse(
+    config.accepts,
+    resourceInfo,
+    `Payment settlement failed: ${errorMessage}`
+  );
+  const settlementFailure = {
+    success: false,
+    errorReason: errorMessage,
+    transaction: "",
+    network: config.accepts[0].network
+  };
+  const errorData = {
+    ...paymentRequired,
+    [MCP_PAYMENT_RESPONSE_META_KEY]: settlementFailure
+  };
+  return {
+    structuredContent: errorData,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(errorData)
+      }
+    ],
+    isError: true
+  };
+}
+
+// src/index.ts
+import { x402Client as x402Client2 } from "@x402/core/client";
+import { x402ResourceServer } from "@x402/core/server";
+export {
+  MCP_PAYMENT_META_KEY,
+  MCP_PAYMENT_REQUIRED_CODE,
+  MCP_PAYMENT_RESPONSE_META_KEY,
+  attachPaymentResponseToMeta,
+  attachPaymentToMeta,
+  createPaymentRequiredError,
+  createPaymentWrapper,
+  createToolResourceUrl,
+  createx402MCPClient,
+  extractPaymentFromMeta,
+  extractPaymentRequiredFromError,
+  extractPaymentResponseFromMeta,
+  isPaymentRequiredError,
+  wrapMCPClientWithPayment,
+  wrapMCPClientWithPaymentFromConfig,
+  x402Client2 as x402Client,
+  x402MCPClient,
+  x402ResourceServer
+};
+//# sourceMappingURL=index.mjs.map