# Xiaohongshu MCP Python

小红书 MCP 服务器的 Python 实现，从 Go 版本完整重构而来。

## 功能特性

### 核心功能

- ✅ **登录管理**：二维码登录、登录状态检查、Cookie 管理
- ✅ **内容浏览**：Feed 列表、搜索、详情查看
- ✅ **互动功能**：评论、回复、点赞、收藏
- ✅ **用户信息**：用户主页查看
- ✅ **内容发布**：图文发布、视频发布（骨架已实现）
- ✅ **MCP 协议**：完整的 MCP 工具集成
- ✅ **HTTP API**：REST API 接口

### 技术栈

- **Web 框架**：FastAPI
- **浏览器自动化**：Playwright
- **MCP 协议**：MCP Python SDK
- **数据验证**：Pydantic
- **日志**：Loguru
- **部署**：Docker + Docker Compose

## 项目结构

```
xiaohongshu-python/
├── xiaohongshu/           # 业务逻辑包
│   ├── __init__.py
│   ├── types.py           # 数据模型
│   ├── navigate.py        # 页面导航
│   ├── login.py           # 登录功能
│   ├── feeds.py           # Feed 列表
│   ├── search.py          # 搜索功能
│   ├── feed_detail.py     # 详情获取
│   ├── comment_feed.py    # 评论功能
│   ├── like_favorite.py   # 点赞收藏
│   ├── user_profile.py    # 用户主页
│   ├── publish.py         # 图文发布
│   └── publish_video.py   # 视频发布
├── browser/               # 浏览器管理
│   ├── __init__.py
│   └── browser.py
├── cookies/               # Cookie 管理
│   ├── __init__.py
│   └── cookies.py
├── configs/               # 配置管理
│   ├── __init__.py
│   └── settings.py
├── errors/                # 错误处理
│   ├── __init__.py
│   └── errors.py
├── service.py             # 业务服务层
├── mcp_server.py          # MCP 服务器
├── routes.py              # HTTP 路由
├── app_server.py          # 应用服务器
├── main.py                # 主程序入口
├── requirements.txt       # Python 依赖
├── Dockerfile             # Docker 配置
├── docker-compose.yml     # Docker Compose 配置
├── .env.example           # 环境变量示例
└── README.md              # 项目文档
```

## 快速开始

### 方式 1：本地运行

#### 1. 安装依赖

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器
playwright install chromium
```

#### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件，根据需要修改配置
```

#### 3. 启动服务

```bash
python main.py
```

服务将在 `http://localhost:18060` 启动。

### 方式 2：Docker 运行

#### 1. 构建镜像

```bash
docker-compose build
```

#### 2. 启动服务

```bash
docker-compose up -d
```

#### 3. 查看日志

```bash
docker-compose logs -f
```

#### 4. 停止服务

```bash
docker-compose down
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `HOST` | 服务器监听地址 | `0.0.0.0` |
| `PORT` | 服务器端口 | `18060` |
| `HEADLESS` | 浏览器无头模式 | `true` |
| `BROWSER_BIN_PATH` | 浏览器二进制路径 | 自动检测 |
| `COOKIES_PATH` | Cookie 文件路径 | `./data/cookies.json` |
| `LOG_LEVEL` | 日志级别 | `INFO` |

### Cookie 管理

Cookie 文件路径优先级：

1. `/tmp/cookies.json`（向后兼容）
2. 环境变量 `COOKIES_PATH`
3. 当前目录 `cookies.json`

## API 文档

### HTTP API

启动服务后，访问 `http://localhost:18060/docs` 查看完整的 API 文档（Swagger UI）。

#### 主要端点

**登录相关**

- `GET /api/v1/login/status` - 检查登录状态
- `GET /api/v1/login/qrcode` - 获取登录二维码
- `DELETE /api/v1/login/cookies` - 删除 cookies

**Feed 相关**

- `GET /api/v1/feeds/list` - 获取 Feed 列表
- `POST /api/v1/feeds/search` - 搜索内容
- `POST /api/v1/feeds/detail` - 获取 Feed 详情

**评论相关**

- `POST /api/v1/feeds/comment` - 发表评论
- `POST /api/v1/feeds/comment/reply` - 回复评论

**用户相关**

- `POST /api/v1/user/profile` - 获取用户主页

**发布相关**

- `POST /api/v1/publish` - 发布图文内容
- `POST /api/v1/publish_video` - 发布视频内容

### MCP 工具

支持以下 13 个 MCP 工具：

1. `check_login_status` - 检查登录状态
2. `get_login_qrcode` - 获取登录二维码
3. `delete_cookies` - 删除 cookies
4. `list_feeds` - 获取 Feed 列表
5. `search_feeds` - 搜索内容
6. `get_feed_detail` - 获取 Feed 详情
7. `post_comment_to_feed` - 发表评论
8. `reply_comment_in_feed` - 回复评论
9. `like_feed` - 点赞/取消点赞
10. `favorite_feed` - 收藏/取消收藏
11. `user_profile` - 获取用户主页
12. `publish_content` - 发布图文内容
13. `publish_with_video` - 发布视频内容

## 开发指南

### 添加新功能

1. 在 `xiaohongshu/` 目录下创建新的模块文件
2. 在 `service.py` 中添加对应的服务方法
3. 在 `mcp_server.py` 中注册 MCP 工具
4. 在 `routes.py` 中添加 HTTP 端点

### 运行测试

```bash
# TODO: 添加测试
pytest tests/
```

### 代码格式化

```bash
# 使用 black 格式化代码
black .

# 使用 isort 排序导入
isort .

# 使用 flake8 检查代码
flake8 .
```

## 与 Go 版本的对比

| 特性 | Go 版本 | Python 版本 |
|------|---------|-------------|
| 浏览器自动化 | go-rod | Playwright |
| Web 框架 | Gin | FastAPI |
| 数据验证 | 手动 | Pydantic |
| 异步支持 | Goroutines | asyncio |
| 类型系统 | 静态类型 | 类型提示 |
| 性能 | 更快 | 较慢但足够 |
| 开发效率 | 中等 | 更高 |
| 生态系统 | 成熟 | 更丰富 |

## 注意事项

### 浏览器选择器

由于小红书页面结构可能会变化，部分 CSS 选择器可能需要更新。如果遇到元素找不到的错误，请检查：

1. 页面是否完全加载
2. CSS 选择器是否正确
3. 是否需要登录

### 发布功能

图文发布和视频发布功能的骨架已实现，但具体的上传逻辑需要根据实际页面结构完善：

- 图片/视频上传
- 标签添加
- 发布确认

### 性能优化

- 使用页面池复用浏览器页面
- 实现请求缓存
- 优化图片加载策略

## 故障排除

### 浏览器启动失败

```bash
# 安装 Playwright 浏览器
playwright install chromium
playwright install-deps chromium
```

### Cookie 加载失败

检查 Cookie 文件路径和权限：

```bash
ls -la data/cookies.json
```

### 端口被占用

修改 `.env` 文件中的 `PORT` 配置。

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 许可证

MIT License

## 致谢

- 原 Go 版本：[xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- Playwright：https://playwright.dev/python/
- FastAPI：https://fastapi.tiangolo.com/
- MCP：https://modelcontextprotocol.io/

## 联系方式

如有问题或建议，请提交 Issue。