firefox-devtools-mcp 0.2.0

package/dist/snapshot.injected.global.js

@@ -0,0 +1 @@
+"use strict";var __SnapshotInjected=(()=>{var h=Object.defineProperty;var W=Object.getOwnPropertyDescriptor;var V=Object.getOwnPropertyNames;var U=Object.prototype.hasOwnProperty;var q=(t,r)=>{for(var e in r)h(t,e,{get:r[e],enumerable:!0})},z=(t,r,e,i)=>{if(r&&typeof r=="object"||typeof r=="function")for(let o of V(r))!U.call(t,o)&&o!==e&&h(t,o,{get:()=>r[o],enumerable:!(i=W(r,o))||i.enumerable});return t};var B=t=>z(h({},"__esModule",{value:!0}),t);var rt={};q(rt,{createSnapshot:()=>P});var v=["a","button","input","select","textarea","img","video","audio","iframe"],J=["nav","main","section","article","header","footer"],K=["div","span","p","li","ul","ol"];function L(t){if(!t||t.nodeType!==Node.ELEMENT_NODE)return!1;try{let e=window.getComputedStyle(t);if(e.display==="none"||e.visibility==="hidden"||e.opacity==="0")return!1}catch{return!1}let r=t.tagName.toLowerCase();if(v.indexOf(r)!==-1||t.hasAttribute("role")||t.hasAttribute("aria-label")||/^h[1-6]$/.test(r)||J.indexOf(r)!==-1)return!0;if(K.indexOf(r)!==-1){let e=(t.textContent||"").trim();if(e.length>0&&e.length<500||t.id||t.className)return!0}return!1}function M(t){if(t.tabIndex>=0)return!0;let e=t.tagName.toLowerCase();return["a","button","input","select","textarea"].indexOf(e)!==-1}function O(t){let r=t.tagName.toLowerCase();if(v.indexOf(r)!==-1)return!0;let e=t.getAttribute("role");return!!(e&&["button","link","menuitem","tab"].indexOf(e)!==-1||t.hasAttribute("onclick"))}var Q=100;function k(t){if(t.hasAttribute("aria-label"))return t.getAttribute("aria-label")||void 0;let e=t.id;if(e){let o=document.querySelector(`label[for="${e}"]`);if(o?.textContent)return o.textContent.trim()}if(t.hasAttribute("placeholder"))return t.getAttribute("placeholder")||void 0;if(t.hasAttribute("title"))return t.getAttribute("title")||void 0;if(t.hasAttribute("alt"))return t.getAttribute("alt")||void 0;let i=t.tagName.toLowerCase();if(["button","a","h1","h2","h3","h4","h5","h6"].indexOf(i)!==-1)return g(t)}function g(t){let r="";for(let i=0;i<t.childNodes.length;i++){let o=t.childNodes[i];o&&o.nodeType===Node.TEXT_NODE&&(r+=o.textContent||"")}let e=r.trim();if(e)return e.substring(0,Q)}function $(t){let r={},e=!1,i=["disabled","hidden","selected","expanded"];for(let a of i){let n=t.getAttribute(`aria-${a}`);n!==null&&(r[a]=n==="true",e=!0)}let o=["checked","pressed"];for(let a of o){let n=t.getAttribute(`aria-${a}`);n!==null&&(n==="mixed"?r[a]="mixed":r[a]=n==="true",e=!0)}let l=["autocomplete","haspopup","invalid","label","labelledby","describedby","controls"];for(let a of l){let n=t.getAttribute(`aria-${a}`);n&&(r[a]=n,e=!0)}let s=t.getAttribute("aria-level");if(s){let a=parseInt(s,10);isNaN(a)||(r.level=a,e=!0)}return e?r:void 0}function I(t){let r={};try{let e=window.getComputedStyle(t);r.visible=e.display!=="none"&&e.visibility!=="hidden"&&e.opacity!=="0"}catch{r.visible=!1}return r.accessible=r.visible&&!t.getAttribute("aria-hidden"),r.focusable=M(t),r.interactive=O(t),r}var Y=["id","data-testid","data-test-id"];function R(t){let r=[],e=t;for(;e&&e.nodeType===Node.ELEMENT_NODE;){let i=e.nodeName.toLowerCase(),o=!1;for(let n of Y){let u=e.getAttribute(n);if(u){n==="id"?i+="#"+CSS.escape(u):i+=`[${n}="${X(u)}"]`,r.unshift(i),o=!0;break}}if(o)break;let l=e.getAttribute("aria-label"),s=e.getAttribute("role");if(l&&s){i+=`[role="${s}"][aria-label="${X(l)}"]`,r.unshift(i),e=e.parentElement;continue}let a=e.parentElement?.children;if(a&&a.length>1){let n=1;for(let u=0;u<a.length;u++){let d=a[u];if(d){if(d===e)break;d.nodeName===e.nodeName&&n++}}(n>1||a.length>1&&a[0]!==e)&&(i+=`:nth-of-type(${n})`)}if(r.unshift(tt(i)),e=e.parentElement,e&&e.nodeName.toLowerCase()==="body"){r.unshift("body");break}}return r.join(" > ")}function G(t){let r=t.id;if(r)return`//*[@id="${Z(r)}"]`;let e=[],i=t;for(;i&&i.nodeType===Node.ELEMENT_NODE;){let o=i.nodeName.toLowerCase(),l=1,s=i.previousElementSibling;for(;s;)s.nodeName.toLowerCase()===o&&l++,s=s.previousElementSibling;let a=i.parentElement,n=!1;a&&(n=Array.from(a.children).filter(E=>E.nodeName.toLowerCase()===o).length>1);let u=n?`${o}[${l}]`:o;if(e.unshift(u),i=i.parentElement,i&&i.nodeName.toLowerCase()==="html"){e.unshift("html");break}}return"/"+e.join("/")}function X(t){return t.replace(/"/g,'\\"').substring(0,64)}function Z(t){return t.indexOf('"')===-1||t.indexOf("'")===-1?t:`concat(${t.split('"').map((e,i,o)=>i===o.length-1?e?`"${e}"`:"":e?`"${e}",'"'`:`"'"`).filter(e=>e).join(",")})`}function tt(t){return t.length<=64?t:t.substring(0,64)}var et=10,H=1e3;function D(t,r,e=!0){let i=0,o=[],l=!1;function s(n,u){if(u>et||i>=H)return l=!0,null;let d=n.tagName.toLowerCase();if(!(d==="body"||d==="html")&&!L(n))return null;let A=`${r}_${i++}`,j=R(n),F=G(n);o.push({uid:A,css:j,xpath:F});let b=n,N=n.getAttribute("role"),T=k(n),y=g(n),x=b.value,C=b.href,S=b.src,w=$(n),_=I(n),c={uid:A,tag:d,...N&&{role:N},...T&&{name:T},...x&&{value:x},...C&&{href:C},...S&&{src:S},...y&&{text:y},...w&&{aria:w},..._&&{computed:_},children:[]};if(d==="iframe"&&e){try{let f=n,p=f.contentDocument||f.contentWindow?.document;if(p?.body){let m=s(p.body,u+1);m&&(m.isIframe=!0,m.frameSrc=f.src,c.children.push(m))}else c.isIframe=!0,c.frameSrc=f.src,c.crossOrigin=!0}catch{c.isIframe=!0,c.frameSrc=n.src,c.crossOrigin=!0}return c}for(let f=0;f<n.children.length;f++){if(i>=H){l=!0;break}let p=n.children[f];if(!p)continue;let m=s(p,u+1);m&&c.children.push(m)}return c}return{tree:s(t,0),uidMap:o,truncated:l}}function P(t){try{let r=D(document.body,t,!0);if(!r.tree)throw new Error("Failed to generate tree");return r}catch{return{tree:null,uidMap:[],truncated:!1}}}typeof window<"u"&&(window.__createSnapshot=P);return B(rt);})();

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "firefox-devtools-mcp",
+  "version": "0.2.0",
+  "description": "Model Context Protocol (MCP) server for Firefox DevTools automation",
+  "author": "freema",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "firefox-devtools-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "setup": "node scripts/setup-mcp-config.js",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "check": "npm run lint:fix && npm run typecheck",
+    "check:all": "npm run check && npm run test:run && npm run build",
+    "prepublishOnly": "npm run clean && npm run build",
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "inspector:dev": "NODE_ENV=development npx @modelcontextprotocol/inspector npx tsx src/index.ts",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest watch",
+    "test:ui": "vitest --ui",
+    "test:tools": "node scripts/test-bidi-devtools.js",
+    "test:input": "node scripts/test-input-tools.js",
+    "test:screenshot": "node scripts/test-screenshot.js",
+    "test:dialog": "node scripts/test-dialog.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "firefox",
+    "firefox-devtools",
+    "browser-automation",
+    "webdriver-bidi",
+    "selenium",
+    "devtools",
+    "browser-testing",
+    "web-automation",
+    "claude",
+    "claude-ai",
+    "ai-agent",
+    "llm"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.1",
+    "ws": "^8.18.3",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "@types/selenium-webdriver": "^4.35.1",
+    "@types/ws": "^8.18.1",
+    "@types/yargs": "^17.0.32",
+    "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "@typescript-eslint/parser": "^6.21.0",
+    "@vitest/coverage-v8": "^3.1.4",
+    "@vitest/ui": "^3.1.4",
+    "dotenv": "^17.2.1",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-plugin-prettier": "^5.4.0",
+    "geckodriver": "^6.0.2",
+    "prettier": "^3.5.3",
+    "selenium-webdriver": "^4.36.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "scripts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freema/firefox-devtools-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/freema/firefox-devtools-mcp/issues"
+  },
+  "homepage": "https://github.com/freema/firefox-devtools-mcp#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/_helpers/page-loader.js

@@ -0,0 +1,121 @@
+/**
+ * Offline test helpers for loading HTML without external dependencies
+ */
+
+/**
+ * Load HTML into Firefox using about:blank + innerHTML injection
+ * This avoids data: URL parsing issues and works offline
+ *
+ * @param {FirefoxDevTools} firefox - Firefox client instance
+ * @param {string} htmlWithScript - HTML content (can include <script> tags)
+ * @returns {Promise<void>}
+ */
+export async function loadHTML(firefox, htmlWithScript) {
+  // Extract all <script> tags and their content
+  const scriptMatches = [...htmlWithScript.matchAll(/<script>([\s\S]*?)<\/script>/g)];
+  const htmlWithoutScript = htmlWithScript.replace(/<script>[\s\S]*?<\/script>/g, '');
+
+  await firefox.navigate('about:blank');
+  await waitShort();
+
+  // Set HTML (without script tags)
+  await firefox.evaluate(`document.documentElement.innerHTML = \`${htmlWithoutScript}\`;`);
+
+  // Execute all scripts in order
+  for (const match of scriptMatches) {
+    if (match[1]) {
+      await firefox.evaluate(match[1]);
+    }
+  }
+
+  await waitShort();
+}
+
+/**
+ * Short deterministic wait (setTimeout for Node.js test context)
+ * More reliable than arbitrary long waits
+ *
+ * @param {number} ms - Milliseconds to wait (default: 300)
+ * @returns {Promise<void>}
+ */
+export async function waitShort(ms = 300) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Wait for browser frame update (uses requestAnimationFrame in browser)
+ *
+ * @param {FirefoxDevTools} firefox - Firefox client instance
+ * @returns {Promise<void>}
+ */
+export async function waitForFrame(firefox) {
+  await firefox.evaluate(() => {
+    return new Promise((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(resolve));
+    });
+  });
+}
+
+/**
+ * Wait for element to appear in DOM
+ *
+ * @param {FirefoxDevTools} firefox - Firefox client instance
+ * @param {string} selector - CSS selector
+ * @param {number} timeout - Max wait time in ms (default: 5000)
+ * @returns {Promise<boolean>} - true if element found, false on timeout
+ */
+export async function waitForElement(firefox, selector, timeout = 5000) {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeout) {
+    // Pass selector as argument instead of template literal to avoid injection
+    const exists = await firefox.evaluate(
+      (sel) => !!document.querySelector(sel),
+      selector
+    );
+    if (exists) {
+      return true;
+    }
+    await waitShort(100);
+  }
+
+  return false;
+}
+
+/**
+ * Wait for condition to be true
+ *
+ * @param {FirefoxDevTools} firefox - Firefox client instance
+ * @param {string} condition - JavaScript expression to evaluate
+ * @param {number} timeout - Max wait time in ms (default: 5000)
+ * @returns {Promise<boolean>} - true if condition met, false on timeout
+ */
+export async function waitForCondition(firefox, condition, timeout = 5000) {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeout) {
+    const result = await firefox.evaluate(`return (${condition})`);
+    if (result) {
+      return true;
+    }
+    await waitShort(100);
+  }
+
+  return false;
+}
+
+/**
+ * Check if online tests should run
+ * @returns {boolean}
+ */
+export function shouldRunOnlineTests() {
+  return process.env.TEST_ONLINE === '1';
+}
+
+/**
+ * Skip message for online tests
+ * @param {string} testName - Name of the test being skipped
+ */
+export function skipOnlineTest(testName) {
+  console.log(`⏭️  Skipping ${testName} (offline mode - set TEST_ONLINE=1 to enable)\n`);
+}

package/scripts/demo-server.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * Simple demo server for testing MCP tools
+ * Serves a page with console logs, dialogs, and interactive elements
+ */
+
+import http from 'http';
+
+const PORT = 3456;
+
+const HTML_PAGE = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>MCP - Demo Page</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      max-width: 800px;
+      margin: 50px auto;
+      padding: 20px;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: white;
+    }
+    .container {
+      background: rgba(255, 255, 255, 0.1);
+      backdrop-filter: blur(10px);
+      border-radius: 16px;
+      padding: 30px;
+      box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+    }
+    h1 {
+      margin-top: 0;
+      font-size: 2.5rem;
+    }
+    .section {
+      margin: 30px 0;
+      padding: 20px;
+      background: rgba(255, 255, 255, 0.1);
+      border-radius: 12px;
+    }
+    button {
+      background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+      border: none;
+      color: white;
+      padding: 12px 24px;
+      font-size: 16px;
+      border-radius: 8px;
+      cursor: pointer;
+      margin: 5px;
+      transition: transform 0.2s;
+      font-weight: 600;
+    }
+    button:hover {
+      transform: scale(1.05);
+    }
+    button:active {
+      transform: scale(0.95);
+    }
+    input {
+      padding: 10px;
+      border-radius: 6px;
+      border: 2px solid rgba(255, 255, 255, 0.3);
+      background: rgba(255, 255, 255, 0.2);
+      color: white;
+      font-size: 16px;
+      margin: 5px;
+    }
+    input::placeholder {
+      color: rgba(255, 255, 255, 0.6);
+    }
+    .console-output {
+      background: rgba(0, 0, 0, 0.3);
+      padding: 15px;
+      border-radius: 8px;
+      font-family: 'Monaco', 'Consolas', monospace;
+      font-size: 14px;
+      margin-top: 10px;
+      max-height: 200px;
+      overflow-y: auto;
+    }
+    .log { color: #4ade80; }
+    .info { color: #60a5fa; }
+    .warn { color: #fbbf24; }
+    .error { color: #f87171; }
+    .debug { color: #a78bfa; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>🦊 Firefox DevTools MCP</h1>
+    <p><strong>Demo Page for Testing MCP Tools</strong></p>
+    <p>Use this page with the MCP Inspector to test various tools!</p>
+
+    <div class="section">
+      <h2>📝 Console Logs</h2>
+      <button onclick="generateLogs()">Generate All Log Types</button>
+      <button onclick="generateManyLogs()">Generate 50 Logs</button>
+      <button onclick="logObject()">Log Object</button>
+      <button onclick="logArray()">Log Array</button>
+      <button onclick="console.clear()">Clear Console</button>
+    </div>
+
+    <div class="section">
+      <h2>💬 Dialogs</h2>
+      <button onclick="testAlert()">Show Alert</button>
+      <button onclick="testConfirm()">Show Confirm</button>
+      <button onclick="testPrompt()">Show Prompt</button>
+    </div>
+
+    <div class="section">
+      <h2>⌨️ Input Elements</h2>
+      <input type="text" id="testInput" placeholder="Type something here...">
+      <button onclick="showInputValue()">Show Input Value</button>
+      <button onclick="clearInput()">Clear Input</button>
+    </div>
+
+    <div class="section">
+      <h2>🔄 Page Actions</h2>
+      <button onclick="location.reload()">Reload Page</button>
+      <button onclick="window.open('about:blank', '_blank')">Open New Tab</button>
+      <button onclick="navigateToExample()">Navigate to Example.com</button>
+    </div>
+
+    <div class="section">
+      <h2>🎯 Clickable Elements</h2>
+      <button id="clickCounter" onclick="incrementCounter()">Click Counter: 0</button>
+      <button onclick="changeBackground()">Change Background</button>
+    </div>
+
+    <div class="section">
+      <h2>📊 Live Console Output</h2>
+      <div class="console-output" id="consoleOutput">
+        Console logs will appear here...
+      </div>
+    </div>
+  </div>
+
+  <script>
+    let clickCount = 0;
+    const colors = ['#667eea', '#764ba2', '#f093fb', '#f5576c', '#4ade80', '#60a5fa'];
+    let colorIndex = 0;
+
+    // Intercept console methods to show in page
+    const originalLog = console.log;
+    const originalInfo = console.info;
+    const originalWarn = console.warn;
+    const originalError = console.error;
+    const originalDebug = console.debug;
+
+    function addToOutput(message, type) {
+      const output = document.getElementById('consoleOutput');
+      const line = document.createElement('div');
+      line.className = type;
+      line.textContent = '[' + type.toUpperCase() + '] ' + message;
+      output.appendChild(line);
+      output.scrollTop = output.scrollHeight;
+    }
+
+    console.log = function(...args) {
+      originalLog.apply(console, args);
+      addToOutput(args.join(' '), 'log');
+    };
+
+    console.info = function(...args) {
+      originalInfo.apply(console, args);
+      addToOutput(args.join(' '), 'info');
+    };
+
+    console.warn = function(...args) {
+      originalWarn.apply(console, args);
+      addToOutput(args.join(' '), 'warn');
+    };
+
+    console.error = function(...args) {
+      originalError.apply(console, args);
+      addToOutput(args.join(' '), 'error');
+    };
+
+    console.debug = function(...args) {
+      originalDebug.apply(console, args);
+      addToOutput(args.join(' '), 'debug');
+    };
+
+    // Console log functions
+    function generateLogs() {
+      console.log('This is a log message');
+      console.info('This is an info message');
+      console.warn('This is a warning message');
+      console.error('This is an error message');
+      console.debug('This is a debug message');
+    }
+
+    function generateManyLogs() {
+      for (let i = 0; i < 50; i++) {
+        const types = ['log', 'info', 'warn', 'error', 'debug'];
+        const type = types[i % types.length];
+        console[type]('Message #' + (i + 1) + ' - ' + type);
+      }
+    }
+
+    function logObject() {
+      console.log('Object:', {
+        name: 'Firefox DevTools MCP',
+        version: '0.1.0',
+        features: ['console', 'dialog', 'input', 'screenshot'],
+        config: { headless: false, timeout: 5000 }
+      });
+    }
+
+    function logArray() {
+      console.log('Array:', [1, 2, 3, 'four', { five: 5 }, [6, 7, 8]]);
+    }
+
+    // Dialog functions
+    function testAlert() {
+      alert('This is an alert dialog! 🚨');
+      console.info('Alert dialog was shown');
+    }
+
+    function testConfirm() {
+      const result = confirm('Do you want to continue? 🤔');
+      console.log('Confirm result:', result);
+    }
+
+    function testPrompt() {
+      const result = prompt('What is your favorite color? 🎨');
+      console.log('Prompt result:', result);
+    }
+
+    // Input functions
+    function showInputValue() {
+      const value = document.getElementById('testInput').value;
+      console.log('Input value:', value);
+      alert('Input value: ' + value);
+    }
+
+    function clearInput() {
+      document.getElementById('testInput').value = '';
+      console.info('Input cleared');
+    }
+
+    // Page actions
+    function navigateToExample() {
+      console.info('Navigating to example.com...');
+      window.location.href = 'https://example.com';
+    }
+
+    // Clickable elements
+    function incrementCounter() {
+      clickCount++;
+      document.getElementById('clickCounter').textContent = 'Click Counter: ' + clickCount;
+      console.log('Button clicked! Count:', clickCount);
+    }
+
+    function changeBackground() {
+      colorIndex = (colorIndex + 1) % colors.length;
+      document.body.style.background = 'linear-gradient(135deg, ' + colors[colorIndex] + ' 0%, ' + colors[(colorIndex + 1) % colors.length] + ' 100%)';
+      console.log('Background changed to:', colors[colorIndex]);
+    }
+
+    // Initial log
+    console.log('🦊 Firefox DevTools MCP Demo Page Loaded!');
+    console.info('Server running on http://localhost:3456');
+    console.info('Use MCP Inspector to test tools: list_console_messages, list_pages, etc.');
+  </script>
+</body>
+</html>
+`;
+
+const server = http.createServer((req, res) => {
+  if (req.url === '/') {
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(HTML_PAGE);
+  } else if (req.url === '/health') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ status: 'ok', timestamp: new Date().toISOString() }));
+  } else {
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+  }
+});
+
+server.listen(PORT, () => {
+  console.log('');
+  console.log('🦊 Firefox DevTools MCP - Demo Server');
+  console.log('=====================================');
+  console.log('');
+  console.log(`🌐 Server running at: http://localhost:${PORT}`);
+  console.log('');
+  console.log('📋 Available endpoints:');
+  console.log(`   http://localhost:${PORT}/        - Demo page`);
+  console.log(`   http://localhost:${PORT}/health  - Health check`);
+  console.log('');
+  console.log('💡 Usage with MCP Inspector:');
+  console.log('   1. Start this server (already running)');
+  console.log(`   2. Open MCP Inspector: npm run inspector`);
+  console.log(`   3. Use tool: new_page with url "http://localhost:${PORT}"`);
+  console.log('   4. Test tools: list_console_messages, list_pages, etc.');
+  console.log('');
+  console.log('Press Ctrl+C to stop the server');
+  console.log('');
+});
+
+server.on('error', (error) => {
+  if (error.code === 'EADDRINUSE') {
+    console.error(`❌ Port ${PORT} is already in use!\n`);
+    console.error('   Try stopping other servers or change the PORT in demo-server.js\n');
+  } else {
+    console.error('❌ Server error:', error.message);
+  }
+  process.exit(1);
+});
+
+// Graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n\n🛑 Shutting down demo server...');
+  server.close(() => {
+    console.log('✅ Server closed');
+    process.exit(0);
+  });
+});