MCP Swap

以太坊交易 MCP 服务器

🚀 一个基于 Rust 构建的生产就绪模型上下文协议 (MCP) 服务器，使 AI 代理能够与以太坊区块链交互。查询余额、获取代币价格、模拟 Uniswap 交换，具有企业级可靠性。

✨ 功能特性

• 🔍 余额查询: 精确查询 ETH 和 ERC20 代币余额
• 💰 价格数据: 来自 CoinGecko API 的实时代币价格
• 🔄 交换模拟: Uniswap V2 交易模拟（只读）
• 🛡️ 安全优先: 仅模拟操作，真实资金零风险
• ⚡ 高性能: 使用 ethers-rs 的异步 Rust，实现最佳速度
• 🎯 精确计算: 使用 rust_decimal 进行精确的金融计算

🚀 快速开始

前置要求

• Rust 1.70+: 从 rustup.rs 安装
• RPC 提供商: 从 Infura 或 Alchemy 获取免费 API 密钥

设置

1. 克隆并设置环境:

   git clone 
   cd MCP-EHT
   cp .env.example .env

1. 配置 .env 文件:

   # 必需：添加您的 RPC URL
   ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID
   
   # 必需：生成测试私钥（禁止使用真实资金！）
   PRIVATE_KEY=0x$(openssl rand -hex 32)
   
   # 可选：设置链（1=主网, 11155111=Sepolia）
   CHAIN_ID=1

1. 构建并运行:

   cargo build --release
   cargo run

1. 运行测试:

   cargo test

🛠️ MCP 工具

服务器提供三个符合模型上下文协议规范的核心工具：

1. get_balance - 查询代币余额

请求:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {
      "address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe",
      "token": "0xA0b86a33E6441E4C2C15Bf077bB8A7ff0c4e5FE0"  // 可选的 ERC20 地址
    }
  }
}

响应（ETH 余额）:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "address": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
          "eth_balance": "1.234567890123456789",
          "type": "ETH"
        }
      }
    ]
  }
}

响应（ERC20 代币）:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "address": "0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae",
          "token": {
            "address": "0xa0b86a33e6441e4c2c15bf077bb8a7ff0c4e5fe0",
            "symbol": "USDC",
            "name": "USD Coin",
            "balance": "1000.50"
          },
          "type": "ERC20"
        }
      }
    ]
  }
}

2. get_token_price - 获取代币价格

请求:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_token_price",
    "arguments": {
      "token": "ethereum"  // 符号或合约地址
    }
  }
}

响应:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "token": "ethereum",
          "usd_price": "3456.78",
          "eth_price": "1.0",
          "last_updated": "2024-01-15T10:30:00Z",
          "source": "CoinGecko"
        }
      }
    ]
  }
}

3. swap_tokens - 模拟交换

请求:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "swap_tokens",
    "arguments": {
      "from_token": "0xA0b86a33E6441E4C2C15Bf077bB8A7ff0c4e5FE0",  // USDC
      "to_token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",    // WETH
      "amount": "1000000",    // 1 USDC（6位小数）
      "slippage": 0.5         // 0.5%
    }
  }
}

响应:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "simulation": {
            "from_token": {
              "address": "0xa0b86a33e6441e4c2c15bf077bb8a7ff0c4e5fe0",
              "symbol": "USDC",
              "amount": "1000000"
            },
            "to_token": {
              "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
              "symbol": "WETH",
              "estimated_amount": "289567123456789012",
              "minimum_amount": "288121234567890123"
            },
            "slippage_tolerance": "0.5%",
            "price_impact": "0.12%",
            "route": ["0xa0b86a33e6441e4c2c15bf077bb8a7ff0c4e5fe0", "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"],
            "gas": {
              "estimate": "200000",
              "price_gwei": "30",
              "cost_eth": "0.006"
            }
          },
          "warning": "这仅是模拟。未执行实际交易。"
        }
      }
    ]
  }
}

⚙️ 配置

服务器使用环境变量进行配置。复制 .env.example 到 .env 并自定义：

必需设置

# 以太坊 RPC URL（必需）
ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID

# 钱包操作私钥（必需 - 仅测试密钥！）
PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

# 区块链网络（必需）
CHAIN_ID=1  # 1=主网, 11155111=Sepolia

可选设置

# CoinGecko API（可选 - 获得更高速率限制）
COINGECKO_API_URL=https://api.coingecko.com/api/v3
COINGECKO_API_KEY=your_pro_api_key_here

# MCP 服务器（可选）
MCP_SERVER_HOST=127.0.0.1
MCP_SERVER_PORT=8080

# 日志记录（可选）
RUST_LOG=info  # trace, debug, info, warn, error

网络选项

🏗️ 架构与设计决策

该 MCP 服务器基于几个关键架构原则设计：

1. 单文件架构: 所有功能整合在 src/main.rs（约1000行）中，便于部署和审查。这种方法简化了代码库，同时通过注释和结构保持清晰的模块分离。

1. 仅模拟安全性: 所有交换操作使用 Uniswap V2 getAmountsOut 进行只读模拟，而非执行真实交易。这确保了完全安全，同时为 AI 代理提供准确估算。

1. ethers-rs 集成: 选择 ethers-rs 而非其他替代方案，因其成熟的生态系统、全面的以太坊支持和出色的异步集成。该库无缝处理 ABI 编码/解码、交易签名和提供商管理。

1. 精确优先的金融计算: 在所有货币计算中使用 rust_decimal，避免 DeFi 应用中常见的浮点精度问题。Wei 到 ETH 的转换保持完整的18位小数精度。

1. 健壮的错误处理: 使用 Rust 的 Result 类型和 anyhow crate 实现地址、滑点边界和 API 响应的全面验证，提供详细的错误上下文。

🧪 测试

项目包含全面的测试覆盖以确保可靠性：

运行测试

# 运行所有测试
cargo test

# 运行带输出的测试
cargo test -- --nocapture

# 运行特定测试
cargo test test_wei_to_eth_conversion

# 运行集成测试（需要网络）
cargo test test_integration_price_fetch -- --ignored

测试覆盖

• 单元测试: 11个通过的测试，覆盖核心功能

- 配置验证 - Wei/ETH 转换精度 - 地址验证 - 滑点边界检查 - MCP 工具请求验证 - 代币地址工具

• 集成测试: 1个网络依赖测试（默认忽略）

- CoinGecko API 连接 - 真实价格数据获取

测试结果

test result: ok. 11 passed; 0 failed; 1 ignored

📋 常用代币地址（以太坊主网）

🔒 安全性与已知限制

安全特性

• ✅ 仅模拟操作: 永远不会执行真实交易
• ✅ 仅测试密钥: 专为无真实资金的测试私钥设计
• ✅ 输入验证: 对所有地址和参数进行全面验证
• ✅ 速率限制感知: 遵守 API 速率限制并包含超时处理
• ✅ 错误边界: 优雅的故障处理防止崩溃

已知限制

1. 测试网 vs 主网: 当前配置为以太坊主网，但可通过 CHAIN_ID 轻松切换到测试网
2. 仅 Uniswap V2: 交换模拟使用 Uniswap V2 合约；V3 支持需要额外开发
3. 价格数据延迟: CoinGecko 价格在高波动性期间可能有1-2分钟延迟
4. Gas 估算: 使用静态 gas 估算而非动态模拟
5. 单一 DEX: 仅模拟 Uniswap V2；不跨多个 DEX 聚合

假设条件

• 代币遵循标准 ERC20 接口
• 请求的交易对存在 Uniswap V2 池
• RPC 提供商保持可靠连接
• CoinGecko API 保持可访问并维持当前响应格式

📊 API 速率限制

🔧 故障排除

常见问题

"ETHEREUM_RPC_URL must be set"

# 解决方案：复制并配置环境文件
cp .env.example .env
# 编辑 .env 文件，填入您的真实 Infura/Alchemy URL

"Connection timeout" 或 RPC 错误

# 解决方案：验证 RPC URL 和网络连接
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  $ETHEREUM_RPC_URL

"Invalid private key format"

# 解决方案：确保私钥有 0x 前缀和64个十六进制字符
PRIVATE_KEY=0x$(openssl rand -hex 32)

"CoinGecko API rate limit exceeded"

# 解决方案：在请求间添加延迟或升级到 Pro API
COINGECKO_API_KEY=your_pro_api_key

开发提示

• 使用 RUST_LOG=debug 获取详细日志
• 首先使用 Sepolia 测试网测试（CHAIN_ID=11155111）
• 监控 RPC 使用量以避免速率限制
• 开发期间使用 cargo check 进行快速编译

📋 系统要求

• Rust: 1.70.0 或更高版本
• 操作系统: Linux、macOS 或 Windows
• 内存: 最少 256MB RAM
• 网络: 稳定的互联网连接用于 RPC/API 调用
• 存储: 编译二进制文件需要 50MB

📄 许可证

MIT 许可证 - 详见 LICENSE 文件。

使用 ❤️ 构建，基于 Rust、ethers-rs 和模型上下文协议