@bsbofmusic/agent-reach-mcp 0.1.1 → 0.2.1

package/README.md

@@ -1,252 +1,153 @@
-Agent-Reach MCP (stdio)
-
-A production-ready MCP (Model Context Protocol) stdio server for OpenCode / CC-Switch.
-
-This package automatically installs and upgrades Agent-Reach on every tool call, ensuring you always run the latest version from GitHub main.
-
-Designed for:
-
-✅ One-click activation via npx
-
-✅ Always-latest behavior
-
-✅ Self-healing Python environment
-
-✅ Reusable across machines
-
-✅ Zero manual dependency management
-
-✅ Works with OpenCode + CC-Switch
-
-🚀 What This Package Does
-
-When enabled as an MCP server:
-
-Creates a dedicated Python virtual environment under your user cache directory
-
-Automatically upgrades Agent-Reach from:
-
-https://github.com/Panniantong/agent-reach/archive/main.zip
-
-Executes Agent-Reach CLI commands
-
-Returns structured output to the LLM via MCP
-
-This guarantees:
-
-🔁 Always running latest Agent-Reach
-
-🔧 No manual pip management
-
-♻️ Environment automatically recreated if broken
-
-💡 Fully stateless from OpenCode’s perspective
-
-🧠 Architecture Overview
-OpenCode
-   ↓
-MCP (stdio)
-   ↓
-Node.js server (this package)
-   ↓
-Auto-managed Python venv (user cache)
-   ↓
-Latest Agent-Reach (pip install -U main.zip)
-
-The Python environment is stored in:
-
-Windows:
-
-%LOCALAPPDATA%\agent-reach-mcp\runtime\venv
-
-macOS:
-
-~/Library/Caches/agent-reach-mcp/runtime/venv
-
-Linux:
-
-~/.cache/agent-reach-mcp/runtime/venv
-📦 Installation (Local Development)
-npm install
-node index.js
-
-If the process starts without crashing, it is working correctly (stdio server waits for input).
-
-📤 Publish to npm
-
-1️⃣ Edit package.json name:
-
-"name": "@your-scope/agent-reach-mcp"
-
-or without scope:
-
-"name": "agent-reach-mcp-yourname"
-
-2️⃣ Publish:
-
-npm login
-npm publish --access public
-⚙️ Using With CC-Switch
-
-Add this configuration:
-
-{
-  "command": "npx",
-  "args": ["-y", "@your-scope/agent-reach-mcp@latest"],
-  "type": "stdio"
-}
-
-Then:
-
-Enable MCP
-
-Restart OpenCode
-
-Tools will be automatically available
-
-🛠 Available MCP Tools
-1️⃣ reach_ensure
-
-Ensures:
-
-Python venv exists
-
-Agent-Reach upgraded to latest
-
-Returns installation logs.
-
-2️⃣ reach_doctor
-
-Runs:
-
-agent-reach doctor
-
-Automatically upgrades before execution.
-
-3️⃣ reach_read
-
-Runs:
-
-agent-reach read <url>
-
-Automatically upgrades before execution.
-
-Example input:
-
-{
-  "url": "https://example.com"
-}
-🔄 Always Latest Behavior
-
-This package intentionally prioritizes:
-
-Latest > Stability
-
-On every tool call:
-
-pip install -U https://github.com/Panniantong/agent-reach/archive/main.zip
-
-This ensures:
-
-New features immediately available
-
-Bug fixes applied instantly
-
-No stale installs
-
-⚠️ If upstream breaks, you get upstream behavior immediately (by design).
-
-🛡 Stability Notes
-
-This MCP server:
-
-Automatically recreates venv if deleted
-
-Upgrades pip tooling
-
-Fallbacks to python -m agent_reach if console script missing
-
-Captures stdout/stderr
-
-Handles timeouts
-
-Returns structured MCP errors
-
-🧩 Requirements
-
-Node.js >= 18
-
-Python 3 available in PATH
-
-pip available
-
-Internet connection
-
-🔍 Why Use MCP Instead of Direct CLI?
-
-Because:
-
-OpenCode forgets memory after restart
-
-MCP ensures environment is rebuilt automatically
-
-Tools become persistent capabilities
-
-One-click activation via CC-Switch
-
-No manual installation per machine
-
-🏗 Design Philosophy
-
-Minimal
-
-Stateless
-
-Self-healing
-
-Always current
-
-Reusable anywhere via npx
-
-📄 License
-
-MIT
-
-💡 Example OpenCode Prompt
-
-After enabling MCP:
-
-Use reach_read to analyze https://example.com
-
-Or:
-
-Run reach_doctor and summarize health status
-🔮 Future Extensions (Optional)
-
-Possible future improvements:
-
-Version pin mode
-
-Automatic rollback on failure
-
-Dependency preflight checks
-
-Docker isolation mode
-
-Logging level control
-
-Configurable update strategy
-
-✅ Summary
-
-You now have:
-
-A reusable MCP server
-
-Publishable npm package
-
-Always-latest Agent-Reach integration
-
-Zero manual maintenance workflow
-
-One-click OpenCode integration
+# 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/index.js

@@ -12,12 +12,16 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 /**
- * A minimal, robust MCP stdio server that:
- * - Creates a Python venv under user cache dir
- * - On EVERY tool call, upgrades Agent-Reach from GitHub main.zip
- * - Executes `agent-reach` via the venv (fallback to python -m ...)
+ * Agent-Reach MCP (stdio) — Full capability proxy
  *
- * NOTE: This favors "latest" over strict stability, per your requirement.
+ * Goals:
+ * - Import MCP => "full Agent-Reach" via reach_exec (generic passthrough)
+ * - Still provide ergonomic basics: ensure / doctor / read
+ * - On EVERY tool call: auto-upgrade Agent-Reach from GitHub main.zip (always latest)
+ *
+ * Notes:
+ * - This favors "latest" over strict stability, per your requirement.
+ * - It manages its own python venv in user cache.
  */
 
 function isWindows() {
@@ -101,8 +105,6 @@ async function createVenvIfMissing(root) {
 
   if (existsSync(pythonExe)) return;
 
-  // Try creating venv using system python.
-  // Windows: python, then py -3
   const candidates = isWindows()
     ? [
         { cmd: "python", args: ["-m", "venv", venvDir] },
@@ -120,7 +122,9 @@ async function createVenvIfMissing(root) {
   }
 
   if (!existsSync(pythonExe)) {
-    const tried = candidates.map((c) => `${c.cmd} ${c.args.join(" ")}`).join(" | ");
+    const tried = candidates
+      .map((c) => `${c.cmd} ${c.args.join(" ")}`)
+      .join(" | ");
     const err = last?.stderr || "";
     throw new Error(
       `Failed to create Python venv.\nTried: ${tried}\nLast stderr:\n${err}`
@@ -133,15 +137,19 @@ async function ensureLatestAgentReach(root) {
   const { pythonExe, agentReachExe } = venvPaths(root);
 
   // Upgrade pip tooling (best effort)
-  await run(pythonExe, ["-m", "pip", "install", "-U", "pip", "setuptools", "wheel"], {
-    timeoutMs: 5 * 60 * 1000,
-  });
+  await run(
+    pythonExe,
+    ["-m", "pip", "install", "-U", "pip", "setuptools", "wheel"],
+    { timeoutMs: 5 * 60 * 1000 }
+  );
 
-  // Your "always latest" requirement:
+  // ALWAYS LATEST (main branch zip)
   const pkgUrl = "https://github.com/Panniantong/agent-reach/archive/main.zip";
-  const installRes = await run(pythonExe, ["-m", "pip", "install", "-U", pkgUrl], {
-    timeoutMs: 10 * 60 * 1000,
-  });
+  const installRes = await run(
+    pythonExe,
+    ["-m", "pip", "install", "-U", pkgUrl],
+    { timeoutMs: 10 * 60 * 1000 }
+  );
 
   let log = `pip install -U ${pkgUrl}\nexit=${installRes.code}\n`;
   if (installRes.stdout.trim()) log += `stdout:\n${installRes.stdout}\n`;
@@ -158,17 +166,19 @@ async function ensureLatestAgentReach(root) {
   return { pythonExe, agentReachExe, ensureLog: log };
 }
 
-async function runAgentReach(root, args) {
-  const { pythonExe, agentReachExe, ensureLog } = await ensureLatestAgentReach(root);
+async function runAgentReach(root, args, extraOpts = {}) {
+  const { pythonExe, agentReachExe, ensureLog } = await ensureLatestAgentReach(
+    root
+  );
+
+  const timeoutMs = extraOpts.timeoutMs ?? 10 * 60 * 1000;
 
   let execRes;
   if (existsSync(agentReachExe)) {
-    execRes = await run(agentReachExe, args, { timeoutMs: 10 * 60 * 1000 });
+    execRes = await run(agentReachExe, args, { timeoutMs });
   } else {
-    // Fallback: module import. (May vary; best effort.)
-    execRes = await run(pythonExe, ["-m", "agent_reach", ...args], {
-      timeoutMs: 10 * 60 * 1000,
-    });
+    // Fallback: module import (best effort)
+    execRes = await run(pythonExe, ["-m", "agent_reach", ...args], { timeoutMs });
   }
 
   let out = `# ensure_latest\n${ensureLog}\n`;
@@ -179,13 +189,55 @@ async function runAgentReach(root, args) {
   return { out, code: execRes.code };
 }
 
+/**
+ * Best-effort command listing:
+ * - Try: `agent-reach --help`
+ * - Parse lines that look like subcommands.
+ */
+function parseCommandsFromHelp(helpText) {
+  const lines = helpText.split(/\r?\n/);
+  const commands = new Set();
+
+  // Common patterns:
+  //   "Commands:" section in Click/Typer
+  //   indented: "read      ..." or "doctor    ..."
+  let inCommands = false;
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+
+    if (/^Commands:\s*$/i.test(line.trim())) {
+      inCommands = true;
+      continue;
+    }
+    if (inCommands && line.trim() === "") {
+      // stop after an empty line (often ends section)
+      // (but some help formats include blank lines; be conservative)
+      // We'll not hard-stop here.
+    }
+
+    if (inCommands) {
+      const m = line.match(/^\s{0,4}([a-zA-Z0-9][a-zA-Z0-9_-]+)\s{2,}.*$/);
+      if (m?.[1]) commands.add(m[1]);
+    } else {
+      // Some CLIs list commands without explicit "Commands:" header
+      const m = line.match(/^\s{0,4}([a-zA-Z0-9][a-zA-Z0-9_-]+)\s{2,}.*$/);
+      if (m?.[1] && !/^(Usage|Options|Arguments):?$/i.test(m[1])) {
+        // Only add if it doesn't look like a header.
+        // But to avoid noise, we won't add outside commands section.
+      }
+    }
+  }
+
+  return Array.from(commands).sort();
+}
+
 function text(content) {
   return [{ type: "text", text: content }];
 }
 
 async function main() {
   const server = new Server(
-    { name: "agent-reach-mcp", version: "0.1.0" },
+    { name: "agent-reach-mcp", version: "0.2.0" },
     { capabilities: { tools: {} } }
   );
 
@@ -218,6 +270,38 @@ async function main() {
             required: ["url"],
           },
         },
+        {
+          name: "reach_exec",
+          description:
+            "Execute ANY Agent-Reach subcommand. Example: {subcommand:'search-xhs', args:['关键词']} or {subcommand:'read', args:['https://...']}. Auto-updates Agent-Reach first.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              subcommand: {
+                type: "string",
+                description:
+                  "Agent-Reach subcommand name, e.g. 'search-xhs', 'read', 'doctor', etc.",
+              },
+              args: {
+                type: "array",
+                items: { type: "string" },
+                description: "Arguments passed to the subcommand",
+              },
+              timeoutMs: {
+                type: "number",
+                description:
+                  "Optional timeout in milliseconds for the command execution (default ~10 minutes).",
+              },
+            },
+            required: ["subcommand"],
+          },
+        },
+        {
+          name: "reach_list_commands",
+          description:
+            "List available Agent-Reach subcommands by parsing `agent-reach --help`. Auto-updates Agent-Reach first.",
+          inputSchema: { type: "object", properties: {} },
+        },
       ],
     };
   });
@@ -240,12 +324,68 @@ async function main() {
       if (name === "reach_read") {
         const url = String(input.url ?? "");
         if (!url || !/^https?:\/\//i.test(url)) {
-          return { content: text("Invalid url. Must start with http(s)://"), isError: true };
+          return {
+            content: text("Invalid url. Must start with http(s)://"),
+            isError: true,
+          };
         }
-        const { out, code } = await runAgentReach(runtimeRoot, ["read", url]);
+        const { out, code } = await runAgentReach(runtimeRoot, ["read", url], {
+          timeoutMs: 10 * 60 * 1000,
+        });
         return { content: text(out), isError: code !== 0 };
       }
 
+      if (name === "reach_exec") {
+        const subcommand = String(input.subcommand ?? "").trim();
+        const args = Array.isArray(input.args) ? input.args.map(String) : [];
+        const timeoutMs =
+          typeof input.timeoutMs === "number" && input.timeoutMs > 0
+            ? Math.floor(input.timeoutMs)
+            : 10 * 60 * 1000;
+
+        if (!subcommand) {
+          return {
+            content: text("Missing required field: subcommand"),
+            isError: true,
+          };
+        }
+
+        // Minimal safety: prevent command injection by disallowing whitespace in subcommand
+        // (args are passed as array so they are safe).
+        if (/\s/.test(subcommand)) {
+          return {
+            content: text("Invalid subcommand (contains whitespace)."),
+            isError: true,
+          };
+        }
+
+        const { out, code } = await runAgentReach(
+          runtimeRoot,
+          [subcommand, ...args],
+          { timeoutMs }
+        );
+        return { content: text(out), isError: code !== 0 };
+      }
+
+      if (name === "reach_list_commands") {
+        const { out, code } = await runAgentReach(runtimeRoot, ["--help"], {
+          timeoutMs: 2 * 60 * 1000,
+        });
+
+        // Parse only from stdout/stderr combined output we already include.
+        const helpText = out;
+        const commands = parseCommandsFromHelp(helpText);
+
+        const payload = [
+          "# parsed_commands",
+          commands.length ? commands.join("\n") : "(no commands parsed; see help output below)",
+          "",
+          out,
+        ].join("\n");
+
+        return { content: text(payload), isError: code !== 0 };
+      }
+
       return { content: text(`Unknown tool: ${name}`), isError: true };
     } catch (e) {
       const msg = e?.stack || e?.message || String(e);

package/package.json

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