From fe82b14ba9e15a421e8ba7804fdf815fbf40e9e3 Mon Sep 17 00:00:00 2001 From: zy Date: Mon, 29 Sep 2025 00:16:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9EHTTP=20API=E6=96=87?= =?UTF-8?q?=E6=A1=A3=20(#178)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加小红书MCP HTTP API完整文档 - 包含所有端点的请求/响应格式说明 - 简化响应示例，突出关键字段结构 - 与实际代码结构保持一致 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude --- docs/API.md | 437 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 437 insertions(+) create mode 100644 docs/API.md diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..e53f0ff --- /dev/null +++ b/docs/API.md @@ -0,0 +1,437 @@ +# 小红书 MCP HTTP API 文档 + +## 概述 + +该项目提供了小红书 MCP (Model Context Protocol) 服务的 HTTP API 接口，同时支持 MCP 协议和标准的 HTTP REST API。本文档描述了 HTTP API 的使用方法。 + +**Base URL**: `http://localhost:8080` + +**注意**: 以下响应示例仅展示主要字段结构，完整的字段信息请通过实际API调用查看。 + +## 通用响应格式 + +所有 API 响应都使用统一的 JSON 格式： + +### 成功响应 +```json +{ + "success": true, + "data": {}, + "message": "操作成功消息" +} +``` + +### 错误响应 +```json +{ + "error": "错误消息", + "code": "ERROR_CODE", + "details": "详细错误信息" +} +``` + +## API 端点 + +### 1. 健康检查 + +检查服务状态。 + +**请求** +``` +GET /health +``` + +**响应** +```json +{ + "success": true, + "data": { + "status": "healthy", + "service": "xiaohongshu-mcp", + "account": "ai-report", + "timestamp": "now" + }, + "message": "服务正常" +} +``` + +--- + +### 2. 登录管理 + +#### 2.1 检查登录状态 + +检查当前用户的登录状态。 + +**请求** +``` +GET /api/v1/login/status +``` + +**响应** +```json +{ + "success": true, + "data": { + "is_logged_in": true, + "username": "用户名" + }, + "message": "检查登录状态成功" +} +``` + +#### 2.2 获取登录二维码 + +获取登录二维码，用于用户扫码登录。 + +**请求** +``` +GET /api/v1/login/qrcode +``` + +**响应** +```json +{ + "success": true, + "data": { + "timeout": "300", + "is_logged_in": false, + "img": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." + }, + "message": "获取登录二维码成功" +} +``` + +**响应字段说明:** +- `timeout`: 二维码过期时间（秒） +- `is_logged_in`: 当前是否已登录 +- `img`: Base64 编码的二维码图片 + +--- + +### 3. 内容发布 + +发布笔记内容到小红书。 + +**请求** +``` +POST /api/v1/publish +Content-Type: application/json +``` + +**请求体** +```json +{ + "title": "笔记标题", + "content": "笔记内容", + "images": [ + "http://example.com/image1.jpg", + "http://example.com/image2.jpg" + ], + "tags": ["标签1", "标签2"] +} +``` + +**请求参数说明:** +- `title` (string, required): 笔记标题 +- `content` (string, required): 笔记内容 +- `images` (array, required): 图片URL数组，至少包含一张图片 +- `tags` (array, optional): 标签数组 + +**响应** +```json +{ + "success": true, + "data": { + "title": "笔记标题", + "content": "笔记内容", + "images": 2, + "status": "published", + "post_id": "64f1a2b3c4d5e6f7a8b9c0d1" + }, + "message": "发布成功" +} +``` + +--- + +### 4. Feed 管理 + +#### 4.1 获取 Feeds 列表 + +获取用户的 Feeds 列表。 + +**请求** +``` +GET /api/v1/feeds/list +``` + +**响应** +```json +{ + "success": true, + "data": { + "feeds": [ + { + "xsecToken": "security_token_value", + "id": "feed_id_1", + "modelType": "note", + "noteCard": { + "type": "normal", + "displayTitle": "笔记标题", + "user": { + "userId": "user_id_1", + "nickname": "用户昵称", + "avatar": "https://example.com/avatar.jpg" + }, + "interactInfo": { + "likedCount": "100", + "commentCount": "50" + }, + "cover": { + "url": "https://example.com/cover.jpg" + } + }, + "index": 0 + } + ], + "count": 10 + }, + "message": "获取Feeds列表成功" +} +``` + +#### 4.2 搜索 Feeds + +根据关键词搜索 Feeds。 + +**请求** +``` +GET /api/v1/feeds/search?keyword=搜索关键词 +``` + +**查询参数:** +- `keyword` (string, required): 搜索关键词 + +**响应** +```json +{ + "success": true, + "data": { + "feeds": [ + { + "xsecToken": "security_token_value", + "id": "feed_id_1", + "modelType": "note", + "noteCard": { + "displayTitle": "相关笔记标题", + "user": { + "userId": "user_id_1", + "nickname": "用户昵称" + }, + "interactInfo": { + "likedCount": "80", + "commentCount": "35" + } + }, + "index": 0 + } + ], + "count": 5 + }, + "message": "搜索Feeds成功" +} +``` + +#### 4.3 获取 Feed 详情 + +获取指定 Feed 的详细信息。 + +**请求** +``` +POST /api/v1/feeds/detail +Content-Type: application/json +``` + +**请求体** +```json +{ + "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1", + "xsec_token": "security_token_here" +} +``` + +**请求参数说明:** +- `feed_id` (string, required): Feed ID +- `xsec_token` (string, required): 安全令牌 + +**响应** +```json +{ + "success": true, + "data": { + "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1", + "data": { + "note": { + "noteId": "64f1a2b3c4d5e6f7a8b9c0d1", + "title": "笔记标题", + "desc": "笔记详细内容描述", + "user": { + "userId": "user_id_123", + "nickname": "作者昵称" + }, + "interactInfo": { + "likedCount": "100", + "commentCount": "50" + }, + "imageList": [ + { + "urlDefault": "https://example.com/image1_default.jpg" + } + ] + }, + "comments": { + "list": [ + { + "id": "comment_id_1", + "content": "评论内容", + "userInfo": { + "nickname": "评论者昵称" + } + } + ], + "hasMore": true + } + } + }, + "message": "获取Feed详情成功" +} +``` + +--- + +### 5. 用户信息 + +获取用户主页信息。 + +**请求** +``` +POST /api/v1/user/profile +Content-Type: application/json +``` + +**请求体** +```json +{ + "user_id": "64f1a2b3c4d5e6f7a8b9c0d1", + "xsec_token": "security_token_here" +} +``` + +**请求参数说明:** +- `user_id` (string, required): 用户ID +- `xsec_token` (string, required): 安全令牌 + +**响应** +```json +{ + "success": true, + "data": { + "data": { + "userBasicInfo": { + "nickname": "用户昵称", + "desc": "用户个人描述", + "redId": "xiaohongshu_id" + }, + "interactions": [ + { + "type": "follows", + "name": "关注", + "count": "1000" + }, + { + "type": "fans", + "name": "粉丝", + "count": "5000" + } + ], + "feeds": [ + { + "id": "feed_id_1", + "noteCard": { + "displayTitle": "用户的笔记标题" + } + } + ] + } + }, + "message": "获取用户主页成功" +} +``` + +--- + +### 6. 评论管理 + +#### 6.1 发表评论 + +对指定 Feed 发表评论。 + +**请求** +``` +POST /api/v1/feeds/comment +Content-Type: application/json +``` + +**请求体** +```json +{ + "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1", + "xsec_token": "security_token_here", + "content": "评论内容" +} +``` + +**请求参数说明:** +- `feed_id` (string, required): Feed ID +- `xsec_token` (string, required): 安全令牌 +- `content` (string, required): 评论内容 + +**响应** +```json +{ + "success": true, + "data": { + "feed_id": "64f1a2b3c4d5e6f7a8b9c0d1", + "success": true, + "message": "评论发表成功" + }, + "message": "评论发表成功" +} +``` + +--- + +## 注意事项 + +1. **认证**: 部分 API 需要有效的登录状态，建议先调用登录状态检查接口确认登录。 + +2. **安全令牌**: `xsec_token` 是小红书的安全令牌，在调用需要该参数的接口时必须提供。 + +3. **图片上传**: 发布接口中的 `images` 参数需要提供可访问的图片URL。 + +4. **错误处理**: 所有接口在出错时都会返回统一格式的错误响应，请根据 `code` 字段进行相应的错误处理。 + +5. **日志记录**: 所有API调用都会被记录到服务日志中，包括请求方法、路径和状态码。 + +6. **跨域支持**: API 支持跨域请求 (CORS)。 + +## MCP 协议支持 + +除了上述HTTP API，本服务同时支持 MCP (Model Context Protocol) 协议： + +- **MCP 端点**: `/mcp` 和 `/mcp/*path` +- **协议类型**: 支持 JSON 响应格式的 Streamable HTTP +- **用途**: 可以通过MCP客户端调用相同的功能 + +更多MCP协议相关信息请参考 [Model Context Protocol 官方文档](https://modelcontextprotocol.io/)。 \ No newline at end of file