# XHS-MCP 使用指南

## 概述

本指南详细介绍如何使用 XHS-MCP 进行小红书自动化操作，包括认证、发布、搜索等功能。

## 🚀 快速开始

### 安装和运行

```bash
# 使用 npx 运行（推荐）
npx xhs-mcp --help

# 或者全局安装
npm install -g xhs-mcp
xhs-mcp --help
```

### 首次使用

1. **检查浏览器依赖**
```bash
npx xhs-mcp browser
```

2. **登录账户**
```bash
npx xhs-mcp login --timeout 120
```

3. **验证登录状态**
```bash
npx xhs-mcp status
```

## 📝 内容发布

### 图文发布

#### 使用本地图片

```bash
npx xhs-mcp publish \
  --type image \
  --title "美丽的风景" \
  --content "分享一张美丽的风景照片" \
  --media-paths "./images/photo1.jpg,./images/photo2.png" \
  --tags "风景,摄影"
```

#### 使用图片 URL（新功能）

```bash
npx xhs-mcp publish \
  --type image \
  --title "网络图片分享" \
  --content "来自网络的高质量图片" \
  --media-paths "https://example.com/image1.jpg,https://example.com/image2.png" \
  --tags "网络,分享"
```

#### 混合使用本地和网络图片

```bash
npx xhs-mcp publish \
  --type image \
  --title "我的相册" \
  --content "本地照片和网络图片的完美结合" \
  --media-paths "https://example.com/remote.jpg,./local/photo.jpg,https://example.com/another.png" \
  --tags "相册,混合"
```

### 视频发布

```bash
npx xhs-mcp publish \
  --type video \
  --title "我的视频" \
  --content "分享一个有趣的视频" \
  --media-paths "./videos/my_video.mp4" \
  --tags "视频,分享"
```

### 支持的格式

#### 图片格式
- JPEG/JPG
- PNG
- GIF
- WebP
- BMP

#### 视频格式
- MP4
- MOV
- AVI
- MKV
- WebM
- FLV
- WMV

## 🔍 内容发现

### 获取推荐内容

```bash
npx xhs-mcp feeds
```

### 搜索笔记

```bash
npx xhs-mcp search -k "美食"
```

### 当前用户笔记

```bash
# 列出当前用户笔记
npx xhs-mcp usernote list [-l 20] [--cursor <cursor>]
```

### 评论笔记

```bash
npx xhs-mcp comment --feed-id <feed_id> --xsec-token <token> -n "很棒的内容！"
```

## 🤖 MCP 服务器模式

### Stdio 模式（默认）

```bash
# 启动 MCP 服务器
npx xhs-mcp mcp

# 启用调试日志
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp
```

### HTTP 模式

```bash
# 启动 HTTP 服务器（默认端口 3000）
npx xhs-mcp mcp --mode http

# 指定端口
npx xhs-mcp mcp --mode http --port 8080

# 启用调试模式
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp --mode http
```

### 客户端配置

#### Cursor 配置

`.cursor/mcp.json`：
```json
{
  "mcpServers": {
    "xhs-mcp": {
      "command": "npx",
      "args": ["xhs-mcp", "mcp"],
      "env": { "XHS_ENABLE_LOGGING": "true" }
    }
  }
}
```

#### HTTP 客户端配置

```json
{
  "mcpServers": {
    "xhs-mcp-http": {
      "command": "npx",
      "args": ["xhs-mcp", "mcp", "--mode", "http", "--port", "3000"],
      "env": { "XHS_ENABLE_LOGGING": "true" }
    }
  }
}
```

## 🛠️ 高级功能

### 图片 URL 自动下载

XHS-MCP 现在支持直接使用 HTTP/HTTPS 图片 URL 进行发布，无需手动下载：

#### 工作原理

1. **URL 识别**：自动识别以 `http://` 或 `https://` 开头的路径
2. **智能下载**：将 URL 图片下载到 `./temp_images/` 目录
3. **格式验证**：检查文件签名，确保是有效的图片格式
4. **缓存机制**：已下载的图片会被缓存，避免重复下载
5. **混合处理**：URL 和本地路径可以混合使用

#### 缓存机制

- 使用 URL 的 SHA256 哈希值生成唯一文件名
- 相同的 URL 只会下载一次
- 缓存的图片可以在多次发布中重复使用

#### 下载位置

默认情况下，下载的图片会保存在项目根目录的 `temp_images/` 文件夹中：

```
xhs-mcp/
├── temp_images/          # 自动创建
│   ├── img_abc123_1234567890.jpg
│   ├── img_def456_1234567891.png
│   └── ...
```

### 错误处理

#### 常见错误及解决方案

**1. 图片下载失败**
```
Error: Failed to download image: HTTP 404 Not Found
```
**解决方案**：检查 URL 是否正确，图片是否仍然存在

**2. 无效的图片格式**
```
Error: Downloaded file is not a valid image
```
**解决方案**：确保 URL 指向的是真实的图片文件，而不是 HTML 页面

**3. 下载超时**
```
Error: Image download timeout after 30000ms
```
**解决方案**：
- 检查网络连接
- 图片可能太大
- 尝试使用本地图片

**4. 本地文件不存在**
```
Error: Local image file not found: ./image.jpg
```
**解决方案**：检查文件路径是否正确

## 📊 性能优化

### 1. 使用缓存

如果需要多次发布相同的图片，第一次下载后会自动缓存：

```bash
# 第一次 - 下载图片（可能需要几秒）
npx xhs-mcp publish --media-paths "https://example.com/large-image.jpg"

# 第二次 - 使用缓存（即时）
npx xhs-mcp publish --media-paths "https://example.com/large-image.jpg"
```

### 2. 预下载图片

对于大批量发布，可以先下载图片到本地：

```bash
# 使用测试脚本下载图片
node examples/test-image-url-download.js
```

### 3. 合理控制并发

避免同时运行多个发布任务，建议串行执行。

## ⚠️ 注意事项

### 发布限制

- **图文发布**：标题≤20字符、内容≤1000字符、图片≤18张
- **视频发布**：文件大小建议≤500MB
- **频率控制**：避免过于频繁的发布操作

### 账号安全

- 避免同账号多端同时网页登录
- 合理控制操作频率
- 定期检查登录状态

### 网络要求

- 确保网络连接稳定
- 图片 URL 需要可以公开访问
- 避免使用需要登录才能访问的图片

## 🔧 调试和故障排除

### 启用调试日志

```bash
XHS_ENABLE_LOGGING=true npx xhs-mcp <command>
```

### 查看下载的图片

```bash
ls -lh temp_images/
```

### 清理缓存

```bash
rm -rf temp_images/
```

### 验证 MCP 连接

```bash
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx xhs-mcp mcp
```

## 📚 更多资源

- [图片 URL 发布完整指南](./examples/image-url-publish.md)
- [项目结构文档](./PROJECT_STRUCTURE.md)
- [HTTP 传输文档](./HTTP_TRANSPORTS.md)
- [测试脚本](./examples/test-image-url-download.js)

## 🤝 获取帮助

- 查看可用工具：`npx xhs-mcp tools`
- 查看详细帮助：`npx xhs-mcp <command> --help`
- 提交问题：[GitHub Issues](https://github.com/algovate/xhs-mcp/issues)

---

**提示**：这个功能参考了 [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) 项目的优秀实现，特此感谢！