# 山东电力交易中心 MCP 服务

<div align="center">

**提供电价数据查询、市场信息获取和自动化交易功能**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)

[功能特性](#功能特性) • [快速开始](#快速开始) • [完整文档](DOCS.md) • [使用示例](#使用示例)

</div>

---

## 功能特性

### 🔍 数据查询
- 日前/实时电价查询（单日 & 批量）
- 负荷预测、联络线数据
- 市场边界披露数据
- 支持 CSV/JSON/Excel 导出

### 🤖 自动化交易
- **智能交易策略**：根据成本价和电量自动执行卖出
- **分阶段执行**：监控 → 跟随 → 降价 → 撤单
- **超高价抢单**：自动捕捉市场高价机会
- **实时监控**：订单统计、成交情况、盈亏数据
- **验证码处理**：自动识别滑块验证码

### 📊 核心能力

| 能力 | 工具数量 | 说明 |
|-----|---------|------|
| 认证管理 | 4 个 | 登录、登出、状态检查 |
| 电价数据 | 4 个 | 日前/实时电价查询 |
| 市场数据 | 4 个 | 负荷、联络线、披露数据 |
| 验证码 | 2 个 | 滑块验证码自动处理 |
| 自动交易 | 3 个 | 策略管理和监控 |

**共计 10 个工具**，全面覆盖电力交易需求。

---

## 快速开始

### 前置要求

本项目依赖 Python 进行验证码识别，**首次使用前需要安装 Python 依赖**：

```bash
# 安装 Python 库（必需，仅需一次）
pip install no-puzzle-captcha

# 或使用国内镜像加速
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple no-puzzle-captcha
```

**说明**：
- 如果未安装此依赖，服务启动时会显示清晰的错误提示和安装命令
- 安装一次后即可永久使用，无需重复安装

### 使用 npx 运行（推荐）

无需安装，直接使用：

```bash
npx electricity-trading-mcp
```

或全局安装：

```bash
npm install -g electricity-trading-mcp
```

### 配置 Claude Desktop

在配置文件中添加：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "shandong-power": {
      "command": "npx",
      "args": ["-y", "electricity-trading-mcp@latest"]
    }
  }
}
```

### 配置其他 MCP 客户端

**VSCode / Cline**:
```json
{
  "mcpServers": {
    "shandong-power": {
      "command": "npx",
      "args": ["-y", "electricity-trading-mcp@latest"]
    }
  }
}
```

**Agent-Box / XMO**:
```yaml
shandong-power:
  enabled: true
  type: stdio
  cmd: npx
  args:
    - -y
    - electricity-trading-mcp@latest
```

---

## 使用示例

### 📈 查询电价数据

```
用户: 帮我查询昨天的日前电价

Claude: [调用 get-day-ahead-price 工具]
✓ 数据已导出到: 山东日前电价_2025-01-07.csv
```

### 🤖 启动自动交易

```
用户: 我想今天下午自动卖电，成本价600元/MWh，
      9点1MWh，10点2MWh，11点1.5MWh，用普通模式

Claude: [调用 start-trading-strategy 工具]
✓ 策略已启动
✓ 交易时段: D20260120H09, D20260120H10, D20260120H11
✓ 每5秒轮询市场数据
```

### 📊 监控交易状态

```
用户: 策略运行得怎么样？

Claude: [调用 get-strategy-status 工具]

运行状态: ✓ 运行中
订单统计: 提交3个，成交1个，部分成交1个
总盈亏: +120.50 元

各时段详情:
- H09: 已成交 1.0 MWh @ 720元/MWh
- H10: 部分成交 0.5/2.0 MWh，挂单1个
- H11: 等待中，买一价 590元/MWh < 成本价
```

---

## 自动交易策略

### 三种交易模式

| 模式 | 策略 | 适用场景 |
|-----|------|---------|
| `aggressive` | 比买一价低1-5元 | 急于成交 |
| `normal` | 以买一价挂单 | 平衡收益 |
| `conservative` | 以成本价挂单 | 优先利润 |

### 分阶段执行

```
13:30-14:00  初期  │ 监控 + 超高价抢单（≥1000元/MWh）
14:00-14:15  中期  │ 跟随出价（买一价≥成本价时挂单）
14:15-14:25  后期  │ 降价促成交
14:25-14:30  收尾  │ 保留订单等待最后成交
```

### 风险控制

- ✅ **成本价保护**（卖出价永远 >= 成本价，除非设置可容忍亏损）
- ✅ 最低价格保护（成本价 - 可容忍亏损）
- ✅ 实时订单监控（5秒轮询）
- ✅ 自动撤单机制
- ✅ 验证码自动处理

**核心保障**: 默认情况下系统**绝不会亏本卖出**，确保所有交易价格 >= 成本价

### 测试建议

首次使用时设置**高成本价**（如 1000 元/MWh）进行测试：
- 市场价格通常 400-600 元/MWh
- 策略正常运行但不会成交
- 验证功能无风险

---

## 主要工具列表

### 认证工具
- `login` - 浏览器登录
- `logout` - 清除凭证
- `check-login-status` - 检查状态
- `close-browser` - 关闭浏览器

### 电价查询
- `get-day-ahead-price` - 日前电价（单日）
- `get-day-ahead-price-range` - 日前电价（批量）
- `get-realtime-price` - 实时电价（单日）
- `get-realtime-price-range` - 实时电价（批量）

### 市场数据
- `get-load-forecast` - 负荷预测
- `get-interconnection-forecast` - 联络线
- `get-predict-disclosure` - 预测披露
- `get-actual-disclosure` - 实际披露

### 验证码处理
- `test-captcha` - 测试验证码识别
- `solve-captcha` - 自动解决验证码

### 自动交易
- `start-trading-strategy` - 启动策略
- `get-strategy-status` - 查看状态
- `stop-trading-strategy` - 停止策略

---

## 系统要求

- Node.js >= 18.0.0
- Google Chrome 浏览器
- 山东电力交易中心账号

---

## 注意事项

⚠️ **自动交易风险提示**：
- 涉及真实资金交易，请谨慎设置参数
- 交易时间：工作日 13:30-14:30
- 首次使用建议高成本价测试
- 需要稳定网络连接
- 同一时间只能运行一个策略

---

## 完整文档

查看 [DOCS.md](DOCS.md) 获取：
- 详细的工具参数说明
- 完整的使用示例
- 策略配置指南
- 开发和调试信息

---

## 故障排除

### 错误: 缺少必需的 Python 依赖

如果启动时看到以下错误：

```
⚠️  缺少必需的 Python 依赖
验证码识别功能需要 Python 库 no-puzzle-captcha
```

**解决方法**：

```bash
# 安装 Python 依赖
pip install no-puzzle-captcha

# 或使用国内镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple no-puzzle-captcha
```

### 验证 Python 环境

确保 Python 3 和依赖库正确安装：

```bash
# 检查 Python 版本（需要 3.7+）
python3 --version

# 验证依赖库
python3 -c "import no_puzzle_captcha; print('✓ 依赖已安装')"
```

### 在 Agent-Box/XMO 中无法使用

如果在 Agent-Box 或 XMO 中遇到连接问题：

1. **确保使用 npx 和绝对路径**：
   ```yaml
   cmd: npx  # 不是 node
   args: ["-y", "electricity-trading-mcp@latest"]
   ```

2. **重启客户端**：配置修改后需要完全重启应用

3. **检查日志**：查看客户端日志确认错误信息

---

## License

MIT

常用命令总结：


# 查看所有 npx 启动的 MCP 服务
ps aux | grep -E "(npx|electricity-trading-mcp)" | grep -v grep

# 只看 electricity-trading-mcp 相关进程
ps aux | grep electricity-trading-mcp | grep -v grep

# 杀掉所有旧版本（保留 1.0.28）
pkill -f "electricity-trading-mcp@1.0.2[3456]"

# 杀掉所有 electricity-trading-mcp（包括最新版）
pkill -f electricity-trading-mcp

# 查看端口占用
lsof -i tcp:3000,3001,3002,3003,3004,3005,3006,3007