PolyMind MCP

README.md
# PolyMind MCP

> 🧠 AI 驱动的 Polymarket 预测市场分析平台

[![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 项目简介

**PolyMind MCP** 是一个基于 Polygon 链上真实数据构建的 Polymarket 生态数据分析平台。通过解码链上 `OrderFilled` 事件，提供聪明钱追踪、市场情绪分析、套利机会检测等功能，帮助交易者做出更明智的决策。

**核心价值**：
- 🔗 **链上数据驱动** - 直接从 Polygon 链获取并解码真实交易数据
- 🧠 **聪明钱分析** - 识别高胜率交易者，追踪其持仓变化
- 📊 **可视化看板** - 实时展示市场情绪、大单监控、热门市场
- 🤖 **MCP 协议** - 支持 Claude Desktop 集成，自然语言查询

---

## 技术架构

```
┌─────────────────────────────────────────────────────────────┐
│                      Frontend (React)                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐        │
│  │ 情绪仪表 │ │ 大单监控 │ │ 热门市场 │ │ 聪明钱   │        │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    HTTP API (Flask)                          │
│  /stats  /hot  /smart-money  /trades  /sentiment  /arbitrage│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP Tools Layer                           │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐               │
│  │ Profiler   │ │ Advisor    │ │ Analyzer   │               │
│  │ 交易者画像 │ │ 交易建议   │ │ 套利检测   │               │
│  └────────────┘ └────────────┘ └────────────┘               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Data Layer                                │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐               │
│  │ Indexer    │ │ Decoder    │ │ SQLite DB  │               │
│  │ 区块链索引 │ │ 交易解码   │ │ 数据存储   │               │
│  └────────────┘ └────────────┘ └────────────┘               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              External Data Sources                           │
│  ┌────────────────────┐  ┌────────────────────┐             │
│  │ Polygon RPC        │  │ Gamma API          │             │
│  │ CTF Exchange Events│  │ Market Metadata    │             │
│  └────────────────────┘  └────────────────────┘             │
└─────────────────────────────────────────────────────────────┘
```

**技术栈**：
- **后端**: Python 3.9+, Flask, SQLite
- **前端**: React (CDN), Tailwind CSS
- **链上交互**: Web3.py, Polygon RPC
- **协议**: MCP (Model Context Protocol)

---

## 快速开始

### 环境要求

- Python 3.9+
- 有效的 Polygon RPC URL（推荐 Alchemy/Infura）

### 安装步骤

```bash
# 1. 克隆项目
git clone https://github.com/your-repo/polymind-mcp.git
cd polymind-mcp

# 2. 创建虚拟环境
python -m venv venv
.\venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

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

# 4. 配置环境变量
cp .env.example .env
# 编辑 .env，填入 RPC_URL
```

### 运行命令

```bash
# 🚀 一键演示模式（推荐评审使用）
python start.py demo

# 📊 验证数据
python verify_data.py

# 🌐 只启动 API 服务
python start.py api

# 🔗 索引链上数据（需要 RPC_URL）
python start.py index --from-block 66000000 --to-block 66001000

# 📦 同步市场元数据
python start.py sync-markets
```

### 访问地址

| 服务 | 地址 |
|------|------|
| API 服务 | http://localhost:8888 |
| 前端看板 | http://localhost:3000（需另启动前端服务） |
| 健康检查 | http://localhost:8888/health |

启动前端看板：
```bash
cd frontend
python -m http.server 3000
```

---

## 功能说明

### 核心功能

| 功能 | 说明 | API 端点 |
|------|------|----------|
| **市场情绪分析** | 基于买卖比例计算市场情绪指数 | `GET /sentiment` |
| **大单监控** | 追踪 >$1000 的大额交易 | `GET /trades/large` |
| **聪明钱追踪** | 识别高胜率交易者 | `GET /smart-money` |
| **热门市场** | 按交易量排序的活跃市场 | `GET /hot` |
| **套利机会** | 检测 YES+NO 价差套利 | `GET /arbitrage` |
| **交易者画像** | 分析地址交易行为 | `GET /trader/{address}` |

### MCP 工具列表

| 工具名称 | 功能描述 |
|---------|---------|
| `get_market_info` | 获取市场详情 |
| `search_markets` | 搜索 Polymarket 市场 |
| `analyze_trader` | 分析交易者行为模式 |
| `get_trading_advice` | 获取交易建议 |
| `find_arbitrage` | 扫描套利机会 |
| `get_smart_money_activity` | 获取聪明钱活动 |
| `get_hot_markets` | 获取热门市场 |
| `analyze_market_relationship` | 分析市场关系 |
| `natural_language_query` | 自然语言查询 |

---

## HTTP API 端点

### 数据查询

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 + 数据状态 |
| GET | `/stats` | 仪表盘统计（真实数据） |
| GET | `/trades/recent` | 最近交易列表 |
| GET | `/trades/large` | 大单交易监控 |
| GET | `/hot` | 热门市场排行 |
| GET | `/markets/search?q=` | 搜索市场 |

### 分析功能

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/sentiment` | 市场情绪指数 |
| GET | `/smart-money` | 聪明钱活动 |
| GET | `/trader/{address}` | 交易者分析 |
| GET | `/arbitrage` | 套利机会 |

### AI 功能

| 方法 | 端点 | 说明 |
|------|------|------|
| POST | `/nl-query` | 自然语言查询 |
| GET | `/markets/{slug}/advice` | 交易建议 |

---

## 数据来源

本项目使用以下数据源：

| 数据类型 | 来源 | 说明 |
|---------|------|------|
| **交易数据** | Polygon 链上 | 通过 RPC 获取 CTF Exchange 的 `OrderFilled` 事件 |
| **市场元数据** | Gamma API | 获取市场 slug、描述、Token ID 映射 |
| **价格数据** | 链上计算 | 基于交易事件计算 YES/NO 价格 |

### 合约地址

| 合约 | 地址 |
|------|------|
| CTF Exchange | `0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E` |
| Neg Risk Exchange | `0xC5d563A36AE78145C45a50134d48A1215220f80a` |
| USDC (Collateral) | `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` |

### 示例数据

- **交易哈希**: `0x916cad96dd5c219997638133512fd17fe7c1ce72b830157e4fd5323cf4f19946`
- **市场 Slug**: `will-there-be-another-us-government-shutdown-by-january-31`

可在 Polygonscan 验证: https://polygonscan.com/tx/0x916cad96dd5c219997638133512fd17fe7c1ce72b830157e4fd5323cf4f19946

---

## 项目结构

```
PolyMind-MCP/
├── src/
│   ├── mcp/                   # MCP 服务模块
│   │   ├── server.py          # HTTP API 服务
│   │   ├── mcp_server.py      # MCP stdio 服务
│   │   ├── tools.py           # MCP 工具实现
│   │   ├── profiler.py        # 交易者画像
│   │   └── advisor.py         # 交易建议引擎
│   ├── indexer/               # 区块链索引器
│   │   ├── run.py             # 索引器主逻辑
│   │   ├── store.py           # 数据存储
│   │   └── gamma.py           # Gamma API 客户端
│   ├── db/                    # 数据库模块
│   │   └── schema.py          # 表结构定义
│   ├── trade_decoder.py       # 交易解码器
│   └── market_decoder.py      # 市场参数解码器
├── frontend/                  # Web 前端
│   ├── index.html             # 主页面
│   ├── script.js              # React 组件
│   └── styles.css             # 样式
├── data/                      # 数据目录
│   └── polymarket.db          # SQLite 数据库
├── tests/                     # 测试
├── docs/                      # 文档
├── start.py                   # 统一启动脚本
├── verify_data.py             # 数据验证脚本
├── requirements.txt           # Python 依赖
├── .env.example               # 环境变量示例
├── README.md                  # 项目说明
└── DEMO.md                    # 演示说明
```

---

## 环境变量

| 变量 | 必需 | 说明 |
|------|------|------|
| `RPC_URL` | ✅ | Polygon RPC 地址 |
| `OPENAI_API_KEY` | ❌ | OpenAI API（启用 AI 分析）|
| `DB_PATH` | ❌ | 数据库路径（默认 `data/polymarket.db`） |
| `GAMMA_BASE_URL` | ❌ | Gamma API 地址 |

---

## Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "polymind": {
      "command": "python",
      "args": ["-m", "src.mcp.mcp_server"],
      "cwd": "/path/to/polymind-mcp",
      "env": {
        "RPC_URL": "your-polygon-rpc-url"
      }
    }
  }
}
```

配置完成后，可在 Claude Desktop 中直接查询：
- "显示最热门的 10 个预测市场"
- "分析地址 0x1234... 的交易行为"
- "查找当前的套利机会"

---

## 开发

### 运行测试

```bash
# 运行所有测试
pytest tests/

# 运行特定测试
pytest tests/test_market_decoder.py -v

# 验证系统
python verify_system.py
```

### 代码风格

```bash
# 格式化代码
black src/

# 类型检查
mypy src/
```

---

## 激励机制设计

### 防止作恶

1. **链上数据不可篡改** - 所有交易数据直接从 Polygon 链获取并验证
2. **透明的聪明钱算法** - 胜率计算基于链上可验证的交易历史
3. **开源可审计** - 所有代码开源，任何人可以验证数据处理逻辑

### 激励正确预测

1. **聪明钱排行榜** - 高胜率交易者获得曝光，建立链上信誉
2. **跟单信号** - 用户可追踪表现优秀的交易者
3. **套利提醒** - 及时发现市场定价偏差，奖励信息发现者

---

## 团队成员

- **开发者**: AN_SU,Ethan,Rustc.rs,bluerabbit2026

---

## License

MIT License - 详见 [LICENSE](LICENSE) 文件
This server cannot be deployed
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd
Maintenance

ActivityInactive
ResponsivenessNo issues
Resources

GitHub Repository
Need Help?
Related Servers