@bsbofmusic/agent-reach-mcp 0.2.0 → 0.2.1

package/README.md

@@ -1,368 +1,153 @@
-````md
-# Agent-Reach MCP (stdio) — Full Mirror Edition
-
-这是一个给 **OpenCode / CC-Switch** 用的 MCP（Model Context Protocol）stdio 服务器。目标很明确：
-
-> ✅ 导入 MCP 后，就能 **完整复刻 Agent-Reach 的全部能力**（通过 `reach_exec` 透传任意子命令）  
-> ✅ 并且满足你要求的：**简单 / 快捷 / 强大 / 永远最新**（每次调用前自动更新 Agent-Reach）
-
----
-
-## 你将得到什么
-
-启用这个 MCP 后，OpenCode 会多出一组工具（tools）：
-
-- `reach_ensure`：自愈环境 + 更新到最新 Agent-Reach
-- `reach_doctor`：执行 `agent-reach doctor`
-- `reach_read`：执行 `agent-reach read <url>`
-- ✅ `reach_exec`：执行 **任意** `agent-reach <subcommand> ...args`（全功能复刻关键）
-- `reach_list_commands`：执行 `agent-reach --help` 并解析出可用子命令列表（帮助模型“知道自己能干什么”）
-
-你不需要让 OpenCode 记住安装过程；它每次调用都会先把 Agent-Reach 升级到最新再执行。
-
----
-
-## 核心理念：MCP = “能力注入”，不是“记忆依赖”
-
-OpenCode 重启会“失忆”，但 MCP 是持久配置。
-
-- CC-Switch 负责：开关 / 配置 / 切换
-- MCP server 负责：环境自愈 + 能力暴露
-- Agent-Reach 负责：实际的多平台读/搜/配置能力
-
-所以正确心智模型是：
-
-> OpenCode 不需要记住怎么安装  
-> 它只要知道：有一个 MCP tool 叫 `reach_exec`，能运行 Agent-Reach 的任何命令
-
----
-
-## 工作原理（非常重要）
-
-每次你调用任意一个 tool（包括 `reach_exec`），MCP 都会：
-
-1) 在用户缓存目录创建/复用 Python venv  
-2) 执行（永远最新策略）：
-   - `pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip`  
-3) 然后运行对应的 `agent-reach ...` 命令  
-4) 把 stdout/stderr 回传给 OpenCode
-
-### venv 位置（默认）
-- Windows：`%LOCALAPPDATA%\agent-reach-mcp\runtime\venv`
-- macOS：`~/Library/Caches/agent-reach-mcp/runtime/venv`
-- Linux：`~/.cache/agent-reach-mcp/runtime/venv`
-
----
-
-## 环境要求
-
-- Node.js >= 18
-- Python 3（系统 PATH 里能找到 `python`，Windows 也可用 `py`）
-- 能访问 GitHub（用于拉 main.zip）
-
-> 说明：某些平台能力（例如需要 cookie / 代理 / docker 的）属于 Agent-Reach 上游能力，你需要按 doctor 输出提示去配。
-
----
-
-## 安装与本地验证（开发者）
-
-在项目目录：
-
-```bash
-npm install
-node index.js
-````
-
-stdio MCP server 启动后会等待输入，这属于正常现象。
-
----
-
-## 发布到 npm（手动，无 CI）
-
-### 1) 修改 package.json
-
-确保：
-
-* `name` 是你自己的包名（建议 scope 包：`@你的scope/agent-reach-mcp`）
-* `version` 每次发布都 +1（npm 禁止同版本覆盖）
-
-### 2) 发布
-
-```bash
-npm login
-npm publish --access public
-```
-
----
-
-## CC-Switch / OpenCode 配置方式（你要的“一键复活”）
-
-在 CC-Switch 新建 MCP 配置：
-
-```json
-{
-  "command": "npx",
-  "args": ["-y", "@your-scope/agent-reach-mcp@latest"],
-  "type": "stdio"
-}
-```
-
-然后重启 OpenCode。
-
-> 之后只要你更新 npm 包版本，用户侧 `@latest` 会在下次启动时拉到新版本（通常如此；依赖 npx 缓存策略）。
-
----
-
-# Tools 使用说明（强烈建议认真看）
-
-## 0) 第一次使用推荐流程
-
-1. `reach_ensure`（确保环境就绪）
-2. `reach_doctor`（看哪些渠道通、怎么配）
-3. `reach_list_commands`（让 OpenCode 知道有哪些子命令）
-4. 用 `reach_exec` 跑你要的平台命令
-
----
-
-## 1) reach_ensure
-
-用途：只做环境准备 + 更新。
-
-它等价于：
-
-* 创建 venv
-* pip 工具链更新
-* pip 安装/升级 Agent-Reach main.zip
-
-适用场景：
-
-* 第一次启用 MCP
-* 你怀疑环境坏了
-* 你想强制刷新到最新
-
----
-
-## 2) reach_doctor
-
-用途：诊断所有渠道状态。
-
-它会执行：
-
-```bash
-agent-reach doctor
-```
-
-适用场景：
-
-* 为什么某个平台读不到？
-* 需要 cookie 吗？
-* 需要代理吗？
-* 需要 docker 吗？
-
-doctor 是 Agent-Reach 官方推荐的“总检命令”。
-
----
-
-## 3) reach_read
-
-用途：读一个链接（网页/视频/仓库等，交给 Agent-Reach 判断）。
-
-它会执行：
-
-```bash
-agent-reach read <url>
-```
-
-输入：
-
-```json
-{ "url": "https://example.com" }
-```
-
-### 常见例子
-
-* 读普通网页：
-
-```json
-{ "url": "https://example.com" }
-```
-
-* 获取 YouTube 教程字幕/内容（Agent-Reach README 的示例就是 read YouTube）：
-
-```json
-{ "url": "https://youtube.com/watch?v=xxx" }
-```
-
----
-
-## 4) reach_exec ✅（全功能复刻关键）
-
-这是“完整复刻”的核心。它可以透传执行任何 Agent-Reach 子命令：
-
-等价于：
-
-```bash
-agent-reach <subcommand> ...args
-```
-
-输入格式：
-
-```json
-{
-  "subcommand": "doctor",
-  "args": [],
-  "timeoutMs": 600000
-}
-```
-
-### 4.1 安装（对应 Agent-Reach README 的安装方式）
-
-> 虽然 MCP 自己会安装 main.zip，但 Agent-Reach 还有 “install” 用来装系统依赖/配置渠道（很重要）
-
-* 全自动安装（默认推荐）：
-
-```json
-{ "subcommand": "install", "args": ["--env=auto"] }
-```
-
-* 安全模式（不自动改系统，只提示缺什么）：
-
-```json
-{ "subcommand": "install", "args": ["--env=auto", "--safe"] }
-```
-
-* Dry Run（预览将做什么，不执行）：
-
-```json
-{ "subcommand": "install", "args": ["--env=auto", "--dry-run"] }
-```
-
-### 4.2 Twitter/X：配置 cookie + 搜索推文（来自官方 README FAQ）
-
-* 配置 twitter cookie（你需要把 Cookie-Editor 导出的 cookie 字符串填进去）：
-
-```json
-{
-  "subcommand": "configure",
-  "args": ["twitter-cookies", "your_cookies_here"]
-}
-```
-
-* 搜索推文：
-
-```json
-{
-  "subcommand": "search-twitter",
-  "args": ["关键词"]
-}
-```
-
-### 4.3 代理配置（解决 Reddit 数据中心 IP 403 等，来自官方 README FAQ）
-
-```json
-{
-  "subcommand": "configure",
-  "args": ["proxy", "http://user:pass@ip:port"]
-}
-```
-
-### 4.4 小红书：搜索（来自官方 README FAQ）
-
-```json
-{
-  "subcommand": "search-xhs",
-  "args": ["关键词"]
-}
-```
-
-> 小红书往往需要 docker / MCP 服务配套，先跑 `reach_doctor` 看提示。
-
-### 4.5 读任意链接（等价 reach_read，但更通用）
-
-```json
-{
-  "subcommand": "read",
-  "args": ["https://github.com/Panniantong/Agent-Reach"]
-}
-```
-
----
-
-## 5) reach_list_commands（推荐让 OpenCode“自发现”能力）
-
-用途：列出当前安装的 Agent-Reach 版本支持哪些子命令。
-
-为什么需要它？
-
-* Agent-Reach 在快速迭代
-* 你坚持“永远最新”
-* 所以命令集合可能随时变化
-* `reach_list_commands` 能让 OpenCode 在**没有记忆**的情况下，仍然准确知道有哪些子命令
-
-推荐用法：
-
-1. 启用 MCP 后先跑一次 `reach_list_commands`
-2. OpenCode 会得到一份命令列表
-3. 后续就用 `reach_exec` 调用列表里的命令
-
----
-
-# 推荐验证计划（你可以照抄给 OpenCode 执行）
-
-## Phase 1：基础健康
-
-1. `reach_ensure`
-2. `reach_doctor`
-3. `reach_read` 读一个普通网页
-
-预期：能成功安装/更新 + doctor 输出渠道状态 + read 有返回内容
-
-## Phase 2：全能力复刻
-
-1. `reach_list_commands`
-2. 从列表里挑 3 个子命令用 `reach_exec` 跑（例如 install / configure / search-* / read）
-
-## Phase 3：按需补齐配置
-
-* Twitter 需要 cookie：用 `configure twitter-cookies ...`
-* 服务器访问 Reddit/B站可能需要代理：用 `configure proxy ...`
-* 小红书可能需要 docker：按 doctor 指引
-
----
-
-# 常见问题（FAQ）
-
-## Q1: 为什么我明明启用了 MCP，但某个平台用不了？
-
-A：平台能力取决于 Agent-Reach 的“渠道状态”，不是 MCP 本身。跑 `reach_doctor` 看缺什么（cookie、代理、docker、登录等）。
-
-## Q2: 为什么每次调用都要更新？会不会慢？
-
-A：这是你选择的策略：Always-Latest。首次或上游更新时会慢，但能保证永远最新。如果以后你要“快且稳”，可以改成“每日一次更新/或失败回滚”。
-
-## Q3: 如何避免 OpenCode 重启后不知道有哪些命令？
-
-A：用 `reach_list_commands`。这是为“无记忆模型”专门做的能力自发现入口。
-
-## Q4: 我想要更友好的工具（比如 reach_search_twitter / reach_search_xhs）要不要做？
-
-A：可以做，但不是必须。`reach_exec` 已经完整复刻；单独工具只是“更强的 schema 引导”。
-
----
-
-# License
-
-MIT
-
-```
-
----
-
-### 我对齐了哪些“真实命令名”（可核对）
-这些命令名来自 Agent-Reach 最新 README 中的安装方式与 FAQ：`configure twitter-cookies`、`search-twitter`、`configure proxy`、`search-xhs`、`read`、`doctor`、`install --env=auto/--safe/--dry-run`。 :contentReference[oaicite:1]{index=1}
-
-如果你愿意，我还可以再给你一个**更强的 README 增强版**：把 `reach_list_commands` 的输出示例也写进去，并给一份“OpenCode Prompt 模板”（让模型自动：list_commands → 选命令 → exec）。
-::contentReference[oaicite:2]{index=2}
-```
-
-[1]: https://github.com/Panniantong/Agent-Reach "GitHub - Panniantong/Agent-Reach: Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees."
+# Agent-Reach MCP
+
+MCP (stdio) server that provides full access to Agent-Reach for OpenCode / CC-Switch.
+
+## What is Agent-Reach?
+
+Agent-Reach gives your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
+
+**Key Features:**
+- Web page reading (via Jina Reader)
+- YouTube video/subtitle extraction
+- Twitter/X reading and search
+- Reddit search and reading
+- GitHub repository access
+- Bilibili video extraction
+- XiaoHongShu (Little Red Book) search
+- Full-text web search (via Exa)
+- RSS feed parsing
+
+## Installation
+
+### Quick Start (CC-Switch / OpenCode)
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@bsbofmusic/agent-reach-mcp@latest"],
+  "type": "stdio"
+}
+```
+
+### Local Development
+
+```bash
+npm install
+node index.js
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `reach_ensure` | Create/update Python venv and install latest Agent-Reach |
+| `reach_doctor` | Run `agent-reach doctor` - diagnose all channels |
+| `reach_read` | Read a URL (webpage/video/repo) |
+| `reach_exec` | Execute any `agent-reach <subcommand>` command |
+| `reach_list_commands` | List available subcommands from `agent-reach --help` |
+
+## Usage Examples
+
+### First Time Setup
+
+```json
+{ "subcommand": "install", "args": ["--env=auto"] }
+```
+
+### Read a Webpage
+
+```json
+{ "url": "https://example.com" }
+```
+
+### Read YouTube Video
+
+```json
+{ "url": "https://youtube.com/watch?v=xxx" }
+```
+
+### Configure Twitter Cookies
+
+```json
+{
+  "subcommand": "configure",
+  "args": ["twitter-cookies", "your_cookie_string"]
+}
+```
+
+### Search Twitter
+
+```json
+{
+  "subcommand": "search-twitter",
+  "args": ["your search query"]
+}
+```
+
+### Configure Proxy
+
+```json
+{
+  "subcommand": "configure",
+  "args": ["proxy", "http://user:pass@ip:port"]
+}
+```
+
+### Search XiaoHongShu
+
+```json
+{
+  "subcommand": "search-xhs",
+  "args": ["keywords"]
+}
+```
+
+## Environment Requirements
+
+- Node.js >= 18
+- Python 3 (in PATH, or `py` on Windows)
+- Internet access to GitHub
+
+## How It Works
+
+Every tool call triggers:
+
+1. Create/reuse Python venv in user cache directory
+2. Run `pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip`
+3. Execute the requested `agent-reach ...` command
+4. Return stdout/stderr to the AI
+
+### Venv Location
+
+- Windows: `%LOCALAPPDATA%\agent-reach-mcp\runtime\venv`
+- macOS: `~/Library/Caches/agent-reach-mcp/runtime/venv`
+- Linux: `~/.cache/agent-reach-mcp/runtime/venv`
+
+## Recommended Workflow
+
+1. **Initial Setup**: Run `reach_ensure` to install/update Agent-Reach
+2. **Diagnosis**: Run `reach_doctor` to check channel status
+3. **Discovery**: Run `reach_list_commands` to see available commands
+4. **Usage**: Use `reach_exec` for any Agent-Reach command
+
+## FAQ
+
+**Q: Why can't I use a certain platform?**
+
+A: Check with `reach_doctor` - you may need cookies, proxy, or docker configured.
+
+**Q: Does it update every call?会不会慢?**
+
+A: Yes, this is "Always-Latest" strategy. First call or upstream updates may be slow, but you'll always have the latest version.
+
+**Q: How to discover available commands after restart?**
+
+A: Run `reach_list_commands` - this enables "capability self-discovery" for memory-less models.
+
+## License
+
+MIT
+
+## Links
+
+- [Agent-Reach GitHub](https://github.com/Panniantong/Agent-Reach)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsbofmusic/agent-reach-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP stdio server that auto-installs/updates Agent-Reach and exposes reach_* tools.",
   "license": "MIT",
   "type": "module",