# TDX Local MCP — 通达信本地终端 MCP 服务

直连运行中的通达信客户端（tqcenter / TPythClient.dll），将 36 个 tqcenter 公开 API 全量封装为 **49 个 MCP 工具**，并提供本地扩展：自动价格预警引擎与模拟交易通道。

## 功能概览

| 分组 | 数量 | 工具 |
|---|---|---|
| 连接状态 | 1 | tdx_status |
| 行情与报价 | 4 | tdx_kline / tdx_snapshot / tdx_divid_factors / tdx_money_flow |
| 基础信息 | 6 | tdx_stock_info / tdx_stock_list / tdx_trading_calendar / tdx_trading_dates / tdx_cb_info / tdx_ipo_info |
| 财务与专业数据 | 9 | tdx_financial_data(_by_date) / tdx_gpjy_value(_by_date) / tdx_bkjy_value(_by_date) / tdx_scjy_value(_by_date) / tdx_gp_one_data |
| 板块与自选股 | 8 | tdx_sector_list / tdx_user_sector / tdx_sector_stocks / tdx_create_sector / tdx_delete_sector / tdx_rename_sector / tdx_clear_sector / tdx_send_user_block |
| 数据维护与订阅 | 6 | tdx_download_file / tdx_refresh_cache / tdx_refresh_kline / tdx_hq_subscribed_list / tdx_subscribe_hq / tdx_unsubscribe_hq |
| 终端推送 | 4 | tdx_send_warn / tdx_send_message / tdx_send_file / tdx_send_bt_data |
| 模拟交易 | 6 | tdx_trade_account / tdx_query_asset / tdx_query_positions / tdx_query_orders / tdx_order_stock / tdx_cancel_order |
| 自动价格预警 | 6 | tdx_alert_add / tdx_alert_list / tdx_alert_remove / tdx_alert_history / tdx_alert_check_now / tdx_alert_notify_test |

完整接口签名与返回结构见 [INTERFACE.md](INTERFACE.md)。

## 前置条件

1. 已安装**支持 TQ 策略**的通达信终端（金融终端/专业研究版/量化模拟版/期货通），安装目录如 `D:\new_tdx_mock`
2. Windows Python（3.10+，建议 3.14）已安装依赖：
   ```
   python -m pip install mcp pandas numpy
   ```
3. 终端已启动并登录（行情登录即可；交易工具需另登录交易）

## 快速开始（任意 MCP 客户端）

在 MCP 客户端配置中添加（路径按你的安装位置调整）：

```json
{
  "mcpServers": {
    "tdx-local": {
      "command": "C:\\Python314\\python.exe",
      "args": ["D:\\path\\to\\tdx-local-mcp\\run_server.py"],
      "env": {
        "TDX_ROOT": "D:\\new_tdx_mock",
        "TDX_MCP_POLL_INTERVAL": "30"
      }
    }
  }
}
```

## WSL 部署（openclaw）

WSL2 的 Linux Python 无法加载 Windows DLL（invalid ELF header），必须经 WSL interop 用 Windows Python 拉起：

```json
{
  "mcpServers": {
    "tdx-local": {
      "command": "/mnt/c/Python314/python.exe",
      "args": ["D:/path/to/tdx-local-mcp/run_server.py"],
      "env": {
        "TDX_ROOT": "D:/new_tdx_mock",
        "TDX_MCP_POLL_INTERVAL": "30"
      }
    }
  }
}
```

openclaw 插件部署（源码在 D 盘会被 777 world-writable 安全策略拦截，须复制到 WSL 原生目录）：

```bash
bash deploy_openclaw.sh          # 复制 4 个插件文件到 ~/.openclaw/extensions/tdx-local-mcp/
openclaw gateway restart         # 重启网关加载
```

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `TDX_ROOT` | `D:\new_tdx_mock` | 通达信安装目录（tqcenter.py 与 TPythClient.dll 所在） |
| `TDX_INIT_PATH` | `tdx_local_mcp_{PID}` | 策略连接标识（多实例并存） |
| `TDX_MCP_POLL_INTERVAL` | `30` | 预警引擎轮询间隔（秒，最小 5） |
| `TDX_MCP_ALERT_RULES` | 项目根\alerts_rules.json | 预警规则持久化路径 |
| `TDX_MCP_ALERT_LOG` | 项目根\alerts_log.jsonl | 预警触发历史路径 |
| `TDX_MCP_NOTIFY_AGENT` | 空（关闭） | 预警触发后主动唤起的 openclaw agent id（如 shin-nosuke），实现客户端对智能体的主动触发 |
| `TDX_MCP_NOTIFY_WINDOW` | `60` | 通知聚合窗口（秒）：多条预警合并为一次智能体唤起 |
| `TDX_MCP_OPENCLAW_BIN` | `~/.npm-global/bin/openclaw` | openclaw 可执行路径 |

**TDX_ROOT 必须指向终端实际运行目录**——DLL 与终端经本机进程通信，路径不一致会连接失败。

## 数据规范

- 证券代码：`6位数字.市场后缀`（600519.SH / 000001.SZ / 832566.BJ）
- 价格单位元；成交量：快照=手、K线 Volume 列=股；成交额=万元
- 时间：YYYYMMDD 或 YYYYMMDDHHMMSS
- 复权：none / front / back（默认 front）
- 周期：1m/5m/10m/15m/30m/1h/1d/1w/1mon/45d/1q/1y；K线单次上限 24000 条

## 测试

```bash
python smoke_test.py          # 冒烟：连接/K线/快照/板块/预警闭环/终端推送（14 项）
python mcp_client_test.py     # MCP 协议端到端（8 项）
python consistency_check.py   # 数据一致性（K线 vs .day 文件交叉比对）
python trade_test.py          # 模拟交易全链路（须交易日交易时段）
python cancel_test.py         # 撤单闭环：低价挂单→轮询同步→撤单→状态确认（须交易时段）
python notify_unit_test.py    # 通知器单元测试：路径转换/聚合窗口/命令构造（19 项，无需终端）
python notify_mcp_test.py     # 通知链路 MCP 协议测试：工具发现/直发/预警触发→CLI（13 项）
python notify_e2e_test.py     # 通知端到端：预警触发→唤起 openclaw 智能体（需 WSL+openclaw）
python listen_mcp_test.py     # 行情监听开关测试：start/stop/规则标的保护（13 项）
python hq_freq_test.py        # 直连订阅推送频率实测（盘中完整快照/盘外 ~6s 空心跳）
python listen_freq_test.py    # 监听开关路径推送频率实测（与预警引擎共享回调）
wsl python3 wsl_e2e_test.py   # WSL→Windows 跨系统 MCP 链路（在 WSL 中运行）
```

## 官方 API 对齐

三层真源：官方文档（[help.tdx.com.cn/quant/docs](https://help.tdx.com.cn/quant/docs/)，语义基准）→ 本地 `tqcenter.py`（运行真源，参数透传以此为准）→ 50 个 MCP 工具（消费契约）。两源不一致处在工具 docstring 中以 ⚠️ 标注（本地版实测差异：快照最高最低键名为 Max/Min、get_trading_dates 需 market 参数、subscribe_hq 强制回调等）。

## 客户端→智能体主动通知

预警引擎触发后可反向唤起 openclaw 智能体（终端行情/预警 → MCP server → agent），实现客户端对智能体的主动触发：

```
通达信终端 ──subscribe_hq 推送──> 预警引擎（规则命中）
                                    ├─ send_warn → 终端预警窗口
                                    ├─ 落盘 alerts_log.jsonl
                                    └─ notifier 聚合（60s 窗口合并）
                                          └─ openclaw agent → 目标智能体（如新之助）自主调用 tdx_* 工具研判
```

启用：MCP server 进程环境变量设 `TDX_MCP_NOTIFY_AGENT=<agent id>`（部署脚本 deploy_openclaw.sh 默认注入 shin-nosuke，可用 `TDX_NOTIFY_AGENT` 覆盖或留空关闭）。链路验证用 `tdx_alert_notify_test` 工具（直发）或 `notify_e2e_test.py`（完整链路）。

## 行情回调监听开关

`tdx_subscribe_hq` 是终端→server 的唯一推送通道（官方文档标称每 6 秒回调一次，上限 100 只）。`tdx_hq_listen_start/stop` 在预警规则之外独立管理订阅——不需要挂价格规则即可获得实时行情回调：

```
tdx_hq_listen_start(["600519.SH", ...])   # 启动纯监听，重复调用追加
tdx_hq_listen_stop(["600519.SH"])         # 停止部分；不传参数停全部
                                           # 已有预警规则标的自动保护，不被退订
```

监听标的与预警规则标的由引擎统一订阅（共享 `_on_hq_update` 回调入口），`tdx_status` 的 `alert_engine.hq_listen` 可查当前状态。用途：纯数据订阅、自定义触发维度扩展（涨跌幅/量比/五档等可直接写在回调链上）。推送频率实测脚本：`hq_freq_test.py`（直连订阅）/ `listen_freq_test.py`（监听开关路径）。

## 免责声明

本项目仅供学习研究。交易工具仅在通达信**模拟交易**环境验证；接入实盘风险自负，作者不承担任何资金损失责任。