feat: add write_contract tool and interact_with_contract prompt for safe contract interaction.

Author: wayzeek

README.md

@@ -6,7 +6,7 @@
 ![MCP](https://img.shields.io/badge/MCP-1.22.0+-blue)
 ![Viem](https://img.shields.io/badge/Viem-2.39.3+-green)
 
-A comprehensive Model Context Protocol (MCP) server that provides blockchain services across 60+ EVM-compatible networks. This server enables AI agents to interact with Ethereum, Optimism, Arbitrum, Base, Polygon, and many other EVM chains with a unified interface through 21 tools and 9 AI-guided prompts.
+A comprehensive Model Context Protocol (MCP) server that provides blockchain services across 60+ EVM-compatible networks. This server enables AI agents to interact with Ethereum, Optimism, Arbitrum, Base, Polygon, and many other EVM chains with a unified interface through 22 tools and 10 AI-guided prompts.
 
 ## 📋 Contents
 
@@ -75,7 +75,7 @@ All services are exposed through a consistent interface of MCP tools, resources,
 ### Smart Contract Interactions
 
 - **Read contract state** through view/pure functions
-- **Write services** with private key signing
+- **Write to contracts** - Execute any state-changing function with automatic ABI fetching
 - **Contract verification** to distinguish from EOAs
 - **Event logs** retrieval and filtering
 - **Automatic ABI fetching** from Etherscan v2 API across all 60+ networks (no need to know ABIs in advance)
@@ -93,6 +93,7 @@ All services are exposed through a consistent interface of MCP tools, resources,
 - **Transaction preparation** - Guidance for planning and executing transfers
 - **Wallet analysis** - Tools for analyzing wallet activity and holdings
 - **Smart contract exploration** - Interactive ABI fetching and contract analysis
+- **Contract interaction** - Safe execution of write operations on smart contracts
 - **Network information** - Learning about EVM networks and comparisons
 - **Approval auditing** - Reviewing and managing token approvals
 - **Error diagnosis** - Troubleshooting transaction failures
@@ -440,7 +441,7 @@ console.log(result);
 
 ### Tools
 
-The server provides 21 focused MCP tools for agents. **All tools that accept address parameters support both Ethereum addresses and ENS names.**
+The server provides 22 focused MCP tools for agents. **All tools that accept address parameters support both Ethereum addresses and ENS names.**
 
 #### Wallet Information
 
@@ -487,6 +488,7 @@ The server provides 21 focused MCP tools for agents. **All tools that accept add
 |-----------|-------------|----------------|
 | `get_contract_abi` | Fetch contract ABI from block explorer (60+ networks) | `contractAddress` (address/ENS), `network` |
 | `read_contract` | Read smart contract state (auto-fetches ABI if needed) | `contractAddress`, `functionName`, `args[]`, `abiJson` (optional), `network` |
+| `write_contract` | Execute state-changing functions (auto-fetches ABI if needed) | `contractAddress`, `functionName`, `args[]`, `value` (optional), `abiJson` (optional), `network` |
 
 #### Token Transfers
 

package.json

@@ -3,7 +3,7 @@
   "module": "src/index.ts",
   "type": "module",
   "version": "2.0.0",
-  "description": "MCP server for interacting with EVM-compatible blockchains - supports 21 tools and 9 prompts across 60+ networks",
+  "description": "MCP server for interacting with EVM-compatible blockchains - supports 22 tools and 10 prompts across 60+ networks",
   "bin": {
     "evm-mcp-server": "./bin/cli.js"
   },

src/core/prompts.ts

@@ -46,8 +46,8 @@ Before executing any transfer:
 1. **Wallet Verification**: Call \`get_wallet_address\` to confirm the sending wallet
 2. **Balance Check**:
    ${tokenType === "native"
-     ? "- Call `get_balance` to verify native token balance"
-     : "- Call `get_token_balance` with tokenAddress=${tokenAddress} to verify balance"}
+              ? "- Call `get_balance` to verify native token balance"
+              : "- Call `get_token_balance` with tokenAddress=${tokenAddress} to verify balance"}
 3. **Gas Analysis**: Call \`get_gas_price\` to assess current network costs
 ${tokenType === "erc20" ? `4. **Approval Check**: Call \`get_allowance\` to verify approval (if needed for protocols)` : ""}
 
@@ -204,8 +204,8 @@ Provide structured diagnosis:
 
 ### 3. Token Balances
 ${tokenList.length > 0
-  ? `- Call \`get_token_balance\` for each token:\n${tokenList.map(t => `  * ${t}`).join('\n')}`
-  : `- If specific tokens provided: call \`get_token_balance\` for each
+                ? `- Call \`get_token_balance\` for each token:\n${tokenList.map(t => `  * ${t}`).join('\n')}`
+                : `- If specific tokens provided: call \`get_token_balance\` for each
 - Include token symbol and decimals if available`}
 
 ## Output Format
@@ -475,13 +475,13 @@ Look for:
 ## Exploration Strategy
 
 ${fetchAbi === 'true'
-  ? `### With Full ABI (Fetched)
+              ? `### With Full ABI (Fetched)
 1. Call \`get_contract_abi\` to fetch verified ABI
 2. Parse all available functions
 3. Call \`read_contract\` for important state functions
 4. Build comprehensive understanding
 `
-  : `### Without Full ABI (Probing)
+              : `### Without Full ABI (Probing)
 1. Test common function signatures
 2. Call \`read_contract\` with standard functions:
    - name(), symbol(), decimals(), totalSupply()
@@ -567,6 +567,179 @@ For each contract type:
   // NETWORK & EDUCATION PROMPTS
   // ============================================================================
 
+  server.registerPrompt(
+    "interact_with_contract",
+    {
+      description: "Safely execute write operations on a smart contract with validation and confirmation",
+      argsSchema: {
+        contractAddress: z.string().describe("Contract address to interact with"),
+        functionName: z.string().describe("Function to call (e.g., 'mint', 'swap', 'stake')"),
+        args: z.string().optional().describe("Comma-separated function arguments"),
+        value: z.string().optional().describe("ETH value to send (for payable functions)"),
+        network: z.string().optional().describe("Network name (default: ethereum)")
+      }
+    },
+    ({ contractAddress, functionName, args, value, network = "ethereum" }) => {
+      const argsList = args ? args.split(',').map(a => a.trim()) : [];
+      return {
+        messages: [{
+          role: "user",
+          content: {
+            type: "text",
+            text: `# Smart Contract Interaction
+
+**Objective**: Safely execute ${functionName} on contract ${contractAddress} on ${network}
+
+## Prerequisites Check
+
+### 1. Wallet Verification
+- Call \`get_wallet_address\` to confirm the wallet that will execute this transaction
+- Verify this is the correct wallet for this operation
+
+### 2. Contract Analysis
+- Call \`get_contract_abi\` to fetch and analyze the contract ABI
+- Verify the function exists and understand its parameters
+- Check function type:
+  * **View/Pure**: Read-only (use \`read_contract\` instead)
+  * **Nonpayable**: State-changing, no ETH required
+  * **Payable**: State-changing, can accept ETH
+
+### 3. Function Parameter Validation
+For function: **${functionName}**
+${argsList.length > 0 ? `Arguments provided: ${argsList.join(', ')}` : 'No arguments provided'}
+
+- Verify parameter types match the ABI
+- Validate addresses are checksummed
+- Check numeric values are in correct units
+- Resolve any ENS names to addresses if needed
+
+### 4. Pre-execution Checks
+
+**Balance Check**:
+- Call \`get_balance\` to verify sufficient native token balance
+- Account for gas costs + value (if payable)
+
+**Gas Estimation**:
+- Call \`get_gas_price\` to estimate transaction cost
+- Calculate total cost: (gas_price * estimated_gas) + value
+
+**State Verification** (if applicable):
+- Use \`read_contract\` to check current contract state
+- Verify conditions are met (e.g., allowances, balances, ownership)
+
+## Execution Process
+
+### 1. Present Summary to User
+Before executing, show:
+- **Contract**: ${contractAddress}
+- **Network**: ${network}
+- **Function**: ${functionName}
+- **Arguments**: ${argsList.length > 0 ? argsList.join(', ') : 'None'}
+${value ? `- **Value**: ${value} ETH` : ''}
+- **From**: [wallet address from step 1]
+- **Estimated Gas Cost**: [from gas estimation]
+- **Total Cost**: [gas + value]
+
+### 2. Request User Confirmation
+⚠️ **IMPORTANT**: Always ask user to confirm before executing write operations
+- Clearly state what will happen
+- Show all costs involved
+- Explain any risks or irreversible actions
+
+### 3. Execute Transaction
+Only after user confirms:
+\`\`\`
+Call write_contract with:
+- contractAddress: "${contractAddress}"
+- functionName: "${functionName}"
+${argsList.length > 0 ? `- args: ${JSON.stringify(argsList)}` : ''}
+${value ? `- value: "${value}"` : ''}
+- network: "${network}"
+\`\`\`
+
+### 4. Monitor Transaction
+After execution:
+1. Return transaction hash to user
+2. Call \`wait_for_transaction\` to monitor confirmation
+3. Call \`get_transaction_receipt\` to verify success
+4. If failed, call \`diagnose_transaction\` to understand why
+
+## Output Format
+
+**Pre-Execution Summary**:
+- Contract details
+- Function and parameters
+- Cost breakdown
+- Risk assessment
+
+**Confirmation Request**:
+"Ready to execute ${functionName} on ${contractAddress}. This will cost approximately [X] ETH. Proceed? (yes/no)"
+
+**Execution Result**:
+- Transaction Hash: [hash]
+- Status: Pending/Confirmed/Failed
+- Block Number: [if confirmed]
+- Gas Used: [actual gas used]
+- Total Cost: [final cost]
+
+## Safety Considerations
+
+### Critical Checks
+- ✅ Verify contract is verified on block explorer
+- ✅ Check function parameters are correct type and format
+- ✅ Ensure sufficient balance for gas + value
+- ✅ Validate addresses (no typos, correct network)
+- ✅ Understand what the function does before calling
+
+### Common Risks
+- **Irreversible**: Most blockchain transactions cannot be undone
+- **Gas Loss**: Failed transactions still consume gas
+- **Approval Risks**: Be careful with unlimited approvals
+- **Reentrancy**: Some functions may be vulnerable
+- **Access Control**: Verify you have permission to call this function
+
+### Red Flags
+🚨 Stop and warn user if:
+- Contract is not verified
+- Function requires admin/owner privileges you don't have
+- Unusually high gas estimate
+- Suspicious parameter values
+- Contract has known vulnerabilities
+
+## Error Handling
+
+If transaction fails:
+1. Get the revert reason from receipt
+2. Check common issues:
+   - Insufficient balance/allowance
+   - Access control (onlyOwner, etc.)
+   - Invalid parameters
+   - Contract paused
+   - Slippage (for DEX operations)
+3. Provide actionable fix suggestions
+4. Offer to retry with corrected parameters
+
+## Example Workflow
+
+For a token mint operation:
+1. ✅ Verify wallet
+2. ✅ Fetch contract ABI
+3. ✅ Check mint function exists and is callable
+4. ✅ Verify sufficient ETH for gas
+5. ✅ Show summary: "Minting 1 NFT will cost ~0.002 ETH"
+6. ⏸️ Wait for user confirmation
+7. ✅ Execute write_contract
+8. ✅ Monitor transaction
+9. ✅ Confirm success and return token ID
+
+**Remember**: Always prioritize user safety and transparency!
+`
+          }
+        }]
+      };
+    }
+  );
+
   server.registerPrompt(
     "explain_evm_concept",
     {

src/core/tools.ts

@@ -765,6 +765,119 @@ export function registerEVMTools(server: McpServer) {
     }
   );
 
+  server.registerTool(
+    "write_contract",
+    {
+      description: "Execute state-changing functions on a smart contract. Automatically fetches ABI from block explorer if not provided (requires ETHERSCAN_API_KEY). Use this to call any write function on verified contracts. Requires EVM_PRIVATE_KEY to be configured.",
+      inputSchema: {
+        contractAddress: z.string().describe("The contract address"),
+        functionName: z.string().describe("Function name to call (e.g., 'mint', 'swap', 'stake', 'approve')"),
+        args: z.array(z.string()).optional().describe("Function arguments as strings (e.g., ['0xAddress', '1000000'])"),
+        value: z.string().optional().describe("ETH value to send with transaction in ether (e.g., '0.1' for payable functions)"),
+        abiJson: z.string().optional().describe("Full contract ABI as JSON string (optional - will auto-fetch verified contract ABI if not provided)"),
+        network: z.string().optional().describe("Network name or chain ID. Defaults to Ethereum mainnet.")
+      },
+      annotations: {
+        title: "Write to Smart Contract",
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    async ({ contractAddress, functionName, args = [], value, abiJson, network = "ethereum" }) => {
+      try {
+        const privateKey = getConfiguredPrivateKey();
+        const senderAddress = getWalletAddressFromKey();
+        const client = await services.getPublicClient(network);
+
+        let abi: any[] | undefined;
+        let functionAbi: any;
+
+        // If ABI is provided, use it
+        if (abiJson) {
+          try {
+            abi = services.parseABI(abiJson);
+            functionAbi = services.getFunctionFromABI(abi, functionName);
+          } catch (error) {
+            return {
+              content: [{
+                type: "text",
+                text: `Error parsing provided ABI: ${error instanceof Error ? error.message : String(error)}`
+              }],
+              isError: true
+            };
+          }
+        } else {
+          // Try to auto-fetch ABI from block explorer
+          try {
+            const fetchedAbi = await services.fetchContractABI(contractAddress as Address, network);
+            abi = services.parseABI(fetchedAbi);
+            functionAbi = services.getFunctionFromABI(abi, functionName);
+          } catch (fetchError) {
+            return {
+              content: [{
+                type: "text",
+                text: `Error: Could not auto-fetch ABI (${fetchError instanceof Error ? fetchError.message : String(fetchError)}). Please provide the contract ABI using the abiJson parameter, or use get_contract_abi to fetch it first.`
+              }],
+              isError: true
+            };
+          }
+        }
+
+        // Validate that this is not a view/pure function
+        if (functionAbi.stateMutability === 'view' || functionAbi.stateMutability === 'pure') {
+          return {
+            content: [{
+              type: "text",
+              text: `Error: Function '${functionName}' is a ${functionAbi.stateMutability} function and cannot modify state. Use read_contract instead.`
+            }],
+            isError: true
+          };
+        }
+
+        // Prepare write parameters
+        const writeParams: any = {
+          address: contractAddress as Address,
+          abi: [functionAbi],
+          functionName: functionName,
+          args: args as any
+        };
+
+        // Add value if provided (for payable functions)
+        if (value) {
+          const { parseEther } = await import('viem');
+          writeParams.value = parseEther(value);
+        }
+
+        // Execute the write operation
+        const txHash = await services.writeContract(privateKey, writeParams, network);
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              network,
+              contractAddress,
+              function: functionName,
+              args: args.length > 0 ? args : undefined,
+              value: value || undefined,
+              from: senderAddress,
+              txHash,
+              abiSource: abiJson ? 'provided' : 'auto-fetched',
+              message: "Transaction sent. Use get_transaction_receipt or wait_for_transaction to check confirmation."
+            }, null, 2)
+          }]
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: `Error writing to contract: ${error instanceof Error ? error.message : String(error)}` }],
+          isError: true
+        };
+      }
+    }
+  );
+
   // ============================================================================
   // TRANSFER TOOLS (Write operations)
   // ============================================================================