@ecadlabs/tezosx-mcp 1.0.0 → 1.0.1

package/dist/tools/fetch_with_x402.d.ts

@@ -1,6 +1,6 @@
-import { TezosToolkit } from "@taquito/taquito";
 import z from "zod";
-export declare const createFetchWithX402Tool: (Tezos: TezosToolkit) => {
+import type { LiveConfig } from "../live-config.js";
+export declare const createFetchWithX402Tool: (config: LiveConfig) => {
     name: string;
     config: {
         title: string;
@@ -10,7 +10,7 @@ export declare const createFetchWithX402Tool: (Tezos: TezosToolkit) => {
             maxAmountMutez: z.ZodString;
             method: z.ZodOptional<z.ZodString>;
             body: z.ZodOptional<z.ZodString>;
-            recipient: z.ZodOptional<z.ZodString>;
+            nftRecipientAddress: z.ZodOptional<z.ZodString>;
         }, z.z.core.$strip>;
         annotations: {
             readOnlyHint: boolean;

package/dist/tools/fetch_with_x402.js

@@ -3,17 +3,17 @@ 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) => ({
+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. IMPORTANT: For NFT minting endpoints, always set 'recipient' to the user's wallet address so they receive the NFT (not the spending account).",
+        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.",
         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."),
+            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."),
         }),
         annotations: {
             readOnlyHint: false,
@@ -23,16 +23,17 @@ export const createFetchWithX402Tool = (Tezos) => ({
         }
     },
     handler: async (params) => {
-        const { url, maxAmountMutez, method = "GET", body, recipient } = params;
+        const { Tezos } = config;
+        const { url, maxAmountMutez, method = "GET", body, nftRecipientAddress } = 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) {
+        if (nftRecipientAddress) {
             const urlObj = new URL(url);
-            urlObj.searchParams.set("recipient", recipient);
+            urlObj.searchParams.set("recipient", nftRecipientAddress);
             requestUrl = urlObj.toString();
         }
         // Initial request config

package/dist/tools/get_addresses.d.ts

@@ -1,6 +1,6 @@
-import { TezosToolkit } from "@taquito/taquito";
 import z from "zod";
-export declare const createGetAddressesTool: (Tezos: TezosToolkit, spendingContract: string) => {
+import type { LiveConfig } from "../live-config.js";
+export declare const createGetAddressesTool: (config: LiveConfig) => {
     name: string;
     config: {
         title: string;

package/dist/tools/get_addresses.js

@@ -1,5 +1,5 @@
 import z from "zod";
-export const createGetAddressesTool = (Tezos, spendingContract) => ({
+export const createGetAddressesTool = (config) => ({
     name: "tezos_get_addresses",
     config: {
         title: "Get Tezos Addresses",
@@ -13,6 +13,7 @@ export const createGetAddressesTool = (Tezos, spendingContract) => ({
         },
     },
     handler: async () => {
+        const { Tezos, spendingContract } = config;
         const contract = await Tezos.contract.at(spendingContract);
         const storage = (await contract.storage());
         const result = {

package/dist/tools/get_balance.d.ts

@@ -1,6 +1,6 @@
-import { TezosToolkit } from "@taquito/taquito";
 import z from "zod";
-export declare const createGetBalanceTool: (Tezos: TezosToolkit, spendingContract: string, spendingAddress: string) => {
+import type { LiveConfig } from "../live-config.js";
+export declare const createGetBalanceTool: (config: LiveConfig) => {
     name: string;
     config: {
         title: string;

package/dist/tools/get_balance.js

@@ -1,5 +1,5 @@
 import z from "zod";
-export const createGetBalanceTool = (Tezos, spendingContract, spendingAddress) => ({
+export const createGetBalanceTool = (config) => ({
     name: "tezos_get_balance",
     config: {
         title: "Get Balances",
@@ -14,6 +14,7 @@ export const createGetBalanceTool = (Tezos, spendingContract, spendingAddress) =
     },
     handler: async () => {
         try {
+            const { Tezos, spendingContract, spendingAddress } = config;
             const spendingAddressBalance = (await Tezos.tz.getBalance(spendingAddress)).toString();
             const spendingContractBalance = (await Tezos.tz.getBalance(spendingContract)).toString();
             return {

package/dist/tools/get_dashboard.d.ts

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

package/dist/tools/get_dashboard.js

@@ -1,6 +1,6 @@
 import z from "zod";
 import { DEFAULT_WEB_PORT } from '../index.js';
-export const createGetDashboardTool = (spendingContract) => ({
+export const createGetDashboardTool = (config) => ({
     name: "tezos_get_dashboard",
     config: {
         title: "Get Contract Dashboard",
@@ -16,7 +16,7 @@ export const createGetDashboardTool = (spendingContract) => ({
     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}`;
+        const url = `http://localhost:${port}?contract=${config.spendingContract}&network=${network}`;
         return {
             content: [
                 {

package/dist/tools/get_limits.d.ts

@@ -1,6 +1,6 @@
-import { TezosToolkit } from "@taquito/taquito";
 import z from "zod";
-export declare const createGetLimitsTool: (Tezos: TezosToolkit, spendingContract: string) => {
+import type { LiveConfig } from "../live-config.js";
+export declare const createGetLimitsTool: (config: LiveConfig) => {
     name: string;
     config: {
         title: string;

package/dist/tools/get_limits.js

@@ -3,7 +3,7 @@ import z from "zod";
 const MUTEZ_PER_TEZ = 1_000_000;
 /** Convert mutez to XTZ */
 const mutezToXtz = (mutez) => mutez / MUTEZ_PER_TEZ;
-export const createGetLimitsTool = (Tezos, spendingContract) => ({
+export const createGetLimitsTool = (config) => ({
     name: "tezos_get_limits",
     config: {
         title: "Get Spending Limits",
@@ -17,6 +17,7 @@ export const createGetLimitsTool = (Tezos, spendingContract) => ({
         },
     },
     handler: async () => {
+        const { Tezos, spendingContract } = config;
         const contract = await Tezos.contract.at(spendingContract);
         const storage = (await contract.storage());
         const dailyLimitMutez = storage.daily_limit.toNumber();

package/dist/tools/get_operation_history.d.ts

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

package/dist/tools/get_operation_history.js

@@ -1,6 +1,6 @@
 import axios from "axios";
 import z from "zod";
-export const createGetOperationHistoryTool = (spendingContract, tzktApi) => ({
+export const createGetOperationHistoryTool = (config) => ({
     name: "tezos_get_operation_history",
     config: {
         title: "Get Operation History",
@@ -15,6 +15,7 @@ export const createGetOperationHistoryTool = (spendingContract, tzktApi) => ({
     },
     handler: async () => {
         try {
+            const { spendingContract, tzktApi } = config;
             const url = `${tzktApi}/v1/accounts/${spendingContract}/operations?type=transaction&limit=100`;
             const response = await axios.get(url);
             const allOperations = response.data;

package/dist/tools/index.d.ts

@@ -1,5 +1,5 @@
-import { WalletConfig } from "../index.js";
-export declare const createTools: (walletConfig: WalletConfig, tzktApi: string, http: boolean) => ({
+import type { LiveConfig } from "../live-config.js";
+export declare const createTools: (liveConfig: LiveConfig, http: boolean) => ({
     name: string;
     config: {
         title: string;
@@ -52,7 +52,7 @@ export declare const createTools: (walletConfig: WalletConfig, tzktApi: string,
             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>;
+            nftRecipientAddress: import("zod").ZodOptional<import("zod").ZodString>;
         }, import("zod/v4/core").$strip>;
         annotations: {
             readOnlyHint: boolean;

package/dist/tools/index.js

@@ -8,16 +8,12 @@ import { createParseX402RequirementsTool } from "./parse_x402_requirements.js";
 import { createRevealAccountTool } from "./reveal_account.js";
 import { createSendXtzTool } from "./send_xtz.js";
 import { createGetDashboardTool } from "./get_dashboard.js";
-const getNotConfiguredMessage = () => `Wallet not configured. Please set the following environment variables and restart the MCP server:
-
-1. SPENDING_PRIVATE_KEY - Your spending key (starts with edsk, spsk, or p2sk)
-2. SPENDING_CONTRACT - Your spending contract address (starts with KT1)
+const getNotConfiguredMessage = () => `Wallet not configured.
 
 To get started:
 1. Open the dashboard at http://localhost:${process.env.WEB_PORT || '13205'}
 2. Connect your wallet and deploy a spending contract
-3. Add the environment variables to your MCP client configuration
-4. Restart the MCP server`;
+3. The MCP server will be configured automatically — no manual setup needed`;
 const notConfiguredResponse = () => ({
     content: [{
             type: "text",
@@ -25,35 +21,30 @@ const notConfiguredResponse = () => ({
         }]
 });
 // Wraps a tool's handler to check config before execution
-const withConfigCheck = (tool, walletConfig) => ({
+const withConfigCheck = (tool, liveConfig) => ({
     ...tool,
     handler: async (...args) => {
-        if (!walletConfig) {
+        if (!liveConfig.configured) {
             return notConfiguredResponse();
         }
         return tool.handler(...args);
     }
 });
-export const createTools = (walletConfig, tzktApi, http) => {
-    // Create a mock Tezos toolkit for tool creation when config is missing
-    // The actual handlers will be blocked by withConfigCheck
-    const Tezos = walletConfig?.Tezos ?? {};
-    const spendingContract = walletConfig?.spendingContract ?? '';
-    const spendingAddress = walletConfig?.spendingAddress ?? '';
+export const createTools = (liveConfig, http) => {
     const tools = [
-        createCreateX402PaymentTool(Tezos),
-        createFetchWithX402Tool(Tezos),
-        createGetAddressesTool(Tezos, spendingContract),
-        createGetBalanceTool(Tezos, spendingContract, spendingAddress),
-        createGetLimitsTool(Tezos, spendingContract),
-        createGetOperationHistoryTool(spendingContract, tzktApi),
+        createCreateX402PaymentTool(liveConfig),
+        createFetchWithX402Tool(liveConfig),
+        createGetAddressesTool(liveConfig),
+        createGetBalanceTool(liveConfig),
+        createGetLimitsTool(liveConfig),
+        createGetOperationHistoryTool(liveConfig),
         createParseX402RequirementsTool(),
-        createRevealAccountTool(Tezos),
-        createSendXtzTool(Tezos, spendingContract, spendingAddress),
+        createRevealAccountTool(liveConfig),
+        createSendXtzTool(liveConfig),
     ];
     if (!http) {
-        tools.push(createGetDashboardTool(spendingContract));
+        tools.push(createGetDashboardTool(liveConfig));
     }
     // Wrap all tools with config check
-    return tools.map(tool => withConfigCheck(tool, walletConfig));
+    return tools.map(tool => withConfigCheck(tool, liveConfig));
 };

package/dist/tools/reveal_account.d.ts

@@ -1,5 +1,6 @@
 import { TezosToolkit } from "@taquito/taquito";
 import z from "zod";
+import type { LiveConfig } from "../live-config.js";
 /**
  * Check if an account is revealed on the Tezos network.
  */
@@ -12,7 +13,7 @@ export declare function ensureRevealed(Tezos: TezosToolkit): Promise<{
     wasRevealed: boolean;
     opHash?: string;
 }>;
-export declare const createRevealAccountTool: (Tezos: TezosToolkit) => {
+export declare const createRevealAccountTool: (config: LiveConfig) => {
     name: string;
     config: {
         title: string;

package/dist/tools/reveal_account.js

@@ -20,7 +20,7 @@ export async function ensureRevealed(Tezos) {
     await op.confirmation(1);
     return { wasRevealed: true, opHash: op.hash };
 }
-export const createRevealAccountTool = (Tezos) => ({
+export const createRevealAccountTool = (config) => ({
     name: "tezos_reveal_account",
     config: {
         title: "Reveal Account",
@@ -34,6 +34,7 @@ export const createRevealAccountTool = (Tezos) => ({
         }
     },
     handler: async () => {
+        const { Tezos } = config;
         const address = await Tezos.signer.publicKeyHash();
         const result = await ensureRevealed(Tezos);
         return {

package/dist/tools/send_xtz.d.ts

@@ -1,13 +1,6 @@
-import { TezosToolkit } from "@taquito/taquito";
 import z from "zod";
-/**
- * MCP tool for sending XTZ via a spending contract.
- *
- * @param Tezos - Configured TezosToolkit instance (with signer set to spender key)
- * @param spendingContract - Address of the spending-limited wallet contract
- * @param spendingAddress - Address of the spender account (for fee payments)
- */
-export declare const createSendXtzTool: (Tezos: TezosToolkit, spendingContract: string, spendingAddress: string) => {
+import type { LiveConfig } from "../live-config.js";
+export declare const createSendXtzTool: (config: LiveConfig) => {
     name: string;
     config: {
         title: string;

package/dist/tools/send_xtz.js

@@ -1,8 +1,11 @@
 import z from "zod";
+import { ensureRevealed } from "./reveal_account.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."),
@@ -13,14 +16,9 @@ const inputSchema = z.object({
 const xtzToMutez = (xtz) => xtz * MUTEZ_PER_TEZ;
 /** Format mutez for display */
 const formatMutez = (mutez) => `${mutez} mutez`;
-/**
- * MCP tool for sending XTZ via a spending contract.
- *
- * @param Tezos - Configured TezosToolkit instance (with signer set to spender key)
- * @param spendingContract - Address of the spending-limited wallet contract
- * @param spendingAddress - Address of the spender account (for fee payments)
- */
-export const createSendXtzTool = (Tezos, spendingContract, spendingAddress) => ({
+// Cache the last-verified spender so we only hit the chain when config changes
+let verifiedSpender = null;
+export const createSendXtzTool = (config) => ({
     name: "tezos_send_xtz",
     config: {
         title: "Send Tez",
@@ -35,6 +33,21 @@ export const createSendXtzTool = (Tezos, spendingContract, spendingAddress) => (
     },
     handler: async (params) => {
         params = params;
+        const { Tezos, spendingContract, spendingAddress } = config;
+        // Verify the server's signer matches the on-chain spender (only when config changes)
+        const needsVerify = !verifiedSpender
+            || verifiedSpender.address !== spendingAddress
+            || verifiedSpender.contract !== spendingContract;
+        if (needsVerify) {
+            const c = await Tezos.contract.at(spendingContract);
+            const storage = await c.storage();
+            if (storage.spender !== spendingAddress) {
+                throw new Error(`Spender mismatch: the server's signing key (${spendingAddress}) does not match ` +
+                    `the contract's spender (${storage.spender}). ` +
+                    `Please regenerate the spender key from the dashboard.`);
+            }
+            verifiedSpender = { address: spendingAddress, contract: spendingContract };
+        }
         // Validate spender has funds for fees
         const spenderBalance = await Tezos.tz.getBalance(spendingAddress);
         if (spenderBalance.isZero()) {
@@ -49,11 +62,19 @@ export const createSendXtzTool = (Tezos, spendingContract, spendingAddress) => (
                 `Requested: ${formatMutez(amountMutez)}, ` +
                 `Available: ${formatMutez(contractBalance.toNumber())}`);
         }
-        // Prepare contract call
+        // Taquito auto-reveals on send(), but the estimate step below
+        // simulates via RPC without handling revelation — so we reveal first.
+        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 contract = await Tezos.contract.at(spendingContract);
         const contractCall = contract.methodsObject.spend({
             recipient: params.toAddress,
             amount: amountMutez,
+            fee_rebate: feeRebate,
         });
         // Estimate fees
         let estimate;
@@ -63,19 +84,16 @@ export const createSendXtzTool = (Tezos, spendingContract, spendingAddress) => (
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             if (message.includes("balance_too_low")) {
-                throw new Error(`Spender balance (${formatMutez(spenderBalance.toNumber())}) ` +
+                throw new Error(`Spender balance (${formatMutez(spenderMutez)}) ` +
                     `is too low to cover fees. Please fund the spending address.`);
             }
             throw err;
         }
-        // Run another fee check because the first check is only estimating the fees, but still needs tez in the account to estimate.
-        // This check is checking against the actual estimated fee value.
-        if (spenderBalance.toNumber() < estimate.totalCost) {
+        if (spenderMutez < estimate.totalCost) {
             throw new Error(`Spender balance too low for fees. ` +
                 `Required: ${formatMutez(estimate.totalCost)}, ` +
-                `Available: ${formatMutez(spenderBalance.toNumber())}`);
+                `Available: ${formatMutez(spenderMutez)}`);
         }
-        // Execute transaction
         const operation = await contractCall.send();
         await operation.confirmation(CONFIRMATIONS_TO_WAIT);
         const tzktUrl = `${TZKT_BASE_URL}/${operation.hash}`;

package/dist/webserver.d.ts

@@ -1 +1,2 @@
-export declare const startWebServer: (port: number) => void;
+import { type Router } from "express";
+export declare const startWebServer: (port: number, apiRouter?: Router) => void;

package/dist/webserver.js

@@ -1,10 +1,17 @@
-import { createServer } from "http";
+import express from "express";
 import { fileURLToPath } from "url";
 import { join } from "path";
 import sirv from "sirv";
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
-export const startWebServer = (port) => {
+export const startWebServer = (port, apiRouter) => {
+    const app = express();
+    app.use(express.json());
+    // API routes (config endpoints)
+    if (apiRouter) {
+        app.use(apiRouter);
+    }
+    // Static files + SPA fallback
     const distPath = join(__dirname, "../frontend/dist");
-    const serve = sirv(distPath, { single: true });
-    createServer(serve).listen(port);
+    app.use(sirv(distPath, { single: true }));
+    app.listen(port);
 };