@gecho-ai/gecho-bridge 1.1.5 → 1.1.7

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "@gecho-ai/gecho-bridge",
+  "version": "1.1.7",
+  "description": "TikTok Search Tool for OpenClaw"
+}

package/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "gecho-tiktok-search": {
+      "command": "node",
+      "args": ["./mcp-client.js"],
+      "timeout": 600000,
+      "retries": 0
+    }
+  }
+}

package/README.en.md

@@ -0,0 +1,158 @@
+# Gecho Bridge 🚀
+
+🌐 **Gecho Bridge** is a universal MCP (Model Context Protocol) tool designed to bridge your large language model (LLM) and your local browser.
+After installation, whether you use **OpenClaw**, **Hermes**, or **Trae**, your AI assistant can directly control the browser to automate TikTok search, data scraping, and deep opportunity insights.
+
+---
+
+## ✨ Who Is It For
+
+- 📊 **Competitor analysis**: Input a keyword and quickly get engagement data from top TikTok posts.
+- 💡 **Finding winning products**: Use deep insight tools to analyze trends in specific niches (for example, "portable blender") and discover underserved opportunities.
+- 🤖 **Automated operations**: Let your AI model control the browser, scroll automatically, scrape results, and generate reports without manual counting.
+
+## 🚀 What It Can Do
+
+- Launch Chrome automatically, search TikTok with a target keyword, and simulate natural human-like scrolling.
+- Collect large-scale structured data (video ID, title, likes, video link, and more) and safely save it as JSON files.
+- Run **asynchronous deep insights** powered by large-scale retrieval to summarize trends and potential business opportunities.
+
+## 🔗 Links
+
+- **Official Website**: [https://gecho.ai/](https://gecho.ai/)
+- **ClawHub Plugin Page**: [https://clawhub.ai/plugins/gecho-bridge](https://clawhub.ai/plugins/gecho-bridge)
+- **Chrome Extension**: [Install from Chrome Web Store](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
+
+---
+
+## 📦 Installation & Setup
+
+This project follows the standard MCP protocol and can be integrated with any MCP-compatible AI client (such as OpenClaw, Hermes, and Trae).
+
+### 0. Prerequisites
+1. **Node.js**: >= 18 (with `npm` / `npx` support).
+2. **Browser extension**: [Install the Gecho Chrome Extension first](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).
+3. **Network and account state**: Ensure stable access to TikTok, keep your TikTok account logged in, and keep the extension online.
+
+### Option 1: One-Click Setup in OpenClaw (ClawHub)
+ClawHub provides two installation paths: `Skill` and `Plugin`.
+
+#### Path A: Skill Install (MCP Required First)
+Skill installation executes through MCP, so you must configure MCP first:
+```bash
+openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
+openclaw gateway restart
+```
+*After configuration, run `openclaw mcp list` to verify status.*
+*Then return to ClawHub and install the Skill.*
+
+#### Path B: Plugin Install (Recommended)
+```bash
+openclaw plugins install @gecho-ai/gecho-bridge
+openclaw gateway restart
+```
+*To upgrade later, run `openclaw plugins update @gecho-ai/gecho-bridge`.*
+
+### Option 2: One-Click Setup in Hermes (Hermes Skill Hub)
+Use the following commands to add the service in Hermes and restart:
+```bash
+hermes mcp add gecho-bridge --command npx --args="-y" --args="@gecho-ai/gecho-bridge@latest"
+hermes restart
+```
+*After restart, run `hermes mcp list` to verify installation status.*
+
+### Option 3: Manual Setup for Trae / Claude Desktop and Other MCP Clients
+In clients that support manual MCP configuration, open `mcp.json` or `claude_desktop_config.json` and add:
+```json
+{
+  "mcpServers": {
+    "gecho-bridge": {
+      "command": "npx",
+      "args": ["-y", "@gecho-ai/gecho-bridge@latest"]
+    }
+  }
+}
+```
+
+---
+
+## 🏁 Quick Start & Common Workflows
+
+After setup is complete and your AI client has restarted, you can directly use natural language commands.
+
+### 🔍 Basic Search (`tiktok_search`)
+Best for quick retrieval and collection of video data.
+**Example prompts:**
+- *"Search TikTok for 'portable blender' and return the top 10 by likes."*
+- *"Search 'cat toy' and save full results to /Users/yourname/gecho-data."*
+
+**Execution flow:**
+1. AI triggers the local Gecho browser extension to search and auto-scroll.
+2. After scraping, large-scale results are automatically saved locally.
+3. AI summarizes the top 20 high-like results in your chat.
+
+### 📈 Deep Insight (`tiktok_insight`)
+Best for category research and trend analysis.
+**Example prompts:**
+- *"Run tiktok_insight for 'outdoor picnic mat'."*
+- *"Compare hot video styles and engagement between 'desk setup' and 'minimal desk'."*
+
+**Execution flow:**
+1. The plugin starts an asynchronous insight job and immediately returns a `jobId`.
+2. **⚠️ Important**: Deep insights involve heavy scraping and AI analysis, and usually take **more than 5 minutes**. During execution, **do not close the browser extension or related TikTok pages**.
+3. After waiting, ask AI: *"Use check_insight_status to query the previous job status"* to get the final report.
+
+---
+
+## ⚙️ Storage Configuration
+
+To better manage your data assets, scraped results should be persisted to disk. The plugin supports the following priority order:
+
+1. **Session-level (highest priority)**: In chat, ask AI to set `save_dir` directly (must be an absolute path).
+2. **Global-level**: Set the environment variable `GECHO_DATA_DIR` as the default save directory.
+3. **Fallback default**: If not specified, data is saved to the built-in `./data` directory.
+
+*(Note: All output filenames are automatically sanitized to avoid write failures from invalid characters.)*
+
+---
+
+## 🛠️ Troubleshooting
+
+### 1. How do I confirm the plugin is loaded? (OpenClaw example)
+Run:
+```bash
+openclaw plugins info @gecho-ai/gecho-bridge
+```
+If installation succeeds, you should see `Status: loaded` and `MCP servers: gecho-tiktok-search`.
+
+### 2. Error: Extension not connected
+- Check whether the Gecho Chrome extension is enabled.
+- Make sure your TikTok account is logged in, and the TikTok page is not crashed or unresponsive.
+
+### 3. Error: Request timeout
+- Check whether TikTok displays a CAPTCHA challenge; if so, solve it manually first.
+- If results are too sparse for the keyword or network is unstable, try a more specific keyword and retry.
+
+### 4. Error: Failed to save results
+- Check whether `save_dir` provided to AI is a valid absolute path.
+- Confirm your current system user has write permissions for the target directory.
+
+---
+
+## 🧑‍💻 Local Development
+
+For developers who want to build on top of this project:
+```bash
+git clone https://github.com/gecho-ai/bridge.git
+cd bridge
+npm install
+npm run server
+```
+
+**Two-layer architecture:**
+- **Client layer** (`mcp-client.js`): Standard MCP STDIO integration for communication with OpenClaw/Hermes/Trae and tool schema declarations.
+- **Service layer** (`server.js`): Local resident service that communicates with the browser extension over WebSocket and executes scraping plus persistence. (Supports lazy start and only launches when needed.)
+
+## License
+
+MIT

package/README.md

@@ -1,29 +1,68 @@
 # Gecho Bridge 🚀
 
-Gecho Bridge is an MCP (Model Context Protocol) server that connects AI Agents (like Claude Desktop, Cursor, or OpenClaw) to TikTok via a Chrome extension. It allows your AI models to search and retrieve TikTok video metadata directly from the browser.
+🌐 **Gecho Bridge** 是一款通用的 MCP（Model Context Protocol）工具，旨在为你的大语言模型（LLM）与本地浏览器之间搭建一座桥梁。
+安装后，无论是使用 **OpenClaw**、**Hermes** 还是 **Trae**，你的 AI 助手都能直接控制浏览器，自动化完成 TikTok 搜索、数据抓取与深度商机洞察。
 
-## Features
+---
 
-- **Automated Search**: Search TikTok with keywords and auto-scroll to fetch results.
-- **Data Retrieval**: Get video IDs, titles, like counts, and play URLs.
-- **Dual-Layer Architecture**: A lightweight MCP Client that automatically manages a persistent Service Layer.
-- **Lazy Start**: The bridge automatically starts the background service when needed.
+## ✨ 适合谁用
 
-## Installation
+- 📊 **分析竞品**：输入关键词，快速获取 TikTok 前排高赞视频的各项互动数据。
+- 💡 **寻找爆款**：使用深度洞察工具分析特定品类（如 "portable blender"）的流行趋势，捕捉未被满足的市场蓝海。
+- 🤖 **自动化运营**：让大模型直接指挥浏览器，自动翻页抓取并生成数据报表，免去繁琐的手动统计。
 
-### 1. Install via npm
+## 🚀 能做什么
+
+- 自动唤起 Chrome 并在 TikTok 搜索指定关键词，模拟真人自然滚动加载。
+- 抓取海量结构化数据（视频 ID、标题、点赞量、播放链接等）并自动安全落盘为 JSON 文件。
+- 执行基于大数据检索的**异步深度洞察**，智能提炼爆款趋势与潜在商机。
+
+## 🔗 相关链接
+
+- **官网**：[https://gecho.ai/](https://gecho.ai/)
+- **ClawHub 插件页**：[https://clawhub.ai/plugins/gecho-bridge](https://clawhub.ai/plugins/gecho-bridge)
+- **Chrome 浏览器扩展**：[前往 Chrome 网上应用店下载](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
+
+---
+
+## 📦 安装与配置
+
+本项目基于标准 MCP 协议开发，可以无缝接入任何支持 MCP 的 AI 客户端（如 OpenClaw、Hermes、Trae 等）。
+
+### 0. 前置环境要求
+1. **Node.js**：>= 18（需支持 `npm` / `npx`）。
+2. **浏览器扩展**：请先[点击此处安装 Gecho 浏览器扩展](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)。
+3. **网络与状态**：确保本地网络可稳定访问 TikTok，并在浏览器中登录账号，保持扩展在线。
+
+### 方式一：在 OpenClaw 中一键安装 (ClawHub)
+ClawHub 中有两种安装方式：`Skill` 与 `Plugin`。
+
+#### 方案 A：Skill 安装（需先配置 MCP）
+Skill 安装后会通过 MCP 调用执行，因此需要先完成以下 MCP 配置：
 ```bash
-npm install -g @gecho-ai/gecho-bridge
+openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
+openclaw gateway restart
 ```
+*配置后，可通过 `openclaw mcp list` 检查状态。*
+*完成 MCP 配置后，再回到 ClawHub 选择 Skill 安装即可。*
 
-### 2. Install Chrome Extension
-Ensure you have the Gecho TikTok Extension installed and active in your Chrome browser. The bridge communicates with this extension via WebSocket.
-
-## Configuration
+#### 方案 B：Plugin 安装（推荐）
+```bash
+openclaw plugins install @gecho-ai/gecho-bridge
+openclaw gateway restart
+```
+*如需升级已安装的版本，使用 `openclaw plugins update @gecho-ai/gecho-bridge` 即可。*
 
-### Claude Desktop
-Add the following to your `claude_desktop_config.json`:
+### 方式二：在 Hermes 中一键配置 (Hermes Skill Hub)
+你可以通过以下命令将服务快捷添加到 Hermes 并重启：
+```bash
+hermes mcp add gecho-bridge --command npx --args="-y" --args="@gecho-ai/gecho-bridge@latest"
+hermes restart
+```
+*重启后，可通过 `hermes mcp list` 检查安装状态。*
 
+### 方式三：在 Trae / Claude Desktop 等通用客户端配置
+在支持手动配置的 MCP 客户端中，打开对应的 `mcp.json` 或 `claude_desktop_config.json` 文件，添加如下节点：
 ```json
 {
   "mcpServers": {
@@ -35,75 +74,84 @@ Add the following to your `claude_desktop_config.json`:
 }
 ```
 
-### Cursor
-Go to Settings -> MCP.
-Add a new MCP server:
-- **Name**: gecho-bridge
-- **Type**: command
-- **Command**: `npx -y @gecho-ai/gecho-bridge@latest`
+---
 
-### Save Path Configuration
-Search results are persisted to a JSON file. You can control the save directory in two ways:
+## 🏁 快速开始与常见流程
 
-1. Pass `save_dir` in the MCP tool call arguments.
-2. Set environment variable `GECHO_DATA_DIR` for the MCP process.
+环境配置完毕并重启 AI 客户端后，你可以直接通过自然语言向 AI 下达指令。
 
-Priority order used by the service:
+### 🔍 基础搜索 (`tiktok_search`)
+适用于快速检索和收集视频数据。
+**你可以这样说：**
+- *"帮我搜索 TikTok 关键词 'portable blender'，返回点赞最高的前 10 条"*
+- *"搜索 'cat toy'，并把完整结果保存到 /Users/yourname/gecho-data"*
 
-1. `save_dir` from request arguments
-2. `GECHO_DATA_DIR` environment variable
-3. Default `data` directory (`path.join(__dirname, "..", "data")`)
+**执行流程：**
+1. AI 唤起本地浏览器的 Gecho 扩展进行搜索和自动滚动。
+2. 抓取完成后，海量数据会自动落盘到本地。
+3. AI 会在会话中为你精简总结前 20 条高赞结果。
 
-File naming:
+### 📈 深度洞察 (`tiktok_insight`)
+适用于品类调研和趋势分析。
+**你可以这样说：**
+- *"请对 'outdoor picnic mat' 做 tiktok_insight 分析"*
+- *"对比 'desk setup' 和 'minimal desk' 的热视频风格与互动量"*
 
-- Result file pattern: `<query>_search_results.json`
-- Query text is sanitized to a safe file name before writing.
+**执行流程：**
+1. 插件会下发异步洞察任务，并立即返回一个 `jobId`。
+2. **⚠️ 高危注意**：洞察分析涉及深度抓取和 AI 运算，耗时通常会**超过 5 分钟**。在执行期间，**请务必不要关闭浏览器插件或相关的 TikTok 页面**。
+3. 等待一段时间后，对 AI 说：*“用 check_insight_status 查询刚才任务的执行状态”* 来获取最终的分析报告。
 
-Example (Claude Desktop with `GECHO_DATA_DIR`):
+---
 
-```json
-{
-  "mcpServers": {
-    "gecho-bridge": {
-      "command": "npx",
-      "args": ["-y", "@gecho-ai/gecho-bridge@latest"],
-      "env": {
-        "GECHO_DATA_DIR": "/Users/yourname/gecho-data"
-      }
-    }
-  }
-}
-```
+## ⚙️ 存储配置
+
+为了更好地管理数据资产，抓取的海量结果需要落盘保存。插件支持以下优先级配置方式：
+
+1. **会话级（最高优先级）**：直接在对话时让 AI 指定 `save_dir`（必须为绝对路径）。
+2. **全局级**：配置环境变量 `GECHO_DATA_DIR` 来指定默认的数据保存目录。
+3. **默认回退**：若未指定，默认保存在工具自带的 `./data` 目录下。
 
-Example (Cursor command with env):
+*(注：所有保存的文件名均会自动进行安全化处理，避免非法字符导致写入失败。)*
 
+---
+
+## 🛠️ 排障指南
+
+### 1. 如何确认插件已加载？（以 OpenClaw 为例）
+执行：
 ```bash
-GECHO_DATA_DIR=/Users/yourname/gecho-data npx -y @gecho-ai/gecho-bridge@latest
+openclaw plugins info @gecho-ai/gecho-bridge
 ```
+如果安装成功，你应看到 `Status: loaded` 以及 `MCP servers: gecho-tiktok-search`。
 
-## Usage
+### 2. 报错：提示扩展未连接
+- 检查 Chrome 浏览器中的 Gecho 扩展是否已开启。
+- 确认当前浏览器环境中已登录 TikTok 账号，且 TikTok 页面未处于崩溃或无响应状态。
 
-Once configured, you can ask your AI:
+### 3. 报错：请求超时
+- 检查 TikTok 页面是否弹出了人机验证码（CAPTCHA），如果是，请手动滑动解决。
+- 若目标关键词本身结果极少或网络卡顿，可尝试更换更具体的关键词后重试。
 
-- "Search TikTok for 'cooking recipes'"
-- "Find trending TikTok videos about AI agents"
-- "Search TikTok for 'computer' and save to `/Users/yourname/data` (`save_dir`)"
+### 4. 报错：无法保存结果
+- 检查你让 AI 指定的 `save_dir` 是否为合法的绝对路径。
+- 确认当前系统用户是否具有该目标目录的写入权限。
 
-## Development
+---
 
-If you want to run the bridge locally from source:
+## 🧑‍💻 本地开发
 
+对于希望基于本工具进行二次开发的开发者：
 ```bash
 git clone https://github.com/gecho-ai/bridge.git
 cd bridge
 npm install
-node mcp-client.js
+npm run server
 ```
 
-## Architecture
-
-- **Service Layer (server.js)**: Maintains the WebSocket connection with the Chrome extension (Port 18792) and exposes an HTTP API (Port 18793).
-- **Client Layer (mcp-client.js)**: Implements the MCP Stdio protocol and forwards requests to the Service Layer.
+**双层架构说明：**
+- **Client 层** (`mcp-client.js`)：标准 MCP STDIO 接入层，负责与 OpenClaw/Hermes/Trae 等客户端通信，并声明 Tools 规范。
+- **Service 层** (`server.js`)：本地常驻服务层，负责与浏览器扩展通过 WebSocket 通信，执行实际抓取与落盘。（支持 Lazy Start 机制，仅在需要时自动拉起）。
 
 ## License