# Prover MCP

> **⚠️ Testnet Only**: This MCP is for Sepolia testnet only.

A Model Context Protocol (MCP) server that enables AI assistants to control Succinct Prover Network operations following the [official Succinct workflow](https://docs.succinct.xyz/docs/provers/running-a-prover/quickstart).

## Prerequisites

> **⚠️ Security Notice**: Use only fresh test wallets for Sepolia testnet. Never use mainnet private keys!

### Required Software
- **Node.js 18+** - [Download here](https://nodejs.org/)
- **Docker Desktop** - [Download here](https://docs.docker.com/get-started/get-docker/)
  - ⚠️ Must be running before setup

### Required Blockchain Assets  
1. **Fresh Ethereum Wallet** 
   - Create a new wallet (MetaMask, etc.)
   - Get Sepolia ETH from [faucet](https://sepolia.etherscan.io/)
   - Export private key (64 hex characters, no 0x prefix)

2. **PROVE Tokens**
   - Get 1000+ PROVE tokens from [official faucet](https://docs.google.com/forms/d/e/1FAIpQLSfgTpBL_wMWyyoxT6LxuMhiu-bex0cBg9kRTmxoKw3XOluOCA/viewform)
   - Minimum 1000 PROVE required for staking

## 🚀 Quick Setup

### Installation
```bash
git clone https://github.com/d3lta02/prover-mcp.git
cd prover-mcp
npm install
npm run build
```

### Setup Options

**Option 1: Interactive Setup (Recommended)**
```bash
npm run init
# Choose: Interactive Setup
# Select: AI client preference  
# Optional: Add credentials during setup
```

**Option 2: Auto Setup (Fastest)**
```bash
npm run init
# Choose: Auto Setup
# Automatically configures detected AI clients
```
### Check Prover MCP & You're Ready
```bash
npm start

# Succinct Prover Network MCP Server running
```

Both methods create:
- 📄 `.env` file with configuration template
- 🤖 AI client MCP configurations (Claude/Cursor)
- 📋 Next steps following official Succinct workflow

## Configuration Methods

### Method 1: MCP Config (Recommended)
Environment variables are set directly in your AI client's MCP configuration:

**Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Cursor IDE**: `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "succinct-prover": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/your/prover-mcp",
      "env": {
        "PROVER_ADDRESS": "your_prover_contract_address",
        "PRIVATE_KEY": "your_64_character_private_key_no_0x_prefix"
      }
    }
  }
}
```

### Method 2: Environment File
Edit the `.env` file created by setup:

```bash
# Edit with your real credentials
PROVER_ADDRESS=0x1234567890123456789012345678901234567890
PRIVATE_KEY=1234567890123456789012345678901234567890123456789012345678901234
```

> **💡 Pro Tip**: MCP config method bypasses tool cache issues and provides better reliability.

## Official Succinct Workflow

The setup follows the [official 5-step Succinct workflow](https://docs.succinct.xyz/docs/provers/running-a-prover/quickstart):

1. **✅ Requirements** (Automated by setup)
   - Fresh Ethereum wallet with Sepolia ETH
   - 1000+ PROVE tokens from faucet
   - Docker Desktop running

2. **🏗️ Create Prover Contract** (Manual)
   - Visit: https://staking.sepolia.succinct.xyz/prover
   - Connect wallet & create prover
   - Save prover address (different from wallet address!)

3. **💰 Stake PROVE Tokens** (Manual) 
   - Visit: https://staking.sepolia.succinct.xyz
   - Stake minimum 1000 PROVE tokens

4. **⚙️ Calibrate Hardware** (AI Assisted)
   - Command: *"Calibrate my prover hardware"*

5. **🚀 Run Prover** (AI Assisted)
   - Command: *"Run Succinct Prover"*

## Usage After Setup

### Basic Commands
- 💬 **"Run Succinct Prover"** - Start the prover and earn PROVE tokens
- 💬 **"Calibrate my prover hardware"** - Optimize performance settings  
- 💬 **"Show Succinct workflow"** - Check setup progress
- 💬 **"Get my prover status"** - View current earnings and performance

### Advanced Commands  
- 💬 **"Get proof requests"** - View available proof requests
- 💬 **"Get my account balance"** - Check PROVE token balance
- 💬 **"Stop my prover"** - Gracefully stop the prover

## Manual Terminal Monitoring

For advanced users who want to monitor prover logs directly in terminal:

```bash
# Find your container ID
docker ps | grep succinct

# Stream live logs
docker logs -f CONTAINER_ID

# Monitor resource usage  
docker stats CONTAINER_ID
```

> **💡 Note**: Replace CONTAINER_ID with your actual container ID. The MCP provides smart log viewing, but terminal monitoring offers real-time streaming for power users.

## How It Works

The MCP server provides secure access to Succinct Prover Network operations:

1. **Environment Loading**: Credentials loaded from MCP config (priority) or .env file
2. **Docker Integration**: Official Succinct Docker images with hardware optimization
3. **AI Commands**: Natural language interface to prover operations
4. **Security**: Sepolia testnet only, credentials never logged

The MCP configuration ensures environment variables are available to all tools, bypassing cache issues.

## Troubleshooting

### Common Issues

**❌ "Environment validation failed"**
- Ensure credentials are set in MCP config or .env file
- Restart your AI client completely after configuration changes

**❌ "Docker not found"**  
- Install and start Docker Desktop
- Verify: `docker --version`

**❌ "Tool cache issues"**
- Use MCP config method instead of .env file
- MCP config bypasses tool cache limitations

**❌ "No PROVE tokens"**
- Get tokens from [official faucet](https://docs.google.com/forms/d/e/1FAIpQLSfgTpBL_wMWyyoxT6LxuMhiu-bex0cBg9kRTmxoKw3XOluOCA/viewform)
- Minimum 1000 PROVE required for staking

### Debug Commands
```bash
npm run validate  # Validate installation
npm run init      # Re-run setup process
npm test         # Run test suite
```

## Security

> **🔒 CRITICAL SECURITY NOTES**

- **Testnet Only**: This MCP only works with Sepolia testnet
- **Fresh Wallets**: Use dedicated test wallets, never mainnet wallets
- **Private Keys**: Never commit credentials to version control
- **Official Sources**: Only use official Succinct URLs and contracts

All credential files are automatically git-ignored for security.

## Development

### Build
```bash
npm run build
```

### Testing
```bash
npm test
npm run validate
```

### File Structure
```
src/
├── index.ts           # MCP server entry point
├── main.ts           # CLI argument handling  
├── cli/init.ts       # Interactive setup tool
├── tools/prover/     # Prover network tools
├── tools/network/    # Network status tools
└── tools/monitoring/ # Performance monitoring
```

## Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature-name`
3. Follow the [official Succinct documentation](https://docs.succinct.xyz/)
4. Test with Sepolia testnet only
5. Submit pull request

## Resources

- 📖 [Official Succinct Documentation](https://docs.succinct.xyz/)
- 🌐 [Succinct Prover Network](https://sepolia.succinct.xyz/)
- 💰 [PROVE Token Faucet](https://docs.google.com/forms/d/e/1FAIpQLSfgTpBL_wMWyyoxT6LxuMhiu-bex0cBg9kRTmxoKw3XOluOCA/viewform)
- 🏗️ [Prover Staking Interface](https://staking.sepolia.succinct.xyz/)

## License

MIT License - See LICENSE file for details.

---

**⚡ Ready to start earning PROVE tokens? Run `npm run init` and follow the setup!**

> **💡 Important**: The `cwd` (current working directory) parameter is automatically set by `npm run init` to ensure relative paths work correctly across different installations.