completed faucet mcp example

[leonine17]

Description

@0xlucasliao @robot-ux

This PR adds a new MCP (Model Context Protocol) server implementation for secure, rate-limited faucet token distribution on BSC testnet. This addresses the requirements outlined in Issue #156 for a modular, secure MCP with built-in identity and rate-limiting capabilities for faucet distribution.

Summary of Changes

• New MCP Server Implementation: Added a complete MCP-compliant server (mcp_server/) that implements JSON-RPC 2.0 over HTTP for MCP protocol compatibility
• Verification Service: Added a FastAPI-based verification service (verification_service/) that performs GitHub-based identity verification with anti-abuse mechanisms
• Docker Deployment: Provided ready-to-deploy Docker configuration with docker-compose.yml and individual Dockerfiles for both services
• Comprehensive Documentation: Created detailed README with deployment instructions, MCP protocol usage examples, and production deployment guide

Key Features Implemented

1. Identity & Anti-Abuse Layer

   • GitHub-based identity verification (account age, repository count)
   • Rate limiting with 24-hour cooldown per GitHub user ID
   • SQLite database for tracking payout history

2. Rate Limiting & Enforcement

   • Per-identity cooldown window (0.3 tBNB per 24 hours per user)
   • Configurable policies via environment variables
   • Automatic rejection with clear error messages

3. Faucet Transaction Layer

   • Manages custodial faucet signer (supports mnemonic or private key)
   • Broadcasts token transfers with retry logic
   • Network support for BSC testnet
   • Auto gas estimation and controlled payout amounts

4. MCP Protocol Compliance

   • Implements JSON-RPC 2.0 over HTTP
   • Standard MCP endpoints: /mcp/v1/tools and /mcp/v1/tools/call
   • Tool discovery and execution following MCP specification

5. Production-Ready Deployment

   • Dockerized services with health checks
   • Environment-based configuration
   • AWS deployment guide included
   • Database persistence via Docker volumes

Motivation and Context

The goal is to provide a secure, fair, and scalable faucet solution that prevents automated drainers while allowing real developers to test on-chain. This implementation provides a reusable foundation for community tools (reward bots, quests, grant distributions, etc.) as requested in Issue #156.

Fixes #156

Type of change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• 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?

Local Testing

1. Docker Compose Deployment:

   docker-compose up -d
   docker-compose ps  # Verify both services are running
   docker-compose logs -f  # Monitor logs

2. Health Check Endpoints:

   curl http://localhost:8080/health  # Verification service
   curl http://localhost:8090/health  # MCP server

3. MCP Protocol Testing:

   • 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 (with test GitHub username and wallet):

     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": {
             "github_username": "octocat",
             "wallet_address": "0x1234567890123456789012345678901234567890"
           }
         }
       }'

4. Verification Service Testing:

   curl -X POST http://localhost:8080/verify \
     -H "Content-Type: application/json" \
     -d '{
       "wallet_address": "0x1234",
       "github_username": "octocat"
     }'

Test Scenarios Verified

• ✅ GitHub account verification (exists, has repos, account age)
• ✅ Rate limiting enforcement (24-hour cooldown)
• ✅ MCP protocol compliance (JSON-RPC 2.0 format)
• ✅ Transaction submission to BSC testnet
• ✅ Error handling for invalid requests
• ✅ Database persistence across container restarts
• ✅ Health check endpoints for monitoring

Production Deployment

The implementation has been deployed to AWS EC2 for demonstration purposes and is ready for use. The deployment includes:

• Both services running in Docker containers
• Database persistence configured
• Health monitoring endpoints active

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 (Manual testing performed, unit tests can be added in future PR)
• New and existing unit tests pass locally with my changes (N/A - new feature)

Additional Notes

• The implementation uses SQLite for rate limiting storage. For production, consider migrating to a managed database service (AWS RDS, PostgreSQL, etc.)
• GitHub token is optional but recommended for higher API rate limits (5000/hour vs 60/hour)
• The MCP server supports both JSON-RPC 2.0 format and simplified direct format for easier integration
• All sensitive configuration is handled via environment variables (never committed to repository)

[leonine17]

can i get some tBNB for the live demo