Metadata-Version: 2.4
Name: ozon_mcp
Version: 0.1.3
Summary: OZON MCP Server - Browser automation for OZON seller platform with auto profile detection
Author-email: Oychao <oychao@example.com>
License: MIT
Project-URL: Homepage, https://github.com/oychao1988/ozon-mcp
Project-URL: Repository, https://github.com/oychao1988/ozon-mcp.git
Project-URL: Issues, https://github.com/oychao1988/ozon-mcp/issues
Keywords: ozon,mcp,playwright,automation,ecommerce
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: playwright>=1.40.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tenacity>=8.2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pytest>=7.4.0
Requires-Dist: pytest-asyncio>=0.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# OZON MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/ozon-mcp.svg)](https://badge.fury.io/py/ozon-mcp)

[中文](#中文文档) | [English](#english-docs)

---

## 中文文档

OZON MCP Server 是一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的工具，通过 Playwright 实现 OZON 电商后台自动化操作，支持 QQ 邮箱验证码自动读取。

### 功能

- **自动登录** (`login-with-email-code`) - 使用 QQ 邮箱验证码自动登录 OZON 卖家后台
- **价格监控** (`get-marketing-actions`) - 获取营销活动商品价格数据，识别低于最低价格的商品
- **CLI 直接调用** - 无需 MCP 协议，可从命令行直接执行单个操作

### 安装

#### 方式一：从 PyPI 安装（推荐）

```bash
# 安装 uv (如果没有)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 全局安装 ozon-mcp
uv tool install ozon-mcp

# 安装浏览器
uv tool run ozon-mcp playwright install chromium
```

#### 方式二：克隆源码开发

```bash
# 克隆项目
git clone https://github.com/oychao1988/ozon-mcp.git
cd ozon-mcp

# 安装 uv (如果没有)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖
uv sync
uv run playwright install chromium
```

### 配置环境变量

复制 `.env.example` 为 `.env` 并填写：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```bash
# OZON 账号配置（只需要用户名）
ozon_username="your_qq@qq.com"

# QQ 邮箱授权码（16位）- 获取方式见下方
qq_imap_auth_code="your_16_digit_auth_code"

# Chrome Profile 配置（可选）
chrome_profile_source="copy_to_local"
```

#### 获取 QQ 邮箱授权码

1. 登录 [mail.qq.com](https://mail.qq.com)
2. 设置 → 账户 → POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
3. 开启 IMAP/SMTP 服务，获取 16 位授权码

### 在 Claude Code 中配置

#### 方式一：使用已安装的 ozon-mcp 命令（推荐）

```bash
claude mcp add ozon --transport stdio -- ozon-mcp
```

#### 方式二：使用 uvx 远程运行

```bash
claude mcp add ozon --transport stdio -- uvx ozon-mcp
```

#### 使用 uvx 从 GitHub 直接运行（无需安装）

```bash
claude mcp add ozon --transport stdio -- uvx github:oychao1988/ozon-mcp
```

### Claude Code 使用示例

配置完成后，可以在 Claude Code 中直接调用 MCP 工具：

```
# 登录 OZON 账号
使用 ozon 工具执行 login-with-email-code 命令

# 获取营销活动价格数据
使用 ozon 工具执行 get-marketing-actions 命令，参数为 page=1, page_size=20
```

在 Claude Code 对话中可以这样交互：

```
# 登录示例
User: 请帮我登录 OZON 卖家后台
Claude: [调用 login-with-email-code]

# 获取数据示例
User: 获取第1页的营销活动商品数据
Claude: [调用 get-marketing-actions，参数 {page: 1, page_size: 20}]

# 获取所有页面数据
User: 获取所有营销活动商品的价格数据
Claude: [调用 get-marketing-actions，参数 {all_pages: true}]
```

### 在 Cursor 中配置

在 `.mcp.json` 或 Cursor MCP 设置中添加：

```json
{
  "mcpServers": {
    "ozon": {
      "command": "ozon-mcp"
    }
  }
}
```

或使用 uvx：

```json
{
  "mcpServers": {
    "ozon": {
      "command": "uvx",
      "args": ["ozon-mcp"]
    }
  }
}
```

### 使用方法

#### 工具列表

##### 1. login-with-email-code

自动登录 OZON 卖家后台（使用 QQ 邮箱接收验证码）。

```json
{
  "command": "login-with-email-code"
}
```

##### 2. get-marketing-actions

获取营销活动商品价格数据。

```json
{
  "command": "get-marketing-actions",
  "arguments": {
    "page": 1,
    "page_size": 20,
    "all_pages": false
  }
}
```

**参数说明：**

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| page | number | 1 | 页码（从 1 开始） |
| page_size | number | 20 | 每页产品数量 |
| all_pages | boolean | false | 是否获取所有页面数据 |

### CLI 命令行直接调用

除了通过 MCP 协议在 Claude Code / Cursor 中使用，也可以直接从命令行执行单个操作：

```bash
# 检查环境配置
python cli.py check

# 登录 OZON 卖家后台
python cli.py login

# 获取营销活动数据（第1页，50条，表格输出）
python cli.py marketing

# 获取第2页，每页100条
python cli.py marketing --page 2 --page-size 100

# 获取所有页面数据并保存到文件
python cli.py marketing --all --output products.json

# 保存为 CSV 格式
python cli.py marketing --page-size 100 --output data/products.csv

# 无头模式运行（不显示浏览器界面）
python cli.py --headless marketing

# JSON 格式输出（适合管道处理）
python cli.py marketing --json
python cli.py login --json
```

**CLI 参数说明：**

| 命令 | 参数 | 说明 |
|------|------|------|
| `check` | - | 检查环境配置是否完整 |
| `login` | `--headless` | 无头模式运行 |
| `marketing` | `--page N` | 页码（从1开始） |
| | `--page-size N` | 每页产品数量（默认50） |
| | `--all` | 获取所有页面 |
| | `--max-scrolls N` | 最大滚动次数 |
| | `--scroll-delay N` | 滚动延迟（秒，默认3秒） |
| | `--output PATH` | 输出文件路径（csv 或 json 格式） |
| 通用 | `--headless` | 无头模式 |
| | `--json` | JSON 格式输出 |

> **说明**: CLI 脚本直接调用 `server.py` 中的 handler 函数，复用了全部浏览器自动化逻辑，只是跳过了 MCP 协议层。

### 运行测试

```bash
# 运行所有测试
uv run pytest tests/ -v

# 运行特定测试文件
uv run pytest tests/test_server.py -v

# 运行带覆盖率报告的测试
uv run pytest tests/ -v --cov=ozon_mcp

# 运行特定测试类
uv run pytest tests/test_handlers.py::TestRetryDecorator -v

# 运行特定测试用例
uv run pytest tests/test_server.py::TestLoginOTPFlow::test_otp_filled_then_submit_button_clicked -v
```

### 项目结构

```
ozon-mcp/
├── src/ozon_mcp/          # 核心代码
│   ├── __init__.py        # 版本声明和导出
│   ├── server.py          # MCP Server 入口 + 业务逻辑
│   ├── browser.py         # Playwright 浏览器管理
│   ├── mail.py            # QQ 邮箱 IMAP 操作
│   ├── session.py         # 多账号会话管理
│   ├── _selectors.py      # YAML 选择器加载器
│   ├── selectors.yaml     # 选择器配置文件
│   ├── handlers/          # 工具处理器
│   │   ├── __init__.py
│   │   └── base.py        # BaseHandler 基类
│   └── ozon_selectors.py  # OZON 页面选择器常量
├── cli.py                 # CLI 命令行脚本（直接调用 handler）
├── tests/                 # 测试代码
│   ├── test_browser.py    # 浏览器管理器测试
│   ├── test_handlers.py   # 处理器测试
│   ├── test_mail.py       # 邮箱模块测试
│   ├── test_selectors.py  # 选择器配置测试
│   ├── test_server.py     # MCP Server 测试
│   └── test_session.py    # 会话管理器测试
├── .env.example           # 环境变量示例
├── pyproject.toml         # 项目配置
└── README.md             # 使用说明
```

### 发布到 PyPI

```bash
# 构建包
uv build

# 发布到 PyPI（需要账号）
uv publish

# 或发布到 TestPyPI 测试
uv publish --repository testpypi
```

### 注意事项

1. **隐私保护** - 请勿提交 `.env` 文件或 `chrome-profile/` 目录到 Git
2. **验证码** - 确保 QQ 邮箱能正常接收 OZON 的验证码邮件
3. **Chrome Profile** - 首次登录后会保存登录状态，避免重复验证

### Claude Code 管理命令

```bash
# 查看已配置的 MCP 服务器
claude mcp list

# 移除 MCP 服务器
claude mcp remove ozon

# 重新添加（更新版本后）
claude mcp add ozon --transport stdio -- ozon-mcp

# 检查 MCP 服务器状态
claude mcp start ozon
```

### 常见问题

**Q: 登录失败，显示验证码错误**
A: 确保 QQ 邮箱能收到 OZON 的邮件，检查垃圾邮件文件夹

**Q: 页面加载超时**
A: 增加网络超时时间，或检查 Chrome Profile 是否正常

**Q: 如何查看详细日志**
A: 运行 `RUST_LOG=debug claude` 启动 Claude Code 查看 MCP 通信日志

### 更新日志

#### v0.1.2 (2026-04-20)

**Bug 修复：**
- 修复 `__version__` 与 `pyproject.toml` 版本不一致的问题
- 修复 OTP 验证码填写后未点击提交按钮的问题
- 删除重复的 `scroll_to_load` 函数定义

**健壮性改进：**
- 添加 tenacity 依赖用于重试逻辑
- IMAP 连接添加 30 秒 socket 超时
- 邮件轮询添加指数退避策略
- 分页失败时返回已获取的部分数据
- `scroll_to_load` 支持通过 `max_scrolls` 和 `scroll_delay` 参数配置

**可扩展性改进：**
- 新增 `SessionManager` 支持多账号管理
- 新增 `BaseHandler` 基类，集成重试和错误恢复逻辑
- Selectors 配置迁移到 YAML 文件，支持热重载
- Server.py 全面采用 `SelectorConfig` 管理选择器

**包修复：**
- 修复 `pyproject.toml` 缺少 `handlers` 子包和 `selectors.yaml` 数据文件的打包配置

#### v0.1.0 (2026-04-20)

初始版本发布，包含：
- `login-with-email-code` - QQ 邮箱验证码自动登录
- `get-marketing-actions` - 营销活动价格数据获取
- Playwright 浏览器自动化
- Chrome Profile 会话管理

---

## English Docs

OZON MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) based tool for automating OZON seller platform operations using Playwright, with QQ Mail OTP support.

### Features

- **Auto Login** - Login to OZON using QQ Mail verification codes
- **Price Monitoring** - Check marketing action prices and identify underpriced items

### Installation

```bash
# Install via uv
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install ozon-mcp

# Install browser
uv tool run ozon-mcp playwright install chromium
```

### Configuration

Copy `.env.example` to `.env` and configure:

```bash
ozon_username="your_qq@qq.com"
qq_imap_auth_code="your_16_digit_auth_code"
```

Get QQ Mail auth code from: mail.qq.com → Settings → Account → IMAP/SMTP service

### Claude Code Configuration

```bash
claude mcp add ozon --transport stdio -- ozon-mcp
```

### Cursor Configuration

Add to `.mcp.json` or Cursor MCP settings:

```json
{
  "mcpServers": {
    "ozon": {
      "command": "ozon-mcp"
    }
  }
}
```

### License

MIT License - see [LICENSE](LICENSE) file
