tbnb MCP

tBNB MCP

该存储库托管了模型上下文协议（MCP）驱动的水龙头体验的实验架构和原型服务。

服务

验证服务(verification_service/)

FastAPI服务，通过具有速率限制的GitHub API验证构建者。

配置（可选）

创建 verification_service/.env 要提高GitHub API的速率限制：

GITHUB_TOKEN=ghp_your_personal_access_token_here

获取GitHub代币：

1. 首选https://github.com/settings/tokens
2. 点击“生成新令牌（经典）”
3. 设置过期和检查 read:user 范围
4. 复制令牌并将其添加到 .env

费率限制：

• 无令牌：每个IP每小时60个请求
• 带令牌：5000个请求/小时

在本地运行（PowerShell）

cd verification_service
python -m venv .venv
.venv\Scripts\activate               # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8080

测试服务：

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

预期响应：

{
  "wallet_address": "0x1234",
  "verified": true,
  "confidence": 0.75,
  "reason": "All verification checks passed",
  "github_user_id": 1,
  "repo_count": 8,
  "account_age_days": 5000
}

MCP服务器(mcp_server/)

FastAPI编排层，通过验证服务验证钱包请求，并在获得批准后通过Web3（默认情况下为BSC测试网）提交实际的tBNB转账。

配置机密

创建 mcp_server/.env （切勿承诺）：

BSC_RPC_URL=https://data-seed-prebsc-1-s1.bnbchain.org:8545
TREASURY_PRIVATE_KEY=
DEFAULT_PAYOUT_AMOUNT=0.01          # optional, defaults to 0.3
PAYOUT_GAS_LIMIT=21000               # optional
VERIFICATION_SERVICE_URL=http://localhost:8080/verify

服务器将解释 TREASURY_PRIVATE_KEY 当它包含多个单词（逗号或空格）时，作为助记符。确保钱包有足够的tBNB来支付支出和汽油。

在本地运行（PowerShell）

cd mcp_server
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload --port 8090

请求付款：

curl -X POST http://localhost:8090/requests ^
  -H "Content-Type: application/json" ^
  -d "{\"builder_id\": \"user-123\", \"wallet_address\": \"0x1234\", \"channel\": \"discord\"}"

预期响应（tx哈希在BSC测试网上是真实的）：

{
  "request_id": "UUID",
  "status": "approved",
  "message": "Disbursement submitted to BSC testnet",
  "tx_hash": "0x...",
  "verification": {
    "wallet_address": "0x1234...",
    "verified": true,
    "confidence": 1.0,
    "reason": "Stubbed verification service"
  }
}

LangChain聊天机器人(langchain_bot/)

该角色扮演BNB支持AI的交互式CLI。当构建器请求tBNB时，代理通过LangChain工具调用MCP服务器并中继返回的事务哈希。

配置机密

创建 langchain_bot/.env 与：

OPENAI_API_KEY=sk-...
MCP_SERVER_URL=http://127.0.0.1:8090/requests   # or your tunnel URL

在本地运行（PowerShell）

cd langchain_bot
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python chat.py

保持验证服务和MCP服务器运行。示例会话：

builder> hey support, can I get tBNB sent to 0x76c9...15ce?
assistant> Payout approved ... tx_hash=0x...

端到端流程（顺序）

sequenceDiagram
    participant Builder
    participant Bot as LangChain Bot
    participant OpenAI as OpenAI Chat API
    participant GitHub as GitHub API
    participant MCP as MCP Server
    participant Verify as Verification Service
    participant Chain as BSC Testnet

    Builder->>Bot: "I want tBNB, my GitHub is @username"
    Bot->>OpenAI: Chat completion w/ tool schemas
    OpenAI-->>Bot: Function-call to `issue_tbnb` (github_username, repo_url?)
    Bot->>GitHub: GET /repos/{username}/{repo}/contents/bsc.address
    alt Wallet found in GitHub repo
        GitHub-->>Bot: bsc.address file content (wallet address)
        Bot->>MCP: POST /requests (github_username, wallet_address, builder_id, channel)
        MCP->>Verify: POST /verify (github_username, wallet_address)
        Verify->>GitHub: GET /users/{username} (verify account exists)
        alt GitHub user exists
            GitHub-->>Verify: User data (id, repos, created_at)
            Verify->>Verify: Check: account age >= 30 days
            Verify->>Verify: Check: repo count >= 1
            Verify->>Verify: Check: rate limit (24h cooldown per user_id)
            alt Verification passes
                Verify-->>MCP: { verified: true, github_user_id, confidence }
                MCP->>Chain: Send tBNB transaction (signed)
                Chain-->>MCP: Tx hash / receipt
                MCP->>Verify: POST /record-payout (github_user_id)
                Verify-->>MCP: Payout recorded
                MCP-->>Bot: Approval + tx_hash + verification details
                Bot-->>OpenAI: Tool result / assistant message
                OpenAI-->>Bot: Final LLM reply text
                Bot-->>Builder: Confirmation + tx_hash + verification status
            else Verification fails
                Verify-->>MCP: { verified: false, reason: "Account too new" / "No repos" / "Rate limited" }
                MCP-->>Bot: HTTP 403 - Verification failed + reason
                Bot-->>OpenAI: Tool result (error message)
                OpenAI-->>Bot: Final LLM reply text
                Bot-->>Builder: Error message explaining why verification failed
            end
        else GitHub user not found
            GitHub-->>Verify: 404 Not Found
            Verify-->>MCP: { verified: false, reason: "GitHub account not found" }
            MCP-->>Bot: HTTP 403 - Verification failed
            Bot-->>OpenAI: Tool result (error message)
            OpenAI-->>Bot: Final LLM reply text
            Bot-->>Builder: Error: GitHub account not found
        end
    else Wallet not found in GitHub repo
        GitHub-->>Bot: 404 Not Found (bsc.address file missing)
        Bot-->>OpenAI: Tool result (error: wallet not found)
        OpenAI-->>Bot: Final LLM reply text
        Bot-->>Builder: Error: bsc.address file not found in repository
    end

验证（通过GitHub）

验证服务执行以下检查：

1. GitHub帐户已存在：验证GitHub用户名是否存在
2. 存储库计数：生成器必须至少有一个公共存储库
3. 账户年龄：GitHub帐户必须至少有30天的历史
4. 速率限制：每个GitHub用户每24小时只能收集一次tBNB

数据库模式

验证服务使用SQLite来跟踪速率限制：

• github_user_id （INTEGER PRIMARY KEY）：GitHub的数字用户ID
• last_payout_timestamp （TIMESTAMP）：用户上次收到tBNB的时间

API变更

现在所有请求都需要 github_username:

• 验证服务: POST /verify 预期 github_username 在请求正文中
• MCP服务器: POST /requests 预期 github_username 在请求正文中
• 郎链机器人: issue_tbnb 工具现在需要 github_username 参数

速率限制

每个GitHub用户ID（不是用户名）都强制执行速率限制，防止用户通过更改用户名绕过限制。在验证过程中检查24小时冷却时间，并在成功支付后记录。

为了防止用户使用多个存储库，验证服务将检查url、用户名、存储库、文件名、钱包地址和提交哈希。存储在SQL中的数据是用户名、提交哈希、钱包地址和时间戳。