@ecadlabs/tezosx-mcp 1.0.0

package/dist/tools/fetch_with_x402.js

@@ -0,0 +1,143 @@
+import z from "zod";
+import axios from "axios";
+import { X402ResponseSchema } from "./x402/types.js";
+import { signX402Payment } from "./x402/sign.js";
+import { ensureRevealed } from "./reveal_account.js";
+export const createFetchWithX402Tool = (Tezos) => ({
+    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. IMPORTANT: For NFT minting endpoints, always set 'recipient' to the user's wallet address so they receive the NFT (not the spending 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"),
+            recipient: z.string().optional().describe("Address to receive any minted assets (NFTs). IMPORTANT: For /mint endpoints, set this to the user's wallet address. If omitted, defaults to the spending account (payer), which is usually not desired."),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        }
+    },
+    handler: async (params) => {
+        const { url, maxAmountMutez, method = "GET", body, recipient } = 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
+        let requestUrl = url;
+        if (recipient) {
+            const urlObj = new URL(url);
+            urlObj.searchParams.set("recipient", recipient);
+            requestUrl = urlObj.toString();
+        }
+        // Initial request config
+        const axiosConfig = {
+            method,
+            url: requestUrl,
+            headers: { "Content-Type": "application/json" },
+            validateStatus: () => true, // Don't throw on any status code
+        };
+        if (body && (method === "POST" || method === "PUT")) {
+            axiosConfig.data = body;
+        }
+        const initialResponse = await axios(axiosConfig);
+        // If not 402, return the response directly
+        if (initialResponse.status !== 402) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            status: initialResponse.status,
+                            statusText: initialResponse.statusText,
+                            paymentMade: false,
+                            body: typeof initialResponse.data === 'string'
+                                ? initialResponse.data
+                                : JSON.stringify(initialResponse.data)
+                        }, null, 2)
+                    }]
+            };
+        }
+        // Parse 402 response
+        let x402Response;
+        try {
+            const responseData = typeof initialResponse.data === 'string'
+                ? JSON.parse(initialResponse.data)
+                : initialResponse.data;
+            x402Response = X402ResponseSchema.parse(responseData);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse x402 response: ${error instanceof Error ? error.message : error}`);
+        }
+        // Find Tezos payment requirement
+        const tezosRequirement = x402Response.paymentRequirements.find(req => req.scheme === "exact-tezos");
+        if (!tezosRequirement) {
+            throw new Error("No Tezos payment option available in x402 response");
+        }
+        const requiredAmount = parseInt(tezosRequirement.amount, 10);
+        // Check if amount is within limit
+        if (requiredAmount > maxAmount) {
+            const decimals = tezosRequirement.extra?.decimals ?? 6;
+            const requiredFormatted = requiredAmount / Math.pow(10, decimals);
+            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`);
+        }
+        // Ensure account is revealed before signing
+        await ensureRevealed(Tezos);
+        // Sign the payment using shared utility
+        const signed = await signX402Payment(Tezos, {
+            network: tezosRequirement.network,
+            amount: requiredAmount,
+            recipient: tezosRequirement.recipient,
+        });
+        // Retry with payment header
+        const paidConfig = {
+            ...axiosConfig,
+            headers: {
+                ...axiosConfig.headers,
+                "X-PAYMENT": signed.base64,
+            },
+        };
+        let paidResponse;
+        try {
+            paidResponse = await axios(paidConfig);
+        }
+        catch (error) {
+            throw new Error(`Payment signed but request failed: ${error instanceof Error ? error.message : error}`);
+        }
+        const decimals = tezosRequirement.extra?.decimals ?? 6;
+        const amountFormatted = requiredAmount / Math.pow(10, decimals);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        status: paidResponse.status,
+                        statusText: paidResponse.statusText,
+                        paymentMade: true,
+                        paymentDetails: {
+                            amount: tezosRequirement.amount,
+                            amountFormatted: `${amountFormatted} XTZ`,
+                            recipient: tezosRequirement.recipient,
+                            network: tezosRequirement.network,
+                        },
+                        body: typeof paidResponse.data === 'string'
+                            ? paidResponse.data
+                            : JSON.stringify(paidResponse.data)
+                    }, null, 2)
+                }]
+        };
+    }
+});

package/dist/tools/get_address.d.ts

@@ -0,0 +1,20 @@
+import { TezosToolkit } from "@taquito/taquito";
+import z from "zod";
+export declare const createGetAddressTool: (Tezos: TezosToolkit) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{}, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+        };
+    };
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/get_address.js

@@ -0,0 +1,24 @@
+import z from "zod";
+export const createGetAddressTool = (Tezos) => ({
+    name: "tezos_get_address",
+    config: {
+        title: "Get Tezos Address",
+        description: "Returns the currently configured Tezos address",
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false
+        }
+    },
+    handler: async () => {
+        try {
+            const address = await Tezos.signer.publicKeyHash();
+            return {
+                content: [{ type: "text", text: address }]
+            };
+        }
+        catch {
+            throw new ReferenceError("Failed to get public key from signer.");
+        }
+    }
+});

package/dist/tools/get_addresses.d.ts

@@ -0,0 +1,22 @@
+import { TezosToolkit } from "@taquito/taquito";
+import z from "zod";
+export declare const createGetAddressesTool: (Tezos: TezosToolkit, spendingContract: string) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{}, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/get_addresses.js

@@ -0,0 +1,32 @@
+import z from "zod";
+export const createGetAddressesTool = (Tezos, spendingContract) => ({
+    name: "tezos_get_addresses",
+    config: {
+        title: "Get Tezos Addresses",
+        description: "Returns the spending contract address, owner address, and spender address from the contract storage.",
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    handler: async () => {
+        const contract = await Tezos.contract.at(spendingContract);
+        const storage = (await contract.storage());
+        const result = {
+            contractAddress: spendingContract,
+            ownerAddress: storage.owner,
+            spenderAddress: storage.spender,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+});

package/dist/tools/get_balance.d.ts

@@ -0,0 +1,22 @@
+import { TezosToolkit } from "@taquito/taquito";
+import z from "zod";
+export declare const createGetBalanceTool: (Tezos: TezosToolkit, spendingContract: string, spendingAddress: string) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{}, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/get_balance.js

@@ -0,0 +1,27 @@
+import z from "zod";
+export const createGetBalanceTool = (Tezos, spendingContract, spendingAddress) => ({
+    name: "tezos_get_balance",
+    config: {
+        title: "Get Balances",
+        description: "Returns the balance of the spending contract (usable tokens) and spending address (tokens for fees)",
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        }
+    },
+    handler: async () => {
+        try {
+            const spendingAddressBalance = (await Tezos.tz.getBalance(spendingAddress)).toString();
+            const spendingContractBalance = (await Tezos.tz.getBalance(spendingContract)).toString();
+            return {
+                content: [{ type: "text", text: `Spending address balance: ${spendingAddressBalance} mutez. Spending contract balance: ${spendingContractBalance} mutez` }]
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to get balance: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+});

package/dist/tools/get_dashboard.d.ts

@@ -0,0 +1,21 @@
+import z from "zod";
+export declare const createGetDashboardTool: (spendingContract: string) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{}, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/get_dashboard.js

@@ -0,0 +1,29 @@
+import z from "zod";
+import { DEFAULT_WEB_PORT } from '../index.js';
+export const createGetDashboardTool = (spendingContract) => ({
+    name: "tezos_get_dashboard",
+    config: {
+        title: "Get Contract Dashboard",
+        description: "Returns a link to the dashboard where the user can configure their contracts spending limits, spending keys, and deploy a new spending contract.",
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    handler: async () => {
+        const port = process.env.WEB_PORT || DEFAULT_WEB_PORT;
+        const network = process.env.TEZOS_NETWORK || 'shadownet';
+        const url = `http://localhost:${port}?contract=${spendingContract}&network=${network}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: url,
+                },
+            ],
+        };
+    },
+});

package/dist/tools/get_limits.d.ts

@@ -0,0 +1,22 @@
+import { TezosToolkit } from "@taquito/taquito";
+import z from "zod";
+export declare const createGetLimitsTool: (Tezos: TezosToolkit, spendingContract: string) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{}, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/get_limits.js

@@ -0,0 +1,61 @@
+import z from "zod";
+// Constants
+const MUTEZ_PER_TEZ = 1_000_000;
+/** Convert mutez to XTZ */
+const mutezToXtz = (mutez) => mutez / MUTEZ_PER_TEZ;
+export const createGetLimitsTool = (Tezos, spendingContract) => ({
+    name: "tezos_get_limits",
+    config: {
+        title: "Get Spending Limits",
+        description: "Returns the spending limits and current usage from the contract: daily limit, per-transaction limit, amount spent today, and time until reset.",
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    },
+    handler: async () => {
+        const contract = await Tezos.contract.at(spendingContract);
+        const storage = (await contract.storage());
+        const dailyLimitMutez = storage.daily_limit.toNumber();
+        const perTxLimitMutez = storage.per_tx_limit.toNumber();
+        const spentTodayMutez = storage.spent_today.toNumber();
+        const lastReset = new Date(storage.last_reset);
+        // Calculate time until next reset (24 hours from last_reset)
+        const nextReset = new Date(lastReset.getTime() + 24 * 60 * 60 * 1000);
+        const now = new Date();
+        const msUntilReset = Math.max(0, nextReset.getTime() - now.getTime());
+        const hoursUntilReset = Math.floor(msUntilReset / (1000 * 60 * 60));
+        const minutesUntilReset = Math.floor((msUntilReset % (1000 * 60 * 60)) / (1000 * 60));
+        const result = {
+            dailyLimit: {
+                xtz: mutezToXtz(dailyLimitMutez),
+                mutez: dailyLimitMutez,
+            },
+            perTransactionLimit: {
+                xtz: mutezToXtz(perTxLimitMutez),
+                mutez: perTxLimitMutez,
+            },
+            spentToday: {
+                xtz: mutezToXtz(spentTodayMutez),
+                mutez: spentTodayMutez,
+            },
+            remainingDaily: {
+                xtz: mutezToXtz(Math.max(0, dailyLimitMutez - spentTodayMutez)),
+                mutez: Math.max(0, dailyLimitMutez - spentTodayMutez),
+            },
+            lastReset: storage.last_reset,
+            timeUntilReset: `${hoursUntilReset}h ${minutesUntilReset}m`,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    },
+});

package/dist/tools/get_operation_history.d.ts

@@ -0,0 +1,21 @@
+import z from "zod";
+export declare const createGetOperationHistoryTool: (spendingContract: string, tzktApi: string) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{}, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/get_operation_history.js

@@ -0,0 +1,58 @@
+import axios from "axios";
+import z from "zod";
+export const createGetOperationHistoryTool = (spendingContract, tzktApi) => ({
+    name: "tezos_get_operation_history",
+    config: {
+        title: "Get Operation History",
+        description: "Returns the last 100 transaction operations for the spending contract from TzKT API, ordered from most recent to oldest.",
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    },
+    handler: async () => {
+        try {
+            const url = `${tzktApi}/v1/accounts/${spendingContract}/operations?type=transaction&limit=100`;
+            const response = await axios.get(url);
+            const allOperations = response.data;
+            // Filter to only incoming/outgoing transfers, exclude spend calls
+            const operations = allOperations.filter((op) => {
+                const entrypoint = op.parameter?.entrypoint;
+                const isSpendCall = op.target.address === spendingContract && entrypoint === "spend";
+                const isOutgoing = op.sender.address === spendingContract;
+                const isIncoming = op.target.address === spendingContract && !isSpendCall;
+                return isIncoming || isOutgoing;
+            });
+            if (operations.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No transaction history found for contract ${spendingContract}`,
+                        },
+                    ],
+                };
+            }
+            const formattedOperations = operations.map((op, index) => {
+                const amount = (op.amount / 1_000_000).toFixed(6);
+                const date = new Date(op.timestamp).toISOString();
+                const direction = op.sender.address === spendingContract ? "OUT" : "IN";
+                return `${index + 1}. [${direction}] [${date}] ${op.hash}
+   From: ${op.sender.address}
+   To: ${op.target.address}
+   Amount: ${amount} XTZ
+   Status: ${op.status}`;
+            });
+            const summary = `Operation history for ${spendingContract} (${operations.length} transactions):\n\n${formattedOperations.join("\n\n")}`;
+            return {
+                content: [{ type: "text", text: summary }],
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to fetch operation history: ${error instanceof Error ? error.message : error}`);
+        }
+    },
+});

package/dist/tools/index.d.ts

@@ -0,0 +1,113 @@
+import { WalletConfig } from "../index.js";
+export declare const createTools: (walletConfig: WalletConfig, tzktApi: string, http: boolean) => ({
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: import("zod").ZodObject<{
+            network: import("zod").ZodString;
+            asset: import("zod").ZodString;
+            amount: import("zod").ZodString;
+            recipient: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: (params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+} | {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: import("zod").ZodObject<{}, import("zod/v4/core").$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: () => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+} | {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: import("zod").ZodObject<{
+            url: import("zod").ZodString;
+            maxAmountMutez: import("zod").ZodString;
+            method: import("zod").ZodOptional<import("zod").ZodString>;
+            body: import("zod").ZodOptional<import("zod").ZodString>;
+            recipient: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: (params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+} | {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: import("zod").ZodObject<{
+            responseBody: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: (params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+} | {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: import("zod").ZodObject<{
+            toAddress: import("zod").ZodString;
+            amount: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: (params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+})[];