# 🔄 Quant2Ptrader-MCP
**一键转换聚宽策略到Ptrade平台的MCP服务器**
[](https://www.npmjs.com/package/quant2ptrader-mcp)
[](LICENSE)
## 📖 简介
Quant2Ptrader-MCP 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的服务器，专门用于将聚宽（JoinQuant）量化策略代码自动转换为Ptrade平台格式。
### ✨ 核心功能
- 🚀 **一键转换**：输入完整聚宽策略代码，自动输出Ptrade格式
- 📁 **文件支持**：支持直接传入文件路径（.py、.txt等），方便长代码文件转换
- 💾 **自动保存**：转换结果自动保存为.py文件，返回文件路径，可直接使用 ⭐ **新功能**
- 🔍 **智能识别**：自动识别所有需要修改的API调用
- 📊 **详细报告**：生成完整的转换报告，包含所有修改详情
- ⚠️ **风险提示**：标注可能需要手动调整的部分
- 🎯 **高兼容性**：基于两个平台的API相似性，实现无缝转换
## 🚀 快速开始
### 安装依赖
```bash
npm install
```
### 构建项目
```bash
npm run build
```
### 本地运行
#### ⭐ stdio 模式（推荐）
```bash
npm run start:stdio
```
#### 🌐 HTTP 模式
```bash
npm run start:http
# 服务将运行在 http://localhost:3000/mcp
```
## 📱 客户端配置
### Claude Desktop 配置
#### stdio 模式（推荐）
在 Claude Desktop 的配置文件中添加：
**macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"quant2ptrader": {
"command": "npx",
"args": ["-y", "quant2ptrader-mcp"]
}
}
}
```
#### HTTP 模式
```json
{
"mcpServers": {
"quant2ptrader": {
"type": "streamableHttp",
"url": "http://localhost:3000/mcp",
"timeout": 600
}
}
}
```
## 🛠️ 使用方法
### 1. 启动服务
使用上述任一方式启动MCP服务器
### 2. 在AI助手中调用
**方式1: 直接输入代码**
在Claude或其他支持MCP的AI助手中：
```
请帮我把这个聚宽策略转换为Ptrade格式：
from jqdata import *
def initialize(context):
set_benchmark('000300.XSHG')
def handle_data(context, data):
order('000001.XSHE', 100)
```
**方式2: 传入文件路径（推荐长代码使用）**
```
请将这个聚宽策略文件转换为Ptrade格式：
文件路径: C:\path\to\your\strategy.py
```
或者：
```
转换这个文件: /home/user/my_strategy.txt
```
**支持的文件格式**: `.py`, `.txt`, `.text`, `.code`, `.strategy`
**方式3: 指定输出目录（可选）**
```
转换这个文件并保存到指定目录：
文件: C:\strategies\my_strategy.py
输出目录: D:\ptrade_strategies\
```
### 3. 获取转换结果
AI助手会返回：
- 📄 源文件信息
- ✅ 转换状态
- 💾 **输出文件路径**（自动保存的.py文件）⭐ **重点**
- 📝 详细的代码修改列表
- ⚠️ 需要注意的兼容性问题
- 📋 代码预览（折叠显示）
**文件命名规则**：
- 输入：`my_strategy.py` → 输出：`my_strategy_ptrade.py`
- 输入：`strategy.txt` → 输出：`strategy_ptrade.py`
- 直接代码输入 → 输出：`strategy_ptrade.py`
**输出位置**：
- 有文件路径：保存在原文件同目录
- 无文件路径：保存在当前工作目录
- 指定output_dir：保存在指定目录
## 📋 转换示例
### 示例1: 直接输入代码
**输入（聚宽策略）：**
```python
from jqdata import *
def initialize(context):
set_benchmark('000300.XSHG')
set_option('use_real_price', True)
def handle_data(context, data):
stock = '000001.XSHE'
price = data[stock].close
order(stock, 100)
```
**输出（Ptrade策略）：**
```python
from ptrade.api import *
def initialize(context):
set_benchmark('000300.XSHG')
set_option('use_real_price', True)
def handle_data(context, data):
stock = '000001.XSHE'
price = data[stock].close
order(stock, 100)
```
### 示例2: 文件路径输入
**命令：**
```
转换这个策略文件: /path/to/strategy.py
```
**报告包含：**
- 📄 源文件：`strategy.py`
- 📝 修改了第1行的导入语句
- ⚠️ 所有检测到的兼容性注意事项
- 🎯 完整转换后的代码
### 示例3: 真实策略案例（58行）
查看 `test_strategy.py` 了解完整的双均线策略示例，包含：
- 完整的初始化配置
- 历史数据获取
- 交易逻辑
- 日志输出
- 账户管理
**转换结果**: ✅ 完美转换，仅修改1行（导入语句）
## 🔧 开发指南
### 项目结构
```
quant2ptrader-mcp/
├── src/
│ ├── index.ts # stdio模式入口
│ ├── httpServer.ts # HTTP模式入口
│ └── tools/
│ └── convertStrategy.ts # 核心转换逻辑
├── build/ # 编译输出目录
├── package.json
├── tsconfig.json
└── README.md
```
### 脚本命令
```bash
npm run build # 构建项目
npm run watch # 监听模式编译
npm run start:stdio # 启动stdio模式
npm run start:http # 启动HTTP模式
npm run dev # 开发模式（HTTP）
```
### 添加新的转换规则
编辑 `src/tools/convertStrategy.ts` 中的 `apiMappings` 数组：
```typescript
const apiMappings = [
{
pattern: /your_pattern/g,
replacement: 'your_replacement',
reason: '转换原因说明'
},
// ... 更多规则
];
```
## 🤝 API差异说明
### ✅ 完全兼容的API
以下聚宽API在Ptrade中完全兼容，无需修改：
- `initialize(context)` - 初始化函数
- `handle_data(context, data)` - 数据处理函数
- `order()`, `order_target()`, `order_value()`, `order_target_value()` - 下单函数
- `set_benchmark()` - 设置基准
- `set_slippage()` - 设置滑点
- `get_price()` - 获取价格数据
- `get_fundamentals()` - 获取财务数据
- `context.portfolio.total_value` - 总资产
- `context.portfolio.available_cash` - 可用资金
- `context.portfolio.market_value` - 持仓市值
### 🔄 自动转换的API（关键差异）
转换工具会自动处理以下API差异：
#### 导入模块
- `from jqdata import *` → `from ptrade.api import *`
- `import jqdata` → `import ptrade`
#### 日志函数 ⭐
- `log.info()` → `log()`
- `log.debug()` → `log()`
- `log.warn()` → `log()`
- `log.error()` → `log()`
#### 持仓访问 ⭐
- `context.portfolio.positions` → `get_positions()`
- `context.portfolio.positions[stock]` → `get_position(stock)`
#### 历史数据获取
- `attribute_history()` → `get_history()`
- `history()` → `get_history()`
#### 行情数据
- `get_current_data()` → `get_snapshot()`
#### 市场数据
- `get_all_securities()` → `get_market_list()`
#### 手续费设置
- `set_order_cost()` → `set_commission()`
#### 交易函数
- `order_target_percent()` → `order_target_value()` ⚠️ 需手动计算金额
#### 定时任务
- `run_weekly()` → `run_daily()` ⚠️ 需添加日期判断
- `run_monthly()` → `run_daily()` ⚠️ 需添加日期判断
### ⚠️ 需要注意的转换
1. **按比例下单**：`order_target_percent()`已转换为`order_target_value()`，需要手动计算目标金额
2. **定时任务**：`run_weekly/monthly`转换为`run_daily`后，需在函数内添加日期判断逻辑
3. **财务数据查询**：`get_fundamentals()`在Ptrade中支持，但查询语法可能需要微调
4. **日期时间参数**：建议使用字符串格式，符合Ptrade要求
## 📦 发布到npm
```bash
# 登录npm
npm login
# 发布
npm publish
```
## 🐛 已知问题
1. 部分聚宽特有的研究环境API可能无法完全转换
2. 自定义函数和第三方库需要手动检查兼容性
3. 建议转换后在Ptrade上进行小规模回测验证
## 🛣️ 未来计划
- [ ] 支持批量文件转换
- [ ] 增强财务数据查询API的转换
- [ ] 添加策略语法检查
- [ ] 支持双向转换（Ptrade → 聚宽）
- [ ] 提供Web界面
## 📄 许可证
Apache License 2.0 - 查看 [LICENSE](LICENSE) 文件了解详情
## 👨💻 作者
**Xingyu Chen**
- LinkedIn: [https://www.linkedin.com/in/xingyu-chen-b5b3b0313/](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/)
- Email: guangxiangdebizi@gmail.com
- GitHub: [https://github.com/guangxiangdebizi/](https://github.com/guangxiangdebizi/)
- NPM: [https://www.npmjs.com/~xingyuchen](https://www.npmjs.com/~xingyuchen)
## 🙏 致谢
- 感谢 [Model Context Protocol](https://modelcontextprotocol.io/) 提供的优秀协议
- 感谢聚宽和Ptrade平台提供的量化交易基础设施
## 📞 支持
如有问题或建议，欢迎：
- 提交 [GitHub Issue](https://github.com/guangxiangdebizi/quant2ptrader-mcp/issues)
- 发送邮件至 guangxiangdebizi@gmail.com
---
⭐ 如果这个项目对你有帮助，欢迎 Star！
