xhs-mcp 0.7.3 → 0.8.3

package/README.en.md

@@ -17,7 +17,13 @@ Unified CLI `xhs-mcp` with built-in MCP server subcommand. Automate XiaoHongShu
 ## ✨ Features
 
 - Auth: login, logout, status check
-- Publish: unified content publishing (images: 1-18 files, videos: exactly 1 file)
+- Publish: unified content publishing
+  - **Images**: 1-18 files or URLs
+  - **Videos**: exactly 1 file
+  - ⭐ **New**: Auto-download image URLs (HTTP/HTTPS)
+  - ⭐ **New**: Precise title width validation (CJK: 2 units, ASCII: 1 unit)
+  - Support local paths and URLs mixed
+  - Smart caching to avoid duplicate downloads
 - Discover: home feeds, keyword search, note detail, comment
 - Automation: Puppeteer-driven, headless mode, cookie management
 
@@ -27,8 +33,9 @@ Unified CLI `xhs-mcp` with built-in MCP server subcommand. Automate XiaoHongShu
 - `xhs_discover_feeds`, `xhs_search_note`, `xhs_get_note_detail`
 - `xhs_comment_on_note`
 - `xhs_publish_content` (unified interface: `type`, `title`, `content`, `media_paths`, `tags`)
-  - Images: 1-18 image files
-  - Videos: exactly 1 video file
+  - **Images**: 1-18 image files or URLs
+  - **Videos**: exactly 1 video file
+  - **Mixed**: Support image URLs and local paths together
 
 ## 🚀 Quick Start (MCP)
 
@@ -68,18 +75,37 @@ echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx xhs-mcp mcp
 ## 🧰 CLI
 
 ```bash
+# Auth
 npx xhs-mcp login --timeout 120
 npx xhs-mcp logout
 npx xhs-mcp status
- npx xhs-mcp browser  # check and install Chromium, shows executable path
- npx xhs-mcp feeds
- npx xhs-mcp search -k keyword
- npx xhs-mcp note-detail --feed-id <id> --xsec-token <token>
- npx xhs-mcp comment --feed-id <id> --xsec-token <token> -n "Nice!"
- npx xhs-mcp publish --type image --title Title --content Content -m path1.jpg,path2.png --tags a,b
- npx xhs-mcp publish --type video --title Title --content Content -m video.mp4 --tags a,b
- npx xhs-mcp tools [--detailed] [--json]
- npx xhs-mcp mcp --mode http --port 3000
+
+# Browser
+npx xhs-mcp browser  # check and install Chromium, shows executable path
+
+# Discover
+npx xhs-mcp feeds
+npx xhs-mcp search -k keyword
+npx xhs-mcp note-detail --feed-id <id> --xsec-token <token>
+npx xhs-mcp comment --feed-id <id> --xsec-token <token> -n "Nice!"
+
+# Publish with local images
+npx xhs-mcp publish --type image --title Title --content Content -m path1.jpg,path2.png --tags a,b
+
+# ⭐ Publish with image URLs (auto-download)
+npx xhs-mcp publish --type image --title Title --content Content -m "https://example.com/img1.jpg,https://example.com/img2.png" --tags a,b
+
+# Mix URLs and local paths
+npx xhs-mcp publish --type image --title Title --content Content -m "https://example.com/img1.jpg,./local/img2.jpg" --tags a,b
+
+# Video
+npx xhs-mcp publish --type video --title Title --content Content -m video.mp4 --tags a,b
+
+# Tools
+npx xhs-mcp tools [--detailed] [--json]
+
+# MCP Server
+npx xhs-mcp mcp --mode http --port 3000
 ```
 
 ## 🔧 Client Integration (Cursor)
@@ -100,9 +126,35 @@ npx xhs-mcp status
 
 ## ⚠️ Notes
 
-- Title≤20, content≤1000, images: 1-18 files, videos: exactly 1 file
+- **Images**: Title≤20 chars (40 display units), content≤1000, 1-18 images
+- **Videos**: exactly 1 video file, recommended size ≤500MB
 - Avoid multiple web logins for the same account simultaneously
 - Keep reasonable posting frequency
+- Image URLs auto-download to `./temp_images/` directory (cached)
+- Supported image formats: JPEG, PNG, GIF, WebP, BMP
+
+## 📖 Documentation and Examples
+
+### 📚 Documentation
+- [Usage Guide](./docs/USAGE_GUIDE.md) - Detailed usage and best practices
+- [HTTP Transports](./docs/HTTP_TRANSPORTS.md) - HTTP/SSE mode configuration
+- [Publish Guide](./docs/PUBLISH_GUIDE.md) - NPM publishing process
+
+## 🛠️ Build Notes
+
+- Unified single production build config: `config/webpack.config.js`
+- Development and optimized variants have been removed.
+- For development:
+  - `npm run dev` (run TypeScript CLI directly)
+  - `npm run build` (bundle to `dist/xhs-mcp.js`)
+
+### 🎨 Examples
+- [Examples](./examples/README.md) - Image and publishing examples
+- [Sample Images](./examples/images/) - Test images
+
+### 🧪 Tests
+- [Run Tests](./tests/README.md) - Testing guide
+- Run all tests: `npm test`
 
 ## 🙏 Acknowledgments
 

package/README.md

@@ -17,7 +17,14 @@
 ## ✨ 功能
 
 - 认证：登录、登出、状态检查
-- 发布：图文发布（标题≤20、内容≤1000、最多18图）
+- 发布：图文和视频发布
+  - **图文发布**：标题≤20字符（40显示单位）、内容≤1000、最多18图
+  - **视频发布**：支持 MP4、MOV、AVI、MKV、WebM、FLV、WMV 格式
+  - ⭐ **新功能**: 支持图片 URL 自动下载（HTTP/HTTPS）
+  - ⭐ **新功能**: 标题宽度精确验证（CJK字符2单位，ASCII字符1单位）
+  - 支持本地图片路径
+  - 支持 URL 和本地路径混合使用
+  - 智能缓存机制，避免重复下载
 - 发现：推荐、搜索、详情、评论
 - 自动化：Puppeteer 驱动、无头模式、Cookie 管理
 
@@ -27,8 +34,9 @@
 - `xhs_discover_feeds`、`xhs_search_note`、`xhs_get_note_detail`
 - `xhs_comment_on_note`
 - `xhs_publish_content`（统一发布接口：`type`、`title`、`content`、`media_paths`、`tags`）
-  - 图片：1-18个图片文件
-  - 视频：恰好1个视频文件
+  - **图片发布**：1-18个图片文件或URL
+  - **视频发布**：恰好1个视频文件
+  - **混合使用**：支持图片URL和本地路径混合
 
 ## 🚀 快速开始（MCP）
 
@@ -107,7 +115,16 @@ npx xhs-mcp note-detail --feed-id <id> --xsec-token <token> [-b /path/to/chromiu
 npx xhs-mcp comment --feed-id <id> --xsec-token <token> -n "Nice!" [-b /path/to/chromium]
 
 # 发布
+# 使用本地图片
 npx xhs-mcp publish --type image --title 标题 --content 内容 -m path1.jpg,path2.png --tags a,b [-b /path/to/chromium]
+
+# ⭐ 使用图片 URL（自动下载）
+npx xhs-mcp publish --type image --title 标题 --content 内容 -m "https://example.com/img1.jpg,https://example.com/img2.png" --tags a,b
+
+# 混合使用 URL 和本地路径
+npx xhs-mcp publish --type image --title 标题 --content 内容 -m "https://example.com/img1.jpg,./local/img2.jpg" --tags a,b
+
+# 发布视频
 npx xhs-mcp publish --type video --title 视频标题 --content 视频描述 -m path/to/video.mp4 --tags a,b [-b /path/to/chromium]
 
 # 查看可用工具
@@ -165,9 +182,34 @@ npx xhs-mcp mcp [--mode stdio|http] [--port 3000]
 
 ## ⚠️ 注意事项
 
-- 标题≤20、内容≤1000、图片≤18
+- **图文发布**：标题≤20、内容≤1000、图片≤18
+- **视频发布**：支持多种格式，文件大小建议≤500MB
 - 避免同账号多端同时网页登录
 - 合理控制发帖频率
+- 图片 URL 自动下载到 `./temp_images/` 目录（自动缓存）
+- 图片 URL 支持格式：JPEG、PNG、GIF、WebP、BMP
+
+## 📖 文档和示例
+
+### 📚 文档
+- [完整使用指南](./docs/USAGE_GUIDE.md) - 详细的使用说明和最佳实践
+- [HTTP 传输文档](./docs/HTTP_TRANSPORTS.md) - HTTP/SSE 模式配置
+- [发布指南](./docs/PUBLISH_GUIDE.md) - NPM 发布流程
+
+### 🎨 示例
+- [使用示例](./examples/README.md) - 图片和发布示例
+- [示例图片](./examples/images/) - 可用于测试的示例图片
+
+### 🧪 测试
+- [运行测试](./tests/README.md) - 测试说明和用法
+- 运行所有测试：`npm test`
+
+## 🛠️ 构建说明
+
+- 统一使用单一生产构建配置：`config/webpack.config.js`
+- 已移除开发与优化变体；开发请直接运行：
+  - `npm run dev`（直接运行 TypeScript CLI）
+  - `npm run build`（打包到 `dist/xhs-mcp.js`）
 
 ## 🙏 致谢