秘密网络MCP服务器
用于Secret Network区块链集成的生产就绪模型上下文协议（MCP）服务器，使AI助手能够通过安全、经过良好测试的接口与Secret Network进行交互。
   
🎉 项目状态：已完成
所有阶段完成 ✅
- ✅ 第一阶段：基础层（11个模块，372个测试）
- ✅ 第2阶段：MCP工具（60个工具，601个测试）
- ✅ 第三期：MCP提示和资源（2个提示，4个资源）
- ✅ 阶段4：集成测试（5个测试套件，36个测试）
总计：637项测试通过，约22500行代码，生产就绪
🚀 快速开始
# Install dependencies
pip install -e ".[dev]"
# Configure environment
cp .env.example .env
# Run tests
pytest
# Start building!查看综合 入门指南 详细说明。
✨ 特性
完整的MCP工具套件（60个工具）
网络工具 （4个工具）
- 网络配置和切换
- 网络信息和健康检查
- 天然气价格查询
钱包工具 （6个工具）
- HD钱包创建和导入
- 多钱包管理
- 安全钱包切换
银行工具 （5个工具）
- 余额查询
- 代币转移
- 多发送操作
- 供应和面额查询
区块链工具 （5个工具）
- 块查询（最新、按高度、按哈希）
- 节点信息
- 同步状态监控
帐户工具 （3个工具）
- 账户信息
- 交易记录
- 事务计数
交易工具 （5个工具）
- 交易查询
- 交易搜索
- 天然气估算
- 交易模拟
- 状态跟踪
打桩工具 （8工具）
- 验证器查询和选择
- 委托管理
- 取消授权和重新授权
- 委托跟踪
奖励工具 （4个工具）
- 奖励查询
- 奖励提取
- 撤回地址配置
- 社区池查询
治理工具 （6个工具）
- 提案清单和详细信息
- 提案提交
- 对提案进行投票
- 存款管理
- 投票跟踪
合同工具 （10个工具）
- 合同上传和部署
- 合同实例化
- 合同执行（书面）
- 合同查询（阅读）
- 批量合同执行
- 合同信息
- 合同迁移
- 代码信息
IBC工具 （4个工具）
- 跨链代币转移
- IBC频道查询
- 频道信息
- Denom跟踪
MCP提示（2个提示）
秘密网络指南
- 全面使用指南
- 特定主题的帮助（网络、钱包、代币、质押、合约、治理、IBC）
- 安全说明和最佳做法
- 错误处理指南
智能合约指南
- 完整的合同生命周期文档
- 操作特定指南（上传、实例化、执行、查询、迁移、批处理）
- 隐私功能说明
- 示例和故障排除
MCP资源（4个资源）
会话状态 (secret://session/state)
- 当前网络和活动钱包
- 会话元数据和状态
钱包列表 (secret://wallets/list)
- 所有已加载的带有地址的钱包
- 活动钱包指示
网络配置 (secret://network/config)
- 网络类型和端点
- 链ID和天然气价格
顶级验证器 (secret://validators/top)
- 按投票权排名的顶级验证器
- 缓存以提高性能
核心基础设施
类型系统
- 全面的Pydantic v2型号
- 对所有输入进行严格验证
- 清除错误消息
配置管理
- 基于环境的配置
- 网络配置文件（测试网、主网）
- 可自定义设置
错误处理
- 分层异常系统（10种错误类型）
- 带建议的结构化错误消息
- 详细的错误上下文
结构化日志记录
- 使用structlog进行两级调试日志记录
- JSON和控制台输出格式
- 请求/响应跟踪
缓存层
- 基于TTL的缓存与LRU逐出
- 自动缓存失效
- 缓存统计和监控
会话管理
- 安全会话生命周期
- 多钱包支持
- 线程安全操作
连接池
- 线程安全的LCD客户端池
- 自动连接管理
- 池统计
输入验证
- 地址验证（bech32）
- 金额验证
- 交易参数验证
- 安全检查
安全模块
- 钱包加密（Fernet+PBKDF2）
- 支出限额
- 速率限制
- 密码要求
HD钱包
- 全面实施BIP32/BIP44/SLIP10
- 多账户支持
- 记忆生成
📚 文档
🏗️ 建筑
高级概述
┌─────────────────────────────────────────────────────────────┐
│ MCP Server Layer │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MCP Tools │ │ MCP Prompts │ │MCP Resources │ │
│ │ (60 tools) │ │ (2 prompts) │ │ (4 resources)│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Core Infrastructure │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Session │ │ Cache │ │Security │ │Validation│ │
│ │ Manager │ │ Layer │ │ Module │ │ Engine │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ SDK Layer │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Client Pool │ │ HD Wallet │ │
│ │ (Connection) │ │ (BIP44) │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Secret Network Blockchain │
│ (Testnet: pulsar-3 / Mainnet: secret-4) │
└─────────────────────────────────────────────────────────────┘模块组织
mcp-scrt/
├── src/mcp_scrt/
│ ├── types.py # Pydantic models and enums
│ ├── constants.py # Network, gas, cache constants
│ ├── config.py # Configuration management
│ ├── utils/
│ │ ├── errors.py # Exception hierarchy
│ │ └── logging.py # Structured logging
│ ├── core/
│ │ ├── cache.py # Caching layer
│ │ ├── session.py # Session management
│ │ ├── validation.py # Input validation
│ │ └── security.py # Security features
│ ├── sdk/
│ │ ├── client.py # Connection pool
│ │ └── wallet.py # HD wallet
│ ├── tools/ # 60 MCP tools (11 categories)
│ │ ├── base.py
│ │ ├── network.py
│ │ ├── wallet.py
│ │ ├── bank.py
│ │ ├── blockchain.py
│ │ ├── account.py
│ │ ├── transaction.py
│ │ ├── staking.py
│ │ ├── rewards.py
│ │ ├── governance.py
│ │ ├── contract.py
│ │ └── ibc.py
│ ├── prompts/ # MCP prompts
│ │ ├── guide.py
│ │ └── contracts.py
│ └── resources/ # MCP resources
│ ├── session.py
│ ├── wallets.py
│ ├── network.py
│ └── validators.py
└── tests/
├── unit/ # 601 unit tests (29 modules)
└── integration/ # 36 integration tests (5 suites)🧪 测试
测试覆盖率
Total Tests: 637
├── Unit Tests: 601 (29 modules)
│ ├── Foundation: 372 tests
│ └── Tools: 229 tests
└── Integration Tests: 36 (5 suites)
├── Transfer workflow: 5 tests
├── Staking workflow: 4 tests
├── Contract workflow: 6 tests
├── Error scenarios: 11 tests
└── Caching behavior: 10 tests
Pass Rate: 100% ✅
Coverage: Comprehensive (all modules)运行测试
# All tests
pytest
# Unit tests only
pytest tests/unit/
# Integration tests only
pytest tests/integration/
# Specific module
pytest tests/unit/test_wallet.py
# With coverage
pytest --cov=mcp_scrt --cov-report=html
# Verbose output
pytest -v
# Show print statements
pytest -s测试质量
- 测试驱动开发（TDD） -所有代码开发测试优先
- 综合模拟 -独立单元测试
- 集成测试 -真实工作流验证
- 错误场景覆盖率 -测试所有错误路径
- 边缘案例测试 -边界条件已验证
🔒 安全
钱包安全
- 加密：Fernet对称加密
- 导出密钥：PBKDF2有600000次迭代
- 密码要求：强密码强制
- 存储：仅在内存中，从不持久化到磁盘
交易安全
- 支出限额：可配置每笔交易限额
- 确认：大型交易需要
- 验证：执行前验证所有输入
- 速率限制：防止虐待
网络安全
- 超文本传输安全协议：所有RPC通信都已加密
- 输入消毒：防止注射攻击
- 地址验证：严格的bech32验证
- 错误消息：未暴露敏感数据
🛠️ 配置
环境变量
创建一个 .env 文件：
# Network
SECRET_NETWORK=testnet # testnet, mainnet, or custom
# Testnet Configuration
SECRET_TESTNET_URL=https://lcd.testnet.secretsaturn.net
SECRET_TESTNET_CHAIN_ID=pulsar-3
# Mainnet Configuration
SECRET_MAINNET_URL=https://lcd.mainnet.secretsaturn.net
SECRET_MAINNET_CHAIN_ID=secret-4
# Security
SPENDING_LIMIT=10000000 # 10 SCRT in uscrt
CONFIRMATION_THRESHOLD=1000000 # 1 SCRT in uscrt
# Performance
MAX_CONNECTIONS=10
CACHE_TTL_DEFAULT=60
# Logging
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_FORMAT=json # json or console
DEBUG=false # Extra verbose logging网络交换
from mcp_scrt.core.session import Session
from mcp_scrt.types import NetworkType
# Use testnet (for development)
session = Session(network=NetworkType.TESTNET)
# Use mainnet (for production)
session = Session(network=NetworkType.MAINNET)📦 安装
先决条件
- Python 3.13+
- pip或uv包管理器
安装
# Clone repository
git clone https://github.com/yourusername/mcp-scrt.git
cd mcp-scrt
# Install dependencies (choose one)
pip install -e ".[dev]" # Using pip
uv pip install -e ".[dev]" # Using uv (faster)
# Configure environment
cp .env.example .env
# Edit .env with your settings
# Verify installation
pytest💡 用法示例
基本代币转移
from mcp_scrt.core.session import Session
from mcp_scrt.sdk.client import ClientPool
from mcp_scrt.tools.base import ToolExecutionContext
from mcp_scrt.tools.wallet import ImportWalletTool
from mcp_scrt.tools.bank import SendTokensTool
from mcp_scrt.types import NetworkType
# Setup
session = Session(network=NetworkType.TESTNET)
session.start()
pool = ClientPool(network=NetworkType.TESTNET)
context = ToolExecutionContext(session=session, client_pool=pool, network=NetworkType.TESTNET)
# Import wallet
import_tool = ImportWalletTool(context)
await import_tool.run({
"name": "my_wallet",
"mnemonic": "your 24 word mnemonic here..."
})
# Send tokens
send_tool = SendTokensTool(context)
result = await send_tool.run({
"recipient": "secret1recipientaddress...",
"amount": "1000000", # 1 SCRT
"denom": "uscrt",
"memo": "Payment"
})
print(f"Transaction: {result['data']['txhash']}")质押和奖励
from mcp_scrt.tools.staking import GetValidatorsTool, DelegateTool
from mcp_scrt.tools.rewards import GetRewardsTool, WithdrawRewardsTool
# Get validators
validators_tool = GetValidatorsTool(context)
validators = await validators_tool.run({"limit": 10})
# Delegate
delegate_tool = DelegateTool(context)
await delegate_tool.run({
"validator_address": validators['data']['validators'][0]['operator_address'],
"amount": "5000000" # 5 SCRT
})
# Check rewards
rewards_tool = GetRewardsTool(context)
rewards = await rewards_tool.run({})
# Withdraw rewards
withdraw_tool = WithdrawRewardsTool(context)
await withdraw_tool.run({})智能合约
from mcp_scrt.tools.contract import (
UploadContractTool,
InstantiateContractTool,
ExecuteContractTool,
QueryContractTool
)
# Upload contract
upload_tool = UploadContractTool(context)
upload_result = await upload_tool.run({"wasm_byte_code": wasm_base64})
code_id = upload_result['data']['code_id']
# Instantiate
instantiate_tool = InstantiateContractTool(context)
instantiate_result = await instantiate_tool.run({
"code_id": code_id,
"init_msg": {"count": 0},
"label": "my_counter"
})
contract_address = instantiate_result['data']['contract_address']
# Execute
execute_tool = ExecuteContractTool(context)
await execute_tool.run({
"contract_address": contract_address,
"execute_msg": {"increment": {}}
})
# Query
query_tool = QueryContractTool(context)
result = await query_tool.run({
"contract_address": contract_address,
"query_msg": {"get_count": {}}
})更多示例请参见 Get-Started.md.
🤝 贡献
该项目遵循严格的开发标准：
开发工作流程
- 测试驱动开发（TDD） -先写测试
- 代码审查 -所有更改均已审核
- 文档 -用代码更改更新文档
- 类型安全 -在任何地方使用类型提示
- 错误处理 -全面的错误处理
代码规范
- 风格：黑色格式的PEP 8
- 代码检查：用于快速、全面脱毛的褶边
- 类型检查：mypy用于静态类型检查
- 测试：pytest，覆盖率目标为100%
- 文档：带示例的文档字符串
运行质量检查
# Format code
black src/ tests/
# Lint code
ruff check src/ tests/
# Type check
mypy src/
# Run tests
pytest --cov=mcp_scrt📊 项目统计
Lines of Code: ~22,500
├── Source Code: ~10,500
└── Test Code: ~12,000
Test Coverage: 637 tests (100% pass)
├── Unit Tests: 601
└── Integration: 36
Modules: 40+
├── Core: 11
├── Tools: 11
├── Prompts: 2
└── Resources: 4
Features: 66+
├── Tools: 60
├── Prompts: 2
└── Resources: 4🗺️ 路线图
✅ 完成
- \[x\] 第一阶段：基础层（100%）
- \[x\] 第2阶段：MCP工具（100%）
- \[x\] 第三期：提示和资源（100%）
- \[x\] 阶段4：集成测试（100%）
🔮 未来的增强功能
- \[\]WebSocket支持实时更新
- \[\]用于复杂查询的GraphQL端点
- \[\]支持多签名钱包
- \[\]硬件钱包集成（Ledger、Trezor）
- \[\]高级缓存策略
- \[\]监控和指标仪表板
- \[\]性能优化
- \[\]MCP服务器的其他功能
📄 许可证
MIT许可证-请参阅 许可证 详细信息文件
🔗 链接
- 秘密网络: https://scrt.network/
- 文档: https://docs.scrt.network/
- MCP协议: https://modelcontextprotocol.io/
- 测试网水龙头: https://faucet.pulsar.scrttestnet.com/
🙏 致谢
- 区块链和SDK的秘密网络团队
- MCP协议的拟人化
- 优秀图书馆的开源社区
💬 支持
- 问题:
- 讨论:
- Discord 的中文翻译是“不和谐”或“纷争”。: 秘密网络不和
______________________________________________________________________
采用测试驱动开发构建 | 生产就绪安全 | 综合文档
由以下材料制成❤️ 秘密网络生态系统