# MCP Anvil Tools

Model Context Protocol (MCP) server providing Ethereum development and testing tools for AI agents. Built on Anvil (Foundry's local Ethereum node) and viem for robust blockchain interactions.

## Overview

MCP Anvil Tools enables AI agents to:
- Read Solidity source code and contract storage
- Simulate and execute transactions on local Anvil or testnets
- Manipulate blockchain state with snapshots and impersonation
- Query events and decode bytecode
- Test smart contracts in isolated environments

Perfect for AI-powered smart contract auditing, testing workflows, and blockchain development automation.

## Key Features

- **Dual Transport Modes**: Stateless HTTP via `/mcp` endpoint or stdio for CLI/desktop integration
- **Reading Tools (4)**: Source code, storage, bytecode, and event log access
- **Execution Tools (5)**: Transaction simulation, sending, and state manipulation
- **Tracing Tools (2)**: Transaction and call tracing with multiple tracer types
- **Anvil Integration**: Automatic Anvil process management with snapshot/revert support
- **State Persistence**: SQLite-backed deployment and session tracking
- **Type Safety**: Full TypeScript support with Zod validation

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/mcp-anvil-tools.git
cd mcp-anvil-tools

# Install dependencies
npm install

# Build the project
npm run build
```

### Configuration

```bash
# Copy example environment file
cp .env.example .env

# Edit .env with your configuration
nano .env
```

Required environment variables:
- `AUDIT_MCP_PORT` - Server port (default: 3000)
- `MAINNET_RPC_URL` - RPC endpoint for mainnet interactions
- `ETHERSCAN_API_KEY` - Optional, for source code verification

### Running the Server

**HTTP/SSE Mode** (for web clients, multi-agent systems):
```bash
npm start
# Server runs on http://localhost:3000
```

**stdio Mode** (for Claude Desktop, CLI tools):
```bash
npm run start:stdio
# Communicates via stdin/stdout
```

**Development Mode** (with hot reload):
```bash
npm run dev
```

## Transport Modes

### HTTP Mode

Use HTTP mode for:
- Web-based AI clients
- Multi-agent architectures
- Stateless MCP connections
- RESTful API interactions

**Endpoints:**
- `GET /health` - Health check (unauthenticated)
- `GET /metrics` - Deployment and instance statistics
- `POST /mcp` - MCP protocol endpoint (StreamableHTTPServerTransport)

**Example Connection:**
```bash
# Health check
curl http://localhost:3000/health

# Metrics
curl http://localhost:3000/metrics

# MCP protocol request
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'
```

### stdio Mode

Use stdio for:
- Claude Desktop integration
- Command-line MCP clients
- Programmatic testing
- Shell script automation

**Example Test:**
```bash
# Simple echo test
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npm run start:stdio

# Automated test suite
npx tsx test-stdio.ts

# Manual test script
./test-stdio-manual.sh
```

## Available Tools

### Reading Tools

#### 1. `read_source`
Read Solidity source code files from the v4-core repository.

**Input:**
- `path` (string): Relative path from `lib/v4-core/src/` (e.g., `PoolManager.sol`)

**Output:**
- `content` (string): Full source code
- `lines` (number): Total line count
- `path` (string): Absolute file path
- `size` (number): File size in bytes
- `lastModified` (string): ISO timestamp

**Example:**
```json
{
  "path": "PoolManager.sol"
}
```

#### 2. `read_storage`
Read contract storage slots (persistent storage only, not transient).

**Input:**
- `address` (string): Contract address
- `slot` (string): Storage slot (hex, e.g., `0x0`)
- `blockTag` (optional): `latest`, `earliest`, `pending`, block number, or block hash
- `rpc` (optional): RPC URL (default: `http://localhost:8545`)

**Output:**
- `value` (string): Raw 32-byte hex value
- `decoded` (optional): Best-effort interpretation (uint256, address, bool, bytes32)

**Example:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "slot": "0x0",
  "blockTag": "latest"
}
```

#### 3. `read_bytecode`
Retrieve deployed bytecode from a contract address.

**Input:**
- `address` (string): Contract address
- `blockTag` (optional): Block identifier
- `rpc` (optional): RPC URL

**Output:**
- `bytecode` (string): Hex-encoded bytecode
- `size` (number): Bytecode size in bytes
- `codeHash` (string): Keccak256 hash
- `isEmpty` (boolean): True if no code deployed (EOA)

**Example:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}
```

#### 4. `read_events`
Query and decode contract event logs.

**Input:**
- `address` (string): Contract address
- `eventSignature` (optional): Event signature (e.g., `Transfer(address,address,uint256)`)
- `topics` (optional): Indexed topics filter
- `fromBlock` (optional): Starting block (default: `earliest`)
- `toBlock` (optional): Ending block (default: `latest`)
- `rpc` (optional): RPC URL

**Output:**
- `events` (array): Event logs with block info
- `count` (number): Total events returned
- `fromBlock` (string): Actual starting block
- `toBlock` (string): Actual ending block

**Example:**
```json
{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "eventSignature": "Transfer(address,address,uint256)",
  "fromBlock": 1000000,
  "toBlock": 1000100
}
```

### Execution Tools

#### 5. `simulate_tx`
Simulate transactions without sending them to the network.

**Input:**
- `to` (string): Target contract address
- `data` (string): Calldata (hex)
- `from` (optional): Sender address
- `gasLimit` (optional): Gas limit
- `value` (optional): ETH value in wei (hex)
- `abi` (optional): Contract ABI for decoding
- `functionName` (optional): Function name for decoding
- `blockNumber` (optional): Block to simulate at
- `stateOverrides` (optional): State overrides by address
- `rpc` (optional): RPC endpoint

**Output:**
- `result` (string): Return data (hex)
- `decoded` (optional): Decoded return value
- `reverted` (boolean): Whether call reverted
- `revertReason` (optional): Decoded revert reason
- `revertData` (optional): Raw revert data

**Example:**
```json
{
  "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "data": "0x70a08231000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "abi": [...],
  "functionName": "balanceOf"
}
```

#### 6. `send_tx`
Send actual transactions to the network.

**Input:**
- `to` (optional): Target address (omit for deployment)
- `data` (string): Transaction data / bytecode
- `from` (optional): Sender address
- `value` (optional): ETH value in wei (hex)
- `gasLimit` (optional): Gas limit (auto-estimated)
- `gasPrice` (optional): Legacy gas price
- `maxFeePerGas` (optional): EIP-1559 max fee
- `maxPriorityFeePerGas` (optional): EIP-1559 priority fee
- `nonce` (optional): Transaction nonce
- `privateKey` (optional): Private key for signing
- `confirmations` (optional): Confirmations to wait (default: 1)
- `rpc` (optional): RPC endpoint

**Output:**
- `txHash` (string): Transaction hash
- `blockNumber` (string): Block number
- `blockHash` (string): Block hash
- `gasUsed` (string): Gas consumed
- `effectiveGasPrice` (string): Actual gas price
- `status` (enum): `success` or `reverted`
- `logs` (array): Event logs
- `contractAddress` (optional): Deployed contract address
- `from` (string): Sender address
- `to` (optional): Recipient address

**Example:**
```json
{
  "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "data": "0xa9059cbb...",
  "value": "0x0",
  "privateKey": "0x..."
}
```

#### 7. `impersonate`
Impersonate any address on Anvil (testing only).

**Input:**
- `address` (string): Address to impersonate
- `stopImpersonating` (optional): Stop impersonation (default: false)
- `rpc` (optional): RPC endpoint (must be Anvil)

**Output:**
- `success` (boolean): Whether operation succeeded
- `address` (string): Impersonated address
- `active` (boolean): Current impersonation status
- `balance` (optional): Current balance

**Example:**
```json
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}
```

#### 8. `create_snapshot`
Create Anvil state snapshot for later revert.

**Input:**
- `name` (optional): Human-readable snapshot name
- `description` (optional): Snapshot description
- `rpc` (optional): RPC endpoint (must be Anvil)

**Output:**
- `snapshotId` (string): Unique snapshot identifier
- `name` (optional): Snapshot name
- `blockNumber` (number): Block at snapshot
- `blockHash` (string): Block hash
- `timestamp` (number): Block timestamp
- `created` (number): Unix timestamp created

**Example:**
```json
{
  "name": "before-attack-simulation",
  "description": "State before testing exploit scenario"
}
```

#### 9. `revert_snapshot`
Revert blockchain state to a previous snapshot.

**Input:**
- `snapshotId` (string): Snapshot ID or name
- `rpc` (optional): RPC endpoint (must be Anvil)

**Output:**
- `success` (boolean): Whether revert succeeded
- `snapshotId` (string): Reverted snapshot ID
- `blockNumber` (number): Block after revert
- `blockHash` (string): Block hash after revert
- `timestamp` (number): Block timestamp
- `reverted` (boolean): State revert confirmation

**Example:**
```json
{
  "snapshotId": "before-attack-simulation"
}
```

### Tracing Tools

#### 10. `trace_transaction`
Trace an existing transaction by hash using debug_traceTransaction.

**Input:**
- `txHash` (string): Transaction hash to trace (64 hex characters)
- `tracer` (optional): Tracer type - `callTracer`, `prestateTracer`, `4byteTracer`, or omit for raw opcode trace
- `tracerConfig` (optional): Tracer-specific configuration object
  - For `callTracer`: `{ onlyTopCall: true }` to exclude subcalls
- `rpc` (optional): RPC URL (default: `http://localhost:8545`)

**Output:**
- `result`: Trace result (format depends on tracer type)
  - **callTracer**: Call tree with `type`, `from`, `to`, `value`, `gas`, `input`, `output`
  - **prestateTracer**: Pre-execution state of all touched accounts
  - **4byteTracer**: Map of function selectors to call counts
  - **No tracer**: Full opcode trace with `structLogs` array
- `txHash` (string): Transaction hash that was traced

**Example:**
```json
{
  "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "tracer": "callTracer",
  "tracerConfig": {
    "onlyTopCall": true
  }
}
```

**Use Cases:**
- Debug failed transactions
- Analyze gas usage patterns
- Understand contract interactions
- Detect reentrancy or complex call paths

#### 11. `trace_call`
Trace a call without sending transaction using debug_traceCall.

**Input:**
- `to` (string): Target contract address
- `data` (string): Calldata (hex encoded)
- `from` (optional): Sender address
- `value` (optional): ETH value in wei (hex)
- `blockTag` (optional): Block to trace at - `latest`, `earliest`, `pending`, `safe`, `finalized`, or block number
- `tracer` (optional): Tracer type (same as `trace_transaction`)
- `tracerConfig` (optional): Tracer configuration
- `rpc` (optional): RPC URL

**Output:**
- `result`: Trace result (format depends on tracer type, same as `trace_transaction`)

**Example:**
```json
{
  "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "data": "0xa9059cbb000000000000000000000000f39fd6e51aad88f6f4ce6ab8827279cfffb922660000000000000000000000000000000000000000000000000de0b6b3a7640000",
  "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "tracer": "callTracer"
}
```

**Use Cases:**
- Debug before sending actual transactions
- Analyze call behavior at specific blocks
- Test state override scenarios
- Investigate potential exploits safely

## Claude Desktop Integration

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "anvil-tools": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-anvil-tools/dist/index.js",
        "--stdio"
      ],
      "env": {
        "AUDIT_MCP_PORT": "3000",
        "MAINNET_RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
        "ETHERSCAN_API_KEY": "your_etherscan_api_key"
      }
    }
  }
}
```

**Important**: Use absolute paths for the `command` args. Restart Claude Desktop after configuration changes.

## Configuration

### Alchemy Multi-Network Support

Set `ALCHEMY_API_KEY` to enable access to any Alchemy-supported network without additional configuration:

```bash
ALCHEMY_API_KEY=your_alchemy_api_key
```

Use any [Alchemy network slug](https://docs.alchemy.com/reference/supported-chains) directly:

| Network | Slug |
|---------|------|
| Ethereum | `eth-mainnet`, `eth-sepolia` |
| Arbitrum | `arb-mainnet`, `arb-sepolia` |
| Optimism | `opt-mainnet`, `opt-sepolia` |
| Polygon | `polygon-mainnet`, `polygon-amoy` |
| Base | `base-mainnet`, `base-sepolia` |

New networks are supported automatically as Alchemy adds them - no code changes needed.

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AUDIT_MCP_PORT` | HTTP server port | `3000` |
| `AUDIT_MCP_HOST` | HTTP server host | `0.0.0.0` |
| `AUDIT_MCP_DB_PATH` | SQLite database path | `./audit-mcp.db` |
| `ANVIL_PORT_START` | Anvil port range start | `8545` |
| `ANVIL_PORT_END` | Anvil port range end | `8555` |
| `ANVIL_DEFAULT_CHAIN_ID` | Default chain ID | `31337` |
| `ALCHEMY_API_KEY` | Alchemy API key (enables multi-network) | - |
| `MAINNET_RPC_URL` | Mainnet RPC (overrides Alchemy) | - |
| `SEPOLIA_RPC_URL` | Sepolia RPC (overrides Alchemy) | - |
| `ETHERSCAN_API_KEY` | Etherscan API key | - |
| `ARBISCAN_API_KEY` | Arbiscan API key | - |
| `LOG_LEVEL` | Logging level | `info` |
| `LOG_FILE` | Log file path | `./audit-mcp.log` |
| `SLITHER_PATH` | Path to Slither binary | `/usr/local/bin/slither` |
| `SOLC_PATH` | Path to Solc binary | `/usr/local/bin/solc` |

## Architecture

### Project Structure

```
src/
├── index.ts              # Entry point (HTTP/stdio mode detection)
├── server.ts             # Express app + McpServer setup
├── config.ts             # Configuration management
├── anvil/
│   ├── manager.ts        # Anvil process lifecycle
│   └── types.ts          # Anvil-related types
├── state/
│   └── manager.ts        # SQLite state management
├── tools/
│   ├── index.ts          # Tool registration with McpServer.registerTool()
│   ├── reading.ts        # Reading tools (4): source, storage, bytecode, events
│   ├── execution.ts      # Execution tools (5): simulate, send, impersonate, snapshots
│   └── tracing.ts        # Tracing tools (2): trace_transaction, trace_call
└── utils/
    ├── errors.ts         # Error handling
    └── validation.ts     # Zod schemas
```

### Database Schema

SQLite tables for state persistence:

- **deployments** - Contract deployment records
- **anvil_instances** - Running Anvil instances
- **audit_sessions** - Audit session metadata
- **audit_findings** - Discovered vulnerabilities
- **audit_notes** - Session notes

### Transport Architecture

```
┌─────────────────┐
│  AI Agent/User  │
└────────┬────────┘
         │
    ┌────┴────┐
    │  HTTP   │  stdio
    │  /mcp   │  (stdin/stdout)
    └────┬────┘
         │
    ┌────┴──────────────────┐
    │  McpServer (stateless)│
    │  + registerTool API   │
    └────┬──────────────────┘
         │
    ┌────┴────────┐
    │   11 Tools  │
    │  Reading: 4 │
    │ Execution: 5│
    │  Tracing: 2 │
    └────┬────────┘
         │
    ┌────┴────────┐
    │    viem +   │
    │    Anvil    │
    └─────────────┘
```

## Testing

### Automated Tests

```bash
# Run stdio transport tests
npx tsx test-stdio.ts

# Run all tool tests
npm test
```

### Manual Testing

```bash
# Test stdio transport
./test-stdio-manual.sh

# Test specific tools
npm run test:tools
```

### Example Workflows

**1. Read and analyze contract:**
```bash
# Read source
read_source { "path": "PoolManager.sol" }

# Get bytecode
read_bytecode { "address": "0x..." }

# Read storage
read_storage { "address": "0x...", "slot": "0x0" }
```

**2. Simulate and execute transaction:**
```bash
# Simulate first
simulate_tx {
  "to": "0x...",
  "data": "0x...",
  "abi": [...]
}

# If successful, send
send_tx {
  "to": "0x...",
  "data": "0x...",
  "privateKey": "0x..."
}
```

**3. Test with snapshots:**
```bash
# Create snapshot
create_snapshot { "name": "clean-state" }

# Run test transactions
send_tx { ... }

# Revert to clean state
revert_snapshot { "snapshotId": "clean-state" }
```

## Development

### Building

```bash
# Build TypeScript
npm run build

# Watch mode
npm run dev
```

### Linting

```bash
# Run ESLint
npm run lint

# Format code
npm run format
```

### Adding New Tools

1. Define input/output schemas with Zod in `src/tools/`
2. Implement handler function
3. Export tool in tools object
4. Register in `src/tools/index.ts`
5. Add documentation to TOOLS.md

## Security Considerations

- **Impersonation**: Only works on Anvil, not production networks
- **Private Keys**: Never log or expose private keys
- **RPC Access**: Use secure RPC endpoints with authentication
- **State Overrides**: Validate carefully to prevent unintended behavior
- **Gas Limits**: Always set reasonable gas limits to prevent DoS
- **Input Validation**: All inputs validated with Zod schemas

## Troubleshooting

### Common Issues

**Server won't start:**
- Check port availability: `lsof -i :3000`
- Verify environment variables in `.env`
- Check database permissions for `AUDIT_MCP_DB_PATH`

**Anvil connection fails:**
- Ensure Anvil is installed: `which anvil`
- Check port range configuration
- Verify no port conflicts

**Tool execution errors:**
- Check RPC endpoint availability
- Verify contract address exists
- Ensure sufficient gas for transactions
- Check impersonation is only used on Anvil

**stdio mode issues:**
- Ensure one JSON-RPC message per line
- Check stderr for log messages (stdout is for responses)
- Verify MCP protocol version compatibility

## Performance

- **Connection Pooling**: Reuses viem clients across requests
- **State Caching**: SQLite for fast state retrieval
- **Snapshot Registry**: In-memory tracking for quick snapshot operations
- **Concurrent Requests**: Express handles multiple concurrent MCP connections

## Roadmap

- [ ] Advanced analysis tools (Slither integration)
- [ ] Call graph visualization
- [ ] AST parsing utilities
- [ ] Multi-chain support
- [x] Enhanced trace analysis (debug_traceTransaction, debug_traceCall)
- [ ] Gas optimization suggestions
- [ ] Security pattern detection

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Update documentation
5. Submit a pull request

## License

MIT

## Resources

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [viem Documentation](https://viem.sh/)
- [Foundry Anvil](https://book.getfoundry.sh/anvil/)
- [TOOLS.md](./TOOLS.md) - Detailed tool reference

## Support

- Issues: [GitHub Issues](https://github.com/yourusername/mcp-anvil-tools/issues)
- Documentation: [TOOLS.md](./TOOLS.md)
- Examples: See `test-tools.ts` for usage examples