cdp-tools-mcp/docs/messages.md

MCP server that connects AI assistants to Chrome DevTools Protocol for runtime debugging - set breakpoints, inspect variables, monitor network traffic, and automate browser interactions

# cdp-tools Message Templates

This file contains all user-facing messages for the cdp-tools debugger. Messages use markdown formatting and support variable interpolation using `{{variable}}` syntax.

## Template Usage Status

Some templates are currently unused but kept for:
- Future error paths and edge cases
- Potential error conditions not yet encountered
- Consistency across similar tools
- Forward compatibility

**Currently unused templates (kept for future use):**
- BREAKPOINT_ALREADY_EXISTS - For duplicate breakpoint detection
- CHROME_LAUNCH_SUCCESS - For enhanced launch messages
- CONSOLE_MONITORING_ENABLED - For explicit monitoring activation
- DEBUGGER_CONNECT_SUCCESS - Reserved for verbose connection mode
- EXECUTION_CONTEXT_DESTROYED - For context destruction errors
- LINE_NOT_FOUND - For invalid line number errors
- LOGPOINT_SET_SUCCESS - For logpoint creation confirmation
- LOGPOINT_VALIDATE_SUCCESS - For logpoint validation feedback
- PLATFORM_UNSUPPORTED - For unsupported platform errors
- PORT_NOT_INSPECTABLE - For port availability errors
- SCRIPT_NOT_FOUND - For missing script errors
- SESSION_CLOSED - For session termination errors
- TIMEOUT_WAITING_FOR_PAUSE - For pause timeout errors

These templates should not be removed - they represent potential error conditions or future enhancements.

---

## Connection Messages

## CHROME_ALREADY_RUNNING

**Type:** error
**Code:** CHROME_RUNNING

Chrome is already running. You can either:

**Suggestions:**
- Use `killChrome()` to close the existing instance
- Use `connectDebugger()` to connect to the running instance instead

---

## CHROME_LAUNCH_SUCCESS

**Type:** success
**Summary:** Chrome launched and connected

Title: {{title}}, URL: {{url}}{{#consoleStats}}

Console: {{consoleStats}}{{/consoleStats}}

{{#hasUserReference}}Ready to use! Use connectionReason: "{{reference}}" in tool calls.{{/hasUserReference}}{{^hasUserReference}}Ready to use! Use connectionReason: "{{reference}}" in tool calls, or rename with tab({ action: 'rename' }) first.{{/hasUserReference}}

---

## CHROME_CONNECTION_REUSED

**Type:** success
**Summary:** Chrome connection reused (already exists)

Title: {{title}}, URL: {{url}}

Ready to use! Use connectionReason: "{{reference}}" in tool calls.

---

## CHROME_LAUNCH_NO_CONNECT

**Type:** success

Chrome launched with debugging on port {{port}}

---

## CHROME_LAUNCH_AUTO_CONNECT_FAILED

**Type:** warning

Chrome launched successfully but auto-connect failed: {{error}}

**Note:** Use `connectDebugger()` to connect manually.

---

## DEBUGGER_CONNECT_SUCCESS

**Type:** success
**Summary:** Connected to {{runtimeType}} debugger

Host: {{host}}:{{port}}, Reference: {{reference}}

Features: {{features}}{{#consoleStats}}
Console: {{consoleStats}}{{/consoleStats}}{{#isChrome}}

Note: Console monitoring auto-enabled. Page auto-reloaded to capture initial logs.

IMPORTANT: Please provide a reference name for this tab using the renameTab tool.{{/isChrome}}{{#isNode}}

Note: Browser automation features are not available for Node.js debugging.
Console Monitoring: Enabled via CDP (logpoint output and console.log calls will be captured).{{/isNode}}

---

## DEBUGGER_CONNECT_FAILED

**Type:** error
**Code:** CONNECTION_FAILED

Failed to connect to debugger at {{host}}:{{port}}: {{error}}

**Suggestions:**
- Verify the debugger is running and listening on the specified port
- For Chrome: Launch with `launchChrome()` or start with `--remote-debugging-port={{port}}`
- For Node.js: Start with `node --inspect={{port}} app.js`

---

## DEBUGGER_NOT_RUNNING

**Type:** error
**Code:** NOT_RUNNING

{{message}}

**Note:** This error occurs when trying to connect to a debugger that is not running on the specified port.

---

## DEBUGGER_NOT_CONNECTED

**Type:** error
**Code:** NOT_CONNECTED
**Summary:** Debugger not connected

No active debugger connection found.

**Suggestions:**
- Use `launchChrome()` to launch Chrome with debugging enabled
- Use `connectDebugger()` to connect to an existing debugger instance

**Example:**
```javascript
// Launch Chrome
launchChrome({ url: 'http://localhost:3000' })

// Or connect to existing
connectDebugger({ host: 'localhost', port: 9222 })
```

---

## DEBUGGER_DISCONNECT_SUCCESS

**Type:** success

Disconnected from connection: {{reference}}

---

## PORT_NOT_INSPECTABLE

**Type:** error
**Code:** PORT_NOT_READY

Chrome debugging port {{port}} failed to become inspectable within the timeout period

**Suggestions:**
- Chrome may be starting slowly - try increasing the timeout
- Check if another process is using port {{port}}
- Verify Chrome launched successfully (check process list)

---

## CHROME_KILLED

**Type:** success

action:killed;port:{{port}};reason:{{reason}}

---

## CHROME_STATUS

**Type:** info

Chrome launcher status

{{#if lastCloseEvents.length}}
### Recent Close Events

{{#each lastCloseEvents}}
- **{{reason}}** (port {{port}}, PID {{pid}}) at {{timestamp}}{{#hasExitCode}} - exit code: {{exitCode}}{{/hasExitCode}}{{#signal}} - signal: {{signal}}{{/signal}}
{{/each}}
{{/if}}

---

## CHROME_LAUNCHER_RESET

**Type:** success

Chrome launcher state reset successfully

---

## CONNECTION_STATUS

**Type:** info

Connection status retrieved

---

## CONNECTIONS_LIST

**Type:** info

Active debugger connections ({{totalConnections}} total)

---

## CONNECTION_SWITCH_SUCCESS

**Type:** success

Switched to connection: {{reference}}

---

## CONNECTION_SWITCH_FAILED

**Type:** error
**Code:** CONNECTION_NOT_FOUND

Connection with reference "{{reference}}" not found

**Suggestion:** Use `listConnections()` to see all available connections.

---

## CONNECTION_NOT_FOUND

**Type:** error
**Code:** NO_CONNECTION
**Summary:** Connection not found

No active browser connection available.

**Suggestions:**
- Use `launchChrome()` to launch Chrome with debugging enabled
- Use `connectDebugger()` to connect to an existing debugger instance

---

## INVALID_REFERENCE

**Type:** error
**Code:** INVALID_REFERENCE

Invalid reference: {{error}}

**Requirements:**
- Reference must be exactly 3 words
- Words are separated by spaces

---

## REFERENCE_IN_USE

**Type:** error
**Code:** REFERENCE_IN_USE

Reference "{{reference}}" is already in use by another connection

**Suggestion:** Choose a different 3-word reference that describes this specific debugging activity.

---

## SOURCE_MAPS_LOADED

**Type:** success

Loaded {{count}} source maps from {{directory}}

---

## SOURCE_MAPS_FAILED

**Type:** error
**Code:** SOURCE_MAP_ERROR

Failed to load source maps: {{error}}

**Suggestions:**
- Verify the directory path is correct
- Ensure .js.map files exist in the directory
- Check file permissions

---

## SOURCE_CODE_SUCCESS

**Type:** success

Source code retrieved from {{url}} (lines {{startLine}}-{{endLine}})

---

## SOURCE_CODE_FAILED

**Type:** error
**Code:** SOURCE_CODE_ERROR

Failed to retrieve source code: {{error}}

---

## CODE_SEARCH_RESULTS

**Type:** info

Code search completed - found {{count}} matches

---

## FUNCTION_SEARCH_RESULTS

**Type:** info

Function search completed - found {{count}} matches for '{{functionName}}'

---

## Breakpoint Messages

## BREAKPOINT_SET_SUCCESS

**Type:** success
**Summary:** Breakpoint set

Location: {{url}}:{{resolvedLine}}, ID: {{breakpointId}}{{#wasAdjusted}}

⚠️ CDP resolved to {{resolvedLocation}} (requested {{requestedLocation}}) due to source mapping{{/wasAdjusted}}{{#condition}}
Condition: {{condition}}{{/condition}}

---

## BREAKPOINT_SET_FAILED

**Type:** error
**Code:** BREAKPOINT_FAILED
**Summary:** Failed to set breakpoint

Location: {{url}}:{{lineNumber}}
Reason: {{error}}

**Suggestions:**
- Verify the file URL is correct (use `file://` for local files or `http://` for web URLs)
- Ensure the line number exists in the source file
- Check that the debugger is paused or the script is already loaded

---

## BREAKPOINT_ALREADY_EXISTS

**Type:** error
**Code:** BREAKPOINT_EXISTS

A breakpoint already exists at {{url}}:{{lineNumber}}

**TIP:** Use `listBreakpoints()` to see all active breakpoints and their IDs.

---

## BREAKPOINT_REMOVE_SUCCESS

**Type:** success

Breakpoint {{breakpointId}} removed successfully

---

## BREAKPOINT_NOT_FOUND

**Type:** error
**Code:** BREAKPOINT_NOT_FOUND

Breakpoint {{breakpointId}} not found

**Suggestions:**
- Use `listBreakpoints()` to see all active breakpoints
- The breakpoint may have already been removed

---

## LOGPOINT_SET_SUCCESS

**Type:** success

Logpoint set at {{url}}:{{lineNumber}} (max executions: {{maxExecutions}})

**Breakpoint ID:** `{{breakpointId}}`
**Log message:** `{{logMessage}}`

**Note:** Logpoint will pause execution after {{maxExecutions}} executions. Use `resetLogpointCounter()` to reset the counter.

---

## LOGPOINT_VALIDATE_SUCCESS

**Type:** success

Logpoint validation successful! The expression can be evaluated at {{url}}:{{lineNumber}}

**Sample output:** {{sampleOutput}}

---

## LOGPOINT_VALIDATE_FAILED

**Type:** error
**Code:** LOGPOINT_INVALID

Logpoint validation failed: {{error}}

**Suggestions:**
- Check that the expressions in `{curly braces}` are valid JavaScript
- Ensure variables referenced exist in the scope at that line
- Try evaluating the expression manually with `evaluateExpression()`

---

## LOGPOINT_LIMIT_EXCEEDED

**Type:** warning
**Code:** LOGPOINT_LIMIT

Logpoint at {{url}}:{{lineNumber}} has reached execution limit ({{executionCount}}/{{maxExecutions}})

Captured logs:
{{logs}}

Options:
- Use resetLogpointCounter('{{breakpointId}}') to continue logging
- Use removeBreakpoint('{{breakpointId}}') to remove the logpoint
- Review the captured logs above

---

## LOGPOINT_COUNTER_RESET

**Type:** success

Logpoint {{breakpointId}} execution counter reset. It can now execute {{maxExecutions}} more times.

---

## Execution Messages

## EXECUTION_PAUSED

**Type:** success

Execution paused

---

## EXECUTION_RESUMED

**Type:** success

Execution resumed

---

## EXECUTION_STEP_OVER

**Type:** success

Stepped over to next line

---

## EXECUTION_STEP_INTO

**Type:** success

Stepped into function

---

## EXECUTION_STEP_OUT

**Type:** success

Stepped out of function

---

## CALL_STACK_SUCCESS

**Type:** success

Call Stack ({{frameCount}} frames){{#pausedLocation}} - Paused at: {{pausedLocation}}{{/pausedLocation}}

---

## VARIABLES_SUCCESS

**Type:** success

Variables for call frame {{callFrameId}}: {{returnedCount}} of {{totalCount}} total at depth {{usedDepth}}{{#filter}} (filtered by: {{filter}}){{/filter}}{{#includeGlobal}} (includes global scope){{/includeGlobal}}

---

## VARIABLES_DEPTH_REDUCED

**Type:** warning

Variables for call frame {{callFrameId}}: {{totalCount}} total (depth reduced from {{requestedDepth}} to {{usedDepth}}){{#filter}} (filtered by: {{filter}}){{/filter}}

Variable names/types shown. To inspect at full depth:
- Use `filter` parameter (e.g., filter: "^myVar$") to narrow results
- Use `evaluateExpression` (e.g., expression: "myVar") for specific values

---

## VARIABLES_NAMES_ONLY

**Type:** warning

Variables for call frame {{callFrameId}}: {{totalCount}} total (names only, values exceed limit)

Variable names listed by scope. To inspect values:
- Use `filter` parameter (e.g., filter: "^myVar$") to get values for matching variables
- Use `evaluateExpression` (e.g., expression: "myVar") to evaluate directly

---

## VARIABLES_COUNTS_ONLY

**Type:** warning

Variables for call frame {{callFrameId}}: {{totalCount}} total (counts only, names exceed limit)

Variable counts per scope shown. Too many variables to list names. To inspect:
- Use `filter` parameter to narrow scope (e.g., filter: "config|state|user")
- Use `includeGlobal: false` to exclude global scope (often has 100+ built-ins)
- Use `evaluateExpression` to check a specific variable directly

---

## VARIABLES_FILTER_INSUFFICIENT

**Type:** warning

Variables for call frame {{callFrameId}}: {{totalCount}} variables match filter "{{filter}}" (still exceeds limit)

The filter matches too many variables. Try:
- A more specific filter pattern (e.g., filter: "^exactName$" instead of "name")
- Use `evaluateExpression` to inspect a specific variable directly
- Use `includeGlobal: false` if global scope variables are included

---

## EVALUATE_EXPRESSION_SUCCESS

**Type:** success
**Summary:** Expression evaluated successfully

Expression: {{expression}}, Context: {{context}}

Result:
{{result}}

---

## EVALUATE_EXPRESSION_FAILED

**Type:** error
**Code:** EVALUATION_FAILED

Failed to evaluate expression: {{error}}

**Expression:** `{{expression}}`

**Suggestions:**
- Check that the expression is valid JavaScript
- Ensure variables referenced exist in the current scope
- If evaluating in a specific frame, verify the call frame ID is valid with `getCallStack()`

---

## NOT_PAUSED

**Type:** error
**Code:** NOT_PAUSED

Not currently paused at a breakpoint

**Suggestions:**
- Use `pause()` to pause execution
- Set a breakpoint with `setBreakpoint()` and trigger it
- Wait for execution to hit an existing breakpoint

---

## TIMEOUT_WAITING_FOR_PAUSE

**Type:** error
**Code:** TIMEOUT

Timeout waiting for execution to pause

**Suggestions:**
- The breakpoint may not be hit in the code path being executed
- Try increasing the timeout duration
- Verify the breakpoint is set at the correct location with `listBreakpoints()`

---

## Browser Automation Messages

## PAGE_NAVIGATE_SUCCESS

**Type:** success
**Summary:** Navigation complete

URL: {{url}}{{#title}}, Title: {{title}}{{/title}}{{#clickableElements}}

**Clickable elements:** {{clickableElements.total}} total ({{clickableElements.inViewport}} in viewport)

{{clickableElements.hint}}{{/clickableElements}}{{#console}}

**Console:** {{console.errors}} errors, {{console.warnings}} warnings{{#console.hint}} - {{console.hint}}{{/console.hint}}{{/console}}{{#network}}

**Network:** {{network.failed}} failed requests of {{network.total}} total - {{network.hint}}{{/network}}

---

## PAGE_GO_BACK_SUCCESS

**Type:** success

Navigated back{{#url}} to: {{url}}{{/url}}{{#clickableElements}}

**Clickable elements:** {{clickableElements.total}} total ({{clickableElements.inViewport}} in viewport){{/clickableElements}}{{#console}}

**Console:** {{console.errors}} errors, {{console.warnings}} warnings{{#console.hint}} - {{console.hint}}{{/console.hint}}{{/console}}{{#network}}

**Network:** {{network.failed}} failed requests of {{network.total}} total - {{network.hint}}{{/network}}

---

## PAGE_GO_FORWARD_SUCCESS

**Type:** success

Navigated forward{{#url}} to: {{url}}{{/url}}{{#clickableElements}}

**Clickable elements:** {{clickableElements.total}} total ({{clickableElements.inViewport}} in viewport){{/clickableElements}}{{#console}}

**Console:** {{console.errors}} errors, {{console.warnings}} warnings{{#console.hint}} - {{console.hint}}{{/console.hint}}{{/console}}{{#network}}

**Network:** {{network.failed}} failed requests of {{network.total}} total - {{network.hint}}{{/network}}

---

## PAGE_INFO_SUCCESS

**Type:** success
**Summary:** Page information

URL: {{url}}, Title: {{title}}

---

## PAGE_RELOAD_SUCCESS

**Type:** success

Page reloaded successfully{{#clickableElements}}

**Clickable elements:** {{clickableElements.total}} total ({{clickableElements.inViewport}} in viewport){{/clickableElements}}{{#console}}

**Console:** {{console.errors}} errors, {{console.warnings}} warnings{{#console.hint}} - {{console.hint}}{{/console.hint}}{{/console}}{{#network}}

**Network:** {{network.failed}} failed requests of {{network.total}} total - {{network.hint}}{{/network}}

---

## ELEMENT_NOT_FOUND

**Type:** error
**Code:** ELEMENT_NOT_FOUND

Element not found: `{{selector}}`

**Suggestions:**
- Verify the CSS selector is correct
- Use `querySelector()` to test if the element exists
- The element may not be visible or loaded yet - try waiting or reloading the page

---

## ELEMENT_CLICK_SUCCESS

**Type:** success
**Summary:** Element clicked

Selector: `{{selector}}`

---

## TEXT_TYPE_SUCCESS

**Type:** success

Text typed into `{{selector}}`: "{{text}}"

---

## KEY_PRESS_SUCCESS

**Type:** success

Key pressed: `{{key}}`

---

## ELEMENT_HOVER_SUCCESS

**Type:** success

Hovered over element: `{{selector}}`

---

## ELEMENT_FOCUS_SUCCESS

**Type:** success
**Summary:** Element focused

{{description}}, Selector: {{selector}}{{#nextTabbable}}

Next tab: {{nextTabbable}}{{/nextTabbable}}{{#warning}}

Warning: {{warning}}{{/warning}}

---

## FOCUS_NEXT_SUCCESS

**Type:** success
**Summary:** Tabbed forward{{#count}} {{count}} times{{/count}}

{{description}}, Selector: {{selector}}{{#nextTabbable}}

Next tab: {{nextTabbable}}{{/nextTabbable}}

---

## FOCUS_PREVIOUS_SUCCESS

**Type:** success
**Summary:** Tabbed backward{{#count}} {{count}} times{{/count}}

{{description}}, Selector: {{selector}}{{#nextTabbable}}

Next tab: {{nextTabbable}}{{/nextTabbable}}

---

## INVALID_ACTION

**Type:** error
**Code:** INVALID_ACTION

Invalid action: {{action}}

**Valid actions:** {{validActions}}

---

## ELEMENT_CLICK_WARNING

**Type:** warning

Element `{{selector}}` was clicked, but may not have a click handler attached. Verify the expected action occurred.

---

## ACTION_PAUSED_AT_BREAKPOINT

**Type:** success

{{action}} on `{{selector}}` triggered breakpoint at {{url}}:{{lineNumber}}

**Next steps:**
- Use `getCallStack()` to see the full call stack
- Use `getVariables()` to inspect variables at this location
- Use `stepOver()`, `stepInto()`, or `stepOut()` to continue debugging
- Use `resume()` to continue execution

---

## ELEMENT_BLOCKED_BY_MODAL

**Type:** error
**Code:** ELEMENT_BLOCKED

Cannot interact with element `{{selector}}` - blocked by {{modalDescription}}

**Modal details:**
- Type: {{modalType}}
- Selector: `{{modalSelector}}`
- Available dismiss strategies: {{availableStrategies}}

**Suggestions:**
- Use `dismissModal()` tool to remove the blocking modal first
- Enable `handleModals: true` parameter to automatically dismiss modals
- Use `detectModals()` to see all blocking elements on the page

{{#suggestion}}
**Hint:** {{suggestion}}
{{/suggestion}}

---

## SCREENSHOT_SAVED

**Type:** success
**Summary:** Screenshot saved

Path: {{filepath}}, Size: {{fileSize}}

---

## DOM_SNAPSHOT_SUCCESS

**Type:** success

DOM snapshot retrieved (depth: {{depth}})

---

## Monitoring Messages

## CONSOLE_MONITORING_ENABLED

**Type:** info

Console monitoring auto-enabled. Page auto-reloaded to capture initial logs.

---

## CONSOLE_CLEARED

**Type:** success

Console cleared successfully ({{count}} messages removed)

---

## CONSOLE_MESSAGES_LIST

**Type:** success
**Summary:** Console messages retrieved

Count: {{count}} of {{totalCount}} total{{#type}} (filtered by type: {{type}}){{/type}}

---

## CONSOLE_MESSAGE_DETAIL

**Type:** success

Console message [{{id}}] - Type: {{type}}, Timestamp: {{timestamp}}
Text: {{text}}

---

## CONSOLE_MESSAGES_RECENT

**Type:** success

Recent Console Messages: {{count}} of {{requestedCount}} requested ({{totalCount}} total){{#type}} (filtered by type: {{type}}){{/type}}

---

## CONSOLE_SEARCH_RESULTS

**Type:** success

Console Log Search: {{matchCount}} matches for pattern "{{pattern}}"{{#flags}} (flags: {{flags}}){{/flags}}{{#type}} (type: {{type}}){{/type}} out of {{totalSearched}} searched

---

## NETWORK_MONITORING_ENABLED

**Type:** success

Network monitoring enabled

---

## NETWORK_MONITORING_DISABLED

**Type:** success

Network monitoring disabled

---

## NETWORK_CONDITIONS_SET

**Type:** success

Network conditions set to **{{preset}}**

---

## NETWORK_REQUESTS_LIST

**Type:** success
**Summary:** Network requests retrieved

Count: {{count}} of {{totalCount}} total{{#resourceType}} (filtered by type: {{resourceType}}){{/resourceType}}

---

## NETWORK_REQUEST_DETAIL

**Type:** success

Network Request [{{id}}]: {{method}} {{url}}
Resource Type: {{resourceType}}, Status: {{status}}{{#failed}}
FAILED: {{errorText}}{{/failed}}

---

## NETWORK_SEARCH_RESULTS

**Type:** success

Network Request Search: {{matchCount}} matches for pattern "{{pattern}}"{{#flags}} (flags: {{flags}}){{/flags}}{{#filtersText}} (filters: {{filtersText}}){{/filtersText}} out of {{totalSearched}} searched

---

## NETWORK_REQUEST_NOT_FOUND

**Type:** error
**Code:** REQUEST_NOT_FOUND

Network request {{id}} not found

**Suggestions:**
- Use `listNetworkRequests()` to see all captured requests
- Ensure network monitoring was enabled before the request was made
- The request may have occurred before monitoring started

---

## Validation Errors

## SCRIPT_NOT_FOUND

**Type:** error
**Code:** SCRIPT_NOT_FOUND

Script not found for URL: {{url}}

**Suggestions:**
- Verify the URL is correct (use `file://` for local files)
- Ensure the script has been loaded by the browser
- For dynamically loaded scripts, wait for them to load before setting breakpoints
- Use `searchCode()` to find available scripts

---

## LINE_NOT_FOUND

**Type:** error
**Code:** LINE_NOT_FOUND

Line {{lineNumber}} not found in {{url}}

**Suggestions:**
- Verify the line number exists in the source file
- If using source maps, check that they're loaded correctly
- The file may have been modified - reload the page

---

## CALL_FRAME_NOT_FOUND

**Type:** error
**Code:** FRAME_NOT_FOUND

Call frame {{callFrameId}} not found

**Suggestions:**
- Use `getCallStack()` to get valid call frame IDs
- Ensure execution is still paused at a breakpoint
- The call stack may have changed if execution resumed

---

## INVALID_FILTER

**Type:** error
**Code:** INVALID_REGEX

Invalid filter regex: {{filter}}

{{error}}

**Suggestions:**
- Check regex syntax (e.g., escape special characters like `[`, `]`, `(`, `)`)
- Test your regex at regex101.com before using

---

## System Errors

## PLATFORM_UNSUPPORTED

**Type:** error
**Code:** PLATFORM_UNSUPPORTED

Unsupported platform: {{platform}}

**Note:** Chrome launching is only supported on macOS, Windows, and Linux.

---

## CHROME_SPAWN_FAILED

**Type:** error
**Code:** SPAWN_FAILED

Failed to spawn Chrome process: {{error}}

**Suggestions:**
- Verify Chrome is installed on your system
- Check that you have permission to execute Chrome
- On macOS: Chrome should be at `/Applications/Google Chrome.app`
- On Linux: Chrome/Chromium should be in your PATH

---

## PUPPETEER_NOT_CONNECTED

**Type:** error
**Code:** PUPPETEER_NOT_CONNECTED

Not connected to browser. This operation requires browser automation support.

**Suggestions:**
1. Launch Chrome with `launchChrome()` (automatically enables browser automation)
2. Or connect to Chrome: `connectDebugger({ host: 'localhost', port: 9222 })`

**Note:** Browser automation features (DOM interaction, screenshots, navigation) are only available when connected to Chrome, not Node.js.

---

## PAGE_NOT_LOADED

**Type:** error
**Code:** PAGE_NOT_LOADED

No page loaded. The tool `{{toolName}}` requires a web page to be loaded first.

**Suggestions:**
1. Navigate to a URL with `navigateTo({ url: 'https://example.com' })`
2. Or launch Chrome with a URL: `launchChrome({ url: 'https://example.com' })`

**Note:** Chrome starts with a blank page by default. You must navigate to a URL before using tools that interact with page content.

---

## NODEJS_NOT_SUPPORTED

**Type:** error
**Code:** FEATURE_NOT_SUPPORTED

This feature is not supported for Node.js debugging ({{feature}})

**Available for Node.js:**
- Breakpoints and debugging
- Code execution and evaluation
- Call stack inspection
- Console log monitoring

**Not available for Node.js:**
- Browser automation (DOM, screenshots, navigation)
- Network request monitoring

**Suggestion:** Use `launchChrome()` if you need browser automation features.

---

## EXECUTION_CONTEXT_DESTROYED

**Type:** error
**Code:** CONTEXT_DESTROYED

Execution context was destroyed (page may have navigated or reloaded)

**Suggestions:**
- Reload the page and try again
- Reconnect to the debugger with `connectDebugger()`
- Check if the page navigated unexpectedly

---

## SESSION_CLOSED

**Type:** error
**Code:** SESSION_CLOSED

Debugger session closed unexpectedly

**Suggestions:**
- The browser or Node.js process may have crashed or been closed
- Use `getDebuggerStatus()` to check connection status
- Reconnect with `connectDebugger()` or relaunch with `launchChrome()`

---

## COOKIE_SET_SUCCESS

**Type:** success

Cookie set: `{{name}}`

---

## LOCAL_STORAGE_SET_SUCCESS

**Type:** success

localStorage item set: `{{key}}` = "{{value}}"

---

## STORAGE_CLEARED

**Type:** success

Storage cleared successfully ({{types}})

---

## Variable Templates

Common variables used across messages:

- `{{port}}` - Port number (e.g., 9222)
- `{{host}}` - Hostname (e.g., localhost)
- `{{url}}` - File or page URL
- `{{lineNumber}}` - Line number in source code
- `{{columnNumber}}` - Column number in source code (optional)
- `{{breakpointId}}` - Unique breakpoint identifier
- `{{reference}}` - Connection reference name
- `{{runtimeType}}` - 'chrome' or 'node'
- `{{error}}` - Error message or details
- `{{selector}}` - CSS selector string
- `{{filepath}}` - File system path
- `{{fileSize}}` - Human-readable file size
- `{{id}}` - Generic identifier (request ID, log ID, etc.)
- `{{count}}` - Numeric count
- `{{logMessage}}` - Logpoint message template
- `{{maxExecutions}}` - Maximum execution count for logpoints
- `{{executionCount}}` - Current execution count
- `{{logs}}` - Formatted log output
- `{{feature}}` - Feature name
- `{{platform}}` - Operating system platform
- `{{types}}` - List of storage types
- `{{depth}}` - DOM traversal depth
- `{{sampleOutput}}` - Example output from validation
- `{{newReference}}` - New tab reference name
- `{{oldReference}}` - Old tab reference name
- `{{closedReference}}` - Closed tab reference
- `{{newActiveReference}}` - New active tab reference

---

## Tab Management Messages

## TAB_CREATE_SUCCESS

**Type:** success
**Summary:** New tab created and connected

Title: {{title}}, URL: {{url}}{{#consoleStats}}

Console: {{consoleStats}}{{/consoleStats}}

---

## TAB_LIST_EMPTY

**Type:** info
**Summary:** No Chrome tabs open

Use action "create" to create a new tab.

---

## TAB_LIST_SUCCESS

**Type:** list
**Summary:** {{count}} open tab(s)

{{tabList}}

Tip: Use action "switch" to switch tabs, or "create" to open a new one.

---

## TAB_CREATE_FAILED

**Type:** error
**Code:** TAB_CREATE_FAILED

Failed to create new tab: {{error}}

**Suggestions:**
- Ensure a Chrome browser is already running (use `launchChrome` first)
- Check that the browser connection is still active

---

## TAB_RENAME_SUCCESS

**Type:** success
**Summary:** Tab renamed

Old: {{oldReference}}, New: {{newReference}}

---

## TAB_SWITCH_SUCCESS

**Type:** success
**Summary:** Switched to tab

Title: {{title}}, URL: {{url}}

---

## TAB_CLOSE_SUCCESS

**Type:** success
**Summary:** Tab closed

New active: {{newActiveReference}}

---

## TAB_CLOSE_FAILED

**Type:** error
**Code:** TAB_CLOSE_FAILED

Failed to close tab: {{reference}}

**Suggestions:**
- Verify the reference is correct using `listTabs()`
- The tab may have already been closed

---

## DEBUG_LOGGING_ENABLED

**Type:** success
**Code:** DEBUG_LOGGING_ENABLED

{{message}}

Debug logs will be written to `.cdp-tools/logs/debug.log` and visible in the MCP server's stderr output.

---

## DEBUG_LOGGING_DISABLED

**Type:** success
**Code:** DEBUG_LOGGING_DISABLED

{{message}}

Debug logging is now disabled. No logs will be written.

---

## DEBUG_LOGGING_STATUS

**Type:** success
**Code:** DEBUG_LOGGING_STATUS

Debug logging is currently **{{status}}**.
{{#enabled}}
Logs are being written to: `{{logFile}}`
{{/enabled}}

---

## FILE_DOWNLOADED

**Type:** success
**Code:** FILE_DOWNLOADED

File downloaded successfully from `{{url}}`

Saved to: `{{filepath}}`
Size: {{size}}

---

## FILE_DOWNLOADED_OVERWROTE

**Type:** success
**Code:** FILE_DOWNLOADED_OVERWROTE

File downloaded and **overwrote existing file** at `{{filepath}}`

Downloaded from: `{{url}}`
Size: {{size}}

---

## FILE_ALREADY_EXISTS

**Type:** error
**Code:** FILE_ALREADY_EXISTS

**ERROR:** A file named `{{filename}}` already exists at this location.

**Existing file:**
- Path: `{{filepath}}`
- Size: {{existingSize}}
- Last modified: {{existingModified}}

**New file from `{{url}}`:**
- Size: {{newSize}}

Please choose a different, more descriptive filename or set `overwriteIfExists: true` to replace the existing file.

---

## CANNOT_OVERWRITE_NONEXISTENT

**Type:** error
**Code:** CANNOT_OVERWRITE_NONEXISTENT

**ERROR:** Cannot set `overwriteIfExists: true` for a file that doesn't exist yet.

The file `{{filename}}` does not exist at `{{filepath}}`.

Remove the `overwriteIfExists` parameter (it defaults to false) for new downloads.

---

## FILE_DOWNLOAD_FAILED

**Type:** error
**Code:** FILE_DOWNLOAD_FAILED

Failed to download file from `{{url}}`

{{#status}}HTTP {{status}}: {{statusText}}{{/status}}
{{#error}}Error: {{error}}{{/error}}

**Suggestions:**
- Verify the URL is correct and accessible
- Check your network connection
- Ensure the server is responding

---

## INVALID_FILENAME

**Type:** error
**Code:** INVALID_FILENAME

**ERROR:** Invalid filename `{{filename}}`

Reason: {{reason}}

Please use a valid filename without path separators or special characters.

---

## FILE_TOO_LARGE

**Type:** error
**Code:** FILE_TOO_LARGE

**ERROR:** File is too large to download

The file at `{{url}}` is {{size}}, which exceeds the maximum allowed size of {{maxSize}}.

For security and performance reasons, files larger than {{maxSize}} cannot be downloaded automatically.

---

## FILE_QUARANTINED

**Type:** error
**Code:** FILE_QUARANTINED

**WARNING:** File has been quarantined due to security concerns

**File:** `{{filename}}`
**Reason:** {{reason}}
**Size:** {{size}}
**Content-Type:** {{contentType}}
**Quarantine Location:** `{{quarantinePath}}`

The file was downloaded but renamed with a `.quarantined` extension and moved to quarantine to prevent accidental execution. If you trust this file, you can manually rename and move it from the quarantine location.

---

## FILE_SAVE_FAILED

**Type:** error
**Code:** FILE_SAVE_FAILED

**ERROR:** Failed to save file to disk

The file was downloaded successfully but could not be saved to `{{filepath}}`

Error: {{error}}

**Possible causes:**
- Disk is full
- No write permission to the directory
- File system error

---

## FILE_DOWNLOAD_NETWORK_ERROR

**Type:** error
**Code:** FILE_DOWNLOAD_NETWORK_ERROR

**ERROR:** Network error while downloading file

Failed to connect to `{{url}}`

Error: {{error}}

**Suggestions:**
- Check your internet connection
- Verify the URL is accessible
- Ensure the server is online

---

## PDF_SAVED

**Type:** success
**Code:** PDF_SAVED

PDF saved successfully to `{{filepath}}`
File size: {{fileSize}}
{{#engine}}Engine: {{engine}}{{/engine}}
{{#version}}Version: {{version}}{{/version}}

---

## PDF_GENERATED

**Type:** success
**Code:** PDF_GENERATED

PDF generated successfully
Size: {{size}}

{{note}}

---

## PDF_GENERATION_FAILED

**Type:** error
**Code:** PDF_GENERATION_FAILED

**ERROR:** Failed to generate PDF

Error: {{error}}

---

## WEASYPRINT_NOT_FOUND

**Type:** error
**Code:** WEASYPRINT_NOT_FOUND

**ERROR:** WeasyPrint is not installed or not found in PATH

WeasyPrint is required for advanced PDF generation with superior CSS page break support.

**Suggestions:**
- Install WeasyPrint: `pip install weasyprint`
- Verify installation: `weasyprint --version`
- Ensure WeasyPrint is in your system PATH
- Use `printToPDF` tool for basic PDF generation with Chrome instead

**Note:** WeasyPrint requires Python 3.7+ and additional system dependencies (Cairo, Pango, GdkPixbuf). See https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation

Error: {{error}}

---

## WEASYPRINT_EXECUTION_FAILED

**Type:** error
**Code:** WEASYPRINT_EXECUTION_FAILED

**ERROR:** WeasyPrint failed to generate PDF

The WeasyPrint process encountered an error during PDF generation.

Error: {{error}}

**Suggestions:**
- Check HTML/CSS syntax for errors
- Verify all referenced resources (images, stylesheets) are accessible
- Check WeasyPrint logs for detailed error information
- Try the `printToPDF` tool for basic PDF generation with Chrome instead

---

## Replay Messages

## REPLAY_HISTORY

**Type:** success
**Summary:** Command history

Showing {{count}} of {{totalCount}} commands

---

## REPLAY_HISTORY_EMPTY

**Type:** info
**Summary:** Command history empty

No commands recorded yet. All tool calls are automatically recorded.

---

## REPLAY_SAVED_LIST

**Type:** list
**Summary:** {{count}} saved sequence(s)

---

## REPLAY_SAVED_EMPTY

**Type:** info
**Summary:** No saved sequences

No sequences saved to disk yet.

Location: `.cdp-tools/sequences/`

---

## REPLAY_RUN_SUCCESS

**Type:** success
**Summary:** {{sequenceName}}

Completed {{successful}}/{{total}} commands in {{duration}}s

---

## REPLAY_RUN_FAILED

**Type:** error
**Summary:** {{sequenceName}}

Failed at step {{failedStep}} ({{failedTool}})

---

## REPLAY_PAUSED

**Type:** info
**Summary:** {{sequenceName}}

Paused at step {{pausedStep}} of {{total}}, {{remaining}} remaining

---

## REPLAY_SEQUENCE_CREATED

**Type:** success
**Summary:** Sequence created

Name: {{name}}, ID: {{id}}, Commands: {{commandCount}}

---

## REPLAY_SEQUENCE_DETAILS

**Type:** success
**Summary:** Sequence details

{{name}}: {{commandCount}} commands

---

## REPLAY_STEP_SUCCESS

**Type:** success
**Summary:** {{sequenceName}}

Executed {{stepCount}} step(s), {{remaining}} remaining

---

## REPLAY_STEP_COMPLETE

**Type:** success
**Summary:** {{sequenceName}}

All {{total}} steps executed successfully

---

## REPLAY_BREAKPOINT_HIT

**Type:** info
**Summary:** {{sequenceName}}

Breakpoint hit at {{location}}

---

## REPLAY_SEQUENCE_LIST

**Type:** list
**Summary:** {{count}} sequence(s) in memory

---

## REPLAY_SEQUENCE_LIST_EMPTY

**Type:** info
**Summary:** No sequences saved

No sequences saved yet in memory.

---

## REPLAY_ACTIVE_STATUS

**Type:** info
**Summary:** {{sequenceName}}

Paused at step {{currentStep}} of {{totalSteps}}

---

## REPLAY_STEP_FAILED

**Type:** error
**Summary:** Step failed

{{sequenceName}}: Failed at step {{failedStep}} ({{failedTool}})

---

## REPLAY_INSERT_PROMPT

**Type:** info
**Summary:** Insert commands

{{sequenceName}}: {{commandCount}} command(s) available to insert

---

## REPLAY_INSERT_SUCCESS

**Type:** success
**Summary:** Commands inserted

{{sequenceName}}: Inserted {{insertedCount}} command(s) after step {{insertAfter}}

---

## REPLAY_INSERT_NEW

**Type:** success
**Summary:** New sequence created

{{sequenceName}}: Created with {{insertedCount}} inserted command(s)

---

## REPLAY_DEBUG_STATE

**Type:** info
**Summary:** Debug state

Execution paused at {{location}}

---

## REPLAY_VARIABLE_PROMPT

**Type:** info
**Summary:** Variables found

{{sequenceName}}: {{variableCount}} customizable parameter(s)

---

## REPLAY_NO_COMMANDS_SINCE_PAUSE

**Type:** info
**Summary:** No commands to insert

No commands recorded since pause. Run some commands first.

---

## RECORDING_STARTED

**Type:** success

Command recording started. All tool calls will be recorded until you stop.

---

## RECORDING_STOPPED

**Type:** success

Recording stopped with {{commandCount}} commands (not saved). Provide sequenceName to save.

---

## SEQUENCE_SAVED

**Type:** success

Sequence "{{name}}" saved successfully!

**Sequence ID:** `{{sequenceId}}`
**Commands:** {{commandCount}}

---

## SEQUENCE_DELETED

**Type:** success

Sequence `{{sequenceId}}` deleted successfully.

---

## ALREADY_RECORDING

**Type:** error
**Code:** ALREADY_RECORDING

Already recording. Stop current recording first with `replay({ action: 'stopRecording' })`.

---

## NOT_RECORDING

**Type:** error
**Code:** NOT_RECORDING

Not currently recording. Start recording first with `replay({ action: 'startRecording' })`.

---

## NO_COMMANDS_RECORDED

**Type:** error
**Code:** NO_COMMANDS_RECORDED

No commands were recorded in this session.

---

## SEQUENCE_NOT_FOUND

**Type:** error
**Code:** SEQUENCE_NOT_FOUND

{{#message}}{{message}}{{/message}}{{^message}}Sequence `{{sequenceId}}` not found. Use `replay({ action: 'list' })` to see available sequences or `replay({ action: 'listSaved' })` to see saved files.{{/message}}

---

## NO_MATCHING_COMMANDS

**Type:** error
**Code:** NO_MATCHING_COMMANDS

No commands matched the provided IDs.

**Provided IDs:** {{providedIds}}

---

## SEQUENCE_SAVED_TO_DISK

**Type:** success

Sequence saved to disk successfully!

**Filename:** `{{filename}}`
**Location:** `.cdp-tools/sequences/`

---

## LOAD_FAILED

**Type:** error
**Code:** LOAD_FAILED

Failed to load sequence from disk.

**Filename:** `{{filename}}`
**Error:** {{error}}

**Suggestions:**
- Verify the filename is correct
- Check that the file exists in `.cdp-tools/sequences/`
- Use `replay({ action: 'listSaved' })` to see available files

---

## SEQUENCE_LOADED_FROM_DISK

**Type:** success

Sequence loaded.

**Sequence ID:** `{{sequenceId}}`
**Name:** {{name}}
**Commands:** {{commandCount}}

---

## SEQUENCE_LOADED_INTO_HISTORY

**Type:** success

Loaded {{commandCount}} commands from "{{name}}" into history.

Use `replay({ action: 'history' })` to view commands.

---

## SAVED_SEQUENCE_DELETED

**Type:** success

Sequence file "{{filename}}" deleted successfully.

---

## MISSING_CONNECTION

**Type:** error
**Code:** MISSING_CONNECTION

{{message}}

**Tools needing connection:** {{toolsNeedingConnection}}

{{suggestion}}

---

## MISSING_PARAMETER

**Type:** error
**Code:** MISSING_PARAMETER

Missing required parameter: {{missing}}

**Action:** {{action}}
**Message:** {{message}}

---

## Server Messages

## SERVER_START_SUCCESS

**Type:** success
**Summary:** Server started and ready

{{id}} (PID: {{pid}}){{#port}}, Port: {{port}}{{/port}}{{#autoRun}}, Auto-run: enabled{{/autoRun}}

Logs: server({ action: "logs", serverId: "{{id}}" })

---

## SERVER_STOP_SUCCESS

**Type:** success

Server `{{serverId}}` stopped.

---

## SERVER_RESTART_SUCCESS

**Type:** success
**Summary:** Server restarted and ready

{{id}} (PID: {{pid}}){{#port}}, Port: {{port}}{{/port}}{{#autoRun}}, Auto-run: enabled{{/autoRun}}

---

## SERVER_LIST_SUCCESS

**Type:** success

{{count}} server(s) ({{runningCount}} running, {{stoppedCount}} stopped)

{{serverList}}

**Actions:**
- Stop: `server({ action: "stop", serverId: "<id>" })`
- Restart: `server({ action: "restart", serverId: "<id>" })`
- Logs: `server({ action: "logs", serverId: "<id>" })`

---

## SERVER_LIST_EMPTY

**Type:** success

No servers running.

Use `server({ action: "start", command: "<cmd>", cwd: "<dir>", id: "<name>" })` to start a server.

---

## SERVER_LOGS_SUCCESS

**Type:** success

**Logs for `{{serverId}}`** ({{lineCount}} lines{{#isDelta}}, new since last view{{/isDelta}})

{{#running}}🟢 Running{{/running}}{{^running}}🔴 Stopped{{/running}}{{#autoRun}} ⚡{{/autoRun}}
{{#port}}**Port:** {{port}}{{/port}}
{{#uptime}}**Uptime:** {{uptime}}{{/uptime}}

{{logs}}

---

## SERVER_LOGS_EMPTY

**Type:** success

**Logs for `{{serverId}}`**

{{#running}}🟢 Running{{/running}}{{^running}}🔴 Stopped{{/running}}{{#autoRun}} ⚡{{/autoRun}}

_No {{#isDelta}}new {{/isDelta}}log output._

---

## SERVER_STOP_ALL_SUCCESS

**Type:** success

Stopped {{count}} server(s): {{serverIds}}

---

## SERVER_STOP_ALL_EMPTY

**Type:** success

No servers were running.

---

## SERVER_AUTORUN_ENABLED

**Type:** success

Auto-run enabled for `{{serverId}}`.

Server will automatically start when MCP server starts.

---

## SERVER_AUTORUN_DISABLED

**Type:** success

Auto-run disabled for `{{serverId}}`.

Server will not auto-start when MCP server starts.

---

## SERVER_NOT_FOUND

**Type:** error
**Code:** SERVER_NOT_FOUND

Server `{{serverId}}` not found.

**Suggestions:**
- Use `server({ action: "list" })` to see running servers
- Check the server ID you provided when starting the server

---

## SERVER_ALREADY_RUNNING

**Type:** error
**Code:** SERVER_ALREADY_RUNNING

Server `{{serverId}}` is already running (PID: {{pid}}).

**Suggestions:**
- Use `server({ action: "stop", serverId: "{{serverId}}" })` to stop it first
- Use `server({ action: "restart", serverId: "{{serverId}}" })` to restart it

---

## SERVER_START_FAILED

**Type:** error
**Code:** SERVER_START_FAILED

Failed to start server: {{error}}

**Suggestions:**
- Check that the working directory (cwd) exists
- Verify the command is correct
- Check for port conflicts

---

## SERVER_MISSING_COMMAND

**Type:** error
**Code:** MISSING_PARAMETER

Missing required parameter: `command`

Provide the command to run (e.g., "npm run dev", "flask run", "python manage.py runserver").

---

## SERVER_MISSING_CWD

**Type:** error
**Code:** MISSING_PARAMETER

Missing required parameter: `cwd`

Provide the working directory for the server command.

---

## SERVER_MISSING_ID

**Type:** error
**Code:** MISSING_PARAMETER

Missing required parameter: `id`

Provide a unique identifier for this server (e.g., "flask-api", "next-frontend").

---

## SERVER_MISSING_SERVER_ID

**Type:** error
**Code:** MISSING_PARAMETER

Missing required parameter: `serverId`

Use `server({ action: "list" })` to see running servers.

---

## SERVER_MISSING_AUTORUN

**Type:** error
**Code:** MISSING_PARAMETER

Missing required parameter: `autoRun`

Set to `true` to enable auto-start on MCP startup, or `false` to disable.

---

## SERVER_LOGS_CLEARED

**Type:** success

Logs cleared for `{{serverId}}`.

**Log directory:** `{{logDir}}`

---

## SERVER_REMOVED

**Type:** success

Server `{{serverId}}` removed from config.

---

## Port Monitoring Messages

## PORT_MONITOR_STARTED

**Type:** success
**Summary:** Port monitoring started

Now monitoring port {{port}} at level `{{level}}`{{#description}} ({{description}}){{/description}}{{#interval}} with custom interval {{interval}}ms{{/interval}}.

The port will be checked via TCP connection probes. If the port goes down, tool responses will be affected based on the monitoring level:
- `inform`: Info line prepended to responses
- `error`: Error line prepended to responses
- `block`: All tools blocked until acknowledged

**Default intervals:** block=1000ms, error=2000ms, inform=5000ms (configurable in `.cdp-tools/config.json`)

---

## PORT_MONITOR_STOPPED

**Type:** success
**Summary:** Port monitoring stopped

Stopped monitoring port {{port}}.

---

## PORT_MONITOR_LIST

**Type:** list
**Summary:** {{count}} monitored port(s)

**Up:** {{upCount}} | **Down:** {{downCount}} | **Connecting:** {{connectingCount}}

{{portList}}

---

## PORT_MONITOR_LIST_EMPTY

**Type:** success

No ports are currently being monitored.

Use `server({ action: 'monitorPort', port: <port>, monitoringLevel: 'inform'|'error'|'block' })` to start monitoring.

---

## PORT_ACKNOWLEDGED

**Type:** success
**Summary:** Port failure acknowledged

Acknowledged failure for port {{port}}. Tool execution will now continue.

**Note:** The port is still being monitored. If it comes back up and fails again, you will need to acknowledge again.

---

## PORT_MISSING_PORT

**Type:** error
**Code:** MISSING_PORT

Port number is required.

**Example:**
```
server({ action: 'monitorPort', port: 3000, monitoringLevel: 'error' })
```

---

## PORT_MISSING_LEVEL

**Type:** error
**Code:** MISSING_LEVEL

Monitoring level is required. Choose one of: `inform`, `error`, or `block`.

- `inform`: Info line prepended to tool responses when port is down
- `error`: Error line prepended to tool responses when port is down
- `block`: All tools blocked until failure is acknowledged

**Example:**
```
server({ action: 'monitorPort', port: 3000, monitoringLevel: 'block' })
```

---

## PORT_NOT_MONITORED

**Type:** error
**Code:** NOT_MONITORED

Port {{port}} is not being monitored.

Use `server({ action: 'listMonitored' })` to see all monitored ports.

---

## PORT_ACK_FAILED

**Type:** error
**Code:** ACK_FAILED

Cannot acknowledge port {{port}}. Either the port is not being monitored, or it is not currently in a failed state.

Use `server({ action: 'listMonitored' })` to check the current status of monitored ports.

---