aether-mcp-server 2.0.0 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +141 -0
- package/package.json +3 -2
package/README.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# Aether — AI Browser Controller
|
|
2
|
+
|
|
3
|
+
Aether is an MCP (Model Context Protocol) server that lets AI coding agents inspect and control a real browser through the Chrome DevTools Protocol (CDP). No browser extension needed.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx aether-mcp-server
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Or globally:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install -g aether-mcp-server
|
|
15
|
+
aether-mcp-server
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## MCP Client Config
|
|
19
|
+
|
|
20
|
+
Add this to your MCP client (Cursor, Claude Code, Codex, KiloCode, etc.):
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"mcpServers": {
|
|
25
|
+
"aether-browser": {
|
|
26
|
+
"command": "npx",
|
|
27
|
+
"args": ["-y", "aether-mcp-server"]
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
If installed globally:
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"mcpServers": {
|
|
38
|
+
"aether-browser": {
|
|
39
|
+
"command": "aether-mcp-server",
|
|
40
|
+
"args": []
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
That's it. No cloning. No building. No absolute paths.
|
|
47
|
+
|
|
48
|
+
## What It Does
|
|
49
|
+
|
|
50
|
+
- Launches or connects to Chrome, Edge, Brave, or Firefox with remote debugging
|
|
51
|
+
- Exposes MCP tools for navigation, clicking, typing, form filling, screenshots, tabs, logs, cookies, network controls, PDF printing, and page inspection
|
|
52
|
+
- Uses native CDP input events instead of fragile DOM-only hacks
|
|
53
|
+
- Provides Set-of-Marks style visual element references for screenshot-based workflows
|
|
54
|
+
- Resolves elements by selector, text, role, accessible name, label, placeholder, XPath, coordinates, same-origin iframe content, and shadow DOM content
|
|
55
|
+
- Caches compact page snapshots and invalidates them on DOM/navigation/runtime events
|
|
56
|
+
|
|
57
|
+
## Browser Setup
|
|
58
|
+
|
|
59
|
+
Launch a clean browser automatically:
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
launch_browser()
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Pick a specific browser:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
launch_browser(browser="chrome")
|
|
69
|
+
launch_browser(browser="edge")
|
|
70
|
+
launch_browser(browser="brave")
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Connect to an existing browser with remote debugging:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
chrome --remote-debugging-port=9222
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Then:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
connect_browser(mode="connect", port=9222)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Key Tools
|
|
86
|
+
|
|
87
|
+
- `browser_status` — connection and active tab status
|
|
88
|
+
- `snapshot_compact` — title, URL, readyState, and interactive element list
|
|
89
|
+
- `list_interactive_elements` — element refs for click/fill flows
|
|
90
|
+
- `click_by_ref` — click refs returned by compact snapshots
|
|
91
|
+
- `click_text`, `click_role`, `fill_label` — semantic actions powered by the locator engine
|
|
92
|
+
- `get_state` — optional screenshot, tabs, DOM snapshot, and elements
|
|
93
|
+
- `get_logs`, `get_network_errors` — compact debugging output
|
|
94
|
+
- `act` — broad compatibility action tool
|
|
95
|
+
|
|
96
|
+
## Project-Local Learning
|
|
97
|
+
|
|
98
|
+
Aether stores learned lessons and skills in `.aether/` inside your project:
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
<project>/.aether/
|
|
102
|
+
memory/
|
|
103
|
+
lessons.jsonl
|
|
104
|
+
learned.json
|
|
105
|
+
skills/
|
|
106
|
+
<skill-name>/SKILL.md
|
|
107
|
+
_registry.json
|
|
108
|
+
memory-config.json
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Call `configure_aether_memory` with your project root to enable it. Aether creates `.aether/` and adds it to `.gitignore`.
|
|
112
|
+
|
|
113
|
+
## Environment Variables
|
|
114
|
+
|
|
115
|
+
| Variable | Purpose |
|
|
116
|
+
|---|---|
|
|
117
|
+
| `AETHER_MODE` | `"cdp"` (default) or `"extension"` |
|
|
118
|
+
| `AETHER_PROJECT_ROOT` | Fallback project root for aether memory |
|
|
119
|
+
|
|
120
|
+
## Requirements
|
|
121
|
+
|
|
122
|
+
- Node.js >= 18
|
|
123
|
+
- Chrome, Edge, Brave, or Firefox installed locally
|
|
124
|
+
|
|
125
|
+
## Architecture
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
AI Agent / MCP Client
|
|
129
|
+
|
|
|
130
|
+
| stdio JSON-RPC
|
|
131
|
+
v
|
|
132
|
+
Aether MCP Server
|
|
133
|
+
|
|
|
134
|
+
| Chrome DevTools Protocol
|
|
135
|
+
v
|
|
136
|
+
Browser Target
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## License
|
|
140
|
+
|
|
141
|
+
ISC
|
package/package.json
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "aether-mcp-server",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.1",
|
|
4
4
|
"description": "Aether MCP Server - AI Browser Controller",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"bin": {
|
|
7
7
|
"aether-mcp-server": "dist/index.js"
|
|
8
8
|
},
|
|
9
9
|
"files": [
|
|
10
|
-
"dist/"
|
|
10
|
+
"dist/",
|
|
11
|
+
"README.md"
|
|
11
12
|
],
|
|
12
13
|
"scripts": {
|
|
13
14
|
"build": "tsc",
|