chrometools-mcp 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,111 @@
 
 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
+- **appendScenarioToFile** - Simplified architecture: MCP server no longer reads test files
+  - Removed `FileAppender.validateFile()` and `FileAppender.readFile()` calls
+  - Removed `generator.appendTest()` call - no longer merges content server-side
+  - Returns only test code (without imports) via `testCode` field
+  - Changed `action: "write_file"` → `action: "append_test"` (more accurate description)
+  - Claude Code now responsible for reading file, appending test, and writing back
+  - Clearer separation of concerns: MCP generates code, Claude Code handles file I/O
+  - Location: `index.js:2126-2215`
+
+## [2.3.1] - 2024-12-25
+
+### Fixed
+- **executeScenario** - Fixed scenario execution when current page URL doesn't match scenario's entryUrl
+  - Added automatic navigation to entryUrl before executing scenario
+  - Normalizes URLs for comparison (ignores trailing slashes, query params like `nr`, `redirect_ts`)
+  - Prevents timeout errors when scenario expects different page than currently open
+  - Example: If scenario recorded on `ya.ru` but current page is `ya.ru/search/`, automatically navigates to `ya.ru`
+  - Logs navigation events to console for debugging
+  - Location: `index.js:1951-1987`
+
+- **appendScenarioToFile** - Unified response format with exportScenarioAsCode for better Claude Code compatibility
+  - Changed `action: "append_to_file"` → `action: "write_file"` (clearer action)
+  - Changed `updatedContent` → `testCode` (same field name as exportScenarioAsCode)
+  - Added `content` field (duplicate of testCode for compatibility)
+  - Simplified instruction: single-step "Write the testCode..." instead of two-step "Read... then write..."
+  - Improved error message when file not found: now suggests using exportScenarioAsCode instead
+  - Location: `index.js:2191-2229`
+
+## [2.3.0] - 2024-12-25
+
+### Breaking Changes
+- **exportScenarioAsCode** - Removed append-to-file functionality to eliminate confusion
+  - **REMOVED** parameters: `appendToFile`, `testName`, `insertPosition`, `referenceTestName`
+  - Now exclusively creates NEW test files (returns JSON with `action: "create_new_file"`)
+  - Returns JSON format with `action`, `suggestedFileName`, `testCode`, `instruction` fields
+  - Claude Code writes files based on returned JSON (MCP server no longer writes files directly)
+  - Migration: Use new `appendScenarioToFile` tool instead of `appendToFile` parameter
+
+### Added
+- **appendScenarioToFile** - NEW tool for appending tests to existing files
+  - Parameters: `scenarioName`, `language`, `targetFile` (required)
+  - Optional: `testName`, `insertPosition`, `referenceTestName`, `cleanSelectors`, `includeComments`, `generatePageObject`, `pageObjectClassName`
+  - Returns JSON with `action: "append_to_file"`, `targetFile`, `updatedContent`, `instruction`
+  - Safely appends tests without overwriting existing tests
+  - Claude Code writes updated file content based on returned JSON
+  - Location: `index.js:2041-2186`, `server/tool-definitions.js:577-628`
+
+### Changed
+- **exportScenarioAsCode** - Changed return format from plain text to structured JSON
+  - Returns: `{action, suggestedFileName, testCode, instruction, pageObject?}`
+  - Suggests filename based on scenario name and language
+  - Includes clear instructions for Claude Code to create files
+  - Location: `index.js:2188-2357`, `server/tool-definitions.js:542-576`
+- **File writing responsibility** - Moved from MCP server to Claude Code
+  - MCP tools now return JSON with file content + instructions
+  - Claude Code uses Write tool to create/update files
+  - Eliminates risk of MCP server directly overwriting files
+
+### Documentation
+- **README.md** - Split exportScenarioAsCode documentation into two sections
+  - exportScenarioAsCode: For creating new test files
+  - appendScenarioToFile: For appending to existing files
+  - Updated tool count: 39+ → 40+ tools
+  - Added clear examples for both tools with JSON response formats
+  - Location: `README.md:11,17,652-806`
+
+## [2.2.1] - 2024-12-24
+
+### Improved
+- **exportScenarioAsCode** - Clarified tool description to prevent accidental test file overwrites
+  - Added explicit warning: default mode (without `appendToFile`) returns code for NEW file
+  - Emphasized that `appendToFile` parameter is **REQUIRED** to safely add tests to existing files
+  - Updated `appendToFile` parameter description to highlight safety aspect
+  - Updated `insertPosition` and `referenceTestName` descriptions to clarify they only work with `appendToFile`
+  - Added warning section in README.md documentation
+  - Location: `server/tool-definitions.js:544,575-589`, `README.md:667-669`
+
 ## [2.2.0] - 2025-12-21
 
 ### Added

package/README.md

@@ -8,13 +8,13 @@ MCP server for Chrome automation using Puppeteer with persistent browser session
 - [Usage](#usage)
 - [AI Optimization Features](#ai-optimization-features) ⭐ **NEW**
 - [Scenario Recorder](#scenario-recorder) ⭐ **NEW** - Visual UI-based recording with smart optimization
-- [Available Tools](#available-tools) - **39+ Tools Total**
+- [Available Tools](#available-tools) - **40+ Tools Total**
   - [AI-Powered Tools](#ai-powered-tools) ⭐ **NEW** - smartFindElement, analyzePage, getAllInteractiveElements, findElementsByText
   - [Core Tools](#1-core-tools) - ping, openBrowser
   - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo
   - [Inspection Tools](#3-inspection-tools) - getElement, getComputedCss, getBoxModel, screenshot
   - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
-  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, generatePageObject
+  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, appendScenarioToFile, generatePageObject
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
@@ -650,7 +650,7 @@ Delete a scenario and its associated secrets. Searches all projects to find the
 - **Returns**: Success confirmation
 
 #### exportScenarioAsCode ⭐ **NEW**
-Export recorded scenario as executable test code for various frameworks. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class for the page. Can append tests to existing files. Searches all projects to find the scenario.
+Export recorded scenario as executable test code for creating a **NEW** test file. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class. Returns JSON with code and suggested filename - Claude Code will create the file. To add tests to **EXISTING** files, use `appendScenarioToFile` instead.
 
 - **Parameters**:
   - `scenarioName` (required): Name of scenario to export
@@ -659,38 +659,34 @@ Export recorded scenario as executable test code for various frameworks. Automat
   - `includeComments` (optional): Include descriptive comments (default: true)
   - `generatePageObject` (optional): Also generate Page Object class for the page (default: false)
   - `pageObjectClassName` (optional): Custom Page Object class name (auto-generated if not provided)
-  - `appendToFile` (optional): Path to existing test file to append to (enables **append mode**) ⭐ **NEW**
-  - `testName` (optional): Override test name (default: from scenario name) ⭐ **NEW**
-  - `insertPosition` (optional): Where to insert: `'end'` (default), `'before'`, `'after'` ⭐ **NEW**
-  - `referenceTestName` (optional): Reference test name for before/after insertion ⭐ **NEW**
 
-- **Use case**: Convert recorded scenarios into maintainable test code with optional Page Objects, or append to existing test suites
+- **Use case**: Create new test files from recorded scenarios with optional Page Objects
 
-- **Returns**:
-  - **Without `appendToFile`**: Test code as string (or JSON with Page Object)
-  - **With `appendToFile`**: JSON with `{success, mode: "append", file, testName, message}`
+- **Returns**: JSON with:
+  - `action`: `"create_new_file"`
+  - `suggestedFileName`: Suggested test filename
+  - `testCode`: Full test code with imports
+  - `instruction`: Instructions for Claude Code
+  - `pageObject` (if `generatePageObject=true`): Page Object code and metadata
 
-- **Example 1 - Test only** (default behavior):
+- **Example 1 - Test only**:
   ```javascript
-  // Export scenario as Playwright TypeScript
+  // Export scenario as new Playwright TypeScript file
   exportScenarioAsCode({
     scenarioName: "checkout_flow",
-    language: "playwright-typescript",
-    cleanSelectors: true,
-    includeComments: true
+    language: "playwright-typescript"
   })
 
-  // Returns clean test code:
-  // import { test, expect } from '@playwright/test';
-  //
-  // test('checkout_flow', async ({ page }) => {
-  //   await page.goto('https://example.com');
-  //   await page.locator('button[data-testid="add-to-cart"]').click();
-  //   await expect(page).toHaveURL(/checkout/);
-  // });
+  // Returns JSON:
+  {
+    "action": "create_new_file",
+    "suggestedFileName": "checkout_flow.spec.ts",
+    "testCode": "import { test, expect } from '@playwright/test';\n\ntest('checkout_flow', async ({ page }) => {\n  await page.goto('https://example.com');\n  await page.locator('button[data-testid=\"add-to-cart\"]').click();\n  await expect(page).toHaveURL(/checkout/);\n});",
+    "instruction": "Create a new test file 'checkout_flow.spec.ts' with the testCode."
+  }
   ```
 
-- **Example 2 - Test + Page Object** ⭐ **NEW**:
+- **Example 2 - Test + Page Object**:
   ```javascript
   // Export with Page Object class
   exportScenarioAsCode({
@@ -702,63 +698,117 @@ Export recorded scenario as executable test code for various frameworks. Automat
 
   // Returns JSON with both files:
   {
-    "success": true,
+    "action": "create_new_file",
+    "suggestedFileName": "login_test.spec.ts",
     "testCode": "import { test } from '@playwright/test';\nimport { LoginPage } from './LoginPage';\n\ntest('login_test', async ({ page }) => {\n  const loginPage = new LoginPage(page);\n  await loginPage.goto();\n  await loginPage.fillEmailInput('user@test.com');\n  await loginPage.clickLoginButton();\n});",
-    "pageObjectCode": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage {\n  readonly page: Page;\n  readonly emailInput: Locator;\n  readonly loginButton: Locator;\n  \n  constructor(page: Page) {\n    this.page = page;\n    this.emailInput = page.locator('#email');\n    this.loginButton = page.locator('button[type=\"submit\"]');\n  }\n  \n  async goto() {\n    await this.page.goto('https://example.com/login');\n  }\n  \n  async fillEmailInput(text: string) {\n    await this.emailInput.fill(text);\n  }\n  \n  async clickLoginButton() {\n    await this.loginButton.click();\n  }\n}",
-    "pageObjectClassName": "LoginPage",
-    "framework": "playwright-typescript",
-    "elementCount": 12
+    "pageObject": {
+      "code": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage { ... }",
+      "className": "LoginPage",
+      "suggestedFileName": "LoginPage.ts",
+      "elementCount": 12
+    },
+    "instruction": "Create a new test file 'login_test.spec.ts' with the testCode. Also create a Page Object file 'LoginPage.ts' with the pageObject.code."
   }
   ```
 
-- **Example 3 - Append Mode** ⭐ **NEW**:
+- **Selector Cleaning**: Automatically removes unstable patterns:
+  - CSS Modules: `Button_primary__2x3yZ` → removed
+  - Styled-components: `sc-AbCdEf-0` → removed
+  - Emotion: `css-1a2b3c4d` → removed
+  - Hash suffixes: `component_a1b2c3d` → removed
+  - Prefers stable selectors: `data-testid`, `role`, `aria-label`, semantic attributes
+
+#### appendScenarioToFile ⭐ **NEW v2.3.0**
+Append recorded scenario as test code to an **EXISTING** test file. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class. Returns JSON with test code (without imports) - Claude Code will read the file, append the test, and write back. To create **NEW** test files, use `exportScenarioAsCode` instead.
+
+- **Parameters**:
+  - `scenarioName` (required): Name of scenario to export
+  - `language` (required): Target framework - `"playwright-typescript"`, `"playwright-python"`, `"selenium-python"`, `"selenium-java"`
+  - `targetFile` (required): Path to existing test file to append to
+  - `testName` (optional): Override test name (default: from scenario name)
+  - `insertPosition` (optional): Where to insert: `'end'` (default), `'before'`, `'after'`
+  - `referenceTestName` (optional): Reference test name for 'before'/'after' insertion
+  - `cleanSelectors` (optional): Remove unstable CSS classes (default: true)
+  - `includeComments` (optional): Include descriptive comments (default: true)
+  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false)
+  - `pageObjectClassName` (optional): Custom Page Object class name (auto-generated if not provided)
+
+- **Use case**: Add tests to existing test files without overwriting current tests
+
+- **Architecture**: MCP server generates only test code (without imports). Claude Code reads the target file, appends the test at the specified position, and writes the file back. This separation ensures MCP doesn't need file system access to test files.
+
+- **Returns**: JSON with:
+  - `action`: `"append_test"`
+  - `targetFile`: Path to file to update
+  - `testCode`: Test code only (without imports/headers)
+  - `testName`: Name of test to append
+  - `insertPosition`: Where to insert test
+  - `referenceTestName`: Reference test for 'before'/'after' positioning
+  - `instruction`: Instructions for Claude Code to read/append/write
+  - `pageObject` (if `generatePageObject=true`): Page Object code and metadata
+
+- **Example 1 - Append to end**:
   ```javascript
   // Append test to end of existing file
-  exportScenarioAsCode({
+  appendScenarioToFile({
     scenarioName: "new_feature_test",
     language: "playwright-typescript",
-    appendToFile: "./tests/features.spec.ts"
+    targetFile: "./tests/features.spec.ts"
   })
 
-  // Returns:
+  // Returns JSON:
   {
-    "success": true,
-    "mode": "append",
-    "file": "./tests/features.spec.ts",
+    "action": "append_test",
+    "targetFile": "./tests/features.spec.ts",
+    "testCode": "test('new_feature_test', async ({ page }) => {\n  // Test implementation\n  await page.click('#submit');\n  await expect(page.locator('.result')).toBeVisible();\n});",
     "testName": "new_feature_test",
     "insertPosition": "end",
-    "message": "Test 'new_feature_test' successfully appended to ./tests/features.spec.ts"
+    "referenceTestName": null,
+    "instruction": "Read file './tests/features.spec.ts', append the testCode at position 'end', then write the file back."
   }
   ```
 
-- **Example 4 - Append with Position Control** ⭐ **NEW**:
+- **Example 2 - Insert before specific test**:
   ```javascript
   // Insert test before specific test
-  exportScenarioAsCode({
+  appendScenarioToFile({
     scenarioName: "setup_test",
     language: "selenium-python",
-    appendToFile: "./tests/test_suite.py",
+    targetFile: "./tests/test_suite.py",
     insertPosition: "before",
-    referenceTestName: "main_test",
-    testName: "test_setup_data"  // Override name
+    referenceTestName: "test_main",
+    testName: "test_setup_data"
   })
+  ```
 
-  // Or insert after specific test
-  exportScenarioAsCode({
-    scenarioName: "cleanup",
-    language: "playwright-python",
-    appendToFile: "./tests/test_flow.py",
-    insertPosition: "after",
-    referenceTestName: "test_main_flow"
+- **Example 3 - Append with Page Object**:
+  ```javascript
+  // Append test and generate Page Object
+  appendScenarioToFile({
+    scenarioName: "login_test",
+    language: "playwright-typescript",
+    targetFile: "./tests/auth.spec.ts",
+    generatePageObject: true,
+    pageObjectClassName: "LoginPage"
   })
-  ```
 
-- **Selector Cleaning**: Automatically removes unstable patterns:
-  - CSS Modules: `Button_primary__2x3yZ` → removed
-  - Styled-components: `sc-AbCdEf-0` → removed
-  - Emotion: `css-1a2b3c4d` → removed
-  - Hash suffixes: `component_a1b2c3d` → removed
-  - Prefers stable selectors: `data-testid`, `role`, `aria-label`, semantic attributes
+  // Returns JSON with both test code and Page Object:
+  {
+    "action": "append_test",
+    "targetFile": "./tests/auth.spec.ts",
+    "testCode": "test('login_test', async ({ page }) => {\n  await page.fill('#username', 'user');\n  await page.fill('#password', 'pass');\n  await page.click('button[type=\"submit\"]');\n});",
+    "testName": "login_test",
+    "insertPosition": "end",
+    "referenceTestName": null,
+    "pageObject": {
+      "code": "export class LoginPage { ... }",
+      "className": "LoginPage",
+      "suggestedFileName": "LoginPage.ts",
+      "elementCount": 8
+    },
+    "instruction": "Read file './tests/auth.spec.ts', append the testCode at position 'end', then write the file back. Also create a Page Object file 'LoginPage.ts' with the provided pageObject.code."
+  }
+  ```
 
 #### generatePageObject ⭐ **NEW**
 Generate Page Object Model (POM) class from current page structure. Analyzes page, extracts interactive elements, and generates framework-specific code with smart naming and helper methods.
@@ -915,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,
   };
 });
 
@@ -1948,6 +1964,44 @@ async function executeToolInternal(name, args) {
         }
       }
 
+      // Check if current page URL matches scenario's entryUrl
+      // If not, navigate to entryUrl before executing scenario
+      const entryUrl = scenario.metadata?.entryUrl;
+      if (entryUrl) {
+        try {
+          const currentUrl = page.url();
+
+          // Normalize URLs for comparison (remove trailing slashes, hash, some query params)
+          const normalizeUrl = (url) => {
+            try {
+              const urlObj = new URL(url);
+              // Keep protocol, hostname, pathname - ignore some query params like nr, redirect_ts
+              return `${urlObj.protocol}//${urlObj.hostname}${urlObj.pathname}`.replace(/\/$/, '');
+            } catch (e) {
+              return url;
+            }
+          };
+
+          const normalizedCurrent = normalizeUrl(currentUrl);
+          const normalizedEntry = normalizeUrl(entryUrl);
+
+          if (normalizedCurrent !== normalizedEntry) {
+            console.error(`[executeScenario] Current URL (${currentUrl}) doesn't match scenario entryUrl (${entryUrl})`);
+            console.error(`[executeScenario] Navigating to entryUrl...`);
+
+            await page.goto(entryUrl, {
+              waitUntil: 'networkidle2',
+              timeout: 30000
+            });
+
+            console.error(`[executeScenario] Navigation completed`);
+          }
+        } catch (navError) {
+          console.error(`[executeScenario] Warning: Failed to navigate to entryUrl: ${navError.message}`);
+          // Continue anyway - scenario might still work
+        }
+      }
+
       const options = {};
 
       // Pass executeDependencies option if provided
@@ -2038,7 +2092,7 @@ async function executeToolInternal(name, args) {
       };
     }
 
-    if (name === "exportScenarioAsCode") {
+    if (name === "appendScenarioToFile") {
       const scenario = await loadScenario(args.scenarioName, false, null);
 
       if (!scenario) {
@@ -2085,83 +2139,157 @@ async function executeToolInternal(name, args) {
           };
       }
 
-      // Check if append mode is requested
-      if (args.appendToFile) {
-        try {
-          // Validate file path and extension
-          FileAppender.validateFile(args.appendToFile, args.language);
-
-          // Read existing file content
-          const existingContent = FileAppender.readFile(args.appendToFile);
+      try {
+        // Generate test code only (without imports)
+        const testOnly = generator.generateTestOnly(scenario, {
+          ...options,
+          testName: args.testName
+        });
 
-          // Check if file is empty - if so, generate full test with imports
-          if (FileAppender.isEmpty(existingContent)) {
-            const fullCode = generator.generate(scenario, options);
-            FileAppender.writeFile(args.appendToFile, fullCode);
+        // Prepare append options for Claude Code
+        const appendOptions = {
+          insertPosition: args.insertPosition || 'end',
+          referenceTestName: args.referenceTestName
+        };
 
-            return {
-              content: [{
-                type: 'text',
-                text: JSON.stringify({
-                  success: true,
-                  mode: 'append',
-                  file: args.appendToFile,
-                  testName: args.testName || scenario.metadata?.name,
-                  message: `Test written to empty file: ${args.appendToFile}`
-                }, null, 2)
-              }]
-            };
+        // Generate Page Object if requested
+        let pageObjectData = null;
+        if (args.generatePageObject) {
+          try {
+            const entryUrl = scenario.metadata?.entryUrl;
+            if (entryUrl) {
+              let page;
+              try {
+                page = await getLastOpenPage();
+                const currentUrl = page.url();
+                if (currentUrl !== entryUrl) {
+                  await page.goto(entryUrl, { waitUntil: 'networkidle2' });
+                }
+              } catch (error) {
+                page = await getOrCreatePage(entryUrl);
+              }
+
+              const pageObjectOptions = {
+                className: args.pageObjectClassName || null,
+                framework: args.language,
+                includeComments: args.includeComments !== false,
+                groupElements: true
+              };
+
+              const pageObjectResult = await generatePageObject(page, pageObjectOptions);
+              if (pageObjectResult.success) {
+                // Suggest filename based on className
+                const extension = args.language.includes('typescript') ? '.ts' :
+                                 args.language.includes('java') ? '.java' : '.py';
+                pageObjectData = {
+                  code: pageObjectResult.code,
+                  className: pageObjectResult.className,
+                  suggestedFileName: `${pageObjectResult.className}${extension}`,
+                  elementCount: pageObjectResult.elementCount
+                };
+              }
+            }
+          } catch (error) {
+            // Page Object generation failed, continue without it
           }
+        }
 
-          // Generate only test function (without imports)
-          const testOnly = generator.generateTestOnly(scenario, {
-            ...options,
-            testName: args.testName
-          });
+        // Return JSON with instructions for Claude Code to append the test
+        const result = {
+          action: 'append_test',
+          targetFile: args.targetFile,
+          testCode: testOnly,  // Only test code, no imports
+          testName: args.testName || scenario.metadata?.name,
+          insertPosition: appendOptions.insertPosition,
+          referenceTestName: appendOptions.referenceTestName,
+          instruction: `Read file '${args.targetFile}', append the testCode at position '${appendOptions.insertPosition}', then write the file back.`
+        };
 
-          // Append test to existing content
-          const appendOptions = {
-            insertPosition: args.insertPosition || 'end',
-            referenceTestName: args.referenceTestName
-          };
+        if (pageObjectData) {
+          result.pageObject = pageObjectData;
+          result.instruction += ` Also create a Page Object file '${pageObjectData.suggestedFileName}' with the provided pageObject.code.`;
+        }
 
-          const updatedContent = generator.appendTest(existingContent, testOnly, appendOptions);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+          }]
+        };
+      } catch (error) {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              error: error.message,
+              action: 'append_test',
+              targetFile: args.targetFile
+            }, null, 2)
+          }],
+          isError: true
+        };
+      }
+    }
 
-          // Write updated content to file
-          FileAppender.writeFile(args.appendToFile, updatedContent);
+    if (name === "exportScenarioAsCode") {
+      const scenario = await loadScenario(args.scenarioName, false, null);
 
+      if (!scenario) {
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              error: `Scenario "${args.scenarioName}" not found`
+            }, null, 2)
+          }],
+          isError: true
+        };
+      }
+
+      // Select generator based on language
+      let generator;
+      const options = {
+        cleanSelectors: args.cleanSelectors !== false, // default true
+        includeComments: args.includeComments !== false, // default true
+      };
+
+      switch (args.language) {
+        case 'playwright-typescript':
+          generator = new PlaywrightTypeScriptGenerator(options);
+          break;
+        case 'playwright-python':
+          generator = new PlaywrightPythonGenerator(options);
+          break;
+        case 'selenium-python':
+          generator = new SeleniumPythonGenerator(options);
+          break;
+        case 'selenium-java':
+          generator = new SeleniumJavaGenerator(options);
+          break;
+        default:
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
-                success: true,
-                mode: 'append',
-                file: args.appendToFile,
-                testName: args.testName || scenario.metadata?.name,
-                insertPosition: appendOptions.insertPosition,
-                message: `Test '${args.testName || scenario.metadata?.name}' successfully appended to ${args.appendToFile}`
-              }, null, 2)
-            }]
-          };
-        } catch (error) {
-          return {
-            content: [{
-              type: 'text',
-              text: JSON.stringify({
-                success: false,
-                mode: 'append',
-                file: args.appendToFile,
-                error: error.message
+                error: `Unknown language: ${args.language}. Supported: playwright-typescript, playwright-python, selenium-python, selenium-java`
               }, null, 2)
             }],
             isError: true
           };
-        }
       }
 
-      // Non-append mode: Generate test code
+      // Generate test code with full imports
       const testCode = generator.generate(scenario, options);
 
+      // Generate suggested filename
+      const testName = scenario.metadata?.name || 'test';
+      const extension = args.language.includes('typescript') ? '.spec.ts' :
+                       args.language.includes('java') ? 'Test.java' :
+                       args.language.includes('python') ? '_test.py' : '.test.js';
+      const suggestedFileName = args.language.includes('java')
+        ? testName.charAt(0).toUpperCase() + testName.slice(1) + 'Test.java'
+        : testName.replace(/\s+/g, '_').toLowerCase() + extension;
+
       // If generatePageObject is requested, also generate Page Object class
       if (args.generatePageObject) {
         try {
@@ -2205,19 +2333,26 @@ async function executeToolInternal(name, args) {
           const pageObjectResult = await generatePageObject(page, pageObjectOptions);
 
           if (pageObjectResult.success) {
+            // Suggest Page Object filename
+            const poExtension = args.language.includes('typescript') ? '.ts' :
+                               args.language.includes('java') ? '.java' : '.py';
+            const pageObjectFileName = `${pageObjectResult.className}${poExtension}`;
+
             // Return both test code and Page Object code
             return {
               content: [{
                 type: 'text',
                 text: JSON.stringify({
-                  success: true,
+                  action: 'create_new_file',
+                  suggestedFileName: suggestedFileName,
                   testCode: testCode,
-                  pageObjectCode: pageObjectResult.code,
-                  pageObjectClassName: pageObjectResult.className,
-                  framework: args.language,
-                  scenarioName: args.scenarioName,
-                  url: pageObjectResult.url,
-                  elementCount: pageObjectResult.elementCount
+                  pageObject: {
+                    code: pageObjectResult.code,
+                    className: pageObjectResult.className,
+                    suggestedFileName: pageObjectFileName,
+                    elementCount: pageObjectResult.elementCount
+                  },
+                  instruction: `Create a new test file '${suggestedFileName}' with the testCode. Also create a Page Object file '${pageObjectFileName}' with the pageObject.code.`
                 }, null, 2)
               }]
             };
@@ -2227,10 +2362,11 @@ async function executeToolInternal(name, args) {
               content: [{
                 type: 'text',
                 text: JSON.stringify({
-                  success: true,
+                  action: 'create_new_file',
+                  suggestedFileName: suggestedFileName,
                   testCode: testCode,
-                  pageObjectCode: null,
-                  warning: 'Page Object generation failed: ' + (pageObjectResult.error || 'Unknown error')
+                  warning: 'Page Object generation failed: ' + (pageObjectResult.error || 'Unknown error'),
+                  instruction: `Create a new test file '${suggestedFileName}' with the testCode.`
                 }, null, 2)
               }]
             };
@@ -2241,10 +2377,11 @@ async function executeToolInternal(name, args) {
             content: [{
               type: 'text',
               text: JSON.stringify({
-                success: true,
+                action: 'create_new_file',
+                suggestedFileName: suggestedFileName,
                 testCode: testCode,
-                pageObjectCode: null,
-                warning: 'Page Object generation error: ' + error.message
+                warning: 'Page Object generation error: ' + error.message,
+                instruction: `Create a new test file '${suggestedFileName}' with the testCode.`
               }, null, 2)
             }]
           };
@@ -2255,7 +2392,12 @@ async function executeToolInternal(name, args) {
       return {
         content: [{
           type: 'text',
-          text: testCode
+          text: JSON.stringify({
+            action: 'create_new_file',
+            suggestedFileName: suggestedFileName,
+            testCode: testCode,
+            instruction: `Create a new test file '${suggestedFileName}' with the testCode.`
+          }, null, 2)
         }]
       };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrometools-mcp",
-  "version": "2.2.0",
+  "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-definitions.js

@@ -541,7 +541,7 @@ export const toolDefinitions = [
       },
       {
         name: "exportScenarioAsCode",
-        description: "Export recorded scenario as executable test code for various frameworks. Automatically cleans unstable selectors (CSS modules, styled-components). Optionally generates Page Object class for the page. Can append to existing test files. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        description: "Export recorded scenario as executable test code for creating a NEW test file. Automatically cleans unstable selectors (CSS modules, styled-components). Optionally generates Page Object class. Returns JSON with code and suggested filename - Claude Code will create the file. To add tests to EXISTING files, use 'appendScenarioToFile' instead. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
         inputSchema: {
           type: "object",
           properties: {
@@ -570,9 +570,28 @@ export const toolDefinitions = [
               type: "string",
               description: "Page Object class name (optional, auto-generated if not provided)"
             },
-            appendToFile: {
+          },
+          required: ["scenarioName", "language"],
+        },
+      },
+      {
+        name: "appendScenarioToFile",
+        description: "Append recorded scenario as test code to an EXISTING test file. Automatically cleans unstable selectors (CSS modules, styled-components). Optionally generates Page Object class. Returns JSON with test code and target file - Claude Code will append to the file without overwriting existing tests. To create NEW test files, use 'exportScenarioAsCode' instead. Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/. Use global index at ~/.config/chrometools-mcp/index.json to discover available projects and scenarios.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            scenarioName: {
+              type: "string",
+              description: "Name of scenario to export"
+            },
+            language: {
+              type: "string",
+              enum: ["playwright-typescript", "playwright-python", "selenium-python", "selenium-java"],
+              description: "Target test framework and language"
+            },
+            targetFile: {
               type: "string",
-              description: "Path to existing test file to append to (enables append mode)"
+              description: "Path to existing test file to append to (REQUIRED)"
             },
             testName: {
               type: "string",
@@ -581,14 +600,30 @@ export const toolDefinitions = [
             insertPosition: {
               type: "string",
               enum: ["end", "before", "after"],
-              description: "Where to insert test: 'end' (default), 'before', or 'after' a reference test"
+              description: "Where to insert test: 'end' (default - after all tests), 'before' (before reference test), or 'after' (after reference test)"
             },
             referenceTestName: {
               type: "string",
-              description: "Reference test name for 'before'/'after' insertion"
+              description: "Reference test name for 'before'/'after' insertion. Required when insertPosition is 'before' or 'after'"
+            },
+            cleanSelectors: {
+              type: "boolean",
+              description: "Remove unstable CSS classes (default: true)"
+            },
+            includeComments: {
+              type: "boolean",
+              description: "Include descriptive comments (default: true)"
+            },
+            generatePageObject: {
+              type: "boolean",
+              description: "Also generate Page Object class for the page (default: false)"
+            },
+            pageObjectClassName: {
+              type: "string",
+              description: "Page Object class name (optional, auto-generated if not provided)"
             },
           },
-          required: ["scenarioName", "language"],
+          required: ["scenarioName", "language", "targetFile"],
         },
       },
       {

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);
+}