chrometools-mcp 2.3.2 → 2.4.2

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.4.2] - 2026-01-05
+
+### Added
+- **`analyzePage` - `includeAll` parameter** - New optional parameter to get ALL page elements, not just interactive ones
+  - Set `includeAll: true` to get complete page structure with selectors for all visible elements
+  - Returns new `allElements` array containing divs, spans, headings, and all other visible elements
+  - Each element includes: selector, tag, text, classes, id, and attributes (role, aria-label)
+  - Useful for layout work and styling - find any element, get its selector, then use `getComputedCss` or `setStyles`
+  - Example workflow: `analyzePage({ includeAll: true })` → find element → `getComputedCss({ selector })` or `setStyles({ selector })`
+  - Skips hidden elements and non-visual tags (SCRIPT, STYLE, META, etc.)
+  - Location: `index.js:1613-1751`, schemas in `tools/tool-schemas.js:215`, `server/tool-schemas.js:221`
+
+### Changed
+- **Tool Groups reorganization** - Moved `executeScript` and `navigateTo` from `advanced` to `core` group
+  - These are fundamental navigation and scripting tools that should be available in basic configurations
+  - Core group now includes: `ping`, `openBrowser`, `executeScript`, `navigateTo` (4 tools)
+  - Advanced group now has: `setStyles`, `setViewport`, `getViewport`, `smartFindElement`, `analyzePage`, `getAllInteractiveElements`, `findElementsByText` (7 tools)
+  - Location: `server/tool-groups.js:8,21-29`
+
+## [2.4.0] - 2025-12-29
+
+### Added
+- **Tool Filtering by Groups** - New `ENABLED_TOOLS` environment variable for selective group enabling
+  - Configure via `env.ENABLED_TOOLS` in MCP client config (comma-separated list of group names)
+  - Available groups: `core`, `interaction`, `inspection`, `debug`, `advanced`, `recorder`, `figma`
+  - Group structure optimized:
+    - `debug` - NEW group for debugging tools (console logs, network monitoring)
+    - `advanced` - Combined with AI tools (now includes smartFindElement, analyzePage, etc.)
+  - If not set, all tools are enabled (default behavior)
+  - If set, only tools from specified groups are available to AI
+  - Primary benefit: **Token optimization** - all 43 tools consume ~28k tokens (~14% of context). Enable only needed groups to reduce token usage and costs
+  - Additional use cases: security/compliance restrictions, workflow simplification, improved AI focus
+  - Examples:
+    - Basic automation: `ENABLED_TOOLS=core,interaction,inspection`
+    - Advanced with AI: `ENABLED_TOOLS=core,interaction,advanced`
+    - With debugging: `ENABLED_TOOLS=core,interaction,inspection,debug`
+    - Figma validation: `ENABLED_TOOLS=core,figma`
+  - Location:
+    - `server/tool-groups.js` - group definitions (7 groups, 43 tools total)
+    - `index.js:36` - import groups module
+    - `index.js:77-92` - parsing and filtering logic
+    - `index.js:195-203` - apply filter to ListTools handler
+  - Documentation: README.md section "Tool Filtering with ENABLED_TOOLS"
+
 ## [2.3.2] - 2025-12-25
 
 ### Changed

package/README.md

@@ -148,18 +148,27 @@ Get current page state and structure. Returns complete map of forms (with values
   - **After form submissions** (check results, errors)
   - **After AJAX updates** (dynamic content loaded)
   - When debugging (see actual form values, not just visual)
+  - **Layout/styling work** - use `includeAll: true` to get ALL page elements with selectors
 - **Parameters**:
   - `refresh` (optional): Force refresh cache to get CURRENT state after changes (default: false)
+  - `includeAll` (optional): Include ALL page elements, not just interactive ones (default: false). Useful for layout work - find any element, get its selector, then use `getComputedCss` or `setStyles` on it.
 - **Why better than screenshot**:
   - Shows actual data (form values, validation errors) not just visual
   - Uses 2-5k tokens vs screenshot 15-25k tokens
   - Returns structured data with selectors
-- **Returns**: Complete map of forms (with current values), inputs, buttons, links, navigation with selectors
+- **Returns**:
+  - By default: Complete map of forms (with current values), inputs, buttons, links, navigation with selectors
+  - With `includeAll: true`: Also includes `allElements` array with ALL visible page elements (divs, spans, headings, etc.) - each with selector, tag, text, classes, id
 - **Example workflow**:
   1. `openBrowser({ url: "..." })`
   2. `analyzePage()` ← Initial analysis
   3. `click({ selector: "submit-btn" })`
   4. **`analyzePage({ refresh: true })`** ← See what changed after click!
+- **Layout work example**:
+  1. `analyzePage({ includeAll: true })` ← Get all elements
+  2. Find element you want to style (e.g., `div.header`)
+  3. `getComputedCss({ selector: "div.header" })` ← Get current styles
+  4. `setStyles({ selector: "div.header", styles: [...] })` ← Apply new styles
 
 #### getAllInteractiveElements
 Get all clickable/fillable elements with their selectors.
@@ -965,6 +974,106 @@ If you don't need to see the browser window, you can use xvfb (virtual X server)
 
 This runs Chrome in GUI mode but on a virtual display (window is not visible).
 
+### Tool Filtering with ENABLED_TOOLS
+
+By default, all tools are enabled. You can selectively enable only specific tool groups using the `ENABLED_TOOLS` environment variable.
+
+**Why filter tools?**
+
+Each tool definition is sent to the AI in every request, consuming context tokens. All 43 tools consume ~28k tokens (~14% of context window). By enabling only the groups you need, you can significantly reduce token usage:
+
+- **Save tokens:** Fewer tools = less context consumed per request
+- **Reduce costs:** Lower token usage means lower API costs
+- **Improve focus:** AI sees only relevant tools for your workflow
+- **Security/compliance:** Restrict available capabilities when needed
+
+**Available Tool Groups:**
+
+| Group | Description | Tools (count) |
+|-------|-------------|---------------|
+| `core` | Basic tools | `ping`, `openBrowser` (2) |
+| `interaction` | User interaction | `click`, `type`, `scrollTo`, `waitForElement`, `hover` (5) |
+| `inspection` | Page inspection | `getElement`, `getComputedCss`, `getBoxModel`, `screenshot`, `saveScreenshot` (5) |
+| `debug` | Debugging & network | `getConsoleLogs`, `listNetworkRequests`, `getNetworkRequest`, `filterNetworkRequests` (4) |
+| `advanced` | Advanced automation & AI | `executeScript`, `setStyles`, `setViewport`, `getViewport`, `navigateTo`, `smartFindElement`, `analyzePage`, `getAllInteractiveElements`, `findElementsByText` (9) |
+| `recorder` | Scenario recording | `enableRecorder`, `executeScenario`, `listScenarios`, `searchScenarios`, `getScenarioInfo`, `deleteScenario`, `exportScenarioAsCode`, `appendScenarioToFile`, `generatePageObject` (9) |
+| `figma` | Figma integration | `getFigmaFrame`, `compareFigmaToElement`, `getFigmaSpecs`, `parseFigmaUrl`, `listFigmaPages`, `searchFigmaFrames`, `getFigmaComponents`, `getFigmaStyles`, `getFigmaColorPalette` (9) |
+
+**Total:** 43 tools across 7 groups
+
+**Configuration:**
+
+**Claude Desktop** (`~/.claude/mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"],
+      "env": {
+        "ENABLED_TOOLS": "core,interaction,inspection"
+      }
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"],
+      "env": {
+        "ENABLED_TOOLS": "core,interaction,advanced"
+      }
+    }
+  }
+}
+```
+
+**Format:**
+- Comma-separated list of group names (e.g., `"core,interaction,advanced"`)
+- Spaces are automatically trimmed
+- If not set or empty, all tools are enabled (default behavior)
+
+**Example configurations:**
+
+**Basic automation only:**
+```json
+"ENABLED_TOOLS": "core,interaction,inspection"
+```
+
+**Advanced automation with AI:**
+```json
+"ENABLED_TOOLS": "core,interaction,advanced"
+```
+
+**With debugging tools:**
+```json
+"ENABLED_TOOLS": "core,interaction,inspection,debug"
+```
+
+**Figma design validation:**
+```json
+"ENABLED_TOOLS": "core,figma"
+```
+
+**Full automation with recording:**
+```json
+"ENABLED_TOOLS": "core,interaction,inspection,debug,advanced,recorder"
+```
+
+**All tools (default):**
+```json
+"env": {}
+```
+or omit the `env` field entirely.
+
 ### Figma API Token Setup
 
 To use Figma tools, you need to configure your Figma Personal Access Token.