# 加密货币市场数据和技术指标计算 MCP 服务

这是一个从 Go 项目抽取的加密货币技术指标计算服务，封装为标准的 MCP 服务，提供：

1. **高效的指标计算**：使用序列增量计算（O(n)时间复杂度）
2. **清晰的数据结构**：参考 Go 项目的 `market.Data` 结构
3. **多时间框架支持**：支持从1分钟到1周的完整周期（1m/3m/5m/15m/30m/1h/2h/4h/6h/12h/1d/1w）
4. **Aster DEX 集成**：直接从 Aster DEX 获取实时加密货币数据
5. **MCP 协议**：标准的 MCP 服务，可被任何 MCP 客户端调用

## 特点

### 1. 完全来自 Go 项目
本服务是对 Go 项目 `pkg/market/data.go` 的 Python 重写，保持了：
- **相同的数据结构**：`MarketData`, `IntradaySeriesData`, `OIData`
- **相同的计算逻辑**：EMA、MACD、RSI、ATR、布林带
- **相同的优化策略**：序列增量计算，O(n) 时间复杂度
- **相同的MACD规则**：MACD柱乘以2，与交易所显示一致

### 2. 技术优势
- **Aster API**：获取真实的加密货币数据（BTC, ETH, SOL等）
- **TA-Lib**：成熟的技术指标库
- **无需配置**：直接使用公开API，无需API密钥
- **易于扩展**：Python 生态丰富

## 安装

### 1. 安装依赖

```bash
# 进入 crypto_mcp 目录
cd crypto_mcp

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

**注意**: TA-Lib 需要先安装 C 库：
- **macOS**: `brew install ta-lib`
- **Ubuntu/Debian**: `sudo apt-get install ta-lib`
- **Windows**: 下载预编译的 whl 文件

### 2. 无需配置

本服务直接使用 Aster DEX 的公开API，无需配置环境变量或API密钥。

## 使用方法

### 方法 1: 独立测试（不使用 MCP）

```bash
# 运行测试脚本
python test_crypto_indicators.py
```

这会测试：
- 单个交易对的指标计算（BTC, ETH, SOL）
- 多时间框架分析（1d, 4h, 1h, 15m）
- 山寨币指标获取（SOL, AVAX, MATIC, ARB）
- 不同时间框架的价格变化

### 方法 2: 作为 MCP 服务运行

```bash
# 启动 MCP 服务器
python crypto_indicators_mcp.py
```

### 方法 3: 使用 MCP 客户端

```bash
# 运行客户端示例
python crypto_indicators_client_example.py
```

### 方法 4: 在 Claude Desktop 中使用

在 Claude Desktop 配置文件中添加：

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

```json
{
  "mcpServers": {
    "crypto-indicators": {
      "command": "python3",
      "args": ["/path/to/nofx/backend/crypto_mcp/crypto_indicators_mcp.py"]
    }
  }
}
```

然后在 Claude Desktop 中使用：

```
请使用 get_crypto_indicators 工具获取 BTC 的 1小时 技术指标
```

### 方法 5: 使用 MCP Inspector 测试

```bash
# 安装 MCP Inspector
npx @modelcontextprotocol/inspector python3 crypto_indicators_mcp.py
```

这会打开一个 Web 界面，可以可视化地测试 MCP 工具。

## API 文档

### 工具 1: `get_crypto_indicators`

获取指定加密货币和周期的技术指标数据。

**参数**:
- `symbol` (必需): 交易对代码（例如：`BTC`, `ETH`, `BTCUSDT`, `ETHUSDT`）
- `timeframe` (可选): 时间周期
  - **分钟级**: `1m`, `3m`, `5m`, `15m`, `30m`
  - **小时级**: `1h`, `2h`, `4h`, `6h`, `12h`
  - **日周**: `1d`, `1w`
  - 默认: `1h`
- `limit` (可选): 获取K线数量
  - 短周期（分钟）: 建议 500-1000
  - 中周期（小时）: 建议 500-1000
  - 长周期（日/周）: 建议 200-500
  - 默认: `1000`

**返回**:
```json
{
  "symbol": "BTCUSDT",
  "timeframe": "1h",
  "current_price": 43250.50,
  "price_change_1h": 0.85,
  "price_change_4h": 2.15,
  "current_ema20": 43100.20,
  "current_ema60": 42900.10,
  "current_macd_hist": 45.23,
  "current_rsi7": 65.2,
  "current_rsi14": 58.3,
  "current_atr14": 250.85,
  "open_interest": {
    "latest": 1234567.89,
    "average": 1234567.89
  },
  "funding_rate": 0.0001,
  "intraday_series": {
    "mid_prices": [43100, 43150, 43200, ...],
    "ema20_values": [43050, 43080, 43100, ...],
    "macd_hist": [40.5, 42.0, 45.2, ...],
    "rsi7_values": [62.5, 64.0, 65.2, ...],
    ...
  },
  "timestamp": "2025-01-17T10:30:00Z"
}
```

### 工具 2: `get_multi_timeframe_analysis`

获取指定加密货币的多时间框架分析。

**参数**:
- `symbol` (必需): 交易对代码
- `timeframes` (可选): 时间周期列表，默认 `["1d", "4h", "1h", "15m"]`
  - 支持任意组合：从 `1m` 到 `1w` 的所有周期

**返回**:
多个时间框架的数据汇总（Markdown 格式）。

## 数据结构

### `MarketData`
```python
@dataclass
class MarketData:
    symbol: str                    # 交易对代码
    timeframe: str                 # 时间周期
    current_price: float           # 当前价格
    price_change_1h: float         # 1小时价格变化百分比
    price_change_4h: float         # 4小时价格变化百分比
    current_ema20: float           # 当前EMA20
    current_ema60: float           # 当前EMA60
    current_macd_hist: float       # 当前MACD柱（HIST = DIF - DEA）
    current_rsi7: float            # 当前RSI(7)
    current_rsi14: float           # 当前RSI(14)
    current_atr14: float           # 当前ATR(14)
    open_interest: Optional[OIData]  # 持仓量数据
    funding_rate: float            # 资金费率
    intraday_series: IntradaySeriesData  # 日内序列数据
    timestamp: str                 # 时间戳
```

### `IntradaySeriesData`
```python
@dataclass
class IntradaySeriesData:
    mid_prices: List[float]        # 收盘价序列（最近10个）
    volume_values: List[float]     # 成交量序列
    ema20_values: List[float]      # EMA20序列
    ema60_values: List[float]      # EMA60序列
    macd_dif: List[float]          # MACD DIF序列
    macd_dea: List[float]          # MACD DEA序列
    macd_hist: List[float]         # MACD HIST序列
    rsi7_values: List[float]       # RSI7序列
    rsi14_values: List[float]      # RSI14序列
    atr14_values: List[float]      # ATR14序列
    bb_upper: List[float]          # 布林带上轨
    bb_middle: List[float]         # 布林带中轨
    bb_lower: List[float]          # 布林带下轨
```

### `OIData`
```python
@dataclass
class OIData:
    latest: float    # 最新持仓量
    average: float   # 平均持仓量
```

## 支持的技术指标

1. **趋势指标**:
   - EMA20: 20周期指数移动平均线
   - EMA60: 60周期指数移动平均线

2. **动量指标**:
   - MACD: 包括 DIF、DEA、HIST（柱状图 = (DIF-DEA)×2，与交易所显示一致）
   - RSI7: 7周期相对强弱指标
   - RSI14: 14周期相对强弱指标

3. **波动性指标**:
   - ATR14: 14周期平均真实波动幅度
   - 布林带: 上轨、中轨、下轨

4. **市场数据**:
   - 当前价格、价格变化百分比
   - 持仓量（Open Interest）
   - 资金费率（Funding Rate）
   - 历史价格序列

## 示例

### 示例 1: 获取 BTC 的1小时指标

```python
from crypto_indicators_mcp import CryptoDataProvider

provider = CryptoDataProvider()
data = provider.get_market_data("BTC", "1h", 500)

print(f"当前价格: ${data.current_price}")
print(f"EMA20: ${data.current_ema20}")
print(f"RSI7: {data.current_rsi7}")
print(f"资金费率: {data.funding_rate}")
```

### 示例 2: 多时间框架分析

```python
symbols = ["BTC", "ETH", "SOL"]
timeframes = ["1d", "4h", "1h", "15m"]

for symbol in symbols:
    for tf in timeframes:
        data = provider.get_market_data(symbol, tf)
        print(f"{symbol} ({tf}): 价格=${data.current_price}, RSI7={data.current_rsi7}")
```

### 示例 3: 监控山寨币

```python
altcoins = ["SOL", "AVAX", "MATIC", "ARB", "OP"]

for coin in altcoins:
    data = provider.get_market_data(coin, "15m", limit=200)
    if data:
        print(f"{coin}: ${data.current_price:.4f}")
        print(f"  RSI(7): {data.current_rsi7:.2f}")
        print(f"  MACD柱: {data.current_macd_hist:.3f}")
        print(f"  1h变化: {data.price_change_1h:.2f}%")
```

## 性能特点

1. **序列增量计算**: 所有指标使用 TA-Lib 的优化算法，O(n) 时间复杂度
2. **并发支持**: 多时间框架分析可并发获取数据
3. **实时数据**: 直接从 Aster DEX 获取最新数据

## 与 Go 项目的对比

| 特性 | Go 项目 | Python crypto_mcp |
|------|---------|-------------------|
| 数据源 | Aster API (加密货币) | Aster API (加密货币) |
| 指标计算 | 手动实现 | TA-Lib |
| 时间复杂度 | O(n) | O(n) |
| 数据结构 | market.Data | MarketData |
| MACD规则 | HIST × 2 | HIST × 2 |
| 多时间框架 | ✅ | ✅ |
| MCP 支持 | ❌ | ✅ |
| API 密钥 | 不需要 | 不需要 |

## 支持的交易对

理论上支持 Aster DEX 所有的 USDT 交易对，包括但不限于：

**主流币**: BTC, ETH, BNB
**DeFi**: AVAX, MATIC, ARB, OP, UNI, AAVE
**Layer1**: SOL, ADA, DOT, ATOM
**其他**: DOGE, SHIB, LINK, etc.

使用时可以省略 "USDT" 后缀，服务会自动添加。

## 常见问题

### 1. TA-Lib 安装失败？

确保先安装了 TA-Lib 的 C 库：
```bash
# macOS
brew install ta-lib

# Ubuntu/Debian
sudo apt-get install ta-lib

# 然后安装 Python 包
pip install TA-Lib
```

### 2. 如何获取更多历史数据？

调整 `limit` 参数：
```python
# 获取更多K线数据
data = provider.get_market_data("BTC", "1h", limit=2000)
```

### 3. 支持哪些时间周期？

支持: `1m`, `3m`, `5m`, `15m`, `30m`, `1h`, `2h`, `4h`, `6h`, `12h`, `1d`, `1w`

### 4. 数据从哪里来？

直接从 Aster DEX 的公开 API 获取，无需注册或API密钥。

## 开发计划

- [x] 基础指标计算
- [x] 多时间框架支持
- [x] MCP 服务封装
- [x] Open Interest 和 Funding Rate
- [ ] 缓存机制
- [ ] 更多技术指标（KDJ、CCI等）
- [ ] WebSocket 实时数据
- [ ] 性能优化

## 许可证

MIT License

## 相关文档

- [Go 项目 CLAUDE.md](../CLAUDE.md)
- [Go market/data.go](../pkg/market/data.go)
- [Aster DEX 文档](https://docs.asterdex.com)
- [MCP 协议文档](https://modelcontextprotocol.io/)