@civic/x402-mcp 0.0.1

package/src/proxy/client.test.ts

@@ -0,0 +1,199 @@
+import { createHttpPassthroughProxy, createStdioPassthroughProxy } from '@civic/passthrough-mcp-server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { Wallet } from 'x402/types';
+import { makePaymentAwareClientTransport } from '../client.js';
+import { createClientProxy } from './client.js';
+
+// Mock dependencies
+vi.mock('@civic/passthrough-mcp-server', () => ({
+  createHttpPassthroughProxy: vi.fn(),
+  createStdioPassthroughProxy: vi.fn(),
+}));
+
+vi.mock('../client.js', () => ({
+  makePaymentAwareClientTransport: vi.fn(),
+}));
+
+describe('createClientProxy', () => {
+  let mockWallet: Wallet;
+  let mockHttpProxy: any;
+  let mockStdioProxy: any;
+  let mockTransport: any;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+
+    mockWallet = {
+      account: { address: '0xabc' },
+      chain: { id: 1 },
+    } as unknown as Wallet;
+
+    mockHttpProxy = {
+      start: vi.fn().mockResolvedValue(undefined),
+      stop: vi.fn().mockResolvedValue(undefined),
+    };
+
+    mockStdioProxy = {
+      start: vi.fn().mockResolvedValue(undefined),
+      stop: vi.fn().mockResolvedValue(undefined),
+    };
+
+    mockTransport = {
+      send: vi.fn(),
+      receive: vi.fn(),
+    };
+
+    vi.mocked(makePaymentAwareClientTransport).mockReturnValue(mockTransport);
+    vi.mocked(createHttpPassthroughProxy).mockResolvedValue(mockHttpProxy);
+    vi.mocked(createStdioPassthroughProxy).mockResolvedValue(mockStdioProxy);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('HTTP mode', () => {
+    it('should create an HTTP proxy with default port', async () => {
+      const targetUrl = 'http://example.com/mcp';
+
+      const proxy = await createClientProxy({
+        targetUrl,
+        wallet: mockWallet,
+        mode: 'http',
+      });
+
+      expect(makePaymentAwareClientTransport).toHaveBeenCalledWith(targetUrl, mockWallet);
+
+      expect(vi.mocked(createHttpPassthroughProxy)).toHaveBeenCalledWith({
+        port: 4000,
+        target: {
+          transportType: 'custom',
+          transportFactory: expect.any(Function),
+        },
+      });
+
+      expect(proxy).toBe(mockHttpProxy);
+    });
+
+    it('should create an HTTP proxy with custom port', async () => {
+      const targetUrl = 'http://example.com/mcp';
+      const customPort = 5555;
+
+      const proxy = await createClientProxy({
+        targetUrl,
+        wallet: mockWallet,
+        mode: 'http',
+        port: customPort,
+      });
+
+      expect(vi.mocked(createHttpPassthroughProxy)).toHaveBeenCalledWith({
+        port: customPort,
+        target: {
+          transportType: 'custom',
+          transportFactory: expect.any(Function),
+        },
+      });
+
+      expect(proxy).toBe(mockHttpProxy);
+    });
+
+    it('should use the transport factory correctly', async () => {
+      const targetUrl = 'http://example.com/mcp';
+
+      await createClientProxy({
+        targetUrl,
+        wallet: mockWallet,
+        mode: 'http',
+      });
+
+      const callArgs = vi.mocked(createHttpPassthroughProxy).mock.calls[0][0];
+
+      // Check that target is configured with custom transport
+      expect(callArgs.target.transportType).toBe('custom');
+
+      // Test that the factory returns the payment-aware transport
+      if (callArgs.target.transportType === 'custom' && 'transportFactory' in callArgs.target) {
+        const transport = callArgs.target.transportFactory();
+        expect(transport).toBe(mockTransport);
+      }
+    });
+  });
+
+  describe('stdio mode', () => {
+    it('should create a stdio proxy', async () => {
+      const targetUrl = 'http://example.com/mcp';
+
+      const proxy = await createClientProxy({
+        targetUrl,
+        wallet: mockWallet,
+        mode: 'stdio',
+      });
+
+      expect(makePaymentAwareClientTransport).toHaveBeenCalledWith(targetUrl, mockWallet);
+
+      expect(vi.mocked(createStdioPassthroughProxy)).toHaveBeenCalledWith({
+        target: {
+          transportType: 'custom',
+          transportFactory: expect.any(Function),
+        },
+      });
+
+      expect(proxy).toBe(mockStdioProxy);
+    });
+
+    it('should use the transport factory correctly in stdio mode', async () => {
+      const targetUrl = 'http://example.com/mcp';
+
+      await createClientProxy({
+        targetUrl,
+        wallet: mockWallet,
+        mode: 'stdio',
+      });
+
+      const callArgs = vi.mocked(createStdioPassthroughProxy).mock.calls[0][0];
+
+      // Check that target is configured with custom transport
+      expect(callArgs.target.transportType).toBe('custom');
+
+      // Test that the factory returns the payment-aware transport
+      if (callArgs.target.transportType === 'custom' && 'transportFactory' in callArgs.target) {
+        const transport = callArgs.target.transportFactory();
+        expect(transport).toBe(mockTransport);
+      }
+    });
+  });
+
+  describe('transport integration', () => {
+    it('should pass wallet to payment-aware transport', async () => {
+      const targetUrl = 'https://secure.example.com/mcp';
+      const wallet = {
+        account: { address: '0x123456' },
+        chain: { id: 8453 },
+      } as unknown as Wallet;
+
+      await createClientProxy({
+        targetUrl,
+        wallet,
+        mode: 'http',
+      });
+
+      expect(makePaymentAwareClientTransport).toHaveBeenCalledWith(targetUrl, wallet);
+    });
+
+    it('should handle different URL formats', async () => {
+      const urls = ['http://localhost:3000/mcp', 'https://api.example.com/v1/mcp', 'http://192.168.1.1:8080'];
+
+      for (const url of urls) {
+        vi.clearAllMocks();
+
+        await createClientProxy({
+          targetUrl: url,
+          wallet: mockWallet,
+          mode: 'stdio',
+        });
+
+        expect(makePaymentAwareClientTransport).toHaveBeenCalledWith(url, mockWallet);
+      }
+    });
+  });
+});

package/src/proxy/client.ts

@@ -0,0 +1,61 @@
+import {
+  createHttpPassthroughProxy,
+  createStdioPassthroughProxy,
+  type HttpProxyConfig,
+  type PassthroughProxy,
+  type StdioProxyConfig,
+} from '@civic/passthrough-mcp-server';
+import type { Wallet } from 'x402/types';
+import { makePaymentAwareClientTransport } from '../client.js';
+
+/**
+ * Creates a client-side proxy that handles x402 payments on behalf of MCP clients
+ * that don't support payment protocols.
+ *
+ * @param params - Configuration for the proxy
+ * @param params.targetUrl - The URL of the x402-enabled MCP server to proxy to
+ * @param params.walletClient - A viem WalletClient configured with account and chain for payments
+ * @param params.mode - 'stdio' for stdio transport or 'http' for HTTP transport
+ * @param params.port - The port for the proxy to listen on (only for HTTP mode, default: 4000)
+ * @returns The proxy instance
+ */
+export async function createClientProxy(
+  params: {
+    targetUrl: string;
+    wallet: Wallet;
+  } & (
+    | {
+        mode: 'stdio';
+      }
+    | {
+        mode: 'http';
+        port?: number;
+      }
+  )
+): Promise<PassthroughProxy> {
+  // Create the payment-aware transport for the target
+  const paymentAwareTransport = makePaymentAwareClientTransport(params.targetUrl, params.wallet);
+
+  if (params.mode === 'stdio') {
+    // Create stdio proxy configuration
+    const config: StdioProxyConfig = {
+      target: {
+        transportType: 'custom',
+        transportFactory: () => paymentAwareTransport,
+      },
+    };
+
+    return createStdioPassthroughProxy(config);
+  } else {
+    // Create HTTP proxy configuration
+    const config: HttpProxyConfig = {
+      port: params.port ?? 4000,
+      target: {
+        transportType: 'custom',
+        transportFactory: () => paymentAwareTransport,
+      },
+    };
+
+    return createHttpPassthroughProxy(config);
+  }
+}

package/src/proxy/hooks/apiKeyHook.test.ts

@@ -0,0 +1,276 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ApiKeyHook } from './apiKeyHook.js';
+
+describe('ApiKeyHook', () => {
+  let hook: ApiKeyHook;
+  const testApiKey = 'sk-test-123456789';
+
+  beforeEach(() => {
+    hook = new ApiKeyHook(testApiKey);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('constructor and name', () => {
+    it('should initialize with provided API key', () => {
+      expect(hook).toBeDefined();
+      expect(hook).toBeInstanceOf(ApiKeyHook);
+    });
+
+    it('should have correct name', () => {
+      expect(hook.name).toBe('api-key-injector');
+    });
+  });
+
+  describe('processToolCallRequest', () => {
+    it('should add Authorization header to request', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: { name: 'test-tool' },
+        id: 1,
+      };
+
+      const result = await hook.processToolCallRequest(request);
+
+      expect(result).toEqual({
+        resultType: 'continue',
+        request: {
+          ...request,
+          requestContext: {
+            headers: {
+              Authorization: `Bearer ${testApiKey}`,
+            },
+          },
+        },
+      });
+    });
+
+    it('should preserve existing requestContext', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: { name: 'test-tool' },
+        id: 1,
+        requestContext: {
+          existingField: 'value',
+          headers: {
+            'X-Custom-Header': 'custom-value',
+          },
+        },
+      };
+
+      const result = await hook.processToolCallRequest(request);
+
+      expect(result).toEqual({
+        resultType: 'continue',
+        request: {
+          ...request,
+          requestContext: {
+            existingField: 'value',
+            headers: {
+              'X-Custom-Header': 'custom-value',
+              Authorization: `Bearer ${testApiKey}`,
+            },
+          },
+        },
+      });
+    });
+
+    it('should override existing Authorization header', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: {},
+        id: 3,
+        requestContext: {
+          headers: {
+            Authorization: 'Bearer old-key',
+          },
+        },
+      };
+
+      const result = await hook.processToolCallRequest(request);
+
+      expect(result.request.requestContext.headers.Authorization).toBe(`Bearer ${testApiKey}`);
+    });
+
+    it('should handle request without requestContext', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: {},
+        id: 4,
+      };
+
+      const result = await hook.processToolCallRequest(request);
+
+      expect(result).toEqual({
+        resultType: 'continue',
+        request: {
+          ...request,
+          requestContext: {
+            headers: {
+              Authorization: `Bearer ${testApiKey}`,
+            },
+          },
+        },
+      });
+    });
+  });
+
+  describe('processToolsListRequest', () => {
+    it('should add Authorization header to tools list request', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'tools/list',
+        params: {},
+        id: 1,
+      };
+
+      const result = await hook.processToolsListRequest(request);
+
+      expect(result).toEqual({
+        resultType: 'continue',
+        request: {
+          ...request,
+          requestContext: {
+            headers: {
+              Authorization: `Bearer ${testApiKey}`,
+            },
+          },
+        },
+      });
+    });
+
+    it('should preserve existing headers in tools list', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'tools/list',
+        params: {},
+        id: 2,
+        requestContext: {
+          headers: {
+            'Content-Type': 'application/json',
+          },
+        },
+      };
+
+      const result = await hook.processToolsListRequest(request);
+
+      expect(result.request.requestContext.headers).toEqual({
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${testApiKey}`,
+      });
+    });
+  });
+
+  describe('processInitializeRequest', () => {
+    it('should add Authorization header to initialize request', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'initialize',
+        params: {
+          clientInfo: {
+            name: 'test-client',
+            version: '1.0.0',
+          },
+        },
+        id: 1,
+      };
+
+      const result = await hook.processInitializeRequest(request);
+
+      expect(result).toEqual({
+        resultType: 'continue',
+        request: {
+          ...request,
+          requestContext: {
+            headers: {
+              Authorization: `Bearer ${testApiKey}`,
+            },
+          },
+        },
+      });
+    });
+
+    it('should preserve existing requestContext in initialize', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'initialize',
+        params: {},
+        id: 2,
+        requestContext: {
+          sessionId: 'session-123',
+          headers: {
+            'User-Agent': 'TestClient/1.0',
+          },
+        },
+      };
+
+      const result = await hook.processInitializeRequest(request);
+
+      expect(result).toEqual({
+        resultType: 'continue',
+        request: {
+          ...request,
+          requestContext: {
+            sessionId: 'session-123',
+            headers: {
+              'User-Agent': 'TestClient/1.0',
+              Authorization: `Bearer ${testApiKey}`,
+            },
+          },
+        },
+      });
+    });
+  });
+
+  describe('different API key formats', () => {
+    it('should work with various API key formats', async () => {
+      const apiKeys = [
+        'simple-key',
+        'sk-proj-very-long-api-key-with-many-characters',
+        'Bearer existing-token',
+        'ApiKey 12345',
+      ];
+
+      for (const apiKey of apiKeys) {
+        const customHook = new ApiKeyHook(apiKey);
+        const request = {
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          params: {},
+          id: 1,
+        };
+
+        const result = await customHook.processToolCallRequest(request);
+
+        expect(result.request.requestContext.headers.Authorization).toBe(`Bearer ${apiKey}`);
+      }
+    });
+  });
+
+  describe('all methods add the same header', () => {
+    it('should add consistent headers across all methods', async () => {
+      const request = {
+        jsonrpc: '2.0',
+        method: 'test',
+        params: {},
+        id: 1,
+      };
+
+      const toolCallResult = await hook.processToolCallRequest(request);
+      const toolsListResult = await hook.processToolsListRequest(request);
+      const initializeResult = await hook.processInitializeRequest(request);
+
+      const expectedHeader = `Bearer ${testApiKey}`;
+
+      expect(toolCallResult.request.requestContext.headers.Authorization).toBe(expectedHeader);
+      expect(toolsListResult.request.requestContext.headers.Authorization).toBe(expectedHeader);
+      expect(initializeResult.request.requestContext.headers.Authorization).toBe(expectedHeader);
+    });
+  });
+});

package/src/proxy/hooks/apiKeyHook.ts

@@ -0,0 +1,77 @@
+import { AbstractHook } from '@civic/passthrough-mcp-server';
+
+/**
+ * Hook that adds an API key to outgoing requests to authenticate with upstream MCP servers
+ */
+export class ApiKeyHook extends AbstractHook {
+  constructor(private apiKey: string) {
+    super();
+  }
+
+  get name(): string {
+    return 'api-key-injector';
+  }
+
+  /**
+   * Add API key to tool call requests
+   */
+  async processToolCallRequest(request: any): Promise<any> {
+    const modifiedRequest = {
+      ...request,
+      requestContext: {
+        ...request.requestContext,
+        headers: {
+          ...request.requestContext?.headers,
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+      },
+    };
+
+    return {
+      resultType: 'continue',
+      request: modifiedRequest,
+    };
+  }
+
+  /**
+   * Add API key to tools list requests
+   */
+  async processToolsListRequest(request: any): Promise<any> {
+    const modifiedRequest = {
+      ...request,
+      requestContext: {
+        ...request.requestContext,
+        headers: {
+          ...request.requestContext?.headers,
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+      },
+    };
+
+    return {
+      resultType: 'continue',
+      request: modifiedRequest,
+    };
+  }
+
+  /**
+   * Add API key to initialize requests
+   */
+  async processInitializeRequest(request: any): Promise<any> {
+    const modifiedRequest = {
+      ...request,
+      requestContext: {
+        ...request.requestContext,
+        headers: {
+          ...request.requestContext?.headers,
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+      },
+    };
+
+    return {
+      resultType: 'continue',
+      request: modifiedRequest,
+    };
+  }
+}

package/src/proxy/index.ts

@@ -0,0 +1,3 @@
+export { createClientProxy } from './client.js';
+export { ApiKeyHook } from './hooks/apiKeyHook.js';
+export { createServerProxy } from './server.js';

package/src/proxy/server.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+
+// Test the ApiKeyHook separately since it's the part we can easily test
+describe('ApiKeyHook integration', () => {
+  it('should create ApiKeyHook with correct properties', async () => {
+    const { ApiKeyHook } = await import('./hooks/apiKeyHook.js');
+
+    const apiKey = 'sk-test-123456';
+    const hook = new ApiKeyHook(apiKey);
+
+    expect(hook).toBeDefined();
+    expect(hook.name).toBe('api-key-injector');
+  });
+
+  it('should add Authorization header in processToolCallRequest', async () => {
+    const { ApiKeyHook } = await import('./hooks/apiKeyHook.js');
+
+    const apiKey = 'sk-test-789';
+    const hook = new ApiKeyHook(apiKey);
+
+    const request = {
+      jsonrpc: '2.0',
+      method: 'tools/call',
+      params: {},
+      id: 1,
+    };
+
+    const result = await hook.processToolCallRequest(request);
+
+    expect(result.resultType).toBe('continue');
+    expect(result.request.requestContext.headers.Authorization).toBe(`Bearer ${apiKey}`);
+  });
+});

package/src/proxy/server.ts

@@ -0,0 +1,43 @@
+import { createPassthroughProxy, type PassthroughProxy } from '@civic/passthrough-mcp-server';
+import type { Address } from 'viem';
+import { makePaymentAwareServerTransport } from '../server.js';
+import { ApiKeyHook } from './hooks/apiKeyHook.js';
+
+/**
+ * Creates a server-side proxy that:
+ * 1. Accepts x402 payments from clients
+ * 2. Adds an API key to authenticate with the upstream MCP server
+ *
+ * This allows monetizing access to API-key-protected MCP servers via micropayments.
+ *
+ * @param upstreamUrl - The URL of the API-key-protected MCP server to proxy to
+ * @param apiKey - The API key to authenticate with the upstream server
+ * @param paymentWallet - The wallet address to receive payments
+ * @param toolPricing - Mapping of tool names to prices (e.g., { "my-tool": "$0.01" })
+ * @param port - The port for the proxy to listen on (default: 5000)
+ * @returns The proxy instance
+ */
+export async function createServerProxy(
+  upstreamUrl: string,
+  apiKey: string,
+  paymentWallet: Address | string,
+  toolPricing: Record<string, string>
+): Promise<PassthroughProxy> {
+  // Create the payment-aware server transport
+  const paymentAwareTransport = makePaymentAwareServerTransport(paymentWallet, toolPricing);
+
+  // Create the API key hook
+  const apiKeyHook = new ApiKeyHook(apiKey);
+
+  // Create and return the proxy
+  return createPassthroughProxy({
+    sourceTransportType: 'custom',
+    sourceTransport: paymentAwareTransport,
+    target: {
+      url: upstreamUrl,
+      transportType: 'httpStream',
+    },
+    hooks: [apiKeyHook],
+    autoStart: true,
+  });
+}