🔄 Quant2Ptrader-MCP

一键将宽度聚合策略转换为Ptrade平台上的MCP服务器

📖 介绍

Quant2PTrader-MCP 是基于 模型上下文协议 (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 模式（推荐）

添加：

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": 200
    }
  }
}

🛠️ 使用说明

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

输出位置：

• 如果有文件路径：保存在原始文件所在目录
• 如果没有文件路径：保存在当前工作目录
• 指定输出目录：保存在指定目录

📋 转换示例

示例 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. 部分研究环境特有的 JuKuan API 可能无法完全转换
2. 自定义函数和第三方库需要手动检查兼容性
3. 建议在转换后对 Ptrade 进行小规模回测验证

🛣️ 未来计划

• [] 支持批量文件转换
• [] 提升财务数据查询 API 的转换能力
• [] 添加策略语法检查
• [] 支持双向转换（Ptrade → 宽度聚合）
• [] 提供 Web 接口

📄 许可证

Apache 许可证 2.0 - 查看 LICENSE 了解更多详情

👨‍💻 作者

陈星宇

• 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 提供的优秀协议
• 感谢 Jukuan 和 Ptrade 平台提供的量化交易平台基础设施

📞 支持

如果您有任何问题或建议，请随时：

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

---

⭐ 如果这个项目对您有帮助，欢迎点赞！