@ecadlabs/tezosx-mcp 1.0.2 → 1.0.3

package/dist/live-config.d.ts

@@ -6,6 +6,12 @@ export interface LiveConfig {
     tzktApi: string;
     configured: boolean;
 }
+/**
+ * Calculate the fee rebate amount to keep the spender address funded for gas.
+ * Returns 0 if the spender has sufficient balance, otherwise the amount needed
+ * to bring the balance up to the target level.
+ */
+export declare function calculateFeeRebate(spenderBalanceMutez: number): number;
 export declare const NETWORKS: {
     readonly mainnet: {
         readonly rpcUrl: "https://mainnet.tezos.ecadinfra.com";

package/dist/live-config.js

@@ -1,5 +1,19 @@
 import { TezosToolkit } from "@taquito/taquito";
 import { InMemorySigner } from "@taquito/signer";
+// Spender fee rebate thresholds (in mutez)
+const SPENDER_TOP_UP_THRESHOLD = 250_000; // 0.25 XTZ — rebate when below this
+const SPENDER_TOP_UP_TARGET = 500_000; // 0.5 XTZ — rebate up to this level
+/**
+ * Calculate the fee rebate amount to keep the spender address funded for gas.
+ * Returns 0 if the spender has sufficient balance, otherwise the amount needed
+ * to bring the balance up to the target level.
+ */
+export function calculateFeeRebate(spenderBalanceMutez) {
+    if (spenderBalanceMutez < SPENDER_TOP_UP_THRESHOLD) {
+        return SPENDER_TOP_UP_TARGET - spenderBalanceMutez;
+    }
+    return 0;
+}
 export const NETWORKS = {
     mainnet: {
         rpcUrl: 'https://mainnet.tezos.ecadinfra.com',

package/dist/tools/create_x402_payment.js

@@ -29,19 +29,18 @@ export const createCreateX402PaymentTool = (config) => ({
         if (isNaN(amountMutez) || amountMutez <= 0) {
             throw new Error(`Invalid amount: ${amount}. Must be a positive integer in mutez.`);
         }
-        // Get source address from signer
-        const source = await Tezos.signer.publicKeyHash();
-        // Validate source has sufficient funds
-        const sourceBalance = await Tezos.tz.getBalance(source);
-        if (sourceBalance.toNumber() < amountMutez + 10000) { // Add buffer for fees
-            throw new Error(`Insufficient balance. ` +
-                `Required: ${amountMutez + 10000} mutez (including fees), ` +
-                `Available: ${sourceBalance.toNumber()} mutez`);
+        // Validate contract has sufficient funds for the payment
+        const contractBalance = await Tezos.tz.getBalance(config.spendingContract);
+        if (contractBalance.toNumber() < amountMutez) {
+            throw new Error(`Insufficient contract balance. ` +
+                `Required: ${amountMutez} mutez, ` +
+                `Available: ${contractBalance.toNumber()} mutez`);
         }
         const signed = await signX402Payment(Tezos, {
             network,
             amount: amountMutez,
             recipient,
+            spendingContract: config.spendingContract,
         });
         return {
             content: [{

package/dist/tools/fetch_with_x402.d.ts

@@ -10,7 +10,7 @@ export declare const createFetchWithX402Tool: (config: LiveConfig) => {
             maxAmountMutez: z.ZodString;
             method: z.ZodOptional<z.ZodString>;
             body: z.ZodOptional<z.ZodString>;
-            nftRecipientAddress: z.ZodOptional<z.ZodString>;
+            queryParams: z.ZodOptional<z.ZodString>;
         }, z.z.core.$strip>;
         annotations: {
             readOnlyHint: boolean;

package/dist/tools/fetch_with_x402.js

@@ -7,13 +7,13 @@ export const createFetchWithX402Tool = (config) => ({
     name: "tezos_fetch_with_x402",
     config: {
         title: "Fetch with x402 Payment",
-        description: "Fetches a URL and automatically handles x402 payment requirements. If the server returns 402, it parses the requirements, creates a signed payment, and retries the request with the X-PAYMENT header. WARNING: For NFT minting endpoints (URLs containing '/mint' or otherwise going to a minter), you MUST set 'nftRecipientAddress' to the user's wallet address, otherwise the NFT will be sent to the spender account instead of the user.",
+        description: "Fetches a URL and automatically handles x402 payment requirements. If the server returns 402, it parses the requirements, creates a signed payment, and retries the request with the X-PAYMENT header. Use 'queryParams' to pass dynamic parameters to the endpoint (e.g., for NFT minting, pass {\"recipient\": \"tz1...\"} so the NFT goes to the user's wallet instead of the spender account).",
         inputSchema: z.object({
             url: z.string().describe("The URL to fetch"),
             maxAmountMutez: z.string().describe("Maximum amount in mutez willing to pay (e.g., '500000' for 0.5 XTZ)"),
             method: z.string().optional().describe("HTTP method (default: GET)"),
-            body: z.string().optional().describe("Request body for POST/PUT requests"),
-            nftRecipientAddress: z.string().optional().describe("REQUIRED FOR MINTING: The user's wallet address (tz1...) to receive minted NFTs. If omitted, NFTs go to the spender account, not the user."),
+            body: z.string().optional().describe("Request body for POST/PUT requests (JSON string)"),
+            queryParams: z.string().optional().describe("JSON object of query parameters to append to the URL (e.g., '{\"recipient\": \"tz1...\", \"amount\": \"100\"}')"),
         }),
         annotations: {
             readOnlyHint: false,
@@ -24,17 +24,27 @@ export const createFetchWithX402Tool = (config) => ({
     },
     handler: async (params) => {
         const { Tezos } = config;
-        const { url, maxAmountMutez, method = "GET", body, nftRecipientAddress } = params;
+        const { url, maxAmountMutez, method = "GET", body, queryParams } = params;
         const maxAmount = parseInt(maxAmountMutez, 10);
         if (isNaN(maxAmount) || maxAmount <= 0) {
             throw new Error(`Invalid maxAmountMutez: ${maxAmountMutez}. Must be a positive integer.`);
         }
-        // Build URL with recipient parameter if specified
+        // Build URL with query parameters if specified
         let requestUrl = url;
-        if (nftRecipientAddress) {
-            const urlObj = new URL(url);
-            urlObj.searchParams.set("recipient", nftRecipientAddress);
-            requestUrl = urlObj.toString();
+        if (queryParams) {
+            try {
+                const parsed = JSON.parse(queryParams);
+                if (typeof parsed === "object" && parsed !== null) {
+                    const urlObj = new URL(url);
+                    for (const [key, value] of Object.entries(parsed)) {
+                        urlObj.searchParams.set(key, String(value));
+                    }
+                    requestUrl = urlObj.toString();
+                }
+            }
+            catch {
+                throw new Error(`Invalid queryParams: must be a valid JSON object (e.g., '{"key": "value"}')`);
+            }
         }
         // Initial request config
         const axiosConfig = {
@@ -87,22 +97,21 @@ export const createFetchWithX402Tool = (config) => ({
             const maxFormatted = maxAmount / Math.pow(10, decimals);
             throw new Error(`Payment amount ${requiredFormatted} XTZ exceeds maximum allowed ${maxFormatted} XTZ`);
         }
-        // Get source address from signer
-        const source = await Tezos.signer.publicKeyHash();
-        // Validate source has sufficient funds
-        const sourceBalance = await Tezos.tz.getBalance(source);
-        if (sourceBalance.toNumber() < requiredAmount + 10000) { // Add buffer for fees
-            throw new Error(`Insufficient balance. ` +
-                `Required: ${requiredAmount + 10000} mutez (including fees), ` +
-                `Available: ${sourceBalance.toNumber()} mutez`);
+        // Validate contract has sufficient funds for the payment
+        const contractBalance = await Tezos.tz.getBalance(config.spendingContract);
+        if (contractBalance.toNumber() < requiredAmount) {
+            throw new Error(`Insufficient contract balance. ` +
+                `Required: ${requiredAmount} mutez, ` +
+                `Available: ${contractBalance.toNumber()} mutez`);
         }
         // Ensure account is revealed before signing
         await ensureRevealed(Tezos);
-        // Sign the payment using shared utility
+        // Sign the payment as a contract call to the spending wallet
         const signed = await signX402Payment(Tezos, {
             network: tezosRequirement.network,
             amount: requiredAmount,
             recipient: tezosRequirement.recipient,
+            spendingContract: config.spendingContract,
         });
         // Retry with payment header
         const paidConfig = {

package/dist/tools/index.d.ts

@@ -52,7 +52,7 @@ export declare const createTools: (liveConfig: LiveConfig, http: boolean) => ({
             maxAmountMutez: import("zod").ZodString;
             method: import("zod").ZodOptional<import("zod").ZodString>;
             body: import("zod").ZodOptional<import("zod").ZodString>;
-            nftRecipientAddress: import("zod").ZodOptional<import("zod").ZodString>;
+            queryParams: import("zod").ZodOptional<import("zod").ZodString>;
         }, import("zod/v4/core").$strip>;
         annotations: {
             readOnlyHint: boolean;

package/dist/tools/send_xtz.d.ts

@@ -1,5 +1,5 @@
 import z from "zod";
-import type { LiveConfig } from "../live-config.js";
+import { type LiveConfig } from "../live-config.js";
 export declare const createSendXtzTool: (config: LiveConfig) => {
     name: string;
     config: {

package/dist/tools/send_xtz.js

@@ -1,11 +1,10 @@
 import z from "zod";
 import { ensureRevealed } from "./reveal_account.js";
+import { calculateFeeRebate } from "../live-config.js";
 // Constants
 const MUTEZ_PER_TEZ = 1_000_000;
 const CONFIRMATIONS_TO_WAIT = 3;
 const TZKT_BASE_URL = "https://shadownet.tzkt.io";
-const SPENDER_TOP_UP_THRESHOLD = 250_000; // 0.25 XTZ
-const SPENDER_TOP_UP_TARGET = 500_000; // 0.5 XTZ
 // Types
 const inputSchema = z.object({
     toAddress: z.string().describe("The address to send Tez to."),
@@ -67,9 +66,7 @@ export const createSendXtzTool = (config) => ({
         await ensureRevealed(Tezos);
         // Top up spender from contract if balance is low
         const spenderMutez = spenderBalance.toNumber();
-        const feeRebate = spenderMutez < SPENDER_TOP_UP_THRESHOLD
-            ? SPENDER_TOP_UP_TARGET - spenderMutez
-            : 0;
+        const feeRebate = calculateFeeRebate(spenderMutez);
         const contract = await Tezos.contract.at(spendingContract);
         const contractCall = contract.methodsObject.spend({
             recipient: params.toAddress,

package/dist/tools/x402/sign.d.ts

@@ -4,6 +4,7 @@ export interface SignPaymentParams {
     network: string;
     amount: number;
     recipient: string;
+    spendingContract: string;
 }
 export interface SignedPayment {
     payload: X402PaymentPayload;

package/dist/tools/x402/sign.js

@@ -1,7 +1,8 @@
 import { OpKind } from "@taquito/taquito";
 import { LocalForger } from "@taquito/local-forging";
+import { calculateFeeRebate } from "../../live-config.js";
 export async function signX402Payment(Tezos, params) {
-    const { network, amount, recipient } = params;
+    const { network, amount, recipient, spendingContract } = params;
     // Get source address and public key from the signer
     let source;
     let publicKey;
@@ -24,6 +25,21 @@ export async function signX402Payment(Tezos, params) {
     if (!publicKey.startsWith('edpk') && !publicKey.startsWith('sppk') && !publicKey.startsWith('p2pk')) {
         throw new Error(`Invalid public key format: ${publicKey}`);
     }
+    // Calculate fee rebate to keep spender funded for gas
+    const spenderBalance = await Tezos.tz.getBalance(source);
+    const spenderMutez = spenderBalance.toNumber();
+    const feeRebate = calculateFeeRebate(spenderMutez);
+    // Build contract call via Taquito to get properly encoded parameters
+    const contract = await Tezos.contract.at(spendingContract);
+    const contractCall = contract.methodsObject.spend({
+        recipient,
+        amount,
+        fee_rebate: feeRebate,
+    });
+    // Estimate gas, storage, and fees
+    const estimate = await Tezos.estimate.contractCall(contractCall);
+    // Get the encoded parameters from the contract call
+    const transferParams = contractCall.toTransferParams();
     // Get the current block hash for the branch
     const block = await Tezos.rpc.getBlockHeader();
     const branch = block.hash;
@@ -33,19 +49,20 @@ export async function signX402Payment(Tezos, params) {
         throw new Error(`Failed to get contract info for ${source}. Account may not exist on chain.`);
     }
     const nextCounter = (parseInt(contractInfo.counter || "0") + 1).toString();
-    // Build the transfer operation
+    // Build the contract call operation (funds come from the contract, not the spender)
     const operation = {
         branch,
         contents: [
             {
                 kind: OpKind.TRANSACTION,
                 source,
-                fee: "1500",
+                fee: estimate.suggestedFeeMutez.toString(),
                 counter: nextCounter,
-                gas_limit: "1527",
-                storage_limit: "257",
-                amount: amount.toString(),
-                destination: recipient,
+                gas_limit: estimate.gasLimit.toString(),
+                storage_limit: estimate.storageLimit.toString(),
+                amount: "0",
+                destination: spendingContract,
+                parameters: transferParams.parameter,
             }
         ]
     };

package/dist/webserver.js

@@ -13,5 +13,29 @@ export const startWebServer = (port, apiRouter) => {
     // Static files + SPA fallback
     const distPath = join(__dirname, "../frontend/dist");
     app.use(sirv(distPath, { single: true }));
-    app.listen(port);
+    let retries = 0;
+    const maxRetries = 3;
+    const tryListen = () => {
+        const server = app.listen(port);
+        server.on("error", (err) => {
+            if (err.code === "EADDRINUSE" && retries < maxRetries) {
+                retries++;
+                console.error(`[tezosx-mcp] Port ${port} in use, retrying (${retries}/${maxRetries})...`);
+                setTimeout(tryListen, 500);
+            }
+            else if (err.code === "EADDRINUSE") {
+                console.error(`[tezosx-mcp] Port ${port} in use, frontend dashboard unavailable`);
+            }
+            else {
+                console.error(`[tezosx-mcp] Web server error:`, err.message);
+            }
+        });
+        server.on("listening", () => {
+            const shutdown = () => server.close();
+            process.on("SIGTERM", shutdown);
+            process.on("SIGINT", shutdown);
+            process.on("exit", shutdown);
+        });
+    };
+    tryListen();
 };