@ecadlabs/tezosx-mcp 1.0.0

package/dist/adapters/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Environment adapter interface for abstracting platform-specific operations.
+ * This allows the MCP server to run in both Node.js and Cloudflare Workers environments.
+ */
+export interface EnvConfig {
+    MCP_TRANSPORT?: string;
+    SKIP_FRONTEND?: string;
+    WEB_PORT?: string;
+    PORT?: string;
+    TEZOS_NETWORK?: string;
+    SPENDING_PRIVATE_KEY?: string;
+    SPENDING_CONTRACT?: string;
+}
+export interface EnvironmentAdapter {
+    /**
+     * Get environment variable value
+     */
+    getEnv(key: keyof EnvConfig): string | undefined;
+    /**
+     * Check if we're running in a Workers environment
+     */
+    isWorker(): boolean;
+    /**
+     * Base64 encode a string (Buffer.from in Node, btoa in Workers)
+     */
+    base64Encode(data: string): string;
+    /**
+     * Base64 decode a string
+     */
+    base64Decode(data: string): string;
+    /**
+     * Log a message (stderr in Node, console.log in Workers)
+     */
+    log(message: string): void;
+}
+/**
+ * Static file serving configuration for HTTP mode
+ */
+export interface StaticFileConfig {
+    /** Path to serve static files from (Node.js only) */
+    staticPath?: string;
+    /** Whether to use SPA fallback (serve index.html for unknown routes) */
+    spaFallback?: boolean;
+}
+/**
+ * Runtime environment type
+ */
+export type RuntimeEnvironment = 'node' | 'worker';
+/**
+ * Detect the current runtime environment
+ */
+export declare function detectEnvironment(): RuntimeEnvironment;

package/dist/adapters/types.js

@@ -0,0 +1,25 @@
+/**
+ * Environment adapter interface for abstracting platform-specific operations.
+ * This allows the MCP server to run in both Node.js and Cloudflare Workers environments.
+ */
+/**
+ * Detect the current runtime environment
+ */
+export function detectEnvironment() {
+    // Check for Cloudflare Workers-specific globals
+    // @ts-ignore - caches is a Workers global
+    if (typeof globalThis.caches !== 'undefined' && typeof globalThis.caches.default !== 'undefined') {
+        return 'worker';
+    }
+    // Check for other Workers indicators
+    // @ts-ignore - WorkerGlobalScope is a Workers type
+    if (typeof WorkerGlobalScope !== 'undefined') {
+        return 'worker';
+    }
+    // Check for Node.js process
+    if (typeof process !== 'undefined' && process.versions?.node) {
+        return 'node';
+    }
+    // Default to worker if we can't determine (safer for bundled code)
+    return 'worker';
+}

package/dist/adapters/worker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Cloudflare Workers environment adapter
+ * Uses Web APIs and Worker bindings instead of Node.js filesystem/process
+ */
+import type { EnvironmentAdapter, EnvConfig } from './types.js';
+/**
+ * Cloudflare Worker environment bindings type
+ * These are passed to the fetch handler by Cloudflare
+ */
+export interface WorkerEnv {
+    MCP_TRANSPORT?: string;
+    SKIP_FRONTEND?: string;
+    WEB_PORT?: string;
+    PORT?: string;
+    TEZOS_NETWORK?: string;
+    SPENDING_PRIVATE_KEY?: string;
+    SPENDING_CONTRACT?: string;
+}
+export declare class WorkerAdapter implements EnvironmentAdapter {
+    private env;
+    constructor(env?: WorkerEnv);
+    /**
+     * Update the environment bindings (called per-request with the env from fetch handler)
+     */
+    setEnv(env: WorkerEnv): void;
+    getEnv(key: keyof EnvConfig): string | undefined;
+    isWorker(): boolean;
+    base64Encode(data: string): string;
+    base64Decode(data: string): string;
+    log(message: string): void;
+}
+/**
+ * Create a Worker adapter instance
+ */
+export declare function createWorkerAdapter(env?: WorkerEnv): WorkerAdapter;

package/dist/adapters/worker.js

@@ -0,0 +1,50 @@
+/**
+ * Cloudflare Workers environment adapter
+ * Uses Web APIs and Worker bindings instead of Node.js filesystem/process
+ */
+export class WorkerAdapter {
+    env;
+    constructor(env = {}) {
+        this.env = env;
+    }
+    /**
+     * Update the environment bindings (called per-request with the env from fetch handler)
+     */
+    setEnv(env) {
+        this.env = env;
+    }
+    getEnv(key) {
+        return this.env[key];
+    }
+    isWorker() {
+        return true;
+    }
+    base64Encode(data) {
+        // Use TextEncoder for proper UTF-8 handling
+        const encoder = new TextEncoder();
+        const bytes = encoder.encode(data);
+        let binary = '';
+        for (let i = 0; i < bytes.length; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary);
+    }
+    base64Decode(data) {
+        const binary = atob(data);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        const decoder = new TextDecoder();
+        return decoder.decode(bytes);
+    }
+    log(message) {
+        console.log(`[tezosx-mcp] ${message}`);
+    }
+}
+/**
+ * Create a Worker adapter instance
+ */
+export function createWorkerAdapter(env) {
+    return new WorkerAdapter(env);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export declare const DEFAULT_WEB_PORT = "13205";
+import { TezosToolkit } from "@taquito/taquito";
+export type WalletConfig = {
+    Tezos: TezosToolkit;
+    spendingContract: string;
+    spendingAddress: string;
+} | null;

package/dist/index.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+export const DEFAULT_WEB_PORT = '13205';
+import { config } from 'dotenv';
+// Taquito
+import { InMemorySigner } from "@taquito/signer";
+import { TezosToolkit } from "@taquito/taquito";
+// MCP
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createTools } from "./tools/index.js";
+// MCP hosted
+import express from 'express';
+// Webserver
+import { startWebServer } from "./webserver.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { fileURLToPath } from "url";
+import { join } from "path";
+config({ quiet: true });
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+// Global error handlers
+process.on('uncaughtException', (err) => {
+    console.error('[tezosx-mcp] Uncaught exception:', err);
+});
+process.on('unhandledRejection', (reason) => {
+    console.error('[tezosx-mcp] Unhandled rejection:', reason);
+});
+// Network configurations
+const NETWORKS = {
+    mainnet: {
+        rpcUrl: 'https://mainnet.tezos.ecadinfra.com',
+        tzktApi: 'https://api.tzkt.io',
+    },
+    shadownet: {
+        rpcUrl: 'https://shadownet.tezos.ecadinfra.com',
+        tzktApi: 'https://api.shadownet.tzkt.io',
+    },
+};
+const log = (msg) => console.error(`[tezosx-mcp] ${msg}`);
+const init = async () => {
+    log('Starting server...');
+    // Start web server for frontend (skip if SKIP_FRONTEND is set or if using HTTP transport)
+    const skipFrontend = process.env.SKIP_FRONTEND === 'true' || process.env.MCP_TRANSPORT === 'http';
+    if (!skipFrontend) {
+        const webPort = parseInt(process.env.WEB_PORT || DEFAULT_WEB_PORT, 10);
+        startWebServer(webPort);
+        log(`Frontend server started on port ${webPort}`);
+    }
+    const server = new McpServer({
+        name: "tezosx-mcp",
+        version: "1.0.0"
+    });
+    // Network configuration
+    const networkName = (process.env.TEZOS_NETWORK || 'mainnet');
+    const network = NETWORKS[networkName];
+    if (!network) {
+        throw new ReferenceError(`Invalid network: ${networkName}. Valid options: ${Object.keys(NETWORKS).join(', ')}`);
+    }
+    log(`Network: ${networkName}`);
+    // Taquito setup
+    const Tezos = new TezosToolkit(network.rpcUrl);
+    // Wallet configuration (optional - tools will guide user to configure if not set)
+    let walletConfig = null;
+    const privateKey = process.env.SPENDING_PRIVATE_KEY?.trim();
+    const spendingContract = process.env.SPENDING_CONTRACT?.trim();
+    if (privateKey && spendingContract) {
+        log('Configuring wallet...');
+        // Validate private key format
+        if (!privateKey.startsWith('edsk') && !privateKey.startsWith('spsk') && !privateKey.startsWith('p2sk')) {
+            log(`Warning: Invalid SPENDING_PRIVATE_KEY format. Must start with edsk, spsk, or p2sk. Wallet not configured.`);
+        }
+        else {
+            try {
+                const signer = await InMemorySigner.fromSecretKey(privateKey);
+                Tezos.setSignerProvider(signer);
+                const spendingAddress = await Tezos.signer.publicKeyHash();
+                walletConfig = { Tezos, spendingContract, spendingAddress };
+                log(`Wallet configured: ${spendingAddress}`);
+            }
+            catch (error) {
+                log(`Warning: Failed to initialize signer: ${error instanceof Error ? error.message : 'Unknown error'}. Wallet not configured.`);
+            }
+        }
+    }
+    else {
+        log('Wallet not configured (missing SPENDING_PRIVATE_KEY or SPENDING_CONTRACT)');
+    }
+    // Tools
+    log('Registering tools...');
+    const http = process.env.MCP_TRANSPORT === 'http';
+    const tools = createTools(walletConfig, network.tzktApi, http);
+    tools.forEach(tool => {
+        server.registerTool(tool.name, tool.config, tool.handler);
+    });
+    log(`Registered ${tools.length} tools`);
+    const transport = process.env.MCP_TRANSPORT || 'stdio';
+    log(`Transport: ${transport}`);
+    if (transport === 'http') {
+        const app = express();
+        app.use(express.json());
+        // Dashboard frontend (serve from frontend/dist)
+        const frontendPath = join(__dirname, "../frontend/dist");
+        app.use(express.static(frontendPath));
+        // MCP endpoint
+        app.post('/mcp', async (req, res) => {
+            log('Received MCP request');
+            const httpTransport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true
+            });
+            res.on('close', () => httpTransport.close());
+            await server.connect(httpTransport);
+            await httpTransport.handleRequest(req, res, req.body);
+        });
+        // SPA fallback - serve index.html for all non-API routes
+        app.get('/{*path}', (req, res) => {
+            res.sendFile(join(frontendPath, 'index.html'));
+        });
+        const port = process.env.PORT || 3004;
+        // Keep reference to http server and wait for it to start
+        await new Promise((resolve) => {
+            const httpServer = app.listen(port, () => {
+                log(`HTTP server listening on port ${port}`);
+                log(`MCP endpoint: http://localhost:${port}/mcp`);
+                resolve();
+            });
+            // Keep process alive
+            httpServer.on('error', (err) => {
+                log(`HTTP server error: ${err.message}`);
+            });
+        });
+        // Keep the process running
+        log('Server ready, waiting for requests...');
+    }
+    else {
+        log('Connecting stdio transport...');
+        const stdioTransport = new StdioServerTransport();
+        await server.connect(stdioTransport);
+        log('Stdio transport connected');
+    }
+};
+init().catch(err => {
+    console.error('[tezosx-mcp] Fatal error:', err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Core MCP server setup - shared between Node.js and Workers environments
+ */
+import { TezosToolkit } from "@taquito/taquito";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { EnvironmentAdapter } from "./adapters/index.js";
+export type WalletConfig = {
+    Tezos: TezosToolkit;
+    spendingContract: string;
+    spendingAddress: string;
+} | null;
+declare const NETWORKS: {
+    readonly mainnet: {
+        readonly rpcUrl: "https://mainnet.tezos.ecadinfra.com";
+        readonly tzktApi: "https://api.tzkt.io";
+    };
+    readonly shadownet: {
+        readonly rpcUrl: "https://shadownet.tezos.ecadinfra.com";
+        readonly tzktApi: "https://api.shadownet.tzkt.io";
+    };
+};
+export type NetworkName = keyof typeof NETWORKS;
+export type NetworkConfig = typeof NETWORKS[NetworkName];
+export interface ServerConfig {
+    server: McpServer;
+    walletConfig: WalletConfig;
+    network: NetworkConfig;
+    networkName: NetworkName;
+    isHttp: boolean;
+}
+/**
+ * Initialize the MCP server with tools and wallet configuration
+ * This is the shared core that works in both Node.js and Workers
+ */
+export declare function createMcpServer(adapter: EnvironmentAdapter): Promise<ServerConfig>;
+export {};

package/dist/server.js

@@ -0,0 +1,80 @@
+/**
+ * Core MCP server setup - shared between Node.js and Workers environments
+ */
+import { InMemorySigner } from "@taquito/signer";
+import { TezosToolkit } from "@taquito/taquito";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createTools } from "./tools/index.js";
+// Network configurations
+const NETWORKS = {
+    mainnet: {
+        rpcUrl: 'https://mainnet.tezos.ecadinfra.com',
+        tzktApi: 'https://api.tzkt.io',
+    },
+    shadownet: {
+        rpcUrl: 'https://shadownet.tezos.ecadinfra.com',
+        tzktApi: 'https://api.shadownet.tzkt.io',
+    },
+};
+/**
+ * Initialize the MCP server with tools and wallet configuration
+ * This is the shared core that works in both Node.js and Workers
+ */
+export async function createMcpServer(adapter) {
+    const log = (msg) => adapter.log(msg);
+    log('Initializing MCP server...');
+    const server = new McpServer({
+        name: "tezosx-mcp",
+        version: "1.0.0"
+    });
+    // Network configuration
+    const networkName = (adapter.getEnv('TEZOS_NETWORK') || 'mainnet');
+    const network = NETWORKS[networkName];
+    if (!network) {
+        throw new ReferenceError(`Invalid network: ${networkName}. Valid options: ${Object.keys(NETWORKS).join(', ')}`);
+    }
+    log(`Network: ${networkName}`);
+    // Taquito setup
+    const Tezos = new TezosToolkit(network.rpcUrl);
+    // Wallet configuration (optional - tools will guide user to configure if not set)
+    let walletConfig = null;
+    const privateKey = adapter.getEnv('SPENDING_PRIVATE_KEY')?.trim();
+    const spendingContract = adapter.getEnv('SPENDING_CONTRACT')?.trim();
+    if (privateKey && spendingContract) {
+        log('Configuring wallet...');
+        // Validate private key format
+        if (!privateKey.startsWith('edsk') && !privateKey.startsWith('spsk') && !privateKey.startsWith('p2sk')) {
+            log(`Warning: Invalid SPENDING_PRIVATE_KEY format. Must start with edsk, spsk, or p2sk. Wallet not configured.`);
+        }
+        else {
+            try {
+                const signer = await InMemorySigner.fromSecretKey(privateKey);
+                Tezos.setSignerProvider(signer);
+                const spendingAddress = await Tezos.signer.publicKeyHash();
+                walletConfig = { Tezos, spendingContract, spendingAddress };
+                log(`Wallet configured: ${spendingAddress}`);
+            }
+            catch (error) {
+                log(`Warning: Failed to initialize signer: ${error instanceof Error ? error.message : 'Unknown error'}. Wallet not configured.`);
+            }
+        }
+    }
+    else {
+        log('Wallet not configured (missing SPENDING_PRIVATE_KEY or SPENDING_CONTRACT)');
+    }
+    // Tools
+    log('Registering tools...');
+    const isHttp = adapter.getEnv('MCP_TRANSPORT') === 'http';
+    const tools = createTools(walletConfig, network.tzktApi, isHttp);
+    tools.forEach(tool => {
+        server.registerTool(tool.name, tool.config, tool.handler);
+    });
+    log(`Registered ${tools.length} tools`);
+    return {
+        server,
+        walletConfig,
+        network,
+        networkName,
+        isHttp
+    };
+}

package/dist/tools/create_x402_payment.d.ts

@@ -0,0 +1,27 @@
+import { TezosToolkit } from "@taquito/taquito";
+import z from "zod";
+export declare const createCreateX402PaymentTool: (Tezos: TezosToolkit) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{
+            network: z.ZodString;
+            asset: z.ZodString;
+            amount: z.ZodString;
+            recipient: 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/create_x402_payment.js

@@ -0,0 +1,55 @@
+import z from "zod";
+import { signX402Payment } from "./x402/sign.js";
+export const createCreateX402PaymentTool = (Tezos) => ({
+    name: "tezos_create_x402_payment",
+    config: {
+        title: "Create x402 Payment",
+        description: "Creates a signed Tezos payment for x402 protocol. Builds and signs a transfer operation without broadcasting it, then packages it as a base64-encoded X-PAYMENT header value.",
+        inputSchema: z.object({
+            network: z.string().describe("The Tezos network (e.g., 'shadownet', 'mainnet')"),
+            asset: z.string().describe("The asset to pay with (e.g., 'XTZ')"),
+            amount: z.string().describe("The amount in mutez to send"),
+            recipient: z.string().describe("The recipient Tezos address (tz1...)")
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        }
+    },
+    handler: async (params) => {
+        const { network, asset, amount, recipient } = params;
+        // Validate asset type
+        if (asset !== "XTZ") {
+            throw new Error(`Unsupported asset: ${asset}. Only XTZ is supported.`);
+        }
+        const amountMutez = parseInt(amount, 10);
+        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`);
+        }
+        const signed = await signX402Payment(Tezos, {
+            network,
+            amount: amountMutez,
+            recipient,
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        headerValue: signed.base64,
+                        payload: signed.payload,
+                    }, null, 2)
+                }]
+        };
+    }
+});

package/dist/tools/fetch_with_x402.d.ts

@@ -0,0 +1,28 @@
+import { TezosToolkit } from "@taquito/taquito";
+import z from "zod";
+export declare const createFetchWithX402Tool: (Tezos: TezosToolkit) => {
+    name: string;
+    config: {
+        title: string;
+        description: string;
+        inputSchema: z.ZodObject<{
+            url: z.ZodString;
+            maxAmountMutez: z.ZodString;
+            method: z.ZodOptional<z.ZodString>;
+            body: z.ZodOptional<z.ZodString>;
+            recipient: z.ZodOptional<z.ZodString>;
+        }, z.z.core.$strip>;
+        annotations: {
+            readOnlyHint: boolean;
+            destructiveHint: boolean;
+            idempotentHint: boolean;
+            openWorldHint: boolean;
+        };
+    };
+    handler: (params: any) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+    }>;
+};