# dots2api

`dots2api` 现在是一个基于 dots.ai 的 MCP 搜索工具。它通过 Playwright 复用已登录的 dots.ai 网页会话，把 dots.ai / 小红书相关搜索结果作为 MCP tool 暴露给其他 AI 客户端调用。

历史上本项目曾经尝试提供 OpenAI-compatible API；当前主入口已经收敛为 Streamable HTTP MCP 服务。

## 功能

- MCP Streamable HTTP endpoint: `http://127.0.0.1:8000/mcp`
- 首选工具：`search_xiaohongshu`
- 兼容别名：`query_dots`
- 返回文本结果，并在 dots.ai 返回图片时附带 Markdown 图片链接和 MCP image content
- 使用 `.browser_data/` 保持浏览器登录状态
- 使用 `.session.json` 导出/导入可迁移 session
- 服务运行时会在成功查询后保存 session，并按 `SESSION_REFRESH_INTERVAL` 定期保存

## 本地运行

```bash
pip install -r requirements.txt
playwright install chromium
python login.py
python -m src.server
```

手机号登录：

```bash
python login.py --phone 13800138000
```

服务默认监听 `8000`，MCP 地址为：

```text
http://127.0.0.1:8000/mcp
```

也可以显式指定端口：

```bash
PORT=8100 python -m src.server
python -m src.server --port 8100
```

PowerShell：

```powershell
$env:PORT = "8100"
python -m src.server
```

## MCP 客户端配置

支持 remote/Streamable HTTP MCP 的客户端通常可以使用类似配置：

```json
{
  "mcpServers": {
    "dots-search": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

工具选择建议：

- 用户提到“小红书 / XHS / 点点 / 种草 / 图文灵感 / 图片参考 / 内容参考”时优先调用 `search_xiaohongshu`
- 老配置仍可调用 `query_dots`，它等同于 `search_xiaohongshu`

## Docker

先在本机完成登录并生成 `.browser_data/` 与 `.session.json`：

```bash
python login.py
docker compose up -d --build
```

查看日志：

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

`docker-compose.yml` 会把 `.browser_data/` 和 `.session.json` 挂载进容器。其中 `.session.json` 必须可写，服务才能保存自动刷新后的 session 状态。

## Session 与登录续期

登录状态由两部分组成：

- `.browser_data/`：Playwright persistent context，保存完整浏览器 profile
- `.session.json`：便于迁移到服务器的 cookies/localStorage 导出文件

服务启动时会尝试从 `.session.json` 恢复 session。每次成功查询后会写回 `.session.json`，并按 `SESSION_REFRESH_INTERVAL` 定期保存一次当前浏览器 session。

可用环境变量：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PORT` | `8000` | MCP HTTP 服务端口 |
| `HEADLESS` | `1` | `1` 为无头浏览器，`0` 显示浏览器窗口 |
| `SESSION_FILE` | `.session.json` | session 导出文件路径 |
| `SESSION_REFRESH_INTERVAL` | `300` | 定期保存 session 的间隔秒数；设为 `0` 可关闭 |

如果 dots.ai 服务端彻底吊销 session，仍需要重新运行 `python login.py` 登录。

## 测试与排查

静态检查：

```bash
python -m compileall src login.py test_e2e.py test_mcp.py
```

MCP 工具列表 smoke test（需要服务已启动）：

```bash
python test_mcp.py --url http://127.0.0.1:8000/mcp
```

实际调用 dots.ai（需要已登录，会消耗一次查询）：

```bash
python test_mcp.py --message "帮我找小红书露营拍照灵感"
```

## 文件说明

- `src/server.py`：当前 canonical MCP Streamable HTTP 服务
- `src/mcp_server.py`：历史入口兼容层，会转到 `src.server`
- `src/main.py`：本地调试用 CLI
- `login.py`：登录并导出 session，不会写入源码
- `reverse-engineering.md`：历史逆向研究记录，不代表当前运行入口

## 免责声明

本项目仅供学习研究使用。请遵守 dots.ai 及相关平台的服务条款，不要用于未授权的数据抓取或滥用场景。