@gecho-ai/gecho-bridge 1.1.6 → 1.1.7
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.
- package/.claude-plugin/plugin.json +1 -1
- package/README.en.md +158 -0
- package/README.md +12 -0
- package/package.json +1 -1
- package/server.js +19 -0
- package/skills/tiktok-search/README.md +137 -0
- package/skills/tiktok-search/_meta.json +1 -1
package/README.en.md
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
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/README.md
CHANGED
|
@@ -35,6 +35,18 @@
|
|
|
35
35
|
3. **网络与状态**：确保本地网络可稳定访问 TikTok，并在浏览器中登录账号，保持扩展在线。
|
|
36
36
|
|
|
37
37
|
### 方式一：在 OpenClaw 中一键安装 (ClawHub)
|
|
38
|
+
ClawHub 中有两种安装方式：`Skill` 与 `Plugin`。
|
|
39
|
+
|
|
40
|
+
#### 方案 A：Skill 安装（需先配置 MCP）
|
|
41
|
+
Skill 安装后会通过 MCP 调用执行，因此需要先完成以下 MCP 配置：
|
|
42
|
+
```bash
|
|
43
|
+
openclaw mcp set gecho-bridge '{"command":"npx","args":["-y","@gecho-ai/gecho-bridge@latest"]}'
|
|
44
|
+
openclaw gateway restart
|
|
45
|
+
```
|
|
46
|
+
*配置后，可通过 `openclaw mcp list` 检查状态。*
|
|
47
|
+
*完成 MCP 配置后，再回到 ClawHub 选择 Skill 安装即可。*
|
|
48
|
+
|
|
49
|
+
#### 方案 B：Plugin 安装（推荐）
|
|
38
50
|
```bash
|
|
39
51
|
openclaw plugins install @gecho-ai/gecho-bridge
|
|
40
52
|
openclaw gateway restart
|
package/package.json
CHANGED
package/server.js
CHANGED
|
@@ -670,6 +670,25 @@ wss.on("connection", (ws) => {
|
|
|
670
670
|
console.warn(`WARN pendingRequests.size=${pendingRequests.size}, sampleKeys=${JSON.stringify(keys.slice(0, 10))}`);
|
|
671
671
|
}
|
|
672
672
|
}
|
|
673
|
+
if (parsed.method === "action_result" && !parsed.requestId) {
|
|
674
|
+
const keys = Array.from(pendingRequests.keys());
|
|
675
|
+
if (keys.length === 1) {
|
|
676
|
+
const recoveredRequestId = keys[0];
|
|
677
|
+
const pending = pendingRequests.get(recoveredRequestId);
|
|
678
|
+
console.warn(
|
|
679
|
+
`WARN action_result missing requestId; recovered using single pending request: ${recoveredRequestId}`
|
|
680
|
+
);
|
|
681
|
+
if (pending) {
|
|
682
|
+
clearTimeout(pending.timeoutId);
|
|
683
|
+
pending.resolve(parsed.data);
|
|
684
|
+
pendingRequests.delete(recoveredRequestId);
|
|
685
|
+
}
|
|
686
|
+
} else {
|
|
687
|
+
console.warn(
|
|
688
|
+
`WARN action_result missing requestId and cannot recover (pendingRequests.size=${keys.length})`
|
|
689
|
+
);
|
|
690
|
+
}
|
|
691
|
+
}
|
|
673
692
|
} catch (e) {
|
|
674
693
|
console.error("Error parsing extension message:", e);
|
|
675
694
|
}
|
|
@@ -0,0 +1,137 @@
|
|
|
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
|