odos-mcp

🚀 Odos MCP 客户端

Odos MCP 客户端是一个模型上下文协议（MCP）客户端，用于与 Odos DEX 聚合平台和 Zerion 投资组合分析工具进行交互。该工具可全面访问多个区块链网络的 DeFi 交易数据、兑换报价、投资组合分析和交易历史。

🚀 快速开始

请确保你已完成以下步骤来设置和运行 Odos MCP 客户端：

1. 安装依赖：按照安装指南中的步骤克隆仓库、创建虚拟环境并安装所需依赖。
2. 配置环境变量：设置 ZERION_API_KEY 环境变量，以便使用 Zerion 分析工具。
3. 验证设置：运行验证脚本 python scripts/verify_setup.py 确保一切配置正确。
4. 启动 MCP 服务器：运行 poetry run python -m src.client.server 启动服务器。

✨ 主要特性

Odos API 集成

• 兑换报价：获取跨 DEX 流动性来源的最优兑换路线和价格。
• Zap 操作：单交易流动性提供报价。
• 链支持：访问所有 Odos 支持的区块链网络。
• 代币数据：获取支持代币的实时价格和元数据。
• 路由器信息：获取合约地址和区块链基础设施详情。

Zerion 分析

• 投资组合分析：提供完整的钱包持有量和组成明细。
• 交易历史：提供详细的历史交易数据和分析。
• 绩效跟踪：跟踪历史投资组合绩效和回报。
• 燃气价格监控：实时监控各网络的燃气价格估算。

📦 安装指南

# 克隆仓库
git clone <repository-url>
cd odos-mcp

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上使用: .venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 设置环境变量
# 创建 .env 文件并添加你的 API 密钥（请参阅配置部分）
# 或者直接设置环境变量：
export ZERION_API_KEY="your_zerion_api_key_here"

# 验证设置（可选但推荐）
python scripts/verify_setup.py

💻 使用示例

基础用法

确保你已设置所需的环境变量（请参阅配置部分），然后启动 MCP 服务器：

poetry run python -m src.client.server

注意：如果你计划使用任何 Zerion 分析工具，请确保已设置 ZERION_API_KEY。

验证设置

运行验证脚本以确保一切配置正确：

python scripts/verify_setup.py

此脚本将执行以下操作：

• 测试所有模块导入
• 验证环境配置
• 检查 API 连接性
• 验证辅助函数
• 提供全面的设置报告

📚 详细文档

可用工具

API 工具 (src/client/tools/api/)

| 工具 | 描述 | | ---- | ---- | | get_quote_swap | 获取兑换报价和交易数据 | | get_quote_zap | 获取流动性提供的 zap 报价 | | get_supported_chains | 列出支持的区块链网络 | | get_supported_tokens | 按链检索可交易代币 | | get_token_price | 获取代币实时价格数据 | | get_chain_token_prices | 获取跨链的批量代币价格 | | get_currencies | 获取法定货币汇率 | | get_contract_info | 获取智能合约详情和元数据 | | get_router_address | 获取 Odos 路由器合约地址 | | get_current_block | 获取当前区块编号和网络状态 | | get_liquidity_sources | 获取可用的 DEX 集成 |

Zerion 工具 (src/client/tools/zerion/)

注意：这些工具需要设置 ZERION_API_KEY 环境变量。 | 工具 | 描述 | | ---- | ---- | | get_wallet_portfolio | 获取投资组合持有量和组成 | | get_past_transactions | 进行历史交易分析 | | get_past_performance | 跟踪投资组合绩效 | | get_gas_prices | 获取网络燃气价格估算 |

项目结构

odos-mcp/
├── src/client/                 # 核心客户端包
│   ├── tools/                  # 工具实现
│   │   ├── api/               # Odos API 工具
│   │   └── zerion/            # Zerion 集成工具
│   ├── constants.py           # 链 ID、代币地址、API 端点
│   ├── helpers.py             # API 请求的实用函数
│   ├── mcp_types.py          # API 响应的 Pydantic 模型
│   └── api_models.py         # 其他数据模型
├── scripts/                   # 开发和维护脚本
│   ├── verify_setup.py        # 设置验证脚本
│   └── ...
├── tests/                     # 测试套件
└── requirements.txt          # Python 依赖项

配置

环境变量

客户端需要以下环境变量：

# 必需：用于投资组合分析的 Zerion API 密钥
export ZERION_API_KEY="your_zerion_api_key_here"

获取 API 密钥

Zerion API 密钥

要使用 Zerion 分析工具，你需要一个 Zerion API 密钥：

1. 访问 Zerion 开发者门户
2. 注册开发者账户
3. 创建新的 API 密钥
4. 设置 ZERION_API_KEY 环境变量

设置环境变量

在项目根目录下创建 .env 文件：

# .env 文件
ZERION_API_KEY=your_zerion_api_key_here

或者直接在 shell 中设置：

export ZERION_API_KEY="your_zerion_api_key_here"

API 端点

以下 API 端点在应用程序中硬编码：

• Odos API：https://api.odos.xyz（无需身份验证）
• Zerion API：https://api.zerion.io（需要 API 密钥）

开发

设置开发环境

# 安装开发依赖
pip install -r requirements-dev.txt

# 运行格式化
python scripts/format.py

# 运行测试

添加新工具

1. 在适当的目录（api/ 或 zerion/）中创建工具文件。
2. 添加简要的描述文档字符串。
3. 使用 FastMCP 装饰器模式实现。
4. 更新 __init__.py 导出。
5. 在 tests/ 目录中添加测试。

贡献

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 文件。

🛠️ 支持

如果你有任何问题或遇到问题，请：

• 在仓库中创建问题
• 查看现有文档和工具描述
• 查看 Odos API 文档以获取参数详情