🔄 Quant2Ptrader-MCP

一键转换聚宽策略到Ptrade平台的MCP服务器

📖 简介

Quant2Ptrader-MCP 是一个基于 Model Context Protocol (MCP) 的服务器，专门用于将聚宽（JoinQuant）量化策略代码自动转换为Ptrade平台格式。

✨ 核心功能

• 🚀 一键转换：输入完整聚宽策略代码，自动输出Ptrade格式
• 📁 文件支持：支持直接传入文件路径（.py、.txt等），方便长代码文件转换
• 💾 自动保存：转换结果自动保存为.py文件，返回文件路径，可直接使用 ⭐ 新功能
• 🔍 智能识别：自动识别所有需要修改的API调用
• 📊 详细报告：生成完整的转换报告，包含所有修改详情
• ⚠️ 风险提示：标注可能需要手动调整的部分
• 🎯 高兼容性：基于两个平台的API相似性，实现无缝转换

🚀 快速开始

安装依赖

npm install

构建项目

npm run build

本地运行

⭐ stdio 模式（推荐）

npm run start:stdio

🌐 HTTP 模式

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

{
  "mcpServers": {
    "quant2ptrader": {
      "command": "npx",
      "args": ["-y", "quant2ptrader-mcp"]
    }
  }
}

HTTP 模式

{
  "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: 直接输入代码

输入（聚宽策略）：

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策略）：

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

脚本命令

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 数组：

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

# 登录npm
npm login

# 发布
npm publish

🐛 已知问题

1. 部分聚宽特有的研究环境API可能无法完全转换
2. 自定义函数和第三方库需要手动检查兼容性
3. 建议转换后在Ptrade上进行小规模回测验证

🛣️ 未来计划

• [ ] 支持批量文件转换
• [ ] 增强财务数据查询API的转换
• [ ] 添加策略语法检查
• [ ] 支持双向转换（Ptrade → 聚宽）
• [ ] 提供Web界面

📄 许可证

Apache License 2.0 - 查看 LICENSE 文件了解详情

👨‍💻 作者

Xingyu Chen

• LinkedIn: https://www.linkedin.com/in/xingyu-chen-b5b3b0313/
• Email: guangxiangdebizi@gmail.com
• GitHub: https://github.com/guangxiangdebizi/
• NPM: https://www.npmjs.com/~xingyuchen

🙏 致谢

• 感谢 Model Context Protocol 提供的优秀协议
• 感谢聚宽和Ptrade平台提供的量化交易基础设施

📞 支持

如有问题或建议，欢迎：

• 提交 GitHub Issue
• 发送邮件至 guangxiangdebizi@gmail.com

---

⭐ 如果这个项目对你有帮助，欢迎 Star！