@weavetab/mcp 2.5.0 → 2.5.1
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/AGENTS.md +49 -49
- package/ARCHITECTURE.md +590 -590
- package/LICENSE +216 -216
- package/README.md +269 -269
- package/SECURITY.md +207 -207
- package/TROUBLESHOOTING.md +373 -365
- package/dist/anticaptcha/detector.js +395 -395
- package/dist/anticaptcha/solver.js +130 -130
- package/dist/cdp/bridge.js +73 -73
- package/dist/cdp/connector.js +46 -22
- package/dist/cdp/extension.js +34 -34
- package/dist/cdp/helpers.js +174 -174
- package/dist/cdp/pruner.js +195 -195
- package/dist/cdp/ref_cache.js +66 -66
- package/dist/cdp/security.js +10 -10
- package/dist/cdp/verify.js +57 -57
- package/dist/cdp/walker.js +563 -525
- package/dist/cli/plugin.js +26 -3
- package/dist/config/loader.d.ts +0 -3
- package/dist/config/loader.js +0 -9
- package/dist/index.js +0 -4
- package/dist/intelligence/intent.js +81 -81
- package/dist/intelligence/sessionMemory.js +2 -2
- package/dist/overlay/ghost.js +22 -22
- package/dist/overlay/injector.js +89 -89
- package/dist/plugin/extension_bridge.js +54 -54
- package/dist/plugin/interface.d.ts +7 -0
- package/dist/plugin/loader.js +3 -4
- package/dist/plugin/schema.d.ts +11 -0
- package/dist/plugin/schema.js +59 -0
- package/dist/security/guard.js +18 -18
- package/dist/sensors/actionability.js +167 -167
- package/dist/sensors/guard.js +29 -29
- package/dist/sensors/network.js +15 -17
- package/dist/server.d.ts +1 -1
- package/dist/server.js +173 -144
- package/dist/state/delta.js +6 -7
- package/dist/tools/automation.js +85 -85
- package/dist/tools/canvas.js +48 -25
- package/dist/tools/checkpoint.js +94 -35
- package/dist/tools/click.js +52 -41
- package/dist/tools/clipboard.js +80 -74
- package/dist/tools/design_extract.js +441 -441
- package/dist/tools/dialog.js +13 -13
- package/dist/tools/emulation.d.ts +2 -0
- package/dist/tools/emulation.js +7 -0
- package/dist/tools/fill.js +344 -347
- package/dist/tools/find.js +78 -52
- package/dist/tools/highlight.js +67 -67
- package/dist/tools/inspect.js +54 -25
- package/dist/tools/key.js +42 -35
- package/dist/tools/navigate.d.ts +1 -1
- package/dist/tools/navigate.js +35 -35
- package/dist/tools/office/parse.js +62 -18
- package/dist/tools/pdf.d.ts +9 -0
- package/dist/tools/pdf.js +7 -4
- package/dist/tools/performance.d.ts +11 -4
- package/dist/tools/performance.js +94 -42
- package/dist/tools/performance_test.d.ts +2 -2
- package/dist/tools/performance_test.js +69 -69
- package/dist/tools/pointer.js +116 -116
- package/dist/tools/read.js +99 -67
- package/dist/tools/recording.js +9 -0
- package/dist/tools/scrape.js +146 -146
- package/dist/tools/screenshot.d.ts +2 -0
- package/dist/tools/screenshot.js +46 -4
- package/dist/tools/scroll.d.ts +3 -1
- package/dist/tools/scroll.js +13 -15
- package/dist/tools/select.d.ts +3 -0
- package/dist/tools/select.js +131 -124
- package/dist/tools/snapshot.js +8 -6
- package/dist/tools/storage.d.ts +5 -1
- package/dist/tools/storage.js +16 -0
- package/dist/tools/tabs.d.ts +7 -5
- package/dist/tools/tabs.js +79 -26
- package/dist/tools/thought.js +8 -8
- package/dist/tools/type.js +274 -274
- package/dist/tools/type_secret.js +23 -23
- package/dist/tools/upload.js +3 -3
- package/dist/tools/video_compiler.js +9 -0
- package/dist/tools/wait.js +35 -35
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/docs/DOCUMENTATION.md +583 -585
- package/docs/PLUGINS.md +139 -121
- package/docs/TOOLS.md +3 -4
- package/docs/architecture/blind-injection.md +83 -83
- package/docs/architecture/overview.md +49 -49
- package/docs/architecture/security.md +36 -36
- package/docs/architecture/transport.md +37 -37
- package/docs/cli/cli-commands.md +50 -50
- package/docs/cli/cli-flags.md +28 -28
- package/docs/cli/cli-scripting.md +35 -35
- package/docs/configuration/config-locations.md +23 -23
- package/docs/configuration/configuration.md +39 -27
- package/docs/configuration/env-variables.md +19 -19
- package/docs/configuration/folders.md +62 -55
- package/docs/desktop-automation/electron-apps.md +225 -214
- package/docs/get-started/installation.md +1 -1
- package/docs/get-started/introduction.md +60 -60
- package/docs/get-started/quickstart.md +2 -2
- package/docs/get-started/setup-wizard.md +27 -27
- package/docs/intelligence/site-profiles.md +151 -151
- package/docs/tools/tools.md +582 -631
- package/docs/troubleshooting/trouble-browser.md +27 -27
- package/docs/troubleshooting/trouble-loop.md +31 -31
- package/ext-dist/background.js +415 -415
- package/ext-dist/content.js +2527 -2527
- package/ext-dist/dashboard.html +583 -583
- package/ext-dist/hud/hud.js +3 -3
- package/ext-dist/hud/index.html +20 -20
- package/ext-dist/manifest.json +73 -73
- package/ext-dist/styles.css +223 -223
- package/mcp.json +796 -805
- package/package.json +118 -118
- package/server.json +23 -23
- package/dist/cdp/walker.test.d.ts +0 -2
- package/dist/cdp/walker.test.js +0 -172
- package/dist/intelligence/sessionMemory.test.d.ts +0 -2
- package/dist/intelligence/sessionMemory.test.js +0 -62
- package/dist/intelligence/trail.test.d.ts +0 -2
- package/dist/intelligence/trail.test.js +0 -110
- package/dist/state/cache.test.d.ts +0 -2
- package/dist/state/cache.test.js +0 -76
- package/dist/state/delta.test.d.ts +0 -2
- package/dist/state/delta.test.js +0 -279
- package/dist/state/groups.d.ts +0 -15
- package/dist/state/groups.js +0 -80
- package/dist/tools/accessibility.d.ts +0 -14
- package/dist/tools/accessibility.js +0 -32
- package/dist/tools/ask.d.ts +0 -14
- package/dist/tools/ask.js +0 -49
- package/dist/tools/click_and_wait.d.ts +0 -33
- package/dist/tools/click_and_wait.js +0 -149
- package/dist/tools/drag.d.ts +0 -15
- package/dist/tools/drag.js +0 -29
- package/dist/tools/geo.d.ts +0 -19
- package/dist/tools/geo.js +0 -29
- package/dist/tools/github/analyze.d.ts +0 -4
- package/dist/tools/github/analyze.js +0 -113
- package/dist/tools/github/cache.d.ts +0 -21
- package/dist/tools/github/cache.js +0 -28
- package/dist/tools/github/index.d.ts +0 -19
- package/dist/tools/github/index.js +0 -40
- package/dist/tools/github/issues.d.ts +0 -9
- package/dist/tools/github/issues.js +0 -88
- package/dist/tools/github/pr.d.ts +0 -5
- package/dist/tools/github/pr.js +0 -88
- package/dist/tools/github/rateLimiter.d.ts +0 -4
- package/dist/tools/github/rateLimiter.js +0 -46
- package/dist/tools/github/read.d.ts +0 -34
- package/dist/tools/github/read.js +0 -74
- package/dist/tools/github/repoContext.d.ts +0 -20
- package/dist/tools/github/repoContext.js +0 -129
- package/dist/tools/hover.d.ts +0 -19
- package/dist/tools/hover.js +0 -57
- package/dist/tools/integration.test.d.ts +0 -2
- package/dist/tools/integration.test.js +0 -96
- package/dist/tools/macro_compiler.d.ts +0 -7
- package/dist/tools/macro_compiler.js +0 -82
- package/dist/tools/mouse.d.ts +0 -21
- package/dist/tools/mouse.js +0 -62
- package/dist/tools/response.d.ts +0 -129
- package/dist/tools/response.js +0 -5
- package/dist/tools/wait_for.d.ts +0 -23
- package/dist/tools/wait_for.js +0 -30
- package/dist/tools/windows.d.ts +0 -22
- package/dist/tools/windows.js +0 -57
package/README.md
CHANGED
|
@@ -1,269 +1,269 @@
|
|
|
1
|
-
<div align="center">
|
|
2
|
-
|
|
3
|
-
<img src="weavetab-banner.png" alt="Weavetab" /><br /><br />
|
|
4
|
-
|
|
5
|
-
<p>The open automation engine for AI agents.<br />Control live browsers and desktop apps locally with instant execution.</p>
|
|
6
|
-
|
|
7
|
-
<p>
|
|
8
|
-
<a href="https://github.com/weavetab/mcp/releases"><img src="https://img.shields.io/github/v/release/weavetab/mcp?label=version&style=flat-square&color=3b82f6" alt="version" /></a>
|
|
9
|
-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-8b5cf6?style=flat-square" alt="license" /></a>
|
|
10
|
-
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-10b981?style=flat-square" alt="MCP" /></a>
|
|
11
|
-
<img src="https://img.shields.io/badge/Node.js-%3E%3D18-green?style=flat-square" alt="Node" />
|
|
12
|
-
<a href="docs/tools/tools.md"><img src="https://img.shields.io/badge/tools-
|
|
13
|
-
<a href="https://github.com/sponsors/fy2ne"><img src="https://img.shields.io/badge/sponsor-fy2ne-ea4aaa?style=flat-square&logo=github-sponsors" alt="sponsor" /></a>
|
|
14
|
-
</p>
|
|
15
|
-
|
|
16
|
-
<p>
|
|
17
|
-
<a href="docs/tools/tools.md">Tool Reference</a> ·
|
|
18
|
-
<a href="docs/DOCUMENTATION.md">Documentation</a> ·
|
|
19
|
-
<a href="ARCHITECTURE.md">Architecture</a> ·
|
|
20
|
-
<a href="SUPPORT.md">Support</a> ·
|
|
21
|
-
<a href="SECURITY.md">Security</a>
|
|
22
|
-
</p>
|
|
23
|
-
|
|
24
|
-
</div>
|
|
25
|
-
|
|
26
|
-
---
|
|
27
|
-
|
|
28
|
-
Weavetab is the open automation engine for AI agents. It connects models directly to live Chromium browsers and Electron desktop applications via native **Chrome DevTools Protocol (CDP)** sockets — no WebDriver binaries, no cloud relay, zero telemetry.
|
|
29
|
-
|
|
30
|
-
Actions execute with **sub-10ms latency**. Web pages are translated into agent-readable semantic maps with turn-by-turn diffing that reduces token usage by **up to 95%**. Built-in security enforces local domain policies, role-based access control, and client-side credential injection.
|
|
31
|
-
|
|
32
|
-
Built and architected by [fy2ne](https://github.com/fy2ne).
|
|
33
|
-
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
## Why not Playwright or Puppeteer?
|
|
37
|
-
|
|
38
|
-
> The standard approach
|
|
39
|
-
|
|
40
|
-
| | Playwright / Puppeteer | **Weavetab** |
|
|
41
|
-
|---|---|---|
|
|
42
|
-
| **Protocol layer** | WebDriver BiDi or CDP via browser binary | Raw CDP WebSocket, Layer 0 |
|
|
43
|
-
| **Tool execution latency** | 50
|
|
44
|
-
| **Desktop app control** | Browser only | Chrome + any Electron app (Discord, VS Code, Figma
|
|
45
|
-
| **DOM representation** | Full HTML dump to LLM | Semantic Map 3.0 with delta diffing |
|
|
46
|
-
| **Token cost per map** | ~2,000
|
|
47
|
-
| **CAPTCHA** | API service required | **Zero-API** via CDP mouse physics |
|
|
48
|
-
| **Credential safety** | Secrets passed in plaintext | **Blind Injection**
|
|
49
|
-
| **Extension access** | Limited | Full Chrome Extension API surface |
|
|
50
|
-
|
|
51
|
-
---
|
|
52
|
-
|
|
53
|
-
## Architecture
|
|
54
|
-
|
|
55
|
-
```
|
|
56
|
-
MCP Client (Claude / Cursor / Antigravity / Copilot / Windsurf)
|
|
57
|
-
|
|
|
58
|
-
| JSON-RPC 2.0 (stdio or WebSocket :3000)
|
|
59
|
-
v
|
|
60
|
-
+-------------------------------------------------------------+
|
|
61
|
-
| Weavetab MCP Server |
|
|
62
|
-
| |
|
|
63
|
-
| +-----------------+ +---------------------------------+ |
|
|
64
|
-
| | Security Layer |-->| Intelligence Engine | |
|
|
65
|
-
| | Rate
|
|
66
|
-
| | Policy
|
|
67
|
-
| +-----------------+ +----------------+----------------+ |
|
|
68
|
-
| | |
|
|
69
|
-
| +----------v----------------+ |
|
|
70
|
-
| | CDP Bridge | |
|
|
71
|
-
| | Ghost Cursor
|
|
72
|
-
| | App Router
|
|
73
|
-
| +----------+----------------+ |
|
|
74
|
-
+-------------------------------------------------------------+
|
|
75
|
-
| CDP WebSocket (127.0.0.1)
|
|
76
|
-
+---------------------------+-----------------------------+
|
|
77
|
-
v v v
|
|
78
|
-
Chrome / Edge VS Code / Discord Your Electron App
|
|
79
|
-
(any tab) (Electron apps) (local dev)
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
No cloud. No external process. The CDP WebSocket connection is strictly bound to `127.0.0.1`.
|
|
83
|
-
|
|
84
|
-
---
|
|
85
|
-
|
|
86
|
-
## Quick Start
|
|
87
|
-
|
|
88
|
-
```bash
|
|
89
|
-
npx -y @weavetab/mcp
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Add to your MCP client config:
|
|
93
|
-
|
|
94
|
-
```json
|
|
95
|
-
{
|
|
96
|
-
"mcpServers": {
|
|
97
|
-
"weavetab": {
|
|
98
|
-
"command": "npx",
|
|
99
|
-
"args": ["-y", "@weavetab/mcp"]
|
|
100
|
-
}
|
|
101
|
-
}
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
| Client | Config path |
|
|
106
|
-
|---|---|
|
|
107
|
-
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
108
|
-
| Claude Code | `claude mcp add weavetab -- npx -y @weavetab/mcp` |
|
|
109
|
-
| Cursor | `.cursor/mcp.json` |
|
|
110
|
-
| Antigravity | `~/.gemini/antigravity/mcp/weavetab/` |
|
|
111
|
-
| VS Code Copilot | `.vscode/mcp.json` |
|
|
112
|
-
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
## Core Technology
|
|
117
|
-
|
|
118
|
-
### Semantic Map 3.0
|
|
119
|
-
|
|
120
|
-
The primary bottleneck in browser-based agents is DOM representation. Full HTML dumps are noisy, large, and structurally meaningless to language models. Weavetab's `browser_map` runs an in-browser CDP walker that produces a compact semantic map:
|
|
121
|
-
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
[w:3] button "Confirm" [w:4] button "Cancel"
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
[w:12] button "Upgrade" [w:13] button "View Details"
|
|
128
|
-
[w:14] input val:"john@example.com" ph:"Email address" FOCUSED
|
|
129
|
-
|
|
130
|
-
[w:20...w:38] 18 nav links: "Dashboard" ... "Sign out"
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Key properties:
|
|
134
|
-
|
|
135
|
-
- **Ref IDs** (`w:N`) are stable within a session and used by all interaction tools
|
|
136
|
-
- **Container binding**
|
|
137
|
-
- **Modal hoisting**
|
|
138
|
-
- **Link collapsing**
|
|
139
|
-
- **Semantic delta**
|
|
140
|
-
|
|
141
|
-
### Ghost Cursor
|
|
142
|
-
|
|
143
|
-
Clicks are not dispatched as synthetic DOM events. They are delivered as a physical sequence of `Input.dispatchMouseEvent` CDP calls along a Bezier curve trajectory with randomized acceleration, natural jitter, and hold durations. Anti-bot fingerprinting that flags event-based automation does not trigger.
|
|
144
|
-
|
|
145
|
-
`browser_pointer` supports `hover_chain` for multi-level menu traversal in a single tool call:
|
|
146
|
-
|
|
147
|
-
```json
|
|
148
|
-
{
|
|
149
|
-
"hover_chain": ["File", "Export As", "PNG"],
|
|
150
|
-
"click_final": true
|
|
151
|
-
}
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
### Blind Credential Injection
|
|
155
|
-
|
|
156
|
-
`browser_type_secret` resolves secrets server-side from `~/.weavetab/secrets.json`. The resolved value is never included in the MCP response, never appears in DOM snapshots, and is permanently masked as `[REDACTED]` in all audit logs. The LLM context never sees the credential.
|
|
157
|
-
|
|
158
|
-
```bash
|
|
159
|
-
weavetab secrets set GITHUB_TOKEN
|
|
160
|
-
# Stored. Never echoed, never logged, never surfaced to the agent.
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
### Electron & Desktop App Automation
|
|
164
|
-
|
|
165
|
-
Any tool accepts an optional `app` parameter that routes the command to a registered Electron process instead of a browser tab:
|
|
166
|
-
|
|
167
|
-
```json
|
|
168
|
-
{ "app": "discord", "ref": "w:24", "text": "Hey, deploying now" }
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
Register apps in `~/.weavetab/config.json`:
|
|
172
|
-
|
|
173
|
-
```json
|
|
174
|
-
{
|
|
175
|
-
"electron": {
|
|
176
|
-
"discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\Discord.exe",
|
|
177
|
-
"vscode": "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
|
|
178
|
-
"figma": "C:\\Users\\<user>\\AppData\\Local\\Figma\\Figma.exe"
|
|
179
|
-
}
|
|
180
|
-
}
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
Weavetab auto-attaches via CDP to the registered process. No code changes required in the target application.
|
|
184
|
-
|
|
185
|
-
### Zero-API CAPTCHA Solving
|
|
186
|
-
|
|
187
|
-
`browser_captcha` solves Cloudflare Turnstile, reCAPTCHA v2/v3, GeeTest, and hCaptcha by orchestrating CDP mouse events that replicate human behavioral signatures
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## Tool Suite
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
| Category | Tools |
|
|
196
|
-
|---|---|
|
|
197
|
-
| **Vision & DOM** | `browser_map` `browser_find` `browser_scrape` `browser_inspect` `browser_snapshot` `browser_screenshot` `browser_console` `browser_extract_design` |
|
|
198
|
-
| **Input & Interaction** | `browser_click` `browser_type` `browser_type_secret` `browser_key` `browser_pointer` `browser_select` `browser_fill` `browser_upload` `browser_scroll` |
|
|
199
|
-
| **Navigation & Environment** | `browser_navigate` `browser_tabs` `browser_detect` `browser_viewport` `browser_emulate` |
|
|
200
|
-
| **Mission & Automation** | `browser_burst` `browser_automation` `browser_recording` `browser_pattern_learn` |
|
|
201
|
-
| **Safety & Human Oversight** | `browser_dialog` `browser_thoughts` `browser_clipboard` `browser_wait` |
|
|
202
|
-
| **Autonomous CAPTCHA** | `browser_captcha` |
|
|
203
|
-
| **Network & Storage** | `browser_network_intercept` `browser_storage` `browser_cookies` `browser_checkpoint` `browser_performance` |
|
|
204
|
-
| **
|
|
205
|
-
| **Canvas & Eval** | `browser_eval` `browser_pdf` `browser_canvas` `browser_highlight` |
|
|
206
|
-
|
|
207
|
-
---
|
|
208
|
-
|
|
209
|
-
## Security
|
|
210
|
-
|
|
211
|
-
- **Transport**: CDP WebSocket strictly bound to `127.0.0.1`. No listener on external interfaces.
|
|
212
|
-
- **Policy Engine**: Per-domain `allow` / `read-only` / `deny` / `audit` rules in `~/.weavetab/
|
|
213
|
-
- **RBAC**:
|
|
214
|
-
- **Blind Injection**: Credentials resolved server-side, masked in all outputs and audit logs
|
|
215
|
-
- **Loop Breaker**: Strike-based stuck-loop detector halts runaway autonomous sequences
|
|
216
|
-
- **Audit Log**: All tool invocations, policy decisions, and errors written to `~/.weavetab/logs/
|
|
217
|
-
|
|
218
|
-
Security vulnerabilities: `security@fy2ne.me` (do not use public issues).
|
|
219
|
-
|
|
220
|
-
---
|
|
221
|
-
|
|
222
|
-
## CLI Reference
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
weavetab # Start in stdio mode (default)
|
|
226
|
-
weavetab --ws --port 3000 # WebSocket daemon mode
|
|
227
|
-
weavetab config # Interactive configuration wizard
|
|
228
|
-
weavetab secrets set KEY_NAME # Store a secret (never echoed)
|
|
229
|
-
weavetab secrets list # List stored secret keys (not values)
|
|
230
|
-
weavetab plugin add <name> # Install a plugin from npm
|
|
231
|
-
weavetab plugin list # List installed plugins
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
Configuration file: `~/.weavetab/config.json`
|
|
235
|
-
|
|
236
|
-
```json
|
|
237
|
-
{
|
|
238
|
-
"browserType": "chromium",
|
|
239
|
-
"headless": false,
|
|
240
|
-
"extension": true,
|
|
241
|
-
"maxActionsPerMinute": 60,
|
|
242
|
-
"role": "admin",
|
|
243
|
-
"electron": {
|
|
244
|
-
"discord": "...",
|
|
245
|
-
"vscode": "...",
|
|
246
|
-
"antigravity": "..."
|
|
247
|
-
}
|
|
248
|
-
}
|
|
249
|
-
```
|
|
250
|
-
|
|
251
|
-
---
|
|
252
|
-
|
|
253
|
-
## Extensibility
|
|
254
|
-
|
|
255
|
-
Weavetab exposes a typed Plugin SDK for authoring custom MCP tools, HUD overlays, and tool lifecycle hooks:
|
|
256
|
-
|
|
257
|
-
```bash
|
|
258
|
-
npx @weavetab/sdk init my-plugin
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
See [`docs/PLUGINS.md`](docs/PLUGINS.md) for architecture, manifest spec, and SDK API reference.
|
|
262
|
-
|
|
263
|
-
---
|
|
264
|
-
|
|
265
|
-
## License
|
|
266
|
-
|
|
267
|
-
AGPL-3.0-only. Client connections over stdio or WebSocket do not extend copyleft obligations to your client application or models.
|
|
268
|
-
|
|
269
|
-
[Sponsor development](https://github.com/sponsors/fy2ne) · [Discussions](https://github.com/weavetab/mcp/discussions) · [SUPPORT.md](SUPPORT.md)
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
<img src="weavetab-banner.png" alt="Weavetab" /><br /><br />
|
|
4
|
+
|
|
5
|
+
<p>The open automation engine for AI agents.<br />Control live browsers and desktop apps locally with instant execution.</p>
|
|
6
|
+
|
|
7
|
+
<p>
|
|
8
|
+
<a href="https://github.com/weavetab/mcp/releases"><img src="https://img.shields.io/github/v/release/weavetab/mcp?label=version&style=flat-square&color=3b82f6" alt="version" /></a>
|
|
9
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-8b5cf6?style=flat-square" alt="license" /></a>
|
|
10
|
+
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-10b981?style=flat-square" alt="MCP" /></a>
|
|
11
|
+
<img src="https://img.shields.io/badge/Node.js-%3E%3D18-green?style=flat-square" alt="Node" />
|
|
12
|
+
<a href="docs/tools/tools.md"><img src="https://img.shields.io/badge/tools-41-ec4899?style=flat-square" alt="tools" /></a>
|
|
13
|
+
<a href="https://github.com/sponsors/fy2ne"><img src="https://img.shields.io/badge/sponsor-fy2ne-ea4aaa?style=flat-square&logo=github-sponsors" alt="sponsor" /></a>
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
<p>
|
|
17
|
+
<a href="docs/tools/tools.md">Tool Reference</a> ·
|
|
18
|
+
<a href="docs/DOCUMENTATION.md">Documentation</a> ·
|
|
19
|
+
<a href="ARCHITECTURE.md">Architecture</a> ·
|
|
20
|
+
<a href="SUPPORT.md">Support</a> ·
|
|
21
|
+
<a href="SECURITY.md">Security</a>
|
|
22
|
+
</p>
|
|
23
|
+
|
|
24
|
+
</div>
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
Weavetab is the open automation engine for AI agents. It connects models directly to live Chromium browsers and Electron desktop applications via native **Chrome DevTools Protocol (CDP)** sockets — no WebDriver binaries, no cloud relay, zero telemetry.
|
|
29
|
+
|
|
30
|
+
Actions execute with **sub-10ms latency**. Web pages are translated into agent-readable semantic maps with turn-by-turn diffing that reduces token usage by **up to 95%**. Built-in security enforces local domain policies, role-based access control, and client-side credential injection.
|
|
31
|
+
|
|
32
|
+
Built and architected by [fy2ne](https://github.com/fy2ne).
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Why not Playwright or Puppeteer?
|
|
37
|
+
|
|
38
|
+
> The standard approach — Playwright over MCP — works. But it carries fundamental architectural costs that compound at scale.
|
|
39
|
+
|
|
40
|
+
| | Playwright / Puppeteer | **Weavetab** |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| **Protocol layer** | WebDriver BiDi or CDP via browser binary | Raw CDP WebSocket, Layer 0 |
|
|
43
|
+
| **Tool execution latency** | 50–300 ms (binary + IPC overhead) | **3–8 ms** |
|
|
44
|
+
| **Desktop app control** | Browser only | Chrome + any Electron app (Discord, VS Code, Figma…) |
|
|
45
|
+
| **DOM representation** | Full HTML dump to LLM | Semantic Map 3.0 with delta diffing |
|
|
46
|
+
| **Token cost per map** | ~2,000–8,000 tokens | **~80–400 tokens** (95% reduction via delta) |
|
|
47
|
+
| **CAPTCHA** | API service required | **Zero-API** via CDP mouse physics |
|
|
48
|
+
| **Credential safety** | Secrets passed in plaintext | **Blind Injection** — never in LLM context |
|
|
49
|
+
| **Extension access** | Limited | Full Chrome Extension API surface |
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Architecture
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
MCP Client (Claude / Cursor / Antigravity / Copilot / Windsurf)
|
|
57
|
+
|
|
|
58
|
+
| JSON-RPC 2.0 (stdio or WebSocket :3000)
|
|
59
|
+
v
|
|
60
|
+
+-------------------------------------------------------------+
|
|
61
|
+
| Weavetab MCP Server |
|
|
62
|
+
| |
|
|
63
|
+
| +-----------------+ +---------------------------------+ |
|
|
64
|
+
| | Security Layer |-->| Intelligence Engine | |
|
|
65
|
+
| | Rate · RBAC | | Map 3.0 · Delta · Memory | |
|
|
66
|
+
| | Policy · Audit | | Pruner · Framework Detector | |
|
|
67
|
+
| +-----------------+ +----------------+----------------+ |
|
|
68
|
+
| | |
|
|
69
|
+
| +----------v----------------+ |
|
|
70
|
+
| | CDP Bridge | |
|
|
71
|
+
| | Ghost Cursor · Typing | |
|
|
72
|
+
| | App Router · Loop Guard | |
|
|
73
|
+
| +----------+----------------+ |
|
|
74
|
+
+-------------------------------------------------------------+
|
|
75
|
+
| CDP WebSocket (127.0.0.1)
|
|
76
|
+
+---------------------------+-----------------------------+
|
|
77
|
+
v v v
|
|
78
|
+
Chrome / Edge VS Code / Discord Your Electron App
|
|
79
|
+
(any tab) (Electron apps) (local dev)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
No cloud. No external process. The CDP WebSocket connection is strictly bound to `127.0.0.1`.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Quick Start
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
npx -y @weavetab/mcp
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Add to your MCP client config:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"mcpServers": {
|
|
97
|
+
"weavetab": {
|
|
98
|
+
"command": "npx",
|
|
99
|
+
"args": ["-y", "@weavetab/mcp"]
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
| Client | Config path |
|
|
106
|
+
|---|---|
|
|
107
|
+
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
108
|
+
| Claude Code | `claude mcp add weavetab -- npx -y @weavetab/mcp` |
|
|
109
|
+
| Cursor | `.cursor/mcp.json` |
|
|
110
|
+
| Antigravity | `~/.gemini/antigravity/mcp/weavetab/` |
|
|
111
|
+
| VS Code Copilot | `.vscode/mcp.json` |
|
|
112
|
+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## Core Technology
|
|
117
|
+
|
|
118
|
+
### Semantic Map 3.0
|
|
119
|
+
|
|
120
|
+
The primary bottleneck in browser-based agents is DOM representation. Full HTML dumps are noisy, large, and structurally meaningless to language models. Weavetab's `browser_map` runs an in-browser CDP walker that produces a compact semantic map:
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
╔═ ACTIVE DIALOG: "Confirm Payment" ═╗
|
|
124
|
+
[w:3] button "Confirm" [w:4] button "Cancel"
|
|
125
|
+
|
|
126
|
+
┌ "Pro Plan — $49/mo"
|
|
127
|
+
[w:12] button "Upgrade" [w:13] button "View Details"
|
|
128
|
+
[w:14] input val:"john@example.com" ph:"Email address" FOCUSED
|
|
129
|
+
|
|
130
|
+
[w:20...w:38] 18 nav links: "Dashboard" ... "Sign out"
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Key properties:
|
|
134
|
+
|
|
135
|
+
- **Ref IDs** (`w:N`) are stable within a session and used by all interaction tools
|
|
136
|
+
- **Container binding** — buttons and inputs are grouped under their parent card, row, or section header
|
|
137
|
+
- **Modal hoisting** — open dialogs are isolated at the top so agents cannot miss them
|
|
138
|
+
- **Link collapsing** — repeated nav/footer runs of 4+ links compress into a single token line
|
|
139
|
+
- **Semantic delta** — on re-reads, only changed nodes are transmitted (`~` modified, `+` added, `−` removed), cutting re-read cost by up to 95%
|
|
140
|
+
|
|
141
|
+
### Ghost Cursor
|
|
142
|
+
|
|
143
|
+
Clicks are not dispatched as synthetic DOM events. They are delivered as a physical sequence of `Input.dispatchMouseEvent` CDP calls along a Bezier curve trajectory with randomized acceleration, natural jitter, and hold durations. Anti-bot fingerprinting that flags event-based automation does not trigger.
|
|
144
|
+
|
|
145
|
+
`browser_pointer` supports `hover_chain` for multi-level menu traversal in a single tool call:
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"hover_chain": ["File", "Export As", "PNG"],
|
|
150
|
+
"click_final": true
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Blind Credential Injection
|
|
155
|
+
|
|
156
|
+
`browser_type_secret` resolves secrets server-side from `~/.weavetab/secrets.json`. The resolved value is never included in the MCP response, never appears in DOM snapshots, and is permanently masked as `[REDACTED]` in all audit logs. The LLM context never sees the credential.
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
weavetab secrets set GITHUB_TOKEN
|
|
160
|
+
# Stored. Never echoed, never logged, never surfaced to the agent.
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Electron & Desktop App Automation
|
|
164
|
+
|
|
165
|
+
Any tool accepts an optional `app` parameter that routes the command to a registered Electron process instead of a browser tab:
|
|
166
|
+
|
|
167
|
+
```json
|
|
168
|
+
{ "app": "discord", "ref": "w:24", "text": "Hey, deploying now" }
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Register apps in `~/.weavetab/config.json`:
|
|
172
|
+
|
|
173
|
+
```json
|
|
174
|
+
{
|
|
175
|
+
"electron": {
|
|
176
|
+
"discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\Discord.exe",
|
|
177
|
+
"vscode": "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
|
|
178
|
+
"figma": "C:\\Users\\<user>\\AppData\\Local\\Figma\\Figma.exe"
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Weavetab auto-attaches via CDP to the registered process. No code changes required in the target application.
|
|
184
|
+
|
|
185
|
+
### Zero-API CAPTCHA Solving
|
|
186
|
+
|
|
187
|
+
`browser_captcha` solves Cloudflare Turnstile, reCAPTCHA v2/v3, GeeTest, and hCaptcha by orchestrating CDP mouse events that replicate human behavioral signatures — velocity curves, micro-pauses, scroll inertia — with no third-party API, no external service, and no API key required.
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## Tool Suite
|
|
192
|
+
|
|
193
|
+
41 tools across 9 categories. Full parameter reference: [`docs/tools/tools.md`](docs/tools/tools.md)
|
|
194
|
+
|
|
195
|
+
| Category | Tools |
|
|
196
|
+
|---|---|
|
|
197
|
+
| **Vision & DOM** | `browser_map` `browser_find` `browser_scrape` `browser_inspect` `browser_snapshot` `browser_screenshot` `browser_console` `browser_extract_design` |
|
|
198
|
+
| **Input & Interaction** | `browser_click` `browser_type` `browser_type_secret` `browser_key` `browser_pointer` `browser_select` `browser_fill` `browser_upload` `browser_scroll` |
|
|
199
|
+
| **Navigation & Environment** | `browser_navigate` `browser_tabs` `browser_detect` `browser_viewport` `browser_emulate` |
|
|
200
|
+
| **Mission & Automation** | `browser_burst` `browser_automation` `browser_recording` `browser_pattern_learn` |
|
|
201
|
+
| **Safety & Human Oversight** | `browser_dialog` `browser_thoughts` `browser_clipboard` `browser_wait` |
|
|
202
|
+
| **Autonomous CAPTCHA** | `browser_captcha` |
|
|
203
|
+
| **Network & Storage** | `browser_network_intercept` `browser_storage` `browser_cookies` `browser_checkpoint` `browser_performance` |
|
|
204
|
+
| **Office Documents** | `browser_office` |
|
|
205
|
+
| **Canvas & Eval** | `browser_eval` `browser_pdf` `browser_canvas` `browser_highlight` |
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## Security
|
|
210
|
+
|
|
211
|
+
- **Transport**: CDP WebSocket strictly bound to `127.0.0.1`. No listener on external interfaces.
|
|
212
|
+
- **Policy Engine**: Per-domain `allow` / `read-only` / `deny` / `audit` rules under the top-level `policies` array in `~/.weavetab/config.json`
|
|
213
|
+
- **RBAC**: Five roles — `admin`, `operator`, `viewer`, `automation`, `system` — enforce tool-level permission gates
|
|
214
|
+
- **Blind Injection**: Credentials resolved server-side, masked in all outputs and audit logs
|
|
215
|
+
- **Loop Breaker**: Strike-based stuck-loop detector halts runaway autonomous sequences
|
|
216
|
+
- **Audit Log**: All tool invocations, policy decisions, and errors written to `~/.weavetab-system/logs/mission_<timestamp>.log`
|
|
217
|
+
|
|
218
|
+
Security vulnerabilities: `security@fy2ne.me` (do not use public issues).
|
|
219
|
+
|
|
220
|
+
---
|
|
221
|
+
|
|
222
|
+
## CLI Reference
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
weavetab # Start in stdio mode (default)
|
|
226
|
+
weavetab --ws --port 3000 # WebSocket daemon mode
|
|
227
|
+
weavetab config # Interactive configuration wizard
|
|
228
|
+
weavetab secrets set KEY_NAME # Store a secret (never echoed)
|
|
229
|
+
weavetab secrets list # List stored secret keys (not values)
|
|
230
|
+
weavetab plugin add <name> # Install a plugin from npm
|
|
231
|
+
weavetab plugin list # List installed plugins
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Configuration file: `~/.weavetab/config.json`
|
|
235
|
+
|
|
236
|
+
```json
|
|
237
|
+
{
|
|
238
|
+
"browserType": "chromium",
|
|
239
|
+
"headless": false,
|
|
240
|
+
"extension": true,
|
|
241
|
+
"maxActionsPerMinute": 60,
|
|
242
|
+
"role": "admin",
|
|
243
|
+
"electron": {
|
|
244
|
+
"discord": "...",
|
|
245
|
+
"vscode": "...",
|
|
246
|
+
"antigravity": "..."
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Extensibility
|
|
254
|
+
|
|
255
|
+
Weavetab exposes a typed Plugin SDK for authoring custom MCP tools, HUD overlays, and tool lifecycle hooks:
|
|
256
|
+
|
|
257
|
+
```bash
|
|
258
|
+
npx @weavetab/sdk init my-plugin
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
See [`docs/PLUGINS.md`](docs/PLUGINS.md) for architecture, manifest spec, and SDK API reference.
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## License
|
|
266
|
+
|
|
267
|
+
AGPL-3.0-only. Client connections over stdio or WebSocket do not extend copyleft obligations to your client application or models.
|
|
268
|
+
|
|
269
|
+
[Sponsor development](https://github.com/sponsors/fy2ne) · [Discussions](https://github.com/weavetab/mcp/discussions) · [SUPPORT.md](SUPPORT.md)
|