web3-tools-mcp 1.0.1 → 1.2.0

package/dist/src/tools/contract.js

@@ -0,0 +1,140 @@
+import { isAddress, parseAbiItem } from "viem";
+import { z } from "zod";
+import { getClientManager, SUPPORTED_CHAINS } from "../client.js";
+import { convertArgumentsToTypes, createTool, formatResponse } from "../utils.js";
+const ContractCallSchema = z.object({
+    chain: z
+        .enum(SUPPORTED_CHAINS)
+        .describe("Blockchain network (mainnet, base, arbitrum, polygon, optimism, celo, localhost)"),
+    contractAddress: z
+        .string()
+        .describe("Contract address to call (must be valid checksummed address)"),
+    functionAbi: z
+        .string()
+        .describe('Function ABI signature string (e.g., "function balanceOf(address owner) view returns (uint256)"). Only view/pure functions allowed.'),
+    args: z
+        .array(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+        .optional()
+        .describe("Function arguments in order matching the ABI signature. Automatically type-converted."),
+    blockNumber: z
+        .string()
+        .optional()
+        .describe("Block number for historical queries (defaults to latest)"),
+    label: z.string().optional().describe("Optional label to identify this call in batch results"),
+});
+export default {
+    call_contract_function: createTool("Call Contract Functions", "Execute multiple view/pure contract functions efficiently. BATCH OPTIMIZED - use for reading contract state, token metadata.", z.object({
+        calls: z
+            .array(ContractCallSchema)
+            .describe("Array of contract function calls. Automatically batched by chain/block for optimal performance."),
+    }), async (args) => {
+        // Group by chain and blockNumber for efficient multicall
+        const groupedCalls = new Map();
+        for (const item of args.calls) {
+            const key = `${item.chain}:${item.blockNumber || "latest"}`;
+            if (!groupedCalls.has(key)) {
+                groupedCalls.set(key, []);
+            }
+            groupedCalls.get(key).push(item);
+        }
+        const allResults = [];
+        try {
+            // Process each group
+            for (const [key, calls] of groupedCalls) {
+                const [chain, blockNum] = key.split(":");
+                const clientManager = getClientManager();
+                const client = clientManager.getClient(chain);
+                const blockTag = blockNum === "latest" ? "latest" : BigInt(blockNum);
+                // Prepare multicall contracts
+                const multicallContracts = calls.map((call) => {
+                    if (!isAddress(call.contractAddress)) {
+                        throw new Error(`Invalid contract address: ${call.contractAddress}`);
+                    }
+                    const abiItem = parseAbiItem(call.functionAbi);
+                    if (abiItem.stateMutability !== "view" && abiItem.stateMutability !== "pure") {
+                        throw new Error(`Only view and pure functions can be called: ${call.functionAbi}`);
+                    }
+                    const convertedArgs = convertArgumentsToTypes(call.args || [], abiItem.inputs);
+                    return {
+                        address: call.contractAddress,
+                        abi: [abiItem],
+                        functionName: abiItem.name,
+                        args: convertedArgs,
+                    };
+                });
+                // Execute multicall
+                const multicallResults = await client.multicall({
+                    contracts: multicallContracts,
+                    blockNumber: blockTag === "latest" ? undefined : blockTag,
+                });
+                // Process results
+                multicallResults.forEach((result, idx) => {
+                    const call = calls[idx];
+                    const abiItem = parseAbiItem(call.functionAbi);
+                    const originalIndex = args.calls.indexOf(call);
+                    if (result.status === "success") {
+                        allResults[originalIndex] = {
+                            index: originalIndex,
+                            label: call.label,
+                            contractAddress: call.contractAddress,
+                            functionName: abiItem.name,
+                            success: true,
+                            result: result.result,
+                            chain: call.chain,
+                            blockNumber: call.blockNumber || "latest",
+                        };
+                    }
+                    else {
+                        allResults[originalIndex] = {
+                            index: originalIndex,
+                            label: call.label,
+                            contractAddress: call.contractAddress,
+                            functionName: abiItem.name,
+                            success: false,
+                            error: result.error instanceof Error ? result.error.message : String(result.error),
+                            chain: call.chain,
+                            blockNumber: call.blockNumber || "latest",
+                        };
+                    }
+                });
+            }
+            return formatResponse({
+                success: true,
+                totalCalls: args.calls.length,
+                successfulCalls: allResults.filter((r) => r.success).length,
+                failedCalls: allResults.filter((r) => !r.success).length,
+                results: allResults,
+            });
+        }
+        catch (error) {
+            throw new Error(`Contract call failed: ${error}`);
+        }
+    }),
+    is_contract: createTool("Check Address Type", "Determine if address is smart contract or EOA. Returns contract status and bytecode length.", z.object({
+        chain: z.enum(SUPPORTED_CHAINS).describe("Blockchain network to query"),
+        address: z
+            .string()
+            .describe("Address to check (returns true if contract, false if EOA/wallet)"),
+    }), async (args) => {
+        if (!isAddress(args.address)) {
+            throw new Error("Invalid address format");
+        }
+        const clientManager = getClientManager();
+        const client = clientManager.getClient(args.chain);
+        try {
+            const bytecode = await client.getBytecode({ address: args.address });
+            const isContractFlag = bytecode !== undefined && bytecode !== "0x";
+            return formatResponse({
+                address: args.address,
+                isContract: isContractFlag,
+                type: isContractFlag ? "contract" : "EOA",
+                chain: args.chain,
+                bytecodeLength: bytecode ? bytecode.length - 2 : 0, // -2 for '0x' prefix
+            });
+        }
+        catch (error) {
+            throw new Error(`Failed to check address type: ${error}`);
+        }
+    }),
+};
+//# sourceMappingURL=contract.js.map

package/dist/src/tools/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../../src/tools/contract.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/ens.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+declare const _default: {
+    resolve_ens_name: {
+        title: string;
+        description: string;
+        schema: z.ZodObject<{
+            chain: z.ZodDefault<z.ZodEnum<["mainnet", "base", "arbitrum", "polygon", "optimism", "celo", "localhost"]>>;
+            name: z.ZodString;
+            universalResolver: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            name: string;
+            universalResolver?: boolean | undefined;
+        }, {
+            name: string;
+            chain?: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost" | undefined;
+            universalResolver?: boolean | undefined;
+        }>;
+        handler: (args: {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            name: string;
+            universalResolver?: boolean | undefined;
+        }) => Promise<import("../types.js").ToolResult>;
+    };
+    reverse_resolve_ens: {
+        title: string;
+        description: string;
+        schema: z.ZodObject<{
+            chain: z.ZodDefault<z.ZodEnum<["mainnet", "base", "arbitrum", "polygon", "optimism", "celo", "localhost"]>>;
+            address: z.ZodString;
+            universalResolver: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            address: string;
+            universalResolver?: boolean | undefined;
+        }, {
+            address: string;
+            chain?: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost" | undefined;
+            universalResolver?: boolean | undefined;
+        }>;
+        handler: (args: {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            address: string;
+            universalResolver?: boolean | undefined;
+        }) => Promise<import("../types.js").ToolResult>;
+    };
+    get_ens_text_record: {
+        title: string;
+        description: string;
+        schema: z.ZodObject<{
+            chain: z.ZodDefault<z.ZodEnum<["mainnet", "base", "arbitrum", "polygon", "optimism", "celo", "localhost"]>>;
+            name: z.ZodString;
+            key: z.ZodString;
+            universalResolver: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            key: string;
+            name: string;
+            universalResolver?: boolean | undefined;
+        }, {
+            key: string;
+            name: string;
+            chain?: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost" | undefined;
+            universalResolver?: boolean | undefined;
+        }>;
+        handler: (args: {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            key: string;
+            name: string;
+            universalResolver?: boolean | undefined;
+        }) => Promise<import("../types.js").ToolResult>;
+    };
+    get_ens_avatar: {
+        title: string;
+        description: string;
+        schema: z.ZodObject<{
+            chain: z.ZodDefault<z.ZodEnum<["mainnet", "base", "arbitrum", "polygon", "optimism", "celo", "localhost"]>>;
+            name: z.ZodString;
+            universalResolver: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            name: string;
+            universalResolver?: boolean | undefined;
+        }, {
+            name: string;
+            chain?: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost" | undefined;
+            universalResolver?: boolean | undefined;
+        }>;
+        handler: (args: {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            name: string;
+            universalResolver?: boolean | undefined;
+        }) => Promise<import("../types.js").ToolResult>;
+    };
+    batch_resolve_ens_names: {
+        title: string;
+        description: string;
+        schema: z.ZodObject<{
+            chain: z.ZodDefault<z.ZodEnum<["mainnet", "base", "arbitrum", "polygon", "optimism", "celo", "localhost"]>>;
+            names: z.ZodArray<z.ZodString, "many">;
+            universalResolver: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            names: string[];
+            universalResolver?: boolean | undefined;
+        }, {
+            names: string[];
+            chain?: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost" | undefined;
+            universalResolver?: boolean | undefined;
+        }>;
+        handler: (args: {
+            chain: "mainnet" | "base" | "arbitrum" | "polygon" | "optimism" | "celo" | "localhost";
+            names: string[];
+            universalResolver?: boolean | undefined;
+        }) => Promise<import("../types.js").ToolResult>;
+    };
+};
+export default _default;
+//# sourceMappingURL=ens.d.ts.map

package/dist/src/tools/ens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ens.d.ts","sourceRoot":"","sources":["../../../src/tools/ens.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwNxB,wBAkRE"}