mppx 0.0.1 → 0.1.0

package/src/mcp-sdk/client/McpClient.test.ts

@@ -0,0 +1,219 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { McpError } from '@modelcontextprotocol/sdk/types.js'
+import { Challenge, Mcp as core_Mcp } from 'mppx'
+import { tempo as tempo_client } from 'mppx/client'
+import { Mppx as Mppx_server, tempo as tempo_server } from 'mppx/server'
+import { createClient } from 'viem'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+import { accounts, asset, chain, http, client as testClient } from '~test/tempo/viem.js'
+import * as McpServer_transport from '../server/Transport.js'
+import * as McpClient from './McpClient.js'
+
+const realm = 'api.example.com'
+const secretKey = 'test-secret-key'
+
+describe('McpClient.wrap', () => {
+  let client: Client
+  let server: McpServer
+  let clientTransport: InstanceType<typeof InMemoryTransport>
+  let serverTransport: InstanceType<typeof InMemoryTransport>
+
+  const mppxServer = Mppx_server.create({
+    methods: [
+      tempo_server.charge({
+        getClient: () => testClient,
+      }),
+    ],
+    realm,
+    secretKey,
+    transport: McpServer_transport.mcpSdk(),
+  })
+
+  beforeEach(async () => {
+    ;[clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+
+    client = new Client({ name: 'test-client', version: '1.0.0' })
+    server = new McpServer({ name: 'test-server', version: '1.0.0' })
+
+    server.registerTool(
+      'premium_tool',
+      { description: 'A tool that requires payment' },
+      async (extra) => {
+        const result = await mppxServer.charge({
+          amount: '1',
+          currency: asset,
+          expires: new Date(Date.now() + 60_000).toISOString(),
+          recipient: accounts[0].address,
+        })(extra)
+
+        if (result.status === 402) throw result.challenge
+
+        return result.withReceipt({
+          content: [{ type: 'text' as const, text: 'Premium tool executed' }],
+        })
+      },
+    )
+
+    server.registerTool('free_tool', { description: 'A free tool' }, async () => {
+      return { content: [{ type: 'text' as const, text: 'Free tool executed' }] }
+    })
+
+    await Promise.all([client.connect(clientTransport), server.connect(serverTransport)])
+  })
+
+  afterEach(async () => {
+    await Promise.all([client.close(), server.close()])
+  })
+
+  test('default: handles payment and returns result with receipt', async () => {
+    const mcp = McpClient.wrap(client, {
+      methods: [
+        tempo_client.charge({
+          account: accounts[1],
+          getClient: () => testClient,
+        }),
+      ],
+    })
+
+    const result = await mcp.callTool({ name: 'premium_tool', arguments: {} })
+
+    expect(result.content).toEqual([{ type: 'text', text: 'Premium tool executed' }])
+    expect(result.isError).toBeUndefined()
+    expect(result.receipt).toBeDefined()
+    expect(result.receipt?.status).toBe('success')
+    expect(result.receipt?.method).toBe('tempo')
+  })
+
+  test('default: account via context', async () => {
+    const mcp = McpClient.wrap(client, {
+      methods: [
+        tempo_client.charge({
+          getClient: () => testClient,
+        }),
+      ],
+    })
+
+    const result = await mcp.callTool(
+      { name: 'premium_tool', arguments: {} },
+      { context: { account: accounts[1] } },
+    )
+
+    expect(result.content).toEqual([{ type: 'text', text: 'Premium tool executed' }])
+    expect(result.receipt?.status).toBe('success')
+  })
+
+  test('behavior: passes through when no payment required', async () => {
+    const mcp = McpClient.wrap(client, {
+      methods: [
+        tempo_client.charge({
+          account: accounts[1],
+          getClient: () => testClient,
+        }),
+      ],
+    })
+
+    const result = await mcp.callTool({ name: 'free_tool', arguments: {} })
+
+    expect(result.content).toEqual([{ type: 'text', text: 'Free tool executed' }])
+    expect(result.receipt).toBeUndefined()
+  })
+
+  test('behavior: throws when no account provided', async () => {
+    const mcp = McpClient.wrap(client, {
+      methods: [
+        tempo_client.charge({
+          getClient: () => createClient({ chain, transport: http() }),
+        }),
+      ],
+    })
+
+    await expect(mcp.callTool({ name: 'premium_tool', arguments: {} })).rejects.toThrow(
+      'No `account` provided',
+    )
+  })
+
+  test('error: returns isError for non-payment errors', async () => {
+    server.registerTool('broken_tool', { description: 'Broken' }, async () => {
+      throw new Error('Internal server error')
+    })
+
+    const mcp = McpClient.wrap(client, {
+      methods: [
+        tempo_client.charge({
+          account: accounts[1],
+          getClient: () => testClient,
+        }),
+      ],
+    })
+
+    const result = await mcp.callTool({ name: 'broken_tool', arguments: {} })
+    expect(result.isError).toBe(true)
+    expect(result.content).toEqual([{ type: 'text', text: 'Internal server error' }])
+  })
+
+  test('error: throws when method not found', async () => {
+    const challenge = Challenge.fromIntent(tempo_server.charge({ getClient: () => testClient }), {
+      realm,
+      secretKey,
+      request: {
+        amount: '1',
+        currency: asset,
+        decimals: 6,
+        expires: new Date(Date.now() + 60_000).toISOString(),
+        recipient: accounts[0].address,
+      },
+    })
+
+    server.registerTool('tool_unknown_method', { description: 'Tool' }, async () => {
+      throw new McpError(core_Mcp.paymentRequiredCode, 'Payment Required', {
+        httpStatus: 402,
+        challenges: [{ ...challenge, method: 'unknown_method' }],
+      })
+    })
+
+    const mcp = McpClient.wrap(client, {
+      methods: [
+        tempo_client.charge({
+          account: accounts[1],
+          getClient: () => testClient,
+        }),
+      ],
+    })
+
+    await expect(mcp.callTool({ name: 'tool_unknown_method', arguments: {} })).rejects.toThrow(
+      'No compatible payment method. Server offers: unknown_method.charge. Client has: tempo.charge',
+    )
+  })
+})
+
+describe('isPaymentRequiredError', () => {
+  test('returns true for McpError with payment code and challenges', () => {
+    const error = new McpError(core_Mcp.paymentRequiredCode, 'Payment Required', {
+      httpStatus: 402,
+      challenges: [{ id: 'test', method: 'tempo', intent: 'charge', realm: 'test', request: {} }],
+    })
+    expect(McpClient.isPaymentRequiredError(error)).toBe(true)
+  })
+
+  test('returns false for McpError with wrong code', () => {
+    const error = new McpError(-32600, 'Invalid Request', {
+      challenges: [{ id: 'test', method: 'tempo' }],
+    })
+    expect(McpClient.isPaymentRequiredError(error)).toBe(false)
+  })
+
+  test('returns false for McpError without challenges', () => {
+    const error = new McpError(core_Mcp.paymentRequiredCode, 'Payment Required', {
+      httpStatus: 402,
+    })
+    expect(McpClient.isPaymentRequiredError(error)).toBe(false)
+  })
+
+  test('returns false for non-McpError', () => {
+    expect(McpClient.isPaymentRequiredError(null)).toBe(false)
+    expect(McpClient.isPaymentRequiredError(new Error('test'))).toBe(false)
+    expect(McpClient.isPaymentRequiredError('error')).toBe(false)
+  })
+})

package/src/mcp-sdk/client/McpClient.ts

@@ -0,0 +1,187 @@
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import type { McpError } from '@modelcontextprotocol/sdk/types.js'
+import type * as Challenge from '../../Challenge.js'
+import * as Credential from '../../Credential.js'
+import * as core_Mcp from '../../Mcp.js'
+import type * as MethodIntent from '../../MethodIntent.js'
+import type * as z from '../../zod.js'
+
+type AnyClient = MethodIntent.Client<any, any>
+
+/**
+ * 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
+}
+
+/**
+ * Creates a payment-aware wrapper around an MCP SDK client.
+ *
+ * Similar to `Fetch.from()` for HTTP, this wraps an MCP client's `callTool`
+ * method to automatically handle payment challenges.
+ *
+ * @example
+ * ```ts
+ * import { Client } from '@modelcontextprotocol/sdk/client'
+ * import { McpClient, tempo } from 'mppx/mcp-sdk/client'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * const client = new Client({ name: 'my-client', version: '1.0.0' })
+ * await client.connect(transport)
+ *
+ * const mcp = McpClient.wrap(client, {
+ *   methods: [
+ *     tempo({
+ *       account: privateKeyToAccount('0x...'),
+ *     }),
+ *   ],
+ * })
+ *
+ * // Automatically handles payment challenges
+ * const result = await mcp.callTool({ name: 'premium_tool', arguments: {} })
+ * console.log(result.content, result.receipt)
+ * ```
+ */
+export function wrap<
+  const client extends Pick<Client, 'callTool'>,
+  const methods extends readonly MethodIntent.AnyClient[],
+>(client: client, config: wrap.Config<methods>): wrap.McpClient<client, methods> {
+  const { methods } = config
+
+  return {
+    ...client,
+    async callTool(params, options) {
+      const context = options?.context
+      const timeout = options?.timeout
+
+      try {
+        const result = await client.callTool(
+          params,
+          undefined,
+          timeout !== undefined ? { timeout } : undefined,
+        )
+
+        return {
+          ...result,
+          receipt: result._meta?.[core_Mcp.receiptMetaKey] as core_Mcp.Receipt | undefined,
+        }
+      } catch (error) {
+        // Check if this is a payment required error
+        if (!isPaymentRequiredError(error)) throw error
+
+        const challenges = (error.data as { challenges?: Challenge.Challenge[] })?.challenges
+        if (!challenges?.length) throw error
+
+        // Select first challenge that matches an installed method intent
+        const challenge = challenges.find((c) =>
+          methods.some((m) => m.method === c.method && m.name === c.intent),
+        )
+        if (!challenge) {
+          const available = challenges.map((c) => `${c.method}.${c.intent}`).join(', ')
+          const installed = methods.map((m) => `${m.method}.${m.name}`).join(', ')
+          throw new Error(
+            `No compatible payment method. Server offers: ${available}. Client has: ${installed}`,
+          )
+        }
+
+        const credential = await createCredential(challenge, { context, methods })
+        const parsed = Credential.deserialize(credential)
+
+        const retryResult = await client.callTool(
+          {
+            ...params,
+            _meta: {
+              ...params._meta,
+              [core_Mcp.credentialMetaKey]: parsed,
+            },
+          },
+          undefined,
+          timeout !== undefined ? { timeout } : undefined,
+        )
+
+        return {
+          ...retryResult,
+          receipt: retryResult._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 MethodIntent.Client<any, infer context>
+    ? context extends z.ZodMiniType
+      ? z.input<context>
+      : undefined
+    : undefined
+}[number]
+
+export declare namespace wrap {
+  type Config<
+    methods extends readonly MethodIntent.AnyClient[] = readonly MethodIntent.AnyClient[],
+  > = {
+    /** Array of method intents to use. */
+    methods: methods
+  }
+
+  type McpClient<
+    client extends Pick<Client, 'callTool'> = Pick<Client, 'callTool'>,
+    methods extends readonly AnyClient[] = readonly AnyClient[],
+  > = Omit<client, 'callTool'> & {
+    /** Call a tool with automatic payment handling. */
+    callTool: (
+      params: {
+        name: string
+        arguments?: Record<string, unknown>
+        _meta?: Record<string, unknown>
+      },
+      options?: CallToolOptions<methods>,
+    ) => Promise<CallToolResult>
+  }
+
+  type CallToolOptions<methods extends readonly AnyClient[] = readonly AnyClient[]> = {
+    /** Context to pass to the method intent's createCredential. */
+    context?: AnyContextFor<methods>
+    /** Request timeout in milliseconds. */
+    timeout?: number
+  }
+}
+
+/**
+ * Checks if an error is a payment required error.
+ */
+export function isPaymentRequiredError(
+  error: unknown,
+): error is McpError & { data: { challenges: Challenge.Challenge[] } } {
+  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
+  const data = (error as { data?: { challenges?: unknown } }).data
+  return Array.isArray(data?.challenges) && data.challenges.length > 0
+}
+
+/** @internal */
+async function createCredential<methods extends readonly MethodIntent.AnyClient[]>(
+  challenge: Challenge.Challenge,
+  config: {
+    context?: unknown
+    methods: methods
+  },
+): Promise<string> {
+  const { context, methods } = config
+
+  const mi = methods.find((m) => m.method === challenge.method && m.name === challenge.intent)
+  if (!mi)
+    throw new Error(
+      `No method intent found for "${challenge.method}.${challenge.intent}". Available: ${methods.map((m) => `${m.method}.${m.name}`).join(', ')}`,
+    )
+
+  const parsedContext = mi.context && context !== undefined ? mi.context.parse(context) : undefined
+  return mi.createCredential(
+    parsedContext !== undefined ? { challenge, context: parsedContext } : ({ challenge } as never),
+  )
+}

package/src/mcp-sdk/client/index.ts

@@ -0,0 +1,2 @@
+export * as tempo from '../../tempo/client/index.js'
+export * as McpClient from './McpClient.js'

package/src/mcp-sdk/server/Transport.ts

@@ -0,0 +1,94 @@
+import type { CallToolResult, McpError } from '@modelcontextprotocol/sdk/types.js'
+import type * as Credential from '../../Credential.js'
+import * as core_Mcp from '../../Mcp.js'
+import * as Transport from '../../server/Transport.js'
+
+/**
+ * MCP SDK tool handler "extra" parameter.
+ * Compatible with `@modelcontextprotocol/sdk` RequestHandlerExtra.
+ */
+export type Extra = {
+  _meta?:
+    | {
+        [core_Mcp.credentialMetaKey]?: Credential.Credential
+        [key: string]: unknown
+      }
+    | undefined
+  [key: string]: unknown
+}
+
+export type McpSdk = Transport.Transport<Extra, McpError, CallToolResult>
+
+/**
+ * MCP SDK transport for server-side payment handling with `@modelcontextprotocol/sdk`.
+ *
+ * - Reads credentials from `_meta["org.paymentauth/credential"]`
+ * - Issues challenges as `McpError` with code `-32042` and challenge in `error.data`
+ * - Attaches receipts via `_meta["org.paymentauth/receipt"]` on tool results
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp'
+ * import { Mppx, Transport } from 'mppx/server'
+ *
+ * const payment = Mppx.create({
+ *   method: tempo(),
+ *   secretKey: process.env.SECRET_KEY,
+ *   transport: Transport.mcpSdk(),
+ * })
+ *
+ * server.registerTool('premium', { description: '...' }, async (extra) => {
+ *   const result = await payment.charge({ request: { ... } })(extra)
+ *   if (result.status === 402) throw result.challenge
+ *   return result.withReceipt({ content: [...] })
+ * })
+ * ```
+ */
+export function mcpSdk(): McpSdk {
+  let McpErrorClass: typeof McpError | undefined
+
+  return Transport.from<Extra, McpError, CallToolResult>({
+    name: 'mcp-sdk',
+
+    getCredential(extra) {
+      const credential = extra._meta?.[core_Mcp.credentialMetaKey]
+      if (!credential) return null
+      return credential
+    },
+
+    async respondChallenge({ challenge, error }) {
+      if (!McpErrorClass) {
+        try {
+          const mod = await import('@modelcontextprotocol/sdk/types.js')
+          McpErrorClass = mod.McpError
+        } catch (error) {
+          const err = new Error(
+            'Missing optional dependency "@modelcontextprotocol/sdk". Install it to use mppx MCP SDK transports.',
+          )
+          ;(err as Error & { cause?: unknown }).cause = error
+          throw err
+        }
+      }
+      return new McpErrorClass(core_Mcp.paymentRequiredCode, error?.message ?? 'Payment Required', {
+        httpStatus: 402,
+        challenges: [challenge],
+        ...(error && { problem: error.toProblemDetails(challenge.id) }),
+      })
+    },
+
+    respondReceipt({ receipt, response, challengeId }) {
+      const mcpReceipt: core_Mcp.Receipt = {
+        ...receipt,
+        challengeId,
+      }
+
+      return {
+        ...response,
+        _meta: {
+          ...response._meta,
+          [core_Mcp.receiptMetaKey]: mcpReceipt,
+        },
+      }
+    },
+  })
+}

package/src/mcp-sdk/server/index.ts

@@ -0,0 +1 @@
+export * as Transport from './Transport.js'

package/src/middlewares/elysia.ts

@@ -0,0 +1,66 @@
+import type { Context } from 'elysia'
+import * as Mppx_core from '../server/Mppx.js'
+import * as Mppx_internal from './internal/mppx.js'
+
+export * from '../server/Methods.js'
+
+type ElysiaHook = (context: Context) => Promise<Response | undefined>
+
+export namespace Mppx {
+  /**
+   * Creates an Elysia-aware payment handler where each intent
+   * returns an Elysia `beforeHandle` hook.
+   *
+   * Use with `.guard()` to scope payment to specific routes,
+   * or `.onBeforeHandle()` to apply globally.
+   *
+   * @example
+   * ```ts
+   * import { Elysia } from 'elysia'
+   * import { Mppx, tempo } from 'mppx/elysia'
+   *
+   * const mppx = Mppx.create({ methods: [tempo()] })
+   *
+   * const app = new Elysia()
+   *   .guard(
+   *     { beforeHandle: mppx.charge({ amount: '1' }) },
+   *     (app) => app.get('/premium', () => ({ data: 'paid content' })),
+   *   )
+   * ```
+   */
+  export function create<const methods extends Mppx_core.Methods>(
+    config: Mppx_core.create.Config<methods>,
+  ): Mppx_internal.Wrap<Mppx_core.Mppx<methods>, ElysiaHook> {
+    return Mppx_internal.wrap(Mppx_core.create(config), payment)
+  }
+}
+
+/**
+ * Elysia `beforeHandle` hook that gates a route behind a payment intent.
+ *
+ * Returns a 402 challenge if no valid credential is provided.
+ *
+ * @example
+ * ```ts
+ * import { Elysia } from 'elysia'
+ * import { Mppx } from 'mppx/server'
+ * import { payment } from 'mppx/elysia'
+ *
+ * const mppx = Mppx.create({ methods: [tempo()] })
+ *
+ * const app = new Elysia()
+ *   .guard(
+ *     { beforeHandle: payment(mppx.charge, { amount: '1' }) },
+ *     (app) => app.get('/premium', () => ({ data: 'paid content' })),
+ *   )
+ * ```
+ */
+export function payment<const intent extends Mppx_internal.AnyIntentFn>(
+  intent: intent,
+  options: intent extends (options: infer options) => any ? options : never,
+): ElysiaHook {
+  return async ({ request }) => {
+    const result = await intent(options)(request)
+    if (result.status === 402) return result.challenge
+  }
+}