docs: 新增HTTP API文档 (#178)
- 添加小红书MCP HTTP API完整文档 - 包含所有端点的请求/响应格式说明 - 简化响应示例，突出关键字段结构 - 与实际代码结构保持一致 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
zy
437
docs/API.md
Normal file
437
docs/API.md
Normal file
@@ -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/)。
|
||||
Reference in New Issue
Block a user