@ecadlabs/tezosx-mcp 1.0.0

package/dist/tools/index.js

@@ -0,0 +1,59 @@
+import { createCreateX402PaymentTool } from "./create_x402_payment.js";
+import { createFetchWithX402Tool } from "./fetch_with_x402.js";
+import { createGetAddressesTool } from "./get_addresses.js";
+import { createGetBalanceTool } from "./get_balance.js";
+import { createGetLimitsTool } from "./get_limits.js";
+import { createGetOperationHistoryTool } from "./get_operation_history.js";
+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)
+
+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`;
+const notConfiguredResponse = () => ({
+    content: [{
+            type: "text",
+            text: getNotConfiguredMessage()
+        }]
+});
+// Wraps a tool's handler to check config before execution
+const withConfigCheck = (tool, walletConfig) => ({
+    ...tool,
+    handler: async (...args) => {
+        if (!walletConfig) {
+            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 ?? '';
+    const tools = [
+        createCreateX402PaymentTool(Tezos),
+        createFetchWithX402Tool(Tezos),
+        createGetAddressesTool(Tezos, spendingContract),
+        createGetBalanceTool(Tezos, spendingContract, spendingAddress),
+        createGetLimitsTool(Tezos, spendingContract),
+        createGetOperationHistoryTool(spendingContract, tzktApi),
+        createParseX402RequirementsTool(),
+        createRevealAccountTool(Tezos),
+        createSendXtzTool(Tezos, spendingContract, spendingAddress),
+    ];
+    if (!http) {
+        tools.push(createGetDashboardTool(spendingContract));
+    }
+    // Wrap all tools with config check
+    return tools.map(tool => withConfigCheck(tool, walletConfig));
+};

package/dist/tools/parse_x402_requirements.d.ts

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

package/dist/tools/parse_x402_requirements.js

@@ -0,0 +1,66 @@
+import z from "zod";
+import { X402ResponseSchema } from "./x402/types.js";
+export const createParseX402RequirementsTool = () => ({
+    name: "tezos_parse_x402_requirements",
+    config: {
+        title: "Parse x402 Payment Requirements",
+        description: "Parses a 402 response body containing x402 payment requirements for Tezos payments. Returns structured payment information including scheme, network, asset, amount, and recipient.",
+        inputSchema: z.object({
+            responseBody: z.string().describe("The JSON response body from a 402 Payment Required response")
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        }
+    },
+    handler: async (params) => {
+        const { responseBody } = params;
+        try {
+            const parsed = JSON.parse(responseBody);
+            const validated = X402ResponseSchema.parse(parsed);
+            const tezosRequirements = validated.paymentRequirements.filter(req => req.scheme === 'exact-tezos');
+            if (tezosRequirements.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: "No Tezos payment requirements found in the response"
+                        }]
+                };
+            }
+            const formattedRequirements = tezosRequirements.map(req => {
+                const decimals = req.extra?.decimals ?? 6;
+                const amountInUnits = Number(req.amount) / Math.pow(10, decimals);
+                const assetName = req.extra?.name ?? req.asset;
+                return {
+                    network: req.network,
+                    asset: req.asset,
+                    assetName,
+                    amount: req.amount,
+                    amountFormatted: `${amountInUnits} ${assetName}`,
+                    recipient: req.recipient,
+                    decimals
+                };
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            x402Version: validated.x402Version,
+                            tezosPaymentRequirements: formattedRequirements
+                        }, null, 2)
+                    }]
+            };
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw new Error(`Invalid x402 response format: ${error.message}`);
+            }
+            if (error instanceof SyntaxError) {
+                throw new Error(`Invalid JSON: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+});

package/dist/tools/reveal_account.d.ts

@@ -0,0 +1,34 @@
+import { TezosToolkit } from "@taquito/taquito";
+import z from "zod";
+/**
+ * Check if an account is revealed on the Tezos network.
+ */
+export declare function isAccountRevealed(Tezos: TezosToolkit, address: string): Promise<boolean>;
+/**
+ * Reveal an account if not already revealed.
+ * Returns true if reveal was needed and performed, false if already revealed.
+ */
+export declare function ensureRevealed(Tezos: TezosToolkit): Promise<{
+    wasRevealed: boolean;
+    opHash?: string;
+}>;
+export declare const createRevealAccountTool: (Tezos: TezosToolkit) => {
+    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/reveal_account.js

@@ -0,0 +1,51 @@
+import z from "zod";
+/**
+ * Check if an account is revealed on the Tezos network.
+ */
+export async function isAccountRevealed(Tezos, address) {
+    const managerKey = await Tezos.rpc.getManagerKey(address);
+    return managerKey !== null;
+}
+/**
+ * Reveal an account if not already revealed.
+ * Returns true if reveal was needed and performed, false if already revealed.
+ */
+export async function ensureRevealed(Tezos) {
+    const address = await Tezos.signer.publicKeyHash();
+    const revealed = await isAccountRevealed(Tezos, address);
+    if (revealed) {
+        return { wasRevealed: false };
+    }
+    const op = await Tezos.contract.reveal({});
+    await op.confirmation(1);
+    return { wasRevealed: true, opHash: op.hash };
+}
+export const createRevealAccountTool = (Tezos) => ({
+    name: "tezos_reveal_account",
+    config: {
+        title: "Reveal Account",
+        description: "Reveals the spender account's public key on the Tezos network. This is required before the account can perform any operations. The tool checks if the account is already revealed and only performs the reveal operation if needed.",
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        }
+    },
+    handler: async () => {
+        const address = await Tezos.signer.publicKeyHash();
+        const result = await ensureRevealed(Tezos);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        message: result.wasRevealed ? `Account ${address} has been revealed` : `Account ${address} was already revealed`,
+                        operationHash: result.opHash,
+                        alreadyRevealed: !result.wasRevealed,
+                    }, null, 2)
+                }]
+        };
+    }
+});

package/dist/tools/send_xtz.d.ts

@@ -0,0 +1,32 @@
+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) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{
+            toAddress: z.ZodString;
+            amount: z.ZodNumber;
+        }, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: (params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};

package/dist/tools/send_xtz.js

@@ -0,0 +1,86 @@
+import z from "zod";
+// Constants
+const MUTEZ_PER_TEZ = 1_000_000;
+const CONFIRMATIONS_TO_WAIT = 3;
+const TZKT_BASE_URL = "https://shadownet.tzkt.io";
+// Types
+const inputSchema = z.object({
+    toAddress: z.string().describe("The address to send Tez to."),
+    amount: z.number().describe("The amount of Tez to send to the address."),
+});
+// Helper Functions
+/** Convert XTZ to mutez */
+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) => ({
+    name: "tezos_send_xtz",
+    config: {
+        title: "Send Tez",
+        description: "Sends a set amount of Tez to another address via the spending contract.",
+        inputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    },
+    handler: async (params) => {
+        params = params;
+        // Validate spender has funds for fees
+        const spenderBalance = await Tezos.tz.getBalance(spendingAddress);
+        if (spenderBalance.isZero()) {
+            throw new Error("Spending account balance is 0. " +
+                "Please fund the spending address to cover transaction fees.");
+        }
+        // Validate contract has funds for transfer
+        const contractBalance = await Tezos.tz.getBalance(spendingContract);
+        const amountMutez = xtzToMutez(params.amount);
+        if (contractBalance.toNumber() < amountMutez) {
+            throw new Error(`Insufficient contract balance. ` +
+                `Requested: ${formatMutez(amountMutez)}, ` +
+                `Available: ${formatMutez(contractBalance.toNumber())}`);
+        }
+        // Prepare contract call
+        const contract = await Tezos.contract.at(spendingContract);
+        const contractCall = contract.methodsObject.spend({
+            recipient: params.toAddress,
+            amount: amountMutez,
+        });
+        // Estimate fees
+        let estimate;
+        try {
+            estimate = await Tezos.estimate.contractCall(contractCall);
+        }
+        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())}) ` +
+                    `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) {
+            throw new Error(`Spender balance too low for fees. ` +
+                `Required: ${formatMutez(estimate.totalCost)}, ` +
+                `Available: ${formatMutez(spenderBalance.toNumber())}`);
+        }
+        // Execute transaction
+        const operation = await contractCall.send();
+        await operation.confirmation(CONFIRMATIONS_TO_WAIT);
+        const tzktUrl = `${TZKT_BASE_URL}/${operation.hash}`;
+        return {
+            content: [{ type: "text", text: tzktUrl }],
+        };
+    },
+});

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

@@ -0,0 +1,12 @@
+import { TezosToolkit } from "@taquito/taquito";
+import { X402PaymentPayload } from "./types.js";
+export interface SignPaymentParams {
+    network: string;
+    amount: number;
+    recipient: string;
+}
+export interface SignedPayment {
+    payload: X402PaymentPayload;
+    base64: string;
+}
+export declare function signX402Payment(Tezos: TezosToolkit, params: SignPaymentParams): Promise<SignedPayment>;

package/dist/tools/x402/sign.js

@@ -0,0 +1,76 @@
+import { OpKind } from "@taquito/taquito";
+import { LocalForger } from "@taquito/local-forging";
+export async function signX402Payment(Tezos, params) {
+    const { network, amount, recipient } = params;
+    // Get source address and public key from the signer
+    let source;
+    let publicKey;
+    try {
+        source = await Tezos.signer.publicKeyHash();
+    }
+    catch (error) {
+        throw new Error(`Failed to get source address from signer. Is SPENDING_PRIVATE_KEY set correctly? Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    try {
+        publicKey = await Tezos.signer.publicKey();
+    }
+    catch (error) {
+        throw new Error(`Failed to get public key from signer. Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    // Validate we got proper values
+    if (!source.startsWith('tz1') && !source.startsWith('tz2') && !source.startsWith('tz3')) {
+        throw new Error(`Invalid source address format: ${source}`);
+    }
+    if (!publicKey.startsWith('edpk') && !publicKey.startsWith('sppk') && !publicKey.startsWith('p2pk')) {
+        throw new Error(`Invalid public key format: ${publicKey}`);
+    }
+    // Get the current block hash for the branch
+    const block = await Tezos.rpc.getBlockHeader();
+    const branch = block.hash;
+    // Get the counter for the source account
+    const contractInfo = await Tezos.rpc.getContract(source);
+    if (!contractInfo) {
+        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
+    const operation = {
+        branch,
+        contents: [
+            {
+                kind: OpKind.TRANSACTION,
+                source,
+                fee: "1500",
+                counter: nextCounter,
+                gas_limit: "1527",
+                storage_limit: "257",
+                amount: amount.toString(),
+                destination: recipient,
+            }
+        ]
+    };
+    // Forge the operation using LocalForger
+    const forger = new LocalForger();
+    const forgedBytes = await forger.forge(operation);
+    // Sign the operation (with generic operation watermark 0x03)
+    const signature = await Tezos.signer.sign(forgedBytes, new Uint8Array([3]));
+    // Create x402 payload in the facilitator-compatible format
+    const payload = {
+        x402Version: 1,
+        scheme: "exact-tezos",
+        network,
+        asset: "XTZ",
+        payload: {
+            operationBytes: forgedBytes,
+            signature: signature.prefixSig,
+            publicKey,
+            source,
+        }
+    };
+    // Base64 encode the payload
+    const base64 = Buffer.from(JSON.stringify(payload)).toString("base64");
+    return {
+        payload,
+        base64,
+    };
+}

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

@@ -0,0 +1,40 @@
+import z from "zod";
+export declare const PaymentRequirementSchema: z.ZodObject<{
+    scheme: z.ZodString;
+    network: z.ZodString;
+    asset: z.ZodString;
+    amount: z.ZodString;
+    recipient: z.ZodString;
+    extra: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        decimals: z.ZodNumber;
+    }, z.z.core.$strip>>;
+}, z.z.core.$strip>;
+export declare const X402ResponseSchema: z.ZodObject<{
+    x402Version: z.ZodNumber;
+    paymentRequirements: z.ZodArray<z.ZodObject<{
+        scheme: z.ZodString;
+        network: z.ZodString;
+        asset: z.ZodString;
+        amount: z.ZodString;
+        recipient: z.ZodString;
+        extra: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            decimals: z.ZodNumber;
+        }, z.z.core.$strip>>;
+    }, z.z.core.$strip>>;
+}, z.z.core.$strip>;
+export type PaymentRequirement = z.infer<typeof PaymentRequirementSchema>;
+export type X402Response = z.infer<typeof X402ResponseSchema>;
+export interface X402PaymentPayload {
+    x402Version: number;
+    scheme: "exact-tezos";
+    network: string;
+    asset: "XTZ";
+    payload: {
+        operationBytes: string;
+        signature: string;
+        publicKey: string;
+        source: string;
+    };
+}

package/dist/tools/x402/types.js

@@ -0,0 +1,16 @@
+import z from "zod";
+export const PaymentRequirementSchema = z.object({
+    scheme: z.string(),
+    network: z.string(),
+    asset: z.string(),
+    amount: z.string(),
+    recipient: z.string(),
+    extra: z.object({
+        name: z.string(),
+        decimals: z.number()
+    }).optional()
+});
+export const X402ResponseSchema = z.object({
+    x402Version: z.number(),
+    paymentRequirements: z.array(PaymentRequirementSchema)
+});

package/dist/webserver.d.ts

@@ -0,0 +1 @@
+export declare const startWebServer: (port: number) => void;

package/dist/webserver.js

@@ -0,0 +1,10 @@
+import { createServer } from "http";
+import { fileURLToPath } from "url";
+import { join } from "path";
+import sirv from "sirv";
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+export const startWebServer = (port) => {
+    const distPath = join(__dirname, "../frontend/dist");
+    const serve = sirv(distPath, { single: true });
+    createServer(serve).listen(port);
+};