diff --git a/python/bnb-testnet-faucet-mcp-main/.gitignore b/python/bnb-testnet-faucet-mcp-main/.gitignore
new file mode 100644
index 0000000..12aeee2
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/.gitignore
@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
diff --git a/python/bnb-testnet-faucet-mcp-main/CHANGES.md b/python/bnb-testnet-faucet-mcp-main/CHANGES.md
new file mode 100644
index 0000000..44a8fe6
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/CHANGES.md
@@ -0,0 +1,109 @@
+# BNB Testnet Faucet MCP - Complete Rewrite Summary
+
+## What Changed
+
+### Architecture
+- **Old**: Flat structure with `mcp_server/` and `verification_service/`
+- **New**: Modular structure with `src/core/` (business logic) and `src/services/` (APIs)
+
+### Verification Method
+- **Old**: GitHub username → GitHub API → Account verification
+- **New**: Passkey + IP Address → Local validation → Rate limiting
+
+### Coding Style
+- **Old**: Procedural with global variables, direct imports
+- **New**: Functional + OOP hybrid, dataclasses, service classes, dependency injection
+
+### Configuration
+- **Old**: Global `os.getenv()` calls scattered throughout code
+- **New**: Centralized dataclass-based configuration in `core/config/settings.py`
+
+### Dependencies
+- **Old**: `requests` for GitHub API, external API dependency
+- **New**: No external API calls, pure validation logic
+
+## New Structure
+
+```
+src/
+├── core/                    # Domain layer (no framework deps)
+│   ├── config/             # Configuration management
+│   ├── blockchain/         # Transaction handling
+│   ├── mcp/                # MCP protocol
+│   └── verification/       # Passkey & IP validation
+└── services/               # Application layer (FastAPI)
+    ├── verification/       # Verification API
+    └── mcp/                # MCP server API
+```
+
+## Key Features
+
+### Passkey Validation
+- Format validation (base64-like, min 32 chars)
+- SHA-256 hashing for storage
+- HMAC comparison for verification
+
+### IP Address Validation
+- Standard IP format checking (IPv4/IPv6)
+- Optional IP whitelist/blacklist support
+- Combined with passkey for rate limiting
+
+### Rate Limiting
+- Per passkey + IP address combination
+- 24-hour cooldown (configurable)
+- SQLite storage with proper indexing
+
+### MCP Protocol
+- Full JSON-RPC 2.0 compliance
+- Tools discovery (`tools/list`)
+- Tool execution (`tools/call`)
+- Error handling with proper codes
+
+## Benefits
+
+1. **No External Dependencies**: No GitHub API calls, faster responses
+2. **Better Privacy**: No need for GitHub accounts
+3. **More Control**: Custom validation rules
+4. **Cleaner Code**: Modular, testable, maintainable
+5. **Type Safety**: Full type hints, dataclasses
+6. **Better Organization**: Domain-driven design
+
+## Migration
+
+See `MIGRATION_GUIDE.md` for detailed migration steps.
+
+## Testing
+
+Use the test script:
+```bash
+python scripts/test_mcp.py http://your-server:8090
+```
+
+Or test manually:
+```bash
+# Health
+curl http://localhost:8090/health
+
+# 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": "0x...",
+        "passkey": "your-passkey",
+        "ip_address": "192.168.1.1"
+      }
+    }
+  }'
+```
+
diff --git a/python/bnb-testnet-faucet-mcp-main/DEPLOYMENT.md b/python/bnb-testnet-faucet-mcp-main/DEPLOYMENT.md
new file mode 100644
index 0000000..4c71dae
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/DEPLOYMENT.md
@@ -0,0 +1,91 @@
+# Deployment Guide
+
+## Quick Start
+
+### 1. Local Development
+
+```bash
+# Clone and setup
+git clone <repo>
+cd bnb-testnet-faucet-mcp
+
+# Create .env file
+cp .env.example .env
+# Edit .env with your values
+
+# Run with Docker Compose
+docker-compose up -d --build
+
+# Or run services individually (see README)
+```
+
+### 2. AWS EC2 Deployment
+
+#### Prerequisites
+- EC2 instance (Amazon Linux 2023 recommended)
+- Docker and Docker Compose installed
+- Security Group configured
+
+#### Steps
+
+**1. Transfer code to EC2:**
+```bash
+# On local machine
+tar --exclude='.git' --exclude='venv' --exclude='__pycache__' \
+    --exclude='*.db' --exclude='data' \
+    -czf bnb-faucet-mcp.tar.gz bnb-testnet-faucet-mcp/
+
+scp -i your-key.pem bnb-faucet-mcp.tar.gz ec2-user@your-ec2-ip:~/
+```
+
+**2. On EC2:**
+```bash
+# Extract code
+tar -xzf ~/bnb-faucet-mcp.tar.gz
+cd ~/bnb-testnet-faucet-mcp
+
+# Create .env file
+nano .env
+# Add your configuration values
+
+# Build and run
+DOCKER_BUILDKIT=0 docker-compose up -d --build
+
+# Check status
+docker-compose ps
+docker-compose logs -f
+```
+
+**3. Configure Security Group:**
+- Port 8080: Verification service
+- Port 8090: MCP server
+- Source: Your IP or 0.0.0.0/0 for testing
+
+**4. Test:**
+```bash
+# From local machine
+curl http://your-ec2-ip:8090/health
+curl -X POST http://your-ec2-ip:8090/mcp/v1/tools \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
+```
+
+## Environment Variables
+
+### Required
+- `BSC_RPC_URL`: BSC RPC endpoint
+- `TREASURY_PRIVATE_KEY`: Wallet private key or mnemonic
+
+### Optional
+- `DEFAULT_PAYOUT_AMOUNT`: Default payout (default: 0.3)
+- `PAYOUT_GAS_LIMIT`: Gas limit (default: 21000)
+- `CHAIN_ID`: Chain ID (default: 97)
+- `DB_PATH`: Database path (default: data/verifications.db)
+- `RATE_LIMIT_HOURS`: Rate limit cooldown (default: 24)
+- `PASSKEY_SECRET_KEY`: Secret for passkey hashing
+- `VERIFICATION_SERVICE_URL`: Verification service URL
+
+## Troubleshooting
+
+See `TROUBLESHOOTING.md` for common issues and solutions.
+
diff --git a/python/bnb-testnet-faucet-mcp-main/LICENSE b/python/bnb-testnet-faucet-mcp-main/LICENSE
new file mode 100644
index 0000000..29f81d8
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/LICENSE
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/python/bnb-testnet-faucet-mcp-main/MCP_COMPLIANCE_ANALYSIS.md b/python/bnb-testnet-faucet-mcp-main/MCP_COMPLIANCE_ANALYSIS.md
new file mode 100644
index 0000000..7678f54
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/MCP_COMPLIANCE_ANALYSIS.md
@@ -0,0 +1,225 @@
+# MCP Protocol Compliance Analysis
+
+## Executive Summary
+
+**Current Status: ❌ NOT MCP COMPLIANT**
+
+Your current implementation is a **REST API** (FastAPI), not an **MCP Server** according to Anthropic's Model Context Protocol specification. While it provides similar functionality, it does not follow the MCP protocol standard.
+
+## What is the MCP Protocol?
+
+The Model Context Protocol (MCP) is a standardized protocol for connecting AI assistants to external tools and data sources. Key characteristics:
+
+1. **Transport Layer**: Uses JSON-RPC 2.0 over:
+   - **stdio** (standard input/output) - for local processes
+   - **SSE** (Server-Sent Events) - for HTTP-based servers
+   - **WebSocket** - for bidirectional communication
+
+2. **Message Format**: JSON-RPC 2.0 with specific MCP methods:
+   - `initialize` - Handshake between client and server
+   - `tools/list` - List available tools
+   - `tools/call` - Execute a tool
+   - `resources/list` - List available resources
+   - `resources/read` - Read a resource
+   - `prompts/list` - List available prompts
+   - `prompts/get` - Get a prompt
+
+3. **Tool Definition**: Tools must follow MCP's tool schema format with:
+   - `name` - Tool identifier
+   - `description` - Tool description
+   - `inputSchema` - JSON Schema for parameters
+
+## Current Implementation Analysis
+
+### What You Have Now
+
+**File**: `mcp_server/main.py`
+
+```python
+# Current: REST API endpoint
+@app.post("/requests", response_model=DisbursementResponse)
+async def request_tbnb(payload: DisbursementRequest) -> DisbursementResponse:
+    # ... verification and payout logic
+```
+
+**Connection Method**: HTTP POST requests
+```python
+# langchain_bot/chat.py
+response = requests.post(
+    MCP_SERVER_URL,  # http://127.0.0.1:8090/requests
+    json=payload,
+    timeout=30,
+)
+```
+
+### Issues with Current Implementation
+
+1. ❌ **Not JSON-RPC 2.0**: Uses REST API instead of JSON-RPC 2.0
+2. ❌ **No MCP Handshake**: Missing `initialize` method
+3. ❌ **No Tool Discovery**: Missing `tools/list` endpoint
+4. ❌ **No Standard Tool Call**: Uses custom `/requests` endpoint instead of `tools/call`
+5. ❌ **Wrong Transport**: Uses HTTP REST instead of stdio/SSE/WebSocket
+6. ❌ **No MCP SDK**: Not using official MCP Python SDK
+
+## What Needs to Change
+
+### Option 1: Implement True MCP Server (Recommended)
+
+Convert your FastAPI server to a proper MCP server using the official MCP Python SDK.
+
+**Required Changes:**
+
+1. **Install MCP SDK**:
+```bash
+pip install mcp
+```
+
+2. **Restructure as MCP Server**:
+```python
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+app = Server("tbnb-mcp")
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="issue_tbnb",
+            description="Request tBNB payout for a verified GitHub user",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "github_username": {
+                        "type": "string",
+                        "description": "GitHub username for verification"
+                    },
+                    "wallet_address": {
+                        "type": "string",
+                        "description": "BSC wallet address"
+                    },
+                    "builder_id": {
+                        "type": "string",
+                        "description": "Builder identifier"
+                    },
+                    "channel": {
+                        "type": "string",
+                        "description": "Support channel"
+                    }
+                },
+                "required": ["github_username", "wallet_address"]
+            }
+        )
+    ]
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "issue_tbnb":
+        # Your existing verification and payout logic
+        result = await process_tbnb_request(arguments)
+        return [TextContent(type="text", text=result)]
+    raise ValueError(f"Unknown tool: {name}")
+
+if __name__ == "__main__":
+    stdio_server(app).run()
+```
+
+3. **Update Client Connection**:
+   - Use MCP client SDK instead of HTTP requests
+   - Connect via stdio or SSE transport
+
+### Option 2: Keep REST API but Add MCP Wrapper
+
+Create a separate MCP server that wraps your existing REST API:
+
+```python
+# mcp_wrapper.py
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+import httpx
+
+app = Server("tbnb-mcp-wrapper")
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    if name == "issue_tbnb":
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                "http://localhost:8090/requests",
+                json=arguments
+            )
+            return [TextContent(type="text", text=response.text)]
+```
+
+## Production Readiness Checklist
+
+### MCP Protocol Compliance
+- [ ] Implement JSON-RPC 2.0 message format
+- [ ] Add `initialize` handshake method
+- [ ] Implement `tools/list` for tool discovery
+- [ ] Implement `tools/call` for tool execution
+- [ ] Use stdio, SSE, or WebSocket transport
+- [ ] Follow MCP tool schema format
+- [ ] Use official MCP SDK
+
+### Security & Best Practices
+- [ ] Input validation on all parameters
+- [ ] Rate limiting per user/IP
+- [ ] Authentication/authorization
+- [ ] Error handling with proper MCP error codes
+- [ ] Logging and monitoring
+- [ ] Environment variable validation
+- [ ] Secure secret management
+- [ ] Transaction idempotency checks
+
+### Code Quality
+- [ ] Type hints throughout
+- [ ] Comprehensive error messages
+- [ ] Unit tests
+- [ ] Integration tests
+- [ ] Documentation
+- [ ] Health check endpoint (if using HTTP)
+
+### Current Issues to Address
+
+1. **Error Handling**: 
+   - Current: Generic HTTP exceptions
+   - Should: Use MCP error codes (e.g., `-32602` for invalid params)
+
+2. **Tool Schema**:
+   - Current: Pydantic models
+   - Should: JSON Schema compatible with MCP
+
+3. **Transport**:
+   - Current: HTTP REST
+   - Should: stdio/SSE/WebSocket with JSON-RPC 2.0
+
+4. **Tool Discovery**:
+   - Current: No discovery mechanism
+   - Should: Implement `tools/list`
+
+## Recommended Next Steps
+
+1. **Immediate**: Decide on Option 1 (full MCP) or Option 2 (wrapper)
+2. **Short-term**: Implement MCP protocol compliance
+3. **Medium-term**: Add comprehensive testing
+4. **Long-term**: Security audit and production deployment
+
+## Resources
+
+- [MCP Specification](https://modelcontextprotocol.io)
+- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
+- [Anthropic MCP Documentation](https://docs.anthropic.com/en/docs/mcp)
+- [MCP Directory Policy](https://support.anthropic.com/en/articles/11697096-anthropic-mcp-directory-policy)
+
+## Conclusion
+
+Your current implementation is a **functional REST API** but **NOT an MCP server**. To be production-ready and MCP-compliant, you need to:
+
+1. Implement the MCP protocol (JSON-RPC 2.0)
+2. Use the official MCP SDK
+3. Follow MCP's tool/resource/prompt patterns
+4. Use appropriate transport mechanisms (stdio/SSE/WebSocket)
+
+Would you like me to help you convert your current implementation to a proper MCP server?
diff --git a/python/bnb-testnet-faucet-mcp-main/MIGRATION_GUIDE.md b/python/bnb-testnet-faucet-mcp-main/MIGRATION_GUIDE.md
new file mode 100644
index 0000000..4774ab2
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/MIGRATION_GUIDE.md
@@ -0,0 +1,162 @@
+# Migration Guide: v1.0 → v2.0
+
+## Major Changes
+
+### 1. Project Structure
+
+**Old (v1.0):**
+```
+mcp_server/
+verification_service/
+```
+
+**New (v2.0):**
+```
+src/
+├── core/          # Business logic
+└── services/      # API endpoints
+```
+
+### 2. Verification Method
+
+**Old:** GitHub username verification
+- Required GitHub account
+- Checked account age, repo count
+- Rate limited per GitHub user ID
+
+**New:** Passkey + IP Address verification
+- No external API dependencies
+- Validates passkey format and IP address
+- Rate limited per passkey + IP combination
+
+### 3. Configuration
+
+**Old:** Global environment variables
+```python
+VERIFICATION_URL = os.getenv("VERIFICATION_SERVICE_URL")
+```
+
+**New:** Dataclass-based configuration
+```python
+config = AppConfig.load()
+config.verification.service_url
+```
+
+### 4. Coding Style
+
+**Old:** Procedural with global state
+**New:** Functional + OOP hybrid with immutable configs
+
+## Migration Steps
+
+### Step 1: Update Environment Variables
+
+**Remove:**
+- `GITHUB_TOKEN` (no longer needed)
+
+**Add:**
+- `PASSKEY_SECRET_KEY` (optional, for passkey hashing)
+- `CHAIN_ID` (optional, defaults to 97)
+
+**Keep:**
+- `BSC_RPC_URL`
+- `TREASURY_PRIVATE_KEY`
+- `DEFAULT_PAYOUT_AMOUNT`
+- `PAYOUT_GAS_LIMIT`
+- `VERIFICATION_SERVICE_URL`
+
+### Step 2: Update API Calls
+
+**Old Verification Request:**
+```json
+{
+  "wallet_address": "0x1234",
+  "github_username": "octocat",
+  "builder_id": "user-123"
+}
+```
+
+**New Verification Request:**
+```json
+{
+  "wallet_address": "0x1234",
+  "passkey": "your-passkey-here",
+  "ip_address": "192.168.1.1"
+}
+```
+
+**Old MCP Tool Call:**
+```json
+{
+  "arguments": {
+    "github_username": "octocat",
+    "wallet_address": "0x1234"
+  }
+}
+```
+
+**New MCP Tool Call:**
+```json
+{
+  "arguments": {
+    "wallet_address": "0x1234",
+    "passkey": "your-passkey",
+    "ip_address": "192.168.1.1"
+  }
+}
+```
+
+### Step 3: Update Docker Deployment
+
+**Old:**
+```bash
+docker-compose up -d --build
+```
+
+**New:**
+```bash
+# Same command, but structure is different
+docker-compose up -d --build
+```
+
+The docker-compose.yml has been updated for the new structure.
+
+### Step 4: Update Client Code
+
+If you have client code calling the APIs:
+
+1. **Replace GitHub username with passkey + IP**
+2. **Update request payloads** to match new schema
+3. **Update response handling** (response structure is similar)
+
+## Breaking Changes
+
+1. **Verification endpoint** now requires `passkey` and `ip_address` instead of `github_username`
+2. **MCP tool arguments** changed from `github_username` to `passkey` + `ip_address`
+3. **Rate limiting** is now per passkey+IP combination instead of GitHub user ID
+4. **No GitHub API dependency** - faster but requires passkey management
+
+## Benefits of v2.0
+
+- ✅ **No external API dependencies** - faster, more reliable
+- ✅ **Better privacy** - no GitHub account required
+- ✅ **More control** - custom validation rules
+- ✅ **Cleaner architecture** - modular, testable
+- ✅ **Better code organization** - domain-driven design
+
+## Rollback Plan
+
+If you need to rollback to v1.0:
+1. Keep the old `mcp_server/` and `verification_service/` directories
+2. Use the old docker-compose.yml (if you have it)
+3. Restore old environment variables
+
+## Testing
+
+After migration, test:
+1. Health endpoints
+2. Verification endpoint with passkey + IP
+3. MCP tools/list endpoint
+4. MCP tools/call endpoint
+5. End-to-end payout flow
+
diff --git a/python/bnb-testnet-faucet-mcp-main/PROJECT_NAME.md b/python/bnb-testnet-faucet-mcp-main/PROJECT_NAME.md
new file mode 100644
index 0000000..25df30e
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/PROJECT_NAME.md
@@ -0,0 +1,15 @@
+# Project Name: BNB Testnet Faucet MCP
+
+This project has been renamed from "tBNB MCP" to **"BNB Testnet Faucet MCP"**.
+
+## What Changed
+
+- **Project Title**: BNB Testnet Faucet MCP
+- **Description**: MCP-compliant server for BNB Testnet (tBNB) faucet payouts
+- **Container Names**: Updated to `bnb-faucet-verification-service` and `bnb-faucet-mcp-server`
+- **Documentation**: All references updated throughout README, architecture docs, and code
+
+## Legacy Code
+
+The old `mcp_server/` and `verification_service/` directories are from v1.0 and can be removed or kept for reference. The new code is in `src/` directory.
+
diff --git a/python/bnb-testnet-faucet-mcp-main/README.md b/python/bnb-testnet-faucet-mcp-main/README.md
new file mode 100644
index 0000000..595c6f5
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/README.md
@@ -0,0 +1,314 @@
+# BNB Testnet Faucet MCP
+
+A Model Context Protocol (MCP) compliant server for BNB Testnet faucet payouts with passkey and IP address verification.
+
+> **Submission to GitHub Issue**: This project is a submission to [bnb-chain/example-hub#156](https://github.com/bnb-chain/example-hub/issues/156) - MCP Wishlist: Faucet Token Distribution Bot.
+
+## 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:
+```env
+DB_PATH=data/verifications.db
+RATE_LIMIT_HOURS=24
+```
+
+#### Run Locally
+
+```bash
+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:**
+```bash
+curl http://localhost:8080/health
+```
+
+**Verify Request:**
+```bash
+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:**
+```json
+{
+  "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:
+```env
+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
+
+```bash
+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:**
+```bash
+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:**
+```bash
+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:
+```env
+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:**
+```bash
+docker-compose up -d --build
+```
+
+3. **Check status:**
+```bash
+docker-compose ps
+docker-compose logs -f
+```
+
+### Individual Services
+
+**Verification Service:**
+```bash
+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:**
+```bash
+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
+
+```bash
+# 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):
+```bash
+sudo dnf install -y docker
+sudo systemctl start docker
+sudo systemctl enable docker
+sudo usermod -aG docker ec2-user
+```
+
+2. **Install Docker Compose:**
+```bash
+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:**
+```bash
+# 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.
diff --git a/python/bnb-testnet-faucet-mcp-main/TROUBLESHOOTING.md b/python/bnb-testnet-faucet-mcp-main/TROUBLESHOOTING.md
new file mode 100644
index 0000000..380c0fe
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/TROUBLESHOOTING.md
@@ -0,0 +1,139 @@
+# Troubleshooting MCP Server Connection Issues
+
+## Connection Timeout Errors
+
+If you're getting connection timeout errors when testing from your local machine:
+
+### 1. Check EC2 Security Group
+
+**Most Common Issue:** Port 8090 is not open in the Security Group.
+
+**Fix:**
+1. AWS Console → EC2 → Your Instance → Security Tab
+2. Click Security Group → Edit Inbound Rules
+3. Add Rule:
+   - Type: Custom TCP
+   - Port: 8090
+   - Source: 0.0.0.0/0 (or your specific IP)
+   - Description: MCP Server HTTP
+4. Save rules
+
+### 2. Verify Containers are Running
+
+**On EC2, run:**
+```bash
+docker ps
+```
+
+You should see both `mcp-server` and `verification-service` running.
+
+**If containers stopped:**
+```bash
+# Check logs for errors
+docker logs mcp-server
+docker logs verification-service
+
+# Restart containers
+docker restart mcp-server verification-service
+```
+
+### 3. Test from Inside EC2
+
+**Test locally on EC2:**
+```bash
+# Health check
+curl http://localhost:8090/health
+
+# 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"}'
+```
+
+If this works locally but not from outside, it's a Security Group issue.
+
+### 4. Check Port Binding
+
+**Verify port is listening:**
+```bash
+sudo netstat -tlnp | grep 8090
+# or
+sudo ss -tlnp | grep 8090
+
+# Check Docker port mapping
+docker port mcp-server
+```
+
+Should show: `0.0.0.0:8090->8090/tcp`
+
+### 5. Check EC2 Instance Firewall
+
+**Amazon Linux 2023:**
+```bash
+# Check if firewall is running
+sudo systemctl status firewalld
+
+# If running, allow port 8090
+sudo firewall-cmd --permanent --add-port=8090/tcp
+sudo firewall-cmd --reload
+```
+
+### 6. Verify Public IP
+
+**Check your instance's public IP:**
+```bash
+# On EC2
+curl http://169.254.169.254/latest/meta-data/public-ipv4
+```
+
+Make sure you're using this IP in your test script.
+
+### 7. Container Logs Check
+
+**Check for startup errors:**
+```bash
+docker logs mcp-server --tail=50
+docker logs verification-service --tail=50
+```
+
+Look for:
+- Missing environment variables
+- Database connection errors
+- Port binding errors
+- Application crashes
+
+## Common Error Messages
+
+### "Connection refused"
+- Container not running → Check `docker ps`
+- Wrong port → Verify port mapping
+- Application crashed → Check logs
+
+### "Connection timeout"
+- Security Group not allowing traffic → Add inbound rule
+- Firewall blocking → Configure firewall
+- Wrong IP address → Verify public IP
+
+### "Method not found"
+- Wrong endpoint URL → Use `/mcp/v1/tools` and `/mcp/v1/tools/call`
+- Wrong request format → Use JSON-RPC 2.0 format
+
+## Quick Test Checklist
+
+- [ ] Security Group allows port 8090
+- [ ] Containers are running (`docker ps`)
+- [ ] Port is listening (`netstat -tlnp | grep 8090`)
+- [ ] Test works locally on EC2 (`curl http://localhost:8090/health`)
+- [ ] Using correct public IP address
+- [ ] No firewall blocking port 8090
+- [ ] Containers have environment variables set
+
+## Still Having Issues?
+
+1. **SSH into EC2** and run all checks above
+2. **Share the output** of:
+   - `docker ps`
+   - `docker logs mcp-server --tail=50`
+   - `curl http://localhost:8090/health`
+   - Security Group inbound rules screenshot
+
diff --git a/python/bnb-testnet-faucet-mcp-main/architecture.md b/python/bnb-testnet-faucet-mcp-main/architecture.md
new file mode 100644
index 0000000..586caeb
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/architecture.md
@@ -0,0 +1,92 @@
+# tBNB Project Architecture
+
+## Introduction
+The project delivers an MCP (Model Context Protocol) server that lets verified builders request and receive 0.3 tBNB directly through BNB AI assistants (Discord, Telegram, web chatbot) without having to front 0.02 BNB on the public faucet.
+
+## Goals and Success Criteria
+1. Reduce onboarding friction: verified builders should receive tBNB in a single conversational flow.
+2. Preserve anti-abuse protections equivalent to the official faucet.
+3. Provide auditable logs for every disbursement and manual override.
+4. Make the architecture deployable inside existing BNB Chain support infrastructure.
+
+## Actors & Systems
+- **Builder**: verified user requesting tBNB.
+- **BNB AI Assistant**: LLM-bound chat entry point (Discord, Telegram, web).
+- **MCP Server**: core service that validates wallets, manages quotas, and triggers payouts.
+- **Verification Source**: proof that the builder already passed Discord/Telegram verification.
+- **Treasury Wallet / Faucet Contract**: holds tBNB and signs transfers.
+- **Ledger & Observability Stack**: storage for requests, decisions, and alerts.
+
+## Current Pain Points
+1. Builders must preload 0.02 BNB just to qualify for the faucet.
+2. The official faucet is difficult to discover from support channels.
+3. Verification context is lost when users are redirected from support to the faucet UI.
+
+```mermaid
+flowchart TD
+    A[Builder opens support ticket] --> B[LLM support replies with faucet link]
+    B --> C[Builder visits faucet UI]
+    C --> D{Wallet has ≥0.02 BNB?}
+    D -- No --> E[Request rejected]
+    D -- Yes --> F[0.3 tBNB sent from faucet wallet]
+```
+
+## Proposed Architecture
+
+### High-Level Flow
+1. Builder engages BNB AI from a verified channel and submits wallet address.
+2. MCP server validates wallet ownership, rate limits, and channel verification.
+3. Upon approval, the MCP server requests a tBNB transfer from the treasury/faucet wallet.
+4. The transaction hash and conversation context are logged.
+
+```mermaid
+sequenceDiagram
+    participant U as Builder
+    participant AI as BNB AI Assistant
+    participant MCP as MCP Server
+    participant VF as Verification Source
+    participant TW as Treasury Wallet
+
+    U->>AI: Request tBNB + wallet
+    AI->>MCP: Submit request payload
+    MCP->>VF: Confirm user verification & quota
+    VF-->>MCP: Verification OK
+    MCP->>TW: Sign & send 0.3 tBNB
+    TW-->>MCP: Tx hash
+    MCP-->>AI: Success + tx hash
+    AI-->>U: Delivery confirmation
+```
+
+### Core Components
+- **Conversation Adapter**: normalizes Discord/Telegram/web payloads into MCP requests.
+- **Eligibility Engine**: enforces verification, wallet sanity checks, abuse heuristics, and per-user quotas.
+- **Payout Orchestrator**: wraps the treasury wallet/faucet contract, queues transactions, and monitors confirmations.
+- **Audit Ledger**: append-only store of requests, decisions, tx hashes, and metadata for compliance.
+- **Monitoring & Alerting**: tracks wallet balances, error rates, and suspicious use (e.g., repeated wallet rotations).
+
+### Data Model (conceptual)
+- `ConversationContext`: user handle, channel, verification status, timestamps.
+- `WalletRecord`: checksum address, last verified owner, risk score, payout history.
+- `Disbursement`: amount, tx hash, gas cost, status, operator overrides.
+
+## Security & Compliance Considerations
+- Require signature (or OAuth token) from the verified Discord/Telegram bot to prevent spoofing.
+- Rate-limit per channel and per wallet; auto-block wallets failing ownership proofs.
+- Keep treasury wallet isolated with hardware key / custodial service; MCP requests should trigger a signer service rather than hold private keys inline.
+- Emit structured logs for every decision to support audits and incident response.
+
+## Operational Concerns
+- **Scalability**: MCP server should be stateless behind load balancer; state persists in datastore.
+- **Reliability**: queue payout requests and retry idempotently if blockchain confirmation is delayed.
+- **Observability**: dashboards for request volume, approval ratios, and treasury balance forecasts.
+- **Runbooks**: document manual refill of tBNB, incident response when abuse heuristics fire, and disaster recovery of ledger data.
+
+## Open Questions
+1. Which verification proofs (Discord role, Telegram token, etc.) should be persisted, and for how long?
+2. Do we need explicit consent logging before sending funds to a wallet shared in chat?
+3. Who funds and manages the treasury wallet replenishment cadence?
+4. Are there jurisdictions requiring KYC/AML checks before dispensing tBNB at this volume?
+
+## Appendix: Diagram Reference
+- Problem funnel: see **Current Pain Points** diagram for legacy experience.
+- Solution flow: see **Proposed Architecture > High-Level Flow** sequence diagram.
\ No newline at end of file
diff --git a/python/bnb-testnet-faucet-mcp-main/docker-compose.yml b/python/bnb-testnet-faucet-mcp-main/docker-compose.yml
new file mode 100644
index 0000000..846bdcb
--- /dev/null
+++ b/python/bnb-testnet-faucet-mcp-main/docker-compose.yml
@@ -0,0 +1,57 @@
+services:
+  verification-service:
+    build:
+      context: .
+      dockerfile: src/services/verification/Dockerfile
+    container_name: bnb-faucet-verification-service
+    ports:
+      - "8080:8080"
+    environment:
+      - DB_PATH=/app/data/verifications.db
+      - RATE_LIMIT_HOURS=24
+    volumes:
+      - verification_db:/app/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 5s
+    networks:
+      - tbnb-network
+
+  mcp-server:
+    build:
+      context: .
+      dockerfile: src/services/mcp/Dockerfile
+    container_name: bnb-faucet-mcp-server
+    ports:
+      - "8090:8090"
+    environment:
+      - BSC_RPC_URL=${BSC_RPC_URL}
+      - TREASURY_PRIVATE_KEY=${TREASURY_PRIVATE_KEY}
+      - DEFAULT_PAYOUT_AMOUNT=${DEFAULT_PAYOUT_AMOUNT:-0.3}
+      - PAYOUT_GAS_LIMIT=${PAYOUT_GAS_LIMIT:-21000}
+      - CHAIN_ID=${CHAIN_ID:-97}
+      - VERIFICATION_SERVICE_URL=http://verification-service:8080
+    depends_on:
+      verification-service:
+        condition: service_healthy
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8090/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 5s
+    networks:
+      - tbnb-network
+
+volumes:
+  verification_db:
+    driver: local
+
+networks:
+  tbnb-network:
+    driver: bridge