内容
# Regen 网络 MCP 服务器
> 一个提供编程接口的模型上下文协议（MCP）服务器，用于访问 Regen 网络区块链 - 使 AI 代理和开发者能够与生态信用市场互动。
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## 概述
该 MCP 服务器实现了与 [Regen 网络](https://www.regen.network/) 的无缝交互，这是一个专为生态资产验证和交易而设计的区块链平台。通过标准化的接口，您可以：
- 🌍 查询生态信用类型、类别和批次
- 💰 分析市场动态和销售订单
- 📊 执行投资组合影响分析
- 🔍 比较方法论框架
- ⛓️ 访问区块链数据（银行、治理、分配模块）
- 🤖 使 AI 代理参与环境市场
### 什么是 Regen 网络？
Regen 网络是一个专门为生态信用设计的区块链基础设施，支持多样化的资产类型：
- **碳信用**（CO2e 封存和减少）
- **生物多样性信用**（栖息地保护和恢复）
- **再生农业指标**（土壤健康、放牧管理）
该网络提供透明、可验证的生态项目跟踪，具有链上溯源。
### 什么是 MCP？
[模型上下文协议](https://modelcontextprotocol.io) 是一个标准化的接口，用于连接 AI 系统与外部数据源和工具。该服务器实现了 MCP，使 Regen 网络可被 AI 代理（如 Claude、ChatGPT）和自定义应用程序访问。
## 功能
### 🛠️ **45+ 区块链工具**
- **银行模块**（11 个工具）：账户余额、代币供应、计价单位元数据
- **分配模块**（9 个工具）：验证者奖励、委托人信息、社区池
- **治理模块**（8 个工具）：提案、投票、存款、计票结果
- **市场模块**（5 个工具）：销售订单、定价、允许的计价单位
- **生态信用模块**（4 个工具）：信用类型、类别、项目、批次
- **篮子模块**（5 个工具）：篮子操作、余额、费用
- **分析模块**（3 个工具）：投资组合影响、市场趋势、方法论比较
### 📖 **8 个交互式提示**
常见任务的引导式工作流：
- 区块链探索和入门
- 生态信用查询工作坊
- 市场调查
- 项目发现
- 信用批次分析
- 查询构建器辅助
- 配置设置
- 完整功能参考
### 🔧 **企业功能**
- 具有可靠性的多个端点故障转移
- 可配置的缓存层
- 类型安全的 Pydantic 模型
- 异步/等待以提高性能
- 全面的错误处理，带有可重试性信号
- 健康监测和指标
### 🔄 **API 弹性（v3.1）**
客户端包含强化的重试/回退逻辑：
- **瞬态错误**（5xx、429、超时）自动重试，指数回退 + 抖动
- **客户端错误**（4xx 除 429 外）立即失败，不浪费重试尝试
- 所有错误包含 `retryable` 和 `retry_after_ms` 字段，供下游客户端使用
- `fetch_all_pages()` 助手消除代理侧分页循环
### 🏷️ **信用类别名称解析（v3.2）**
信用类别名称现直接从链上锚定元数据 IRI 中解析：
- **权威名称**：`schema:name` 来自 `https://api.regen.network/data/v2/metadata-graph/{iri}`
- **源注册表**：提取 `regen:sourceRegistry`（例如，“城市森林信用”适用于 C02）
- **缓存**：解析元数据的 1 小时 TTL，失败的 5 分钟 TTL
- **无需猜测**：C01=“Verified Carbon Standard”等类别名称来自链上，而非硬编码映射
### 📊 **摘要模式**
`/ecocredits/batches` 端点支持聚合：
```bash
# 按信用类型获取摘要，而不是遍历所有批次
curl "https://regen.gaiaai.xyz/regen-api/ecocredits/batches?summary=true&fetch_all=true"
```
返回按类型划分的已发行/可交易/已退休信用额，减少常见的多页面循环。
## 安装
### 先决条件
- Python 3.10 或更高版本
- pip 包管理器
### 快速安装
```bash
# 克隆仓库
git clone https://github.com/your-org/regen-python-mcp.git
cd regen-python-mcp
# 安装依赖项
pip install -r requirements.txt
# 运行服务器
python main.py
```
### 配置
服务器使用环境变量进行配置。创建一个 `.env` 文件：
```bash
# 可选：覆盖默认 RPC 端点
REGEN_RPC_ENDPOINTS=https://regen-rpc.polkachu.com,https://rpc.cosmos.directory/regen
# 可选：覆盖默认 REST 端点
REGEN_REST_ENDPOINTS=https://regen-api.polkachu.com,https://rest.cosmos.directory/regen
# 可选：配置缓存
REGEN_MCP_ENABLE_CACHE=true
REGEN_MCP_CACHE_TTL_SECONDS=60
# 可选：日志记录级别
REGEN_MCP_LOG_LEVEL=INFO
```
参见 [`src/mcp_server/config/settings.py`](src/mcp_server/config/settings.py) 获取所有配置选项。
## 快速入门
### 与 Claude Code / Claude Desktop 一起使用
仓库中包含预配置的 MCP 设置文件。参见 **[MCP_SETUP.md](MCP_SETUP.md)** 获取完整说明。
**快速入门：**
1. 文件已预配置：
- `.mcp.json` - 服务器连接配置
- `.claude/settings.json` - 启用 MCP 服务器
2. 安装依赖项：`pip install -r requirements.txt`
3. 重启 Claude Code
**手动配置：**
将以下内容添加到您的 Claude Desktop 或 Claude Code 配置中：
```json
{
"mcpServers": {
"regen-network": {
"command": "/path/to/uv",
"args": ["run", "--directory", "/path/to/regen-python-mcp", "python", "main.py"],
"env": {
"PYTHONPATH": "/path/to/regen-python-mcp/src"
}
}
}
}
```
### 与 Python 一起使用
```python
from mcp.client import ClientSession, StdioServerParameters
import asyncio
async def main():
server_params = StdioServerParameters(
command="python",
args=["main.py"]
)
async with ClientSession(server_params) as session:
# 列出可用工具
tools = await session.list_tools()
print(f"可用工具：{len(tools)}")
# 列出信用类型
result = await session.call_tool("list_credit_types", {})
print(result)
asyncio.run(main())
```
### 示例查询
```python
# 获取所有生态信用类型
await client.call_tool("list_credit_types", {})
# 分页列出信用类别
await client.call_tool("list_classes", {"limit": 10, "offset": 0})
# 获取市场销售订单
await client.call_tool("list_sell_orders", {"page": 1, "limit": 20})
# 分析投资组合影响
await client.call_tool("analyze_portfolio_impact", {
"address": "regen1...",
"analysis_type": "full"
})
# 比较方法论
await client.call_tool("compare_credit_methodologies", {
"class_ids": ["C01", "C02", "C03"]
})
```
## 与 ChatGPT 自定义 GPT 操作（OpenAPI）一起使用
OpenAI 自定义 GPT 操作强制执行 **每个 OpenAPI 规范的最大 30 个操作**，并且操作集不能包括重复的域。此仓库支持 **两操作** 设置：
- **账本操作**（链上）：上传 `openapi-gpt-ledger.json`，服务器 `https://regen.gaiaai.xyz`（25 个操作，仅限 `/regen-api/*`）
- **KOI 操作**（知识）：上传 `openapi-gpt-koi.json`，服务器 `https://registry.regen.gaiaai.xyz`（4 个操作，仅限 `/api/koi/*`）
要确定性地重新生成 GPT/Full + 分割操作规范：
```bash
python3 scripts/generate_openapi_schemas.py
python3 scripts/validate_openapi_gpt.py --strict
```
GPT 的推荐指令文本位于：
- `gpt-instructions.md`
- `gpt-knowledge.md`
## 架构
```
regen-python-mcp/
├── main.py # 入口点
├── requirements.txt # Python 依赖项
├── docs/ # 文档
│ ├── regen_mcp_thesis.md # 愿景和用例
│ └── regen_network_exploration_report.md
├── tests/ # 测试套件
├── archive/ # 存档的探索代码
└── src/
└── mcp_server/
├── server.py # 主 MCP 服务器（45 个工具，8 个提示）
├── client/ # Regen 网络 API 客户端
├── config/ # 配置管理
├── models/ # Pydantic 数据模型
├── tools/ # 按模块划分的工具实现
├── prompts/ # 交互式提示指南
├── resources/ # 动态资源处理程序
├── cache/ # 缓存层
├── monitoring/ # 健康和指标
└── scrapers/ # 数据收集实用程序
```
### 设计原则
- **模块化组织**：按区块链模块组织工具以提高可维护性
- **类型安全**：整个 Pydantic 模型以确保运行时验证
- **异步优先**：所有 I/O 操作都使用异步/等待模式
- **优雅降级**：可选模块具有备用行为
- **配置驱动**：环境变量用于部署灵活性
## 工具参考
### 银行模块（11 个工具）
- `list_accounts`、`get_account`、`get_balance`、`get_all_balances`
- `get_spendable_balances`、`get_total_supply`、`get_supply_of`
- `get_bank_params`、`get_denoms_metadata`、`get_denom_metadata`、`get_denom_owners`
### 分配模块（9 个工具）
- `get_distribution_params`、`get_validator_outstanding_rewards`
- `get_validator_commission`、`get_validator_slashes`
- `get_delegation_rewards`、`get_delegation_total_rewards`
- `get_delegator_validators`、`get_delegator_withdraw_address`、`get_community_pool`
### 治理模块（8 个工具）
- `get_governance_proposal`、`list_governance_proposals`
- `get_governance_vote`、`list_governance_votes`
- `list_governance_deposits`、`get_governance_params`
- `get_governance_deposit`、`get_governance_tally_result`
### 市场模块（5 个工具）
- `get_sell_order`、`list_sell_orders`
- `list_sell_orders_by_batch`、`list_sell_orders_by_seller`、`list_allowed_denoms`
### 生态信用模块（4 个工具）
- `list_credit_types`、`list_classes`、`list_projects`、`list_credit_batches`
### 篮子模块（5 个工具）
- `list_baskets`、`get_basket`、`list_basket_balances`
- `get_basket_balance`、`get_basket_fee`
### 分析模块（3 个工具）
- `analyze_portfolio_impact`、`analyze_market_trends`、`compare_credit_methodologies`
## 开发
### 设置开发环境
```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
# 以可编辑模式安装
pip install -e .
# 安装开发依赖项
pip install pytest black mypy ruff
```
### 运行测试
```bash
# 运行所有测试
pytest tests/
# 运行并覆盖
pytest --cov=src/mcp_server tests/
# 运行特定测试文件
pytest tests/test_prompts.py -v
```
### 代码质量
```bash
# 格式化代码
black src/
# 类型检查
mypy src/
# 整理代码
ruff check src/
```
## 文档
- **[提示指南](src/README_PROMPTS.md)**：交互式提示的完整指南
- **[论文文档](docs/regen_mcp_thesis.md)**：愿景、用例和影响潜力
- **[探索报告](docs/regen_network_exploration_report.md)**：技术深入研究
- **[配置](src/mcp_server/config/settings.py)**：所有配置选项
## 用例
### 对于 AI 代理
- 自动环境市场分析
- 自动投资组合优化
- 实时信用价格发现
- 方法论比较和选择
### 对于开发者
- 构建生态金融应用
- 将 Regen 数据集成到仪表板中
- 创建自定义分析工具
- 原型设计新的市场机制
### 对于研究人员
- 环境信用市场分析
- 方法论有效性研究
- 市场流动性和定价研究
- 影响验证和跟踪
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开拉取请求
## 许可证
该项目使用 MIT 许可证 - 有关详细信息，请参见 LICENSE 文件。
## 致谢
- [Regen 网络](https://www.regen.network/) - 构建生态信用基础设施
- [Anthropic](https://www.anthropic.com/) - 模型上下文协议规范
- 开源社区
## 链接
- [Regen 网络文档](https://docs.regen.network/)
- [模型上下文协议](https://modelcontextprotocol.io)
- [报告问题](https://github.com/your-org/regen-python-mcp/issues)
---
**使用 🌱 构建再生未来**
