@bsbofmusic/agent-reach-mcp 0.4.1 → 1.2.0

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,8 +1,21 @@
 # Agent-Reach MCP
 
-> ✅ 导入 MCP 即用 | ✅ 完整能力（exec） | ✅ 自发现（list） | ✅ 自动更新（latest） | ✅ 可诊断（doctor）
+> ✅ 导入 MCP 即用 | ✅ 完整能力（exec） | ✅ 自发现（list） | ✅ 自动更新（latest） | ✅ 可诊断（doctor）| ✅ 启动自愈（bootstrap）
 
-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
+
+本项目是对上游项目 **Agent-Reach** 的 MCP 封装（wrapper），用于通过 MCP 接口调用其功能。
+
+- **上游项目地址**: https://github.com/Panniantong/Agent-Reach
+- **本项目不是上游项目的官方发布**
+- 上游项目的名称、商标与版权归其各自权利人所有
+- 上游项目按其许可证条款（MIT）授权使用；本项目已在 THIRD_PARTY_NOTICES.md 中包含上游许可证声明。
+
+---
 
 ## 一键启用
 
@@ -14,30 +27,43 @@ MCP (stdio) server that provides full access to [Agent-Reach](https://github.com
 }
 ```
 
+**启用后自动完成**:
+1. 🔍 环境检测（OS、Python、Node.js、网络）
+2. 📦 自动安装 Python venv
+3. 🔄 自动安装/升级 Agent-Reach 到最新版
+4. ✅ Smoke test 验证可用性
+
+---
+
 ## 是什么
 
 Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter、Reddit、YouTube、GitHub、Bilibili、小红书 — 一个 CLI，零 API 费用。
 
-| 平台 | 功能 |
-|------|------|
-| 🌐 网页 | Jina Reader 读取任意网页 |
-| 📺 YouTube | 字幕提取 + 视频搜索 |
-| 🐦 Twitter/X | 读取推文、搜索 |
-| 📖 Reddit | 搜索、读取帖子评论 |
-| 📦 GitHub | 读取公开仓库、搜索 |
-| 📺 Bilibili | 字幕提取 + 搜索 |
-| 📕 小红书 | 搜索、阅读 |
-| 🔍 全网搜索 | Exa AI 语义搜索 |
+| 平台 | 功能 | 状态 |
+|------|------|------|
+| 🌐 网页 | Jina Reader 读取任意网页 | ✅ 开箱即用 |
+| 📺 YouTube | 字幕提取 + 视频搜索 | ✅ 开箱即用 |
+| 📡 RSS | 读取任意 RSS/Atom 源 | ✅ 开箱即用 |
+| 🐦 Twitter/X | 读取推文、搜索 | ⚙️ 需配置 bird CLI |
+| 📖 Reddit | 搜索、读取帖子评论 | ⚙️ 需配置代理 |
+| 📦 GitHub | 读取公开仓库、搜索 | ⚙️ 需安装 gh CLI |
+| 📺 Bilibili | 字幕提取 + 搜索 | ⚙️ 需配置代理 |
+| 📕 小红书 | 搜索、阅读 | ⚙️ 需配置 mcporter |
+| 🔍 全网搜索 | Exa AI 语义搜索 | ⚙️ 需配置 mcporter |
+
+---
 
 ## 5 个核心工具（必须实现）
 
 | 工具 | 说明 |
 |------|------|
-| `reach_ensure` | ✅ 准备环境 + 升级到最新 |
-| `reach_doctor` | ✅ 诊断所有平台渠道状态 |
+| `reach_ensure` | ✅ 准备环境 + 升级到最新（幂等）|
+| `reach_doctor` | ✅ 诊断所有平台渠道状态 + nextSteps |
 | `reach_exec` | ✅ 万能入口 - 完美复刻所有功能 |
 | `reach_list_commands` | ✅ 能力自发现 - 列出所有子命令 |
-| `reach_version` | ✅ 输出版本信息 |
+| `reach_version` | ✅ 输出版本信息 + bootstrap 状态 |
+
+---
 
 ## 完整工具列表
 
@@ -46,29 +72,29 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 | 工具 | 说明 |
 |------|------|
 | `reach_ensure` | 确保 venv 存在并升级到最新 Agent-Reach |
-| `reach_doctor` | 诊断所有平台渠道状态 |
-| `reach_version` | 显示 MCP + Agent-Reach 版本 |
+| `reach_doctor` | 诊断所有平台渠道状态，输出 nextSteps |
+| `reach_version` | 显示 MCP + Agent-Reach 版本 + bootstrap 状态 |
 | `reach_check_update` | 检查 GitHub 是否有新版本 |
-| `reach_watch` | 快速健康检查（适合定时任务） |
+| `reach_watch` | 快速健康检查（适合定时任务）|
 | `reach_list_commands` | 列出所有可用子命令 |
 
 ### 安装与配置
 
 | 工具 | 说明 |
 |------|------|
-| `reach_install` | 安装系统依赖（gh CLI, Node.js, bird, mcporter） |
-| `reach_configure` | 设置配置（proxy, token, cookies） |
+| `reach_install` | 安装系统依赖（gh CLI, Node.js, bird, mcporter）|
+| `reach_configure` | 设置配置（proxy, token, cookies）|
 | `reach_setup` | 交互式配置向导 |
 
 ### 读取与搜索
 
 | 工具 | 说明 |
 |------|------|
-| `reach_read` | 读取任意 URL |
-| `reach_search_twitter` | 搜索 Twitter |
-| `reach_search_xhs` | 搜索小红书 |
-| `reach_search_web` | 全网搜索（Exa） |
-| `reach_search_github` | 搜索 GitHub |
+| `reach_read` | 读取任意 URL（Jina Reader）|
+| `reach_search_twitter` | 搜索 Twitter（需 bird CLI）|
+| `reach_search_xhs` | 搜索小红书（需 mcporter）|
+| `reach_search_web` | 全网搜索（Exa）|
+| `reach_search_github` | 搜索 GitHub（需 gh CLI）|
 
 ### 高级
 
@@ -76,41 +102,57 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 |------|------|
 | `reach_exec` | 🔧 万能入口 - 执行任意子命令 |
 
+---
+
 ## 使用示例
 
-### 首次安装
+### 首次使用（自动完成）
+
+启用 MCP 后，会自动执行 bootstrap 确保。也可手动触发：
 
 ```json
 {
-  "name": "reach_install",
-  "arguments": { "env": "auto" }
+  "name": "reach_ensure"
 }
 ```
 
-### 配置 Twitter Cookie
+**输出示例**:
+```
+# reach_ensure 结果
 
-```json
-{
-  "name": "reach_configure",
-  "arguments": {
-    "key": "twitter-cookies",
-    "value": "auth_token=xxx; ct0=yyy"
-  }
-}
+状态: ✅ 成功
+
+## 执行日志
+- venv_check: OK (0ms)
+- upgrade_pip: OK (2341ms)
+- install_agent_reach: OK (5678ms)
+
+版本: 1.2.0
 ```
 
-### 配置代理
+### 诊断
 
 ```json
 {
-  "name": "reach_configure",
-  "arguments": {
-    "key": "proxy",
-    "value": "http://user:pass@ip:port"
-  }
+  "name": "reach_doctor"
 }
 ```
 
+**输出示例**:
+```
+# reach_doctor 诊断报告
+
+👁️ Agent Reach 状态
+========================================
+✅ YouTube 视频和字幕 — 可提取视频信息和字幕
+✅ RSS/Atom 订阅源 — 可读取 RSS/Atom 源
+❌ Twitter/X 推文 — bird CLI 未安装
+
+## Next Steps
+- Install bird CLI: npm install -g @steipete/bird
+- Configure cookies: reach_configure with twitter-cookies
+```
+
 ### 读取网页
 
 ```json
@@ -129,93 +171,288 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
 
-### 搜索 GitHub
+**未安装 bird CLI 时的输出**:
+```
+❌ bird CLI 未安装
+
+## Next Steps
+- Install: npm install -g @steipete/bird
+- Configure cookies: reach_configure with twitter-cookies
+- Or use reach_search_web for Exa search instead
+```
+
+### 使用万能入口
 
 ```json
 {
-  "name": "reach_search_github",
-  "arguments": { "query": "LLM framework", "limit": 10 }
+  "name": "reach_exec",
+  "arguments": {
+    "subcommand": "doctor",
+    "skipUpdate": false
+  }
 }
 ```
 
-### 使用万能入口
+### 能力自发现
 
 ```json
 {
-  "name": "reach_exec",
+  "name": "reach_list_commands"
+}
+```
+
+### 配置 Twitter Cookie
+
+```json
+{
+  "name": "reach_configure",
+  "arguments": {
+    "key": "twitter-cookies",
+    "value": "auth_token=xxx; ct0=yyy"
+  }
+}
+```
+
+### 配置代理
+
+```json
+{
+  "name": "reach_configure",
   "arguments": {
-    "subcommand": "doctor"
+    "key": "proxy",
+    "value": "http://user:pass@ip:port"
   }
 }
 ```
 
+---
+
 ## 自动更新策略
 
-每次工具调用前自动执行：
+**默认**: 每次工具调用前执行轻量 `ensureLatest()`
+
+### 支持的环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `ALWAYS_LATEST` | `1` | 是否自动更新 |
+| `UPDATE_STRATEGY` | `simple` | 更新策略（simple/atomic）|
+| `NETWORK_REQUIRED` | `1` | 是否需要网络 |
+| `CACHE_DIR` | 系统缓存目录 | 缓存位置 |
+| `RUNTIME_DIR` | 系统缓存目录/runtime | 运行时目录 |
+| `LOG_LEVEL` | `info` | 日志级别（error/info/debug）|
 
-1. 创建/复用 Python venv
-2. 执行 `pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip`
-3. 然后运行目标命令
+### 更新流程
 
-**版本信息：** `reach_version` 显示当前 MCP 版本、Agent-Reach 版本、更新时间。
+1. 检查 venv 是否存在
+2. 检查 bootstrap 时间戳
+3. 执行 `pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip`
+4. 运行 smoke test 验证
+5. 记录 bootstrap 时间戳
+
+**失败处理**: 更新失败不会破坏现有可用版本，返回 nextSteps 修复建议。
+
+---
 
 ## 环境要求
 
-- Node.js >= 18
-- Python 3.10+（在 PATH 中）
-- 能访问 GitHub
+### 启动时自动检测
 
-### Venv 位置
+- OS / CPU 架构
+- Python 版本（需要 3.10+）
+- Node.js 版本
+- 网络可达性
+- 磁盘空间
 
-- Windows: `%LOCALAPPDATA%\agent-reach-mcp\runtime\venv`
-- macOS: `~/Library/Caches/agent-reach-mcp/runtime/venv`
-- Linux: `~/.cache/agent-reach-mcp/runtime/venv`
+### 运行时目录
+
+| 平台 | 目录 |
+|------|------|
+| Windows | `%LOCALAPPDATA%\agent-reach-mcp\` |
+| macOS | `~/Library/Caches/agent-reach-mcp/` |
+| Linux | `~/.cache/agent-reach-mcp/` |
 
-## 平台要求
+### 平台特定要求
 
 | 平台 | 要求 |
 |------|------|
 | Twitter | bird CLI + twitter-cookies |
-| 小红书 | mcporter + docker xiaohongshu-mcp |
-| Reddit | 代理（服务器 IP 被封） |
-| Bilibili | 代理（服务器 IP 被封） |
-| 全网搜索 | 配置 Exa MCP |
-| GitHub | gh CLI（可选，提高速率限制） |
+| 小红书 | mcporter + xiaohongshu-mcp Docker |
+| Reddit | 代理（服务器 IP 被封）|
+| Bilibili | 代理（服务器 IP 被封）|
+| GitHub | gh CLI（提高速率限制）|
+| 全网搜索 | mcporter + Exa MCP |
+
+---
 
 ## 推荐工作流
 
-1. **首次安装**: `reach_install` 安装依赖
-2. **配置**: `reach_configure` 配置 Twitter cookies、代理等
-3. **诊断**: `reach_doctor` 检查渠道状态
-4. **发现**: `reach_list_commands` 查看可用命令
-5. **使用**: 使用搜索/读取工具或 `reach_exec`
+1. **启用 MCP** → 自动 bootstrap
+2. **诊断**: `reach_doctor` 查看渠道状态
+3. **发现**: `reach_list_commands` 查看可用命令
+4. **配置**: `reach_configure` 配置 cookies/代理
+5. **使用**: 搜索/读取工具 或 `reach_exec`
+
+---
+
+## 验证矩阵
+
+### A. 一键部署验证 ✅
 
-## 验证计划
+**目标**: 只需启用 MCP，全自动收集并安装依赖
 
-### A. 一键部署验证
+**验证步骤**:
+```bash
+# 1. 清空缓存
+rm -rf ~/Library/Caches/agent-reach-mcp  # macOS
+rd /s /q %LOCALAPPDATA%\agent-reach-mcp  # Windows
 
-- [ ] 清空本地缓存（或换一台机器）
-- [ ] 仅通过 CC-Switch 启用 MCP
-- [ ] 重启 OpenCode
-- [ ] 直接调用 `reach_ensure` 成功
-- [ ] 不需要手动安装任何依赖
+# 2. 重启 MCP
 
-### B. 完美复刻验证
+# 3. 调用版本检查
+reach_version
+```
 
-- [ ] `reach_exec` 能执行至少 5 个核心功能
-- [ ] `reach_list_commands` 输出与原工具 `--help` 一致
-- [ ] 新增功能无需改 MCP 即可通过 exec 使用
+**预期输出（成功）**:
+```
+=== Agent-Reach MCP Version Info ===
 
-### C. 稳定健全验证
+MCP Version: 1.0.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
+```
 
-- [ ] `reach_doctor` 能定位常见问题
-- [ ] 调用失败返回清晰错误
-- [ ] 超时机制有效
+**预期输出（失败 - 无 Python）**:
+```
+⚠️ MCP 未完全就绪
+
+Bootstrap 失败，部分功能可能不可用。
+错误类型: python_missing
+
+Next Steps:
+- Install Python 3.10+ from https://www.python.org/downloads/
+- Ensure Python is added to PATH during installation
+```
+
+### B. 完美复刻验证 ✅
+
+**目标**: 封装后能力不缩水，新增命令自动支持
+
+**验证命令**:
+```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"}}
+```
+
+**判定标准**: 所有命令执行成功，输出与原 CLI 一致
+
+### C. 稳定健全验证 ✅
+
+**目标**: 自检 / 自愈 / 清晰错误 / 可观测日志
+
+**验证步骤**:
+1. 调用 `reach_doctor` → 检查输出包含 nextSteps
+2. 破坏 venv → 调用 `reach_ensure` → 确认修复
+3. 调用不存在的命令 → 检查错误输出
+
+**预期输出（doctor）**:
+```
+# reach_doctor 诊断报告
+...
+## Next Steps
+- Install bird CLI: npm install -g @steipete/bird
+```
 
-### D. 自动更新验证
+### D. 自动更新验证 ✅
 
-- [ ] 每次调用前执行 ensureLatest
-- [ ] `reach_version` 能反映 latest 状态
+**目标**: 每次调用前升级到最新版本
+
+**验证步骤**:
+1. 调用 `reach_version` 记录版本
+2. 等待上游更新
+3. 再次调用任意工具
+4. 检查 `reach_version` 是否更新
+
+### E. 部署即用验证 ✅
+
+**目标**: 重启 Agent 后自动恢复
+
+**验证步骤**:
+1. 启用 MCP
+2. 重启 Agent
+3. 调用任意工具
+4. 确认无需手动操作
+
+### F. 失败场景验证
+
+| 场景 | 触发方式 | 预期 nextSteps |
+|------|---------|----------------|
+| 断网 | 关闭网络 | 检查网络连接 |
+| 无 Python | 移除 PATH | 安装 Python 3.10+ |
+| venv 损坏 | 删除 venv 目录 | reach_ensure 会自动重建 |
+| bird 未安装 | reach_search_twitter | npm install -g @steipete/bird |
+
+---
+
+## 常见错误与排障
+
+### `python_missing`
+
+**原因**: 系统未安装 Python
+
+**修复**:
+- 安装 Python 3.10+: https://www.python.org/downloads/
+- 确保勾选 "Add Python to PATH"
+
+### `network_error`
+
+**原因**: 无法访问 GitHub
+
+**修复**:
+- 检查网络连接
+- 配置代理: `HTTP_PROXY`, `HTTPS_PROXY`
+- 或设置 `NETWORK_REQUIRED=0`
+
+### `venv_failed`
+
+**原因**: Python venv 模块不可用
+
+**修复**:
+- 确保安装了完整的 Python（非精简版）
+- Linux: `sudo apt install python3-venv`
+
+### Bootstrap 未完成的工具调用
+
+**错误信息**:
+```
+⚠️ MCP 未完全就绪
+
+Bootstrap 失败，部分功能可能不可用。
+```
+
+**修复**: 调用 `reach_ensure` 进行修复
+
+---
+
+## 合规声明
+
+### 许可证
+
+| 项目 | 许可证 |
+|------|--------|
+| 本项目 (agent-reach-mcp) | MIT License |
+| 上游 Agent-Reach | MIT License |
+
+### 第三方声明
+
+详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
+
+---
 
 ## 本地开发
 
@@ -224,10 +461,16 @@ npm install
 node index.js
 ```
 
+---
+
 ## License
 
 MIT
 
+---
+
 ## Links
 
 - [Agent-Reach GitHub](https://github.com/Panniantong/Agent-Reach)
+- [Agent-Reach 文档](https://github.com/Panniantong/Agent-Reach#readme)
+- [MCP 协议](https://modelcontextprotocol.io/)