redbook-cli 0.2.0__tar.gz

redbook_cli-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

redbook_cli-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Runtime & sensitive
+mcp/cookies.json
+mcp/cookies.json.bak
+mcp/mcp.log
+tmp/
+config/accounts.json
+login_status_cache.json
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Config
+~/.xhs/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/

redbook_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 angiin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

redbook_cli-0.2.0/PKG-INFO

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: redbook-cli
+Version: 0.2.0
+Summary: 小红书命令行工具 — 搜索、发布、互动、数据分析、短索引导航
+Project-URL: Homepage, https://github.com/Youhai020616/xiaohongshu
+Project-URL: Repository, https://github.com/Youhai020616/xiaohongshu
+Author-email: Youhai <youhai020616@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,redbook,xhs,xiaohongshu,小红书
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: browser-cookie3>=0.19
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: rich>=13.0
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <h1 align="center">📕 xiaohongshu</h1>
+  <p align="center">AI-powered Xiaohongshu (小红书/RED) automation — publish, search, engage, and analyze.</p>
+</p>
+
+<p align="center">
+  <a href="#cli-quick-start">CLI Quick Start</a> •
+  <a href="#features">Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#mcp-tools">MCP Tools</a> •
+  <a href="#cdp-scripts">CDP Scripts</a> •
+  <a href="#openclaw-integration">OpenClaw</a> •
+  <a href="#claude-code-integration">Claude Code</a> •
+  <a href="./LICENSE">License</a>
+</p>
+
+---
+
+<p align="center">
+  <img src="./demo.gif" alt="xiaohongshu demo" width="800">
+</p>
+
+## CLI Quick Start
+
+The fastest way to get started — **3 commands** from zero to posting:
+
+```bash
+# 1. Clone
+git clone https://github.com/Youhai020616/xiaohongshu.git
+cd xiaohongshu
+
+# 2. One-click install (auto: Python check → venv → pip install → MCP binary)
+bash setup.sh
+
+# 3. Initialize (auto: proxy config → start MCP → QR login)
+source activate.sh && xhs init
+```
+
+Then just use:
+
+```bash
+xhs search "AI创业"                                          # Search
+xhs publish -t "Hello" -c "My first post" -i photo.jpg      # Publish
+xhs like FEED_ID -t TOKEN                                    # Like
+xhs analytics                                                # Dashboard
+xhs --help                                                   # All commands
+```
+
+> 📖 Full CLI guide: [docs/cli-guide.md](docs/cli-guide.md)
+
+---
+
+## What is this?
+
+A complete toolkit for automating Xiaohongshu (小红书/RED Note) operations through two complementary engines:
+
+| Engine | Technology | Use Cases | Startup |
+|--------|-----------|-----------|---------|
+| **MCP Server** | Go binary, JSON-RPC | Publish, search, comment, like, follow | Always-on daemon |
+| **CDP Scripts** | Python, Chrome DevTools | Analytics dashboard, notifications, advanced search | On-demand |
+
+Built as an [OpenClaw](https://github.com/openclaw/openclaw) Skill, but works standalone or with any MCP-compatible client (Claude Code, Cursor, etc.).
+
+## Features
+
+- 📝 **Publish** — Image posts and video posts with tags, scheduling, and visibility control
+- 🔍 **Search** — Keyword search with filters (sort, note type, suggested keywords)
+- 💬 **Engage** — Comment, reply, like, favorite on any post
+- 👤 **Profile** — Fetch any user's profile and posts
+- 📊 **Analytics** — Creator dashboard data export (CSV), content performance metrics
+- 🔔 **Notifications** — Fetch mentions and interaction notifications
+- 👥 **Multi-Account** — Isolated Chrome profiles per account
+- 🔐 **QR Code Login** — Scan-to-login, persistent cookie storage
+
+## Quick Start
+
+### Prerequisites
+
+- macOS (Apple Silicon) — MCP binary is pre-built for `darwin-arm64`
+- Python 3.9+ (for CDP scripts)
+- Google Chrome (for CDP scripts and QR login)
+- A proxy/VPN if outside China (MCP requires `-rod` proxy flag)
+
+### 1. Clone
+
+```bash
+git clone https://github.com/Youhai020616/xiaohongshu.git
+cd xiaohongshu
+```
+
+### 2. Start MCP Server
+
+```bash
+cd mcp
+chmod +x xiaohongshu-mcp-darwin-arm64
+
+# Without proxy (inside China)
+./xiaohongshu-mcp-darwin-arm64 -port :18060
+
+# With proxy (outside China)
+./xiaohongshu-mcp-darwin-arm64 -port :18060 -rod "proxy=http://127.0.0.1:7897"
+```
+
+### 3. Login
+
+On first run, get a QR code to scan with your Xiaohongshu app:
+
+```bash
+curl -s -X POST http://127.0.0.1:18060/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"1.0"}}}'
+# Save the Mcp-Session-Id from response headers
+
+curl -s -X POST http://127.0.0.1:18060/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
+  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+
+curl -s -X POST http://127.0.0.1:18060/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_login_qrcode","arguments":{}}}'
+```
+
+Or use the login helper binary:
+
+```bash
+cd mcp
+./xiaohongshu-login-darwin-arm64
+```
+
+### 4. Publish Your First Post
+
+```bash
+curl -s -X POST http://127.0.0.1:18060/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
+  -d '{
+    "jsonrpc":"2.0","id":3,
+    "method":"tools/call",
+    "params":{
+      "name":"publish_content",
+      "arguments":{
+        "title":"Hello from API 🚀",
+        "content":"My first automated post on Xiaohongshu!",
+        "images":["/path/to/image.jpg"],
+        "tags":["测试","自动化"]
+      }
+    }
+  }'
+```
+
+## MCP Tools
+
+The MCP server exposes these tools via the [Model Context Protocol](https://modelcontextprotocol.io/):
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `check_login_status` | Check if logged in | — |
+| `get_login_qrcode` | Get QR code for login (base64) | — |
+| `delete_cookies` | Reset login state | — |
+| `publish_content` | Publish image post | `title`, `content`, `images`, `tags?`, `visibility?`, `is_original?`, `schedule_at?` |
+| `publish_with_video` | Publish video post | `title`, `content`, `video` (local path), `tags?`, `visibility?`, `schedule_at?` |
+| `search_feeds` | Search posts by keyword | `keyword`, `filters?` |
+| `get_feed_detail` | Get post details + comments | `feed_id`, `xsec_token`, `load_all_comments?` |
+| `post_comment_to_feed` | Comment on a post | `feed_id`, `xsec_token`, `content` |
+| `reply_comment_in_feed` | Reply to a comment | `feed_id`, `xsec_token`, `comment_id`, `user_id`, `content` |
+| `like_feed` | Like / unlike a post | `feed_id`, `xsec_token`, `unlike?` |
+| `favorite_feed` | Favorite / unfavorite a post | `feed_id`, `xsec_token`, `unfavorite?` |
+| `list_feeds` | Get homepage feed | — |
+| `user_profile` | Get user profile + posts | `user_id`, `xsec_token` |
+| `get_self_info` | Get own account info | — |
+
+### MCP Session Protocol
+
+The MCP server uses [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport. Every request must include:
+
+```
+Content-Type: application/json
+Accept: application/json, text/event-stream
+Mcp-Session-Id: <from initialize response header>
+```
+
+Session lifecycle: `initialize` → `notifications/initialized` → `tools/call` (repeat)
+
+### Parameters Reference
+
+**`publish_content`**
+- `title` (string, required) — Max 20 Chinese characters
+- `content` (string, required) — Post body, max 1000 characters. Do NOT include hashtags here
+- `images` (string[], required) — Local file paths or HTTP URLs (at least 1)
+- `tags` (string[], optional) — Hashtags, e.g. `["旅行", "美食"]`
+- `visibility` (string, optional) — `公开可见` (default) / `仅自己可见` / `仅互关好友可见`
+- `is_original` (bool, optional) — Declare as original content
+- `schedule_at` (string, optional) — ISO 8601 datetime, e.g. `2026-03-15T10:30:00+08:00`
+
+**`publish_with_video`**
+- `video` (string, required) — Local absolute path to video file only
+
+## CDP Scripts
+
+For features the MCP server doesn't support (analytics, notifications, suggested keywords), use the Python CDP scripts:
+
+### Setup
+
+```bash
+pip install -r requirements.txt
+```
+
+### Chrome Launcher
+
+```bash
+# Start Chrome with isolated profile
+python scripts/chrome_launcher.py
+
+# Headless mode
+python scripts/chrome_launcher.py --headless
+
+# Stop Chrome
+python scripts/chrome_launcher.py --kill
+```
+
+### Available Commands
+
+```bash
+# Login (scan QR code)
+python scripts/cdp_publish.py login
+
+# Creator dashboard data → CSV
+python scripts/cdp_publish.py content-data --csv-file output.csv
+
+# Notification mentions
+python scripts/cdp_publish.py get-notification-mentions
+
+# Search with filters
+python scripts/cdp_publish.py search-feeds --keyword "AI创业" --sort-by 最新 --note-type 图文
+
+# Post detail
+python scripts/cdp_publish.py get-feed-detail --feed-id FEED_ID --xsec-token TOKEN
+
+# Comment
+python scripts/cdp_publish.py post-comment-to-feed --feed-id FEED_ID --xsec-token TOKEN --content "Great post!"
+
+# Publish via CDP (alternative to MCP)
+python scripts/publish_pipeline.py --headless \
+  --title-file title.txt --content-file content.txt \
+  --image-urls "https://example.com/img.jpg"
+```
+
+### Multi-Account
+
+```bash
+python scripts/cdp_publish.py add-account work --alias "Work Account"
+python scripts/cdp_publish.py --account work login
+python scripts/cdp_publish.py --account work content-data
+python scripts/cdp_publish.py list-accounts
+```
+
+## OpenClaw Integration
+
+Install as an OpenClaw skill:
+
+```bash
+# Copy to skills directory
+cp -r xiaohongshu ~/.openclaw/skills/xiaohongshu
+
+# Start MCP server
+cd ~/.openclaw/skills/xiaohongshu/mcp
+./start.sh
+```
+
+The `SKILL.md` file provides full instructions for OpenClaw's AI agent to use the tools automatically.
+
+## Claude Code Integration
+
+See [docs/claude-code-integration.md](docs/claude-code-integration.md) for setup instructions with Claude Code.
+
+## Tips & Known Issues
+
+- **Login verification**: `check_login_status` has a DOM detection bug — use `search_feeds` with any keyword to verify login state
+- **Post ID**: `publish_content` may return an empty PostID — this is normal. Use `search_feeds` with your username to verify
+- **Don't retry publishing** — A timeout doesn't mean failure. Always verify before retrying
+- **Proxy required**: Outside China, the MCP server needs `-rod "proxy=..."` flag
+- **Concurrent sessions**: Don't log in to the same account from both MCP and web browser simultaneously
+- **`visibility` values**: Must be in Chinese: `公开可见`, `仅自己可见`, `仅互关好友可见`
+- **`schedule_at` range**: Must be between 1 hour and 14 days from now
+
+## Platform Support
+
+| Component | macOS ARM64 | macOS x86 | Linux | Windows |
+|-----------|:-----------:|:---------:|:-----:|:-------:|
+| **xhs CLI** | ✅ | ✅ | ✅ | ✅ |
+| MCP Server | ✅ | ❌ | ❌ | ❌ |
+| CDP Scripts | ✅ | ✅ | ✅ | ✅ |
+
+**Windows / Linux / macOS x86 users**: Run `xhs init` — the CLI auto-detects missing MCP binary and switches to **CDP-only mode**. All features (publish, search, analytics, etc.) work through Chrome.
+
+```bash
+# Windows
+setup.bat                    # One-click install
+activate.bat && xhs init    # Initialize (auto CDP mode)
+
+# macOS / Linux
+bash setup.sh
+source activate.sh && xhs init
+```
+
+## Project Structure
+
+```
+xiaohongshu/
+├── README.md                          # This file
+├── SKILL.md                           # OpenClaw skill definition
+├── pyproject.toml                     # CLI package config (pip install -e .)
+├── manifest.json                      # Skill metadata
+├── LICENSE                            # MIT License
+├── requirements.txt                   # Python dependencies (legacy)
+├── .gitignore
+├── src/xhs_cli/                       # ⭐ CLI package
+│   ├── main.py                        # Unified entry point (xhs command)
+│   ├── engines/
+│   │   ├── mcp_client.py             # MCP JSON-RPC client (auto session)
+│   │   └── cdp_client.py             # CDP scripts wrapper
+│   ├── commands/
+│   │   ├── init.py                   # xhs init (guided setup)
+│   │   ├── auth.py                   # xhs login/logout/status
+│   │   ├── publish.py                # xhs publish (auto engine)
+│   │   ├── search.py                 # xhs search/detail
+│   │   ├── interact.py               # xhs like/comment/favorite
+│   │   ├── analytics.py              # xhs analytics/notifications
+│   │   ├── account.py                # xhs account management
+│   │   ├── profile.py                # xhs me/profile
+│   │   ├── server.py                 # xhs server start/stop/status
+│   │   └── config_cmd.py             # xhs config show/set/get
+│   └── utils/
+│       ├── config.py                  # ~/.xhs/config.json management
+│       └── output.py                  # Rich formatted output
+├── mcp/
+│   ├── xiaohongshu-mcp-darwin-arm64   # MCP server binary
+│   ├── xiaohongshu-login-darwin-arm64 # Login helper binary
+│   └── start.sh                       # Startup script
+├── scripts/
+│   ├── cdp_publish.py                 # Main CDP automation (2700 lines)
+│   ├── chrome_launcher.py             # Chrome lifecycle management
+│   ├── publish_pipeline.py            # High-level publish workflow
+│   ├── feed_explorer.py               # Feed browsing utilities
+│   ├── account_manager.py             # Multi-account management
+│   ├── image_downloader.py            # Image download helper
+│   └── run_lock.py                    # Process locking
+├── config/
+│   └── accounts.json.example          # Account config template
+└── docs/
+    ├── cli-guide.md                   # ⭐ CLI usage guide
+    └── claude-code-integration.md     # Claude Code setup guide
+```
+
+## Contributing
+
+Issues and PRs welcome! Areas where help is needed:
+
+- [ ] Cross-platform MCP builds (Linux, Windows, macOS x86)
+- [ ] MCP Go source code release
+- [ ] Video upload improvements
+- [ ] Rate limiting and retry logic
+- [ ] Test suite
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ by <a href="https://github.com/Youhai020616">Youhai</a></sub>
+</p>