@gecho-ai/gecho-bridge 1.1.7 → 1.1.19

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 (11) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/README.md +107 -79
  3. package/README.zh.md +186 -0
  4. package/mcp-client.js +15 -4
  5. package/openclaw.plugin.json +14 -0
  6. package/package.json +18 -4
  7. package/qywx.jpg +0 -0
  8. package/skills/tiktok-search/SKILL.md +271 -45
  9. package/skills/tiktok-search/_meta.json +1 -1
  10. package/README.en.md +0 -158
  11. package/skills/tiktok-search/README.md +0 -137
package/.claude-plugin/plugin.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "@gecho-ai/gecho-bridge",
3
- "version": "1.1.7",
3
+ "version": "1.1.19",
4
4
  "description": "TikTok Search Tool for OpenClaw"
5
5
  }
package/README.md CHANGED
@@ -1,68 +1,84 @@
1
1
  # Gecho Bridge 🚀
2
2
 
3
- 🌐 **Gecho Bridge** 是一款通用的 MCP（Model Context Protocol）工具，旨在为你的大语言模型（LLM）与本地浏览器之间搭建一座桥梁。
4
- 安装后，无论是使用 **OpenClaw**、**Hermes** 还是 **Trae**，你的 AI 助手都能直接控制浏览器，自动化完成 TikTok 搜索、数据抓取与深度商机洞察。
3
+ 🌐 **Gecho Bridge** is a universal MCP (Model Context Protocol) tool designed to build a bridge between your large language model (LLM) and your local browser.
4
+ After installation, whether you use **OpenClaw**, **Hermes**, or **Trae**, your AI assistant can directly control the browser to automate TikTok search, data collection, and deep business opportunity insights.
5
5
 
6
6
  ---
7
7
 
8
- ## ✨ 适合谁用
8
+ ## ✨ Who Is It For
9
9
 
10
- - 📊 **分析竞品**：输入关键词，快速获取 TikTok 前排高赞视频的各项互动数据。
11
- - 💡 **寻找爆款**：使用深度洞察工具分析特定品类（如 "portable blender"）的流行趋势，捕捉未被满足的市场蓝海。
12
- - 🤖 **自动化运营**：让大模型直接指挥浏览器，自动翻页抓取并生成数据报表，免去繁琐的手动统计。
10
+ - 📊 **Competitor analysis**: Enter a keyword and quickly get engagement data for top TikTok videos.
11
+ - 💡 **Finding winning products**: Use deep insight tools to analyze trends in specific categories (such as "portable blender") and identify underserved blue-ocean opportunities.
12
+ - 🤖 **Automated operations**: Let a large model directly control the browser, auto-scroll, scrape data, and generate reports, eliminating tedious manual counting.
13
13
 
14
- ## 🚀 能做什么
14
+ ## 🚀 What It Can Do
15
15
 
16
- - 自动唤起 Chrome 并在 TikTok 搜索指定关键词，模拟真人自然滚动加载。
17
- - 抓取海量结构化数据（视频 ID、标题、点赞量、播放链接等）并自动安全落盘为 JSON 文件。
18
- - 执行基于大数据检索的**异步深度洞察**，智能提炼爆款趋势与潜在商机。
16
+ - Automatically launch Chrome, search TikTok for a target keyword, and simulate natural human-like scrolling.
17
+ - Collect large volumes of structured data (video ID, title, likes, playback link, and more) and safely save it as JSON files.
18
+ - Run **asynchronous deep insights** based on large-scale retrieval to intelligently summarize winning-product trends and potential business opportunities.
19
19
 
20
- ## 🔗 相关链接
20
+ ## 🔗 Related Links
21
21
 
22
- - **官网**：[https://gecho.ai/](https://gecho.ai/)
23
- - **ClawHub 插件页**：[https://clawhub.ai/plugins/gecho-bridge](https://clawhub.ai/plugins/gecho-bridge)
24
- - **Chrome 浏览器扩展**：[前往 Chrome 网上应用店下载](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
22
+ - **Official Website**: [https://gecho.ai/](https://gecho.ai/)
23
+ - **GitHub**: [https://github.com/gecho-ai/gecho-bridge](https://github.com/gecho-ai/gecho-bridge)
24
+ - **ClawHub Plugin Page**: [https://clawhub.ai/p/gecho-ai](https://clawhub.ai/p/gecho-ai)
25
+ - **Chrome Browser Extension**: [Install from Chrome Web Store](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
26
+
27
+ ## 💬 Community & Feedback
28
+
29
+ Welcome to join our community for discussion or feedback:
30
+
31
+ - **Discord Community**: [Join Discord](https://discord.gg/RFDVZMR6Tn)
32
+ - **WeCom Group**: Scan the QR code below to join
33
+
34
+ ![WeCom QR Code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)
25
35
 
26
36
  ---
27
37
 
28
- ## 📦 安装与配置
38
+ ## 📦 Installation & Setup
29
39
 
30
- 本项目基于标准 MCP 协议开发，可以无缝接入任何支持 MCP 的 AI 客户端（如 OpenClaw、Hermes、Trae 等）。
40
+ This project is built on the standard MCP protocol and can be seamlessly integrated into any AI client that supports MCP (such as OpenClaw, Hermes, and Trae).
31
41
 
32
- ### 0. 前置环境要求
33
- 1. **Node.js**：>= 18（需支持 `npm` / `npx`）。
34
- 2. **浏览器扩展**：请先[点击此处安装 Gecho 浏览器扩展](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)。
35
- 3. **网络与状态**：确保本地网络可稳定访问 TikTok，并在浏览器中登录账号，保持扩展在线。
42
+ **One key point first:**
43
+ The **Skill** on ClawHub mainly provides calling instructions for the large model. It is not the server itself. To actually search TikTok, you still need to configure the `gecho-bridge` MCP service in your client and install the browser extension.
36
44
 
37
- ### 方式一：在 OpenClaw 中一键安装 (ClawHub)
38
- ClawHub 中有两种安装方式：`Skill` 与 `Plugin`。
45
+ ### 0. Prerequisites
46
+ 1. **Node.js**: >= 18 (must support `npm` / `npx`).
47
+ 2. **Browser extension**: Please [install the Gecho browser extension here first](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).
48
+ 3. **Network and state**: Make sure your local network can access TikTok reliably, and log in to both your browser account and the browser extension.
39
49
 
40
- #### 方案 A：Skill 安装（需先配置 MCP）
41
- Skill 安装后会通过 MCP 调用执行，因此需要先完成以下 MCP 配置：
50
+ ### Option 1: One-Click Installation in OpenClaw (ClawHub)
51
+ ClawHub offers two installation types: `Skill` and `Plugin`.
52
+
53
+ #### Plan A: Skill Install (MCP Must Be Configured First)
54
+ If you install the **Skill** from ClawHub, please note: **installing only the Skill page is not enough**. After installation, the Skill runs through MCP calls, so you need to complete the following MCP setup first:
42
55
  ```bash
43
56
  openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
44
57
  openclaw gateway restart
45
58
  ```
46
- *配置后，可通过 `openclaw mcp list` 检查状态。*
47
- *完成 MCP 配置后，再回到 ClawHub 选择 Skill 安装即可。*
59
+ *After configuration, you can check the status with `openclaw mcp list`.*
60
+ *Once MCP is configured, go back to ClawHub and use the Skill.*
48
61
 
49
- #### 方案 B：Plugin 安装（推荐）
62
+ #### Plan B: Plugin Install (Recommended)
50
63
  ```bash
51
- openclaw plugins install @gecho-ai/gecho-bridge
64
+ openclaw plugins install clawhub:@gecho-ai/gecho-bridge-bundle
52
65
  openclaw gateway restart
53
66
  ```
54
- *如需升级已安装的版本，使用 `openclaw plugins update @gecho-ai/gecho-bridge` 即可。*
67
+ *This is the more hassle-free installation method. After installation, you generally do not need to separately configure the MCP that the Skill depends on.*
68
+ *If you need to upgrade an installed version, use `openclaw plugins update clawhub:@gecho-ai/gecho-bridge-bundle`.*
69
+ *The plugin will automatically start a local Gecho service when needed. If the browser extension was opened after the client, run `openclaw gateway restart` once to reconnect cleanly.*
55
70
 
56
- ### 方式二：在 Hermes 中一键配置 (Hermes Skill Hub)
57
- 你可以通过以下命令将服务快捷添加到 Hermes 并重启：
71
+ ### Option 2: One-Click Setup in Hermes (Hermes Skill Hub)
72
+ You can quickly add the service to Hermes and restart it with the following commands:
58
73
  ```bash
59
74
  hermes mcp add gecho-bridge --command npx --args="-y" --args="@gecho-ai/gecho-bridge@latest"
75
+
60
76
  hermes restart
61
77
  ```
62
- *重启后，可通过 `hermes mcp list` 检查安装状态。*
78
+ *After restart, you can check the installation status with `hermes mcp list`.*
63
79
 
64
- ### 方式三：在 Trae / Claude Desktop 等通用客户端配置
65
- 在支持手动配置的 MCP 客户端中，打开对应的 `mcp.json` 或 `claude_desktop_config.json` 文件，添加如下节点：
80
+ ### Option 3: Configure in General Clients Such as Trae / Claude Desktop
81
+ In MCP clients that support manual configuration, open the corresponding `mcp.json` or `claude_desktop_config.json` file and add the following node:
66
82
  ```json
67
83
  {
68
84
  "mcpServers": {
@@ -76,72 +92,84 @@ hermes restart
76
92
 
77
93
  ---
78
94
 
79
- ## 🏁 快速开始与常见流程
95
+ ## 🏁 Quick Start & Common Workflows
80
96
 
81
- 环境配置完毕并重启 AI 客户端后，你可以直接通过自然语言向 AI 下达指令。
97
+ After the environment is configured and your AI client has restarted, you can directly issue instructions to the AI in natural language.
82
98
 
83
- ### 🔍 基础搜索 (`tiktok_search`)
84
- 适用于快速检索和收集视频数据。
85
- **你可以这样说：**
86
- - *"帮我搜索 TikTok 关键词 'portable blender'，返回点赞最高的前 10 条"*
87
- - *"搜索 'cat toy'，并把完整结果保存到 /Users/yourname/gecho-data"*
99
+ ### ✅ Self-Check Before First Use
100
+ 1. `gecho-bridge` MCP is configured, or the `@gecho-ai/gecho-bridge-bundle` plugin is installed.
101
+ 2. The [Gecho browser extension](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb) is installed.
102
+ 3. TikTok is open in Chrome and the account is logged in.
103
+ 4. The Gecho extension is logged in and online, and the TikTok page is not stuck or left on a CAPTCHA page.
88
104
 
89
- **执行流程：**
90
- 1. AI 唤起本地浏览器的 Gecho 扩展进行搜索和自动滚动。
91
- 2. 抓取完成后，海量数据会自动落盘到本地。
92
- 3. AI 会在会话中为你精简总结前 20 条高赞结果。
105
+ ### 🔍 Basic Search (`tiktok_search`)
106
+ Suitable for quickly retrieving and collecting video data.
107
+ **You can say:**
108
+ - *"Search TikTok for the keyword 'portable blender' and return the top 10 by likes."*
109
+ - *"Search 'cat toy' and save the full results to /Users/yourname/gecho-data."*
93
110
 
94
- ### 📈 深度洞察 (`tiktok_insight`)
95
- 适用于品类调研和趋势分析。
96
- **你可以这样说：**
97
- - *"请对 'outdoor picnic mat' 做 tiktok_insight 分析"*
98
- - *"对比 'desk setup' 和 'minimal desk' 的热视频风格与互动量"*
111
+ **Execution flow:**
112
+ 1. The AI triggers the local Gecho browser extension to perform the search and auto-scroll.
113
+ 2. After scraping is complete, large volumes of data are automatically saved locally.
114
+ 3. The AI summarizes the top 20 most-liked results for you in the conversation.
99
115
 
100
- **执行流程：**
101
- 1. 插件会下发异步洞察任务，并立即返回一个 `jobId`。
102
- 2. **⚠️ 高危注意**：洞察分析涉及深度抓取和 AI 运算，耗时通常会**超过 5 分钟**。在执行期间，**请务必不要关闭浏览器插件或相关的 TikTok 页面**。
103
- 3. 等待一段时间后，对 AI 说：*“用 check_insight_status 查询刚才任务的执行状态”* 来获取最终的分析报告。
116
+ ### 📈 Deep Insight (`tiktok_insight`)
117
+ Suitable for category research and trend analysis.
118
+ **You can say:**
119
+ - *"Please run tiktok_insight analysis for 'outdoor picnic mat'."*
120
+ - *"Compare the hot video styles and engagement of 'desk setup' and 'minimal desk'."*
121
+
122
+ **Execution flow:**
123
+ 1. The plugin submits an asynchronous insight task and immediately returns a `jobId`.
124
+ 2. **⚠️ Note**: Deep insight analysis involves heavy scraping and AI computation, and usually takes **more than 5 minutes**. During execution, **do not close the browser extension or the related TikTok page**.
125
+ 3. After waiting for a while, say to the AI: *"Use check_insight_status to query the status of the previous task"* to get the final analysis report.
126
+ 4. If it returns `running`, the task is still being processed. Please continue waiting and query again later.
104
127
 
105
128
  ---
106
129
 
107
- ## ⚙️ 存储配置
130
+ ## ⚙️ Storage Configuration
108
131
 
109
- 为了更好地管理数据资产，抓取的海量结果需要落盘保存。插件支持以下优先级配置方式：
132
+ To better manage data assets, the large amount of scraped results needs to be saved to disk. The plugin supports the following priority order:
110
133
 
111
- 1. **会话级（最高优先级）**：直接在对话时让 AI 指定 `save_dir`（必须为绝对路径）。
112
- 2. **全局级**：配置环境变量 `GECHO_DATA_DIR` 来指定默认的数据保存目录。
113
- 3. **默认回退**：若未指定，默认保存在工具自带的 `./data` 目录下。
134
+ 1. **Session level (highest priority)**: Ask the AI to specify `save_dir` directly during the conversation (must be an absolute path).
135
+ 2. **Global level**: Configure the environment variable `GECHO_DATA_DIR` to specify the default data save directory.
136
+ 3. **Default fallback**: If not specified, data is saved to the tool's built-in `./data` directory by default.
114
137
 
115
- *(注：所有保存的文件名均会自动进行安全化处理，避免非法字符导致写入失败。)*
138
+ *(Note: All saved filenames are automatically sanitized to avoid write failures caused by invalid characters.)*
116
139
 
117
140
  ---
118
141
 
119
- ## 🛠️ 排障指南
142
+ ## 🛠️ Troubleshooting
120
143
 
121
- ### 1. 如何确认插件已加载？（以 OpenClaw 为例）
122
- 执行：
144
+ ### 1. How to confirm the plugin is loaded? (Using OpenClaw as an example)
145
+ Run:
123
146
  ```bash
124
- openclaw plugins info @gecho-ai/gecho-bridge
147
+ openclaw plugins info @gecho-ai/gecho-bridge-bundle
125
148
  ```
126
- 如果安装成功，你应看到 `Status: loaded` 以及 `MCP servers: gecho-tiktok-search`。
149
+ If installation is successful, you should see `Status: loaded` and `MCP servers: gecho-tiktok-search`.
150
+
151
+ ### 2. Note about the local background service
152
+ - Gecho Bridge automatically starts a local service on demand so the MCP client can talk to the browser extension.
153
+ - This service only listens on `127.0.0.1` and is expected to stay available while you use the plugin.
154
+ - If Chrome or the extension was restarted and requests start failing, first run `openclaw gateway restart`, then try again.
127
155
 
128
- ### 2. 报错：提示扩展未连接
129
- - 检查 Chrome 浏览器中的 Gecho 扩展是否已开启。
130
- - 确认当前浏览器环境中已登录 TikTok 账号，且 TikTok 页面未处于崩溃或无响应状态。
156
+ ### 3. Error: Extension not connected
157
+ - Check whether the Gecho extension in Chrome is enabled.
158
+ - Confirm that the TikTok account is logged in in the current browser environment, and that the TikTok page is not crashed or unresponsive.
131
159
 
132
- ### 3. 报错：请求超时
133
- - 检查 TikTok 页面是否弹出了人机验证码（CAPTCHA），如果是，请手动滑动解决。
134
- - 若目标关键词本身结果极少或网络卡顿，可尝试更换更具体的关键词后重试。
160
+ ### 4. Error: Request timeout
161
+ - Check whether a TikTok CAPTCHA challenge has appeared. If so, solve it manually first.
162
+ - If the target keyword has very few results or the network is unstable, try a more specific keyword and retry.
135
163
 
136
- ### 4. 报错：无法保存结果
137
- - 检查你让 AI 指定的 `save_dir` 是否为合法的绝对路径。
138
- - 确认当前系统用户是否具有该目标目录的写入权限。
164
+ ### 5. Error: Failed to save results
165
+ - Check whether the `save_dir` you asked the AI to specify is a valid absolute path.
166
+ - Confirm that the current system user has write permission for the target directory.
139
167
 
140
168
  ---
141
169
 
142
- ## 🧑‍💻 本地开发
170
+ ## 🧑‍💻 Local Development
143
171
 
144
- 对于希望基于本工具进行二次开发的开发者：
172
+ For developers who want to build on top of this tool:
145
173
  ```bash
146
174
  git clone https://github.com/gecho-ai/bridge.git
147
175
  cd bridge
@@ -149,9 +177,9 @@ npm install
149
177
  npm run server
150
178
  ```
151
179
 
152
- **双层架构说明：**
153
- - **Client 层** (`mcp-client.js`)：标准 MCP STDIO 接入层，负责与 OpenClaw/Hermes/Trae 等客户端通信，并声明 Tools 规范。
154
- - **Service 层** (`server.js`)：本地常驻服务层，负责与浏览器扩展通过 WebSocket 通信，执行实际抓取与落盘。（支持 Lazy Start 机制，仅在需要时自动拉起）。
180
+ **Two-layer architecture description:**
181
+ - **Client layer** (`mcp-client.js`): The standard MCP STDIO integration layer, responsible for communicating with clients such as OpenClaw, Hermes, and Trae, and declaring the Tools specification.
182
+ - **Service layer** (`server.js`): The local resident service layer, responsible for communicating with the browser extension via WebSocket and executing the actual scraping and persistence. (Supports a Lazy Start mechanism and launches only when needed.)
155
183
 
156
184
  ## License
157
185
 
package/README.zh.md ADDED
@@ -0,0 +1,186 @@
1
+ # Gecho Bridge 🚀
2
+
3
+ 🌐 **Gecho Bridge** 是一款通用的 MCP（Model Context Protocol）工具，旨在为你的大语言模型（LLM）与本地浏览器之间搭建一座桥梁。
4
+ 安装后，无论是使用 **OpenClaw**、**Hermes** 还是 **Trae**，你的 AI 助手都能直接控制浏览器，自动化完成 TikTok 搜索、数据抓取与深度商机洞察。
5
+
6
+ ---
7
+
8
+ ## ✨ 适合谁用
9
+
10
+ - 📊 **分析竞品**：输入关键词，快速获取 TikTok 前排高赞视频的各项互动数据。
11
+ - 💡 **寻找爆款**：使用深度洞察工具分析特定品类（如 "portable blender"）的流行趋势，捕捉未被满足的市场蓝海。
12
+ - 🤖 **自动化运营**：让大模型直接指挥浏览器，自动翻页抓取并生成数据报表，免去繁琐的手动统计。
13
+
14
+ ## 🚀 能做什么
15
+
16
+ - 自动唤起 Chrome 并在 TikTok 搜索指定关键词，模拟真人自然滚动加载。
17
+ - 抓取海量结构化数据（视频 ID、标题、点赞量、播放链接等）并自动安全落盘为 JSON 文件。
18
+ - 执行基于大数据检索的**异步深度洞察**，智能提炼爆款趋势与潜在商机。
19
+
20
+ ## 🔗 相关链接
21
+
22
+ - **官网**：[https://gecho.ai/](https://gecho.ai/)
23
+ - **GitHub**：[https://github.com/gecho-ai/gecho-bridge](https://github.com/gecho-ai/gecho-bridge)
24
+ - **ClawHub 插件页**：[https://clawhub.ai/p/gecho-ai](https://clawhub.ai/p/gecho-ai)
25
+ - **Chrome 浏览器扩展**：[前往 Chrome 网上应用店下载](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
26
+
27
+ ## 💬 交流与反馈
28
+
29
+ 欢迎加入我们的社区进行交流或反馈问题：
30
+
31
+ - **Discord 社区**：[点击加入 Discord](https://discord.gg/RFDVZMR6Tn)
32
+ - **企业微信群**：扫描下方二维码加入
33
+
34
+ ![企业微信二维码](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg)
35
+
36
+ ---
37
+
38
+ ## 📦 安装与配置
39
+
40
+ 本项目基于标准 MCP 协议开发，可以无缝接入任何支持 MCP 的 AI 客户端（如 OpenClaw、Hermes、Trae 等）。
41
+
42
+ **先说明一个关键点：**
43
+ ClawHub 上的 **Skill** 主要提供给大模型的调用指令，本身不是服务端。想要真正搜索 TikTok，你还需要把 `gecho-bridge` MCP 服务配置到客户端里，并安装浏览器扩展。
44
+
45
+ ### 0. 前置环境要求
46
+ 1. **Node.js**：>= 18（需支持 `npm` / `npx`）。
47
+ 2. **浏览器扩展**：请先[点击此处安装 Gecho 浏览器扩展](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)。
48
+ 3. **网络与状态**：确保本地网络可稳定访问 TikTok，并在浏览器中登录账号，登录浏览器扩展。
49
+
50
+ ### 方式一：在 OpenClaw 中一键安装 (ClawHub)
51
+ ClawHub 中有两种安装方式：`Skill` 与 `Plugin`。
52
+
53
+ #### 方案 A：Skill 安装（需先配置 MCP）
54
+ 如果你安装的是 ClawHub 上的 **Skill**，请注意：**只安装 Skill 页面还不够**。Skill 安装后会通过 MCP 调用执行，因此需要先完成以下 MCP 配置：
55
+ ```bash
56
+ openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
57
+ openclaw gateway restart
58
+ ```
59
+ *配置后，可通过 `openclaw mcp list` 检查状态。*
60
+ *完成 MCP 配置后，再回到 ClawHub 使用 Skill 即可。*
61
+
62
+ #### 方案 B：Plugin 安装（推荐）
63
+ ```bash
64
+ openclaw plugins install clawhub:@gecho-ai/gecho-bridge-bundle
65
+ openclaw gateway restart
66
+ ```
67
+ *这是更省心的安装方式。安装完成后，一般不需要再单独配置 Skill 所依赖的 MCP。*
68
+ *如需升级已安装的版本，使用 `openclaw plugins update clawhub:@gecho-ai/gecho-bridge-bundle` 即可。*
69
+ *插件会在需要时自动启动本地 Gecho Service。如果是先打开了客户端、后打开浏览器扩展，建议再执行一次 `openclaw gateway restart` 重新建立连接。*
70
+
71
+ ### 方式二：在 Hermes 中一键配置 (Hermes Skill Hub)
72
+ 你可以通过以下命令将服务快捷添加到 Hermes 并重启：
73
+ ```bash
74
+ hermes mcp add gecho-bridge --command npx --args="-y" --args="@gecho-ai/gecho-bridge@latest"
75
+
76
+ hermes restart
77
+ ```
78
+ *重启后，可通过 `hermes mcp list` 检查安装状态。*
79
+
80
+ ### 方式三：在 Trae / Claude Desktop 等通用客户端配置
81
+ 在支持手动配置的 MCP 客户端中，打开对应的 `mcp.json` 或 `claude_desktop_config.json` 文件，添加如下节点：
82
+ ```json
83
+ {
84
+ "mcpServers": {
85
+ "gecho-bridge": {
86
+ "command": "npx",
87
+ "args": ["-y", "@gecho-ai/gecho-bridge@latest"]
88
+ }
89
+ }
90
+ }
91
+ ```
92
+
93
+ ---
94
+
95
+ ## 🏁 快速开始与常见流程
96
+
97
+ 环境配置完毕并重启 AI 客户端后，你可以直接通过自然语言向 AI 下达指令。
98
+
99
+ ### ✅ 首次使用前自检
100
+ 1. 已配置 `gecho-bridge` MCP，或已安装 `@gecho-ai/gecho-bridge-bundle` Plugin。
101
+ 2. 已安装 [Gecho 浏览器扩展](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)。
102
+ 3. Chrome 中已打开 TikTok 并登录账号。
103
+ 4. Gecho 扩展已登录并处于在线状态，TikTok 页面未卡住或未停在验证码页面。
104
+
105
+ ### 🔍 基础搜索 (`tiktok_search`)
106
+ 适用于快速检索和收集视频数据。
107
+ **你可以这样说：**
108
+ - *"帮我搜索 TikTok 关键词 'portable blender'，返回点赞最高的前 10 条"*
109
+ - *"搜索 'cat toy'，并把完整结果保存到 /Users/yourname/gecho-data"*
110
+
111
+ **执行流程：**
112
+ 1. AI 唤起本地浏览器的 Gecho 扩展进行搜索和自动滚动。
113
+ 2. 抓取完成后，海量数据会自动落盘到本地。
114
+ 3. AI 会在会话中为你精简总结前 20 条高赞结果。
115
+
116
+ ### 📈 深度洞察 (`tiktok_insight`)
117
+ 适用于品类调研和趋势分析。
118
+ **你可以这样说：**
119
+ - *"请对 'outdoor picnic mat' 做 tiktok_insight 分析"*
120
+ - *"对比 'desk setup' 和 'minimal desk' 的热视频风格与互动量"*
121
+
122
+ **执行流程：**
123
+ 1. 插件会下发异步洞察任务，并立即返回一个 `jobId`。
124
+ 2. **⚠️ 注意**：洞察分析涉及深度抓取和 AI 运算，耗时通常会**超过 5 分钟**。在执行期间，**请务必不要关闭浏览器插件或相关的 TikTok 页面**。
125
+ 3. 等待一段时间后，对 AI 说：*“用 check_insight_status 查询刚才任务的执行状态”* 来获取最终的分析报告。
126
+ 4. 如果返回 `running`，说明任务还在处理，请继续等待后再次查询。
127
+
128
+ ---
129
+
130
+ ## ⚙️ 存储配置
131
+
132
+ 为了更好地管理数据资产，抓取的海量结果需要落盘保存。插件支持以下优先级配置方式：
133
+
134
+ 1. **会话级（最高优先级）**：直接在对话时让 AI 指定 `save_dir`（必须为绝对路径）。
135
+ 2. **全局级**：配置环境变量 `GECHO_DATA_DIR` 来指定默认的数据保存目录。
136
+ 3. **默认回退**：若未指定，默认保存在工具自带的 `./data` 目录下。
137
+
138
+ *(注：所有保存的文件名均会自动进行安全化处理，避免非法字符导致写入失败。)*
139
+
140
+ ---
141
+
142
+ ## 🛠️ 排障指南
143
+
144
+ ### 1. 如何确认插件已加载？（以 OpenClaw 为例）
145
+ 执行：
146
+ ```bash
147
+ openclaw plugins info @gecho-ai/gecho-bridge-bundle
148
+ ```
149
+ 如果安装成功，你应看到 `Status: loaded` 以及 `MCP servers: gecho-tiktok-search`。
150
+
151
+ ### 2. 关于本地后台服务的说明
152
+ - Gecho Bridge 会在需要时自动拉起本地服务，用来让 MCP 客户端和浏览器扩展通信。
153
+ - 这个服务只监听 `127.0.0.1`，在你使用插件期间保持可用属于正常行为。
154
+ - 如果你重启了 Chrome 或扩展，随后请求开始失败，先执行一次 `openclaw gateway restart`，再重试。
155
+
156
+ ### 3. 报错：提示扩展未连接
157
+ - 检查 Chrome 浏览器中的 Gecho 扩展是否已开启。
158
+ - 确认当前浏览器环境中已登录 TikTok 账号，且 TikTok 页面未处于崩溃或无响应状态。
159
+
160
+ ### 4. 报错：请求超时
161
+ - 检查 TikTok 页面是否弹出了人机验证码（CAPTCHA），如果是，请手动滑动解决。
162
+ - 若目标关键词本身结果极少或网络卡顿，可尝试更换更具体的关键词后重试。
163
+
164
+ ### 5. 报错：无法保存结果
165
+ - 检查你让 AI 指定的 `save_dir` 是否为合法的绝对路径。
166
+ - 确认当前系统用户是否具有该目标目录的写入权限。
167
+
168
+ ---
169
+
170
+ ## 🧑‍💻 本地开发
171
+
172
+ 对于希望基于本工具进行二次开发的开发者：
173
+ ```bash
174
+ git clone https://github.com/gecho-ai/bridge.git
175
+ cd bridge
176
+ npm install
177
+ npm run server
178
+ ```
179
+
180
+ **双层架构说明：**
181
+ - **Client 层** (`mcp-client.js`)：标准 MCP STDIO 接入层，负责与 OpenClaw/Hermes/Trae 等客户端通信，并声明 Tools 规范。
182
+ - **Service 层** (`server.js`)：本地常驻服务层，负责与浏览器扩展通过 WebSocket 通信，执行实际抓取与落盘。（支持 Lazy Start 机制，仅在需要时自动拉起）。
183
+
184
+ ## License
185
+
186
+ MIT
package/mcp-client.js CHANGED
@@ -9,6 +9,7 @@
9
9
  * 4. 转发工具请求到 Service 层。
10
10
  */
11
11
 
12
+ const fs = require("fs");
12
13
  const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
13
14
  const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
14
15
  const {
@@ -19,15 +20,25 @@ const http = require("http");
19
20
  const cpModule = "child" + "_process";
20
21
  const { spawn } = require(cpModule);
21
22
  const path = require("path");
23
+ const packageJson = require("./package.json");
22
24
 
23
25
  const SERVICE_BASE_URL = "http://127.0.0.1:18793";
24
26
  const HTTP_SERVICE_URL = `${SERVICE_BASE_URL}/search`;
25
27
  const PING_URL = `${SERVICE_BASE_URL}/ping`;
26
28
  const SHUTDOWN_URL = `${SERVICE_BASE_URL}/shutdown`;
27
- const SERVICE_PATH = path.join(__dirname, "server.js");
29
+ const DIST_SERVICE_PATH = path.join(__dirname, "server.cjs");
30
+ const SOURCE_SERVICE_PATH = path.join(__dirname, "server.js");
31
+ const SERVICE_PATH = fs.existsSync(DIST_SERVICE_PATH) ? DIST_SERVICE_PATH : SOURCE_SERVICE_PATH;
32
+ const SUPPORTED_TOOL_NAMES = new Set([
33
+ "tiktok_search",
34
+ "tiktok_insight",
35
+ "check_insight_status"
36
+ ]);
37
+
38
+ const CLIENT_VERSION = packageJson.version;
28
39
 
29
40
  const server = new Server(
30
- { name: "tiktok-bridge-client", version: "1.1.1" },
41
+ { name: "tiktok-bridge-client", version: CLIENT_VERSION },
31
42
  { capabilities: { tools: {} } }
32
43
  );
33
44
 
@@ -297,8 +308,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
297
308
  }
298
309
  }
299
310
 
300
- // 只要是 tiktok_ 开头的工具，都走通用转发逻辑
301
- if (toolName.startsWith("tiktok_") || toolName.startsWith("x_") || toolName.startsWith("ins_")) {
311
+ // 只转发已在 ListTools 中公开的官方工具，避免未文档化能力暴露出去
312
+ if (SUPPORTED_TOOL_NAMES.has(toolName) && toolName !== "check_insight_status") {
302
313
  // 设置进度上报定时器 (心跳)，防止 MCP 客户端超时
303
314
  let progressValue = 0;
304
315
 
package/openclaw.plugin.json ADDED
@@ -0,0 +1,14 @@
1
+ {
2
+ "id": "gecho-ai-gecho-bridge",
3
+ "name": "@gecho-ai/gecho-bridge",
4
+ "description": "TikTok Search and Insight tools for OpenClaw, connecting LLMs to TikTok via Chrome Extension.",
5
+ "version": "1.1.19",
6
+ "skills": [
7
+ "./skills"
8
+ ],
9
+ "configSchema": {
10
+ "type": "object",
11
+ "additionalProperties": false,
12
+ "properties": {}
13
+ }
14
+ }
package/package.json CHANGED
@@ -1,22 +1,33 @@
1
1
  {
2
2
  "name": "@gecho-ai/gecho-bridge",
3
- "version": "1.1.7",
4
- "description": "MCP Bridge for TikTok Extension Relay - Connecting LLMs to TikTok via Chrome Extension",
3
+ "version": "1.1.19",
4
+ "description": "TikTok Search and Insight tools for OpenClaw, connecting LLMs to TikTok via Chrome Extension.",
5
5
  "main": "mcp-client.js",
6
6
  "bin": {
7
7
  "gecho-bridge": "mcp-client.js"
8
8
  },
9
9
  "files": [
10
10
  "*.js",
11
+ "dist",
11
12
  "package.json",
12
13
  ".claude-plugin",
13
14
  ".mcp.json",
14
- "skills"
15
+ "openclaw.plugin.json",
16
+ "skills",
17
+ "README.md",
18
+ "README.zh.md",
19
+ "qywx.jpg"
15
20
  ],
16
21
  "scripts": {
17
22
  "start": "node mcp-client.js",
18
23
  "server": "node server.js",
19
- "setup": "openclaw plugins install -l ."
24
+ "setup": "openclaw plugins install -l .",
25
+ "sync:version": "node ./scripts/sync-version.js",
26
+ "build:bundle": "node ./scripts/build-bundle.js",
27
+ "bundle:stage": "bash ./scripts/publish-bundle-dist.sh stage",
28
+ "bundle:publish": "bash ./scripts/publish-bundle-dist.sh publish",
29
+ "bundle:stage:dist": "bash ./scripts/publish-bundle-dist.sh stage",
30
+ "bundle:publish:dist": "bash ./scripts/publish-bundle-dist.sh publish"
20
31
  },
21
32
  "keywords": [
22
33
  "mcp",
@@ -33,6 +44,9 @@
33
44
  "@modelcontextprotocol/sdk": "^1.27.1",
34
45
  "ws": "^8.19.0"
35
46
  },
47
+ "devDependencies": {
48
+ "esbuild": "^0.25.4"
49
+ },
36
50
  "publishConfig": {
37
51
  "access": "public"
38
52
  }
package/qywx.jpg ADDED
Binary file
package/skills/tiktok-search/SKILL.md CHANGED
@@ -1,15 +1,125 @@
1
1
  ---
2
2
  name: tiktok-search
3
- description: Professional TikTok keyword search and data extraction tool. Automates browsing and scraping via Chrome extension.
3
+ description: TikTok search and insight workflow for Gecho Bridge. Use when the user asks to search TikTok, find trending videos, analyze competitors, collect TikTok metadata, discover winning products, or run keyword trend research. Requires the Gecho Bridge MCP server plus the Gecho Chrome extension and an active TikTok session.
4
4
  ---
5
5
 
6
- # TikTok Search 🚀
6
+ # Gecho TikTok Search & Insight
7
7
 
8
- A specialized tool for searching and extracting video metadata from TikTok. It bridges your local Chrome browser via an extension to perform automated searches, scrolling, and data collection.
8
+ Search TikTok from your AI chat, extract structured video data, and run deeper insight jobs for product research, competitor analysis, and trend discovery.
9
9
 
10
- ## Tools
10
+ ## Why people install this
11
11
 
12
- ### `tiktok_search`
12
+ - Find top-performing TikTok videos for any keyword in minutes.
13
+ - Research competitors by pulling titles, likes, authors, and video links.
14
+ - Explore product demand and trend signals before creating content or choosing what to sell.
15
+ - Save large raw result sets to disk instead of manually copying data from the browser.
16
+
17
+ ## Best fit use cases
18
+
19
+ - Competitor research: "Show me the highest-liked TikTok videos for portable blender."
20
+ - Trend scouting: "Run insight for desk setup and tell me what styles are performing."
21
+ - Content research: "Find winning hooks and titles for cat toy videos."
22
+
23
+ ## Start here
24
+
25
+ This Skill is only the instruction layer. To actually work, you also need:
26
+
27
+ - the `gecho-bridge` MCP server
28
+ - the Gecho Chrome extension
29
+ - a logged-in TikTok session in Chrome
30
+
31
+ Need the full step-by-step setup guide? Read:
32
+ [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
33
+
34
+ ### If you installed this from ClawHub as a Skill
35
+
36
+ Installing the Skill page alone is not enough. You still need to configure MCP once:
37
+
38
+ ```bash
39
+ openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
40
+ openclaw gateway restart
41
+ ```
42
+
43
+ Then verify:
44
+
45
+ ```bash
46
+ openclaw mcp list
47
+ ```
48
+
49
+ Recommended easier path:
50
+
51
+ ```bash
52
+ openclaw plugins install clawhub:@gecho-ai/gecho-bridge-bundle
53
+ openclaw gateway restart
54
+ ```
55
+
56
+ When using the plugin route, Gecho Bridge may auto-start a local service process to talk to the Chrome extension. If the extension is reopened or Chrome restarts, run `openclaw gateway restart` once before retrying.
57
+
58
+ ### 30-second checklist
59
+
60
+ 1. Install the [Gecho Browser Extension](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).
61
+ 2. Install Node.js `>= 18`.
62
+ 3. Open Chrome, visit TikTok, and log in.
63
+ 4. Log in to the Gecho extension and keep it online.
64
+ 5. Make sure your local network can access TikTok normally.
65
+
66
+ ### First prompts to copy
67
+
68
+ - `"Search TikTok for 'portable blender' and show me the top liked videos."`
69
+ - `"Search 'cat toy' and save the full results to an absolute path."`
70
+ - `"Run tiktok_insight for 'outdoor picnic mat'."`
71
+
72
+ ### Workflow quick map
73
+
74
+ | Goal | Best Tool | Result |
75
+ |------|-----------|--------|
76
+ | Fast search, top videos, metadata export | `tiktok_search` | Returns a result set immediately |
77
+ | Deeper market research or trend analysis | `tiktok_insight` | Starts an async job and returns a `jobId` |
78
+ | Fetch the final insight report | `check_insight_status` | Reads async status or returns final results |
79
+
80
+ ### If first use fails
81
+
82
+ - MCP not configured: run the `openclaw mcp set ...` command above, then restart.
83
+ - Extension not connected: reopen Chrome, enable the extension, and keep a TikTok tab open.
84
+ - TikTok blocked or stuck: solve any CAPTCHA or login wall in the browser first.
85
+ - Insight still running: wait and then ask the AI to call `check_insight_status`.
86
+ - Need the full installation tutorial: [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
87
+
88
+ ---
89
+
90
+ ## 🤖 AI Agent Instructions (CRITICAL)
91
+
92
+ You are the execution guide for Gecho Bridge. Your job is to help the user succeed with the official TikTok MCP workflow, not to invent alternatives.
93
+
94
+ **CRITICAL AGENT INSTRUCTION:** You MUST NOT attempt to install Chrome, open browsers, solve CAPTCHA yourself, or replace the MCP workflow with generic WebSearch, built-in browser tools, or custom TikTok scrapers. Your ONLY responsibility is to use the official MCP tools and report exact outcomes.
95
+
96
+ ### When to use
97
+
98
+ | User Intent | Tool | Example |
99
+ |-------------|------|---------|
100
+ | Search TikTok, find top videos, export data | `tiktok_search` | "Search TikTok for cat toys" |
101
+ | Analyze a niche, trend, or product opportunity | `tiktok_insight` | "Analyze trends for outdoor picnic mat" |
102
+ | Check progress of a previous insight job | `check_insight_status` | "Check the status of my last insight job" |
103
+
104
+ ### Setup awareness rules
105
+
106
+ 1. If the user wants to use this skill for the first time and there has been no successful Gecho tool call in the current conversation, you MUST first perform a readiness check.
107
+ - Tell the user they need to finish the initial setup first.
108
+ - Provide the full installation guide: [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
109
+ - Remind them to:
110
+ - Configure MCP server (provide the `openclaw mcp set` command if using OpenClaw).
111
+ - Install and login to the Gecho Chrome Extension.
112
+ - Keep a logged-in TikTok tab open.
113
+ - **Community Support**: Suggest joining the [Discord](https://discord.gg/RFDVZMR6Tn) or scanning the [WeChat QR Code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg) for real-time help.
114
+ 2. If the user says they installed the Skill from ClawHub but tool usage fails, explicitly tell them that the Skill page alone is not enough and they must configure the `gecho-bridge` MCP server. Always include the tutorial link: [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
115
+ 3. When setup appears missing, provide the exact OpenClaw command from this file. Do not improvise different install commands.
116
+ 4. When setup appears confusing or the user asks for full installation steps, send them this official guide:
117
+ [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
118
+ 5. **Feedback Loop**: Always encourage users to report issues or share feedback in the [Discord](https://discord.gg/RFDVZMR6Tn) or [WeChat Group](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg).
119
+
120
+ ### Tools
121
+
122
+ #### `tiktok_search`
13
123
 
14
124
  Executes a keyword search, auto-scrolls to load results, and returns metadata.
15
125
 
@@ -22,9 +132,9 @@ Executes a keyword search, auto-scrolls to load results, and returns metadata.
22
132
 
23
133
  A JSON array containing video IDs, titles, like counts, play URLs, and author info.
24
134
 
25
- ### `tiktok_insight`
135
+ #### `tiktok_insight`
26
136
 
27
- Performs business insight and trend analysis based on TikTok search results.
137
+ Starts an asynchronous business insight and trend-analysis job based on TikTok search results.
28
138
 
29
139
  **Parameters:**
30
140
 
@@ -33,57 +143,173 @@ Performs business insight and trend analysis based on TikTok search results.
33
143
 
34
144
  **Returns:**
35
145
 
36
- A JSON array with analyzed insights and trends based on the search query.
146
+ A `jobId` for a long-running async task. The final report must be retrieved later with `check_insight_status`.
147
+
148
+ #### `check_insight_status`
149
+
150
+ Checks the status of a previously started async insight job.
37
151
 
38
- ## Prerequisites Check & Environment Setup
152
+ **Parameters:**
153
+
154
+ - `jobId` (string, required): The `jobId` returned by `tiktok_insight`.
39
155
 
40
- Before calling, ensure the following prerequisites are met:
41
- 1. **Node.js**: Installed in the local environment.
42
- 2. **Gecho TikTok Extension & Active Tab**: The **USER** must have Chrome open locally with the extension active and a TikTok tab open.
156
+ **Returns:**
43
157
 
44
- **⚠️ CRITICAL AGENT INSTRUCTION:**
45
- You (the Agent) MUST NOT attempt to install Chrome, open browsers, or use tools like `browser_navigate` to fulfill these prerequisites. Do NOT check for Chrome yourself. Your ONLY responsibility is to call the MCP tool.
158
+ Either a running status or the final insight result payload.
46
159
 
47
- ## Execution Rules & Constraints (CRITICAL)
160
+ ### Execution Rules & Constraints (CRITICAL)
48
161
 
49
- You MUST strictly adhere to the following rules when calling the MCP tools:
50
- 1. **Single Tool Call Limit**: You MUST NOT execute more than ONE tool call (`tiktok_search` OR `tiktok_insight`) per conversational turn. You MUST wait for the user's feedback before initiating another search or insight request.
51
- 2. **Strict Tool Binding (No Fallbacks)**: You MUST ONLY use the EXACT tools specified (`tiktok_search` or `tiktok_insight`) for TikTok searches. You are **STRICTLY FORBIDDEN** from falling back between these tools. For example, if the user asks for an insight (`tiktok_insight`) and it fails or times out, you MUST NOT try to call `tiktok_search` as a backup. Stop immediately and report the failure. You are also forbidden from using built-in browser tools, generic WebSearch, or writing Python scrapers to visit TikTok.com.
52
- 3. **Fail Fast & Explicit Reporting**: If the MCP tool fails, times out, or throws an error (e.g., `params is not defined`), you MUST STOP immediately. Do NOT offer alternative web search solutions. You MUST output the raw error message to the user.
53
- 4. **No Parallel Execution**: Since this tool controls an active Chrome tab, it is strictly single-threaded. You MUST NEVER execute multiple `tiktok_search` tool calls in parallel simultaneously. You must wait for one search to completely finish before starting another.
54
- 5. **Anti-Hallucination (No Fake Data)**: You MUST base your final response ONLY on the exact data returned by the tool. If the tool returns empty results (`[]`), you MUST NOT hallucinate or guess. Inform the user exactly what the tool returned.
55
- 6. **Anti-Spam (No Infinite Loops)**: NEVER call the tool repeatedly with the exact same `query` if it fails or returns empty results.
56
- 7. **No Retries (STRICT)**: If a call fails due to a timeout (`MCP error -32001`), network error, or any other reason, you MUST STOP immediately and return the error to the user. **DO NOT attempt to call the tool again** in the same turn or subsequent turns unless the user explicitly requests it.
57
- 8. **Timeout Awareness**: The `tiktok_insight` tool can take up to 5 minutes to complete. If you receive a timeout error, inform the user that the operation was too complex or that they should check their browser for a CAPTCHA.
58
- 9. **Output Summarization (Avoid Chat Spam)**: If the tool returns a large number of results (e.g., 200 videos), DO NOT print the entire raw JSON array in your chat response. You must summarize the top 3-5 results, and utilize the `save_dir` parameter to save the full dataset to the user's disk.
162
+ 1. **One Gecho tool call per turn**: You MUST NOT execute more than ONE tool call among `tiktok_search`, `tiktok_insight`, and `check_insight_status` in a single conversational turn.
163
+ 2. **Strict tool binding**: Use ONLY the official Gecho tools listed in this file for TikTok work. Do not replace them with WebSearch, browser automation, or ad-hoc scrapers.
164
+ 3. **No fallback between search and insight**: If `tiktok_insight` fails, do not silently switch to `tiktok_search`. If `tiktok_search` fails, do not silently switch to `tiktok_insight`.
165
+ 4. **Fail fast**: If any tool fails, times out, or throws an error, STOP immediately and return the exact error or the exact failure reason. Do not invent recovery steps beyond the troubleshooting section below.
166
+ 5. **No parallel execution**: These tools depend on a live browser tab and are strictly single-threaded. Never call them in parallel.
167
+ 6. **No same-turn retries**: If a tool fails, do not retry in the same turn. Wait for the user to ask again after they fix the environment.
168
+ 7. **No hallucinated results**: Base your response ONLY on returned tool data. If the tool returns `[]`, say that it returned no results.
169
+ 8. **Search result summarization**: If `tiktok_search` returns many results, summarize only the top 3 to 5 items and point the user to the saved file path.
170
+ 9. **Insight is async**: After calling `tiktok_insight`, do not pretend the report is finished. Report the `jobId`, explain that the job may take several minutes, and tell the user to use `check_insight_status`.
171
+ 10. **Running status behavior**: If `check_insight_status` says the job is still running, tell the user that clearly and recommend waiting before checking again.
59
172
 
60
- ## Troubleshooting & Error Handling (Decision Tree)
173
+ ### Troubleshooting & Error Handling (Decision Tree)
61
174
 
62
- If the `tiktok_search` tool execution fails, follow this decision tree to assist the user:
175
+ If any Gecho tool fails, use this decision tree:
63
176
 
64
177
  1. **Error: "MCP error -32001: Request timed out"**
65
- - → **STOP IMMEDIATELY**. Do not retry.
66
- - → Inform the user: *"The analysis/search is taking longer than expected. Please check your Chrome browser to see if TikTok is showing a CAPTCHA or if the page is stuck. You can try again after resolving any browser-side issues."*
178
+ - Stop immediately. Do not retry.
179
+ - Tell the user to check Chrome for a CAPTCHA, login wall, or a stuck TikTok page.
180
+ - If the user is still unsure about the environment, also send the full setup guide:
181
+ [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
182
+ - **Support**: Suggest joining the [Discord](https://discord.gg/RFDVZMR6Tn) or scanning the [WeChat QR Code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg) for help.
67
183
  2. **Error: "Chrome extension not found/connected"**
68
- - → Inform the user: *"Please ensure the Gecho TikTok Chrome extension is installed, enabled, and you have an active TikTok tab open in Chrome."*
69
- 3. **Error: "Timeout" (Service Level)**
70
- - → Inform the user: *"The service layer timed out. This usually happens if the search volume is extremely high. Try a more specific query."*
71
- 4. **Error: "Tool not found"**
72
- - → Inform the user: *"The tool is not registered. Please ensure the Gecho Bridge Plugin is installed and active."*
184
+ - Tell the user to install or enable the Gecho extension, open TikTok in Chrome, and log in.
185
+ - Include the extension link: [Gecho Extension](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
186
+ - Also include the full setup guide:
187
+ [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
188
+ - **Support**: Suggest joining the [Discord](https://discord.gg/RFDVZMR6Tn) or [WeChat Group](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg).
189
+ 3. **Error: tool not found / MCP server missing**
190
+ - Tell the user the `gecho-bridge` MCP server is not configured.
191
+ - For OpenClaw, provide:
192
+ ```bash
193
+ openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
194
+ openclaw gateway restart
195
+ ```
196
+ - Also include the full setup guide:
197
+ [README.md](https://github.com/gecho-ai/gecho-bridge/blob/main/README.md)
198
+ - **Support**: Suggest joining the [Discord](https://discord.gg/RFDVZMR6Tn) or [WeChat Group](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg) for configuration help.
199
+ 4. **Error: service timeout**
200
+ - Tell the user the request likely stalled due to a stuck page, network issue, or an overly broad query.
201
+ - Recommend a more specific keyword after the browser-side issue is resolved.
202
+ - **Support**: If it persists, suggest reporting it in [Discord](https://discord.gg/RFDVZMR6Tn) or [WeChat Group](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg).
203
+ 5. **`check_insight_status` returns running**
204
+ - Tell the user the insight job is still processing.
205
+ - Recommend waiting about 60 seconds before checking again.
206
+
207
+ ### Standard operating procedures
208
+
209
+ #### SOP: `tiktok_search`
210
+
211
+ 1. Generate a valid absolute `save_dir` if the user did not provide one.
212
+ 2. Call `tiktok_search`.
213
+ 3. Summarize the top results only.
214
+ 4. Tell the user where the full dataset was saved.
215
+
216
+ #### SOP: `tiktok_insight`
217
+
218
+ 1. Generate a valid absolute `save_dir` if the user did not provide one.
219
+ 2. Call `tiktok_insight`.
220
+ 3. Report the returned `jobId`.
221
+ 4. Tell the user that insight is asynchronous and usually takes several minutes.
222
+ 5. Tell the user to use `check_insight_status` later with that `jobId`.
223
+
224
+ #### SOP: `check_insight_status`
225
+
226
+ 1. Call `check_insight_status` with the provided `jobId`.
227
+ 2. If status is running, report that it is still processing.
228
+ 3. If status is completed, summarize the key findings and saved path.
229
+
230
+ ### Standard Output Format
231
+
232
+ When a tool returns successfully, use one of these formats.
233
+
234
+ #### Search completed
235
+
236
+ ```markdown
237
+ ✅ TikTok search complete
238
+ Data has been successfully saved to: `/path/to/your/save_dir.json`
239
+
240
+ Here are the top trending videos for your query:
241
+
242
+ | Title | Likes | Author | Link |
243
+ |-------|-------|--------|------|
244
+ | [Video Title 1] | 1.2M ❤️ | @user1 | [Watch](url) |
245
+ | [Video Title 2] | 800K ❤️ | @user2 | [Watch](url) |
246
+ | [Video Title 3] | 500K ❤️ | @user3 | [Watch](url) |
247
+
248
+ *(Showing top 3 results. Check the saved JSON file for the full dataset.)*
249
+
250
+ ---
251
+ 💬 **Need help or have feedback?** Join our [Discord](https://discord.gg/RFDVZMR6Tn) or scan the [WeChat QR Code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg).
252
+ ```
253
+
254
+ #### Insight job started
255
+
256
+ ```markdown
257
+ ✅ Insight job started
258
+ Job ID: `job_xxx`
259
+ Expected duration: usually a few minutes
260
+ Saved output path: `/path/to/your/save_dir.json`
261
+
262
+ Next step:
263
+ Ask me to run `check_insight_status` with this job ID after waiting a bit.
264
+
265
+ ---
266
+ 💬 **Need help or have feedback?** Join our [Discord](https://discord.gg/RFDVZMR6Tn) or scan the [WeChat QR Code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg).
267
+ ```
268
+
269
+ #### Insight still running
270
+
271
+ ```markdown
272
+ ⏳ Insight job still running
273
+ Job ID: `job_xxx`
274
+
275
+ The browser-side task is still processing. Please wait about 60 seconds and ask me to run `check_insight_status` again.
276
+ ```
277
+
278
+ #### Insight completed
279
+
280
+ ```markdown
281
+ ✅ Insight complete
282
+ Data has been saved to: `/path/to/your/save_dir.json`
283
+
284
+ Key findings:
285
+ - [Finding 1]
286
+ - [Finding 2]
287
+ - [Finding 3]
288
+
289
+ If you want, I can next help you compare this keyword with another one.
290
+
291
+ ---
292
+ 💬 **Need help or have feedback?** Join our [Discord](https://discord.gg/RFDVZMR6Tn) or scan the [WeChat QR Code](https://github.com/gecho-ai/gecho-bridge/blob/main/qywx.jpg).
293
+ ```
294
+
295
+ ### Scope
296
+
297
+ This skill SHOULD:
73
298
 
74
- ## Example Usage & Standard Operating Procedure (SOP)
299
+ - Guide the user to the official Gecho setup when prerequisites are missing
300
+ - Use the exact MCP tools defined above
301
+ - Summarize results clearly and point to saved files
302
+ - Keep search and insight flows separate and explicit
75
303
 
76
- When a user requests a TikTok search, follow this exact 4-step workflow:
77
- 1. **Determine Path**: Proactively generate a valid absolute path for `save_dir` based on the user's OS and current workspace.
78
- 2. **Execute**: Call `tiktok_search` with the `query` and `save_dir`.
79
- 3. **Process**: Wait for the JSON array.
80
- 4. **Report**: Inform the user where the raw JSON file was saved, and output a concise Markdown summary table (Title, Likes, Author, URL) for the top 3-5 videos only.
304
+ This skill MUST NEVER:
81
305
 
82
- Example:
83
- "Find trending videos for 'travel vlogs'"
84
- → Action: Call `tiktok_search` with `query="travel vlogs"` and `save_dir="/path/to/workspace/travel_vlogs_results.json"`
306
+ - Pretend the Skill page alone is enough if MCP is missing
307
+ - Pretend `tiktok_insight` is synchronous
308
+ - Use unofficial TikTok scraping workflows
309
+ - Hallucinate results or infer hidden data
85
310
 
86
- ## Limitations
311
+ ### Limitations
87
312
 
88
313
  - Requires an active user session in Chrome.
89
- - Only works via the MCP tool interface.
314
+ - Requires the `gecho-bridge` MCP server to be configured in the AI client.
315
+ - Only works via the MCP tool interface.
package/skills/tiktok-search/_meta.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "slug": "tiktok-search",
3
- "version": "1.1.7",
3
+ "version": "1.1.19",
4
4
  "type": "mcp",
5
5
  "publishedAt": 1775894233000
6
6
  }
package/README.en.md DELETED
@@ -1,158 +0,0 @@
1
- # Gecho Bridge 🚀
2
-
3
- 🌐 **Gecho Bridge** is a universal MCP (Model Context Protocol) tool designed to bridge your large language model (LLM) and your local browser.
4
- 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.
5
-
6
- ---
7
-
8
- ## ✨ Who Is It For
9
-
10
- - 📊 **Competitor analysis**: Input a keyword and quickly get engagement data from top TikTok posts.
11
- - 💡 **Finding winning products**: Use deep insight tools to analyze trends in specific niches (for example, "portable blender") and discover underserved opportunities.
12
- - 🤖 **Automated operations**: Let your AI model control the browser, scroll automatically, scrape results, and generate reports without manual counting.
13
-
14
- ## 🚀 What It Can Do
15
-
16
- - Launch Chrome automatically, search TikTok with a target keyword, and simulate natural human-like scrolling.
17
- - Collect large-scale structured data (video ID, title, likes, video link, and more) and safely save it as JSON files.
18
- - Run **asynchronous deep insights** powered by large-scale retrieval to summarize trends and potential business opportunities.
19
-
20
- ## 🔗 Links
21
-
22
- - **Official Website**: [https://gecho.ai/](https://gecho.ai/)
23
- - **ClawHub Plugin Page**: [https://clawhub.ai/plugins/gecho-bridge](https://clawhub.ai/plugins/gecho-bridge)
24
- - **Chrome Extension**: [Install from Chrome Web Store](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
25
-
26
- ---
27
-
28
- ## 📦 Installation & Setup
29
-
30
- This project follows the standard MCP protocol and can be integrated with any MCP-compatible AI client (such as OpenClaw, Hermes, and Trae).
31
-
32
- ### 0. Prerequisites
33
- 1. **Node.js**: >= 18 (with `npm` / `npx` support).
34
- 2. **Browser extension**: [Install the Gecho Chrome Extension first](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).
35
- 3. **Network and account state**: Ensure stable access to TikTok, keep your TikTok account logged in, and keep the extension online.
36
-
37
- ### Option 1: One-Click Setup in OpenClaw (ClawHub)
38
- ClawHub provides two installation paths: `Skill` and `Plugin`.
39
-
40
- #### Path A: Skill Install (MCP Required First)
41
- Skill installation executes through MCP, so you must configure MCP first:
42
- ```bash
43
- openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
44
- openclaw gateway restart
45
- ```
46
- *After configuration, run `openclaw mcp list` to verify status.*
47
- *Then return to ClawHub and install the Skill.*
48
-
49
- #### Path B: Plugin Install (Recommended)
50
- ```bash
51
- openclaw plugins install @gecho-ai/gecho-bridge
52
- openclaw gateway restart
53
- ```
54
- *To upgrade later, run `openclaw plugins update @gecho-ai/gecho-bridge`.*
55
-
56
- ### Option 2: One-Click Setup in Hermes (Hermes Skill Hub)
57
- Use the following commands to add the service in Hermes and restart:
58
- ```bash
59
- hermes mcp add gecho-bridge --command npx --args="-y" --args="@gecho-ai/gecho-bridge@latest"
60
- hermes restart
61
- ```
62
- *After restart, run `hermes mcp list` to verify installation status.*
63
-
64
- ### Option 3: Manual Setup for Trae / Claude Desktop and Other MCP Clients
65
- In clients that support manual MCP configuration, open `mcp.json` or `claude_desktop_config.json` and add:
66
- ```json
67
- {
68
- "mcpServers": {
69
- "gecho-bridge": {
70
- "command": "npx",
71
- "args": ["-y", "@gecho-ai/gecho-bridge@latest"]
72
- }
73
- }
74
- }
75
- ```
76
-
77
- ---
78
-
79
- ## 🏁 Quick Start & Common Workflows
80
-
81
- After setup is complete and your AI client has restarted, you can directly use natural language commands.
82
-
83
- ### 🔍 Basic Search (`tiktok_search`)
84
- Best for quick retrieval and collection of video data.
85
- **Example prompts:**
86
- - *"Search TikTok for 'portable blender' and return the top 10 by likes."*
87
- - *"Search 'cat toy' and save full results to /Users/yourname/gecho-data."*
88
-
89
- **Execution flow:**
90
- 1. AI triggers the local Gecho browser extension to search and auto-scroll.
91
- 2. After scraping, large-scale results are automatically saved locally.
92
- 3. AI summarizes the top 20 high-like results in your chat.
93
-
94
- ### 📈 Deep Insight (`tiktok_insight`)
95
- Best for category research and trend analysis.
96
- **Example prompts:**
97
- - *"Run tiktok_insight for 'outdoor picnic mat'."*
98
- - *"Compare hot video styles and engagement between 'desk setup' and 'minimal desk'."*
99
-
100
- **Execution flow:**
101
- 1. The plugin starts an asynchronous insight job and immediately returns a `jobId`.
102
- 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**.
103
- 3. After waiting, ask AI: *"Use check_insight_status to query the previous job status"* to get the final report.
104
-
105
- ---
106
-
107
- ## ⚙️ Storage Configuration
108
-
109
- To better manage your data assets, scraped results should be persisted to disk. The plugin supports the following priority order:
110
-
111
- 1. **Session-level (highest priority)**: In chat, ask AI to set `save_dir` directly (must be an absolute path).
112
- 2. **Global-level**: Set the environment variable `GECHO_DATA_DIR` as the default save directory.
113
- 3. **Fallback default**: If not specified, data is saved to the built-in `./data` directory.
114
-
115
- *(Note: All output filenames are automatically sanitized to avoid write failures from invalid characters.)*
116
-
117
- ---
118
-
119
- ## 🛠️ Troubleshooting
120
-
121
- ### 1. How do I confirm the plugin is loaded? (OpenClaw example)
122
- Run:
123
- ```bash
124
- openclaw plugins info @gecho-ai/gecho-bridge
125
- ```
126
- If installation succeeds, you should see `Status: loaded` and `MCP servers: gecho-tiktok-search`.
127
-
128
- ### 2. Error: Extension not connected
129
- - Check whether the Gecho Chrome extension is enabled.
130
- - Make sure your TikTok account is logged in, and the TikTok page is not crashed or unresponsive.
131
-
132
- ### 3. Error: Request timeout
133
- - Check whether TikTok displays a CAPTCHA challenge; if so, solve it manually first.
134
- - If results are too sparse for the keyword or network is unstable, try a more specific keyword and retry.
135
-
136
- ### 4. Error: Failed to save results
137
- - Check whether `save_dir` provided to AI is a valid absolute path.
138
- - Confirm your current system user has write permissions for the target directory.
139
-
140
- ---
141
-
142
- ## 🧑‍💻 Local Development
143
-
144
- For developers who want to build on top of this project:
145
- ```bash
146
- git clone https://github.com/gecho-ai/bridge.git
147
- cd bridge
148
- npm install
149
- npm run server
150
- ```
151
-
152
- **Two-layer architecture:**
153
- - **Client layer** (`mcp-client.js`): Standard MCP STDIO integration for communication with OpenClaw/Hermes/Trae and tool schema declarations.
154
- - **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.)
155
-
156
- ## License
157
-
158
- MIT
package/skills/tiktok-search/README.md DELETED
@@ -1,137 +0,0 @@
1
- # Gecho Bridge 🚀
2
-
3
- 🌐 **Gecho Bridge** is a universal MCP (Model Context Protocol) tool designed to bridge your large language model (LLM) and your local browser.
4
- 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.
5
-
6
- ---
7
-
8
- ## ✨ Who Is It For
9
-
10
- - 📊 **Competitor analysis**: Input a keyword and quickly get engagement data from top TikTok posts.
11
- - 💡 **Finding winning products**: Use deep insight tools to analyze trends in specific niches (for example, "portable blender") and discover underserved opportunities.
12
- - 🤖 **Automated operations**: Let your AI model control the browser, scroll automatically, scrape results, and generate reports without manual counting.
13
-
14
- ## 🚀 What It Can Do
15
-
16
- - Launch Chrome automatically, search TikTok with a target keyword, and simulate natural human-like scrolling.
17
- - Collect large-scale structured data (video ID, title, likes, video link, and more) and safely save it as JSON files.
18
- - Run **asynchronous deep insights** powered by large-scale retrieval to summarize trends and potential business opportunities.
19
-
20
- ## 🔗 Links
21
-
22
- - **Official Website**: [https://gecho.ai/](https://gecho.ai/)
23
- - **ClawHub Plugin Page**: [https://clawhub.ai/plugins/gecho-bridge](https://clawhub.ai/plugins/gecho-bridge)
24
- - **Chrome Extension**: [Install from Chrome Web Store](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb)
25
-
26
- ---
27
-
28
- ## 📦 Installation & Setup
29
-
30
- This project follows the standard MCP protocol and can be integrated with any MCP-compatible AI client (such as OpenClaw, Hermes, and Trae).
31
-
32
- ### 0. Prerequisites
33
- 1. **Node.js**: >= 18 (with `npm` / `npx` support).
34
- 2. **Browser extension**: [Install the Gecho Chrome Extension first](https://chromewebstore.google.com/detail/pjkaeenpekolahdbccjfenjcmanemlbj?utm_source=item-share-cb).
35
- 3. **Network and account state**: Ensure stable access to TikTok, keep your TikTok account logged in, and keep the extension online.
36
-
37
- ### Option 1: One-Click Setup in OpenClaw (ClawHub)
38
- ClawHub provides two installation paths: `Skill` and `Plugin`.
39
-
40
- #### Path A: Skill Install (MCP Required First)
41
- Skill installation executes through MCP, so you must configure MCP first:
42
- ```bash
43
- openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
44
- openclaw gateway restart
45
- ```
46
- *After configuration, run `openclaw mcp list` to verify status.*
47
- *Then return to ClawHub and install the Skill.*
48
-
49
- #### Path B: Plugin Install (Recommended)
50
- ```bash
51
- openclaw plugins install @gecho-ai/gecho-bridge
52
- openclaw gateway restart
53
- ```
54
- *To upgrade later, run `openclaw plugins update @gecho-ai/gecho-bridge`.*
55
-
56
- ---
57
-
58
- ## 🏁 Quick Start & Common Workflows
59
-
60
- After setup is complete and your AI client has restarted, you can directly use natural language commands.
61
-
62
- ### 🔍 Basic Search (`tiktok_search`)
63
- Best for quick retrieval and collection of video data.
64
- **Example prompts:**
65
- - *"Search TikTok for 'portable blender' and return the top 10 by likes."*
66
- - *"Search 'cat toy' and save full results to /Users/yourname/gecho-data."*
67
-
68
- **Execution flow:**
69
- 1. AI triggers the local Gecho browser extension to search and auto-scroll.
70
- 2. After scraping, large-scale results are automatically saved locally.
71
- 3. AI summarizes the top 20 high-like results in your chat.
72
-
73
- ### 📈 Deep Insight (`tiktok_insight`)
74
- Best for category research and trend analysis.
75
- **Example prompts:**
76
- - *"Run tiktok_insight for 'outdoor picnic mat'."*
77
- - *"Compare hot video styles and engagement between 'desk setup' and 'minimal desk'."*
78
-
79
- **Execution flow:**
80
- 1. The plugin starts an asynchronous insight job and immediately returns a `jobId`.
81
- 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**.
82
- 3. After waiting, ask AI: *"Use check_insight_status to query the previous job status"* to get the final report.
83
-
84
- ---
85
-
86
- ## ⚙️ Storage Configuration
87
-
88
- To better manage your data assets, scraped results should be persisted to disk. The plugin supports the following priority order:
89
-
90
- 1. **Session-level (highest priority)**: In chat, ask AI to set `save_dir` directly (must be an absolute path).
91
- 2. **Global-level**: Set the environment variable `GECHO_DATA_DIR` as the default save directory.
92
- 3. **Fallback default**: If not specified, data is saved to the built-in `./data` directory.
93
-
94
- *(Note: All output filenames are automatically sanitized to avoid write failures from invalid characters.)*
95
-
96
- ---
97
-
98
- ## 🛠️ Troubleshooting
99
-
100
- ### 1. How do I confirm the plugin is loaded? (OpenClaw example)
101
- Run:
102
- ```bash
103
- openclaw plugins info @gecho-ai/gecho-bridge
104
- ```
105
- If installation succeeds, you should see `Status: loaded` and `MCP servers: gecho-tiktok-search`.
106
-
107
- ### 2. Error: Extension not connected
108
- - Check whether the Gecho Chrome extension is enabled.
109
- - Make sure your TikTok account is logged in, and the TikTok page is not crashed or unresponsive.
110
-
111
- ### 3. Error: Request timeout
112
- - Check whether TikTok displays a CAPTCHA challenge; if so, solve it manually first.
113
- - If results are too sparse for the keyword or network is unstable, try a more specific keyword and retry.
114
-
115
- ### 4. Error: Failed to save results
116
- - Check whether `save_dir` provided to AI is a valid absolute path.
117
- - Confirm your current system user has write permissions for the target directory.
118
-
119
- ---
120
-
121
- ## 🧑‍💻 Local Development
122
-
123
- For developers who want to build on top of this project:
124
- ```bash
125
- git clone https://github.com/gecho-ai/bridge.git
126
- cd bridge
127
- npm install
128
- npm run server
129
- ```
130
-
131
- **Two-layer architecture:**
132
- - **Client layer** (`mcp-client.js`): Standard MCP STDIO integration for communication with OpenClaw/Hermes/Trae and tool schema declarations.
133
- - **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.)
134
-
135
- ## License
136
-
137
- MIT