@catalyst-team/poly-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,49 +1,121 @@
 # @catalyst-team/poly-mcp
 
-A Model Context Protocol (MCP) server that exposes Polymarket functionality to AI agents.
+AI Agent 接入 Polymarket 预测市场的 MCP Server。
 
-## Installation
+## 🎯 你可以做什么
 
-### From npm (after publishing)
+### 1. 聪明钱分析 (Smart Money Analysis)
+```
+get_leaderboard → 获取 Top 10 聪明钱地址
+  ↓
+get_trader_positions(address) → 查看每个钱包持仓
+  ↓
+get_trader_profile(address) → 分析盈利模式
+```
+**示例问题**: "Top 10 聪明钱主要在哪些市场有持仓？"
 
-```bash
-npm install -g @catalyst-team/poly-mcp
-# or
-pnpm add -g @catalyst-team/poly-mcp
+### 2. 交易者深度分析 (Trader Deep Dive)
 ```
+get_trader_positions(address) → 持仓分析
+  ↓
+按 eventSlug 分组 → 识别对冲 vs 单边策略
+  ↓
+get_trader_trades(address) → 入场时机分析
+  ↓
+判断策略类型: 对冲型/方向型/套利型/做市型
+```
+**示例问题**: "这个交易者是什么策略类型？他的盈利主要来自哪里？"
 
-### From source
+### 3. 跟单交易 (Copy Trading)
+```
+get_leaderboard → 选择跟单目标
+  ↓
+get_trader_trades(address) → 监控新交易
+  ↓
+get_market + get_orderbook → 评估当前价格
+  ↓
+place_limit_order → 跟进交易
+```
+**示例问题**: "排名第一的交易者最近买了什么？我应该跟吗？"
 
-```bash
-# Build the packages
-pnpm -F @catalyst-team/poly-sdk build
-pnpm -F @catalyst-team/poly-mcp build
+### 4. 钱包追踪 (Wallet Tracking)
+```
+get_trader_trades(address) → 查看今日交易
+  ↓
+get_trader_positions(address) → 当前持仓
+  ↓
+get_market(conditionId) → 深入分析相关市场
 ```
+**示例问题**: "这个钱包今天有哪些交易？表现如何？"
 
-## Publishing
+### 5. 热门市场发现 (Market Discovery)
+```
+search_markets(query, sortBy: 'volume') → 热门市场
+  ↓
+get_orderbook(conditionId) → 分析流动性
+  ↓
+get_leaderboard → 查看哪些聪明钱参与
+```
+**示例问题**: "最近24小时哪些市场交易量最大？聪明钱在买入什么？"
 
-```bash
-# 1. Build both packages
-pnpm -F @catalyst-team/poly-sdk build
-pnpm -F @catalyst-team/poly-mcp build
+### 6. 体育市场策略 (Sports Strategy)
+```
+search_markets(query: 'NBA/NFL') → 体育市场
+  ↓
+get_market(conditionId) → 查看赔率和截止时间
+  ↓
+get_orderbook → 分析价差和深度
+```
+**示例问题**: "今天有哪些 NBA 比赛可以投注？赔率合理吗？"
 
-# 2. Publish poly-sdk first (poly-mcp depends on it)
-pnpm -F @catalyst-team/poly-sdk publish --access public
+### 7. 充值与授权 (Deposit & Auth)
+```
+check_allowances() → 检查授权状态
+  ↓
+approve_trading() → 一键授权所有合约
+  ↓
+swap("MATIC", "USDC", "100") → 换币
+  ↓
+deposit_usdc(100) → 充值到交易账户
+```
+**示例问题**: "我的钱包准备好交易了吗？帮我检查授权状态"
 
-# 3. Publish poly-mcp
-pnpm -F @catalyst-team/poly-mcp publish --access public
+### 8. 执行交易 (Trading)
+```
+get_market(identifier) → 获取市场信息
+  ↓
+get_orderbook(conditionId) → 查看盘口深度
+  ↓
+estimate_execution(conditionId, "Yes", "BUY", 100) → 预估成交
+  ↓
+place_limit_order(conditionId, "Yes", "BUY", 0.55, 100) → 下单
+```
+**示例问题**: "帮我在这个市场买入 100 USDC 的 Yes"
+
+---
+
+## 📦 安装
+
+### npm 安装 (推荐)
+```bash
+npm install -g @catalyst-team/poly-mcp
 ```
 
-**Note**: Publishing requires npm 2FA authentication.
+### 从源码构建
+```bash
+pnpm -F @catalyst-team/poly-sdk build
+pnpm -F @catalyst-team/poly-mcp build
+```
 
-## MCP Configuration
+---
 
-### After npm publish (recommended)
+## ⚙️ MCP 配置
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+### Claude Desktop 配置
 
-#### Read-only mode (market data, orderbook, trader analysis)
+文件位置: `~/Library/Application Support/Claude/claude_desktop_config.json`
 
+#### 只读模式 (市场数据、钱包分析)
 ```json
 {
   "mcpServers": {
@@ -55,8 +127,7 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
-#### Trading mode (with private key)
-
+#### 交易模式 (需要私钥)
 ```json
 {
   "mcpServers": {
@@ -71,29 +142,13 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
-### Local development
-
-#### Read-only mode
-
+#### 本地开发
 ```json
 {
   "mcpServers": {
     "polymarket": {
       "command": "node",
-      "args": ["/path/to/PerdictionRouter/packages/poly-mcp/dist/server.js"]
-    }
-  }
-}
-```
-
-#### Trading mode
-
-```json
-{
-  "mcpServers": {
-    "polymarket": {
-      "command": "node",
-      "args": ["/path/to/PerdictionRouter/packages/poly-mcp/dist/server.js"],
+      "args": ["/path/to/poly-mcp/dist/server.js"],
       "env": {
         "POLY_PRIVATE_KEY": "your-wallet-private-key"
       }
@@ -102,215 +157,104 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
-#### Development mode (with hot reload)
-
-```json
-{
-  "mcpServers": {
-    "polymarket": {
-      "command": "npx",
-      "args": ["tsx", "/path/to/PerdictionRouter/packages/poly-mcp/src/server.ts"],
-      "env": {
-        "POLY_PRIVATE_KEY": "your-wallet-private-key"
-      }
-    }
-  }
-}
-```
-
-## Environment Variables
-
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `POLY_PRIVATE_KEY` | Wallet private key (with or without 0x prefix) | For trading |
-| `POLY_CHAIN_ID` | Chain ID (137=mainnet, 80002=testnet) | Optional (default: 137) |
-
-**Note**: API credentials are automatically derived from the private key using Polymarket's `createOrDeriveApiKey()`. You only need to provide the wallet private key to enable trading.
-
-## Available Tools
-
-### Trader Tools (public data)
-
-| Tool | Description |
-|------|-------------|
-| `get_trader_positions` | Get current positions for a wallet address |
-| `get_trader_trades` | Get trade history for a wallet |
-| `get_trader_profile` | Get trader profile with PnL and stats |
-| `get_leaderboard` | Get top traders from leaderboard |
-
-### Market Tools (public data)
-
-| Tool | Description |
-|------|-------------|
-| `get_market` | Get market details by slug or conditionId |
-| `search_markets` | Search markets by keyword |
-| `get_trending_markets` | Get trending markets by volume/liquidity |
-| `get_market_trades` | Get recent trades for a market |
-
-### Order Tools (public data)
-
-| Tool | Description |
-|------|-------------|
-| `get_orderbook` | Get orderbook depth for a market outcome |
-| `get_best_prices` | Get best bid/ask prices for both outcomes |
-| `estimate_execution` | Estimate execution price and slippage |
-
-### Trade Tools (requires private key)
-
-| Tool | Description |
-|------|-------------|
-| `place_limit_order` | Place a limit order |
-| `place_market_order` | Place a market order |
-| `cancel_order` | Cancel an existing order |
-| `get_my_orders` | Get your open orders |
+---
+
+## 🛠️ 完整工具列表
+
+### Trader Tools (公开数据)
+| 工具 | 描述 |
+|------|------|
+| `get_trader_positions` | 获取钱包当前持仓和 PnL |
+| `get_trader_trades` | 获取钱包交易历史 |
+| `get_trader_profile` | 获取交易者综合分析 |
+| `get_leaderboard` | 获取 PnL 排行榜 |
+
+### Market Tools (公开数据)
+| 工具 | 描述 |
+|------|------|
+| `get_market` | 通过 slug 或 conditionId 获取市场详情 |
+| `search_markets` | 关键词搜索市场 |
+| `get_trending_markets` | 获取热门市场 |
+| `get_market_trades` | 获取市场最近成交 |
+
+### Order Tools (公开数据)
+| 工具 | 描述 |
+|------|------|
+| `get_orderbook` | 获取盘口深度 |
+| `get_best_prices` | 获取最优买卖价 |
+| `estimate_execution` | 预估成交价格和滑点 |
+
+### Trade Tools (需要私钥)
+| 工具 | 描述 |
+|------|------|
+| `place_limit_order` | 下限价单 |
+| `place_market_order` | 下市价单 |
+| `cancel_order` | 取消订单 |
+| `get_my_orders` | 查看挂单 |
 
 ### Wallet Tools
+| 工具 | 描述 | 需要私钥 |
+|------|------|:--------:|
+| `get_supported_deposit_assets` | 支持的充值资产和链 | ❌ |
+| `get_deposit_addresses` | 获取充值地址 | ✅ |
+| `deposit_usdc` | 充值 USDC | ✅ |
+| `check_allowances` | 检查授权状态 | ✅ |
+| `approve_trading` | 一键授权所有合约 | ✅ |
+| `swap` | QuickSwap V3 换币 | ✅ |
+| `swap_and_deposit` | 换币并充值 | ✅ |
+| `get_token_balances` | 获取自己钱包余额 | ✅ |
+| `get_wallet_balances` | 获取任意钱包余额 | ❌ |
+| `get_swap_quote` | 获取换币报价 | ❌ |
+| `get_available_pools` | 获取可用交易池 | ❌ |
 
-| Tool | Description | Requires Key |
-|------|-------------|--------------|
-| `get_supported_deposit_assets` | Get all supported assets and chains for deposits | No |
-| `get_deposit_addresses` | Get deposit addresses (EVM, Solana, Bitcoin) | Yes |
-| `deposit_usdc` | Deposit USDC to Polymarket | Yes |
-| `check_allowances` | Check ERC20 and ERC1155 allowances for trading | Yes |
-| `approve_trading` | Set up all required approvals for trading | Yes |
-| `swap` | Swap tokens on Polygon via QuickSwap V3 | Yes |
-| `swap_and_deposit` | Swap to USDC and deposit in one operation | Yes |
-| `get_token_balances` | Get your wallet token balances | Yes |
-| `get_wallet_balances` | Get any wallet's token balances | No |
-| `get_swap_quote` | Get a swap quote (check route availability) | No |
-| `get_available_pools` | Get available QuickSwap V3 pools | No |
+### Guide Tool
+| 工具 | 描述 |
+|------|------|
+| `get_usage_guide` | 🚀 获取使用指南，AI Agent 应首先调用此工具 |
 
-## Tool Examples
+---
 
-### Get Market
+## 💡 Pro Tips
 
-```json
-{
-  "name": "get_market",
-  "arguments": {
-    "identifier": "will-bitcoin-hit-100k-in-2024"
-  }
-}
-```
+1. **AI Agent 首先调用 `get_usage_guide`** - 获取完整的使用场景指南
+2. **用 `get_leaderboard` 获取聪明钱地址** - 这是分析的起点
+3. **用 `search_markets` 的 tag 参数过滤** - Politics, Sports, Crypto
+4. **分析持仓时看 `avgPrice` vs `curPrice`** - 判断盈亏状态
+5. **查看 `volume24hr`** - 判断市场活跃度
 
-Response:
-```json
-{
-  "market": {
-    "conditionId": "0x...",
-    "question": "Will Bitcoin hit $100k in 2024?",
-    "slug": "will-bitcoin-hit-100k-in-2024"
-  },
-  "prices": {
-    "yes": 0.65,
-    "no": 0.35
-  },
-  "stats": {
-    "volume": 1500000,
-    "liquidity": 250000
-  }
-}
-```
+---
 
-### Get Trader Positions
+## ⚠️ 重要：USDC.e vs Native USDC
 
-```json
-{
-  "name": "get_trader_positions",
-  "arguments": {
-    "address": "0x1234..."
-  }
-}
-```
-
-### Get Swap Quote
-
-```json
-{
-  "name": "get_swap_quote",
-  "arguments": {
-    "tokenIn": "MATIC",
-    "tokenOut": "USDC",
-    "amount": "100"
-  }
-}
-```
-
-Response:
-```json
-{
-  "tokenIn": "MATIC",
-  "tokenOut": "USDC",
-  "amountIn": "100",
-  "amountOut": "55.23",
-  "route": "MATIC → WETH → USDC (multi-hop)",
-  "priceImpact": "0.15%"
-}
-```
-
-## Programmatic Usage
+Polymarket CTF **只接受 USDC.e** (Bridged USDC)！
 
-```typescript
-import { PolymarketSDK } from '@catalyst-team/poly-sdk';
-import { createMcpHandler } from '@catalyst-team/poly-mcp';
+| Token | 地址 | CTF 兼容 |
+|-------|------|:--------:|
+| USDC.e (Bridged) | `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` | ✅ |
+| Native USDC | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` | ❌ |
 
-const sdk = new PolymarketSDK();
-const handler = createMcpHandler(sdk);
-
-// Call any tool
-const result = await handler('get_market', {
-  identifier: 'btc-100k',
-});
-
-console.log(result);
-```
+**常见错误**: 钱包显示有 USDC，但 CTF 操作失败
+**原因**: 你有的是 Native USDC，不是 USDC.e
+**解决**: 使用 `deposit_usdc` 通过 Bridge 自动转换
 
-Or register with an MCP server instance:
+---
 
-```typescript
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { PolymarketSDK } from '@catalyst-team/poly-sdk';
-import { registerMcpTools } from '@catalyst-team/poly-mcp';
+## 📦 发布
 
-const server = new Server(
-  { name: 'my-server', version: '1.0.0' },
-  { capabilities: { tools: {} } }
-);
-
-const sdk = new PolymarketSDK();
-registerMcpTools(server, sdk);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
+```bash
+# 按顺序发布 (有依赖关系)
+pnpm -F @catalyst-team/cache publish
+pnpm -F @catalyst-team/poly-sdk publish
+pnpm -F @catalyst-team/poly-mcp publish
 ```
 
-## Architecture
-
-```
-packages/poly-mcp/
-├── src/
-│   ├── index.ts          # Main exports and handler factory
-│   ├── server.ts         # Standalone MCP server (CLI entry point)
-│   ├── types.ts          # TypeScript type definitions
-│   ├── errors.ts         # Error handling utilities
-│   └── tools/
-│       ├── index.ts      # Tool exports
-│       ├── trader.ts     # Trader analysis tools
-│       ├── market.ts     # Market discovery tools
-│       ├── order.ts      # Orderbook analysis tools
-│       ├── trade.ts      # Trading execution tools
-│       ├── wallet.ts     # Deposit and authorization tools
-│       └── guide.ts      # Usage guide tool
-├── docs/
-│   └── 01-mcp.md         # Detailed MCP design document
-├── package.json
-└── README.md
-```
+---
 
-## Related Packages
+## 🔗 相关资源
 
-- `@catalyst-team/poly-sdk` - Core SDK for Polymarket APIs (required dependency)
+- **poly-sdk**: `@catalyst-team/poly-sdk` - Polymarket SDK
+- **文档**: `docs/01-mcp.md` - 详细设计文档
+- **Polymarket**: https://polymarket.com
 
 ## License
 

package/docs/e2e/01-trader-tools.md

@@ -0,0 +1,159 @@
+# Trader Tools E2E Test
+
+> 交易者分析工具端到端测试
+
+---
+
+## 工具清单
+
+| 工具 | 功能 | 认证 | 优先级 |
+|------|------|------|--------|
+| `get_leaderboard` | 获取 PnL 排行榜 | 无 | P1 |
+| `get_trader_profile` | 获取交易者资料 | 无 | P1 |
+| `get_trader_positions` | 获取持仓和 PnL | 无 | P0 |
+| `get_trader_trades` | 获取交易历史 | 无 | P1 |
+
+---
+
+## Test Case 1: get_leaderboard
+
+### 1.1 默认参数
+```
+调用: get_leaderboard()
+预期: 返回 10 个交易者，按 PnL 排序
+验证:
+- traders 数组长度 = 10
+- 每个 trader 有 rank, address, pnl, volume
+- rank 从 1 开始递增
+```
+
+### 1.2 自定义 limit
+```
+调用: get_leaderboard(limit=5)
+预期: 返回 5 个交易者
+验证:
+- traders 数组长度 = 5
+```
+
+### 1.3 分页测试
+```
+调用: get_leaderboard(limit=5, offset=5)
+预期: 返回第 6-10 名交易者
+验证:
+- 第一个 trader 的 rank = 6
+- 与 offset=0 的结果不重叠
+```
+
+---
+
+## Test Case 2: get_trader_profile
+
+### 2.1 有效地址
+```
+前置: 从 leaderboard 获取一个地址
+调用: get_trader_profile(address=<top_trader>)
+预期: 返回完整的交易者资料
+验证:
+- trader.address 匹配
+- ranking.rank 存在
+- performance.officialPnl 存在
+- stats.positionCount >= 0
+```
+
+### 2.2 无效地址
+```
+调用: get_trader_profile(address="0x0000000000000000000000000000000000000000")
+预期: 返回空数据或错误
+验证:
+- 错误信息清晰
+```
+
+---
+
+## Test Case 3: get_trader_positions
+
+### 3.1 有持仓的交易者
+```
+前置: 从 leaderboard 获取顶级交易者
+调用: get_trader_positions(address=<top_trader>)
+预期: 返回持仓列表和汇总
+验证:
+- positions 是数组
+- 每个 position 有 market, holding, pnl
+- summary.totalPositions 匹配 positions.length
+- unrealizedPnl 和 realizedPnl 有值
+```
+
+### 3.2 无持仓的地址
+```
+调用: get_trader_positions(address=<new_address>)
+预期: 返回空持仓列表
+验证:
+- positions = []
+- summary.totalPositions = 0
+```
+
+---
+
+## Test Case 4: get_trader_trades
+
+### 4.1 默认参数
+```
+前置: 从 leaderboard 获取活跃交易者
+调用: get_trader_trades(address=<active_trader>)
+预期: 返回最近 20 笔交易
+验证:
+- trades 数组长度 <= 20
+- 每笔交易有 side, outcome, size, price, timestamp
+- 按时间倒序排列
+```
+
+### 4.2 过滤 BUY
+```
+调用: get_trader_trades(address=<trader>, side="BUY")
+预期: 只返回买入交易
+验证:
+- 所有 trade.side = "BUY"
+```
+
+### 4.3 过滤 SELL
+```
+调用: get_trader_trades(address=<trader>, side="SELL")
+预期: 只返回卖出交易
+验证:
+- 所有 trade.side = "SELL"
+```
+
+### 4.4 自定义 limit
+```
+调用: get_trader_trades(address=<trader>, limit=5)
+预期: 返回 5 笔交易
+验证:
+- trades.length <= 5
+```
+
+---
+
+## 执行记录
+
+| Test Case | 状态 | 结果 | 备注 |
+|-----------|------|------|------|
+| 1.1 get_leaderboard 默认 | - | - | - |
+| 1.2 get_leaderboard limit | - | - | - |
+| 1.3 get_leaderboard 分页 | - | - | - |
+| 2.1 get_trader_profile 有效 | - | - | - |
+| 2.2 get_trader_profile 无效 | - | - | - |
+| 3.1 get_trader_positions 有持仓 | - | - | - |
+| 3.2 get_trader_positions 无持仓 | - | - | - |
+| 4.1 get_trader_trades 默认 | - | - | - |
+| 4.2 get_trader_trades BUY | - | - | - |
+| 4.3 get_trader_trades SELL | - | - | - |
+| 4.4 get_trader_trades limit | - | - | - |
+
+---
+
+## 发现的问题
+
+| ID | 问题描述 | 严重性 | 状态 |
+|----|---------|--------|------|
+| - | - | - | - |