BNB Testnet Faucet MCP

A Model Context Protocol (MCP) compliant server for BNB Testnet faucet payouts with passkey and IP address verification.

Architecture

This project uses a modular, domain-driven architecture:

src/
├── core/                    # Core business logic
│   ├── config/             # Configuration management
│   ├── blockchain/         # Blockchain transaction handling
│   ├── mcp/               # MCP protocol implementation
│   └── verification/      # Passkey & IP verification logic
└── services/              # Service layer (API endpoints)
    ├── verification/      # Verification service API
    └── mcp/               # MCP server API

Key Changes from v1.0

• New Architecture: Modular, domain-driven design with clear separation of concerns
• Verification Method: Changed from GitHub-based to Passkey + IP Address verification
• Coding Style: Functional approach with dataclasses, immutable configs, and service classes
• Structure: Organized by domain (core/services) rather than by technology

Services

Verification Service

FastAPI service that verifies requests using passkey and IP address validation.

Verification Process:

1. Validates passkey format
2. Validates IP address format
3. Checks rate limiting (24-hour cooldown per passkey+IP combination)
4. Returns verification result

Configuration

Create .env file:

DB_PATH=data/verifications.db
RATE_LIMIT_HOURS=24

Run Locally

cd src/services/verification
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
python -m uvicorn src.services.verification.api:app --host 0.0.0.0 --port 8080

API Endpoints

Health Check:

curl http://localhost:8080/health

Verify Request:

curl -X POST http://localhost:8080/verify \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x1234...",
    "passkey": "your-passkey-here",
    "ip_address": "192.168.1.1"
  }'

Response:

{
  "wallet_address": "0x1234...",
  "verified": true,
  "confidence": 1.0,
  "reason": "Passkey and IP address validated successfully",
  "passkey_id": "abc123...",
  "ip_address": "192.168.1.1"
}

MCP Server

MCP protocol compliant server that processes BNB Testnet (tBNB) payout requests.

Configuration

Create .env file:

BSC_RPC_URL=https://data-seed-prebsc-1-s1.bnbchain.org:8545
TREASURY_PRIVATE_KEY=your_private_key_or_mnemonic
DEFAULT_PAYOUT_AMOUNT=0.3
PAYOUT_GAS_LIMIT=21000
CHAIN_ID=97
VERIFICATION_SERVICE_URL=http://localhost:8080

Run Locally

cd src/services/mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m uvicorn src.services.mcp.api:app --host 0.0.0.0 --port 8090

MCP Protocol Endpoints

List Tools:

curl -X POST http://localhost:8090/mcp/v1/tools \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Call Tool:

curl -X POST http://localhost:8090/mcp/v1/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "issue_tbnb",
      "arguments": {
        "wallet_address": "0x1234...",
        "passkey": "your-passkey",
        "ip_address": "192.168.1.1"
      }
    }
  }'

Docker Deployment

Quick Start

1. Create .env file in project root:

BSC_RPC_URL=https://data-seed-prebsc-1-s1.bnbchain.org:8545
TREASURY_PRIVATE_KEY=your_private_key_or_mnemonic
DEFAULT_PAYOUT_AMOUNT=0.3
PAYOUT_GAS_LIMIT=21000
CHAIN_ID=97

2. Build and run:

docker-compose up -d --build

3. Check status:

docker-compose ps
docker-compose logs -f

Individual Services

Verification Service:

docker build -f src/services/verification/Dockerfile -t bnb-faucet-verification:latest .
docker run -d -p 8080:8080 -v verification_db:/app/data bnb-faucet-verification:latest

MCP Server:

docker build -f src/services/mcp/Dockerfile -t bnb-faucet-mcp:latest .
docker run -d -p 8090:8090 --env-file .env bnb-faucet-mcp:latest

Verification Process

Passkey Requirements

• Format: Base64-like string (alphanumeric + +/=-_)
• Length: Minimum 32 characters
• Storage: Stored as SHA-256 hash

IP Address Requirements

• Format: Valid IPv4 or IPv6 address
• Validation: Standard IP address format checking
• Optional: Can be restricted to specific IP ranges

Rate Limiting

• Scope: Per passkey + IP address combination
• Cooldown: 24 hours (configurable)
• Storage: SQLite database

Available MCP Tools

issue_tbnb

Request tBNB payout for a verified passkey holder.

Parameters:

• wallet_address (required): BSC wallet address
• passkey (required): Passkey for verification
• ip_address (required): Client IP address
• requester_id (optional): Requester identifier

Returns:

• Transaction hash
• Verification details
• Request status

Note: This tool sends tBNB on BSC Testnet (tBNB).

Development

Project Structure

src/
├── core/
│   ├── config/          # Configuration dataclasses
│   ├── blockchain/      # Transaction service
│   ├── mcp/            # MCP protocol handlers
│   └── verification/   # Passkey/IP validation
└── services/
    ├── verification/    # Verification API
    └── mcp/            # MCP server API

Coding Style

• Functional approach: Pure functions where possible
• Dataclasses: Immutable configuration and data structures
• Service classes: Encapsulated business logic
• Type hints: Full type annotations
• Separation of concerns: Clear boundaries between layers

Testing

# Test verification service
curl http://localhost:8080/health

# Test MCP server
curl http://localhost:8090/health

# Test MCP tools
curl -X POST http://localhost:8090/mcp/v1/tools \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

AWS EC2 Deployment

1. Install Docker (Amazon Linux 2023):

sudo dnf install -y docker
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker ec2-user

2. Install Docker Compose:

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

3. Deploy:

# Transfer code to EC2
scp -r bnb-testnet-faucet-mcp ec2-user@your-ec2-ip:~/

# On EC2
cd ~/bnb-testnet-faucet-mcp
# Create .env file with your secrets
nano .env

# Build and run
DOCKER_BUILDKIT=0 docker-compose up -d --build

4. Configure Security Group:
   • Open ports 8080 (verification) and 8090 (MCP server)
   • Allow inbound TCP traffic from your IP or 0.0.0.0/0

Environment Variables

Verification Service

• DB_PATH: Database file path (default: data/verifications.db)
• RATE_LIMIT_HOURS: Rate limit cooldown in hours (default: 24)

MCP Server

• BSC_RPC_URL: BSC RPC endpoint (required)
• TREASURY_PRIVATE_KEY: Private key or mnemonic (required)
• DEFAULT_PAYOUT_AMOUNT: Default payout amount (default: 0.3)
• PAYOUT_GAS_LIMIT: Gas limit for transactions (default: 21000)
• CHAIN_ID: Chain ID (default: 97 for BSC testnet)
• VERIFICATION_SERVICE_URL: Verification service URL (default: http://localhost:8080)

License

See LICENSE file for details.