# 同花顺网页模拟交易 MCP 服务

把同花顺交易系统封装成通用 MCP 服务（stdio），供各类 AI Agent 调用。


## 实践案例：两个 MCP 配合，全自动化炒股

- 本项目的MCP服务负责「账户持仓」「下单交易」
- [同花顺 iFinD AI 金融数据服务](https://mcp.51ifind.cn)负责「查数据选股」「查行情指标」（同花顺有免费试用额度）。

两个服务同时接入同一个 AI Agent（如 hermes、codex、claude desktop、 workbuddy、trae work和deepseek harness等）后，
你只需告诉 AI「按 XX 策略自动炒股」，它就会自己用 iFinD 查行情选股，再用交易服务自动
下单、撤单、查成交，全程不用人工操作账户。

### 重要提醒

- **先启动浏览器并登录**同花顺交易系统（见「使用前提」），交易服务才能下单。
- **下单只支持市价**，数量须为 100 的整数倍；买入前 AI 会先查资金，卖出前会先查持仓。
- **AI炒股，各显神通，盈亏自负！**，不要滥用本工具，更不能用于商业化。
- 本项目只能模拟炒股，如果交易策略得到验证想上线真实账户怎么办？请您联系作者会有解决方案！

## 使用前提

1. 人工启动浏览器（详见 `启动浏览器.bat`）：Chrome 开启 9222 调试端口，使用独立用户目录 `chrome_profile`。
2. 人工登录同花顺交易系统，并进入交易页面。
3. 满足以上条件后 MCP 服务才能正常工作；否则各工具会返回明确的中文错误提示。

## 环境

- **推荐 Python 版本：3.11**（`mcp` 依赖要求 `>=3.10`，3.10–3.12 均可正常使用）
- Python 环境：项目内 `.venv`（虚拟环境，见下节创建方式）
- 依赖：`.venv/Scripts/python.exe -m pip install -r requirements.txt`
- 说明：Playwright 通过 CDP 连接已打开的浏览器，**不需要下载浏览器内核**；也不存储任何账号凭证，完全依赖人工登录好的会话。

### 创建 Python 虚拟环境

首次使用需在项目根目录创建 `.venv`（方式二选一）：

```bash
# 方式一：标准库 venv（需本机已安装 Python 3.11，可用 py -3.11 指定版本）
py -3.11 -m venv .venv

# 方式二：uv（更快，未装对应版本时自动下载，推荐）
uv venv --python 3.11 .venv
```

创建完成后安装依赖：

```bash
.venv/Scripts/python.exe -m pip install -r requirements.txt
```

> Windows 下解释器路径为 `.venv/Scripts/python.exe`（Linux/macOS 为 `.venv/bin/python`），
> 后文所有命令均以 `.venv/Scripts/python.exe` 为准。


## MCP 配置教程

本服务通过 **stdio 传输**运行，任何支持 MCP 的客户端都可接入。核心配置只有一行：
用项目 `.venv` 的 Python 解释器启动 `server.py`。

### 通用配置（各Ai Agent 通用）

```json
{
  "mcpServers": {
    "ths-stock-trading-mcp": {
      "command": "D:/workspace_github/ai_ths_moni_trading_mcp/.venv/Scripts/python.exe",
      "args": ["D:/workspace_github/ai_ths_moni_trading_mcp/server.py"]
    }
  }
}
```

> Windows 路径可用正斜杠 `D:/...`；若你的 `.venv` 实际路径不同，按需修改 `command`。

### 验证是否连上

接入后应能看到 5 个工具：`query_account_and_positions` / `query_deals` / `query_orders` /
`place_order` / `cancel_order`。可用 `query_account_and_positions` 做连通性验证（需浏览器已登录）。

## 工具

| 工具 | 说明 |
|---|---|
| `query_account_and_positions` | 查看账户资金与持仓信息（可用余额、资金余额、总资产、证券市值等及持仓明细） |
| `query_deals` | 查看当日成交 |
| `query_orders` | 查看当日委托 |
| `place_order` | 市价委托买入/卖出（`direction`/`stock_code`/`quantity`，数量为 100 的整数倍，仅市价单） |
| `cancel_order` | 撤销未成交委托（`order_id` 为委托号） |

## 测试

```bash
.venv/Scripts/python.exe -m pytest -v            # 单元测试
PYTHONPATH=. .venv/Scripts/python.exe scripts/e2e.py        # 真实浏览器端到端（需已登录浏览器）
PYTHONPATH=. .venv/Scripts/python.exe scripts/mcp_smoke.py  # MCP stdio 协议冒烟
```

## 服务配置

项目根目录 `config.yaml`：

- `cdp_endpoint`：Chrome 远程调试地址，默认 `http://127.0.0.1:9222`。若改了 `启动浏览器.bat`
  里的调试端口，需同步修改此项。
- `slow_ms`：慢速观察模式延时（见下节）。
- `refresh_before_tool`：每次 MCP 工具运行前是否先刷新交易页探测登录超时。
  `true`（默认）= 每次调用先 reload 交易页检测会话，超时则自动关掉失效 tab、重进交易区；
  `false` = 走原快速路径（仅右上角账户号异常时才刷新式探测）。
  若 8/18 下单失败类问题（刷新后行情加载失效）复发，可设 `false` 一键回退。
- `delays`：下单/撤单各步骤延时（毫秒），可按网络/平台状况针对性调大以提高成功率。
  其中 `quote_timeout` 超时会**不点下单按钮**、直接返回「下单失败：行情数据未加载…未提交委托」；
  `js_settle` 是刷新交易页后等待页面 JS 初始化完成的延时（默认 3000）。
  未配置的键自动用默认值（菜单 300 / 面板 800 / 行情与弹窗超时 8000 / 撤单生效 1000 / JS 就绪 3000）。

## 慢速观察模式

MCP 工具操作浏览器默认很快（1-2 秒跑完），不便人工逐步骤观察核实。通过项目根目录
`config.yaml` 的 `slow_ms` 开启慢速模式：每次浏览器操作之间延时该毫秒数，并在服务
stderr 日志中打印中文步骤（如「填写证券代码 600000 并按回车加载行情」「点击买入下单提交」）。

在 `config.yaml` 中把 `slow_ms` 改为 `1200`（每次操作停顿 1.2 秒），重启 MCP 服务会话即可生效：

```yaml
# config.yaml
slow_ms: 1200
```

设为 `0` 即为原速。用文件而非环境变量，是为了兼容各类不注入环境变量的 AI Agent 客户端。

## 已知限制

- 下单依赖平台后端行情服务，偶发返回「暂时不提供[柜台查询证券行情(B)]/后台查询证券代码(B) 功能的服务」——这是交易平台侧临时故障，重试或稍后再试即可。
- 撤单仅在委托「未成交」时可执行；已成交/已撤的委托不会出现在可撤列表中，`cancel_order` 会返回明确提示。

## 目录结构

- `server.py` — MCP 服务入口（FastMCP, stdio）
- `config.yaml` — 服务配置（慢速观察模式等）
- `.mcp.json` — Claude Code 的 MCP 接入配置
- `ths/` — 业务逻辑（浏览器控制、选择器、解析器、页面操作、错误）
- `scripts/` — 勘察/端到端/协议冒烟脚本
- `tests/` — 单元测试与真实页面 fixture