@bsbofmusic/agent-reach-mcp 0.4.1 → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2025-02-27
+
+### Added
+
+- **Docker auto-install**: Bootstrap 时自动安装 Docker Desktop (winget/chocolatey/brew)
+- **Douyin (抖音) support**: 新增 `reach_search_douyin` 工具，解析抖音分享链接
+- **Douyin MCP container**: 自动启动 douyin-mcp-server 容器
+- **Full platform coverage**: 完整支持所有 12 个平台渠道
+
+### Changed
+
+- **ensureDockerContainers**: Docker 未安装时自动尝试安装，而非跳过
+- **reach_version**: 显示 Docker 状态和容器运行状态
+- **reach_doctor**: 输出 Docker 安装建议
+
+### Improved
+
+- **One-click deployment**: 真正实现一键部署，包括 Docker 依赖
+- **Platform parity**: MCP 版本功能完全对齐 GitHub 原版
+
+## [1.1.0] - 2025-02-27
+
+### Added
+
+- **Auto-install npm packages**: Bootstrap 时自动安装 bird、mcporter
+- **Docker container management**: 自动检测并启动 xiaohongshu-mcp 容器
+- **gh CLI auto-install**: Windows (winget) 和 macOS (brew) 自动安装 GitHub CLI
+- **npx fallback**: 使用 `npx -y` 运行 bird/mcporter，无需全局 PATH 配置
+
+### Changed
+
+- **reach_search_twitter**: 使用 `npx @steipete/bird` 替代直接调用
+- **reach_search_xhs/web**: 使用 `npx mcporter` 替代直接调用
+- **reach_version**: 显示所有依赖安装状态
+- **detectEnvironment**: 使用 npx 检测 bird/mcporter
+
+### Fixed
+
+- **Windows PATH issue**: npm 全局包不在 PATH 时仍可通过 npx 运行
+- **Bootstrap timing**: 正确初始化所有依赖
+
+## [1.0.0] - 2025-02-27
+
+### Added
+
+- **Bootstrap Ensure**: MCP 启动时自动检测环境、安装依赖、执行 smoke test
+- **Concurrent Protection**: 使用 lockfile 防止并发 ensure 踩踏
+- **Structured Logging**: 步骤、耗时、stdout/stderr、错误分类记录
+- **nextSteps**: 所有失败场景输出可执行修复建议
+- **Environment Detection**: 自动检测 OS、Python、Node.js、网络、磁盘空间
+- **Graceful Degradation**: Bootstrap 失败时 MCP 仍可启动，工具返回明确错误
+
+### Changed
+
+- **reach_doctor**: 增加 nextSteps 修复建议
+- **reach_version**: 增加 bootstrap 状态显示
+- **reach_search_***: 增加依赖预检查，缺失时返回 nextSteps
+- **Error Output**: 所有错误包含结构化信息
+
+### Improved
+
+- Windows 兼容性：spawn 命令使用 shell 模式
+- 日志输出：支持 LOG_LEVEL 环境变量控制
+- 原子更新：runtime 目录结构支持未来实现 atomic 策略
+
+## [0.4.1] - 2025-02-26
+
+### Added
+
+- Initial MCP wrapper for Agent-Reach
+- 5 core tools: ensure, doctor, exec, list_commands, version
+- Auto-update mechanism
+- Platform channel support: YouTube, Twitter, Reddit, GitHub, Bilibili, XiaoHongShu
+
+---
+
+## Roadmap
+
+- [ ] Atomic update strategy (runtime_staging / runtime_active)
+- [ ] Docker fallback for complex dependencies
+- [ ] Proxy auto-detection
+- [ ] Cache invalidation on upgrade
+- [ ] Telemetry (opt-in)

package/README.md

@@ -1,117 +1,156 @@
 # Agent-Reach MCP
 
-> ✅ 导入 MCP 即用 | ✅ 完整能力（exec） | ✅ 自发现（list） | ✅ 自动更新（latest） | ✅ 可诊断（doctor）
+> ✅ One-click enable | ✅ Full capability (exec) | ✅ Self-discovery (list) | ✅ Auto-update | ✅ Diagnosable (doctor) | ✅ Bootstrap self-healing
 
-MCP (stdio) server that provides full access to [Agent-Reach](https://github.com/Panniantong/Agent-Reach) for OpenCode / CC-Switch.
+MCP (stdio) server that provides full access to [Agent-Reach](https://github.com/Panniantong/Agent-Reach) for OpenCode / Claude Code / Cursor.
 
-## 一键启用
+---
+
+## Wrapper Notice
+
+This project is an MCP wrapper for **Agent-Reach**, enabling its functionality through the MCP protocol.
+
+- **Upstream Project**: [Agent-Reach](https://github.com/Panniantong/Agent-Reach)
+- **This is NOT an official release** of Agent-Reach
+- Upstream project name, trademark, and copyright belong to their respective owners
+- Upstream project is licensed under MIT; see [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
+
+---
+
+## Quick Start
+
+### One-Click Enable (Recommended)
+
+```json
+{
+  "command": ["node", "FULL_PATH_TO_INDEX_JS"],
+  "type": "stdio"
+}
+```
+
+Or via npx (may have Windows JScript issues):
 
 ```json
 {
-  "command": "npx",
-  "args": ["-y", "@bsbofmusic/agent-reach-mcp@latest"],
+  "command": ["npx", "-y", "@bsbofmusic/agent-reach-mcp@latest"],
   "type": "stdio"
 }
 ```
 
-## 是什么
+### What happens on enable:
+
+1. 🔍 Environment detection (OS, Python, Node.js, network)
+2. 📦 Auto-install Python venv
+3. 🔄 Auto-install/upgrade Agent-Reach to latest
+4. 🐳 Auto-install Docker Desktop (Windows: winget/choco, macOS: brew)
+5. ✅ Smoke test verification
+
+---
+
+## What is Agent-Reach?
+
+Agent-Reach gives your AI Agent "eyes to see the entire internet". Read and search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
 
-Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter、Reddit、YouTube、GitHub、Bilibili、小红书 — 一个 CLI，零 API 费用。
+| Platform | Feature | Status |
+|----------|---------|--------|
+| 🌐 Web Pages | Jina Reader (any URL) | ✅ Ready |
+| 📺 YouTube | Transcript + video search | ✅ Ready |
+| 📡 RSS | Read any RSS/Atom feed | ✅ Ready |
+| 🐦 Twitter/X | Read tweets, search | ⚙️ Needs bird CLI |
+| 📖 Reddit | Search, read posts/comments | ⚙️ Needs proxy |
+| 📦 GitHub | Read repos, search | ⚙️ Needs gh CLI |
+| 📺 Bilibili | Transcript + search | ⚙️ Needs proxy |
+| 📕 XiaoHongShu | Search, read notes | ⚙️ Needs Docker |
+| 🎵 Douyin | Parse video, get download URL | ⚙️ Needs Docker |
+| 🔍 Web Search | Exa AI semantic search | ⚙️ Needs mcporter |
 
-| 平台 | 功能 |
-|------|------|
-| 🌐 网页 | Jina Reader 读取任意网页 |
-| 📺 YouTube | 字幕提取 + 视频搜索 |
-| 🐦 Twitter/X | 读取推文、搜索 |
-| 📖 Reddit | 搜索、读取帖子评论 |
-| 📦 GitHub | 读取公开仓库、搜索 |
-| 📺 Bilibili | 字幕提取 + 搜索 |
-| 📕 小红书 | 搜索、阅读 |
-| 🔍 全网搜索 | Exa AI 语义搜索 |
+---
 
-## 5 个核心工具（必须实现）
+## 5 Core Tools (Required)
 
-| 工具 | 说明 |
-|------|------|
-| `reach_ensure` | ✅ 准备环境 + 升级到最新 |
-| `reach_doctor` | ✅ 诊断所有平台渠道状态 |
-| `reach_exec` | ✅ 万能入口 - 完美复刻所有功能 |
-| `reach_list_commands` | ✅ 能力自发现 - 列出所有子命令 |
-| `reach_version` | ✅ 输出版本信息 |
+| Tool | Description |
+|------|-------------|
+| `reach_ensure` | ✅ Full self-healing: reinstall/upgrade + auto-install deps |
+| `reach_doctor` | ✅ Diagnose all platform channels + output nextSteps |
+| `reach_exec` | ✅ Universal entry - perfect replica of all features |
+| `reach_list_commands` | ✅ Self-discovery - list all subcommands |
+| `reach_version` | ✅ Version info + bootstrap status |
 
-## 完整工具列表
+---
 
-### 核心
+## Complete Tool List
 
-| 工具 | 说明 |
-|------|------|
-| `reach_ensure` | 确保 venv 存在并升级到最新 Agent-Reach |
-| `reach_doctor` | 诊断所有平台渠道状态 |
-| `reach_version` | 显示 MCP + Agent-Reach 版本 |
-| `reach_check_update` | 检查 GitHub 是否有新版本 |
-| `reach_watch` | 快速健康检查（适合定时任务） |
-| `reach_list_commands` | 列出所有可用子命令 |
+### Core
 
-### 安装与配置
+| Tool | Description |
+|------|-------------|
+| `reach_ensure` | Ensure venv exists, upgrade to latest Agent-Reach |
+| `reach_doctor` | Diagnose all platform channels, output nextSteps |
+| `reach_version` | Show MCP + Agent-Reach version + bootstrap status |
+| `reach_check_update` | Check for new versions on GitHub |
+| `reach_watch` | Quick health check (for cron tasks) |
+| `reach_list_commands` | List all available subcommands |
 
-| 工具 | 说明 |
-|------|------|
-| `reach_install` | 安装系统依赖（gh CLI, Node.js, bird, mcporter） |
-| `reach_configure` | 设置配置（proxy, token, cookies） |
-| `reach_setup` | 交互式配置向导 |
+### Install & Configure
 
-### 读取与搜索
+| Tool | Description |
+|------|-------------|
+| `reach_install` | Install system dependencies (gh CLI, bird, mcporter) |
+| `reach_configure` | Set config (proxy, token, cookies) |
+| `reach_setup` | Interactive configuration wizard |
 
-| 工具 | 说明 |
-|------|------|
-| `reach_read` | 读取任意 URL |
-| `reach_search_twitter` | 搜索 Twitter |
-| `reach_search_xhs` | 搜索小红书 |
-| `reach_search_web` | 全网搜索（Exa） |
-| `reach_search_github` | 搜索 GitHub |
+### Read & Search
 
-### 高级
+| Tool | Description |
+|------|-------------|
+| `reach_read` | Read any URL (Jina Reader) |
+| `reach_search_twitter` | Search Twitter (needs bird CLI) |
+| `reach_search_xhs` | Search XiaoHongShu (needs mcporter) |
+| `reach_search_douyin` | Parse Douyin video (needs mcporter) |
+| `reach_search_web` | Web search (Exa) |
+| `reach_search_github` | Search GitHub (needs gh CLI) |
 
-| 工具 | 说明 |
-|------|------|
-| `reach_exec` | 🔧 万能入口 - 执行任意子命令 |
+### Advanced
 
-## 使用示例
+| Tool | Description |
+|------|-------------|
+| `reach_exec` | 🔧 Universal entry - execute any subcommand |
 
-### 首次安装
+---
+
+## Usage Examples
+
+### First Use (Auto Bootstrap)
 
 ```json
 {
-  "name": "reach_install",
-  "arguments": { "env": "auto" }
+  "name": "reach_ensure"
 }
 ```
 
-### 配置 Twitter Cookie
+**Example Output**:
+```
+# reach_ensure Result
 
-```json
-{
-  "name": "reach_configure",
-  "arguments": {
-    "key": "twitter-cookies",
-    "value": "auth_token=xxx; ct0=yyy"
-  }
-}
+Status: ✅ Success
+
+## Execution Log
+- venv_check: OK (0ms)
+- upgrade_pip: OK (2341ms)
+- install_agent_reach: OK (5678ms)
+
+Version: 1.2.0
 ```
 
-### 配置代理
+### Diagnosis
 
 ```json
 {
-  "name": "reach_configure",
-  "arguments": {
-    "key": "proxy",
-    "value": "http://user:pass@ip:port"
-  }
+  "name": "reach_doctor"
 }
 ```
 
-### 读取网页
+### Read Web Page
 
 ```json
 {
@@ -120,7 +159,7 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
 
-### 搜索 Twitter
+### Search Twitter
 
 ```json
 {
@@ -129,105 +168,242 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
 
-### 搜索 GitHub
+### Universal Entry
 
 ```json
 {
-  "name": "reach_search_github",
-  "arguments": { "query": "LLM framework", "limit": 10 }
+  "name": "reach_exec",
+  "arguments": {
+    "subcommand": "doctor",
+    "skipUpdate": false
+  }
 }
 ```
 
-### 使用万能入口
+### Self-Discovery
 
 ```json
 {
-  "name": "reach_exec",
-  "arguments": {
-    "subcommand": "doctor"
-  }
+  "name": "reach_list_commands"
 }
 ```
 
-## 自动更新策略
+---
+
+## Auto-Update Strategy
 
-每次工具调用前自动执行：
+**Default**: Lightweight `ensureLatest()` before each tool call
 
-1. 创建/复用 Python venv
-2. 执行 `pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip`
-3. 然后运行目标命令
+### Environment Variables
 
-**版本信息：** `reach_version` 显示当前 MCP 版本、Agent-Reach 版本、更新时间。
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ALWAYS_LATEST` | `1` | Auto-update enabled |
+| `UPDATE_STRATEGY` | `simple` | Update strategy (simple/atomic) |
+| `NETWORK_REQUIRED` | `1` | Network required |
+| `AUTO_INSTALL_DEPS` | `1` | Auto-install dependencies |
+| `AUTO_START_DOCKER` | `1` | Auto-start Docker containers |
+| `CACHE_DIR` | System cache | Cache location |
+| `RUNTIME_DIR` | System cache/runtime | Runtime directory |
+| `LOG_LEVEL` | `info` | Log level (error/info/debug) |
 
-## 环境要求
+### Update Flow
 
-- Node.js >= 18
-- Python 3.10+（在 PATH 中）
-- 能访问 GitHub
+1. Check if venv exists
+2. Check bootstrap timestamp
+3. Run `pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip`
+4. Run smoke test
+5. Record bootstrap timestamp
 
-### Venv 位置
+**Failure handling**: Update failure won't break existing version, returns nextSteps for fix.
 
-- Windows: `%LOCALAPPDATA%\agent-reach-mcp\runtime\venv`
-- macOS: `~/Library/Caches/agent-reach-mcp/runtime/venv`
-- Linux: `~/.cache/agent-reach-mcp/runtime/venv`
+---
 
-## 平台要求
+## Environment Requirements
 
-| 平台 | 要求 |
-|------|------|
-| Twitter | bird CLI + twitter-cookies |
-| 小红书 | mcporter + docker xiaohongshu-mcp |
-| Reddit | 代理（服务器 IP 被封） |
-| Bilibili | 代理（服务器 IP 被封） |
-| 全网搜索 | 配置 Exa MCP |
-| GitHub | gh CLI（可选，提高速率限制） |
+### Auto-Detection on Start
 
-## 推荐工作流
+- OS / CPU architecture
+- Python version (requires 3.10+)
+- Node.js version
+- Network availability
+- Disk space
 
-1. **首次安装**: `reach_install` 安装依赖
-2. **配置**: `reach_configure` 配置 Twitter cookies、代理等
-3. **诊断**: `reach_doctor` 检查渠道状态
-4. **发现**: `reach_list_commands` 查看可用命令
-5. **使用**: 使用搜索/读取工具或 `reach_exec`
+### Runtime Directories
 
-## 验证计划
+| Platform | Directory |
+|----------|-----------|
+| Windows | `%LOCALAPPDATA%\agent-reach-mcp\` |
+| macOS | `~/Library/Caches/agent-reach-mcp/` |
+| Linux | `~/.cache/agent-reach-mcp/` |
 
-### A. 一键部署验证
+---
 
-- [ ] 清空本地缓存（或换一台机器）
-- [ ] 仅通过 CC-Switch 启用 MCP
-- [ ] 重启 OpenCode
-- [ ] 直接调用 `reach_ensure` 成功
-- [ ] 不需要手动安装任何依赖
+## Recommended Workflow
 
-### B. 完美复刻验证
+1. **Enable MCP** → Auto bootstrap
+2. **Diagnose**: `reach_doctor` to see channel status
+3. **Discover**: `reach_list_commands` to see available commands
+4. **Configure**: `reach_configure` for cookies/proxy
+5. **Use**: Search/read tools or `reach_exec`
 
-- [ ] `reach_exec` 能执行至少 5 个核心功能
-- [ ] `reach_list_commands` 输出与原工具 `--help` 一致
-- [ ] 新增功能无需改 MCP 即可通过 exec 使用
+---
 
-### C. 稳定健全验证
+## Verification Matrix
 
-- [ ] `reach_doctor` 能定位常见问题
-- [ ] 调用失败返回清晰错误
-- [ ] 超时机制有效
+### A. One-Click Deployment ✅
+
+**Target**: Just enable MCP, auto-collect and install dependencies
+
+**Steps**:
+```bash
+# 1. Clear cache
+rm -rf ~/Library/Caches/agent-reach-mcp  # macOS
+rd /s /q %LOCALAPPDATA%\agent-reach-mcp  # Windows
 
-### D. 自动更新验证
+# 2. Restart MCP
 
-- [ ] 每次调用前执行 ensureLatest
-- [ ] `reach_version` 能反映 latest 状态
+# 3. Call version check
+reach_version
+```
+
+**Expected Output (Success)**:
+```
+=== Agent-Reach MCP Version Info ===
+
+MCP Version: 1.2.0
+Agent-Reach Version: 1.2.0
+Bootstrap Status: ✅ OK
+Update Strategy: simple (alwaysLatest: true)
+Runtime Dir: /Users/xxx/Library/Caches/agent-reach-mcp/runtime
+```
 
-## 本地开发
+### B. Perfect Replica Verification ✅
+
+**Target**: No capability loss after wrapping
+
+**Verification Commands**:
+```json
+{"name": "reach_exec", "arguments": {"subcommand": "version"}}
+{"name": "reach_exec", "arguments": {"subcommand": "doctor"}}
+{"name": "reach_exec", "arguments": {"subcommand": "check-update", "skipUpdate": true}}
+{"name": "reach_exec", "arguments": {"subcommand": "watch"}}
+{"name": "reach_exec", "arguments": {"subcommand": "setup"}}
+```
+
+**Criteria**: All commands execute successfully, output matches original CLI
+
+### C. Stability Verification ✅
+
+**Target**: Self-check / Self-healing / Clear errors / Observable logs
+
+**Steps**:
+1. Call `reach_doctor` → Check output includes nextSteps
+2. Break venv → Call `reach_ensure` → Confirm fix
+3. Call non-existent command → Check error output
+
+### D. Auto-Update Verification ✅
+
+**Target**: Upgrade to latest on each call
+
+**Steps**:
+1. Call `reach_version` to record version
+2. Wait for upstream update
+3. Call any tool again
+4. Check if `reach_version` updated
+
+### E. Deploy-Ready Verification ✅
+
+**Target**: Auto-recover after Agent restart
+
+**Steps**:
+1. Enable MCP
+2. Restart Agent
+3. Call any tool
+4. Confirm no manual action needed
+
+### F. Failure Scenarios
+
+| Scenario | Trigger | Expected nextSteps |
+|----------|---------|-------------------|
+| No network | Close network | Check network connection |
+| No Python | Remove from PATH | Install Python 3.10+ |
+| venv corrupted | Delete venv dir | reach_ensure will rebuild |
+| bird not installed | reach_search_twitter | npm install -g @steipete/bird |
+
+---
+
+## Troubleshooting
+
+### Python Missing
+
+**Cause**: Python not installed
+
+**Fix**:
+- Install Python 3.10+: https://www.python.org/downloads/
+- Ensure "Add Python to PATH" is checked during installation
+
+### Network Error
+
+**Cause**: Cannot access GitHub
+
+**Fix**:
+- Check network connection
+- Configure proxy: `HTTP_PROXY`, `HTTPS_PROXY`
+- Or set `NETWORK_REQUIRED=0`
+
+### venv Failed
+
+**Cause**: Python venv module not available
+
+**Fix**:
+- Ensure full Python installed (not minimal)
+- Linux: `sudo apt install python3-venv`
+
+### Bootstrap Incomplete
+
+**Error**:
+```
+⚠️ MCP not fully ready
+
+Bootstrap failed, some features may be unavailable.
+```
+
+**Fix**: Call `reach_ensure` to repair
+
+---
+
+## Compliance
+
+### License
+
+| Project | License |
+|---------|---------|
+| This project (agent-reach-mcp) | MIT License |
+| Upstream Agent-Reach | MIT License |
+
+### Third-Party Notices
+
+See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
+
+---
+
+## Local Development
 
 ```bash
 npm install
 node index.js
 ```
 
+---
+
 ## License
 
 MIT
 
+---
+
 ## Links
 
 - [Agent-Reach GitHub](https://github.com/Panniantong/Agent-Reach)
+- [MCP Protocol](https://modelcontextprotocol.io/)