288 lines
8.2 KiB
Markdown
288 lines
8.2 KiB
Markdown
# Social MCP
|
||
|
||
[English README](./README.md)
|
||
|
||
一个面向社交媒体自动化的服务，既提供 MCP（Model Context Protocol）工具能力，也提供 REST API。当前支持平台：**小红书**。
|
||
|
||
## 功能特性
|
||
|
||
- 小红书 **22 个 MCP 工具**（登录、浏览、发布、互动、通知、自动化）
|
||
- 带 Bearer Token 鉴权与按路由限流的 REST API
|
||
- 基于 `rebrowser-playwright` 的浏览器自动化，按平台串行队列执行
|
||
- 文件型 Cookie 持久化（`0600` 权限、原子写入）
|
||
- 通知任务状态入库 SQLite（`$COOKIE_DIR/xiaohongshu/automation.db`），保障自动回复幂等
|
||
- Web 控制台（React + Vite）：登录、内容浏览、发布、接口测试
|
||
- 安全控制：Token 常量时间比对、绑定地址安全门、错误信息脱敏、日志字段脱敏
|
||
- 支持 Docker 部署
|
||
- 插件化平台架构，便于扩展更多平台
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Node.js >= 22.0.0
|
||
- pnpm
|
||
|
||
### 安装与运行（后端）
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 首次安装 Playwright Chromium
|
||
npx playwright install chromium
|
||
|
||
# 构建后端
|
||
pnpm build
|
||
|
||
# 启动服务
|
||
pnpm start
|
||
```
|
||
|
||
本地默认监听地址：`http://127.0.0.1:9527`。
|
||
首次启动会在控制台打印 REST API Bearer Token，并保存到 `~/.social-mcp/.api-token`。
|
||
|
||
### 构建并启用 Web 控制台
|
||
|
||
```bash
|
||
# 构建后端 + 前端
|
||
pnpm build:all
|
||
|
||
# 启动服务（会同时托管 dashboard）
|
||
pnpm start
|
||
```
|
||
|
||
### 开发命令
|
||
|
||
```bash
|
||
# 后端 watch 构建
|
||
pnpm dev
|
||
|
||
# 前端开发服务器
|
||
pnpm dev:web
|
||
|
||
# 类型检查
|
||
pnpm lint
|
||
|
||
# 测试
|
||
pnpm test
|
||
```
|
||
|
||
## MCP 集成
|
||
|
||
### Claude Desktop
|
||
|
||
在 `claude_desktop_config.json` 中添加：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"social-mcp": {
|
||
"url": "http://127.0.0.1:9527/sse"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### MCP 工具列表（小红书）
|
||
|
||
| 工具名 | 说明 |
|
||
|------|------|
|
||
| `xhs_check_login` | 检查登录状态 |
|
||
| `xhs_get_login_qrcode` | 获取扫码登录二维码 |
|
||
| `xhs_delete_cookies` | 删除 Cookie 并重置登录状态 |
|
||
| `xhs_list_feeds` | 获取推荐流 |
|
||
| `xhs_search` | 关键词搜索笔记（支持筛选） |
|
||
| `xhs_get_feed_detail` | 获取笔记详情（支持直接传笔记 URL） |
|
||
| `xhs_get_sub_comments` | 拉取某条父评论的子评论（Keyset 游标分页） |
|
||
| `xhs_get_user_profile` | 获取用户主页及近期笔记（支持直接传主页 URL） |
|
||
| `xhs_list_my_notes` | 获取当前账号已发布笔记列表 |
|
||
| `xhs_publish_image` | 发布图文笔记 |
|
||
| `xhs_publish_video` | 发布视频笔记 |
|
||
| `xhs_post_comment` | 发表评论 |
|
||
| `xhs_reply_comment` | 回复评论 |
|
||
| `xhs_set_like_state` | 设置点赞状态（幂等） |
|
||
| `xhs_set_favorite_state` | 设置收藏状态（幂等） |
|
||
| `xhs_get_unprocessed_notifications` | 从本地 SQLite 获取“未处理”通知任务 |
|
||
| `xhs_mark_notification_task` | 手动标记通知任务状态（new/pending/ignored/replied/failed） |
|
||
| `xhs_mark_notification_tasks` | 批量标记通知任务状态 |
|
||
| `xhs_list_failed_notification_tasks` | 获取失败通知任务列表（用于排障/重试） |
|
||
| `xhs_retry_notification_task` | 按 fingerprint 重试失败通知任务 |
|
||
| `xhs_retry_notification_tasks` | 批量重试失败通知任务 |
|
||
| `xhs_reply_notification` | 对通知进行回复 |
|
||
|
||
## REST API
|
||
|
||
所有 `/api/*` 接口都需要：
|
||
|
||
- `Authorization: Bearer <token>`
|
||
- `POST` 请求需设置 `Content-Type: application/json`
|
||
|
||
示例：
|
||
|
||
```bash
|
||
# 查询登录状态
|
||
curl -H "Authorization: Bearer <token>" \
|
||
http://127.0.0.1:9527/api/xhs/login/status
|
||
|
||
# 搜索笔记
|
||
curl -X POST \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"keyword":"travel","filters":{"sort":"popularity_descending"}}' \
|
||
http://127.0.0.1:9527/api/xhs/search
|
||
```
|
||
|
||
### 接口清单
|
||
|
||
读接口限流：**60/min**（按 IP）
|
||
写接口限流：**10/min**（按 IP）
|
||
|
||
| 方法 | 路径 | 说明 | 限流 |
|
||
|------|------|------|------|
|
||
| `GET` | `/api/xhs/login/status` | 检查登录状态 | 60/min |
|
||
| `GET` | `/api/xhs/login/qrcode` | 获取二维码 | 60/min |
|
||
| `DELETE` | `/api/xhs/login/cookies` | 删除 Cookie | 10/min |
|
||
| `GET` | `/api/xhs/login/cookie-check` | 检查本地 Cookie 文件是否存在 | 60/min |
|
||
| `GET` | `/api/xhs/feeds` | 获取推荐流 | 60/min |
|
||
| `POST` | `/api/xhs/search` | 搜索笔记 | 60/min |
|
||
| `POST` | `/api/xhs/feeds/detail` | 获取笔记详情 | 60/min |
|
||
| `POST` | `/api/xhs/feeds/sub-comments` | 拉取子评论 | 60/min |
|
||
| `POST` | `/api/xhs/user/profile` | 获取用户主页 | 60/min |
|
||
| `GET` | `/api/xhs/my-notes` | 获取我的笔记 | 60/min |
|
||
| `POST` | `/api/xhs/publish/image` | 发布图文 | 10/min |
|
||
| `POST` | `/api/xhs/publish/video` | 发布视频 | 10/min |
|
||
| `POST` | `/api/xhs/comment` | 发表评论 | 10/min |
|
||
| `POST` | `/api/xhs/comment/reply` | 回复评论 | 10/min |
|
||
| `POST` | `/api/xhs/like` | 点赞切换 | 10/min |
|
||
| `POST` | `/api/xhs/favorite` | 收藏切换 | 10/min |
|
||
| `GET` | `/api/xhs/notifications/comments` | 获取评论通知 | 60/min |
|
||
| `GET` | `/api/xhs/notifications/unprocessed` | 获取本地未处理通知任务 | 60/min |
|
||
| `POST` | `/api/xhs/notifications/reply` | 回复通知 | 10/min |
|
||
|
||
### 返回格式
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "VALIDATION_ERROR",
|
||
"message": "keyword: Required"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 公开接口（无需鉴权）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| `GET` | `/health` | 健康检查（运行时长/内存/插件状态） |
|
||
| `GET` | `/sse` | MCP SSE 连接入口 |
|
||
| `POST` | `/messages` | MCP JSON-RPC 消息入口 |
|
||
|
||
## Docker 部署
|
||
|
||
### 使用 Compose（推荐）
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose up -d
|
||
|
||
# 查看日志
|
||
docker compose logs -f
|
||
|
||
# 查找 Bearer Token
|
||
docker compose logs social-mcp | grep "Bearer Token"
|
||
```
|
||
|
||
### 直接运行 Docker
|
||
|
||
```bash
|
||
docker build -t social-mcp .
|
||
|
||
docker run -d \
|
||
--name social-mcp \
|
||
-p 127.0.0.1:3000:3000 \
|
||
--shm-size=1gb \
|
||
--memory=2g \
|
||
--cpus=2.0 \
|
||
--security-opt=no-new-privileges:true \
|
||
--cap-drop=ALL \
|
||
--read-only \
|
||
--tmpfs /tmp:size=512m \
|
||
-v social-mcp-data:/home/appuser/.social-mcp \
|
||
social-mcp
|
||
```
|
||
|
||
说明：Docker 镜像默认使用 `PORT=3000`。
|
||
|
||
## 环境变量
|
||
|
||
| 变量 | 默认值（本地） | 说明 |
|
||
|------|----------------|------|
|
||
| `PORT` | `9527` | HTTP 监听端口 |
|
||
| `HOST` | `127.0.0.1` | 绑定地址（`0.0.0.0` 需设置 `ALLOW_REMOTE`） |
|
||
| `HEADLESS` | `true` | 是否无头运行浏览器 |
|
||
| `BROWSER_BIN` | 自动探测 | 自定义 Chromium 路径 |
|
||
| `LOG_LEVEL` | `info` | 日志级别（`debug`/`info`/`warn`/`error`） |
|
||
| `NODE_ENV` | `development` | 运行环境 |
|
||
| `COOKIE_DIR` | `~/.social-mcp` | Cookie/Token 存储目录 |
|
||
| `MAX_QUEUE_DEPTH` | `10` | 单平台最大排队深度 |
|
||
| `ALLOW_REMOTE` | 空 | 仅当值为 `yes-i-understand-the-risk` 时允许公网绑定 |
|
||
| `XHS_NOTIFICATION_POLL_ENABLED` | `true` | 是否启用通知定时同步到 SQLite |
|
||
| `XHS_NOTIFICATION_POLL_INTERVAL_SEC` | `60` | 通知同步周期（秒，最小 15） |
|
||
| `XHS_NOTIFICATION_POLL_MAX_COUNT` | `20` | 每次同步最多拉取通知数 |
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
social-mcp/
|
||
├── src/
|
||
│ ├── index.ts
|
||
│ ├── server/
|
||
│ │ ├── app.ts
|
||
│ │ └── middleware.ts
|
||
│ ├── browser/
|
||
│ │ └── manager.ts
|
||
│ ├── cookie/
|
||
│ │ └── store.ts
|
||
│ ├── config/
|
||
│ │ └── index.ts
|
||
│ ├── utils/
|
||
│ │ ├── logger.ts
|
||
│ │ ├── errors.ts
|
||
│ │ └── downloader.ts
|
||
│ └── platforms/
|
||
│ └── xiaohongshu/
|
||
│ ├── index.ts
|
||
│ ├── routes.ts
|
||
│ ├── schemas.ts
|
||
│ ├── selectors.ts
|
||
│ ├── login.ts
|
||
│ ├── feeds.ts
|
||
│ ├── search.ts
|
||
│ ├── feed-detail.ts
|
||
│ ├── user-profile.ts
|
||
│ ├── my-notes.ts
|
||
│ ├── publish.ts
|
||
│ ├── publish-video.ts
|
||
│ ├── comment.ts
|
||
│ ├── interaction.ts
|
||
│ ├── notification.ts
|
||
│ ├── notification-state.ts
|
||
│ └── notification-sync.ts
|
||
└── web/
|
||
└── src/
|
||
```
|
||
|
||
## License
|
||
|
||
ISC
|