ai_ths_moni_trading_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

把同花顺交易系统封装成通用 stdio MCP 服务（ths-stock-trading-mcp），供各类 AI Agent 调用。 浏览器由人工启动并登录，服务通过 Chrome 调试端口（9222）挂接现有浏览器操作页面，不启动 新浏览器、不存储凭证。提供 5 个工具：query_account_and_positions / query_deals / query_orders / place_order（仅市价）/ cancel_order。

常用命令

环境全部用项目内 .venv（Windows 路径 .venv/Scripts/python.exe）。

# 安装依赖
.venv/Scripts/python.exe -m pip install -r requirements.txt

# 运行全部测试
.venv/Scripts/python.exe -m pytest -v
# 单个测试（pytest.ini 设了 asyncio_mode=auto，async 测试函数自动收集）
.venv/Scripts/python.exe -m pytest tests/test_tools_place_order.py::test_place_order_buy -v

# 启动 MCP 服务（stdio，等待客户端连接）
.venv/Scripts/python.exe server.py

# 真实浏览器端到端（需浏览器已登录）
PYTHONPATH=. .venv/Scripts/python.exe scripts/e2e.py
# MCP stdio 协议冒烟
PYTHONPATH=. .venv/Scripts/python.exe scripts/mcp_smoke.py

人工前置步骤：运行 启动浏览器.bat → 登录同花顺 → 进入交易页面（标题「同花顺虚拟交易所」）。 不满足时工具返回中文报错（见「浏览器前置」）。

架构

server.py       FastMCP(stdio) 入口，注册 5 个 async 工具（薄层）
ths/
  browser.py    CDP 挂接 9222 + 健康检查（未开/未找到页/未登录→三类错误）
  selectors.py  全部真实 DOM 选择器（唯一来源，页面改版只改这里）
  actions.py    页面导航（左侧菜单）、place_market_order、cancel_order、弹窗辅助
  parsers.py    表头驱动表格解析（thead th 为键）+ 账户(id 节点) 读取
  config.py     读取项目根 config.yaml（slow_ms 慢速观察模式）
  errors.py     ThsError / BrowserNotRunningError / TradingPageNotFoundError / NotLoggedInError
config.yaml     服务配置（cdp_endpoint / slow_ms / delays 下单撤单步骤延时）
.mcp.json       Claude Code 接入配置

核心设计：

• 全链路 async：FastMCP 在 asyncio 事件循环执行 async 工具；Playwright Sync API 会抛 「It looks like you are using Playwright Sync API inside the asyncio loop」。因此 browser/actions/parsers 的页面操作与 server 工具一律 async（Playwright Async API）。 新增页面操作时必须 await，且不得引入 sync Playwright。
• 选择器集中：真实页面 DOM 集中在 ths/selectors.py（如 table[name='qryChicang']、 #sjwtbuySubmit、#promptWinContainer）。交易页 <meta charset="gbk">、面板经 AJAX 按需加载；市价委托的代码框填码后经联想列表点选加载行情并填充市价类型下拉 （页面自带联想因硬编码 http 地址被 https 混合内容拦截永不弹出，由我们注入 JSONP 数据自渲染列表后点击，见 actions._load_and_click_stock）。
• 健康检查：每个工具先 browser.get_trading_page()——连不上 9222 / 找不到标题页 / 未登录（#topUser 无「你好」）→ 抛对应中文错误，不继续操作。
• 下单/撤单：place 走「市价委托→买入/卖出→填码（延时 suggest_wait）→联想点选 股票→选『剩余撤销』→填数量→提交→ymprompt 确认弹窗→读结果弹窗」；cancel 走「撤单 面板→按委托号勾选 checkbox→点撤单→确认」。点选后先校验行情已刷新（股票名精确等于 期望名称 + 最新价为数字，防残留上一只行情误判），quote_timeout 超时则不点下单、 返回「下单失败：行情数据未加载…未提交委托」；其余 Playwright 超时统一转 ThsError("操作超时，请人工检查页面状态。")。