Metadata-Version: 2.4
Name: tdx-link-mcp
Version: 0.1.7
Summary: 通达信 AI Agent MCP Server - pip + 国内镜像安装，降低用户门槛
Project-URL: Homepage, https://github.com/JueJuez/tdxLinkMcp
Project-URL: Repository, https://github.com/JueJuez/tdxLinkMcp
Project-URL: Issues, https://github.com/JueJuez/tdxLinkMcp/issues
Author: TdxLink Team
License-Expression: MIT
Keywords: ai-agent,mcp,stock,tdx,trading,uac,权限提权,通达信
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# TdxLink — 通达信量化框架 + MCP Server

> 一个项目两种用法:AI Agent 通过 MCP 工具操作通达信,Python 开发者通过 tdx_lib 写量化策略。

## 适合谁看

| 你是 | 用什么 | 看哪段 |
|------|--------|--------|
| AI Agent 用户(用 Cursor/Claude/Trae 等让 AI 操作通达信) | MCP Server | [快速安装](#快速安装) + [MCP 可用工具](#mcp-可用工具) + [AI 调用时机](#ai-调用时机) |
| Python 开发者(自己写选股/交易/回测策略) | tdx_lib 框架 | [框架架构](#框架架构) + [快速上手](#快速上手) |
| 项目维护者(改代码/发版) | 全部 | [目录结构](#目录结构) + `PUBLISH_GUIDE.md` |

---

## 快速安装(MCP Server)

### 方式一:通过 AI 平台安装(最简,推荐)

把下面这段复制给你正在用的 AI Agent,**它只需要执行两条命令**:

```
帮我安装 TdxLink MCP Server(通达信 AI Agent)。

请依次执行以下命令:

第一步 - 安装包(使用国内镜像加速):
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tdx-link-mcp

第二步 - 配置 MCP:
python -m tdx_link_mcp.setup_mcp

完成后告诉我结果。
```

> **为什么用 pip 而不是 uvx？**
> - pip 是 Python 标配，AI 编码平台自带，无需额外安装
> - 清华镜像在国内，下载速度快（vs uvx 从国外服务器下载）
> - 安装后直接 `python -m` 运行，简洁稳定
>
> 支持平台: Trae, Cursor, Claude Code, VS Code/Copilot, Gemini CLI,
> OpenCode, OpenClaw, Cline, Kimi CLI, Pi Agent, Codex CLI,
> Antigravity, Windsurf, Mistral Vibe, Qoder（共 16 个）

### 方式二:一键脚本安装

**Windows(PowerShell):**
```powershell
powershell -c "irm https://raw.githubusercontent.com/JueJuez/tdxLinkMcp/main/install.ps1 | iex"
```

**Mac/Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/JueJuez/tdxLinkMcp/main/install.sh | bash
```

脚本会自动:检测 Python → 用国内镜像安装包 → 检测已装的 AI 工具 → 写入 MCP 配置。

### 方式三:手动安装(高级用户)

**1. 安装包**
```bash
# 使用清华镜像(推荐，国内速度快)
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple tdx-link-mcp

# 或使用阿里镜像
pip install -i https://mirrors.aliyun.com/pypi/simple tdx-link-mcp
```

**2. 配 MCP**

在 AI 工具的 MCP 配置中添加:
```json
{
  "mcpServers": {
    "tdxLink": {
      "command": "python",
      "args": ["-m", "tdx_link_mcp.server"]
    }
  }
}
```

**配置文件位置**(常用平台):
- Trae:`~/.trae/User/mcp.json`(Windows: `%APPDATA%\Trae CN\User\mcp.json`)
- Cursor:`~/.cursor/mcp.json`
- Claude Code/Desktop:`~/.claude/claude_desktop_config.json`(Windows: `%APPDATA%\Claude\claude_desktop_config.json`)
- VS Code:`~/.vscode/mcp.json`
- OpenCode:`~/.config/opencode/opencode.json`(注意:键名是 `mcp` 不是 `mcpServers`)
- 其他:Cline / Kimi CLI / Pi Agent / Codex CLI / Gemini CLI / Antigravity / Windsurf / Qoder / Mistral Vibe

> 如果配置文件已有其他 MCP,把 `tdxLink` 合并进 `mcpServers` 对象,不要覆盖整个文件。
> 非标准格式(OpenCode/OpenClaw/Mistral Vibe)建议直接用 `python -m tdx_link_mcp.setup_mcp` 自动处理。

**3. 重启 AI 工具**

---

### 备选安装方式(uvx)

如果 pip 安装失败，可以尝试 uvx 方式:

```bash
uvx tdx-link-mcp --upgrade
```

uvx 会自动管理 Python 环境，适合没有 Python 的机器。但需先安装 uv 工具:

```bash
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Mac/Linux  
curl -LsSf https://astral.sh/uv/install.sh | sh
```

---

## MCP 可用工具

装好后,AI 会自动发现 7 个工具:

| 工具 | 功能 |
|------|------|
| `ensure_tdx_ready` | 启动/检测通达信客户端 |
| `get_market_info` | 获取股票行情(快照/K线/搜索) |
| `screen_stocks` | 筛选股票(涨跌停/涨幅/市值) |
| `get_financial_info` | 获取财务/交易数据(股东/龙虎榜/融资等) |
| `manage_portfolio` | 管理板块(创建/写入/清空/预警) |
| `execute_trade` | 交易操作(买入/卖出/撤单/查资产) |
| `get_market_stats` | 市场统计(涨跌停家数/涨跌分布) |

### 使用示例

```
你: 帮我查今天涨停的股票
AI: [调用 screen_stocks(limit_up)] → 返回涨停股列表

你: 查贵州茅台的财务数据
AI: [调用 get_financial_info(codes=["600519.SH"])] → 返回财务信息

你: 买入100股贵州茅台
AI: [调用 execute_trade(buy, code="600519.SH", quantity=100)] → 执行交易
```

## AI 调用时机

当用户在 AI 会话中询问以下问题时，会优先调用 TdxLink MCP：
- 股票行情查询
- 股票筛选（涨停/跌停）
- 财务数据分析
- 板块管理
- 交易操作
- 市场统计

### 调用示例
```python
# 获取茅台实时行情
get_market_info(info_type="snapshot", codes=["600519.SH"])

# 筛选涨停股票
screen_stocks(screen_type="limit_up")

# 获取茅台财务数据
get_financial_info(codes=["600519.SH"], data_type="financial")
```

### 测试建议(从无副作用到有副作用)

1. `ensure_tdx_ready` — 确认客户端就绪
2. `get_market_stats`(stat_type=`limit_count`)— 秒查涨跌停家数
3. `get_market_info`(info_type=`snapshot`, codes=`["600519.SH"]`)— 单只快照
4. `get_market_info`(info_type=`kline`, kline_count=`10`)— K线
5. `get_market_info`(info_type=`search`, key_word=`"茅台"`)— 搜索
6. `screen_stocks`(screen_type=`limit_up`)— 涨停筛选(全市场约 2s)
7. `get_financial_info`(data_type=`financial`, codes=`["600519.SH"]`)— 财务
8. `manage_portfolio`(action=`query`)— 查所有自定义板块(只读)
9. `execute_trade`(action=`query_asset`)— 查资产(只读,要交易端登录)
10. 最后才碰有写副作用的:`manage_portfolio` 的 create/send/clear、`execute_trade` 的 buy/sell。**交易务必小额先试**。

---

## 框架架构

> 下面是给 Python 开发者看的。如果你只用 MCP,跳过即可。

```
┌──────────────────────────────────────────────────────────┐
│                    strategies/  策略层                      │
│        用户只写这里: 继承 StrategyBase, 实现 analyze()       │
├──────────────────────────────────────────────────────────┤
│           strategy.py        backtest.py    scheduler.py  │
│           策略生命周期        回测引擎       定时调度        │
├──────────────────────────────────────────────────────────┤
│  data.py      trade.py     portfolio.py   risk.py  grid.py│
│  行情数据     交易下单      板块管理      风控止损  网格交易  │
├──────────────────────────────────────────────────────────┤
│              client.py              utils.py              │
│              HTTP通信               计算工具               │
└──────────────────────────────────────────────────────────┘
```

**设计原则**:策略层只依赖框架层,框架层只依赖服务层,服务层只依赖基础层。换策略不用改基础设施,加功能不用动底层通信。

## 功能清单

| 模块 | 功能 | 状态 |
|------|------|------|
| **client.py** | HTTP JSON-RPC 通信、批量并发调用、连通性检测 | ✅ |
| **launcher.py** | 通达信进程检测/自动拉起/HTTP就绪轮询(一行调用) | ✅ |
| **data.py** | 股票列表、K线、快照、more_info 批量查询、预筛框架 | ✅ |
| **financial.py** | 官方财务/交易数据9接口(FN/GP/BK/SC/GO系列),透传官方 | ✅ |
| **screener.py** | 通用筛选器(透传官方公式B007判定涨跌停,取数优化)、涨跌停家数秒查 | ✅ |
| **selector.py** | 官方公式选股(B007),与客户端"条件选股"一致 | ✅ |
| **guard.py** | 官方优先守卫,运行时强制官方入参 | ✅ |
| **trade.py** | 买入/卖出/市价/限价/涨跌停价/隔夜挂单/批量撤单/账户查询 | ✅ |
| **portfolio.py** | 板块创建/删除/清空/重写、预警信号、客户端跳转 | ✅ |
| **strategy.py** | 策略基类,串联完整生命周期(选股→预筛→分析→输出→写板块) | ✅ |
| **risk.py** | 止损(固定/移动/ATR)、止盈(固定/移动)、仓位管理(固定/比例/凯利) | ✅ |
| **grid.py** | 网格交易(等差/等比),自动低买高卖 | ✅ |
| **backtest.py** | 历史回测,绩效统计(胜率/回撤/夏普/盈亏比) | ✅ |
| **scheduler.py** | 定时执行策略,支持 HH:MM 和 cron 表达式 | ✅ |

> ⚠️ MCP Server 只暴露 7 个工具(覆盖行情/筛选/财务/板块/交易/统计/启动),策略框架、回测、风控、网格、调度这 5 个能力**只给本地 Python 用**,不向 MCP 暴露(设计如此)。

---

## 快速上手

### 1. 选股策略 — 只写 analyze()

```python
# strategies/my_strategy.py
from tdx_lib import StrategyBase, calc_ma, parse_kline_float

class MyStrategy(StrategyBase):
    name = "我的策略"
    block_code = "MINE"
    min_cap = 50
    max_cap = 500

    def analyze(self, code, kline_data):
        parsed = parse_kline_float(kline_data)
        closes = parsed["Close"]
        if len(closes) < 20:
            return None
        ma5 = calc_ma(closes, 5)
        ma20 = calc_ma(closes, 20)
        if ma5 > ma20 and closes[-1] > ma5:
            return {"code": code, "close": round(closes[-1], 2)}
        return None
```

运行: `python run_strategy.py my_strategy`

### 2. 回测 — 一行跑历史数据

```python
from tdx_lib.backtest import BacktestEngine
from strategies.my_strategy import MyStrategy

engine = BacktestEngine(MyStrategy, initial_capital=1_000_000)
engine.trailing_stop = True
report = engine.run(start_offset=60, stock_limit=100)
engine.print_report()
```

### 3. 交易 + 止损止盈

```python
from tdx_lib import TdxClient, TdxTrader, RiskManager, StopLoss

client = TdxClient()
trader = TdxTrader(client)
rm = RiskManager(stop_loss_type=StopLoss.Type.TRAILING, sl_pct=5.0,
                 capital=trader.get_total_asset())

# 买入
volume = rm.calc_volume(price=10.0)
trader.limit_buy("600000", volume, 10.0)
rm.on_buy("600000", 10.0)

# 检查止损
should_exit, exit_price, reason = rm.check_exit("600000", high=10.5, low=9.6)
```

### 4. 网格交易

```python
from tdx_lib import GridTrader

grid = GridTrader("600000", lower_bound=8, upper_bound=12,
                  grid_count=20, volume_per_grid=200)
grid.setup(current_price=10.0)

actions = grid.on_price_update(current_price=10.5)
# → [{"action": "sell", "price": 10.5, "volume": 200, ...}]
```

### 5. 定时自动运行

```python
from tdx_lib import StrategyScheduler

sched = StrategyScheduler()
sched.add_strategy("my_strategy", time_str="15:30")  # 每天15:30选股
sched.add_task(overnight_orders, time_str="14:50", name="隔夜挂单")
sched.run()
```

### 6. 条件筛选 — 涨跌停/涨幅/市值(两层过滤,秒级)

```python
from tdx_lib import TdxClient, StockScreener, get_market_limit_count

client = TdxClient()

# 秒查涨跌停家数 (1次请求, ~0.005s)
r = get_market_limit_count(client)
print(f"涨停 {r['limit_up']} 家, 跌停 {r['limit_down']} 家")

# 涨停明细 (粗筛涨幅 + 精筛触及涨停价, 全市场 ~2s)
results = (StockScreener.from_all_a_stocks(client)
           .where(min_pct=9.8).limit_up().run())

# 任意条件: 涨幅 5-10% 且市值 30-300亿
results = (StockScreener.from_all_a_stocks(client)
           .where(min_pct=5.0, max_pct=10.0)
           .where(min_cap=30, max_cap=300).run())
```

### 运行策略

```bash
# 列出所有可用策略
python run_strategy.py

# 运行指定策略
python run_strategy.py first_board_pullback
python run_strategy.py macd_cross
```

策略文件放入 `strategies/` 目录后自动注册,文件名即策略名。

---

## 目录结构

```
tdxLinkMcp/
├── tdx_lib/                        # 核心框架(本地脚本直接 import)
│   ├── __init__.py                 # 统一导出
│   ├── client.py                   # HTTP 客户端
│   ├── utils.py                    # 工具函数
│   ├── launcher.py                 # 客户端启动器
│   ├── data.py                     # 行情数据
│   ├── financial.py                # 官方财务/交易数据
│   ├── screener.py                 # 通用筛选器
│   ├── selector.py                 # 官方公式选股 (B007)
│   ├── guard.py                    # 官方优先守卫
│   ├── trade.py                    # 交易接口
│   ├── portfolio.py                # 板块管理
│   ├── risk.py                     # 风险管理
│   ├── grid.py                     # 网格交易
│   ├── strategy.py                 # 策略基类
│   ├── backtest.py                 # 回测引擎
│   └── scheduler.py                # 定时调度
├── strategies/                     # 策略目录
│   ├── first_board_pullback.py     # 首板回调捉妖
│   └── macd_cross.py               # MACD金叉
├── src/tdx_link_mcp/               # MCP Server (PyPI 包)
│   ├── server.py                   # 7 个 MCP 工具注册
│   └── tdx_lib/                    # 框架拷贝(随包发布)
├── tests/                          # 单元测试
├── run_strategy.py                 # CLI 运行入口
├── SKILL.md                        # AI 改代码用的导航文档
├── PUBLISH_GUIDE.md                # 发版维护指南
├── install.ps1 / install.sh        # 一键安装脚本(Shell)
├── setup_mcp.py                    # 一键安装工具(Python, AI 调用入口)
└── README.md                       # 本文件
```

---

## 前置条件 & 依赖

- **Python 3.10+**(MCP 通过 uv 自动管理,无需手动装)
- **通达信客户端**:必须在本地运行(Windows),并开启 HTTP 服务(默认端口 17709)
- **交易接口**:需通达信已登录交易终端
- 框架本身**无第三方依赖**(纯标准库),MCP Server 依赖 `httpx` + `mcp`(uv 自动装)

---

## 常见问题

**Q: 提示"无法连接通达信"?**
A: 确保通达信客户端已启动且 HTTP 服务已开启(默认端口 17709)。

**Q: 可以远程使用吗?**
A: 当前仅支持本地使用(通达信客户端必须在本地运行)。

**Q: 支持哪些 AI 工具?**
A: 所有支持 MCP 协议的工具。`setup_mcp.py` 已内置 15 个平台自动配置:
Trae、Cursor、Claude Code、VS Code+Copilot、OpenCode、OpenClaw、Cline、
Kimi CLI、Pi Agent、Codex CLI、Gemini CLI、Antigravity、Windsurf、Qoder、Mistral Vibe。

**Q: 如何更新到最新版本?**
A: 配置中已启用 `--upgrade`,每次启动 AI 工具会自动检查。手动更新:`uv cache clean tdx-link-mcp`。

**Q: 安装后没有生效?**
A: 重启 AI 工具,确保配置文件已正确写入。

**Q: MCP 工具和 tdx_lib 框架是什么关系?**
A: MCP 是 tdx_lib 的子集封装。框架 14 个模块里只有 7 个被封装成 MCP 工具(给 AI 用);策略框架、回测、风控、网格、调度只给本地 Python 用,不向 MCP 暴露。

---

## 开发者说明

### 本地开发测试

```bash
# 克隆项目
git clone https://github.com/JueJuez/tdxLinkMcp.git
cd tdxLinkMcp

# 安装依赖
pip install -e .

# 运行测试
python -m pytest tests/

# 本地启动 MCP Server(用于调试)
python -m tdx_link_mcp.server
```

### 相关文档

| 文档 | 给谁看 | 内容 |
|------|--------|------|
| `README.md`(本文件) | 所有人 | 安装 + 框架介绍 |
| `SKILL.md` | AI 模型 | 改代码导航地图 + 项目铁律(AI 改框架代码前必读) |
| `PUBLISH_GUIDE.md` | 维护者 | 发版到 PyPI 的步骤 |

### 项目铁律(给 AI 的话)

**首要原则: 官方入参优先。** 用户与 AI 沟通形成的策略/条件,最终必须是通达信官方接口的入参,本框架只取数与呈现。详见 `.trae/rules/official-first.md`(项目铁律,由 `tdx_lib/guard.py` 运行时强制)。

涨跌停判定必须走 `TdxSelector`(官方公式 B007),禁止本地 ZAF 阈值。

如果需要修改、扩展、或添加新功能,请**先读 `SKILL.md`** — 它是 API 速查与操作指南。

### 发布到 PyPI

见 `PUBLISH_GUIDE.md`。

---

## 版本历史

- **v0.1.5** (2026-06-29):权限自动提权 + 智能缓存目录
  - **UAC 提权机制**：MCP Server 启动时自动检测权限，权限不足时请求 UAC 提权
  - **智能缓存目录检测**：自动检测可写的缓存目录，避免权限拦截
  - 优先使用用户主目录（`%USERPROFILE%\.uv-cache`），降级到临时目录
  - 完全自动化安装流程，用户无需手动配置
- **v0.1.2** (2026-06-28):一键安装工具 + 多平台支持
  - 新增 `setup_mcp.py`:Python 一键安装工具,AI 只需执行一条命令即可完成全部安装
  - 支持 15 个 AI 编码平台自动配置:Trae/Cursor/Claude/VS Code/OpenCode/OpenClaw/
    Cline/Kimi/Pi/Codex/Gemini/Antigravity/Windsurf/Qoder/Mistral Vibe
  - 智能合并不覆盖已有 MCP 配置(解决旧脚本覆盖用户配置的问题)
  - 支持 3 种配置格式:标准 JSON `mcpServers` / OpenCode `mcp` 键 / Mistral Vibe TOML
  - 修复 `install.ps1` 中 Trae 配置路径错误 + 改为合并写入
  - 解决 AI 逐步安装需 5-10 分钟的问题(脚本 30-60 秒完成)
- **v0.1.1** (2026-06-27):修复打包 bug
  - 修复:打包后 `from tdx_lib import` 找不到模块(v0.1.0 用户安装后无法启动)
  - 改为单一真源:tdx_lib 作为独立顶级包打包,删除 src 下拷贝
  - 文档重组:README 合并 MCP_README,删除 3 个冗余文档
- **v0.1.0** (2026-06-27):首次发布
  - 7 个场景化 MCP 工具
  - 14 个 tdx_lib 框架模块
  - 支持 Trae/Qoder/Cursor/Claude Desktop
  - 全自动安装脚本

---

## 许可证

MIT License
