@wordbricks/playwright-mcp 0.1.3

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 (95) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +624 -0
  3. package/cli-wrapper.js +47 -0
  4. package/cli.js +18 -0
  5. package/config.d.ts +119 -0
  6. package/index.d.ts +23 -0
  7. package/index.js +19 -0
  8. package/lib/browserContextFactory.js +289 -0
  9. package/lib/browserServerBackend.js +82 -0
  10. package/lib/config.js +246 -0
  11. package/lib/context.js +236 -0
  12. package/lib/extension/cdpRelay.js +346 -0
  13. package/lib/extension/extensionContextFactory.js +56 -0
  14. package/lib/frameworkPatterns.js +35 -0
  15. package/lib/hooks/core.js +144 -0
  16. package/lib/hooks/eventConsumer.js +39 -0
  17. package/lib/hooks/events.js +42 -0
  18. package/lib/hooks/formatToolCallEvent.js +16 -0
  19. package/lib/hooks/frameworkStateHook.js +182 -0
  20. package/lib/hooks/grouping.js +72 -0
  21. package/lib/hooks/jsonLdDetectionHook.js +175 -0
  22. package/lib/hooks/networkFilters.js +74 -0
  23. package/lib/hooks/networkSetup.js +56 -0
  24. package/lib/hooks/networkTrackingHook.js +55 -0
  25. package/lib/hooks/pageHeightHook.js +75 -0
  26. package/lib/hooks/registry.js +39 -0
  27. package/lib/hooks/requireTabHook.js +26 -0
  28. package/lib/hooks/schema.js +75 -0
  29. package/lib/hooks/waitHook.js +33 -0
  30. package/lib/index.js +39 -0
  31. package/lib/loop/loop.js +69 -0
  32. package/lib/loop/loopClaude.js +152 -0
  33. package/lib/loop/loopOpenAI.js +141 -0
  34. package/lib/loop/main.js +60 -0
  35. package/lib/loopTools/context.js +66 -0
  36. package/lib/loopTools/main.js +51 -0
  37. package/lib/loopTools/perform.js +32 -0
  38. package/lib/loopTools/snapshot.js +29 -0
  39. package/lib/loopTools/tool.js +18 -0
  40. package/lib/mcp/inProcessTransport.js +72 -0
  41. package/lib/mcp/proxyBackend.js +115 -0
  42. package/lib/mcp/server.js +86 -0
  43. package/lib/mcp/tool.js +29 -0
  44. package/lib/mcp/transport.js +181 -0
  45. package/lib/playwrightTransformer.js +497 -0
  46. package/lib/program.js +111 -0
  47. package/lib/response.js +186 -0
  48. package/lib/sessionLog.js +121 -0
  49. package/lib/tab.js +249 -0
  50. package/lib/tools/common.js +55 -0
  51. package/lib/tools/console.js +33 -0
  52. package/lib/tools/dialogs.js +47 -0
  53. package/lib/tools/evaluate.js +53 -0
  54. package/lib/tools/extractFrameworkState.js +214 -0
  55. package/lib/tools/files.js +44 -0
  56. package/lib/tools/getSnapshot.js +37 -0
  57. package/lib/tools/getVisibleHtml.js +52 -0
  58. package/lib/tools/install.js +53 -0
  59. package/lib/tools/keyboard.js +78 -0
  60. package/lib/tools/mouse.js +99 -0
  61. package/lib/tools/navigate.js +70 -0
  62. package/lib/tools/network.js +123 -0
  63. package/lib/tools/networkDetail.js +231 -0
  64. package/lib/tools/networkSearch/bodySearch.js +141 -0
  65. package/lib/tools/networkSearch/grouping.js +28 -0
  66. package/lib/tools/networkSearch/helpers.js +32 -0
  67. package/lib/tools/networkSearch/searchHtml.js +65 -0
  68. package/lib/tools/networkSearch/types.js +1 -0
  69. package/lib/tools/networkSearch/urlSearch.js +82 -0
  70. package/lib/tools/networkSearch.js +168 -0
  71. package/lib/tools/pdf.js +40 -0
  72. package/lib/tools/repl.js +402 -0
  73. package/lib/tools/screenshot.js +79 -0
  74. package/lib/tools/scroll.js +126 -0
  75. package/lib/tools/snapshot.js +139 -0
  76. package/lib/tools/tabs.js +87 -0
  77. package/lib/tools/tool.js +33 -0
  78. package/lib/tools/utils.js +74 -0
  79. package/lib/tools/wait.js +55 -0
  80. package/lib/tools.js +67 -0
  81. package/lib/utils/codegen.js +49 -0
  82. package/lib/utils/extensionPath.js +6 -0
  83. package/lib/utils/fileUtils.js +36 -0
  84. package/lib/utils/graphql.js +258 -0
  85. package/lib/utils/guid.js +22 -0
  86. package/lib/utils/httpServer.js +39 -0
  87. package/lib/utils/log.js +21 -0
  88. package/lib/utils/manualPromise.js +111 -0
  89. package/lib/utils/networkFormat.js +12 -0
  90. package/lib/utils/package.js +20 -0
  91. package/lib/utils/result.js +2 -0
  92. package/lib/utils/sanitizeHtml.js +98 -0
  93. package/lib/utils/truncate.js +103 -0
  94. package/lib/utils/withTimeout.js +7 -0
  95. package/package.json +100 -0
package/README.md ADDED
@@ -0,0 +1,624 @@
1
+ ## Playwright MCP
2
+
3
+ A Model Context Protocol (MCP) server that provides browser automation capabilities using [Playwright](https://playwright.dev). This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.
4
+
5
+ ### Key Features
6
+
7
+ - **Fast and lightweight**. Uses Playwright's accessibility tree, not pixel-based input.
8
+ - **LLM-friendly**. No vision models needed, operates purely on structured data.
9
+ - **Deterministic tool application**. Avoids ambiguity common with screenshot-based approaches.
10
+
11
+ ### Requirements
12
+ - Node.js 18 or newer
13
+ - VS Code, Cursor, Windsurf, Claude Desktop, Goose or any other MCP client
14
+
15
+ <!--
16
+ // Generate using:
17
+ node utils/generate-links.js
18
+ -->
19
+
20
+ ### Getting started
21
+
22
+ First, install the Playwright MCP server with your client.
23
+
24
+ **Standard config** works in most of the tools:
25
+
26
+ ```js
27
+ {
28
+ "mcpServers": {
29
+ "playwright": {
30
+ "command": "npx",
31
+ "args": [
32
+ "@wordbricks/playwright-mcp@latest"
33
+ ]
34
+ }
35
+ }
36
+ }
37
+ ```
38
+
39
+ [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
40
+
41
+
42
+ <details>
43
+ <summary>Claude Code</summary>
44
+
45
+ Use the Claude Code CLI to add the Playwright MCP server:
46
+
47
+ ```bash
48
+ claude mcp add playwright npx @wordbricks/playwright-mcp@latest
49
+ ```
50
+ </details>
51
+
52
+ <details>
53
+ <summary>Claude Desktop</summary>
54
+
55
+ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.
56
+
57
+ </details>
58
+
59
+ <details>
60
+ <summary>Cursor</summary>
61
+
62
+ #### Click the button to install:
63
+
64
+ [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
65
+
66
+ #### Or install manually:
67
+
68
+ Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @wordbricks/playwright-mcp`. You can also verify config or add command like arguments via clicking `Edit`.
69
+
70
+ </details>
71
+
72
+ <details>
73
+ <summary>Gemini CLI</summary>
74
+
75
+ Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.
76
+
77
+ </details>
78
+
79
+ <details>
80
+ <summary>Goose</summary>
81
+
82
+ #### Click the button to install:
83
+
84
+ [![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=%40playwright%2Fmcp%40latest&id=playwright&name=Playwright&description=Interact%20with%20web%20pages%20through%20structured%20accessibility%20snapshots%20using%20Playwright)
85
+
86
+ #### Or install manually:
87
+
88
+ Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @wordbricks/playwright-mcp`. Click "Add Extension".
89
+ </details>
90
+
91
+ <details>
92
+ <summary>LM Studio</summary>
93
+
94
+ #### Click the button to install:
95
+
96
+ [![Add MCP Server playwright to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=playwright&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAcGxheXdyaWdodC9tY3BAbGF0ZXN0Il19)
97
+
98
+ #### Or install manually:
99
+
100
+ Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
101
+ </details>
102
+
103
+ <details>
104
+ <summary>Qodo Gen</summary>
105
+
106
+ Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.
107
+
108
+ Click <code>Save</code>.
109
+ </details>
110
+
111
+ <details>
112
+ <summary>VS Code</summary>
113
+
114
+ #### Click the button to install:
115
+
116
+ [<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
117
+
118
+ #### Or install manually:
119
+
120
+ Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the Playwright MCP server using the VS Code CLI:
121
+
122
+ ```bash
123
+ # For VS Code
124
+ code --add-mcp '{"name":"playwright","command":"npx","args":["@wordbricks/playwright-mcp@latest"]}'
125
+ ```
126
+
127
+ After installation, the Playwright MCP server will be available for use with your GitHub Copilot agent in VS Code.
128
+ </details>
129
+
130
+ <details>
131
+ <summary>Windsurf</summary>
132
+
133
+ Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.
134
+
135
+ </details>
136
+
137
+ ### Configuration
138
+
139
+ Playwright MCP server supports following arguments. They can be provided in the JSON configuration above, as a part of the `"args"` list:
140
+
141
+ <!--- Options generated by update-readme.js -->
142
+
143
+ ```
144
+ > npx @wordbricks/playwright-mcp@latest --help
145
+ --allowed-origins <origins> semicolon-separated list of origins to allow the
146
+ browser to request. Default is to allow all.
147
+ --blocked-origins <origins> semicolon-separated list of origins to block the
148
+ browser from requesting. Blocklist is evaluated
149
+ before allowlist. If used without the allowlist,
150
+ requests not matching the blocklist are still
151
+ allowed.
152
+ --block-service-workers block service workers
153
+ --browser <browser> browser or chrome channel to use, possible
154
+ values: chrome, firefox, webkit, msedge.
155
+ --caps <caps> comma-separated list of additional capabilities
156
+ to enable, possible values: vision, pdf.
157
+ --cdp-endpoint <endpoint> CDP endpoint to connect to.
158
+ --config <path> path to the configuration file.
159
+ --device <device> device to emulate, for example: "iPhone 15"
160
+ --executable-path <path> path to the browser executable.
161
+ --headless run browser in headless mode, headed by default
162
+ --host <host> host to bind server to. Default is localhost. Use
163
+ 0.0.0.0 to bind to all interfaces.
164
+ --ignore-https-errors ignore https errors
165
+ --isolated keep the browser profile in memory, do not save
166
+ it to disk.
167
+ --image-responses <mode> whether to send image responses to the client.
168
+ Can be "allow" or "omit", Defaults to "allow".
169
+ --no-sandbox disable the sandbox for all process types that
170
+ are normally sandboxed.
171
+ --output-dir <path> path to the directory for output files.
172
+ --port <port> port to listen on for SSE transport.
173
+ --proxy-bypass <bypass> comma-separated domains to bypass proxy, for
174
+ example ".com,chromium.org,.domain.com"
175
+ --proxy-server <proxy> specify proxy server, for example
176
+ "http://myproxy:3128" or "socks5://myproxy:8080"
177
+ --save-session Whether to save the Playwright MCP session into
178
+ the output directory.
179
+ --save-trace Whether to save the Playwright Trace of the
180
+ session into the output directory.
181
+ --storage-state <path> path to the storage state file for isolated
182
+ sessions.
183
+ --user-agent <ua string> specify user agent string
184
+ --user-data-dir <path> path to the user data directory. If not
185
+ specified, a temporary directory will be created.
186
+ --viewport-size <size> specify browser viewport size in pixels, for
187
+ example "1280, 720"
188
+ ```
189
+
190
+ <!--- End of options generated section -->
191
+
192
+ ### User profile
193
+
194
+ You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.
195
+
196
+ **Persistent profile**
197
+
198
+ All the logged in information will be stored in the persistent profile, you can delete it between sessions if you'd like to clear the offline state.
199
+ Persistent profile is located at the following locations and you can override it with the `--user-data-dir` argument.
200
+
201
+ ```bash
202
+ # Windows
203
+ %USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile
204
+
205
+ # macOS
206
+ - ~/Library/Caches/ms-playwright/mcp-{channel}-profile
207
+
208
+ # Linux
209
+ - ~/.cache/ms-playwright/mcp-{channel}-profile
210
+ ```
211
+
212
+ **Isolated**
213
+
214
+ In the isolated mode, each session is started in the isolated profile. Every time you ask MCP to close the browser,
215
+ the session is closed and all the storage state for this session is lost. You can provide initial storage state
216
+ to the browser via the config's `contextOptions` or via the `--storage-state` argument. Learn more about the storage
217
+ state [here](https://playwright.dev/docs/auth).
218
+
219
+ ```js
220
+ {
221
+ "mcpServers": {
222
+ "playwright": {
223
+ "command": "npx",
224
+ "args": [
225
+ "@wordbricks/playwright-mcp@latest",
226
+ "--isolated",
227
+ "--storage-state={path/to/storage.json}"
228
+ ]
229
+ }
230
+ }
231
+ }
232
+ ```
233
+
234
+ ### Configuration file
235
+
236
+ The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
237
+ using the `--config` command line option:
238
+
239
+ ```bash
240
+ npx @wordbricks/playwright-mcp@latest --config path/to/config.json
241
+ ```
242
+
243
+ <details>
244
+ <summary>Configuration file schema</summary>
245
+
246
+ ```typescript
247
+ {
248
+ // Browser configuration
249
+ browser?: {
250
+ // Browser type to use (chromium, firefox, or webkit)
251
+ browserName?: 'chromium' | 'firefox' | 'webkit';
252
+
253
+ // Keep the browser profile in memory, do not save it to disk.
254
+ isolated?: boolean;
255
+
256
+ // Path to user data directory for browser profile persistence
257
+ userDataDir?: string;
258
+
259
+ // Browser launch options (see Playwright docs)
260
+ // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
261
+ launchOptions?: {
262
+ channel?: string; // Browser channel (e.g. 'chrome')
263
+ headless?: boolean; // Run in headless mode
264
+ executablePath?: string; // Path to browser executable
265
+ // ... other Playwright launch options
266
+ };
267
+
268
+ // Browser context options
269
+ // @see https://playwright.dev/docs/api/class-browser#browser-new-context
270
+ contextOptions?: {
271
+ viewport?: { width: number, height: number };
272
+ // ... other Playwright context options
273
+ };
274
+
275
+ // CDP endpoint for connecting to existing browser
276
+ cdpEndpoint?: string;
277
+
278
+ // Remote Playwright server endpoint
279
+ remoteEndpoint?: string;
280
+ },
281
+
282
+ // Server configuration
283
+ server?: {
284
+ port?: number; // Port to listen on
285
+ host?: string; // Host to bind to (default: localhost)
286
+ },
287
+
288
+ // List of additional capabilities
289
+ capabilities?: Array<
290
+ 'tabs' | // Tab management
291
+ 'install' | // Browser installation
292
+ 'pdf' | // PDF generation
293
+ 'vision' | // Coordinate-based interactions
294
+ >;
295
+
296
+ // Directory for output files
297
+ outputDir?: string;
298
+
299
+ // Network configuration
300
+ network?: {
301
+ // List of origins to allow the browser to request. Default is to allow all. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
302
+ allowedOrigins?: string[];
303
+
304
+ // List of origins to block the browser to request. Origins matching both `allowedOrigins` and `blockedOrigins` will be blocked.
305
+ blockedOrigins?: string[];
306
+ };
307
+
308
+ /**
309
+ * Whether to send image responses to the client. Can be "allow" or "omit".
310
+ * Defaults to "allow".
311
+ */
312
+ imageResponses?: 'allow' | 'omit';
313
+ }
314
+ ```
315
+ </details>
316
+
317
+ ### Standalone MCP server
318
+
319
+ When running headed browser on system w/o display or from worker processes of the IDEs,
320
+ run the MCP server from environment with the DISPLAY and pass the `--port` flag to enable HTTP transport.
321
+
322
+ ```bash
323
+ npx @wordbricks/playwright-mcp@latest --port 8931
324
+ ```
325
+
326
+ And then in MCP client config, set the `url` to the HTTP endpoint:
327
+
328
+ ```js
329
+ {
330
+ "mcpServers": {
331
+ "playwright": {
332
+ "url": "http://localhost:8931/mcp"
333
+ }
334
+ }
335
+ }
336
+ ```
337
+
338
+ <details>
339
+ <summary><b>Docker</b></summary>
340
+
341
+ **NOTE:** The Docker implementation only supports headless chromium at the moment.
342
+
343
+ ```js
344
+ {
345
+ "mcpServers": {
346
+ "playwright": {
347
+ "command": "docker",
348
+ "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
349
+ }
350
+ }
351
+ }
352
+ ```
353
+
354
+ You can build the Docker image yourself.
355
+
356
+ ```
357
+ docker build -t mcr.microsoft.com/playwright/mcp .
358
+ ```
359
+ </details>
360
+
361
+ <details>
362
+ <summary><b>Programmatic usage</b></summary>
363
+
364
+ ```js
365
+ import http from 'http';
366
+
367
+ import { createConnection } from '@wordbricks/playwright-mcp';
368
+ import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
369
+
370
+ http.createServer(async (req, res) => {
371
+ // ...
372
+
373
+ // Creates a headless Playwright MCP server with SSE transport
374
+ const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
375
+ const transport = new SSEServerTransport('/messages', res);
376
+ await connection.sever.connect(transport);
377
+
378
+ // ...
379
+ });
380
+ ```
381
+ </details>
382
+
383
+ ### Tools
384
+
385
+ <!--- Tools generated by update-readme.js -->
386
+
387
+ <details>
388
+ <summary><b>Core automation</b></summary>
389
+
390
+ <!-- NOTE: This has been generated via update-readme.js -->
391
+
392
+ - **browser_click**
393
+ - Title: Click
394
+ - Description: Perform click on a web page
395
+ - Parameters:
396
+ - `element` (string): Human-readable element description used to obtain permission to interact with the element
397
+ - `ref` (string): Exact target element reference from the page snapshot
398
+ - `doubleClick` (boolean, optional): Whether to perform a double click instead of a single click
399
+ - `button` (string, optional): Button to click, defaults to left
400
+ - Read-only: **false**
401
+
402
+ <!-- NOTE: This has been generated via update-readme.js -->
403
+
404
+ - **browser_close**
405
+ - Title: Close browser
406
+ - Description: Close the page
407
+ - Parameters: None
408
+ - Read-only: **true**
409
+
410
+ <!-- NOTE: This has been generated via update-readme.js -->
411
+
412
+ - **browser_console_messages**
413
+ - Title: Get console messages
414
+ - Description: Returns all console messages
415
+ - Parameters: None
416
+ - Read-only: **true**
417
+
418
+ <!-- NOTE: This has been generated via update-readme.js -->
419
+
420
+ - **browser_drag**
421
+ - Title: Drag mouse
422
+ - Description: Perform drag and drop between two elements
423
+ - Parameters:
424
+ - `startElement` (string): Human-readable source element description used to obtain the permission to interact with the element
425
+ - `startRef` (string): Exact source element reference from the page snapshot
426
+ - `endElement` (string): Human-readable target element description used to obtain the permission to interact with the element
427
+ - `endRef` (string): Exact target element reference from the page snapshot
428
+ - Read-only: **false**
429
+
430
+ <!-- NOTE: This has been generated via update-readme.js -->
431
+
432
+ - **browser_evaluate**
433
+ - Title: Evaluate JavaScript
434
+ - Description: Evaluate JavaScript expression on page or element
435
+ - Parameters:
436
+ - `function` (string): () => { /* code */ } or (element) => { /* code */ } when element is provided
437
+ - `element` (string, optional): Human-readable element description used to obtain permission to interact with the element
438
+ - `ref` (string, optional): Exact target element reference from the page snapshot
439
+ - Read-only: **false**
440
+
441
+ <!-- NOTE: This has been generated via update-readme.js -->
442
+
443
+ - **browser_extract_framework_state**
444
+ - Title: Extract framework state
445
+ - Description: Extract framework state data from web pages (React, Redux, Remix, etc.)
446
+ - Parameters:
447
+ - `framework` (string, optional): Optional: specific key to extract from (e.g., "__remixContext")
448
+ - `path` (string, optional): Path to extract (e.g., "state.loaderData")
449
+ - Read-only: **true**
450
+
451
+ <!-- NOTE: This has been generated via update-readme.js -->
452
+
453
+ - **browser_get_snapshot**
454
+ - Title: Get snapshot
455
+ - Description: Get accessibility snapshot of the current page
456
+ - Parameters: None
457
+ - Read-only: **true**
458
+
459
+ <!-- NOTE: This has been generated via update-readme.js -->
460
+
461
+ - **browser_get_visible_html**
462
+ - Title: Get visible HTML
463
+ - Description: Get HTML content of the page or a specific element
464
+ - Parameters:
465
+ - `selector` (string, optional): CSS selector for a specific element (optional)
466
+ - `cleanHtml` (boolean, optional): Clean HTML (true) or raw HTML (false)
467
+ - `removeScripts` (boolean, optional): Remove scripts (true) or keep them (false)
468
+ - `removeStyles` (boolean, optional): Remove styles (true) or keep them (false)
469
+ - Read-only: **true**
470
+
471
+ <!-- NOTE: This has been generated via update-readme.js -->
472
+
473
+ - **browser_hover**
474
+ - Title: Hover mouse
475
+ - Description: Hover over element on page
476
+ - Parameters:
477
+ - `element` (string): Human-readable element description used to obtain permission to interact with the element
478
+ - `ref` (string): Exact target element reference from the page snapshot
479
+ - Read-only: **true**
480
+
481
+ <!-- NOTE: This has been generated via update-readme.js -->
482
+
483
+ - **browser_navigate**
484
+ - Title: Navigate to a URL
485
+ - Description: Navigate to a URL
486
+ - Parameters:
487
+ - `url` (string): The URL to navigate to
488
+ - Read-only: **false**
489
+
490
+ <!-- NOTE: This has been generated via update-readme.js -->
491
+
492
+ - **browser_navigate_back**
493
+ - Title: Go back
494
+ - Description: Go back to the previous page
495
+ - Parameters: None
496
+ - Read-only: **true**
497
+
498
+ <!-- NOTE: This has been generated via update-readme.js -->
499
+
500
+ - **browser_navigate_forward**
501
+ - Title: Go forward
502
+ - Description: Go forward to the next page
503
+ - Parameters: None
504
+ - Read-only: **true**
505
+
506
+ <!-- NOTE: This has been generated via update-readme.js -->
507
+
508
+ - **browser_network_detail**
509
+ - Title: Get network request detail
510
+ - Description: Show detailed info for a specific network request by event id. Call repeatedly to page through the body.
511
+ - Parameters:
512
+ - `id` (number): The network event id from events log
513
+ - Read-only: **true**
514
+
515
+ <!-- NOTE: This has been generated via update-readme.js -->
516
+
517
+ - **browser_network_requests**
518
+ - Title: List network requests
519
+ - Description: Returns all network requests since loading the page
520
+ - Parameters: None
521
+ - Read-only: **true**
522
+
523
+ <!-- NOTE: This has been generated via update-readme.js -->
524
+
525
+ - **browser_network_search**
526
+ - Title: Search network requests
527
+ - Description: Search for keywords in network request/response bodies and URLs
528
+ - Parameters:
529
+ - `keyword` (string): Keyword or phrase; avoid generic words—specific terms reduce noise and improve precision.
530
+ - Read-only: **true**
531
+
532
+ <!-- NOTE: This has been generated via update-readme.js -->
533
+
534
+ - **browser_press_key**
535
+ - Title: Press a key
536
+ - Description: Press a key on the keyboard
537
+ - Parameters:
538
+ - `key` (string): Name of the key to press or a character to generate, such as `ArrowLeft` or `a`
539
+ - Read-only: **false**
540
+
541
+ <!-- NOTE: This has been generated via update-readme.js -->
542
+
543
+ - **browser_repl**
544
+ - Title: Browser REPL
545
+ - Description: DevTools-like browser REPL. Per-tab state persists across calls (const/let/functions); supports top-level await. Survives SPA nav; resets on full reload or when switching tabs. Helpers available via window.mcp: JSON5, JSONPath, _, GraphQLClient, gql, graphqlRequest. No need for wrapping in IIFE.
546
+ - Parameters:
547
+ - `script` (string): JavaScript code to execute in the browser console.
548
+ - Read-only: **false**
549
+
550
+ <!-- NOTE: This has been generated via update-readme.js -->
551
+
552
+ - **browser_resize**
553
+ - Title: Resize browser window
554
+ - Description: Resize the browser window
555
+ - Parameters:
556
+ - `width` (number): Width of the browser window
557
+ - `height` (number): Height of the browser window
558
+ - Read-only: **true**
559
+
560
+ <!-- NOTE: This has been generated via update-readme.js -->
561
+
562
+ - **browser_scroll**
563
+ - Title: Scroll page
564
+ - Description: Scroll the page using mouse wheel with human-like behavior
565
+ - Parameters:
566
+ - `amount` (number): Vertical scroll amount in pixels (positive scrolls down, negative up)
567
+ - Read-only: **false**
568
+
569
+ <!-- NOTE: This has been generated via update-readme.js -->
570
+
571
+ - **browser_select_option**
572
+ - Title: Select option
573
+ - Description: Select an option in a dropdown
574
+ - Parameters:
575
+ - `element` (string): Human-readable element description used to obtain permission to interact with the element
576
+ - `ref` (string): Exact target element reference from the page snapshot
577
+ - `values` (array): Array of values to select in the dropdown. This can be a single value or multiple values.
578
+ - Read-only: **false**
579
+
580
+ <!-- NOTE: This has been generated via update-readme.js -->
581
+
582
+ - **browser_snapshot**
583
+ - Title: Page snapshot
584
+ - Description: Capture accessibility snapshot of the current page, this is better than screenshot
585
+ - Parameters: None
586
+ - Read-only: **true**
587
+
588
+ <!-- NOTE: This has been generated via update-readme.js -->
589
+
590
+ - **browser_type**
591
+ - Title: Type text
592
+ - Description: Type text into editable element
593
+ - Parameters:
594
+ - `element` (string): Human-readable element description used to obtain permission to interact with the element
595
+ - `ref` (string): Exact target element reference from the page snapshot
596
+ - `text` (string): Text to type into the element
597
+ - `submit` (boolean, optional): Whether to submit entered text (press Enter after)
598
+ - `slowly` (boolean, optional): Whether to type one character at a time. Useful for triggering key handlers in the page. By default entire text is filled in at once.
599
+ - Read-only: **false**
600
+
601
+ </details>
602
+
603
+ <details>
604
+ <summary><b>Tab management</b></summary>
605
+
606
+ </details>
607
+
608
+ <details>
609
+ <summary><b>Browser installation</b></summary>
610
+
611
+ </details>
612
+
613
+ <details>
614
+ <summary><b>Coordinate-based (opt-in via --caps=vision)</b></summary>
615
+
616
+ </details>
617
+
618
+ <details>
619
+ <summary><b>PDF generation (opt-in via --caps=pdf)</b></summary>
620
+
621
+ </details>
622
+
623
+
624
+ <!--- End of tools generated section -->
package/cli-wrapper.js ADDED
@@ -0,0 +1,47 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Copyright (c) Microsoft Corporation.
4
+ *
5
+ * Licensed under the Apache License, Version 2.0 (the "License");
6
+ * you may not use this file except in compliance with the License.
7
+ * You may obtain a copy of the License at
8
+ *
9
+ * http://www.apache.org/licenses/LICENSE-2.0
10
+ *
11
+ * Unless required by applicable law or agreed to in writing, software
12
+ * distributed under the License is distributed on an "AS IS" BASIS,
13
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ * See the License for the specific language governing permissions and
15
+ * limitations under the License.
16
+ */
17
+
18
+ import { spawn } from 'child_process';
19
+ import { fileURLToPath } from 'url';
20
+ import { dirname, join } from 'path';
21
+
22
+ const __filename = fileURLToPath(import.meta.url);
23
+ const __dirname = dirname(__filename);
24
+
25
+ const isBunRuntime = 'bun' in process.versions;
26
+ const isRunViaBundle = process.env.npm_execpath && process.env.npm_execpath.includes('bunx');
27
+
28
+ if (!isBunRuntime && isRunViaBundle) {
29
+ const cliPath = join(__dirname, 'cli.js');
30
+ const args = process.argv.slice(2);
31
+
32
+ const bunProcess = spawn('bun', [cliPath, ...args], {
33
+ stdio: 'inherit',
34
+ env: { ...process.env, FORCE_BUN_RUNTIME: '1' }
35
+ });
36
+
37
+ bunProcess.on('exit', (code) => {
38
+ process.exit(code || 0);
39
+ });
40
+
41
+ bunProcess.on('error', (err) => {
42
+ console.error('Failed to run with bun:', err.message);
43
+ import('./lib/program.js');
44
+ });
45
+ } else {
46
+ import('./lib/program.js');
47
+ }
package/cli.js ADDED
@@ -0,0 +1,18 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Copyright (c) Microsoft Corporation.
4
+ *
5
+ * Licensed under the Apache License, Version 2.0 (the "License");
6
+ * you may not use this file except in compliance with the License.
7
+ * You may obtain a copy of the License at
8
+ *
9
+ * http://www.apache.org/licenses/LICENSE-2.0
10
+ *
11
+ * Unless required by applicable law or agreed to in writing, software
12
+ * distributed under the License is distributed on an "AS IS" BASIS,
13
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14
+ * See the License for the specific language governing permissions and
15
+ * limitations under the License.
16
+ */
17
+
18
+ import './lib/program.js';