<p align="center">
  <img src="./assets/logo.png" width="130" height="130" alt="Web3 EVM Debugger & Auditor MCP Logo" />
</p>

# Web3 EVM Debugger & Auditor MCP

[![Smithery Compatible](https://img.shields.io/badge/Smithery-Compatible-blue.svg)](https://smithery.ai)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard%20v1.0-emerald.svg)](https://modelcontextprotocol.io)
[![Base L2 Settlement](https://img.shields.io/badge/Base%20L2-USDC%20x402-blue.svg)](https://base.org)
[![Tools](https://img.shields.io/badge/Tools-6%20Curated-purple.svg)](#included-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**EVM calldata decoding, debug trace revert pinpointing, storage slot layout mapping, and smart contract reentrancy auditing.**

Built specifically for Solidity developers, smart contract auditors, DeFi protocol engineers, and Web3 security researchers.

---

## ⚡ Quickstart

### Smithery Install
```bash
smithery skill add whambammy/web3-evm-debugger-mcp
```

### Claude Desktop / Cursor (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "web3-evm-debugger-mcp": {
      "command": "npx",
      "args": ["-y", "@whambammy/web3-evm-debugger-mcp"],
      "env": {
        "PAYMENT_WALLET": "0x9793E7269b3301893318dEa8338576Ba612F39B3",
        "BASE_RPC_URL": "https://mainnet.base.org"
      }
    }
  }
}
```

---

## 🛠️ Included Tools

| Tool Name | Price (USDC) | Capability |
| :--- | :---: | :--- |
| `evm_trace_call_revert_debugger` | $0.045 | Parses Geth/Nethermind debug_traceTransaction call trees, pinpointing the exact depth, instruction opcode, sub-contract, and revert message of failed calls. |
| `smart_contract_reentrancy_auditor` | $0.050 | Symbolic execution analyzer scanning Solidity ASTs for cross-function reentrancy, check-effects-interaction violations, and read-only reentrancy in view functions. |
| `decode_evm_calldata` | $0.01 | Decodes raw 4-byte function selectors and hex calldata into human-readable method signatures, types, and named arguments. |
| `evm_storage_slot_layout_calculator` | $0.035 | Calculates exact 32-byte EVM storage slots for complex Solidity state variables (nested mappings, dynamic arrays, packed structs) according to ABI specification. |
| `solidity_assembly_yul_sanitizer` | $0.040 | Scans inline Yul assembly in Solidity smart contracts for uninitialized memory pointer bugs, 64-bit clean memory corruption, and memory expansion gas bombs. |
| `eip1271_smart_contract_signature_verifier` | $0.035 | Verifies EIP-1271 signatures on smart contract wallets (Safe, Argent, Kernel, Biconomy) using eth_staticcall validation with gas safeguards. |


---

## 🔄 End-to-End Workflow

An auditor agent investigates an on-chain transaction revert -> decodes the calldata -> traces the revert step-by-step through internal calls -> maps impacted storage slots -> audits the target contract for reentrancy bugs.

---

## 💰 The x402 Base L2 Micropayment Protocol

When an agent invokes a tool without payment, the server responds with a deterministic `HTTP 402 Payment Required` challenge containing:
- Target tool price in USDC
- Base Native USDC Contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Recipient payout wallet address
- Single-use cryptographic nonce

Once broadcasted on Base L2, resubmitting with `paymentSignature` unlocks deterministic execution.

---

## 📄 License
MIT License. Created by [Whambammy](https://github.com/Whambammy).