# 🔒 MCP Contract Auditor

**Smart Contract Security Audit MCP Server** — Fetch, analyze, and generate audit reports for EVM smart contracts.

Built for [CyOps Arena Hackathon](https://arena.cysic.xyz/) by [Carlys17](https://github.com/Carlys17).

## Features

| Tool | Description |
|------|-------------|
| `audit_contract` | 🔒 **Full audit** — fetch source, scan vulns, analyze holders, generate report |
| `fetch_contract` | Fetch verified contract source code & ABI from Blockscout |
| `scan_vulns` | Scan Solidity source for 15+ vulnerability patterns |
| `check_holders` | Analyze token holder distribution & centralization risk |
| `list_chains` | List all supported EVM chains |

## Supported Chains

Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, Gnosis, Avalanche, zkSync Era, Celo — all via [Blockscout](https://www.blockscout.com/) API (no API key required).

## Vulnerability Detection

| Category | Patterns Detected |
|----------|-------------------|
| 🔴 Reentrancy | Classic reentrancy, cross-function reentrancy |
| 🟠 Access Control | Missing modifiers, tx.origin auth |
| 🟠 External Calls | Unchecked low-level calls, delegatecall, selfdestruct |
| 🟡 Integer | Overflow/underflow (pre-0.8), unchecked arithmetic |
| 🟡 Denial of Service | Unbounded loops, forced ether |
| 🟡 ERC-20 | Missing return values, approve race condition |
| 🔵 Informational | Floating pragma, inline assembly, timestamp dependence |

## Installation

```bash
# Clone
git clone https://github.com/Carlys17/mcp-contract-auditor.git
cd mcp-contract-auditor

# Install dependencies
npm install

# Build
npm run build

# Run
npm start
```

## Usage with Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "contract-auditor": {
      "command": "node",
      "args": ["/path/to/mcp-contract-auditor/dist/index.js"]
    }
  }
}
```

## Example Usage

### Full Audit
```
audit_contract(
  address: "0x1234...abcd",
  chain: "ethereum",
  include_holder_analysis: true
)
```

### Quick Vulnerability Scan
```
scan_vulns(
  source_code: "pragma solidity ^0.8.0; contract Foo { ... }",
  contract_name: "Foo"
)
```

### Check Token Holders
```
check_holders(
  address: "0x1234...abcd",
  chain: "base"
)
```

## Architecture

```
mcp-contract-auditor/
├── src/
│   ├── index.ts                    # MCP server entry (5 tools)
│   ├── types.ts                    # Type definitions
│   ├── tools/
│   │   ├── analyze-vulnerabilities.ts  # 15+ vuln detectors
│   │   ├── holder-analysis.ts      # Token holder analysis
│   │   └── generate-report.ts      # Markdown report generator
│   └── utils/
│       ├── blockscout.ts           # Blockscout API client
│       └── chains.ts               # EVM chain configs
├── package.json
└── tsconfig.json
```

## How It Works

1. **Fetch** — Retrieves verified contract source code from Blockscout API
2. **Analyze** — Runs 15+ pattern-based vulnerability detectors on the source
3. **Holder Check** — Fetches token holder data and calculates Gini coefficient
4. **Report** — Generates a structured markdown audit report with severity ratings

## Disclaimer

This is an automated static analysis tool. It uses pattern matching and heuristics — it is **NOT** a substitute for a professional manual security audit. Always conduct thorough manual review before deploying contracts with real funds.

## License

MIT

---

*Built with ❤️ for CyOps Arena × MiniMax M3 Hackathon*