@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.
Files changed (168) hide show
  1. package/AGENTS.md +49 -49
  2. package/ARCHITECTURE.md +590 -590
  3. package/LICENSE +216 -216
  4. package/README.md +269 -269
  5. package/SECURITY.md +207 -207
  6. package/TROUBLESHOOTING.md +373 -365
  7. package/dist/anticaptcha/detector.js +395 -395
  8. package/dist/anticaptcha/solver.js +130 -130
  9. package/dist/cdp/bridge.js +73 -73
  10. package/dist/cdp/connector.js +46 -22
  11. package/dist/cdp/extension.js +34 -34
  12. package/dist/cdp/helpers.js +174 -174
  13. package/dist/cdp/pruner.js +195 -195
  14. package/dist/cdp/ref_cache.js +66 -66
  15. package/dist/cdp/security.js +10 -10
  16. package/dist/cdp/verify.js +57 -57
  17. package/dist/cdp/walker.js +563 -525
  18. package/dist/cli/plugin.js +26 -3
  19. package/dist/config/loader.d.ts +0 -3
  20. package/dist/config/loader.js +0 -9
  21. package/dist/index.js +0 -4
  22. package/dist/intelligence/intent.js +81 -81
  23. package/dist/intelligence/sessionMemory.js +2 -2
  24. package/dist/overlay/ghost.js +22 -22
  25. package/dist/overlay/injector.js +89 -89
  26. package/dist/plugin/extension_bridge.js +54 -54
  27. package/dist/plugin/interface.d.ts +7 -0
  28. package/dist/plugin/loader.js +3 -4
  29. package/dist/plugin/schema.d.ts +11 -0
  30. package/dist/plugin/schema.js +59 -0
  31. package/dist/security/guard.js +18 -18
  32. package/dist/sensors/actionability.js +167 -167
  33. package/dist/sensors/guard.js +29 -29
  34. package/dist/sensors/network.js +15 -17
  35. package/dist/server.d.ts +1 -1
  36. package/dist/server.js +173 -144
  37. package/dist/state/delta.js +6 -7
  38. package/dist/tools/automation.js +85 -85
  39. package/dist/tools/canvas.js +48 -25
  40. package/dist/tools/checkpoint.js +94 -35
  41. package/dist/tools/click.js +52 -41
  42. package/dist/tools/clipboard.js +80 -74
  43. package/dist/tools/design_extract.js +441 -441
  44. package/dist/tools/dialog.js +13 -13
  45. package/dist/tools/emulation.d.ts +2 -0
  46. package/dist/tools/emulation.js +7 -0
  47. package/dist/tools/fill.js +344 -347
  48. package/dist/tools/find.js +78 -52
  49. package/dist/tools/highlight.js +67 -67
  50. package/dist/tools/inspect.js +54 -25
  51. package/dist/tools/key.js +42 -35
  52. package/dist/tools/navigate.d.ts +1 -1
  53. package/dist/tools/navigate.js +35 -35
  54. package/dist/tools/office/parse.js +62 -18
  55. package/dist/tools/pdf.d.ts +9 -0
  56. package/dist/tools/pdf.js +7 -4
  57. package/dist/tools/performance.d.ts +11 -4
  58. package/dist/tools/performance.js +94 -42
  59. package/dist/tools/performance_test.d.ts +2 -2
  60. package/dist/tools/performance_test.js +69 -69
  61. package/dist/tools/pointer.js +116 -116
  62. package/dist/tools/read.js +99 -67
  63. package/dist/tools/recording.js +9 -0
  64. package/dist/tools/scrape.js +146 -146
  65. package/dist/tools/screenshot.d.ts +2 -0
  66. package/dist/tools/screenshot.js +46 -4
  67. package/dist/tools/scroll.d.ts +3 -1
  68. package/dist/tools/scroll.js +13 -15
  69. package/dist/tools/select.d.ts +3 -0
  70. package/dist/tools/select.js +131 -124
  71. package/dist/tools/snapshot.js +8 -6
  72. package/dist/tools/storage.d.ts +5 -1
  73. package/dist/tools/storage.js +16 -0
  74. package/dist/tools/tabs.d.ts +7 -5
  75. package/dist/tools/tabs.js +79 -26
  76. package/dist/tools/thought.js +8 -8
  77. package/dist/tools/type.js +274 -274
  78. package/dist/tools/type_secret.js +23 -23
  79. package/dist/tools/upload.js +3 -3
  80. package/dist/tools/video_compiler.js +9 -0
  81. package/dist/tools/wait.js +35 -35
  82. package/dist/version.d.ts +1 -1
  83. package/dist/version.js +1 -1
  84. package/docs/DOCUMENTATION.md +583 -585
  85. package/docs/PLUGINS.md +139 -121
  86. package/docs/TOOLS.md +3 -4
  87. package/docs/architecture/blind-injection.md +83 -83
  88. package/docs/architecture/overview.md +49 -49
  89. package/docs/architecture/security.md +36 -36
  90. package/docs/architecture/transport.md +37 -37
  91. package/docs/cli/cli-commands.md +50 -50
  92. package/docs/cli/cli-flags.md +28 -28
  93. package/docs/cli/cli-scripting.md +35 -35
  94. package/docs/configuration/config-locations.md +23 -23
  95. package/docs/configuration/configuration.md +39 -27
  96. package/docs/configuration/env-variables.md +19 -19
  97. package/docs/configuration/folders.md +62 -55
  98. package/docs/desktop-automation/electron-apps.md +225 -214
  99. package/docs/get-started/installation.md +1 -1
  100. package/docs/get-started/introduction.md +60 -60
  101. package/docs/get-started/quickstart.md +2 -2
  102. package/docs/get-started/setup-wizard.md +27 -27
  103. package/docs/intelligence/site-profiles.md +151 -151
  104. package/docs/tools/tools.md +582 -631
  105. package/docs/troubleshooting/trouble-browser.md +27 -27
  106. package/docs/troubleshooting/trouble-loop.md +31 -31
  107. package/ext-dist/background.js +415 -415
  108. package/ext-dist/content.js +2527 -2527
  109. package/ext-dist/dashboard.html +583 -583
  110. package/ext-dist/hud/hud.js +3 -3
  111. package/ext-dist/hud/index.html +20 -20
  112. package/ext-dist/manifest.json +73 -73
  113. package/ext-dist/styles.css +223 -223
  114. package/mcp.json +796 -805
  115. package/package.json +118 -118
  116. package/server.json +23 -23
  117. package/dist/cdp/walker.test.d.ts +0 -2
  118. package/dist/cdp/walker.test.js +0 -172
  119. package/dist/intelligence/sessionMemory.test.d.ts +0 -2
  120. package/dist/intelligence/sessionMemory.test.js +0 -62
  121. package/dist/intelligence/trail.test.d.ts +0 -2
  122. package/dist/intelligence/trail.test.js +0 -110
  123. package/dist/state/cache.test.d.ts +0 -2
  124. package/dist/state/cache.test.js +0 -76
  125. package/dist/state/delta.test.d.ts +0 -2
  126. package/dist/state/delta.test.js +0 -279
  127. package/dist/state/groups.d.ts +0 -15
  128. package/dist/state/groups.js +0 -80
  129. package/dist/tools/accessibility.d.ts +0 -14
  130. package/dist/tools/accessibility.js +0 -32
  131. package/dist/tools/ask.d.ts +0 -14
  132. package/dist/tools/ask.js +0 -49
  133. package/dist/tools/click_and_wait.d.ts +0 -33
  134. package/dist/tools/click_and_wait.js +0 -149
  135. package/dist/tools/drag.d.ts +0 -15
  136. package/dist/tools/drag.js +0 -29
  137. package/dist/tools/geo.d.ts +0 -19
  138. package/dist/tools/geo.js +0 -29
  139. package/dist/tools/github/analyze.d.ts +0 -4
  140. package/dist/tools/github/analyze.js +0 -113
  141. package/dist/tools/github/cache.d.ts +0 -21
  142. package/dist/tools/github/cache.js +0 -28
  143. package/dist/tools/github/index.d.ts +0 -19
  144. package/dist/tools/github/index.js +0 -40
  145. package/dist/tools/github/issues.d.ts +0 -9
  146. package/dist/tools/github/issues.js +0 -88
  147. package/dist/tools/github/pr.d.ts +0 -5
  148. package/dist/tools/github/pr.js +0 -88
  149. package/dist/tools/github/rateLimiter.d.ts +0 -4
  150. package/dist/tools/github/rateLimiter.js +0 -46
  151. package/dist/tools/github/read.d.ts +0 -34
  152. package/dist/tools/github/read.js +0 -74
  153. package/dist/tools/github/repoContext.d.ts +0 -20
  154. package/dist/tools/github/repoContext.js +0 -129
  155. package/dist/tools/hover.d.ts +0 -19
  156. package/dist/tools/hover.js +0 -57
  157. package/dist/tools/integration.test.d.ts +0 -2
  158. package/dist/tools/integration.test.js +0 -96
  159. package/dist/tools/macro_compiler.d.ts +0 -7
  160. package/dist/tools/macro_compiler.js +0 -82
  161. package/dist/tools/mouse.d.ts +0 -21
  162. package/dist/tools/mouse.js +0 -62
  163. package/dist/tools/response.d.ts +0 -129
  164. package/dist/tools/response.js +0 -5
  165. package/dist/tools/wait_for.d.ts +0 -23
  166. package/dist/tools/wait_for.js +0 -30
  167. package/dist/tools/windows.d.ts +0 -22
  168. 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-42-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> &nbsp;&middot;&nbsp;
18
- <a href="docs/DOCUMENTATION.md">Documentation</a> &nbsp;&middot;&nbsp;
19
- <a href="ARCHITECTURE.md">Architecture</a> &nbsp;&middot;&nbsp;
20
- <a href="SUPPORT.md">Support</a> &nbsp;&middot;&nbsp;
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
- 42 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
- | **GitHub & Documents** | `browser_github` `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 in `~/.weavetab/policy.json`
213
- - **RBAC**: Four roles ΓÇö `admin`, `operator`, `viewer`, `automation` ΓÇö 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/logs/audit.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) &nbsp;&middot;&nbsp; [Discussions](https://github.com/weavetab/mcp/discussions) &nbsp;&middot;&nbsp; [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> &nbsp;&middot;&nbsp;
18
+ <a href="docs/DOCUMENTATION.md">Documentation</a> &nbsp;&middot;&nbsp;
19
+ <a href="ARCHITECTURE.md">Architecture</a> &nbsp;&middot;&nbsp;
20
+ <a href="SUPPORT.md">Support</a> &nbsp;&middot;&nbsp;
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) &nbsp;&middot;&nbsp; [Discussions](https://github.com/weavetab/mcp/discussions) &nbsp;&middot;&nbsp; [SUPPORT.md](SUPPORT.md)