@goplausible/algorand-mcp 4.3.1 → 4.3.3

package/dist/tools/utilityManager.js

@@ -86,7 +86,7 @@ export class UtilityManager {
                                 type: 'text',
                                 text: JSON.stringify({
                                     name: 'Algorand MCP Server',
-                                    version: '4.3.1',
+                                    version: '4.3.2',
                                     builder: 'GoPlausible',
                                     description: 'A Model Context Protocol (MCP) server providing comprehensive access to the Algorand blockchain. Supports account management, transaction building and signing, smart contract interaction, asset operations, ARC-26 URI generation, and deep integration with Algorand ecosystem services including NFDomains, Tinyman, Vestige, and Ultrade.',
                                     blockchain: 'Algorand — a carbon-negative, pure proof-of-stake Layer 1 blockchain delivering instant finality, low fees, and advanced smart contract capabilities via AVM (Algorand Virtual Machine).',

package/dist/tools/x402Manager.d.ts

@@ -12,6 +12,15 @@ export declare class X402Manager {
     }>;
     private static handleDiscover;
     private static handlePaidRequest;
+    /**
+     * Returns the amount field from a PaymentRequirement, supporting both x402
+     * spec versions:
+     *   - V2 (current): `amount`
+     *   - V1 (legacy):  `maxAmountRequired`
+     * Prefers V2 if both are set (V2 deployments may include both for compat).
+     */
+    private static getRequirementAmount;
+    private static isValidPaymentRequiredResponse;
     private static discover;
     private static selectRequirement;
     private static buildPaymentHeader;

package/dist/tools/x402Manager.js

@@ -45,8 +45,29 @@ const x402ToolSchemas = {
             headers: { type: 'object', description: 'Optional additional request headers', additionalProperties: { type: 'string' } },
             correlationId: { type: 'string', description: 'Optional correlation id; forwarded as X-Correlation-ID header' },
             maxAmountPerRequest: { type: 'integer', description: 'Maximum payment in USDC atomic units (1,000,000 = $1.00). If a payment requirement exceeds this, the call is refused.' },
-            paymentRequirements: { type: 'array', description: 'Pre-fetched accepts[] array from a prior x402_discover_payment_requirements call. If omitted, this tool discovers internally.' },
-            preferredNetwork: { type: 'string', enum: ['mainnet', 'testnet', 'localnet'], description: 'Preferred Algorand network. When multiple accepts entries match, this network wins. If omitted, the active wallet network is used.' },
+            paymentRequirements: {
+                type: 'array',
+                description: 'Pre-fetched accepts[] array from a prior x402_discover_payment_requirements call. If omitted, this tool discovers internally. Each element must be an OBJECT with at least { scheme, network, payTo, asset, amount }. Common mistake: passing `preferredNetwork` or `maxAmountPerRequest` as array elements instead of sibling top-level fields.',
+                items: {
+                    type: 'object',
+                    required: ['scheme', 'network', 'payTo', 'asset'],
+                    properties: {
+                        scheme: { type: 'string' },
+                        network: { type: 'string', description: 'CAIP-2 network identifier, e.g. "algorand:SGO1…" for testnet.' },
+                        amount: { type: 'string', description: 'x402 V2 canonical amount field (atomic units as decimal string).' },
+                        maxAmountRequired: { type: 'string', description: 'x402 V1 legacy amount field. Either `amount` or `maxAmountRequired` must be present.' },
+                        payTo: { type: 'string' },
+                        asset: { type: 'string' },
+                        maxTimeoutSeconds: { type: 'integer' },
+                        extra: { type: 'object' }
+                    }
+                }
+            },
+            preferredNetwork: {
+                type: 'string',
+                enum: ['mainnet', 'testnet', 'localnet'],
+                description: 'TOP-LEVEL sibling of paymentRequirements (NOT an array element). Preferred Algorand network when multiple accepts entries match. If omitted, the cheapest affordable Algorand entry is chosen.'
+            },
             extensions: { type: 'object', description: 'Optional pre-fetched PaymentRequired extensions (e.g. Bazaar resource details). Passed through to the response under `extensions`.' },
         },
         required: ['baseURL', 'path', 'method'],
@@ -86,7 +107,35 @@ export class X402Manager {
         const preferredNetwork = typeof args.preferredNetwork === 'string' ? args.preferredNetwork : undefined;
         const extensions = args.extensions ?? undefined;
         let accepts = Array.isArray(args.paymentRequirements) ? args.paymentRequirements : undefined;
-        // 1. Discover if needed
+        // 1a. Defensive validation: every paymentRequirements entry must be an
+        //     object with at least { network, payTo, asset } and an amount field
+        //     (either x402 V2 `amount` or V1 `maxAmountRequired`). LLMs frequently
+        //     malform JSON by appending sibling field names (e.g. "preferredNetwork")
+        //     as bare strings inside this array — catch that here with an actionable
+        //     message rather than crashing later in selectRequirement.
+        if (accepts) {
+            for (let i = 0; i < accepts.length; i++) {
+                const entry = accepts[i];
+                const isObject = !!entry && typeof entry === 'object' && !Array.isArray(entry);
+                if (!isObject) {
+                    throw new McpError(ErrorCode.InvalidParams, `paymentRequirements[${i}] must be an OBJECT (got ${entry === null ? 'null' : Array.isArray(entry) ? 'array' : typeof entry}: ${JSON.stringify(entry)}). Tip: pass the accepts[] array verbatim from x402_discover_payment_requirements. Other arguments like preferredNetwork and maxAmountPerRequest are TOP-LEVEL siblings of paymentRequirements, not array members.`);
+                }
+                const e = entry;
+                const missing = [];
+                if (typeof e.network !== 'string')
+                    missing.push('network');
+                if (typeof e.payTo !== 'string')
+                    missing.push('payTo');
+                if (typeof e.asset !== 'string')
+                    missing.push('asset');
+                if (typeof e.amount !== 'string' && typeof e.maxAmountRequired !== 'string')
+                    missing.push('amount (or maxAmountRequired)');
+                if (missing.length > 0) {
+                    throw new McpError(ErrorCode.InvalidParams, `paymentRequirements[${i}] is missing required string field(s): ${missing.join(', ')}. Expected shape: { scheme, network, payTo, asset, amount, extra: { feePayer, ... } }. Pass the accepts[] entry verbatim from x402_discover_payment_requirements.`);
+                }
+            }
+        }
+        // 1b. Discover if needed
         if (!accepts || accepts.length === 0) {
             const discovered = await X402Manager.discover({ baseURL, path, method, queryParams, body });
             if (!discovered.x402 || !Array.isArray(discovered.accepts) || discovered.accepts.length === 0) {
@@ -108,7 +157,10 @@ export class X402Manager {
             throw new McpError(ErrorCode.InvalidRequest, `Payment rejected by server: ${X402Manager.snippet(response.bodyText)}`);
         }
         const result = X402Manager.tryParseJson(response.bodyText) ?? response.bodyText;
-        const paymentResponseHeader = response.headers['x-payment-response'] ?? response.headers['X-PAYMENT-RESPONSE'];
+        // Algorand x402 V2 uses lowercase `payment-response`; older deployments
+        // may use Coinbase's `x-payment-response`. Accept either.
+        const paymentResponseHeader = response.headers['payment-response']
+            ?? response.headers['x-payment-response'];
         return X402Manager.textResponse({
             result,
             status: response.status,
@@ -116,27 +168,51 @@ export class X402Manager {
             paid: {
                 network: mcpNetwork,
                 asset: requirement.asset,
-                amount: requirement.maxAmountRequired,
+                amount: X402Manager.getRequirementAmount(requirement),
                 payTo: requirement.payTo,
             },
             extensions,
         });
     }
     // ── x402 protocol helpers ──────────────────────────────────────────────────
+    /**
+     * Returns the amount field from a PaymentRequirement, supporting both x402
+     * spec versions:
+     *   - V2 (current): `amount`
+     *   - V1 (legacy):  `maxAmountRequired`
+     * Prefers V2 if both are set (V2 deployments may include both for compat).
+     */
+    static getRequirementAmount(req) {
+        return req.amount ?? req.maxAmountRequired;
+    }
+    static isValidPaymentRequiredResponse(v) {
+        return !!v
+            && typeof v === 'object'
+            && typeof v.x402Version === 'number'
+            && Array.isArray(v.accepts);
+    }
     static async discover(opts) {
         const response = await X402Manager.httpRequest(opts);
-        if (response.status !== 402) {
-            return { status: response.status, x402: false, rawBody: X402Manager.tryParseJson(response.bodyText) ?? response.bodyText };
+        // 1. Canonical Algorand x402 V2 transport: requirements arrive in the
+        //    `payment-required` HTTP header as base64-encoded JSON. The body is
+        //    usually empty (`{}`). Check this first.
+        const headerPayload = response.headers['payment-required'];
+        if (headerPayload) {
+            const decoded = X402Manager.decodeBase64Json(headerPayload);
+            if (X402Manager.isValidPaymentRequiredResponse(decoded)) {
+                return { status: response.status, x402: true, accepts: decoded.accepts, x402Version: decoded.x402Version };
+            }
         }
-        const parsed = X402Manager.tryParseJson(response.bodyText);
-        if (!parsed ||
-            typeof parsed !== 'object' ||
-            typeof parsed.x402Version !== 'number' ||
-            !Array.isArray(parsed.accepts)) {
+        // 2. Fallback transport (some x402 servers put requirements in the 402 body).
+        if (response.status === 402) {
+            const parsed = X402Manager.tryParseJson(response.bodyText);
+            if (X402Manager.isValidPaymentRequiredResponse(parsed)) {
+                return { status: 402, x402: true, accepts: parsed.accepts, x402Version: parsed.x402Version };
+            }
             return { status: 402, x402: false, rawBody: parsed ?? response.bodyText };
         }
-        const body = parsed;
-        return { status: 402, x402: true, accepts: body.accepts, x402Version: body.x402Version };
+        // 3. Not an x402-protected response at all.
+        return { status: response.status, x402: false, rawBody: X402Manager.tryParseJson(response.bodyText) ?? response.bodyText };
     }
     static selectRequirement(accepts, preferredNetwork, maxAmountPerRequest) {
         // Map each accepts entry to its MCP network (or null if non-Algorand).
@@ -146,10 +222,11 @@ export class X402Manager {
         if (ranked.length === 0) {
             throw new McpError(ErrorCode.InvalidRequest, `No payment requirement is satisfiable on Algorand. Endpoint accepts networks: [${accepts.map(r => r.network).join(', ')}]`);
         }
-        const inBudget = (req) => maxAmountPerRequest === undefined || Number(req.maxAmountRequired) <= maxAmountPerRequest;
+        const amountOf = (req) => Number(X402Manager.getRequirementAmount(req));
+        const inBudget = (req) => maxAmountPerRequest === undefined || amountOf(req) <= maxAmountPerRequest;
         const affordable = ranked.filter(e => inBudget(e.req));
         if (affordable.length === 0) {
-            throw new McpError(ErrorCode.InvalidRequest, `All Algorand payment requirements exceed maxAmountPerRequest=${maxAmountPerRequest}. Cheapest: ${Math.min(...ranked.map(e => Number(e.req.maxAmountRequired)))}.`);
+            throw new McpError(ErrorCode.InvalidRequest, `All Algorand payment requirements exceed maxAmountPerRequest=${maxAmountPerRequest}. Cheapest: ${Math.min(...ranked.map(e => amountOf(e.req)))}.`);
         }
         if (preferredNetwork) {
             const preferred = affordable.find(e => e.mcpNetwork === preferredNetwork);
@@ -157,7 +234,7 @@ export class X402Manager {
                 return { requirement: preferred.req, mcpNetwork: preferred.mcpNetwork };
         }
         // No preference (or preference not matched): pick the cheapest affordable.
-        const chosen = affordable.reduce((a, b) => Number(a.req.maxAmountRequired) <= Number(b.req.maxAmountRequired) ? a : b);
+        const chosen = affordable.reduce((a, b) => amountOf(a.req) <= amountOf(b.req) ? a : b);
         return { requirement: chosen.req, mcpNetwork: chosen.mcpNetwork };
     }
     static async buildPaymentHeader(requirement, mcpNetwork) {
@@ -165,9 +242,10 @@ export class X402Manager {
         if (!feePayer || typeof feePayer !== 'string') {
             throw new McpError(ErrorCode.InvalidRequest, 'Payment requirement is missing `extra.feePayer` (facilitator address).');
         }
-        const amount = Number(requirement.maxAmountRequired);
+        const amountStr = X402Manager.getRequirementAmount(requirement);
+        const amount = Number(amountStr);
         if (!Number.isFinite(amount) || amount < 0) {
-            throw new McpError(ErrorCode.InvalidRequest, `Invalid maxAmountRequired: ${requirement.maxAmountRequired}`);
+            throw new McpError(ErrorCode.InvalidRequest, `Invalid payment amount: ${amountStr ?? '(missing `amount` / `maxAmountRequired` field)'}`);
         }
         const account = await WalletManager.getActiveWalletAccount();
         const sk = await WalletManager.getActiveWalletSecretKey();

package/dist/types.d.ts

@@ -47,16 +47,16 @@ export declare const AccountDetailsSchema: z.ZodObject<{
     }>, "many">;
     authAddress: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    address: string;
     amount: number | bigint;
+    address: string;
     assets: {
         assetId: number | bigint;
         amount: number | bigint;
     }[];
     authAddress?: string | undefined;
 }, {
-    address: string;
     amount: number | bigint;
+    address: string;
     assets: {
         assetId: number | bigint;
         amount: number | bigint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/algorand-mcp",
-  "version": "4.3.1",
+  "version": "4.3.3",
   "publishConfig": {
     "access": "public"
   },