# quantdb-mcp

量化金融数据库 + 只读 SQL MCP 服务。

- **数据源**：easy-tdx（通达信 TCP 行情）+ pywestockdata（腾讯/东财基本面 HTTP）
- **存储**：DuckDB 双文件 —— `quantdb_ods.duckdb`（ODS 原始层）/ `quantdb.duckdb`（DWD 层，清洗后）
- **接口**：FastMCP streamable-http 只读 `query(sql)` 工具（可跨库 JOIN）

## 分层架构

| 层 | 库文件 | 表 |
|----|--------|----|
| ODS | quantdb_ods.duckdb | stock_basic / daily_kline / realtime_quote / finance_income / finance_balance / finance_cashflow |
| DWD | quantdb.duckdb | dim_stock（去重标准化）/ fact_daily（列名统一） |
| APP | - | 后续因子层（可复用 factor-pipeline 表达式引擎） |

ODS 可整体重灌，DWD 由 `sync_dwd` 全量重建（幂等）。

## 安装

```bash
cd projects/quantdb-mcp
uv sync                       # 或 pip install -e .
```

依赖：duckdb、fastmcp、pywestockdata、easy-tdx、click。

## CLI

```bash
quantdb init                  # 建库建表（双文件）
quantdb full-load             # 全量同步：代码表 → 日K → 财务 → DWD 重建
quantdb full-load --codes 50 --kline-count 120   # 限前 50 只、每只 120 根K线（试跑用）
quantdb update --once         # 增量同步 + 一次实时快照
quantdb update                # 盘中 30s 快照循环（Ctrl+C 退出）
quantdb summary               # 各表行数与最新日期
```

数据目录通过环境变量 `QUANTDB_DATA_DIR` 指定（默认 `./data`）。

## MCP 接入

启动服务（streamable-http）：

```bash
uv run python -m quantdb.server.mcp   # 等价 pip 安装后的 quantdb-mcp
```

注册到 MCP 客户端（如 nanobot / Claude Desktop）：

```json
{
  "mcpServers": {
    "quantdb": {
      "command": "quantdb-mcp",
      "type": "stdio"
    }
  }
}
```

查询示例（`query` 工具，只读）：

```text
SELECT * FROM dim_stock WHERE market = 'sh' LIMIT 5
SELECT d.code, s.name, d.close FROM fact_daily d JOIN ods.stock_basic s ON d.code = s.code
  WHERE d.date = (SELECT max(date) FROM fact_daily)
```

## 安全限制

- 仅允许单条 `SELECT` / `WITH`；写语句、多语句被拒绝
- 表白名单：仅业务表（ODS 用 `ods.` 前缀），内部表不可见
- 最多返回 10_000 行；查询超时 30s；DuckDB 以只读模式打开

## 测试

```bash
uv run pytest                    # 97 tests，100% 覆盖率（mock 数据源，不依赖网络）
uv run ruff check src tests      # 0 error
```

详见 `design.md` 与 `task_list.md`。