Skip to content

Commit 38123bb

Browse files
b10902118b10902118
committed
doc: README and tools
1 parent 2f5bb96 commit 38123bb

File tree

2 files changed

+168
-40
lines changed

2 files changed

+168
-40
lines changed

‎README.md‎

Lines changed: 36 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,55 @@
1-
## Inspector MCP
1+
# Chrome Inspector MCP
22

3-
The DevTools MCP for inspecting DOM elements and CSS rules
3+
This gives agents DOM Elements, CSS Rules, and Computed Style, the tools that `chrome-devtools-mcp` doesn't provide.
44

5-
This gives agents DOM Elements, CSS Rules, and Computed Style, the bread and butter for frontend development.
5+
This redesign of DevTools MCP aims to enable agents to take over DevTools for complex debugging. Any suggestions are welcomed. Current directions includes:
66

7-
Most Chrome DevTools Protocol (CDP) logics are in [chrome-inspector](https://github.com/devtoolcss/chrome-inspector), a programming interface wrapping CDP to DOM methods. This MCP aims to explore the optimal interface for LLMs to control DevTools for complex debugging.
7+
- Agent Ergonomics: Building directly on [Chrome DevTools Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/), designing for agent needs, not library constraints
8+
- Extensibility: Making it easy for users (and agents?) to hack and customize their own toolsets
89

9-
### Tools
10+
## Demo
1011

11-
5 tools
12+
## Installation
1213

13-
- `getTabs`
14-
- `getNodes`
15-
- document, $0, or uid as variable (.getElementById)
16-
- querySelector, parent, children[0], etc
17-
- return uids
18-
- `getMatchedStyles` (optionally filter by selector, properties, appliedOnly)
19-
- `getComputedStyle` (must specify wanted attr array)
20-
- `getOuterHTML` (with depth/line lenght control)
14+
1. Install the extension from [Releases](https://github.com/devtoolcss/chrome-inspector-mcp/releases)
2115

22-
**TODO**
16+
2. Add the following config to your MCP client:
2317

24-
- auto detach, better config panel
18+
```json
19+
{
20+
"mcpServers": {
21+
"chrome-devtools": {
22+
"command": "npx",
23+
"args": ["-y", "chrome-inspector-mcp@latest"]
24+
}
25+
}
26+
}
27+
```
2528

26-
---
29+
## Tools
2730

28-
- console js & message
29-
- device emulation
30-
31-
### Guidelines:
32-
33-
1. Generalization (best to allow programmatic expression. best to only explain rules instead of full functionality.)
34-
2. Filtering (If raw output can be too large, we should have predefined filtering logic. This way, the tool's value is like a lib function that doesn't require LLM implement everytime)
35-
3. Minimal (Less is more. Less unneeded description, better response and longer use.)
31+
- [`getTabs`](./tools.md#gettabs)
32+
- [`selectTab`](./tools.md#selecttabs)
33+
- [`getNodes`](./tools.md#getnodes)
34+
- [`getMatchedStyles`](./tools.md#getmatchedstyles)
35+
- [`getComputedStyle`](./tools.md#getcomputedstyle)
36+
- [`getOuterHTML`](./tools.md#getouterhtml)
3637

37-
## Archtecture
38+
### TODO
3839

39-
chrome extension (ws polling) + stateful inspectors + lazy init
40-
41-
### Connection
40+
- console js & message
41+
- device emulation
4242

43-
comparison between Extension API vs Remote Debugging Port
43+
### Guidelines
4444

45-
used by:
46-
browser devtools access:
47-
avaliable sites: except chrome://
48-
profile:
49-
XXX is debugging your browser
45+
1. **Generalization**: Prefer taking programmatic expression. Let models code.
5046

51-
in theory, Remote Debugging Port gives the most power, but its setup is also more inconvenient
47+
2. **Filtering**: When raw output could be large, provide built-in filtering logic.
5248

53-
---
49+
## How it works
5450

55-
For Chrome Extensions, there are two ways to communicate with local process: ws+polling (extension as client) vs native messaging (server)
51+
When Chrome starts, the extension's background worker polls a specific port every few seconds. When the MCP server starts at the address they connect. By manifest v3, one background worker serves one profile, so the MCP server can access all its tabs (TODO: filtering).
5652

57-
Unlike [hangwin/mcp-chrome](https://github.com/hangwin/mcp-chrome), we opt for http polling + ws for easier maintaince. The polling usage should be marginal, you can also manually turn on/off.
53+
Currently, the extension handles all DevTools logic and the MCP server is just a relay. Yet Chrome extension has many restrictions, so I planed to forward `chrome` API and keep things in MCP's Nodejs runtime following [playwright-mcp's design](https://github.com/microsoft/playwright-mcp/tree/main/extension).
5854

59-
one profile is not intended for multiple persons to use simultaneously, so following chrome-extension design, one mcp per profile is good. for multi agent use, each agent can config its extension and mcp port.
55+
The inspection logic is implemented in [chrome-inspector](https://github.com/devtoolcss/chrome-inspector), a programming interface wrapping [CDP](https://chromedevtools.github.io/devtools-protocol/) to DOM methods.

‎tools.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
## `getTabs`
2+
3+
**Parameters:**
4+
5+
None
6+
7+
**Sample result:**
8+
9+
```json
10+
{
11+
"tabs": [
12+
{
13+
"id": 123,
14+
"title": "Example Page",
15+
"url": "https://example.com",
16+
"active": true,
17+
"lastAccessed": "5min ago"
18+
}
19+
]
20+
}
21+
```
22+
23+
---
24+
25+
## `selectTab`
26+
27+
**Parameters:**
28+
29+
- **tabId** (number) **(required)**: Id of the tab to target for future operations
30+
31+
**Sample result:**
32+
33+
```json
34+
{
35+
"selectedTabId": 123
36+
}
37+
```
38+
39+
---
40+
41+
## `getNodes`
42+
43+
**Parameters:**
44+
45+
- **expression** (string) **(required)**: DOM expression to evaluate, starting with a node, with `document` and `$0` available. Examples: `document.querySelectorAll('div')`, `div_1.children[0]`
46+
47+
**Sample result:**
48+
49+
```json
50+
{
51+
"nodes": ["div_0", "div_1"]
52+
}
53+
```
54+
55+
---
56+
57+
## `getMatchedStyles`
58+
59+
**Parameters:**
60+
61+
- **node** (string) **(required)**: Node identifier
62+
- **selectors** (array of strings) _(optional)_: Filter regex patterns for CSS selectors
63+
- **properties** (array of strings) _(optional)_: Filter patterns for CSS properties
64+
- **appliedOnly** (boolean) _(optional)_: Return only applied styles (default: false)
65+
- **removeUnusedVar** (boolean) _(optional)_: Remove unused CSS variables (default: true)
66+
67+
**Sample result:**
68+
69+
```css
70+
/* Matched: ::after */
71+
*,
72+
::before,
73+
::after {
74+
box-sizing: border-box; /* applied */
75+
}
76+
77+
body {
78+
display: block; /* applied */
79+
margin: 8px;
80+
}
81+
82+
/* Inherited from html */
83+
/* Matched: html */
84+
html,
85+
:host {
86+
line-height: 1.5;
87+
}
88+
```
89+
90+
---
91+
92+
## `getComputedStyle`
93+
94+
**Parameters:**
95+
96+
- **node** (string) **(required)**: Node identifier
97+
- **properties** (array of strings) **(required)**: CSS properties to retrieve
98+
99+
**Sample result:**
100+
101+
```json
102+
{
103+
"display": "block",
104+
"width": "1920px"
105+
}
106+
```
107+
108+
---
109+
110+
## `getOuterHTML`
111+
112+
**Parameters:**
113+
114+
- **node** (string) **(required)**: Node identifier
115+
- **maxDepth** (number) _(optional)_: Maximum depth to traverse (default: 3)
116+
- **maxLineLength** (number) _(optional)_: Maximum line length (default: 200)
117+
118+
**Sample result:**
119+
120+
```html
121+
<body>
122+
<div id="root" class="w-full">
123+
<div class="flex h-screen bg-background">
124+
<div class="bg-card border-r"><!--... 90 more element(s), 15 text node(s), max depth +8--></div>
125+
<div class="flex-1 flex"><!--... 199 more element(s), 97 text node(s), max depth +12--></div>
126+
</div>
127+
<div role="region" aria-label="Notifications (F8)" tabindex="-1" style="pointer-events: none;">
128+
<ol tabindex="-1" class="fixed top-0 z-[100] flex max-h-screen w-full flex-col-reverse p-4 sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]"></ol>
129+
</div>
130+
</div>
131+
</body>
132+
```

0 commit comments

Comments
 (0)