iframer-toolkit 0.10.5 → 0.10.8
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/README.md +165 -65
- package/dist/cli.js +775 -78
- package/dist/local-server.cjs +948 -303
- package/dist/mcp-server.cjs +35 -5
- package/extension/manifest.json +1 -1
- package/package.json +1 -1
- package/skills/iframer.md +65 -10
package/README.md
CHANGED
|
@@ -1,23 +1,62 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<img src="docs/logo.svg" width="104" alt="iframer">
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
No. This is a tool I use almost EVERY SINGLE DAY and I have put a lot of thought and real engineering to actually make this a tool I am proud of.
|
|
7
|
-
Why did I develop this? Because I felt like the other agentic browsers didn't give me enough power and felt very expensive token-wise.
|
|
5
|
+
# iframer
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
Resulting rev API example:
|
|
12
|
-
<img width="2141" height="1173" alt="image" src="https://github.com/user-attachments/assets/19a27904-ebe0-4e65-8a44-a8cfb3756ed8" />
|
|
7
|
+
**Give an AI agent a real browser, get an API back.**<br>
|
|
8
|
+
Drive a site once and iframer hands the agent the actual request behind it, no devtools, no HAR file.
|
|
13
9
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
<img src="docs/example/demo.gif" width="760" alt="left: a demo page being clicked. right: the terminal, running iframer reverse-engineer, showing the captured endpoint">
|
|
18
|
+
|
|
19
|
+
</div>
|
|
20
|
+
|
|
21
|
+
Most agent-driven browsers only replay clicks. Every visit to the same page means rendering the whole thing again, screenshot after screenshot, just to read one field off it.
|
|
22
|
+
|
|
23
|
+
iframer drives a real, stealth-patched Chromium, or your own logged-in Chrome through the extension, and while it does:
|
|
24
|
+
|
|
25
|
+
- Records the fetch and XHR calls the page makes while it drives it (not static assets), no manual devtools work
|
|
26
|
+
- Hands back the real request behind a login form or a button click: method, headers, auth, a working curl
|
|
27
|
+
- Generates typed functions ready to `import`, when an agent is doing the driving
|
|
28
|
+
- Caches the domain after the first run, so the next visit skips the browser and hits the endpoint directly, seconds down to milliseconds
|
|
29
|
+
|
|
30
|
+
## Example
|
|
31
|
+
|
|
32
|
+
The left side of the GIF above is [`docs/example/site/index.html`](docs/example/site/index.html): one button, one hidden API call. The right side is a real terminal, only the typing pace was staged for the recording; the command and its output are exactly what running it produces. Capturing it for real:
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
cd docs/example/site && python3 -m http.server 8934 &
|
|
36
|
+
iframer-toolkit reverse-engineer '[
|
|
37
|
+
{"type":"navigate","url":"http://localhost:8934/index.html"},
|
|
38
|
+
{"type":"click","selector":"#load"},
|
|
39
|
+
{"type":"wait","ms":1000}
|
|
40
|
+
]' --output docs/example/api
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
That produced [`docs/example/api/captured-api.json`](docs/example/api/captured-api.json): the exact request, headers, response body, and a curl command, all automatic, no agent required.
|
|
44
|
+
|
|
45
|
+
The rest of `docs/example/api/` (`getTodos.ts`, `transport/rest.ts`, `types.ts`, `README.md`) is what an agent writes from that capture: iframer tells it the endpoint's protocol, verb, and function name, and the agent turns that into a typed function. That's what happened here, driven by Claude through the MCP `reverse-engineer` tool.
|
|
46
|
+
|
|
47
|
+
The whole round trip, one click to one typed endpoint, cost about 590 tokens back to the agent. This is the whole thing you get: no HAR file, no manual devtools work, a function you can call.
|
|
48
|
+
|
|
49
|
+
## Token cost
|
|
19
50
|
|
|
20
|
-
|
|
51
|
+
Most of iframer's savings come from the snapshot it hands back: capped and filtered, instead of the full accessibility tree other tools dump into context. Measured with the same tokenizer, same steps, on the same three tasks:
|
|
52
|
+
|
|
53
|
+
| Task | iframer (MCP) | iframer (CLI) | agent-browser | Playwright MCP |
|
|
54
|
+
|------|---------------|----------------|----------------|-----------------|
|
|
55
|
+
| Wiki link chase (6 hops, Everest → Gojo) | 517 | 721 | 913 | 1,405 |
|
|
56
|
+
| Store purchase (login → sort → cart → checkout) | 552 | 697 | 851 | 2,739 |
|
|
57
|
+
| Heavy-page recon (GitHub: look + pull 4 facts) | 986 | 1,058 | 8,433 | 19,906 |
|
|
58
|
+
|
|
59
|
+
The gap grows with how much DOM the page has. On the GitHub page, iframer spent about 986 tokens where Playwright MCP spent about 19,900, roughly 20x. That's per-task cost. It doesn't include the roughly 5.1k tokens of MCP tool-definition overhead loaded once per session, not per task.
|
|
21
60
|
|
|
22
61
|
## Install
|
|
23
62
|
|
|
@@ -47,11 +86,17 @@ iframer-toolkit update # update via npm (also refreshes the extensio
|
|
|
47
86
|
iframer-toolkit update --check # just report whether a newer version exists
|
|
48
87
|
```
|
|
49
88
|
|
|
50
|
-
|
|
89
|
+
Your agent can also just run `iframer-toolkit install` for you; it figures out the rest.
|
|
90
|
+
|
|
91
|
+
Ships as:
|
|
92
|
+
- **CLI** (`iframer-toolkit` / `iframer`): browse, screenshot, credentials, sessions, reverse-engineer APIs
|
|
93
|
+
- **MCP server**: plugs into Claude Code or Codex so agents drive the browser themselves
|
|
94
|
+
- **Browser extension** (optional): lets the agent drive tabs in your real Chrome, on your real logged-in session
|
|
95
|
+
- **Self-hosted Docker server** (optional): adds live headful browsing over noVNC for remote or multi-user setups
|
|
51
96
|
|
|
52
97
|
## Quick start
|
|
53
98
|
|
|
54
|
-
Once installed,
|
|
99
|
+
Once installed, drive the browser via the CLI directly, or ask your agent (Claude Code / Codex) to do it through the MCP.
|
|
55
100
|
|
|
56
101
|
**CLI:**
|
|
57
102
|
|
|
@@ -60,7 +105,7 @@ iframer-toolkit status # system + browser m
|
|
|
60
105
|
iframer-toolkit browse https://example.com --extract 'document.title'
|
|
61
106
|
iframer-toolkit screenshot https://news.ycombinator.com -o /tmp/hn.png
|
|
62
107
|
iframer-toolkit credentials add github.com # interactive masked prompt
|
|
63
|
-
iframer-toolkit reverse-engineer https://some-spa.com
|
|
108
|
+
iframer-toolkit reverse-engineer https://some-spa.com # capture the APIs it calls
|
|
64
109
|
iframer-toolkit --cache # list cached domains
|
|
65
110
|
```
|
|
66
111
|
|
|
@@ -68,44 +113,80 @@ iframer-toolkit --cache # list cached domain
|
|
|
68
113
|
|
|
69
114
|
> "Log into my account on example.com and extract the latest invoice."
|
|
70
115
|
|
|
71
|
-
The agent
|
|
116
|
+
The agent calls `knowledge` first to check for a cached direct-API path, falls back to `credentials` + `execute` if there isn't one, auto-escalates browser modes if a site blocks headless, and returns the result. No copying cookies, no proxies, no manual login.
|
|
72
117
|
|
|
73
118
|
## How it works
|
|
74
119
|
|
|
75
120
|
```
|
|
76
|
-
Claude / Codex (MCP)
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
121
|
+
Claude / Codex (MCP) ──▶ iframer MCP server ──▶ shared local server (127.0.0.1)
|
|
122
|
+
├─ patchright (stealth Chromium)
|
|
123
|
+
├─ Chrome for Testing
|
|
124
|
+
├─ your real Chrome (optional, via extension)
|
|
125
|
+
└─ SQLite at ~/.iframer: one file for
|
|
126
|
+
encrypted credentials, session state,
|
|
127
|
+
and per-domain knowledge cache
|
|
83
128
|
```
|
|
84
129
|
|
|
85
|
-
By default, `install mcp` runs in **local mode
|
|
130
|
+
By default, `install mcp` runs in **local mode**, no Docker needed. Both the MCP clients and the `iframer execute` CLI talk to one shared local server (discovered via `~/.iframer/server.json`, loopback only) that keeps a stealth-patched Chromium warm between calls, tracks every browser it spawns in an on-disk PID registry so nothing leaks, and idle-exits when no one needs it. `install mcp` registers the server in both Claude Code (`~/.claude.json`) and Codex (`~/.codex/config.toml`).
|
|
86
131
|
|
|
87
|
-
**Warm CLI.** `iframer execute` routes to that shared daemon instead of launching a cold browser per invocation, so after the first call it's as fast as the MCP (pass `--in-process` to force a private throwaway browser). Each agent gets its own browser instance
|
|
132
|
+
**Warm CLI.** `iframer execute` routes to that shared daemon instead of launching a cold browser per invocation, so after the first call it's as fast as the MCP (pass `--in-process` to force a private throwaway browser). Each agent gets its own browser instance, keyed off `CLAUDE_CODE_SESSION_ID` / `TERM_SESSION_ID` or `IFRAMER_INSTANCE`, so concurrent agents never share a window, while all CLI calls share one login session.
|
|
88
133
|
|
|
89
|
-
**Resuming a task.** The browser and its page persist in the daemon between calls and survive an interrupt (Ctrl-C). Name a multi-step or human-in-the-loop task's browser with a stable `instanceId`, and to resume
|
|
134
|
+
**Resuming a task.** The browser and its page persist in the daemon between calls and survive an interrupt (Ctrl-C). Name a multi-step or human-in-the-loop task's browser with a stable `instanceId`, and to resume, run `execute` again with the same `instanceId` and act on the current page (`snapshot` / `read` / `find`). Don't navigate again; that reloads the page and loses state like an OTP screen. `iframer instances` lists the live windows and which page each is on.
|
|
90
135
|
|
|
91
|
-
**One credential store for every browser mode.** Stored credentials, session cookies/localStorage, and the knowledge cache all live in
|
|
136
|
+
**One credential store for every browser mode.** Stored credentials, session cookies/localStorage, and the knowledge cache all live in one SQLite file at `~/.iframer/iframer.db`. Store a password once, from the CLI or the MCP, and every mode (`headless`, `binary-headful`, `docker-headful`) uses the same row.
|
|
92
137
|
|
|
93
|
-
**Auto-escalation.** When a pipeline is blocked in `headless` (bot detection, captcha), iframer
|
|
138
|
+
**Auto-escalation.** When a pipeline is blocked in `headless` (bot detection, captcha), iframer retries in `binary-headful` and then `docker-headful` without a round trip to the agent. The mode that worked is recorded in `~/.iframer/domain-modes.json`, so the next run on that domain starts at the right mode.
|
|
94
139
|
|
|
95
|
-
**Knowledge cache.** After every successful run, iframer writes a per-domain markdown file at `~/.iframer/knowledge/<domain>.md` recording which cookies
|
|
140
|
+
**Knowledge cache.** After every successful run, iframer writes a per-domain markdown file at `~/.iframer/knowledge/<domain>.md` recording which cookies, localStorage keys, and headers the site uses for auth, plus any API endpoints seen along the way. The next time an agent needs data from that domain, it reads the cache first; if there's a direct-API path, it skips the browser entirely. See [Knowledge cache](#knowledge-cache) below.
|
|
96
141
|
|
|
97
142
|
For live remote viewing, multi-user, or Linux server deployments, see [Self-hosting with Docker](#self-hosting-with-docker) below.
|
|
98
143
|
|
|
99
|
-
## Extension mode
|
|
144
|
+
## Extension mode: drive your real Chrome
|
|
145
|
+
|
|
146
|
+
The optional browser extension lets the agent drive a tab you already have open in your real Chrome. No relaunch, no remote-debugging port, your real logged-in session. The extension dials out to iframer's local server and relays the CDP protocol via `chrome.debugger`, so your live tab is driven by the exact same pipeline engine (find, click, snapshot, obstacle handling, API capture) as every other mode, with real trusted input. While a run is active, Chrome shows its yellow "started debugging" bar.
|
|
100
147
|
|
|
101
|
-
|
|
148
|
+
There's no Chrome Web Store listing. You load it as an unpacked, developer-mode extension, straight from the files npm just installed on your machine.
|
|
102
149
|
|
|
150
|
+
### Installing it
|
|
151
|
+
|
|
152
|
+
1. Run:
|
|
153
|
+
```sh
|
|
154
|
+
iframer install extension chrome
|
|
155
|
+
```
|
|
156
|
+
This installs a small pairing host and prints a folder path. That folder is the extension itself.
|
|
157
|
+
|
|
158
|
+
2. Open `chrome://extensions` in Chrome.
|
|
159
|
+
3. Turn on **Developer mode**, the toggle is top right.
|
|
160
|
+
4. Click **Load unpacked**.
|
|
161
|
+
5. In the file picker, paste the folder path from step 1 and select it.
|
|
162
|
+
|
|
163
|
+
Chrome loads the extension and pins its icon to the toolbar. That's the whole install, one time only.
|
|
164
|
+
|
|
165
|
+
### Finding the path again
|
|
166
|
+
|
|
167
|
+
Lost the path, or setting up a second machine? Run:
|
|
103
168
|
```sh
|
|
104
|
-
iframer
|
|
105
|
-
iframer extension path # prints it again
|
|
169
|
+
iframer extension path
|
|
106
170
|
```
|
|
171
|
+
It prints the same folder every time.
|
|
107
172
|
|
|
108
|
-
|
|
173
|
+
That folder lives inside wherever npm put `iframer-toolkit` globally, not inside a git checkout of this repo. On most machines that's something like `/usr/local/lib/node_modules/iframer-toolkit/extension` or, with nvm, a path under `~/.nvm/versions/node/<version>/lib/node_modules/iframer-toolkit/extension`. Run the command above instead of guessing, the exact path depends on your Node setup.
|
|
174
|
+
|
|
175
|
+
Loading it from that exact path matters: it's what lets `iframer update` refresh the extension files in place, then tell Chrome to reload it, no repeating the install steps after every update.
|
|
176
|
+
|
|
177
|
+
### Pairing (automatic)
|
|
178
|
+
|
|
179
|
+
Once loaded, the extension pairs itself. The pairing host installed in step 1 hands it the same local token the CLI and MCP already use, straight from `~/.iframer/secret`. Nothing to copy, nothing to type.
|
|
180
|
+
|
|
181
|
+
If that ever fails (host not installed, or you're on a platform it doesn't support), click the iframer icon in the toolbar and paste the token yourself:
|
|
182
|
+
```sh
|
|
183
|
+
cat ~/.iframer/secret
|
|
184
|
+
```
|
|
185
|
+
then **Save & connect**.
|
|
186
|
+
|
|
187
|
+
Either way, check the popup: the dot next to "iframer" turns green once it finds the running local server.
|
|
188
|
+
|
|
189
|
+
You can repeat this whole install on more than one Chrome profile, or in Brave, Edge, or another Chromium-based browser, at the same time. Each one pairs under its own profile name, and iframer routes each task to whichever profile actually has the tab. Once paired, the agent lists your open tabs with the `tabs` tool and drives the one you mean. See [`extension/README.md`](extension/README.md) for how the pipeline and multi-profile routing work under the hood.
|
|
109
190
|
|
|
110
191
|
## CLI reference
|
|
111
192
|
|
|
@@ -175,7 +256,7 @@ Setup:
|
|
|
175
256
|
|
|
176
257
|
Browser:
|
|
177
258
|
modes Show available browser modes
|
|
178
|
-
status
|
|
259
|
+
status Show system status
|
|
179
260
|
```
|
|
180
261
|
|
|
181
262
|
The binary is available as either `iframer-toolkit` (full name) or `iframer` (short alias). `npx iframer-toolkit ...` also works without a global install.
|
|
@@ -184,33 +265,33 @@ The binary is available as either `iframer-toolkit` (full name) or `iframer` (sh
|
|
|
184
265
|
|
|
185
266
|
Once the MCP is registered, the agent has access to:
|
|
186
267
|
|
|
187
|
-
- **`status
|
|
188
|
-
- **`knowledge
|
|
189
|
-
- **`execute
|
|
190
|
-
- **`browse
|
|
191
|
-
- **`reverse-engineer
|
|
192
|
-
- **`remember
|
|
193
|
-
- **`tabs
|
|
194
|
-
- **`clipboard
|
|
195
|
-
- **`session
|
|
196
|
-
- **`credentials
|
|
268
|
+
- **`status`**: system health, session state, stored credentials, available browser modes
|
|
269
|
+
- **`knowledge`**: read/list/clear the per-domain knowledge cache. Agents are told to check this before every `execute` or `browse`; if the cache already has a direct-API path, the browser never launches.
|
|
270
|
+
- **`execute`**: run a pipeline of browser steps (navigate, click, right-click, fill, select, human-click, human-type, type-code, read, evaluate, extract, wait, wait-for, scroll, keyboard, upload, paste, download, login, solve-captcha, recaptcha, screenshot, snapshot, find). Each step has a 20s stale-state timeout. On failure, it returns the exact step, error type, and a screenshot of the page at the point of failure. Auto-escalates browser modes on bot-block.
|
|
271
|
+
- **`browse`**: fast headless fetch with session persistence for pages that don't need a full pipeline
|
|
272
|
+
- **`reverse-engineer`**: capture the APIs a site calls (feeds the knowledge cache so future runs can skip the browser)
|
|
273
|
+
- **`remember`**: per-domain element anchors. Save a selector once under a name, then target it as `@a:<name>` in any later pipeline, no re-finding the element on every visit. Anchors self-heal (a failed anchor triggers re-discovery, not blind retries) and the tool also records per-site quirks.
|
|
274
|
+
- **`tabs`**: list and target tabs in your real Chrome (requires the [extension](#extension-mode-drive-your-real-chrome))
|
|
275
|
+
- **`clipboard`**: read/write the machine's clipboard, the same one your Chrome uses: read a code a site just copied, or stage text to paste into a field via the `paste` step
|
|
276
|
+
- **`session`**: `stop` (save state) or `clear` (wipe)
|
|
277
|
+
- **`credentials`**: `store` (secure form via MCP elicitation), `list`. `store` refuses to overwrite existing credentials unless told to (`force: true`), which blocks the common "login failed, re-ask for password" mistake when the real problem is browser mode or bot detection.
|
|
197
278
|
|
|
198
279
|
## Session persistence
|
|
199
280
|
|
|
200
|
-
Session data (cookies + localStorage) and credentials are stored in SQLite at `~/.iframer/iframer.db` and encrypted with AES-256-GCM. Data is automatically re-injected on the next `execute` or `browse` so agents stay logged in across restarts
|
|
281
|
+
Session data (cookies + localStorage) and credentials are stored in SQLite at `~/.iframer/iframer.db` and encrypted with AES-256-GCM. Data is automatically re-injected on the next `execute` or `browse` so agents stay logged in across restarts, and across browser modes: a session captured in `binary-headful` will load into `headless` on the next run.
|
|
201
282
|
|
|
202
|
-
The encryption key lives at `~/.iframer/secret` (0600 permissions), generated on first `install mcp`. Set `IFRAMER_SECRET` in your environment to override it
|
|
283
|
+
The encryption key lives at `~/.iframer/secret` (0600 permissions), generated on first `install mcp`. Set `IFRAMER_SECRET` in your environment to override it, useful if you want to sync the key across machines.
|
|
203
284
|
|
|
204
285
|
## Knowledge cache
|
|
205
286
|
|
|
206
|
-
Every successful `execute` run updates a plain markdown file at `~/.iframer/knowledge/<domain>.md
|
|
287
|
+
Every successful `execute` run updates a plain markdown file at `~/.iframer/knowledge/<domain>.md`, human-readable, grep-able, editable. Each file captures:
|
|
207
288
|
|
|
208
|
-
- Which cookies, localStorage keys, and headers are load-bearing for authentication (names only
|
|
209
|
-
- Which API endpoints the site called during the run
|
|
289
|
+
- Which cookies, localStorage keys, and headers are load-bearing for authentication (names only; values stay encrypted in the session store)
|
|
290
|
+
- Which API endpoints the site called during the run, with method, path, example curl, and status code
|
|
210
291
|
- Which browser mode last worked for the domain
|
|
211
|
-
- Notes about captcha
|
|
292
|
+
- Notes about captcha or bot-detection behavior
|
|
212
293
|
|
|
213
|
-
The MCP `knowledge` tool exposes this
|
|
294
|
+
The MCP `knowledge` tool exposes this with `get`, `list`, and `clear` actions. Agents are instructed to call it before every browser-touching tool; if the cache already has a direct-API path for the data, the agent hits the API directly and never launches a browser. First request takes seconds, repeat requests on the same domain take milliseconds.
|
|
214
295
|
|
|
215
296
|
Inspect the cache yourself:
|
|
216
297
|
|
|
@@ -223,7 +304,7 @@ iframer-toolkit --clear-cache figma.com # wipe one domain
|
|
|
223
304
|
|
|
224
305
|
## Captcha solving
|
|
225
306
|
|
|
226
|
-
iframer
|
|
307
|
+
iframer detects and solves reCAPTCHA and hCaptcha using Claude's vision API. Use the `solve-captcha` step in a pipeline:
|
|
227
308
|
|
|
228
309
|
```json
|
|
229
310
|
{ "type": "solve-captcha" }
|
|
@@ -245,9 +326,9 @@ Requires `ANTHROPIC_API_KEY` in your environment.
|
|
|
245
326
|
|
|
246
327
|
## Self-hosting with Docker
|
|
247
328
|
|
|
248
|
-
The Docker server adds a live headful browsing mode over noVNC (watch the agent drive the browser in real time) and lets multiple clients share one browser pool. The Docker path
|
|
329
|
+
The Docker server adds a live headful browsing mode over noVNC (watch the agent drive the browser in real time) and lets multiple clients share one browser pool. The Docker path only runs when a pipeline explicitly requests `mode: "docker-headful"`; `headless` and `binary-headful` always run directly on the host even when Docker is up, so host-stored credentials stay visible.
|
|
249
330
|
|
|
250
|
-
|
|
331
|
+
`docker-compose.yml` bind-mounts `~/.iframer` from the host into the container as `/iframer-data` and sets `IFRAMER_DATA_DIR=/iframer-data`, so container and host share the same SQLite file. Credentials stored via the CLI or MCP on the host are immediately visible to `docker-headful`, no copy step.
|
|
251
332
|
|
|
252
333
|
**1. Clone and configure**
|
|
253
334
|
|
|
@@ -255,7 +336,7 @@ The `docker-compose.yml` bind-mounts `~/.iframer` from the host into the contain
|
|
|
255
336
|
git clone https://github.com/EduardoFazolo/iframer-toolkit.git
|
|
256
337
|
cd iframer-toolkit
|
|
257
338
|
cp .env.example .env
|
|
258
|
-
# Edit .env
|
|
339
|
+
# Edit .env: set ANTHROPIC_API_KEY (for captcha) and IFRAMER_SECRET (for auth)
|
|
259
340
|
```
|
|
260
341
|
|
|
261
342
|
**2. Start**
|
|
@@ -268,13 +349,13 @@ bun run stop:docker # stop containers
|
|
|
268
349
|
|
|
269
350
|
**3. Point the MCP at it (remote host only)**
|
|
270
351
|
|
|
271
|
-
If
|
|
352
|
+
If Docker runs on a remote machine and the MCP on a different one, install the MCP with the remote URL:
|
|
272
353
|
|
|
273
354
|
```sh
|
|
274
355
|
IFRAMER_URL=https://your-host:3021 iframer-toolkit install mcp --dev
|
|
275
356
|
```
|
|
276
357
|
|
|
277
|
-
When Docker is on the same host as the MCP, no extra setup is needed
|
|
358
|
+
When Docker is on the same host as the MCP, no extra setup is needed; the local MCP server auto-detects the Docker API on `localhost:3021` and routes only `docker-headful` requests through it.
|
|
278
359
|
|
|
279
360
|
**4. Watch the browser live**
|
|
280
361
|
|
|
@@ -292,17 +373,36 @@ Or run `iframer-toolkit watch` to auto-open it.
|
|
|
292
373
|
|--------------------|------------|
|
|
293
374
|
| Browser engine | [patchright](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright) (stealth-patched Playwright fork) |
|
|
294
375
|
| Browser binary | Chrome for Testing (downloaded to `~/.iframer/chrome/`) |
|
|
295
|
-
| Local server | One shared warm server per machine (loopback
|
|
296
|
-
| Extension mode | Chrome extension relaying CDP over WebSocket (`chrome.debugger` → `connectOverCDP`)
|
|
376
|
+
| Local server | One shared warm server per machine (loopback only, discovered via `~/.iframer/server.json`), on-disk browser PID registry, idle auto-exit |
|
|
377
|
+
| Extension mode | Chrome extension relaying CDP over WebSocket (`chrome.debugger` → `connectOverCDP`), drives tabs in your real Chrome |
|
|
297
378
|
| Stealth | Fingerprint injection, WebRTC leak prevention, worker patching |
|
|
298
379
|
| Credential store | SQLite at `~/.iframer/iframer.db`, AES-256-GCM encrypted, shared by every browser mode |
|
|
299
|
-
| Session persistence| Same SQLite file
|
|
380
|
+
| Session persistence| Same SQLite file, cookies + localStorage re-injected across runs and modes |
|
|
300
381
|
| Knowledge cache | Plain markdown at `~/.iframer/knowledge/<domain>.md` |
|
|
301
382
|
| Captcha solving | Anthropic vision API (`@anthropic-ai/sdk`) |
|
|
302
383
|
| Live viewing | Xvfb + x11vnc + noVNC + websockify (Docker mode only) |
|
|
303
384
|
| MCP server | `@modelcontextprotocol/sdk` |
|
|
304
385
|
| Runtime | Node.js ≥18 (Bun for development) |
|
|
305
386
|
|
|
387
|
+
## Repo layout
|
|
388
|
+
|
|
389
|
+
```
|
|
390
|
+
src/lib/ core: pipeline executor, actions, auth, screenshot, knowledge cache
|
|
391
|
+
src/mcp/ MCP server + tool definitions
|
|
392
|
+
bin/cli.js CLI entry point
|
|
393
|
+
extension/ Chrome extension (manifest v3, CDP relay)
|
|
394
|
+
docs/example/ the demo in this README: site/ + captured api/
|
|
395
|
+
benchmark/ token-cost benchmark harness vs agent-browser and Playwright MCP (gitignored, local only)
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
## What's not done yet
|
|
399
|
+
|
|
400
|
+
- Stealth fingerprinting is injected right after the page loads, not at browser-context creation, so a site checking for it in the first tick of navigation can still catch it. This is the main remaining cause of false bot-blocks.
|
|
401
|
+
- The knowledge cache's markdown merge can drop an endpoint's description or example fields when the same domain is captured a second time.
|
|
402
|
+
- Consent banners rendered inside a cross-origin iframe (common with some CMPs) aren't recognized as an obstacle yet.
|
|
403
|
+
- Element anchors (`remember`) still have to be saved by hand after a successful run; auto-saving the selectors that worked isn't wired up.
|
|
404
|
+
- A few internal modules (the SQLite adapter, the stealth/humanize helpers) still carry loose `any` types.
|
|
405
|
+
|
|
306
406
|
## Development
|
|
307
407
|
|
|
308
408
|
```sh
|
|
@@ -310,7 +410,7 @@ git clone https://github.com/EduardoFazolo/iframer-toolkit.git
|
|
|
310
410
|
cd iframer-toolkit
|
|
311
411
|
bun install
|
|
312
412
|
|
|
313
|
-
# Run the CLI from source (no build needed
|
|
413
|
+
# Run the CLI from source (no build needed, bun runs .ts directly)
|
|
314
414
|
bun run bin/cli.js status
|
|
315
415
|
|
|
316
416
|
# Run the MCP server from source
|