Metadata-Version: 2.4
Name: contractscan-mcp
Version: 0.1.0
Summary: ContractScan MCP Server — multi-engine Solidity vulnerability scanner for LLM agents
Author-email: ContractScan <hello@raccoonworld.xyz>
License: MIT
Project-URL: Homepage, https://raccoonworld.xyz
Project-URL: Repository, https://github.com/h33min/contractscan
Project-URL: Documentation, https://github.com/h33min/contractscan/blob/main/contractscan_mcp/README.md
Project-URL: Bug Tracker, https://github.com/h33min/contractscan/issues
Keywords: solidity,smart-contract,security,vulnerability-scanner,mcp,model-context-protocol,slither,blockchain,ethereum,auditing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: slither-analyzer>=0.11.5
Requires-Dist: anthropic>=0.86.0
Requires-Dist: semgrep>=1.80.0
Provides-Extra: ai
Requires-Dist: google-generativeai>=0.8.0; extra == "ai"
Requires-Dist: openai>=1.0.0; extra == "ai"

# ContractScan MCP Server

Expose ContractScan's multi-engine Solidity vulnerability scanner as a
**Model Context Protocol (MCP)** server. Once connected, any MCP-compatible
AI tool (Claude Desktop, Cursor, Windsurf, Cline, …) can scan smart contracts
directly from a conversation.

## Why MCP?

| Tool | Engines |
|------|---------|
| Slither-MCP | Slither only |
| Aderyn-MCP | Aderyn only |
| **ContractScan MCP** | Slither + Semgrep + Mythril + AI cross-verification |

## Requirements

- Python 3.11+
- `pip install contractscan-mcp`
- `solc` installed (`solc-select install 0.8.20 && solc-select use 0.8.20`)

## Quick Start

### Install

```bash
pip install contractscan-mcp
```

### Test it works

```bash
contractscan-mcp --help
```

---

## IDE Setup

### Claude Desktop (macOS / Windows)

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}
```

Restart Claude Desktop. You should see **ContractScan** in the MCP tools list.

---

### Cursor

Open **Cursor Settings → MCP** (or edit `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}
```

Restart Cursor. ContractScan tools will appear in the Composer context.

---

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GOOGLE_API_KEY": "AIza..."
      }
    }
  }
}
```

Restart Windsurf. ContractScan will be available in Cascade.

---

### Cline (VS Code)

In VS Code, open Cline settings and add to **MCP Servers**:

```json
{
  "contractscan": {
    "command": "contractscan-mcp",
    "env": {
      "ANTHROPIC_API_KEY": "sk-ant-..."
    }
  }
}
```

---

### Claude Code (CLI)

Add to your project's `CLAUDE.md`:

```markdown
## MCP Tools

This project uses ContractScan MCP for smart contract security scanning.

Install: `pip install contractscan-mcp`

Add to `~/.claude/settings.json`:
\`\`\`json
{
  "mcpServers": {
    "contractscan": {
      "command": "contractscan-mcp",
      "env": { "ANTHROPIC_API_KEY": "YOUR_KEY" }
    }
  }
}
\`\`\`
```

Or run directly from the Claude Code terminal:

```bash
# Scan a single file
echo '{"tool":"scan_file","args":{"file_path":"contracts/Token.sol"}}' \
  | contractscan-mcp

# Or use Claude Code with MCP enabled (add to settings.json first)
```

---

## Available Tools

### `scan_contract`

Scan Solidity source code passed as a string.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `solidity_code` | string | required | Full Solidity source |
| `filename` | string | `"contract.sol"` | Filename shown in reports |
| `generate_report` | bool | `true` | Generate AI narrative report |
| `anthropic_api_key` | string | env `ANTHROPIC_API_KEY` | BYOK Anthropic key |
| `openai_api_key` | string | env `OPENAI_API_KEY` | BYOK OpenAI key |
| `tier` | string | `"free"` | `"free"` / `"basic"` / `"pro"` |

### `scan_file`

Scan a local `.sol` file or directory of Solidity files.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `file_path` | string | required | Absolute or relative path |
| `generate_report` | bool | `true` | Generate AI narrative report |
| `anthropic_api_key` | string | env `ANTHROPIC_API_KEY` | BYOK Anthropic key |
| `openai_api_key` | string | env `OPENAI_API_KEY` | BYOK OpenAI key |
| `tier` | string | `"free"` | `"free"` / `"basic"` / `"pro"` |

### `get_engines`

List all registered scan engines and their availability.

```json
{
  "engines": [
    {"name": "slither",  "tier": "free",  "available": true},
    {"name": "mythril",  "tier": "basic", "available": true},
    {"name": "semgrep",  "tier": "basic", "available": true},
    {"name": "ai",       "tier": "free",  "available": true}
  ]
}
```

### `get_report`

Retrieve the most recent scan result from the current session.

---

## Analysis Tiers

| Tier | Engines included |
|------|-----------------|
| `free` | Slither + AI |
| `basic` | Slither + Semgrep + Mythril + AI |
| `pro` | All engines |

---

## API Keys

The server reads API keys from environment variables or from the tool call arguments (BYOK):

| Variable | Use |
|----------|-----|
| `ANTHROPIC_API_KEY` | Claude-based AI report / detection |
| `GOOGLE_API_KEY` | Gemini-based AI report / detection |
| `OPENAI_API_KEY` | GPT-4o-based AI report / detection |

At least one AI key is recommended for full reports. Static analysis
(Slither / Semgrep / Mythril) works without any key.

---

## Example Usage (in Claude Desktop)

Once connected, you can use ContractScan in natural language:

> **"Scan this contract for vulnerabilities"** — paste your Solidity code
>
> **"Check `/path/to/contracts/Token.sol` for security issues"** — scan a local file
>
> **"What engines are available?"** — list configured engines

---

## Impact on Existing Features

The MCP server runs as a separate process using **stdio transport**.
It does **not** modify or affect the existing ContractScan web API or FastAPI application.
