chrometools-mcp 2.3.2 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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

@@ -965,6 +965,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.

package/index.js

@@ -33,6 +33,7 @@ import {filterCssStyles} from './utils/css-utils.js';
 // Import tool schemas and definitions
 import * as schemas from './server/tool-schemas.js';
 import {toolDefinitions} from './server/tool-definitions.js';
+import {getToolsFromGroups, getAllGroupNames} from './server/tool-groups.js';
 
 // Import element actions helper
 import {executeElementAction} from './utils/element-actions.js';
@@ -73,6 +74,16 @@ const debugLog = DEBUG_MODE ? console.error : () => {};
 // Figma token from environment variable (can be set in MCP config)
 const FIGMA_TOKEN = process.env.FIGMA_TOKEN || null;
 
+// Tool filtering - read ENABLED_TOOLS environment variable
+// If set, only enable specified tool groups (comma-separated list)
+// If not set, enable all tools (default behavior)
+const ENABLED_TOOLS = process.env.ENABLED_TOOLS;
+let enabledToolsSet = null;
+
+if (ENABLED_TOOLS) {
+  const groupNames = ENABLED_TOOLS.split(',').map(g => g.trim()).filter(g => g.length > 0);
+  enabledToolsSet = getToolsFromGroups(groupNames);
+}
 // Get current directory for loading utils
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -164,7 +175,7 @@ try {
 const server = new Server(
   {
     name: "chrometools-mcp",
-    version: "2.1.0",
+    version: "2.4.0",
   },
   {
     capabilities: {
@@ -175,8 +186,13 @@ const server = new Server(
 
 // List available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
+  // Filter tools based on ENABLED_TOOLS environment variable
+  const tools = enabledToolsSet
+    ? toolDefinitions.filter(tool => enabledToolsSet.has(tool.name))
+    : toolDefinitions;
+
   return {
-    tools: toolDefinitions,
+    tools,
   };
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "MCP (Model Context Protocol) server for Chrome automation using Puppeteer. Persistent browser sessions, visual testing, Figma comparison, and design validation. Works seamlessly in WSL, Linux, and macOS.",
   "type": "module",
   "main": "index.js",

package/server/tool-groups.js

@@ -0,0 +1,82 @@
+/**
+ * server/tool-groups.js
+ *
+ * Tool group definitions for filtering
+ */
+
+export const toolGroups = {
+  core: ['ping', 'openBrowser'],
+
+  interaction: ['click', 'type', 'scrollTo', 'waitForElement', 'hover'],
+
+  inspection: ['getElement', 'getComputedCss', 'getBoxModel', 'screenshot', 'saveScreenshot'],
+
+  debug: [
+    'getConsoleLogs',
+    'listNetworkRequests',
+    'getNetworkRequest',
+    'filterNetworkRequests'
+  ],
+
+  advanced: [
+    'executeScript',
+    'setStyles',
+    'setViewport',
+    'getViewport',
+    'navigateTo',
+    'smartFindElement',
+    'analyzePage',
+    'getAllInteractiveElements',
+    'findElementsByText'
+  ],
+
+  recorder: [
+    'enableRecorder',
+    'executeScenario',
+    'listScenarios',
+    'searchScenarios',
+    'getScenarioInfo',
+    'deleteScenario',
+    'exportScenarioAsCode',
+    'appendScenarioToFile',
+    'generatePageObject'
+  ],
+
+  figma: [
+    'getFigmaFrame',
+    'compareFigmaToElement',
+    'getFigmaSpecs',
+    'parseFigmaUrl',
+    'listFigmaPages',
+    'searchFigmaFrames',
+    'getFigmaComponents',
+    'getFigmaStyles',
+    'getFigmaColorPalette'
+  ]
+};
+
+/**
+ * Get all tool names from specified groups
+ * @param {string[]} groupNames - Array of group names (e.g., ['core', 'interaction'])
+ * @returns {Set<string>} - Set of tool names
+ */
+export function getToolsFromGroups(groupNames) {
+  const tools = new Set();
+
+  for (const groupName of groupNames) {
+    const group = toolGroups[groupName];
+    if (group) {
+      group.forEach(tool => tools.add(tool));
+    }
+  }
+
+  return tools;
+}
+
+/**
+ * Get all available group names
+ * @returns {string[]} - Array of group names
+ */
+export function getAllGroupNames() {
+  return Object.keys(toolGroups);
+}