mppx 0.6.31 → 0.8.0

package/src/mcp/client/McpClient.ts

@@ -0,0 +1,307 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import type { McpError } from '@modelcontextprotocol/sdk/types.js'
+
+import * as Challenge from '../../Challenge.js'
+import * as Credential from '../../Credential.js'
+import * as Expires from '../../Expires.js'
+import * as AcceptPayment from '../../internal/AcceptPayment.js'
+import * as core_Mcp from '../../Mcp.js'
+import type * as Method from '../../Method.js'
+import * as z from '../../zod.js'
+
+type AnyClient = Method.Client<any, any>
+type Methods = readonly (Method.AnyClient | readonly Method.AnyClient[])[]
+type DefaultMethods = readonly [Method.AnyClient | readonly Method.AnyClient[]]
+type CallToolParams = Parameters<Client['callTool']>[0]
+type CallToolResultSchema = Parameters<Client['callTool']>[1]
+type CallToolRequestOptions = Parameters<Client['callTool']>[2]
+type PaymentRequiredData = NonNullable<core_Mcp.ErrorObject['data']>
+
+const MPPX_MCP_CLIENT_WRAPPER = Symbol.for('mppx.mcp.client.wrapper')
+
+export type OnPaymentRequired = (challenge: Challenge.Challenge) => boolean | Promise<boolean>
+
+/**
+ * Result of a tool call with payment handling.
+ * Extends the SDK's callTool return type with an optional payment receipt.
+ */
+export type CallToolResult = Awaited<ReturnType<Client['callTool']>> & {
+  /** Payment receipt if payment was made. */
+  receipt: core_Mcp.Receipt | undefined
+}
+
+/**
+ * Adds automatic payment handling to an MCP SDK client.
+ *
+ * The client's `callTool` method is replaced in place and the same reference
+ * is returned, so surfaces that keep using the original client become
+ * payment-aware — including when another SDK owns the client reference (e.g.
+ * Cloudflare Agents). The MCP SDK `callTool(params, resultSchema?, options?)`
+ * signature is preserved; pass a method's `context` or a per-call
+ * `onPaymentRequired` approval hook via the options argument, where they are
+ * stripped before the remaining request options are forwarded to the SDK.
+ * Payment challenges are handled whether they arrive as payment-required
+ * errors or as tool results carrying payment-required metadata. Calling
+ * `wrap()` again replaces the payment configuration.
+ *
+ * @example
+ * ```ts
+ * import { Client } from '@modelcontextprotocol/sdk/client'
+ * import { tempo } from 'mppx/client'
+ * import { McpClient } from 'mppx/mcp/client'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * const client = new Client({ name: 'my-client', version: '1.0.0' })
+ * await client.connect(transport)
+ *
+ * McpClient.wrap(client, {
+ *   methods: [
+ *     tempo({
+ *       account: privateKeyToAccount('0x...'),
+ *     }),
+ *   ],
+ * })
+ *
+ * // Automatically handles payment challenges
+ * const result = await client.callTool({ name: 'premium_tool', arguments: {} })
+ * console.log(result.content, result.receipt)
+ * ```
+ */
+export function wrap<const client extends Pick<Client, 'callTool'>, const methods extends Methods>(
+  client: client,
+  config: wrap.Config<methods>,
+): wrap.McpClient<client, methods> {
+  const target = client as client & { [MPPX_MCP_CLIENT_WRAPPER]?: Client['callTool'] }
+  const originalCallTool = target[MPPX_MCP_CLIENT_WRAPPER] ?? target.callTool
+  const callTool = createPaymentAwareCallTool(originalCallTool.bind(client), config)
+
+  Object.defineProperty(target, MPPX_MCP_CLIENT_WRAPPER, {
+    configurable: true,
+    value: originalCallTool,
+  })
+
+  Object.defineProperty(target, 'callTool', {
+    configurable: true,
+    enumerable: false,
+    value: (
+      params: CallToolParams,
+      resultSchema?: CallToolResultSchema,
+      options?: wrap.CallToolOptions<methods>,
+    ) => {
+      const { context, onPaymentRequired, ...requestOptions } =
+        options ?? ({} as wrap.CallToolOptions<methods>)
+      return callTool(params, {
+        context,
+        onPaymentRequired:
+          onPaymentRequired === null ? undefined : (onPaymentRequired ?? config.onPaymentRequired),
+        requestOptions: Object.keys(requestOptions).length
+          ? (requestOptions as CallToolRequestOptions)
+          : undefined,
+        resultSchema,
+      })
+    },
+    writable: true,
+  })
+
+  return target as unknown as wrap.McpClient<client, methods>
+}
+
+export declare namespace wrap {
+  type Config<methods extends Methods = Methods> = {
+    /** Optional approval hook called before creating a payment credential. */
+    onPaymentRequired?: OnPaymentRequired
+    /** Filters and sorts supported Challenges before Credential creation. */
+    orderChallenges?: AcceptPayment.OrderChallenges<FlattenMethods<methods>> | undefined
+    /** Client-declared supported payment methods, keyed by typed `method/intent` strings. */
+    paymentPreferences?: AcceptPayment.Config<FlattenMethods<methods>> | undefined
+    /** Array of methods to use. Accepts individual clients or tuples (e.g. from `tempo()`). */
+    methods: methods
+  }
+
+  type McpClient<
+    client extends Pick<Client, 'callTool'> = Pick<Client, 'callTool'>,
+    methods extends Methods = DefaultMethods,
+  > = Omit<client, 'callTool'> & {
+    /** Call a tool with automatic payment handling. Preserves the MCP SDK signature. */
+    callTool: (
+      params: CallToolParams,
+      resultSchema?: CallToolResultSchema,
+      options?: CallToolOptions<methods>,
+    ) => Promise<CallToolResult>
+  }
+
+  type CallToolOptions<methods extends Methods = DefaultMethods> = CallToolRequestOptions & {
+    /** Context to pass to the method intent's createCredential. */
+    context?: AnyContextForMethods<methods>
+    /** Per-call approval hook; overrides the configured hook. Pass `null` to bypass it. */
+    onPaymentRequired?: OnPaymentRequired | null
+  }
+}
+
+/** Minimal wire shape of payment-required data; challenges are validated, extra fields pass through. */
+const PaymentRequiredSchema = z.object({
+  challenges: z.array(Challenge.Schema).check(z.minLength(1)),
+})
+
+/**
+ * Checks if an error is a payment required error.
+ */
+export function isPaymentRequiredError(
+  error: unknown,
+): error is McpError & { data: PaymentRequiredData } {
+  if (typeof error !== 'object' || error === null) return false
+  if (!('code' in error) || !('message' in error)) return false
+  if ((error as { code: unknown }).code !== core_Mcp.paymentRequiredCode) return false
+  return isPaymentRequiredData((error as { data?: unknown }).data)
+}
+
+/** @internal */
+async function createCredential<methods extends readonly Method.AnyClient[]>(
+  challenge: Challenge.Challenge,
+  config: {
+    context?: unknown
+    methods: methods
+  },
+): Promise<string> {
+  const { context, methods } = config
+
+  const mi = methods.find((m) => m.name === challenge.method && m.intent === challenge.intent)
+  if (!mi)
+    throw new Error(
+      `No method found for "${challenge.method}.${challenge.intent}". Available: ${methods.map((m) => `${m.name}.${m.intent}`).join(', ')}`,
+    )
+
+  if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
+
+  const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined
+  return mi.createCredential(
+    parsedContext !== undefined ? { challenge, context: parsedContext } : ({ challenge } as never),
+  )
+}
+
+/** Normalized per-call inputs for the payment-aware adapter. @internal */
+type CallToolCall = {
+  context?: unknown
+  onPaymentRequired?: OnPaymentRequired | undefined
+  requestOptions?: CallToolRequestOptions | undefined
+  resultSchema?: CallToolResultSchema | undefined
+}
+
+function createPaymentAwareCallTool<methods extends Methods>(
+  callTool: Client['callTool'],
+  config: wrap.Config<methods>,
+): (params: CallToolParams, call: CallToolCall) => Promise<CallToolResult> {
+  const methods = config.methods.flat() as unknown as FlattenMethods<methods>
+  const paymentPreferences = AcceptPayment.resolve(methods, config.paymentPreferences)
+
+  const retryWithPayment = async (
+    params: CallToolParams,
+    call: CallToolCall,
+    paymentRequired: PaymentRequiredData,
+    cause: unknown,
+  ) => {
+    const challenges = paymentRequired.challenges
+    const candidates = AcceptPayment.selectChallengeCandidates(
+      challenges,
+      methods,
+      paymentPreferences.entries,
+    )
+    const orderedCandidates = config.orderChallenges
+      ? await config.orderChallenges(candidates)
+      : candidates
+    const selected = orderedCandidates[0]
+
+    if (!selected) {
+      const available = challenges.map((challenge) => `${challenge.method}.${challenge.intent}`)
+      const installed = methods.map((method) => `${method.name}.${method.intent}`)
+      throw new Error(
+        `No compatible payment method. Server offers: ${available.join(', ')}. Client has: ${installed.join(', ')}`,
+        { cause },
+      )
+    }
+
+    if (selected.challenge.expires)
+      Expires.assert(selected.challenge.expires, selected.challenge.id)
+
+    if (call.onPaymentRequired) {
+      const approved = await call.onPaymentRequired(selected.challenge)
+      if (!approved) throw new Error('Payment declined.', { cause })
+    }
+
+    const credential = await createCredential(selected.challenge, {
+      context: call.context,
+      methods,
+    })
+    const parsed = Credential.deserialize(credential)
+
+    const retryResult = await callTool(
+      {
+        ...params,
+        _meta: {
+          ...params._meta,
+          [core_Mcp.credentialMetaKey]: parsed,
+        },
+      },
+      call.resultSchema,
+      call.requestOptions,
+    )
+
+    return withReceipt(retryResult)
+  }
+
+  return async (params, call) => {
+    try {
+      const result = await callTool(params, call.resultSchema, call.requestOptions)
+      const paymentRequired = getPaymentRequiredMeta(result)
+      if (paymentRequired) return retryWithPayment(params, call, paymentRequired, result)
+      return withReceipt(result)
+    } catch (error) {
+      if (!isPaymentRequiredError(error)) throw error
+      return retryWithPayment(params, call, error.data, error)
+    }
+  }
+}
+
+function getPaymentRequiredMeta(
+  result: Awaited<ReturnType<Client['callTool']>>,
+): PaymentRequiredData | undefined {
+  const data = result._meta?.[core_Mcp.paymentRequiredMetaKey]
+  return isPaymentRequiredData(data) ? data : undefined
+}
+
+function isPaymentRequiredData(value: unknown): value is PaymentRequiredData {
+  return PaymentRequiredSchema.safeParse(value).success
+}
+
+function withReceipt(result: Awaited<ReturnType<Client['callTool']>>): CallToolResult {
+  return {
+    ...result,
+    receipt: result._meta?.[core_Mcp.receiptMetaKey] as core_Mcp.Receipt | undefined,
+  }
+}
+
+/** Union of all context types from all methods that have context schemas. */
+type AnyContextFor<methods extends readonly AnyClient[]> = {
+  [key in keyof methods]: methods[key] extends Method.Client<any, infer context>
+    ? context extends z.ZodMiniType
+      ? z.input<context>
+      : undefined
+    : undefined
+}[number]
+
+/** Union of all context types across a methods config, flattening tuples. @internal */
+type AnyContextForMethods<methods extends Methods> =
+  FlattenMethods<methods> extends infer flattened extends readonly AnyClient[]
+    ? AnyContextFor<flattened>
+    : never
+
+type FlattenMethods<methods extends Methods> = methods extends readonly [
+  infer head,
+  ...infer tail extends Methods,
+]
+  ? head extends readonly Method.AnyClient[]
+    ? readonly [...head, ...FlattenMethods<tail>]
+    : head extends Method.AnyClient
+      ? readonly [head, ...FlattenMethods<tail>]
+      : never
+  : readonly []

package/src/mcp/client/McpClient.unit.test.ts

@@ -0,0 +1,135 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { McpError } from '@modelcontextprotocol/sdk/types.js'
+import { Challenge, Credential, Mcp as core_Mcp, Method } from 'mppx'
+import { Methods } from 'mppx/tempo'
+import { describe, expect, test, vi } from 'vp/test'
+
+import * as McpClient from './McpClient.js'
+
+describe('MCP client payment approval', () => {
+  test('calls an approval hook before creating a credential', async () => {
+    const challenge = Challenge.from({
+      id: 'approval-test',
+      intent: 'charge',
+      method: 'tempo',
+      realm: 'api.example.com',
+      request: {},
+    })
+    const calls: unknown[] = []
+    const client = {
+      async callTool(params: unknown) {
+        calls.push(params)
+        if (calls.length === 1)
+          throw new McpError(core_Mcp.paymentRequiredCode, 'Payment Required', {
+            challenges: [challenge],
+            httpStatus: 402,
+          })
+        return {
+          _meta: {
+            [core_Mcp.receiptMetaKey]: {
+              method: 'tempo',
+              reference: 'test',
+              status: 'success',
+              timestamp: new Date().toISOString(),
+            },
+          },
+          content: [{ type: 'text', text: 'ok' }],
+        }
+      },
+    }
+    const createCredential = vi.fn(async ({ challenge }: { challenge: Challenge.Challenge }) =>
+      Credential.serialize({
+        challenge,
+        payload: { signature: '0xsignature', type: 'transaction' },
+      }),
+    )
+    const onPaymentRequired = vi.fn(() => true)
+    const mcp = McpClient.wrap(client as unknown as Pick<Client, 'callTool'>, {
+      methods: [Method.toClient(Methods.charge, { createCredential })],
+    })
+
+    const result = await mcp.callTool({ name: 'paid_tool', arguments: {} }, undefined, {
+      onPaymentRequired,
+    })
+
+    expect(result.content).toEqual([{ type: 'text', text: 'ok' }])
+    expect(onPaymentRequired).toHaveBeenCalledWith(challenge)
+    expect(createCredential).toHaveBeenCalledOnce()
+    expect(calls).toHaveLength(2)
+  })
+
+  test('does not create a credential when approval is denied', async () => {
+    const challenge = Challenge.from({
+      id: 'denied-test',
+      intent: 'charge',
+      method: 'tempo',
+      realm: 'api.example.com',
+      request: {},
+    })
+    const client = {
+      async callTool() {
+        throw new McpError(core_Mcp.paymentRequiredCode, 'Payment Required', {
+          challenges: [challenge],
+          httpStatus: 402,
+        })
+      },
+    }
+    const createCredential = vi.fn(async ({ challenge }: { challenge: Challenge.Challenge }) =>
+      Credential.serialize({
+        challenge,
+        payload: { signature: '0xsignature', type: 'transaction' },
+      }),
+    )
+    const mcp = McpClient.wrap(client as unknown as Pick<Client, 'callTool'>, {
+      methods: [Method.toClient(Methods.charge, { createCredential })],
+    })
+
+    await expect(
+      mcp.callTool({ name: 'paid_tool' }, undefined, { onPaymentRequired: () => false }),
+    ).rejects.toThrow('Payment declined.')
+    expect(createCredential).not.toHaveBeenCalled()
+  })
+
+  test('allows null to bypass a config approval hook', async () => {
+    const challenge = Challenge.from({
+      id: 'null-bypass-test',
+      intent: 'charge',
+      method: 'tempo',
+      realm: 'api.example.com',
+      request: {},
+    })
+    let calls = 0
+    const client = {
+      async callTool() {
+        calls += 1
+        if (calls === 1)
+          throw new McpError(core_Mcp.paymentRequiredCode, 'Payment Required', {
+            challenges: [challenge],
+            httpStatus: 402,
+          })
+        return {
+          content: [{ type: 'text', text: 'ok' }],
+        }
+      },
+    }
+    const createCredential = vi.fn(async ({ challenge }: { challenge: Challenge.Challenge }) =>
+      Credential.serialize({
+        challenge,
+        payload: { signature: '0xsignature', type: 'transaction' },
+      }),
+    )
+    const onPaymentRequired = vi.fn(() => false)
+    const mcp = McpClient.wrap(client as unknown as Pick<Client, 'callTool'>, {
+      methods: [Method.toClient(Methods.charge, { createCredential })],
+      onPaymentRequired,
+    })
+
+    await expect(
+      mcp.callTool({ name: 'paid_tool' }, undefined, { onPaymentRequired: null }),
+    ).resolves.toMatchObject({
+      content: [{ type: 'text', text: 'ok' }],
+    })
+    expect(onPaymentRequired).not.toHaveBeenCalled()
+    expect(createCredential).toHaveBeenCalledOnce()
+  })
+})

package/src/middlewares/elysia.test.ts

@@ -2,14 +2,18 @@ import * as http from 'node:http'
 
 import { Elysia } from 'elysia'
 import { Receipt } from 'mppx'
-import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
+import {
+  Mppx as Mppx_client,
+  sessionLegacy as sessionIntent,
+  tempo as tempo_client,
+} from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/elysia'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as TestHttp from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/session.js'
+import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: Elysia<any, any, any, any, any, any, any>) {
@@ -33,7 +37,7 @@ function createServer(app: Elysia<any, any, any, any, any, any, any>) {
   })
 }
 
-const secretKey = 'test-secret-key'
+const secretKey = 'test-secret-key-test-secret-key-32'
 
 describe('payment', () => {
   test('short-circuits management responses', async () => {
@@ -202,7 +206,7 @@ describe('session', () => {
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.session({
+        tempo_server.sessionLegacy({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
@@ -218,7 +222,7 @@ describe('session', () => {
       methods: [
         sessionIntent({
           account: accounts[2],
-          deposit: '10',
+          maxDeposit: '10',
           getClient: () => client,
         }),
       ],

package/src/middlewares/express.test.ts

@@ -1,13 +1,17 @@
 import express from 'express'
 import { Receipt } from 'mppx'
-import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
+import {
+  Mppx as Mppx_client,
+  sessionLegacy as sessionIntent,
+  tempo as tempo_client,
+} from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/express'
 import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as Http from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/session.js'
+import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: express.Express) {
@@ -19,7 +23,7 @@ function createServer(app: express.Express) {
   })
 }
 
-const secretKey = 'test-secret-key'
+const secretKey = 'test-secret-key-test-secret-key-32'
 
 function createChargeHarness(feePayer: boolean) {
   const mppx = Mppx.create({
@@ -196,7 +200,7 @@ describe('session', () => {
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.session({
+        tempo_server.sessionLegacy({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
@@ -212,7 +216,7 @@ describe('session', () => {
       methods: [
         sessionIntent({
           account: accounts[2],
-          deposit: '10',
+          maxDeposit: '10',
           getClient: () => client,
         }),
       ],

package/src/middlewares/hono.test.ts

@@ -4,7 +4,7 @@ import { Challenge, Credential, Method, Receipt, z } from 'mppx'
 import {
   evm as evm_client,
   Mppx as Mppx_client,
-  session as sessionIntent,
+  sessionLegacy as sessionIntent,
   tempo as tempo_client,
 } from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/hono'
@@ -19,7 +19,7 @@ import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as Http from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/session.js'
+import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(app: Hono) {
@@ -35,7 +35,7 @@ function createServer(app: Hono) {
   })
 }
 
-const secretKey = 'test-secret-key'
+const secretKey = 'test-secret-key-test-secret-key-32'
 
 describe('payment', () => {
   test('short-circuits management responses', async () => {
@@ -391,7 +391,7 @@ describe('session', () => {
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.session({
+        tempo_server.sessionLegacy({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
@@ -407,7 +407,7 @@ describe('session', () => {
       methods: [
         sessionIntent({
           account: accounts[2],
-          deposit: '10',
+          maxDeposit: '10',
           getClient: () => client,
         }),
       ],

package/src/middlewares/internal/mppx.test.ts

@@ -5,7 +5,7 @@ import { describe, expect, test } from 'vp/test'
 import { wrap } from './mppx.js'
 
 const realm = 'api.example.com'
-const secretKey = 'test-secret-key'
+const secretKey = 'test-secret-key-test-secret-key-32'
 
 const mockChargeA = Method.from({
   name: 'alpha',

package/src/middlewares/nextjs.test.ts

@@ -1,14 +1,18 @@
 import * as http from 'node:http'
 
 import { Challenge, Credential, Receipt } from 'mppx'
-import { Mppx as Mppx_client, session as sessionIntent, tempo as tempo_client } from 'mppx/client'
+import {
+  Mppx as Mppx_client,
+  sessionLegacy as sessionIntent,
+  tempo as tempo_client,
+} from 'mppx/client'
 import { Mppx, discovery, payment } from 'mppx/nextjs'
 import { tempo as tempo_server } from 'mppx/server'
 import type { Address } from 'viem'
 import { Addresses } from 'viem/tempo'
 import { beforeAll, describe, expect, test } from 'vp/test'
 import * as TestHttp from '~test/Http.js'
-import { deployEscrow } from '~test/tempo/session.js'
+import { deployEscrow } from '~test/tempo/legacy/session.js'
 import { accounts, asset, chain, client, fundAccount } from '~test/tempo/viem.js'
 
 function createServer(handler: (request: Request) => Promise<Response> | Response) {
@@ -32,7 +36,7 @@ function createServer(handler: (request: Request) => Promise<Response> | Respons
   })
 }
 
-const secretKey = 'test-secret-key'
+const secretKey = 'test-secret-key-test-secret-key-32'
 
 describe('payment', () => {
   test('short-circuits management responses', async () => {
@@ -279,7 +283,7 @@ describe('session', () => {
   function createSessionHarness(feePayer: boolean) {
     const mppx = Mppx.create({
       methods: [
-        tempo_server.session({
+        tempo_server.sessionLegacy({
           getClient: () => client,
           account: accounts[0],
           currency: asset,
@@ -295,7 +299,7 @@ describe('session', () => {
       methods: [
         sessionIntent({
           account: accounts[2],
-          deposit: '10',
+          maxDeposit: '10',
           getClient: () => client,
         }),
       ],