safari-devtools-mcp 0.1.1 → 0.1.2
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 +83 -171
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,62 +1,35 @@
|
|
|
1
1
|
# Safari DevTools MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://npmjs.org/package/safari-devtools-mcp)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`safari-devtools-mcp` lets your coding agent (such as Claude, Cursor, Copilot or Gemini) control and inspect a live Safari browser on macOS. It acts as a Model-Context-Protocol (MCP) server, giving your AI coding assistant access to Safari DevTools for debugging, automation, and testing.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
- **
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
- **Cross-browser compatible** — matching tool names with chrome-devtools-mcp
|
|
7
|
+
## [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md)
|
|
8
|
+
|
|
9
|
+
## Key features
|
|
10
|
+
|
|
11
|
+
- **Browser debugging**: Capture console logs, inspect network requests, and evaluate JavaScript — with stack traces and full request/response details.
|
|
12
|
+
- **Reliable automation**: Click, type, fill forms, drag and drop, and press keyboard shortcuts using accessibility-tree snapshots with stable UIDs.
|
|
13
|
+
- **Native macOS integration**: Tab management via AppleScript for listing, switching, and controlling Safari tabs across windows.
|
|
15
14
|
|
|
16
15
|
## Requirements
|
|
17
16
|
|
|
18
17
|
- **macOS** (Safari and SafariDriver are Apple-exclusive)
|
|
19
|
-
- **Node.js 18+** (22+ recommended
|
|
20
|
-
- **Safari** with
|
|
18
|
+
- **Node.js 18+** (22+ recommended)
|
|
19
|
+
- **Safari** with remote automation enabled
|
|
21
20
|
|
|
22
|
-
### Safari
|
|
21
|
+
### Safari setup
|
|
23
22
|
|
|
24
|
-
1. Open Safari
|
|
25
|
-
2.
|
|
23
|
+
1. Open Safari > Settings > Advanced > check **"Show features for web developers"**
|
|
24
|
+
2. Develop menu > check **"Allow Remote Automation"**
|
|
26
25
|
3. Authorize SafariDriver:
|
|
27
26
|
```bash
|
|
28
27
|
sudo safaridriver --enable
|
|
29
28
|
```
|
|
30
29
|
|
|
31
|
-
## Getting
|
|
32
|
-
|
|
33
|
-
### Install from npm
|
|
34
|
-
|
|
35
|
-
```bash
|
|
36
|
-
npx safari-devtools-mcp
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
### Install from source
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
git clone https://github.com/HayoDev/safari-devtools-mcp.git
|
|
43
|
-
cd safari-devtools-mcp
|
|
44
|
-
npm install
|
|
45
|
-
npm run build
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
### MCP Client Configuration
|
|
49
|
-
|
|
50
|
-
<details>
|
|
51
|
-
<summary>Claude Code</summary>
|
|
52
|
-
|
|
53
|
-
Run this command:
|
|
54
|
-
|
|
55
|
-
```bash
|
|
56
|
-
claude mcp add safari-devtools -- npx safari-devtools-mcp
|
|
57
|
-
```
|
|
30
|
+
## Getting started
|
|
58
31
|
|
|
59
|
-
|
|
32
|
+
Standard MCP config:
|
|
60
33
|
|
|
61
34
|
```json
|
|
62
35
|
{
|
|
@@ -69,77 +42,57 @@ Or add to your project's `.mcp.json`:
|
|
|
69
42
|
}
|
|
70
43
|
```
|
|
71
44
|
|
|
72
|
-
</details>
|
|
73
|
-
|
|
74
45
|
<details>
|
|
75
|
-
<summary>Claude
|
|
76
|
-
|
|
77
|
-
Add to your `claude_desktop_config.json`:
|
|
46
|
+
<summary>Claude Code</summary>
|
|
78
47
|
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
"mcpServers": {
|
|
82
|
-
"safari-devtools": {
|
|
83
|
-
"command": "npx",
|
|
84
|
-
"args": ["safari-devtools-mcp"]
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
}
|
|
48
|
+
```bash
|
|
49
|
+
claude mcp add safari-devtools -- npx safari-devtools-mcp
|
|
88
50
|
```
|
|
89
51
|
|
|
90
|
-
|
|
52
|
+
Or add to your project's `.mcp.json` using the standard config above.
|
|
53
|
+
|
|
54
|
+
</details>
|
|
55
|
+
|
|
56
|
+
<details>
|
|
57
|
+
<summary>Claude Desktop</summary>
|
|
91
58
|
|
|
92
|
-
|
|
59
|
+
Add the standard config to `~/Library/Application Support/Claude/claude_desktop_config.json`.
|
|
93
60
|
|
|
94
61
|
</details>
|
|
95
62
|
|
|
96
63
|
<details>
|
|
97
64
|
<summary>Cursor</summary>
|
|
98
65
|
|
|
99
|
-
Add to your Cursor MCP settings
|
|
100
|
-
|
|
101
|
-
```json
|
|
102
|
-
{
|
|
103
|
-
"mcpServers": {
|
|
104
|
-
"safari-devtools": {
|
|
105
|
-
"command": "npx",
|
|
106
|
-
"args": ["safari-devtools-mcp"]
|
|
107
|
-
}
|
|
108
|
-
}
|
|
109
|
-
}
|
|
110
|
-
```
|
|
66
|
+
Add the standard config to your Cursor MCP settings.
|
|
111
67
|
|
|
112
68
|
</details>
|
|
113
69
|
|
|
114
70
|
<details>
|
|
115
71
|
<summary>VS Code</summary>
|
|
116
72
|
|
|
117
|
-
Add
|
|
118
|
-
|
|
119
|
-
```json
|
|
120
|
-
{
|
|
121
|
-
"mcpServers": {
|
|
122
|
-
"safari-devtools": {
|
|
123
|
-
"command": "npx",
|
|
124
|
-
"args": ["safari-devtools-mcp"]
|
|
125
|
-
}
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
```
|
|
73
|
+
Add the standard config to `.vscode/mcp.json`.
|
|
129
74
|
|
|
130
75
|
</details>
|
|
131
76
|
|
|
132
77
|
<details>
|
|
133
|
-
<summary>From source
|
|
78
|
+
<summary>From source</summary>
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
git clone https://github.com/HayoDev/safari-devtools-mcp.git
|
|
82
|
+
cd safari-devtools-mcp
|
|
83
|
+
npm install && npm run build
|
|
84
|
+
```
|
|
134
85
|
|
|
135
|
-
|
|
86
|
+
Then point your MCP client to the built entry point:
|
|
136
87
|
|
|
137
88
|
```json
|
|
138
89
|
{
|
|
139
90
|
"mcpServers": {
|
|
140
91
|
"safari-devtools": {
|
|
141
92
|
"command": "node",
|
|
142
|
-
"args": [
|
|
93
|
+
"args": [
|
|
94
|
+
"/path/to/safari-devtools-mcp/build/src/bin/safari-devtools-mcp.js"
|
|
95
|
+
]
|
|
143
96
|
}
|
|
144
97
|
}
|
|
145
98
|
}
|
|
@@ -147,50 +100,50 @@ If you cloned the repo, point to the built entry point:
|
|
|
147
100
|
|
|
148
101
|
</details>
|
|
149
102
|
|
|
150
|
-
### Your
|
|
103
|
+
### Your first prompt
|
|
151
104
|
|
|
152
105
|
> Navigate to https://example.com, take a snapshot, and list any console errors.
|
|
153
106
|
|
|
154
|
-
## Tools
|
|
107
|
+
## Tools (25)
|
|
155
108
|
|
|
156
|
-
### Debugging
|
|
109
|
+
### Debugging
|
|
157
110
|
|
|
158
|
-
| Tool | Description
|
|
159
|
-
| ----------------------- |
|
|
160
|
-
| `list_console_messages` | List console messages with filtering by level
|
|
161
|
-
| `get_console_message` | Get detailed message
|
|
162
|
-
| `list_network_requests` | Monitor network requests
|
|
163
|
-
| `get_network_request` | Get full request/response with headers
|
|
164
|
-
| `evaluate_script` | Execute JavaScript in the browser context
|
|
165
|
-
| `take_screenshot` | Capture page or
|
|
166
|
-
| `take_snapshot` |
|
|
111
|
+
| Tool | Description |
|
|
112
|
+
| ----------------------- | ----------------------------------------------------------------------------- |
|
|
113
|
+
| `list_console_messages` | List console messages with filtering by level (log, warn, error) |
|
|
114
|
+
| `get_console_message` | Get a detailed message including stack trace and arguments |
|
|
115
|
+
| `list_network_requests` | Monitor network requests — Fetch, XHR, and resource loads |
|
|
116
|
+
| `get_network_request` | Get full request/response details with headers and body |
|
|
117
|
+
| `evaluate_script` | Execute JavaScript in the browser context and return results |
|
|
118
|
+
| `take_screenshot` | Capture a PNG screenshot of the page or a specific element |
|
|
119
|
+
| `take_snapshot` | Accessibility-tree snapshot of the DOM with stable UIDs for element targeting |
|
|
167
120
|
|
|
168
121
|
### Navigation
|
|
169
122
|
|
|
170
|
-
| Tool | Description
|
|
171
|
-
| --------------- |
|
|
172
|
-
| `list_pages` | List open Safari tabs
|
|
173
|
-
| `select_page` | Switch to a specific tab
|
|
174
|
-
| `new_page` | Open a new tab
|
|
175
|
-
| `close_page` | Close a tab
|
|
176
|
-
| `navigate_page` | Navigate to URL, back, forward, or reload
|
|
177
|
-
| `wait_for` | Wait for text to appear on page
|
|
178
|
-
| `resize_page` | Resize the browser window
|
|
179
|
-
| `handle_dialog` | Accept or dismiss browser dialogs
|
|
180
|
-
|
|
181
|
-
### Input
|
|
182
|
-
|
|
183
|
-
| Tool | Description
|
|
184
|
-
| ------------- |
|
|
185
|
-
| `click` | Click
|
|
186
|
-
| `click_at` | Click at coordinates
|
|
187
|
-
| `hover` | Hover over
|
|
188
|
-
| `fill` | Type into
|
|
189
|
-
| `fill_form` | Fill multiple form fields at once
|
|
190
|
-
| `type_text` | Type text into focused
|
|
191
|
-
| `drag` | Drag and drop elements
|
|
192
|
-
| `press_key` | Press
|
|
193
|
-
| `upload_file` | Upload
|
|
123
|
+
| Tool | Description |
|
|
124
|
+
| --------------- | ---------------------------------------------------------- |
|
|
125
|
+
| `list_pages` | List all open Safari tabs across windows |
|
|
126
|
+
| `select_page` | Switch to a specific tab |
|
|
127
|
+
| `new_page` | Open a new tab and navigate to a URL |
|
|
128
|
+
| `close_page` | Close a tab |
|
|
129
|
+
| `navigate_page` | Navigate to a URL, go back, forward, or reload |
|
|
130
|
+
| `wait_for` | Wait for specific text to appear on the page |
|
|
131
|
+
| `resize_page` | Resize the browser window |
|
|
132
|
+
| `handle_dialog` | Accept or dismiss browser dialogs (alert, confirm, prompt) |
|
|
133
|
+
|
|
134
|
+
### Input automation
|
|
135
|
+
|
|
136
|
+
| Tool | Description |
|
|
137
|
+
| ------------- | ---------------------------------------------------- |
|
|
138
|
+
| `click` | Click an element by UID from a snapshot |
|
|
139
|
+
| `click_at` | Click at specific x/y coordinates |
|
|
140
|
+
| `hover` | Hover over an element |
|
|
141
|
+
| `fill` | Type into an input field or select from a dropdown |
|
|
142
|
+
| `fill_form` | Fill multiple form fields at once |
|
|
143
|
+
| `type_text` | Type text into the currently focused element |
|
|
144
|
+
| `drag` | Drag and drop between elements or coordinates |
|
|
145
|
+
| `press_key` | Press a key or combination (e.g., `Meta+A`, `Enter`) |
|
|
146
|
+
| `upload_file` | Upload a file through a file input |
|
|
194
147
|
|
|
195
148
|
## Architecture
|
|
196
149
|
|
|
@@ -212,56 +165,15 @@ Safari DevTools MCP Server
|
|
|
212
165
|
Safari Browser
|
|
213
166
|
```
|
|
214
167
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
Network request capture uses a 4-layer hybrid approach to minimize the pre-injection gap:
|
|
218
|
-
|
|
219
|
-
1. **Performance API backfill** — `performance.getEntriesByType('resource')` captures historical requests made before script injection (timing and size data, but no headers/status)
|
|
220
|
-
2. **Fetch interception** — Wraps `window.fetch()` for ongoing requests with full details
|
|
221
|
-
3. **XHR interception** — Wraps `XMLHttpRequest` for the same
|
|
222
|
-
4. **PerformanceObserver** — Catches resource loads that interceptors miss
|
|
223
|
-
|
|
224
|
-
Historical entries are flagged so the AI knows they have limited detail compared to intercepted requests.
|
|
225
|
-
|
|
226
|
-
### Tab Management
|
|
227
|
-
|
|
228
|
-
Uses AppleScript (`osascript`) for native macOS tab management — listing all Safari tabs across windows, switching tabs, opening/closing tabs. Falls back to WebDriver-only mode if AppleScript access is denied.
|
|
229
|
-
|
|
230
|
-
## Compatibility with chrome-devtools-mcp
|
|
231
|
-
|
|
232
|
-
Tool names and parameter schemas intentionally mirror chrome-devtools-mcp. The same `take_screenshot`, `evaluate_script`, `list_console_messages`, `click`, `fill`, etc. calls work across both servers, making it easy to switch between Chrome and Safari.
|
|
233
|
-
|
|
234
|
-
## Features NOT Available (vs Chrome DevTools MCP)
|
|
235
|
-
|
|
236
|
-
The following chrome-devtools-mcp features **cannot** be ported to Safari due to platform differences:
|
|
237
|
-
|
|
238
|
-
| Feature | Reason |
|
|
239
|
-
| ------------------------------- | ------------------------------------------------------ |
|
|
240
|
-
| **Lighthouse audits** | Chrome-specific tool, not available for Safari |
|
|
241
|
-
| **Memory heap snapshots** | Requires Chrome DevTools Protocol (CDP) |
|
|
242
|
-
| **Full performance traces** | Chrome's Tracing API is CDP-specific |
|
|
243
|
-
| **Chrome extension management** | Safari extensions use a completely different system |
|
|
244
|
-
| **Screencast/video recording** | Requires CDP screencast API |
|
|
245
|
-
| **Network throttling** | CDP-specific network emulation |
|
|
246
|
-
| **Geolocation emulation** | CDP-specific emulation |
|
|
247
|
-
| **Device emulation** | CDP-specific (Safari has no equivalent via WebDriver) |
|
|
248
|
-
| **Screenshot formats** | Safari WebDriver only supports PNG (no JPEG/WebP) |
|
|
249
|
-
| **Full-page screenshots** | Safari WebDriver does not support full-page capture |
|
|
250
|
-
| **initScript** | Requires CDP's `Page.addScriptToEvaluateOnNewDocument` |
|
|
251
|
-
| **Isolated browser contexts** | Safari WebDriver only supports a single session |
|
|
252
|
-
|
|
253
|
-
## Known Limitations
|
|
254
|
-
|
|
255
|
-
- **Single session**: Safari only allows one WebDriver session at a time
|
|
256
|
-
- **Network pre-injection gap**: Requests before script injection are captured via Performance API with limited detail (no headers, no status code)
|
|
257
|
-
- **Console pre-injection gap**: Console messages logged before script injection are not captured
|
|
258
|
-
- **AppleScript permissions**: Tab management requires macOS Accessibility permissions
|
|
259
|
-
- **No headless mode**: Safari does not support headless operation
|
|
260
|
-
- **macOS only**: Safari and SafariDriver are Apple-exclusive
|
|
261
|
-
|
|
262
|
-
## Contributing
|
|
168
|
+
## Known limitations
|
|
263
169
|
|
|
264
|
-
|
|
170
|
+
- **Single session**: Safari only allows one WebDriver session at a time. Running multiple instances is not supported.
|
|
171
|
+
- **macOS only**: Safari and SafariDriver are Apple-exclusive — this server does not work on Linux or Windows.
|
|
172
|
+
- **No headless mode**: Safari does not support headless operation. A visible browser window is required.
|
|
173
|
+
- **Console pre-injection gap**: Console messages logged before the capture script is injected are not captured.
|
|
174
|
+
- **Network pre-injection gap**: Network requests made before injection are backfilled via the Performance API with limited detail (timing and size, but no headers or status codes).
|
|
175
|
+
- **PNG only**: Safari WebDriver only supports PNG screenshots — no JPEG or WebP. Full-page capture is not available.
|
|
176
|
+
- **AppleScript permissions**: Tab management features require macOS Accessibility permissions for `osascript`.
|
|
265
177
|
|
|
266
178
|
## License
|
|
267
179
|
|