nullpath-mcp 1.1.0

package/dist/index.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * nullpath MCP Client
+ *
+ * Connects to nullpath.com/mcp - AI agent marketplace with x402 micropayments.
+ *
+ * Available tools:
+ * - discover_agents: Search agents by capability
+ * - lookup_agent: Get agent details by ID
+ * - execute_agent: Run an agent (paid via x402)
+ * - register_agent: Register a new agent (paid)
+ * - get_capabilities: List capability categories
+ * - check_reputation: Get agent trust score
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.signTransferAuthorization = signTransferAuthorization;
+exports.encodePaymentHeader = encodePaymentHeader;
+exports.isX402Error = isX402Error;
+exports.getWallet = getWallet;
+exports.handleX402Payment = handleX402Payment;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const index_js_2 = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const accounts_1 = require("viem/accounts");
+const NULLPATH_MCP_URL = process.env.NULLPATH_MCP_URL || 'https://nullpath.com/mcp';
+/**
+ * EIP-3009 TransferWithAuthorization typed data
+ */
+const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+    TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+    ],
+};
+/**
+ * USDC contract metadata by network
+ */
+const USDC_CONTRACTS = {
+    'base': { name: 'USD Coin', version: '2', chainId: 8453 },
+    'base-sepolia': { name: 'USD Coin', version: '2', chainId: 84532 },
+};
+/**
+ * Generate a random 32-byte nonce for EIP-3009
+ */
+function generateNonce() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return `0x${Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')}`;
+}
+/**
+ * Sign an EIP-3009 TransferWithAuthorization
+ */
+async function signTransferAuthorization(wallet, requirements) {
+    const network = requirements.network;
+    const contractMeta = USDC_CONTRACTS[network];
+    if (!contractMeta) {
+        throw new Error(`Unsupported network: ${network}`);
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const validAfter = now - 60; // Valid from 1 minute ago
+    const validBefore = now + requirements.maxTimeoutSeconds;
+    const nonce = generateNonce();
+    const authorization = {
+        from: wallet.address,
+        to: requirements.payTo,
+        value: BigInt(requirements.maxAmountRequired),
+        validAfter: BigInt(validAfter),
+        validBefore: BigInt(validBefore),
+        nonce,
+    };
+    // Create account for signing
+    const account = (0, accounts_1.privateKeyToAccount)(wallet.privateKey);
+    const signature = await account.signTypedData({
+        domain: {
+            name: contractMeta.name,
+            version: contractMeta.version,
+            chainId: contractMeta.chainId,
+            verifyingContract: requirements.asset,
+        },
+        types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+        primaryType: 'TransferWithAuthorization',
+        message: authorization,
+    });
+    return {
+        x402Version: 1,
+        scheme: 'exact',
+        network,
+        payload: {
+            signature,
+            authorization: {
+                from: wallet.address,
+                to: requirements.payTo,
+                value: authorization.value.toString(),
+                validAfter: authorization.validAfter.toString(),
+                validBefore: authorization.validBefore.toString(),
+                nonce,
+            },
+        },
+    };
+}
+/**
+ * Encode payment payload to base64 for X-PAYMENT header
+ */
+function encodePaymentHeader(payment) {
+    return Buffer.from(JSON.stringify(payment)).toString('base64');
+}
+/**
+ * Check if an error response is an x402 payment required error
+ */
+function isX402Error(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const err = error;
+    if (err.code !== -32000)
+        return false;
+    if (typeof err.data !== 'object' || err.data === null)
+        return false;
+    const data = err.data;
+    return typeof data.x402Version === 'number' && Array.isArray(data.accepts);
+}
+/**
+ * Get wallet from environment variable
+ */
+function getWallet() {
+    const privateKey = process.env.NULLPATH_WALLET_KEY;
+    if (!privateKey) {
+        throw new Error('NULLPATH_WALLET_KEY environment variable is required for paid tool calls. ' +
+            'Set it to your wallet private key (0x-prefixed hex string).');
+    }
+    // Ensure the key is properly formatted
+    const formattedKey = privateKey.startsWith('0x')
+        ? privateKey
+        : `0x${privateKey}`;
+    const account = (0, accounts_1.privateKeyToAccount)(formattedKey);
+    return {
+        address: account.address,
+        privateKey: formattedKey,
+    };
+}
+/**
+ * Handle x402 payment flow
+ *
+ * 1. Parse payment requirements from 402 error
+ * 2. Sign EIP-3009 authorization
+ * 3. Return payment header for retry
+ */
+async function handleX402Payment(errorData) {
+    const wallet = getWallet();
+    if (errorData.accepts.length === 0) {
+        throw new Error('No payment options available in 402 response');
+    }
+    // Use the first payment option
+    const requirements = errorData.accepts[0];
+    // Sign the payment authorization
+    const payment = await signTransferAuthorization(wallet, requirements);
+    // Encode for header
+    return encodePaymentHeader(payment);
+}
+async function main() {
+    // Create a local stdio server that proxies to nullpath's remote MCP
+    const server = new index_js_2.Server({
+        name: 'nullpath-mcp',
+        version: '1.0.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Connect to remote nullpath MCP server
+    const transport = new sse_js_1.SSEClientTransport(new URL(NULLPATH_MCP_URL));
+    const client = new index_js_1.Client({
+        name: 'nullpath-mcp-proxy',
+        version: '1.0.0',
+    }, {
+        capabilities: {},
+    });
+    await client.connect(transport);
+    // List available tools from remote server
+    const tools = await client.listTools();
+    // Register tool handlers that proxy to remote
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        return tools;
+    });
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        try {
+            // First attempt without payment
+            const result = await client.callTool({
+                name: request.params.name,
+                arguments: request.params.arguments,
+            });
+            return result;
+        }
+        catch (error) {
+            // Check if this is a 402 Payment Required error
+            if (isX402Error(error)) {
+                console.error(`Payment required for tool: ${request.params.name}`);
+                try {
+                    // Handle x402 payment
+                    const paymentHeader = await handleX402Payment(error.data);
+                    // Retry with payment header
+                    // Note: The MCP SDK doesn't directly support custom headers on tool calls,
+                    // so we need to make the request ourselves with the payment header
+                    const retryResult = await retryWithPayment(request.params.name, request.params.arguments, paymentHeader);
+                    return retryResult;
+                }
+                catch (paymentError) {
+                    // Re-throw with more context
+                    throw new Error(`Payment failed for tool ${request.params.name}: ${paymentError instanceof Error ? paymentError.message : String(paymentError)}`);
+                }
+            }
+            // Re-throw non-payment errors
+            throw error;
+        }
+    });
+    // Start local stdio transport
+    const stdioTransport = new stdio_js_1.StdioServerTransport();
+    await server.connect(stdioTransport);
+    console.error('nullpath MCP client connected to', NULLPATH_MCP_URL);
+}
+/**
+ * Retry a tool call with x402 payment header
+ *
+ * Makes a direct HTTP request to the MCP server with the X-PAYMENT header
+ */
+async function retryWithPayment(toolName, args, paymentHeader) {
+    const requestBody = {
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: {
+            name: toolName,
+            arguments: args || {},
+        },
+        id: Date.now(),
+    };
+    const response = await fetch(NULLPATH_MCP_URL, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-PAYMENT': paymentHeader,
+        },
+        body: JSON.stringify(requestBody),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP ${response.status}: ${errorText}`);
+    }
+    const result = await response.json();
+    if (result.error) {
+        throw new Error(`RPC Error: ${result.error.message}`);
+    }
+    return result.result || { content: [{ type: 'text', text: 'Success' }] };
+}
+main().catch((error) => {
+    console.error('Failed to start nullpath MCP client:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "nullpath-mcp",
+  "version": "1.1.0",
+  "description": "Connect to nullpath's AI agent marketplace via MCP. Discover and pay agents with x402 micropayments.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nullpath-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "nullpath",
+    "x402",
+    "micropayments",
+    "usdc",
+    "base"
+  ],
+  "author": "nullpath-labs",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nullpath-labs/mcp-client.git"
+  },
+  "homepage": "https://nullpath.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/__tests__/x402.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import {
+  signTransferAuthorization,
+  encodePaymentHeader,
+  handleX402Payment,
+  getWallet,
+  isX402Error,
+  type PaymentRequirements,
+  type X402ErrorData,
+  type Wallet,
+} from '../index.js';
+
+// Test wallet - DO NOT use in production
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+const TEST_ADDRESS = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266';
+
+// USDC addresses
+const USDC_BASE = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const USDC_BASE_SEPOLIA = '0x036CbD53842c5426634e7929541eC2318f3dCF7e';
+
+describe('x402 Payment Signing', () => {
+  const mockRequirements: PaymentRequirements = {
+    scheme: 'exact',
+    network: 'base-sepolia',
+    maxAmountRequired: '100000', // 0.10 USDC (6 decimals)
+    resource: 'https://nullpath.com/mcp',
+    description: 'Payment for MCP tool: register_agent',
+    mimeType: 'application/json',
+    payTo: '0x1234567890123456789012345678901234567890' as `0x${string}`,
+    maxTimeoutSeconds: 300,
+    asset: USDC_BASE_SEPOLIA,
+    extra: {},
+  };
+
+  const testWallet: Wallet = {
+    address: TEST_ADDRESS as `0x${string}`,
+    privateKey: TEST_PRIVATE_KEY as `0x${string}`,
+  };
+
+  describe('signTransferAuthorization', () => {
+    it('should sign a valid EIP-3009 authorization for base-sepolia', async () => {
+      const payment = await signTransferAuthorization(testWallet, mockRequirements);
+
+      expect(payment.x402Version).toBe(1);
+      expect(payment.scheme).toBe('exact');
+      expect(payment.network).toBe('base-sepolia');
+      expect(payment.payload.signature).toMatch(/^0x[a-fA-F0-9]{130}$/);
+      expect(payment.payload.authorization.from).toBe(TEST_ADDRESS);
+      expect(payment.payload.authorization.to).toBe(mockRequirements.payTo);
+      expect(payment.payload.authorization.value).toBe('100000');
+      expect(payment.payload.authorization.nonce).toMatch(/^0x[a-fA-F0-9]{64}$/);
+    });
+
+    it('should sign a valid EIP-3009 authorization for base mainnet', async () => {
+      const mainnetRequirements: PaymentRequirements = {
+        ...mockRequirements,
+        network: 'base',
+        asset: USDC_BASE,
+      };
+
+      const payment = await signTransferAuthorization(testWallet, mainnetRequirements);
+
+      expect(payment.network).toBe('base');
+      expect(payment.payload.signature).toMatch(/^0x[a-fA-F0-9]{130}$/);
+    });
+
+    it('should throw for unsupported network', async () => {
+      const badRequirements = {
+        ...mockRequirements,
+        network: 'ethereum' as 'base' | 'base-sepolia',
+      };
+
+      await expect(signTransferAuthorization(testWallet, badRequirements))
+        .rejects.toThrow('Unsupported network: ethereum');
+    });
+
+    it('should set validBefore based on maxTimeoutSeconds', async () => {
+      const now = Math.floor(Date.now() / 1000);
+      const payment = await signTransferAuthorization(testWallet, mockRequirements);
+
+      const validBefore = parseInt(payment.payload.authorization.validBefore, 10);
+      // validBefore should be approximately now + maxTimeoutSeconds (within 5 seconds tolerance)
+      expect(validBefore).toBeGreaterThan(now + mockRequirements.maxTimeoutSeconds - 5);
+      expect(validBefore).toBeLessThan(now + mockRequirements.maxTimeoutSeconds + 5);
+    });
+  });
+
+  describe('encodePaymentHeader', () => {
+    it('should encode payment payload to base64', async () => {
+      const payment = await signTransferAuthorization(testWallet, mockRequirements);
+      const encoded = encodePaymentHeader(payment);
+
+      // Should be valid base64
+      expect(() => Buffer.from(encoded, 'base64')).not.toThrow();
+
+      // Should decode back to valid JSON
+      const decoded = JSON.parse(Buffer.from(encoded, 'base64').toString('utf-8'));
+      expect(decoded.x402Version).toBe(1);
+      expect(decoded.scheme).toBe('exact');
+      expect(decoded.payload.signature).toBe(payment.payload.signature);
+    });
+  });
+
+  describe('isX402Error', () => {
+    it('should return true for valid x402 error', () => {
+      const error = {
+        code: -32000,
+        message: 'Payment required',
+        data: {
+          x402Version: 1,
+          error: 'Payment required for tool: register_agent',
+          accepts: [mockRequirements],
+        },
+      };
+
+      expect(isX402Error(error)).toBe(true);
+    });
+
+    it('should return false for non-x402 errors', () => {
+      expect(isX402Error(null)).toBe(false);
+      expect(isX402Error(undefined)).toBe(false);
+      expect(isX402Error({ code: -32600 })).toBe(false);
+      expect(isX402Error({ code: -32000, data: {} })).toBe(false);
+      expect(isX402Error({ code: -32000, data: { x402Version: 1 } })).toBe(false);
+    });
+  });
+});
+
+describe('Wallet Management', () => {
+  const originalEnv = process.env.NULLPATH_WALLET_KEY;
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.NULLPATH_WALLET_KEY = originalEnv;
+    } else {
+      delete process.env.NULLPATH_WALLET_KEY;
+    }
+  });
+
+  describe('getWallet', () => {
+    it('should throw when NULLPATH_WALLET_KEY is not set', () => {
+      delete process.env.NULLPATH_WALLET_KEY;
+
+      expect(() => getWallet()).toThrow('NULLPATH_WALLET_KEY environment variable is required');
+    });
+
+    it('should return wallet when key is set with 0x prefix', () => {
+      process.env.NULLPATH_WALLET_KEY = TEST_PRIVATE_KEY;
+
+      const wallet = getWallet();
+      expect(wallet.address).toBe(TEST_ADDRESS);
+      expect(wallet.privateKey).toBe(TEST_PRIVATE_KEY);
+    });
+
+    it('should handle key without 0x prefix', () => {
+      process.env.NULLPATH_WALLET_KEY = TEST_PRIVATE_KEY.slice(2);
+
+      const wallet = getWallet();
+      expect(wallet.address).toBe(TEST_ADDRESS);
+    });
+  });
+});
+
+describe('handleX402Payment', () => {
+  const mockX402Data: X402ErrorData = {
+    x402Version: 1,
+    error: 'Payment required for tool: register_agent',
+    accepts: [
+      {
+        scheme: 'exact',
+        network: 'base-sepolia',
+        maxAmountRequired: '100000',
+        resource: 'https://nullpath.com/mcp',
+        description: 'Payment for MCP tool: register_agent',
+        mimeType: 'application/json',
+        payTo: '0x1234567890123456789012345678901234567890' as `0x${string}`,
+        maxTimeoutSeconds: 300,
+        asset: USDC_BASE_SEPOLIA,
+        extra: {},
+      },
+    ],
+  };
+
+  const originalEnv = process.env.NULLPATH_WALLET_KEY;
+
+  beforeEach(() => {
+    process.env.NULLPATH_WALLET_KEY = TEST_PRIVATE_KEY;
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.NULLPATH_WALLET_KEY = originalEnv;
+    } else {
+      delete process.env.NULLPATH_WALLET_KEY;
+    }
+  });
+
+  it('should generate valid payment header from 402 response', async () => {
+    const header = await handleX402Payment(mockX402Data);
+
+    // Should be valid base64
+    const decoded = JSON.parse(Buffer.from(header, 'base64').toString('utf-8'));
+    
+    expect(decoded.x402Version).toBe(1);
+    expect(decoded.scheme).toBe('exact');
+    expect(decoded.network).toBe('base-sepolia');
+    expect(decoded.payload.signature).toMatch(/^0x[a-fA-F0-9]{130}$/);
+    expect(decoded.payload.authorization.from).toBe(TEST_ADDRESS);
+    expect(decoded.payload.authorization.to).toBe(mockX402Data.accepts[0].payTo);
+    expect(decoded.payload.authorization.value).toBe('100000');
+  });
+
+  it('should throw when no payment options available', async () => {
+    const emptyData: X402ErrorData = {
+      ...mockX402Data,
+      accepts: [],
+    };
+
+    await expect(handleX402Payment(emptyData))
+      .rejects.toThrow('No payment options available in 402 response');
+  });
+
+  it('should throw when wallet key is missing', async () => {
+    delete process.env.NULLPATH_WALLET_KEY;
+
+    await expect(handleX402Payment(mockX402Data))
+      .rejects.toThrow('NULLPATH_WALLET_KEY environment variable is required');
+  });
+});