# Crypto MCP

下载 **OKX / Binance K 线** 并缓存到 DuckDB，通过 HTTP streamable MCP 暴露给国内 agent 远程调用。默认走 **OKX USDT 永续**（超短线合约价）；也可拉 OKX 现货（含代币化美股）和 Binance 现货。

服务设计为部署在**海外服务器**（直连交易所）；国内客户端把 MCP 地址指向它即可。数据按短线定位：短周期只保留滚动窗口，不全量存储。

> 本次 schema 含 `exchange` + `market`，与旧库不兼容。首次升级请删除 `data/crypto/klines.db` 后按需重新拉取。

## MCP 工具

| 工具 | 参数 | 说明 |
|---|---|---|
| `get_klines` | `symbol, interval, start, end=None, limit=300, exchange=okx, market=swap` | 拉取 [start, end]（UTC，end 默认当前时间）K 线，写入缓存并剪枝，按时间升序返回，最多 `limit` 条（1..1000） |
| `sync_klines` | `symbol, interval, lookback=5, exchange=okx, market=swap` | 增量同步：缓存里已有该对就只拉缺口；否则拉最近 `lookback` 根。返回新增条数、覆盖范围、最新一根 |
| `list_symbols` | `exchange=okx, market=swap, asset_class=None` | USDT 交易对（内存缓存 1 小时）。`asset_class` 可滤 `crypto` / `equity` |
| `store_status` | `symbol=None, interval=None, exchange=None, market=None` | 只读缓存：每个 (exchange, market, symbol, interval) 的条数与首末时间 |

- `symbol`：如 `BTCUSDT`、`BTC-USDT`、`BTC-USDT-SWAP`、`XTSLAUSDT`（OKX 代币化美股现货）、`TSLAUSDT`（OKX 美股永续）。大小写不敏感。
- `interval`：`1m 3m 5m 15m 30m 1h 2h 4h 6h 8h 12h 1d 3d 1w 1M`。OKX 不支持 `8h`；日线及以上用 UTC 开盘（`1Dutc` 等）。
- `exchange`：`okx` \| `binance`。`market`：`spot` \| `swap`（Binance 仅 spot）。

## 本地运行

```bash
uv sync
uv run crypto-mcp
```

端点：`http://127.0.0.1:8770/mcp/full`

## 海外部署

```bash
# 服务器上
uv sync
cp .env.example .env
# 编辑 .env：
#   CRYPTO_MCP_HOST=0.0.0.0
#   CRYPTO_MCP_ALLOW_REMOTE=true
#   （可选）CRYPTO_MCP_HTTP_PROXY=http://127.0.0.1:7890
uv run crypto-mcp
```

国内客户端（opencode 等）配置示例：

```json
{
  "mcp": {
    "crypto": {
      "type": "remote",
      "url": "http://<海外服务器IP>:8770/mcp/full"
    }
  }
}
```

## 保留窗口（短线优先）

| interval | 保留 |
|---|---|
| 1m / 3m | 2 天 |
| 5m / 15m | 3 天 |
| 30m | 7 天 |
| 1h | 14 天 |
| 2h | 30 天 |
| 4h / 6h | 45 天 |
| 8h / 12h | 60 天 |
| 1d | 730 天 |
| 3d | 1095 天 |
| 1w | 1825 天 |
| 1M | 3650 天 |

每次写库后自动按窗口剪枝（`DELETE open_time < now - 窗口`），保证短线数据不会无限膨胀。

## 开发检查

```bash
uv run pytest
uv run ruff check .
```

## 安全提醒

v0.1 无鉴权。绑定 `0.0.0.0` 时必须显式设置 `CRYPTO_MCP_ALLOW_REMOTE=true`；只暴露在可信网络，或前面挂带鉴权的反向代理（如 nginx + basic auth）。