bnb-testnet-faucet-mcp

[buggythanos]

Description

This PR implements a complete rewrite of the BNB Testnet Faucet MCP server (v2.0), transitioning from a GitHub-based verification system to a passkey + IP address verification system with a modular, domain-driven architecture.

Key Changes:

• Architecture Refactor: Migrated from flat structure (mcp_server/, verification_service/) to modular domain-driven design (src/core/ for business logic, src/services/ for APIs)
• Verification Method: Replaced GitHub username verification with passkey + IP address validation, eliminating external API dependencies
• Code Quality: Refactored from procedural code with global state to functional + OOP hybrid approach using dataclasses, immutable configs, and service classes
• Configuration Management: Centralized configuration using dataclass-based settings instead of scattered os.getenv() calls
• Dependencies: Removed requests library and GitHub API dependency, improving performance and reliability

Benefits:

• Faster response times (no external API calls)
• Better privacy (no GitHub account required)
• More control over validation rules
• Cleaner, more maintainable codebase with better testability
• Full type safety with comprehensive type hints

Fixes # (bnb-chain#156)

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Manual Testing:

1. Health Endpoints: Verified both verification service (/health) and MCP server (/health) respond correctly
2. Verification Service: Tested passkey format validation, IP address validation, and rate limiting with SQLite database
3. MCP Protocol: Tested tools/list and tools/call endpoints with JSON-RPC 2.0 compliance
4. End-to-End Flow: Tested complete payout flow from verification request to blockchain transaction

Test Commands:

# Health checks
curl http://localhost:8080/health
curl http://localhost:8090/health

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

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

# MCP tools/call
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": {...}}'

Docker Testing:

• Built and tested both services using docker-compose up -d --build
• Verified container health and service communication
• Tested with production-like environment variables

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes