npm - @bsbofmusic/agent-reach-mcp - Versions diffs - 1.2.0 → 1.2.1 - Mend

@bsbofmusic/agent-reach-mcp 1.2.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +197 -264
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,114 +1,126 @@
 # Agent-Reach MCP
-> ✅ 导入 MCP 即用 | ✅ 完整能力（exec） | ✅ 自发现（list） | ✅ 自动更新（latest） | ✅ 可诊断（doctor）| ✅ 启动自愈（bootstrap）
+> ✅ 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 / Claude Code / Cursor.
 ---
-## 封装声明 / Wrapper Notice
+## Wrapper Notice
-本项目是对上游项目 **Agent-Reach** 的 MCP 封装（wrapper），用于通过 MCP 接口调用其功能。
+This project is an MCP wrapper for **Agent-Reach**, enabling its functionality through the MCP protocol.
-- **上游项目地址**: https://github.com/Panniantong/Agent-Reach
-- **本项目不是上游项目的官方发布**
-- 上游项目的名称、商标与版权归其各自权利人所有
-- 上游项目按其许可证条款（MIT）授权使用；本项目已在 THIRD_PARTY_NOTICES.md 中包含上游许可证声明。
+- **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"
 }
 ```
-**启用后自动完成**:
-1. 🔍 环境检测（OS、Python、Node.js、网络）
-2. 📦 自动安装 Python venv
-3. 🔄 自动安装/升级 Agent-Reach 到最新版
-4. ✅ Smoke test 验证可用性
+### 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 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter、Reddit、YouTube、GitHub、Bilibili、小红书 — 一个 CLI，零 API 费用。
+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.
-| 平台 | 功能 | 状态 |
-|------|------|------|
-| 🌐 网页 | Jina Reader 读取任意网页 | ✅ 开箱即用 |
-| 📺 YouTube | 字幕提取 + 视频搜索 | ✅ 开箱即用 |
-| 📡 RSS | 读取任意 RSS/Atom 源 | ✅ 开箱即用 |
-| 🐦 Twitter/X | 读取推文、搜索 | ⚙️ 需配置 bird CLI |
-| 📖 Reddit | 搜索、读取帖子评论 | ⚙️ 需配置代理 |
-| 📦 GitHub | 读取公开仓库、搜索 | ⚙️ 需安装 gh CLI |
-| 📺 Bilibili | 字幕提取 + 搜索 | ⚙️ 需配置代理 |
-| 📕 小红书 | 搜索、阅读 | ⚙️ 需配置 mcporter |
-| 🔍 全网搜索 | Exa AI 语义搜索 | ⚙️ 需配置 mcporter |
+| 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 |
 ---
-## 5 个核心工具（必须实现）
+## 5 Core Tools (Required)
-| 工具 | 说明 |
-|------|------|
-| `reach_ensure` | ✅ 准备环境 + 升级到最新（幂等）|
-| `reach_doctor` | ✅ 诊断所有平台渠道状态 + nextSteps |
-| `reach_exec` | ✅ 万能入口 - 完美复刻所有功能 |
-| `reach_list_commands` | ✅ 能力自发现 - 列出所有子命令 |
-| `reach_version` | ✅ 输出版本信息 + bootstrap 状态 |
+| 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
-### 核心
+### Core
-| 工具 | 说明 |
-|------|------|
-| `reach_ensure` | 确保 venv 存在并升级到最新 Agent-Reach |
-| `reach_doctor` | 诊断所有平台渠道状态，输出 nextSteps |
-| `reach_version` | 显示 MCP + Agent-Reach 版本 + bootstrap 状态 |
-| `reach_check_update` | 检查 GitHub 是否有新版本 |
-| `reach_watch` | 快速健康检查（适合定时任务）|
-| `reach_list_commands` | 列出所有可用子命令 |
+| 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 |
-### 安装与配置
+### Install & Configure
-| 工具 | 说明 |
-|------|------|
-| `reach_install` | 安装系统依赖（gh CLI, Node.js, bird, mcporter）|
-| `reach_configure` | 设置配置（proxy, token, cookies）|
-| `reach_setup` | 交互式配置向导 |
+| Tool | Description |
+|------|-------------|
+| `reach_install` | Install system dependencies (gh CLI, bird, mcporter) |
+| `reach_configure` | Set config (proxy, token, cookies) |
+| `reach_setup` | Interactive configuration wizard |
-### 读取与搜索
+### Read & Search
-| 工具 | 说明 |
-|------|------|
-| `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）|
+| 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) |
-### 高级
+### Advanced
-| 工具 | 说明 |
-|------|------|
-| `reach_exec` | 🔧 万能入口 - 执行任意子命令 |
+| Tool | Description |
+|------|-------------|
+| `reach_exec` | 🔧 Universal entry - execute any subcommand |
 ---
-## 使用示例
+## Usage Examples
-### 首次使用（自动完成）
-启用 MCP 后，会自动执行 bootstrap 确保。也可手动触发：
+### First Use (Auto Bootstrap)
 ```json
 {
@@ -116,21 +128,21 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
-**输出示例**:
+**Example Output**:
 ```
-# reach_ensure 结果
+# reach_ensure Result
-状态: ✅ 成功
+Status: ✅ Success
-## 执行日志
+## Execution Log
 - venv_check: OK (0ms)
 - upgrade_pip: OK (2341ms)
 - install_agent_reach: OK (5678ms)
-版本: 1.2.0
+Version: 1.2.0
 ```
-### 诊断
+### Diagnosis
 ```json
 {
@@ -138,22 +150,7 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
-**输出示例**:
-```
-# 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
-```
-### 读取网页
+### Read Web Page
 ```json
 {
@@ -162,7 +159,7 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
-### 搜索 Twitter
+### Search Twitter
 ```json
 {
@@ -171,17 +168,7 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
-**未安装 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
-```
-### 使用万能入口
+### Universal Entry
 ```json
 {
@@ -193,7 +180,7 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
-### 能力自发现
+### Self-Discovery
 ```json
 {
@@ -201,146 +188,101 @@ Agent-Reach 让你的 AI Agent 拥有"互联网之眼"。读取和搜索 Twitter
 }
 ```
-### 配置 Twitter Cookie
-```json
-{
-  "name": "reach_configure",
-  "arguments": {
-    "key": "twitter-cookies",
-    "value": "auth_token=xxx; ct0=yyy"
-  }
-}
-```
-### 配置代理
-```json
-{
-  "name": "reach_configure",
-  "arguments": {
-    "key": "proxy",
-    "value": "http://user:pass@ip:port"
-  }
-}
-```
 ---
-## 自动更新策略
+## Auto-Update Strategy
-**默认**: 每次工具调用前执行轻量 `ensureLatest()`
+**Default**: Lightweight `ensureLatest()` before each tool call
-### 支持的环境变量
+### Environment Variables
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `ALWAYS_LATEST` | `1` | 是否自动更新 |
-| `UPDATE_STRATEGY` | `simple` | 更新策略（simple/atomic）|
-| `NETWORK_REQUIRED` | `1` | 是否需要网络 |
-| `CACHE_DIR` | 系统缓存目录 | 缓存位置 |
-| `RUNTIME_DIR` | 系统缓存目录/runtime | 运行时目录 |
-| `LOG_LEVEL` | `info` | 日志级别（error/info/debug）|
+| 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
-1. 检查 venv 是否存在
-2. 检查 bootstrap 时间戳
-3. 执行 `pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip`
-4. 运行 smoke test 验证
-5. 记录 bootstrap 时间戳
+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
-**失败处理**: 更新失败不会破坏现有可用版本，返回 nextSteps 修复建议。
+**Failure handling**: Update failure won't break existing version, returns nextSteps for fix.
 ---
-## 环境要求
+## Environment Requirements
-### 启动时自动检测
+### Auto-Detection on Start
-- OS / CPU 架构
-- Python 版本（需要 3.10+）
-- Node.js 版本
-- 网络可达性
-- 磁盘空间
+- OS / CPU architecture
+- Python version (requires 3.10+)
+- Node.js version
+- Network availability
+- Disk space
-### 运行时目录
+### Runtime Directories
-| 平台 | 目录 |
-|------|------|
+| Platform | Directory |
+|----------|-----------|
 | Windows | `%LOCALAPPDATA%\agent-reach-mcp\` |
 | macOS | `~/Library/Caches/agent-reach-mcp/` |
 | Linux | `~/.cache/agent-reach-mcp/` |
-### 平台特定要求
-| 平台 | 要求 |
-|------|------|
-| Twitter | bird CLI + twitter-cookies |
-| 小红书 | mcporter + xiaohongshu-mcp Docker |
-| Reddit | 代理（服务器 IP 被封）|
-| Bilibili | 代理（服务器 IP 被封）|
-| GitHub | gh CLI（提高速率限制）|
-| 全网搜索 | mcporter + Exa MCP |
 ---
-## 推荐工作流
+## Recommended Workflow
-1. **启用 MCP** → 自动 bootstrap
-2. **诊断**: `reach_doctor` 查看渠道状态
-3. **发现**: `reach_list_commands` 查看可用命令
-4. **配置**: `reach_configure` 配置 cookies/代理
-5. **使用**: 搜索/读取工具 或 `reach_exec`
+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`
 ---
-## 验证矩阵
+## Verification Matrix
-### A. 一键部署验证 ✅
+### A. One-Click Deployment ✅
-**目标**: 只需启用 MCP，全自动收集并安装依赖
+**Target**: Just enable MCP, auto-collect and install dependencies
-**验证步骤**:
+**Steps**:
 ```bash
-# 1. 清空缓存
+# 1. Clear cache
 rm -rf ~/Library/Caches/agent-reach-mcp  # macOS
 rd /s /q %LOCALAPPDATA%\agent-reach-mcp  # Windows
-# 2. 重启 MCP
+# 2. Restart MCP
-# 3. 调用版本检查
+# 3. Call version check
 reach_version
 ```
-**预期输出（成功）**:
+**Expected Output (Success)**:
 ```
 === Agent-Reach MCP Version Info ===
-MCP Version: 1.0.0
+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
 ```
-**预期输出（失败 - 无 Python）**:
-```
-⚠️ MCP 未完全就绪
-Bootstrap 失败，部分功能可能不可用。
-错误类型: python_missing
+### B. Perfect Replica Verification ✅
-Next Steps:
-- Install Python 3.10+ from https://www.python.org/downloads/
-- Ensure Python is added to PATH during installation
-```
+**Target**: No capability loss after wrapping
-### B. 完美复刻验证 ✅
-**目标**: 封装后能力不缩水，新增命令自动支持
-**验证命令**:
+**Verification Commands**:
 ```json
 {"name": "reach_exec", "arguments": {"subcommand": "version"}}
 {"name": "reach_exec", "arguments": {"subcommand": "doctor"}}
@@ -349,112 +291,104 @@ Next Steps:
 {"name": "reach_exec", "arguments": {"subcommand": "setup"}}
 ```
-**判定标准**: 所有命令执行成功，输出与原 CLI 一致
-### C. 稳定健全验证 ✅
+**Criteria**: All commands execute successfully, output matches original CLI
-**目标**: 自检 / 自愈 / 清晰错误 / 可观测日志
+### C. Stability Verification ✅
-**验证步骤**:
-1. 调用 `reach_doctor` → 检查输出包含 nextSteps
-2. 破坏 venv → 调用 `reach_ensure` → 确认修复
-3. 调用不存在的命令 → 检查错误输出
+**Target**: Self-check / Self-healing / Clear errors / Observable logs
-**预期输出（doctor）**:
-```
-# reach_doctor 诊断报告
-...
-## Next Steps
-- Install bird CLI: npm install -g @steipete/bird
-```
+**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. 自动更新验证 ✅
+### D. Auto-Update Verification ✅
-**目标**: 每次调用前升级到最新版本
+**Target**: Upgrade to latest on each call
-**验证步骤**:
-1. 调用 `reach_version` 记录版本
-2. 等待上游更新
-3. 再次调用任意工具
-4. 检查 `reach_version` 是否更新
+**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. 部署即用验证 ✅
+### E. Deploy-Ready Verification ✅
-**目标**: 重启 Agent 后自动恢复
+**Target**: Auto-recover after Agent restart
-**验证步骤**:
-1. 启用 MCP
-2. 重启 Agent
-3. 调用任意工具
-4. 确认无需手动操作
+**Steps**:
+1. Enable MCP
+2. Restart Agent
+3. Call any tool
+4. Confirm no manual action needed
-### F. 失败场景验证
+### F. Failure Scenarios
-| 场景 | 触发方式 | 预期 nextSteps |
-|------|---------|----------------|
-| 断网 | 关闭网络 | 检查网络连接 |
-| 无 Python | 移除 PATH | 安装 Python 3.10+ |
-| venv 损坏 | 删除 venv 目录 | reach_ensure 会自动重建 |
-| bird 未安装 | reach_search_twitter | npm install -g @steipete/bird |
+| 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`
+### Python Missing
-**原因**: 系统未安装 Python
+**Cause**: Python not installed
-**修复**:
-- 安装 Python 3.10+: https://www.python.org/downloads/
-- 确保勾选 "Add Python to PATH"
+**Fix**:
+- Install Python 3.10+: https://www.python.org/downloads/
+- Ensure "Add Python to PATH" is checked during installation
-### `network_error`
+### Network Error
-**原因**: 无法访问 GitHub
+**Cause**: Cannot access GitHub
-**修复**:
-- 检查网络连接
-- 配置代理: `HTTP_PROXY`, `HTTPS_PROXY`
-- 或设置 `NETWORK_REQUIRED=0`
+**Fix**:
+- Check network connection
+- Configure proxy: `HTTP_PROXY`, `HTTPS_PROXY`
+- Or set `NETWORK_REQUIRED=0`
-### `venv_failed`
+### venv Failed
-**原因**: Python venv 模块不可用
+**Cause**: Python venv module not available
-**修复**:
-- 确保安装了完整的 Python（非精简版）
+**Fix**:
+- Ensure full Python installed (not minimal)
 - Linux: `sudo apt install python3-venv`
-### Bootstrap 未完成的工具调用
+### Bootstrap Incomplete
-**错误信息**:
+**Error**:
 ```
-⚠️ MCP 未完全就绪
+⚠️ MCP not fully ready
-Bootstrap 失败，部分功能可能不可用。
+Bootstrap failed, some features may be unavailable.
 ```
-**修复**: 调用 `reach_ensure` 进行修复
+**Fix**: Call `reach_ensure` to repair
 ---
-## 合规声明
+## Compliance
-### 许可证
+### License
-| 项目 | 许可证 |
-|------|--------|
-| 本项目 (agent-reach-mcp) | MIT License |
-| 上游 Agent-Reach | MIT License |
+| Project | License |
+|---------|---------|
+| This project (agent-reach-mcp) | MIT License |
+| Upstream Agent-Reach | MIT License |
-### 第三方声明
+### Third-Party Notices
-详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
+See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
 ---
-## 本地开发
+## Local Development
 ```bash
 npm install
@@ -472,5 +406,4 @@ MIT
 ## Links
 - [Agent-Reach GitHub](https://github.com/Panniantong/Agent-Reach)
-- [Agent-Reach 文档](https://github.com/Panniantong/Agent-Reach#readme)
-- [MCP 协议](https://modelcontextprotocol.io/)
+- [MCP Protocol](https://modelcontextprotocol.io/)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bsbofmusic/agent-reach-mcp",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "MCP stdio server for Agent-Reach. Bootstrap ensure, auto-install Docker, full platform support (XiaoHongShu, Douyin, Twitter, YouTube, Bilibili, GitHub).",
   "license": "MIT",
   "type": "module",