npm package: @iflow-mcp/guangxiangdebizi-quant2ptrader-mcp
Description: MCP Server for converting JoinQuant strategies to Ptrade format
Author: Xingyu Chen
Latest version: 1.2.0

# 🔄 Quant2Ptrader-MCP

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

[![npm version](https://img.shields.io/npm/v/quant2ptrader-mcp.svg)](https://www.npmjs.com/package/quant2ptrader-mcp)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](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！