Repository: AgentDeskAI/browser-tools-mcp Branch: main Commit: d298068137c3 Files: 26 Total size: 337.4 KB Directory structure: gitextract_uipce7r9/ ├── .gitignore ├── LICENSE ├── README.md ├── browser-tools-mcp/ │ ├── README.md │ ├── mcp-server.ts │ ├── package.json │ └── tsconfig.json ├── browser-tools-server/ │ ├── README.md │ ├── browser-connector.ts │ ├── lighthouse/ │ │ ├── accessibility.ts │ │ ├── best-practices.ts │ │ ├── index.ts │ │ ├── performance.ts │ │ ├── seo.ts │ │ └── types.ts │ ├── package.json │ ├── puppeteer-service.ts │ └── tsconfig.json ├── chrome-extension/ │ ├── background.js │ ├── devtools.html │ ├── devtools.js │ ├── manifest.json │ ├── panel.html │ └── panel.js └── docs/ ├── mcp-docs.md └── mcp.md ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitignore ================================================ node_modules dist .port .DS_Store ================================================ FILE: LICENSE ================================================ MIT License Copyright (c) 2025 AgentDesk LLC Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: README.md ================================================ THIS PROJECT IS NO LONGER ACTIVE PLEASE USE A DIFFERENT SOLUTION FOR THIS. # BrowserTools MCP > Make your AI tools 10x more aware and capable of interacting with your browser This application is a powerful browser monitoring and interaction tool that enables AI-powered applications via Anthropic's Model Context Protocol (MCP) to capture and analyze browser data through a Chrome extension. Read our [docs](https://browsertools.agentdesk.ai/) for the full installation, quickstart and contribution guides. ## Roadmap Check out our project roadmap here: [Github Roadmap / Project Board](https://github.com/orgs/AgentDeskAI/projects/1/views/1) ## Updates v1.2.0 is out! Here's a quick breakdown of the update: - You can now enable "Allow Auto-Paste into Cursor" within the DevTools panel. Screenshots will be automatically pasted into Cursor (just make sure to focus/click into the Agent input field in Cursor, otherwise it won't work!) - Integrated a suite of SEO, performance, accessibility, and best practice analysis tools via Lighthouse - Implemented a NextJS specific prompt used to improve SEO for a NextJS application - Added Debugger Mode as a tool which executes all debugging tools in a particular sequence, along with a prompt to improve reasoning - Added Audit Mode as a tool to execute all auditing tools in a particular sequence - Resolved Windows connectivity issues - Improved networking between BrowserTools server, extension and MCP server with host/port auto-discovery, auto-reconnect, and graceful shutdown mechanisms - Added ability to more easily exit out of the Browser Tools server with Ctrl+C ## Quickstart Guide There are three components to run this MCP tool: 1. Install our chrome extension from here: [v1.2.0 BrowserToolsMCP Chrome Extension](https://github.com/AgentDeskAI/browser-tools-mcp/releases/download/v1.2.0/BrowserTools-1.2.0-extension.zip) 2. Install the MCP server from this command within your IDE: `npx @agentdeskai/browser-tools-mcp@latest` 3. Open a new terminal and run this command: `npx @agentdeskai/browser-tools-server@latest` * Different IDEs have different configs but this command is generally a good starting point; please reference your IDEs docs for the proper config setup IMPORTANT TIP - there are two servers you need to install. There's... - browser-tools-server (local nodejs server that's a middleware for gathering logs) and - browser-tools-mcp (MCP server that you install into your IDE that communicates w/ the extension + browser-tools-server) `npx @agentdeskai/browser-tools-mcp@latest` is what you put into your IDE `npx @agentdeskai/browser-tools-server@latest` is what you run in a new terminal window After those three steps, open up your chrome dev tools and then the BrowserToolsMCP panel. If you're still having issues try these steps: - Quit / close down your browser. Not just the window but all of Chrome itself. - Restart the local node server (browser-tools-server) - Make sure you only have ONE instance of chrome dev tools panel open After that, it should work but if it doesn't let me know and I can share some more steps to gather logs/info about the issue! If you have any questions or issues, feel free to open an issue ticket! And if you have any ideas to make this better, feel free to reach out or open an issue ticket with an enhancement tag or reach out to me at [@tedx_ai on x](https://x.com/tedx_ai) ## Full Update Notes: Coding agents like Cursor can run these audits against the current page seamlessly. By leveraging Puppeteer and the Lighthouse npm library, BrowserTools MCP can now: - Evaluate pages for WCAG compliance - Identify performance bottlenecks - Flag on-page SEO issues - Check adherence to web development best practices - Review NextJS specific issues with SEO ...all without leaving your IDE 🎉 --- ## 🔑 Key Additions | Audit Type | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | **Accessibility** | WCAG-compliant checks for color contrast, missing alt text, keyboard navigation traps, ARIA attributes, and more. | | **Performance** | Lighthouse-driven analysis of render-blocking resources, excessive DOM size, unoptimized images, and other factors affecting page speed. | | **SEO** | Evaluates on-page SEO factors (like metadata, headings, and link structure) and suggests improvements for better search visibility. | | **Best Practices** | Checks for general best practices in web development. | | **NextJS Audit** | Injects a prompt used to perform a NextJS audit. | | **Audit Mode** | Runs all auditing tools in a sequence. | | **Debugger Mode** | Runs all debugging tools in a sequence. | --- ## 🛠️ Using Audit Tools ### ✅ **Before You Start** Ensure you have: - An **active tab** in your browser - The **BrowserTools extension enabled** ### ▶️ **Running Audits** **Headless Browser Automation**: Puppeteer automates a headless Chrome instance to load the page and collect audit data, ensuring accurate results even for SPAs or content loaded via JavaScript. The headless browser instance remains active for **60 seconds** after the last audit call to efficiently handle consecutive audit requests. **Structured Results**: Each audit returns results in a structured JSON format, including overall scores and detailed issue lists. This makes it easy for MCP-compatible clients to interpret the findings and present actionable insights. The MCP server provides tools to run audits on the current page. Here are example queries you can use to trigger them: #### Accessibility Audit (`runAccessibilityAudit`) Ensures the page meets accessibility standards like WCAG. > **Example Queries:** > > - "Are there any accessibility issues on this page?" > - "Run an accessibility audit." > - "Check if this page meets WCAG standards." #### Performance Audit (`runPerformanceAudit`) Identifies performance bottlenecks and loading issues. > **Example Queries:** > > - "Why is this page loading so slowly?" > - "Check the performance of this page." > - "Run a performance audit." #### SEO Audit (`runSEOAudit`) Evaluates how well the page is optimized for search engines. > **Example Queries:** > > - "How can I improve SEO for this page?" > - "Run an SEO audit." > - "Check SEO on this page." #### Best Practices Audit (`runBestPracticesAudit`) Checks for general best practices in web development. > **Example Queries:** > > - "Run a best practices audit." > - "Check best practices on this page." > - "Are there any best practices issues on this page?" #### Audit Mode (`runAuditMode`) Runs all audits in a particular sequence. Will run a NextJS audit if the framework is detected. > **Example Queries:** > > - "Run audit mode." > - "Enter audit mode." #### NextJS Audits (`runNextJSAudit`) Checks for best practices and SEO improvements for NextJS applications > **Example Queries:** > > - "Run a NextJS audit." > - "Run a NextJS audit, I'm using app router." > - "Run a NextJS audit, I'm using page router." #### Debugger Mode (`runDebuggerMode`) Runs all debugging tools in a particular sequence > **Example Queries:** > > - "Enter debugger mode." ## Architecture There are three core components all used to capture and analyze browser data: 1. **Chrome Extension**: A browser extension that captures screenshots, console logs, network activity and DOM elements. 2. **Node Server**: An intermediary server that facilitates communication between the Chrome extension and any instance of an MCP server. 3. **MCP Server**: A Model Context Protocol server that provides standardized tools for AI clients to interact with the browser. ``` ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ ┌─────────────┐ │ MCP Client │ ──► │ MCP Server │ ──► │ Node Server │ ──► │ Chrome │ │ (e.g. │ ◄── │ (Protocol │ ◄── │ (Middleware) │ ◄── │ Extension │ │ Cursor) │ │ Handler) │ │ │ │ │ └─────────────┘ └──────────────┘ └───────────────┘ └─────────────┘ ``` Model Context Protocol (MCP) is a capability supported by Anthropic AI models that allow you to create custom tools for any compatible client. MCP clients like Claude Desktop, Cursor, Cline or Zed can run an MCP server which "teaches" these clients about a new tool that they can use. These tools can call out to external APIs but in our case, **all logs are stored locally** on your machine and NEVER sent out to any third-party service or API. BrowserTools MCP runs a local instance of a NodeJS API server which communicates with the BrowserTools Chrome Extension. All consumers of the BrowserTools MCP Server interface with the same NodeJS API and Chrome extension. #### Chrome Extension - Monitors XHR requests/responses and console logs - Tracks selected DOM elements - Sends all logs and current element to the BrowserTools Connector - Connects to Websocket server to capture/send screenshots - Allows user to configure token/truncation limits + screenshot folder path #### Node Server - Acts as middleware between the Chrome extension and MCP server - Receives logs and currently selected element from Chrome extension - Processes requests from MCP server to capture logs, screenshot or current element - Sends Websocket command to the Chrome extension for capturing a screenshot - Intelligently truncates strings and # of duplicate objects in logs to avoid token limits - Removes cookies and sensitive headers to avoid sending to LLMs in MCP clients #### MCP Server - Implements the Model Context Protocol - Provides standardized tools for AI clients - Compatible with various MCP clients (Cursor, Cline, Zed, Claude Desktop, etc.) ## Installation Installation steps can be found in our documentation: - [BrowserTools MCP Docs](https://browsertools.agentdesk.ai/) ## Usage Once installed and configured, the system allows any compatible MCP client to: - Monitor browser console output - Capture network traffic - Take screenshots - Analyze selected elements - Wipe logs stored in our MCP server - Run accessibility, performance, SEO, and best practices audits ## Compatibility - Works with any MCP-compatible client - Primarily designed for Cursor IDE integration - Supports other AI editors and MCP clients ================================================ FILE: browser-tools-mcp/README.md ================================================ # Browser Tools MCP Server A Model Context Protocol (MCP) server that provides AI-powered browser tools integration. This server works in conjunction with the Browser Tools Server to provide AI capabilities for browser debugging and analysis. ## Features - MCP protocol implementation - Browser console log access - Network request analysis - Screenshot capture capabilities - Element selection and inspection - Real-time browser state monitoring - Accessibility, performance, SEO, and best practices audits ## Prerequisites - Node.js 14 or higher - Browser Tools Server running - Chrome or Chromium browser installed (required for audit functionality) ## Installation ```bash npx @agentdeskai/browser-tools-mcp ``` Or install globally: ```bash npm install -g @agentdeskai/browser-tools-mcp ``` ## Usage 1. First, make sure the Browser Tools Server is running: ```bash npx @agentdeskai/browser-tools-server ``` 2. Then start the MCP server: ```bash npx @agentdeskai/browser-tools-mcp ``` 3. The MCP server will connect to the Browser Tools Server and provide the following capabilities: - Console log retrieval - Network request monitoring - Screenshot capture - Element selection - Browser state analysis - Accessibility and performance audits ## MCP Functions The server provides the following MCP functions: - `mcp_getConsoleLogs` - Retrieve browser console logs - `mcp_getConsoleErrors` - Get browser console errors - `mcp_getNetworkErrors` - Get network error logs - `mcp_getNetworkSuccess` - Get successful network requests - `mcp_getNetworkLogs` - Get all network logs - `mcp_getSelectedElement` - Get the currently selected DOM element - `mcp_runAccessibilityAudit` - Run a WCAG-compliant accessibility audit - `mcp_runPerformanceAudit` - Run a performance audit - `mcp_runSEOAudit` - Run an SEO audit - `mcp_runBestPracticesAudit` - Run a best practices audit ## Integration This server is designed to work with AI tools and platforms that support the Model Context Protocol (MCP). It provides a standardized interface for AI models to interact with browser state and debugging information. ## License MIT ================================================ FILE: browser-tools-mcp/mcp-server.ts ================================================ #!/usr/bin/env node import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import path from "path"; import fs from "fs"; // Create the MCP server const server = new McpServer({ name: "Browser Tools MCP", version: "1.2.0", }); // Track the discovered server connection let discoveredHost = "127.0.0.1"; let discoveredPort = 3025; let serverDiscovered = false; // Function to get the default port from environment variable or default function getDefaultServerPort(): number { // Check environment variable first if (process.env.BROWSER_TOOLS_PORT) { const envPort = parseInt(process.env.BROWSER_TOOLS_PORT, 10); if (!isNaN(envPort) && envPort > 0) { return envPort; } } // Try to read from .port file try { const portFilePath = path.join(__dirname, ".port"); if (fs.existsSync(portFilePath)) { const port = parseInt(fs.readFileSync(portFilePath, "utf8").trim(), 10); if (!isNaN(port) && port > 0) { return port; } } } catch (err) { console.error("Error reading port file:", err); } // Default port if no configuration found return 3025; } // Function to get default server host from environment variable or default function getDefaultServerHost(): string { // Check environment variable first if (process.env.BROWSER_TOOLS_HOST) { return process.env.BROWSER_TOOLS_HOST; } // Default to localhost return "127.0.0.1"; } // Server discovery function - similar to what you have in the Chrome extension async function discoverServer(): Promise { console.log("Starting server discovery process"); // Common hosts to try const hosts = [getDefaultServerHost(), "127.0.0.1", "localhost"]; // Ports to try (start with default, then try others) const defaultPort = getDefaultServerPort(); const ports = [defaultPort]; // Add additional ports (fallback range) for (let p = 3025; p <= 3035; p++) { if (p !== defaultPort) { ports.push(p); } } console.log(`Will try hosts: ${hosts.join(", ")}`); console.log(`Will try ports: ${ports.join(", ")}`); // Try to find the server for (const host of hosts) { for (const port of ports) { try { console.log(`Checking ${host}:${port}...`); // Use the identity endpoint for validation const response = await fetch(`http://${host}:${port}/.identity`, { signal: AbortSignal.timeout(1000), // 1 second timeout }); if (response.ok) { const identity = await response.json(); // Verify this is actually our server by checking the signature if (identity.signature === "mcp-browser-connector-24x7") { console.log(`Successfully found server at ${host}:${port}`); // Save the discovered connection discoveredHost = host; discoveredPort = port; serverDiscovered = true; return true; } } } catch (error: any) { // Ignore connection errors during discovery console.error(`Error checking ${host}:${port}: ${error.message}`); } } } console.error("No server found during discovery"); return false; } // Wrapper function to ensure server connection before making requests async function withServerConnection( apiCall: () => Promise ): Promise { // Attempt to discover server if not already discovered if (!serverDiscovered) { const discovered = await discoverServer(); if (!discovered) { return { content: [ { type: "text", text: "Failed to discover browser connector server. Please ensure it's running.", }, ], isError: true, }; } } // Now make the actual API call with discovered host/port try { return await apiCall(); } catch (error: any) { // If the request fails, try rediscovering the server once console.error( `API call failed: ${error.message}. Attempting rediscovery...` ); serverDiscovered = false; if (await discoverServer()) { console.error("Rediscovery successful. Retrying API call..."); try { // Retry the API call with the newly discovered connection return await apiCall(); } catch (retryError: any) { console.error(`Retry failed: ${retryError.message}`); return { content: [ { type: "text", text: `Error after reconnection attempt: ${retryError.message}`, }, ], isError: true, }; } } else { console.error("Rediscovery failed. Could not reconnect to server."); return { content: [ { type: "text", text: `Failed to reconnect to server: ${error.message}`, }, ], isError: true, }; } } } // We'll define our tools that retrieve data from the browser connector server.tool("getConsoleLogs", "Check our browser logs", async () => { return await withServerConnection(async () => { const response = await fetch( `http://${discoveredHost}:${discoveredPort}/console-logs` ); const json = await response.json(); return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; }); }); server.tool( "getConsoleErrors", "Check our browsers console errors", async () => { return await withServerConnection(async () => { const response = await fetch( `http://${discoveredHost}:${discoveredPort}/console-errors` ); const json = await response.json(); return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; }); } ); server.tool("getNetworkErrors", "Check our network ERROR logs", async () => { return await withServerConnection(async () => { const response = await fetch( `http://${discoveredHost}:${discoveredPort}/network-errors` ); const json = await response.json(); return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], isError: true, }; }); }); server.tool("getNetworkLogs", "Check ALL our network logs", async () => { return await withServerConnection(async () => { const response = await fetch( `http://${discoveredHost}:${discoveredPort}/network-success` ); const json = await response.json(); return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; }); }); server.tool( "takeScreenshot", "Take a screenshot of the current browser tab", async () => { return await withServerConnection(async () => { try { const response = await fetch( `http://${discoveredHost}:${discoveredPort}/capture-screenshot`, { method: "POST", } ); const result = await response.json(); if (response.ok) { return { content: [ { type: "text", text: "Successfully saved screenshot", }, ], }; } else { return { content: [ { type: "text", text: `Error taking screenshot: ${result.error}`, }, ], }; } } catch (error: any) { const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Failed to take screenshot: ${errorMessage}`, }, ], }; } }); } ); server.tool( "getSelectedElement", "Get the selected element from the browser", async () => { return await withServerConnection(async () => { const response = await fetch( `http://${discoveredHost}:${discoveredPort}/selected-element` ); const json = await response.json(); return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; }); } ); server.tool("wipeLogs", "Wipe all browser logs from memory", async () => { return await withServerConnection(async () => { const response = await fetch( `http://${discoveredHost}:${discoveredPort}/wipelogs`, { method: "POST", } ); const json = await response.json(); return { content: [ { type: "text", text: json.message, }, ], }; }); }); // Define audit categories as enum to match the server's AuditCategory enum enum AuditCategory { ACCESSIBILITY = "accessibility", PERFORMANCE = "performance", SEO = "seo", BEST_PRACTICES = "best-practices", PWA = "pwa", } // Add tool for accessibility audits, launches a headless browser instance server.tool( "runAccessibilityAudit", "Run an accessibility audit on the current page", {}, async () => { return await withServerConnection(async () => { try { // Simplified approach - let the browser connector handle the current tab and URL console.log( `Sending POST request to http://${discoveredHost}:${discoveredPort}/accessibility-audit` ); const response = await fetch( `http://${discoveredHost}:${discoveredPort}/accessibility-audit`, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ category: AuditCategory.ACCESSIBILITY, source: "mcp_tool", timestamp: Date.now(), }), } ); // Log the response status console.log(`Accessibility audit response status: ${response.status}`); if (!response.ok) { const errorText = await response.text(); console.error(`Accessibility audit error: ${errorText}`); throw new Error(`Server returned ${response.status}: ${errorText}`); } const json = await response.json(); // flatten it by merging metadata with the report contents if (json.report) { const { metadata, report } = json; const flattened = { ...metadata, ...report, }; return { content: [ { type: "text", text: JSON.stringify(flattened, null, 2), }, ], }; } else { // Return as-is if it's not in the new format return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); console.error("Error in accessibility audit:", errorMessage); return { content: [ { type: "text", text: `Failed to run accessibility audit: ${errorMessage}`, }, ], }; } }); } ); // Add tool for performance audits, launches a headless browser instance server.tool( "runPerformanceAudit", "Run a performance audit on the current page", {}, async () => { return await withServerConnection(async () => { try { // Simplified approach - let the browser connector handle the current tab and URL console.log( `Sending POST request to http://${discoveredHost}:${discoveredPort}/performance-audit` ); const response = await fetch( `http://${discoveredHost}:${discoveredPort}/performance-audit`, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ category: AuditCategory.PERFORMANCE, source: "mcp_tool", timestamp: Date.now(), }), } ); // Log the response status console.log(`Performance audit response status: ${response.status}`); if (!response.ok) { const errorText = await response.text(); console.error(`Performance audit error: ${errorText}`); throw new Error(`Server returned ${response.status}: ${errorText}`); } const json = await response.json(); // flatten it by merging metadata with the report contents if (json.report) { const { metadata, report } = json; const flattened = { ...metadata, ...report, }; return { content: [ { type: "text", text: JSON.stringify(flattened, null, 2), }, ], }; } else { // Return as-is if it's not in the new format return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); console.error("Error in performance audit:", errorMessage); return { content: [ { type: "text", text: `Failed to run performance audit: ${errorMessage}`, }, ], }; } }); } ); // Add tool for SEO audits, launches a headless browser instance server.tool( "runSEOAudit", "Run an SEO audit on the current page", {}, async () => { return await withServerConnection(async () => { try { console.log( `Sending POST request to http://${discoveredHost}:${discoveredPort}/seo-audit` ); const response = await fetch( `http://${discoveredHost}:${discoveredPort}/seo-audit`, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ category: AuditCategory.SEO, source: "mcp_tool", timestamp: Date.now(), }), } ); // Log the response status console.log(`SEO audit response status: ${response.status}`); if (!response.ok) { const errorText = await response.text(); console.error(`SEO audit error: ${errorText}`); throw new Error(`Server returned ${response.status}: ${errorText}`); } const json = await response.json(); return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); console.error("Error in SEO audit:", errorMessage); return { content: [ { type: "text", text: `Failed to run SEO audit: ${errorMessage}`, }, ], }; } }); } ); server.tool("runNextJSAudit", {}, async () => ({ content: [ { type: "text", text: ` You are an expert in SEO and web development with NextJS. Given the following procedures for analyzing my codebase, please perform a comprehensive - page by page analysis of our NextJS application to identify any issues or areas of improvement for SEO. After each iteration of changes, reinvoke this tool to re-fetch our SEO audit procedures and then scan our codebase again to identify additional areas of improvement. When no more areas of improvement are found, return "No more areas of improvement found, your NextJS application is optimized for SEO!". Start by analyzing each of the following aspects of our codebase: 1. Meta tags - provides information about your website to search engines and social media platforms. Pages should provide the following standard meta tags: title description keywords robots viewport charSet Open Graph meta tags: og:site_name og:locale og:title og:description og:type og:url og:image og:image:alt og:image:type og:image:width og:image:height Article meta tags (actually it's also OpenGraph): article:published_time article:modified_time article:author Twitter meta tags: twitter:card twitter:site twitter:creator twitter:title twitter:description twitter:image For applications using the pages router, set up metatags like this in pages/[slug].tsx: import Head from "next/head"; export default function Page() { return ( Next.js SEO: The Complete Checklist to Boost Your Site Ranking ); } For applications using the app router, set up metatags like this in layout.tsx: import type { Viewport, Metadata } from "next"; export const viewport: Viewport = { width: "device-width", initialScale: 1, themeColor: "#ffffff" }; export const metadata: Metadata = { metadataBase: new URL("https://dminhvu.com"), openGraph: { siteName: "Blog | Minh Vu", type: "website", locale: "en_US" }, robots: { index: true, follow: true, "max-image-preview": "large", "max-snippet": -1, "max-video-preview": -1, googleBot: "index, follow" }, alternates: { types: { "application/rss+xml": "https://dminhvu.com/rss.xml" } }, applicationName: "Blog | Minh Vu", appleWebApp: { title: "Blog | Minh Vu", statusBarStyle: "default", capable: true }, verification: { google: "YOUR_DATA", yandex: ["YOUR_DATA"], other: { "msvalidate.01": ["YOUR_DATA"], "facebook-domain-verification": ["YOUR_DATA"] } }, icons: { icon: [ { url: "/favicon.ico", type: "image/x-icon" }, { url: "/favicon-16x16.png", sizes: "16x16", type: "image/png" } // add favicon-32x32.png, favicon-96x96.png, android-chrome-192x192.png ], shortcut: [ { url: "/favicon.ico", type: "image/x-icon" } ], apple: [ { url: "/apple-icon-57x57.png", sizes: "57x57", type: "image/png" }, { url: "/apple-icon-60x60.png", sizes: "60x60", type: "image/png" } // add apple-icon-72x72.png, apple-icon-76x76.png, apple-icon-114x114.png, apple-icon-120x120.png, apple-icon-144x144.png, apple-icon-152x152.png, apple-icon-180x180.png ] } }; And like this for any page.tsx file: import { Metadata } from "next"; export const metadata: Metadata = { title: "Elastic Stack, Next.js, Python, JavaScript Tutorials | dminhvu", description: "dminhvu.com - Programming blog for everyone to learn Elastic Stack, Next.js, Python, JavaScript, React, Machine Learning, Data Science, and more.", keywords: [ "elastic", "python", "javascript", "react", "machine learning", "data science" ], openGraph: { url: "https://dminhvu.com", type: "website", title: "Elastic Stack, Next.js, Python, JavaScript Tutorials | dminhvu", description: "dminhvu.com - Programming blog for everyone to learn Elastic Stack, Next.js, Python, JavaScript, React, Machine Learning, Data Science, and more.", images: [ { url: "https://dminhvu.com/images/home/thumbnail.png", width: 1200, height: 630, alt: "dminhvu" } ] }, twitter: { card: "summary_large_image", title: "Elastic Stack, Next.js, Python, JavaScript Tutorials | dminhvu", description: "dminhvu.com - Programming blog for everyone to learn Elastic Stack, Next.js, Python, JavaScript, React, Machine Learning, Data Science, and more.", creator: "@dminhvu02", site: "@dminhvu02", images: [ { url: "https://dminhvu.com/images/home/thumbnail.png", width: 1200, height: 630, alt: "dminhvu" } ] }, alternates: { canonical: "https://dminhvu.com" } }; Note that the charSet and viewport are automatically added by Next.js App Router, so you don't need to define them. For applications using the app router, dynamic metadata can be defined by using the generateMetadata function, this is useful when you have dynamic pages like [slug]/page.tsx, or [id]/page.tsx: import type { Metadata, ResolvingMetadata } from "next"; type Params = { slug: string; }; type Props = { params: Params; searchParams: { [key: string]: string | string[] | undefined }; }; export async function generateMetadata( { params, searchParams }: Props, parent: ResolvingMetadata ): Promise { const { slug } = params; const post: Post = await fetch("YOUR_ENDPOINT", { method: "GET", next: { revalidate: 60 * 60 * 24 } }).then((res) => res.json()); return { title: "{post.title} | dminhvu", authors: [ { name: post.author || "Minh Vu" } ], description: post.description, keywords: post.keywords, openGraph: { title: "{post.title} | dminhvu", description: post.description, type: "article", url: "https://dminhvu.com/{post.slug}", publishedTime: post.created_at, modifiedTime: post.modified_at, authors: ["https://dminhvu.com/about"], tags: post.categories, images: [ { url: "https://ik.imagekit.io/dminhvu/assets/{post.slug}/thumbnail.png?tr=f-png", width: 1024, height: 576, alt: post.title, type: "image/png" } ] }, twitter: { card: "summary_large_image", site: "@dminhvu02", creator: "@dminhvu02", title: "{post.title} | dminhvu", description: post.description, images: [ { url: "https://ik.imagekit.io/dminhvu/assets/{post.slug}/thumbnail.png?tr=f-png", width: 1024, height: 576, alt: post.title } ] }, alternates: { canonical: "https://dminhvu.com/{post.slug}" } }; } 2. JSON-LD Schema JSON-LD is a format for structured data that can be used by search engines to understand your content. For example, you can use it to describe a person, an event, an organization, a movie, a book, a recipe, and many other types of entities. Our current recommendation for JSON-LD is to render structured data as a )} ); } Script Optimization for Common Third-Party Integrations Next.js App Router introduces a new library called @next/third-parties for: Google Tag Manager Google Analytics Google Maps Embed YouTube Embed To use the @next/third-parties library, you need to install it: npm install @next/third-parties Then, you can add the following code to your app/layout.tsx: app/layout.tsx import { GoogleTagManager } from "@next/third-parties/google"; import { GoogleAnalytics } from "@next/third-parties/google"; import Head from "next/head"; export default function Page() { return ( {process.env.NODE_ENV === "production" && ( <> {/* other scripts */} )} {/* other parts */} ); } Please note that you don't need to include both GoogleTagManager and GoogleAnalytics if you only use one of them. 7. Image optimization Image Optimization This part can be applied to both Pages Router and App Router. Image optimization is also an important part of SEO as it helps your website load faster. Faster image rendering speed will contribute to the Google PageSpeed score, which can improve user experience and SEO. You can use next/image to optimize images in your Next.js website. For example, the following code will optimize this post thumbnail: import Image from "next/image"; export default function Page() { return ( Next.js SEO ); } Remember to use a CDN to serve your media (images, videos, etc.) to improve the loading speed. For the image format, use WebP if possible because it has a smaller size than PNG and JPEG. Given the provided procedures, begin by analyzing all of our Next.js pages. Check to see what metadata already exists, look for any robot.txt files, and take a closer look at some of the other aspects of our project to determine areas of improvement. Once you've performed this comprehensive analysis, return back a report on what we can do to improve our application. Do not actually make the code changes yet, just return a comprehensive plan that you will ask for approval for. If feedback is provided, adjust the plan accordingly and ask for approval again. If the user approves of the plan, go ahead and proceed to implement all the necessary code changes to completely optimize our application. `, }, ], })); server.tool( "runDebuggerMode", "Run debugger mode to debug an issue in our application", async () => ({ content: [ { type: "text", text: ` Please follow this exact sequence to debug an issue in our application: 1. Reflect on 5-7 different possible sources of the problem 2. Distill those down to 1-2 most likely sources 3. Add additional logs to validate your assumptions and track the transformation of data structures throughout the application control flow before we move onto implementing the actual code fix 4. Use the "getConsoleLogs", "getConsoleErrors", "getNetworkLogs" & "getNetworkErrors" tools to obtain any newly added web browser logs 5. Obtain the server logs as well if accessible - otherwise, ask me to copy/paste them into the chat 6. Deeply reflect on what could be wrong + produce a comprehensive analysis of the issue 7. Suggest additional logs if the issue persists or if the source is not yet clear 8. Once a fix is implemented, ask for approval to remove the previously added logs Note: DO NOT run any of our audits (runAccessibilityAudit, runPerformanceAudit, runBestPracticesAudit, runSEOAudit, runNextJSAudit) when in debugging mode unless explicitly asked to do so or unless you switch to audit mode. `, }, ], }) ); server.tool( "runAuditMode", "Run audit mode to optimize our application for SEO, accessibility and performance", async () => ({ content: [ { type: "text", text: ` I want you to enter "Audit Mode". Use the following MCP tools one after the other in this exact sequence: 1. runAccessibilityAudit 2. runPerformanceAudit 3. runBestPracticesAudit 4. runSEOAudit 5. runNextJSAudit (only if our application is ACTUALLY using NextJS) After running all of these tools, return back a comprehensive analysis of the audit results. Do NOT use runNextJSAudit tool unless you see that our application is ACTUALLY using NextJS. DO NOT use the takeScreenshot tool EVER during audit mode. ONLY use it if I specifically ask you to take a screenshot of something. DO NOT check console or network logs to get started - your main priority is to run the audits in the sequence defined above. After returning an in-depth analysis, scan through my code and identify various files/parts of my codebase that we want to modify/improve based on the results of our audits. After identifying what changes may be needed, do NOT make the actual changes. Instead, return back a comprehensive, step-by-step plan to address all of these changes and ask for approval to execute this plan. If feedback is received, make a new plan and ask for approval again. If approved, execute the ENTIRE plan and after all phases/steps are complete, re-run the auditing tools in the same 4 step sequence again before returning back another analysis for additional changes potentially needed. Keep repeating / iterating through this process with the four tools until our application is as optimized as possible for SEO, accessibility and performance. `, }, ], }) ); // Add tool for Best Practices audits, launches a headless browser instance server.tool( "runBestPracticesAudit", "Run a best practices audit on the current page", {}, async () => { return await withServerConnection(async () => { try { console.log( `Sending POST request to http://${discoveredHost}:${discoveredPort}/best-practices-audit` ); const response = await fetch( `http://${discoveredHost}:${discoveredPort}/best-practices-audit`, { method: "POST", headers: { "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ source: "mcp_tool", timestamp: Date.now(), }), } ); // Check for errors if (!response.ok) { const errorText = await response.text(); throw new Error(`Server returned ${response.status}: ${errorText}`); } const json = await response.json(); // flatten it by merging metadata with the report contents if (json.report) { const { metadata, report } = json; const flattened = { ...metadata, ...report, }; return { content: [ { type: "text", text: JSON.stringify(flattened, null, 2), }, ], }; } else { // Return as-is if it's not in the new format return { content: [ { type: "text", text: JSON.stringify(json, null, 2), }, ], }; } } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); console.error("Error in Best Practices audit:", errorMessage); return { content: [ { type: "text", text: `Failed to run Best Practices audit: ${errorMessage}`, }, ], }; } }); } ); // Start receiving messages on stdio (async () => { try { // Attempt initial server discovery console.error("Attempting initial server discovery on startup..."); await discoverServer(); if (serverDiscovered) { console.error( `Successfully discovered server at ${discoveredHost}:${discoveredPort}` ); } else { console.error( "Initial server discovery failed. Will try again when tools are used." ); } const transport = new StdioServerTransport(); // Ensure stdout is only used for JSON messages const originalStdoutWrite = process.stdout.write.bind(process.stdout); process.stdout.write = (chunk: any, encoding?: any, callback?: any) => { // Only allow JSON messages to pass through if (typeof chunk === "string" && !chunk.startsWith("{")) { return true; // Silently skip non-JSON messages } return originalStdoutWrite(chunk, encoding, callback); }; await server.connect(transport); } catch (error) { console.error("Failed to initialize MCP server:", error); process.exit(1); } })(); ================================================ FILE: browser-tools-mcp/package.json ================================================ { "name": "@agentdeskai/browser-tools-mcp", "version": "1.2.0", "description": "MCP (Model Context Protocol) server for browser tools integration", "main": "dist/mcp-server.js", "bin": { "browser-tools-mcp": "dist/mcp-server.js" }, "scripts": { "inspect": "tsc && npx @modelcontextprotocol/inspector node -- dist/mcp-server.js", "inspect-live": "npx @modelcontextprotocol/inspector npx -- @agentdeskai/browser-tools-mcp", "build": "tsc", "start": "tsc && node dist/mcp-server.js", "prepublishOnly": "npm run build", "update": "npm run build && npm version patch && npm publish" }, "keywords": [ "mcp", "model-context-protocol", "browser", "tools", "debugging", "ai", "chrome", "extension" ], "author": "AgentDesk AI", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "^1.4.1", "body-parser": "^1.20.3", "cors": "^2.8.5", "express": "^4.21.2", "llm-cost": "^1.0.5", "node-fetch": "^2.7.0", "ws": "^8.18.0" }, "devDependencies": { "@types/ws": "^8.5.14", "@types/body-parser": "^1.19.5", "@types/cors": "^2.8.17", "@types/express": "^5.0.0", "@types/node": "^22.13.1", "@types/node-fetch": "^2.6.11", "typescript": "^5.7.3" } } ================================================ FILE: browser-tools-mcp/tsconfig.json ================================================ { "compilerOptions": { "target": "ES2020", "module": "NodeNext", "moduleResolution": "NodeNext", "esModuleInterop": true, "outDir": "./dist", "rootDir": ".", "strict": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["*.ts"], "exclude": ["node_modules", "dist"] } ================================================ FILE: browser-tools-server/README.md ================================================ # Browser Tools Server A powerful browser tools server for capturing and managing browser events, logs, and screenshots. This server works in conjunction with the Browser Tools Chrome Extension to provide comprehensive browser debugging capabilities. ## Features - Console log capture - Network request monitoring - Screenshot capture - Element selection tracking - WebSocket real-time communication - Configurable log limits and settings - Lighthouse-powered accessibility, performance, SEO, and best practices audits ## Installation ```bash npx @agentdeskai/browser-tools-server ``` Or install globally: ```bash npm install -g @agentdeskai/browser-tools-server ``` ## Usage 1. Start the server: ```bash npx @agentdeskai/browser-tools-server ``` 2. The server will start on port 3025 by default 3. Install and enable the Browser Tools Chrome Extension 4. The server exposes the following endpoints: - `/console-logs` - Get console logs - `/console-errors` - Get console errors - `/network-errors` - Get network error logs - `/network-success` - Get successful network requests - `/all-xhr` - Get all network requests - `/screenshot` - Capture screenshots - `/selected-element` - Get currently selected DOM element - `/accessibility-audit` - Run accessibility audit on current page - `/performance-audit` - Run performance audit on current page - `/seo-audit` - Run SEO audit on current page ## API Documentation ### GET Endpoints - `GET /console-logs` - Returns recent console logs - `GET /console-errors` - Returns recent console errors - `GET /network-errors` - Returns recent network errors - `GET /network-success` - Returns recent successful network requests - `GET /all-xhr` - Returns all recent network requests - `GET /selected-element` - Returns the currently selected DOM element ### POST Endpoints - `POST /extension-log` - Receive logs from the extension - `POST /screenshot` - Capture and save screenshots - `POST /selected-element` - Update the selected element - `POST /wipelogs` - Clear all stored logs - `POST /accessibility-audit` - Run a WCAG-compliant accessibility audit on the current page - `POST /performance-audit` - Run a performance audit on the current page - `POST /seo-audit` - Run a SEO audit on the current page # Audit Functionality The server provides Lighthouse-powered audit capabilities through four AI-optimized endpoints. These audits have been specifically tailored for AI consumption, with structured data, clear categorization, and smart prioritization. ## Smart Limit Implementation All audit tools implement a "smart limit" approach to provide the most relevant information based on impact severity: - **Critical issues**: No limit (all issues are shown) - **Serious issues**: Up to 15 items per issue - **Moderate issues**: Up to 10 items per issue - **Minor issues**: Up to 3 items per issue This ensures that the most important issues are always included in the response, while less important ones are limited to maintain a manageable response size for AI processing. ## Common Audit Response Structure All audit responses follow a similar structure: ```json { "metadata": { "url": "https://example.com", "timestamp": "2025-03-06T16:28:30.930Z", "device": "desktop", "lighthouseVersion": "11.7.1" }, "report": { "score": 88, "audit_counts": { "failed": 2, "passed": 17, "manual": 10, "informative": 0, "not_applicable": 42 } // Audit-specific content // ... } } ``` ## Accessibility Audit (`/accessibility-audit`) The accessibility audit evaluates web pages against WCAG standards, identifying issues that affect users with disabilities. ### Response Format ```json { "metadata": { "url": "https://example.com", "timestamp": "2025-03-06T16:28:30.930Z", "device": "desktop", "lighthouseVersion": "11.7.1" }, "report": { "score": 88, "audit_counts": { "failed": 2, "passed": 17, "manual": 10, "informative": 0, "not_applicable": 42 }, "issues": [ { "id": "meta-viewport", "title": "`[user-scalable=\"no\"]` is used in the `` element or the `[maximum-scale]` attribute is less than 5.", "impact": "critical", "category": "a11y-best-practices", "elements": [ { "selector": "head > meta", "snippet": "", "label": "head > meta", "issue_description": "Fix any of the following: user-scalable on tag disables zooming on mobile devices" } ], "score": 0 } ], "categories": { "a11y-navigation": { "score": 0, "issues_count": 0 }, "a11y-aria": { "score": 0, "issues_count": 1 }, "a11y-best-practices": { "score": 0, "issues_count": 1 } }, "critical_elements": [ { "selector": "head > meta", "snippet": "", "label": "head > meta", "issue_description": "Fix any of the following: user-scalable on tag disables zooming on mobile devices" } ], "prioritized_recommendations": [ "Fix ARIA attributes and roles", "Fix 1 issues in a11y-best-practices" ] } } ``` ### Key Features - **Issues Categorized by Impact**: Critical, serious, moderate, and minor - **Element-Specific Information**: Selectors, snippets, and labels for affected elements - **Issue Categories**: ARIA, navigation, color contrast, forms, keyboard access, etc. - **Critical Elements List**: Quick access to the most serious issues - **Prioritized Recommendations**: Actionable advice in order of importance ## Performance Audit (`/performance-audit`) The performance audit analyzes page load speed, Core Web Vitals, and optimization opportunities. ### Response Format ```json { "metadata": { "url": "https://example.com", "timestamp": "2025-03-06T16:27:44.900Z", "device": "desktop", "lighthouseVersion": "11.7.1" }, "report": { "score": 60, "audit_counts": { "failed": 11, "passed": 21, "manual": 0, "informative": 20, "not_applicable": 8 }, "metrics": [ { "id": "lcp", "score": 0, "value_ms": 14149, "passes_core_web_vital": false, "element_selector": "div.heading > span", "element_type": "text", "element_content": "Welcome to Example" }, { "id": "fcp", "score": 0.53, "value_ms": 1542, "passes_core_web_vital": false }, { "id": "si", "score": 0, "value_ms": 6883 }, { "id": "tti", "score": 0, "value_ms": 14746 }, { "id": "cls", "score": 1, "value_ms": 0.001, "passes_core_web_vital": true }, { "id": "tbt", "score": 1, "value_ms": 43, "passes_core_web_vital": true } ], "opportunities": [ { "id": "render_blocking_resources", "savings_ms": 1270, "severity": "serious", "resources": [ { "url": "styles.css", "savings_ms": 781 } ] } ], "page_stats": { "total_size_kb": 2190, "total_requests": 108, "resource_counts": { "js": 86, "css": 1, "img": 3, "font": 3, "other": 15 }, "third_party_size_kb": 2110, "main_thread_blocking_time_ms": 693 }, "prioritized_recommendations": ["Improve Largest Contentful Paint (LCP)"] } } ``` ### Key Features - **Core Web Vitals Analysis**: LCP, FCP, CLS, TBT with pass/fail status - **Element Information for LCP**: Identifies what's causing the largest contentful paint - **Optimization Opportunities**: Specific actions to improve performance with estimated time savings - **Resource Breakdown**: By type, size, and origin (first vs. third party) - **Main Thread Analysis**: Blocking time metrics to identify JavaScript performance issues - **Resource-Specific Recommendations**: For each optimization opportunity ## SEO Audit (`/seo-audit`) The SEO audit checks search engine optimization best practices and identifies issues that could affect search ranking. ### Response Format ```json { "metadata": { "url": "https://example.com", "timestamp": "2025-03-06T16:29:12.455Z", "device": "desktop", "lighthouseVersion": "11.7.1" }, "report": { "score": 91, "audit_counts": { "failed": 1, "passed": 10, "manual": 1, "informative": 0, "not_applicable": 3 }, "issues": [ { "id": "is-crawlable", "title": "Page is blocked from indexing", "impact": "critical", "category": "crawlability", "score": 0 } ], "categories": { "content": { "score": 0, "issues_count": 0 }, "mobile": { "score": 0, "issues_count": 0 }, "crawlability": { "score": 0, "issues_count": 1 }, "other": { "score": 0, "issues_count": 0 } }, "prioritized_recommendations": [ "Fix crawlability issues (1 issues): robots.txt, sitemaps, and redirects" ] } } ``` ### Key Features - **Issues Categorized by Impact**: Critical, serious, moderate, and minor - **SEO Categories**: Content, mobile friendliness, crawlability - **Issue Details**: Information about what's causing each SEO problem - **Prioritized Recommendations**: Actionable advice in order of importance ## Best Practices Audit (`/best-practices-audit`) The best practices audit evaluates adherence to web development best practices related to security, trust, user experience, and browser compatibility. ### Response Format ```json { "metadata": { "url": "https://example.com", "timestamp": "2025-03-06T17:01:38.029Z", "device": "desktop", "lighthouseVersion": "11.7.1" }, "report": { "score": 74, "audit_counts": { "failed": 4, "passed": 10, "manual": 0, "informative": 2, "not_applicable": 1 }, "issues": [ { "id": "deprecations", "title": "Uses deprecated APIs", "impact": "critical", "category": "security", "score": 0, "details": [ { "value": "UnloadHandler" } ] }, { "id": "errors-in-console", "title": "Browser errors were logged to the console", "impact": "serious", "category": "user-experience", "score": 0, "details": [ { "source": "console.error", "description": "ReferenceError: variable is not defined" } ] } ], "categories": { "security": { "score": 75, "issues_count": 1 }, "trust": { "score": 100, "issues_count": 0 }, "user-experience": { "score": 50, "issues_count": 1 }, "browser-compat": { "score": 100, "issues_count": 0 }, "other": { "score": 75, "issues_count": 2 } }, "prioritized_recommendations": [ "Address 1 security issues: vulnerabilities, CSP, deprecations", "Improve 1 user experience issues: console errors, user interactions" ] } } ``` ### Key Features - **Issues Categorized by Impact**: Critical, serious, moderate, and minor - **Best Practice Categories**: Security, trust, user experience, browser compatibility - **Detailed Issue Information**: Specific problems affecting best practices compliance - **Security Focus**: Special attention to security vulnerabilities and deprecated APIs - **Prioritized Recommendations**: Actionable advice in order of importance ## License MIT # Puppeteer Service A comprehensive browser automation service built on Puppeteer to provide reliable cross-platform browser control capabilities. ## Features - **Cross-Platform Browser Support**: - Windows, macOS, and Linux support - Chrome, Edge, Brave, and Firefox detection - Fallback strategy for finding browser executables - **Smart Browser Management**: - Singleton browser instance with automatic cleanup - Connection retry mechanisms - Temporary user data directories with cleanup - **Rich Configuration Options**: - Custom browser paths - Network condition emulation - Device emulation (mobile, tablet, desktop) - Resource blocking - Cookies and headers customization - Locale and timezone emulation ================================================ FILE: browser-tools-server/browser-connector.ts ================================================ #!/usr/bin/env node import express from "express"; import cors from "cors"; import bodyParser from "body-parser"; import { tokenizeAndEstimateCost } from "llm-cost"; import { WebSocketServer, WebSocket } from "ws"; import fs from "fs"; import path from "path"; import { IncomingMessage } from "http"; import { Socket } from "net"; import os from "os"; import { exec } from "child_process"; import { runPerformanceAudit, runAccessibilityAudit, runSEOAudit, AuditCategory, LighthouseReport, } from "./lighthouse/index.js"; import * as net from "net"; import { runBestPracticesAudit } from "./lighthouse/best-practices.js"; /** * Converts a file path to the appropriate format for the current platform * Handles Windows, WSL, macOS and Linux path formats * * @param inputPath - The path to convert * @returns The converted path appropriate for the current platform */ function convertPathForCurrentPlatform(inputPath: string): string { const platform = os.platform(); // If no path provided, return as is if (!inputPath) return inputPath; console.log(`Converting path "${inputPath}" for platform: ${platform}`); // Windows-specific conversion if (platform === "win32") { // Convert forward slashes to backslashes return inputPath.replace(/\//g, "\\"); } // Linux/Mac-specific conversion if (platform === "linux" || platform === "darwin") { // Check if this is a Windows UNC path (starts with \\) if (inputPath.startsWith("\\\\") || inputPath.includes("\\")) { // Check if this is a WSL path (contains wsl.localhost or wsl$) if (inputPath.includes("wsl.localhost") || inputPath.includes("wsl$")) { // Extract the path after the distribution name // Handle both \\wsl.localhost\Ubuntu\path and \\wsl$\Ubuntu\path formats const parts = inputPath.split("\\").filter((part) => part.length > 0); console.log("Path parts:", parts); // Find the index after the distribution name const distNames = [ "Ubuntu", "Debian", "kali", "openSUSE", "SLES", "Fedora", ]; // Find the distribution name in the path let distIndex = -1; for (const dist of distNames) { const index = parts.findIndex( (part) => part === dist || part.toLowerCase() === dist.toLowerCase() ); if (index !== -1) { distIndex = index; break; } } if (distIndex !== -1 && distIndex + 1 < parts.length) { // Reconstruct the path as a native Linux path const linuxPath = "/" + parts.slice(distIndex + 1).join("/"); console.log( `Converted Windows WSL path "${inputPath}" to Linux path "${linuxPath}"` ); return linuxPath; } // If we couldn't find a distribution name but it's clearly a WSL path, // try to extract everything after wsl.localhost or wsl$ const wslIndex = parts.findIndex( (part) => part === "wsl.localhost" || part === "wsl$" || part.toLowerCase() === "wsl.localhost" || part.toLowerCase() === "wsl$" ); if (wslIndex !== -1 && wslIndex + 2 < parts.length) { // Skip the WSL prefix and distribution name const linuxPath = "/" + parts.slice(wslIndex + 2).join("/"); console.log( `Converted Windows WSL path "${inputPath}" to Linux path "${linuxPath}"` ); return linuxPath; } } // For non-WSL Windows paths, just normalize the slashes const normalizedPath = inputPath .replace(/\\\\/g, "/") .replace(/\\/g, "/"); console.log( `Converted Windows UNC path "${inputPath}" to "${normalizedPath}"` ); return normalizedPath; } // Handle Windows drive letters (e.g., C:\path\to\file) if (/^[A-Z]:\\/i.test(inputPath)) { // Convert Windows drive path to Linux/Mac compatible path const normalizedPath = inputPath .replace(/^[A-Z]:\\/i, "/") .replace(/\\/g, "/"); console.log( `Converted Windows drive path "${inputPath}" to "${normalizedPath}"` ); return normalizedPath; } } // Return the original path if no conversion was needed or possible return inputPath; } // Function to get default downloads folder function getDefaultDownloadsFolder(): string { const homeDir = os.homedir(); // Downloads folder is typically the same path on Windows, macOS, and Linux const downloadsPath = path.join(homeDir, "Downloads", "mcp-screenshots"); return downloadsPath; } // We store logs in memory const consoleLogs: any[] = []; const consoleErrors: any[] = []; const networkErrors: any[] = []; const networkSuccess: any[] = []; const allXhr: any[] = []; // Store the current URL from the extension let currentUrl: string = ""; // Store the current tab ID from the extension let currentTabId: string | number | null = null; // Add settings state let currentSettings = { logLimit: 50, queryLimit: 30000, showRequestHeaders: false, showResponseHeaders: false, model: "claude-3-sonnet", stringSizeLimit: 500, maxLogSize: 20000, screenshotPath: getDefaultDownloadsFolder(), // Add server host configuration serverHost: process.env.SERVER_HOST || "0.0.0.0", // Default to all interfaces }; // Add new storage for selected element let selectedElement: any = null; // Add new state for tracking screenshot requests interface ScreenshotCallback { resolve: (value: { data: string; path?: string; autoPaste?: boolean; }) => void; reject: (reason: Error) => void; } const screenshotCallbacks = new Map(); // Function to get available port starting with the given port async function getAvailablePort( startPort: number, maxAttempts: number = 10 ): Promise { let currentPort = startPort; let attempts = 0; while (attempts < maxAttempts) { try { // Try to create a server on the current port // We'll use a raw Node.js net server for just testing port availability await new Promise((resolve, reject) => { const testServer = net.createServer(); // Handle errors (e.g., port in use) testServer.once("error", (err: any) => { if (err.code === "EADDRINUSE") { console.log(`Port ${currentPort} is in use, trying next port...`); currentPort++; attempts++; resolve(); // Continue to next iteration } else { reject(err); // Different error, propagate it } }); // If we can listen, the port is available testServer.once("listening", () => { // Make sure to close the server to release the port testServer.close(() => { console.log(`Found available port: ${currentPort}`); resolve(); }); }); // Try to listen on the current port testServer.listen(currentPort, currentSettings.serverHost); }); // If we reach here without incrementing the port, it means the port is available return currentPort; } catch (error: any) { console.error(`Error checking port ${currentPort}:`, error); // For non-EADDRINUSE errors, try the next port currentPort++; attempts++; } } // If we've exhausted all attempts, throw an error throw new Error( `Could not find an available port after ${maxAttempts} attempts starting from ${startPort}` ); } // Start with requested port and find an available one const REQUESTED_PORT = parseInt(process.env.PORT || "3025", 10); let PORT = REQUESTED_PORT; // Create application and initialize middleware const app = express(); app.use(cors()); // Increase JSON body parser limit to 50MB to handle large screenshots app.use(bodyParser.json({ limit: "50mb" })); app.use(bodyParser.urlencoded({ limit: "50mb", extended: true })); // Helper to recursively truncate strings in any data structure function truncateStringsInData(data: any, maxLength: number): any { if (typeof data === "string") { return data.length > maxLength ? data.substring(0, maxLength) + "... (truncated)" : data; } if (Array.isArray(data)) { return data.map((item) => truncateStringsInData(item, maxLength)); } if (typeof data === "object" && data !== null) { const result: any = {}; for (const [key, value] of Object.entries(data)) { result[key] = truncateStringsInData(value, maxLength); } return result; } return data; } // Helper to safely parse and process JSON strings function processJsonString(jsonString: string, maxLength: number): string { try { // Try to parse the string as JSON const parsed = JSON.parse(jsonString); // Process any strings within the parsed JSON const processed = truncateStringsInData(parsed, maxLength); // Stringify the processed data return JSON.stringify(processed); } catch (e) { // If it's not valid JSON, treat it as a regular string return truncateStringsInData(jsonString, maxLength); } } // Helper to process logs based on settings function processLogsWithSettings(logs: any[]) { return logs.map((log) => { const processedLog = { ...log }; if (log.type === "network-request") { // Handle headers visibility if (!currentSettings.showRequestHeaders) { delete processedLog.requestHeaders; } if (!currentSettings.showResponseHeaders) { delete processedLog.responseHeaders; } } return processedLog; }); } // Helper to calculate size of a log entry function calculateLogSize(log: any): number { return JSON.stringify(log).length; } // Helper to truncate logs based on character limit function truncateLogsToQueryLimit(logs: any[]): any[] { if (logs.length === 0) return logs; // First process logs according to current settings const processedLogs = processLogsWithSettings(logs); let currentSize = 0; const result = []; for (const log of processedLogs) { const logSize = calculateLogSize(log); // Check if adding this log would exceed the limit if (currentSize + logSize > currentSettings.queryLimit) { console.log( `Reached query limit (${currentSize}/${currentSettings.queryLimit}), truncating logs` ); break; } // Add log and update size result.push(log); currentSize += logSize; console.log(`Added log of size ${logSize}, total size now: ${currentSize}`); } return result; } // Endpoint for the extension to POST data app.post("/extension-log", (req, res) => { console.log("\n=== Received Extension Log ==="); console.log("Request body:", { dataType: req.body.data?.type, timestamp: req.body.data?.timestamp, hasSettings: !!req.body.settings, }); const { data, settings } = req.body; // Update settings if provided if (settings) { console.log("Updating settings:", settings); currentSettings = { ...currentSettings, ...settings, }; } if (!data) { console.log("Warning: No data received in log request"); res.status(400).json({ status: "error", message: "No data provided" }); return; } console.log(`Processing ${data.type} log entry`); switch (data.type) { case "page-navigated": // Handle page navigation event via HTTP POST // Note: This is also handled in the WebSocket message handler // as the extension may send navigation events through either channel console.log("Received page navigation event with URL:", data.url); currentUrl = data.url; // Also update the tab ID if provided if (data.tabId) { console.log("Updating tab ID from page navigation event:", data.tabId); currentTabId = data.tabId; } console.log("Updated current URL:", currentUrl); break; case "console-log": console.log("Adding console log:", { level: data.level, message: data.message?.substring(0, 100) + (data.message?.length > 100 ? "..." : ""), timestamp: data.timestamp, }); consoleLogs.push(data); if (consoleLogs.length > currentSettings.logLimit) { console.log( `Console logs exceeded limit (${currentSettings.logLimit}), removing oldest entry` ); consoleLogs.shift(); } break; case "console-error": console.log("Adding console error:", { level: data.level, message: data.message?.substring(0, 100) + (data.message?.length > 100 ? "..." : ""), timestamp: data.timestamp, }); consoleErrors.push(data); if (consoleErrors.length > currentSettings.logLimit) { console.log( `Console errors exceeded limit (${currentSettings.logLimit}), removing oldest entry` ); consoleErrors.shift(); } break; case "network-request": const logEntry = { url: data.url, method: data.method, status: data.status, timestamp: data.timestamp, }; console.log("Adding network request:", logEntry); // Route network requests based on status code if (data.status >= 400) { networkErrors.push(data); if (networkErrors.length > currentSettings.logLimit) { console.log( `Network errors exceeded limit (${currentSettings.logLimit}), removing oldest entry` ); networkErrors.shift(); } } else { networkSuccess.push(data); if (networkSuccess.length > currentSettings.logLimit) { console.log( `Network success logs exceeded limit (${currentSettings.logLimit}), removing oldest entry` ); networkSuccess.shift(); } } break; case "selected-element": console.log("Updating selected element:", { tagName: data.element?.tagName, id: data.element?.id, className: data.element?.className, }); selectedElement = data.element; break; default: console.log("Unknown log type:", data.type); } console.log("Current log counts:", { consoleLogs: consoleLogs.length, consoleErrors: consoleErrors.length, networkErrors: networkErrors.length, networkSuccess: networkSuccess.length, }); console.log("=== End Extension Log ===\n"); res.json({ status: "ok" }); }); // Update GET endpoints to use the new function app.get("/console-logs", (req, res) => { const truncatedLogs = truncateLogsToQueryLimit(consoleLogs); res.json(truncatedLogs); }); app.get("/console-errors", (req, res) => { const truncatedLogs = truncateLogsToQueryLimit(consoleErrors); res.json(truncatedLogs); }); app.get("/network-errors", (req, res) => { const truncatedLogs = truncateLogsToQueryLimit(networkErrors); res.json(truncatedLogs); }); app.get("/network-success", (req, res) => { const truncatedLogs = truncateLogsToQueryLimit(networkSuccess); res.json(truncatedLogs); }); app.get("/all-xhr", (req, res) => { // Merge and sort network success and error logs by timestamp const mergedLogs = [...networkSuccess, ...networkErrors].sort( (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime() ); const truncatedLogs = truncateLogsToQueryLimit(mergedLogs); res.json(truncatedLogs); }); // Add new endpoint for selected element app.post("/selected-element", (req, res) => { const { data } = req.body; selectedElement = data; res.json({ status: "ok" }); }); app.get("/selected-element", (req, res) => { res.json(selectedElement || { message: "No element selected" }); }); app.get("/.port", (req, res) => { res.send(PORT.toString()); }); // Add new identity endpoint with a unique signature app.get("/.identity", (req, res) => { res.json({ port: PORT, name: "browser-tools-server", version: "1.2.0", signature: "mcp-browser-connector-24x7", }); }); // Add function to clear all logs function clearAllLogs() { console.log("Wiping all logs..."); consoleLogs.length = 0; consoleErrors.length = 0; networkErrors.length = 0; networkSuccess.length = 0; allXhr.length = 0; selectedElement = null; console.log("All logs have been wiped"); } // Add endpoint to wipe logs app.post("/wipelogs", (req, res) => { clearAllLogs(); res.json({ status: "ok", message: "All logs cleared successfully" }); }); // Add endpoint for the extension to report the current URL app.post("/current-url", (req, res) => { console.log( "Received current URL update request:", JSON.stringify(req.body, null, 2) ); if (req.body && req.body.url) { const oldUrl = currentUrl; currentUrl = req.body.url; // Update the current tab ID if provided if (req.body.tabId) { const oldTabId = currentTabId; currentTabId = req.body.tabId; console.log(`Updated current tab ID: ${oldTabId} -> ${currentTabId}`); } // Log the source of the update if provided const source = req.body.source || "unknown"; const tabId = req.body.tabId || "unknown"; const timestamp = req.body.timestamp ? new Date(req.body.timestamp).toISOString() : "unknown"; console.log( `Updated current URL via dedicated endpoint: ${oldUrl} -> ${currentUrl}` ); console.log( `URL update details: source=${source}, tabId=${tabId}, timestamp=${timestamp}` ); res.json({ status: "ok", url: currentUrl, tabId: currentTabId, previousUrl: oldUrl, updated: oldUrl !== currentUrl, }); } else { console.log("No URL provided in current-url request"); res.status(400).json({ status: "error", message: "No URL provided" }); } }); // Add endpoint to get the current URL app.get("/current-url", (req, res) => { console.log("Current URL requested, returning:", currentUrl); res.json({ url: currentUrl }); }); interface ScreenshotMessage { type: "screenshot-data" | "screenshot-error"; data?: string; path?: string; error?: string; autoPaste?: boolean; } export class BrowserConnector { private wss: WebSocketServer; private activeConnection: WebSocket | null = null; private app: express.Application; private server: any; private urlRequestCallbacks: Map void> = new Map(); constructor(app: express.Application, server: any) { this.app = app; this.server = server; // Initialize WebSocket server using the existing HTTP server this.wss = new WebSocketServer({ noServer: true, path: "/extension-ws", }); // Register the capture-screenshot endpoint this.app.post( "/capture-screenshot", async (req: express.Request, res: express.Response) => { console.log( "Browser Connector: Received request to /capture-screenshot endpoint" ); console.log("Browser Connector: Request body:", req.body); console.log( "Browser Connector: Active WebSocket connection:", !!this.activeConnection ); await this.captureScreenshot(req, res); } ); // Set up accessibility audit endpoint this.setupAccessibilityAudit(); // Set up performance audit endpoint this.setupPerformanceAudit(); // Set up SEO audit endpoint this.setupSEOAudit(); // Set up Best Practices audit endpoint this.setupBestPracticesAudit(); // Handle upgrade requests for WebSocket this.server.on( "upgrade", (request: IncomingMessage, socket: Socket, head: Buffer) => { if (request.url === "/extension-ws") { this.wss.handleUpgrade(request, socket, head, (ws: WebSocket) => { this.wss.emit("connection", ws, request); }); } } ); this.wss.on("connection", (ws: WebSocket) => { console.log("Chrome extension connected via WebSocket"); this.activeConnection = ws; ws.on("message", (message: string | Buffer | ArrayBuffer | Buffer[]) => { try { const data = JSON.parse(message.toString()); // Log message without the base64 data console.log("Received WebSocket message:", { ...data, data: data.data ? "[base64 data]" : undefined, }); // Handle URL response if (data.type === "current-url-response" && data.url) { console.log("Received current URL from browser:", data.url); currentUrl = data.url; // Also update the tab ID if provided if (data.tabId) { console.log( "Updating tab ID from WebSocket message:", data.tabId ); currentTabId = data.tabId; } // Call the callback if exists if ( data.requestId && this.urlRequestCallbacks.has(data.requestId) ) { const callback = this.urlRequestCallbacks.get(data.requestId); if (callback) callback(data.url); this.urlRequestCallbacks.delete(data.requestId); } } // Handle page navigation event via WebSocket // Note: This is intentionally duplicated from the HTTP handler in /extension-log // as the extension may send navigation events through either channel if (data.type === "page-navigated" && data.url) { console.log("Page navigated to:", data.url); currentUrl = data.url; // Also update the tab ID if provided if (data.tabId) { console.log( "Updating tab ID from page navigation event:", data.tabId ); currentTabId = data.tabId; } } // Handle screenshot response if (data.type === "screenshot-data" && data.data) { console.log("Received screenshot data"); console.log("Screenshot path from extension:", data.path); console.log("Auto-paste setting from extension:", data.autoPaste); // Get the most recent callback since we're not using requestId anymore const callbacks = Array.from(screenshotCallbacks.values()); if (callbacks.length > 0) { const callback = callbacks[0]; console.log("Found callback, resolving promise"); // Pass both the data, path and autoPaste to the resolver callback.resolve({ data: data.data, path: data.path, autoPaste: data.autoPaste, }); screenshotCallbacks.clear(); // Clear all callbacks } else { console.log("No callbacks found for screenshot"); } } // Handle screenshot error else if (data.type === "screenshot-error") { console.log("Received screenshot error:", data.error); const callbacks = Array.from(screenshotCallbacks.values()); if (callbacks.length > 0) { const callback = callbacks[0]; callback.reject( new Error(data.error || "Screenshot capture failed") ); screenshotCallbacks.clear(); // Clear all callbacks } } else { console.log("Unhandled message type:", data.type); } } catch (error) { console.error("Error processing WebSocket message:", error); } }); ws.on("close", () => { console.log("Chrome extension disconnected"); if (this.activeConnection === ws) { this.activeConnection = null; } }); }); // Add screenshot endpoint this.app.post( "/screenshot", (req: express.Request, res: express.Response): void => { console.log( "Browser Connector: Received request to /screenshot endpoint" ); console.log("Browser Connector: Request body:", req.body); try { console.log("Received screenshot capture request"); const { data, path: outputPath } = req.body; if (!data) { console.log("Screenshot request missing data"); res.status(400).json({ error: "Missing screenshot data" }); return; } // Use provided path or default to downloads folder const targetPath = outputPath || getDefaultDownloadsFolder(); console.log(`Using screenshot path: ${targetPath}`); // Remove the data:image/png;base64, prefix const base64Data = data.replace(/^data:image\/png;base64,/, ""); // Create the full directory path if it doesn't exist fs.mkdirSync(targetPath, { recursive: true }); console.log(`Created/verified directory: ${targetPath}`); // Generate a unique filename using timestamp const timestamp = new Date().toISOString().replace(/[:.]/g, "-"); const filename = `screenshot-${timestamp}.png`; const fullPath = path.join(targetPath, filename); console.log(`Saving screenshot to: ${fullPath}`); // Write the file fs.writeFileSync(fullPath, base64Data, "base64"); console.log("Screenshot saved successfully"); res.json({ path: fullPath, filename: filename, }); } catch (error: unknown) { console.error("Error saving screenshot:", error); if (error instanceof Error) { res.status(500).json({ error: error.message }); } else { res.status(500).json({ error: "An unknown error occurred" }); } } } ); } private async handleScreenshot(req: express.Request, res: express.Response) { if (!this.activeConnection) { return res.status(503).json({ error: "Chrome extension not connected" }); } try { const result = await new Promise((resolve, reject) => { // Set up one-time message handler for this screenshot request const messageHandler = ( message: string | Buffer | ArrayBuffer | Buffer[] ) => { try { const response: ScreenshotMessage = JSON.parse(message.toString()); if (response.type === "screenshot-error") { reject(new Error(response.error)); return; } if ( response.type === "screenshot-data" && response.data && response.path ) { // Remove the data:image/png;base64, prefix const base64Data = response.data.replace( /^data:image\/png;base64,/, "" ); // Ensure the directory exists const dir = path.dirname(response.path); fs.mkdirSync(dir, { recursive: true }); // Generate a unique filename using timestamp const timestamp = new Date().toISOString().replace(/[:.]/g, "-"); const filename = `screenshot-${timestamp}.png`; const fullPath = path.join(response.path, filename); // Write the file fs.writeFileSync(fullPath, base64Data, "base64"); resolve({ path: fullPath, filename: filename, }); } } catch (error) { reject(error); } finally { this.activeConnection?.removeListener("message", messageHandler); } }; // Add temporary message handler this.activeConnection?.on("message", messageHandler); // Request screenshot this.activeConnection?.send( JSON.stringify({ type: "take-screenshot" }) ); // Set timeout setTimeout(() => { this.activeConnection?.removeListener("message", messageHandler); reject(new Error("Screenshot timeout")); }, 30000); // 30 second timeout }); res.json(result); } catch (error: unknown) { if (error instanceof Error) { res.status(500).json({ error: error.message }); } else { res.status(500).json({ error: "An unknown error occurred" }); } } } // Updated method to get URL for audits with improved connection tracking and waiting private async getUrlForAudit(): Promise { try { console.log("getUrlForAudit called"); // Use the stored URL if available immediately if (currentUrl && currentUrl !== "" && currentUrl !== "about:blank") { console.log(`Using existing URL immediately: ${currentUrl}`); return currentUrl; } // Wait for a URL to become available (retry loop) console.log("No valid URL available yet, waiting for navigation..."); // Wait up to 10 seconds for a URL to be set (20 attempts x 500ms) const maxAttempts = 50; const waitTime = 500; // ms for (let attempt = 0; attempt < maxAttempts; attempt++) { // Check if URL is available now if (currentUrl && currentUrl !== "" && currentUrl !== "about:blank") { console.log(`URL became available after waiting: ${currentUrl}`); return currentUrl; } // Wait before checking again console.log( `Waiting for URL (attempt ${attempt + 1}/${maxAttempts})...` ); await new Promise((resolve) => setTimeout(resolve, waitTime)); } // If we reach here, no URL became available after waiting console.log("Timed out waiting for URL, returning null"); return null; } catch (error) { console.error("Error in getUrlForAudit:", error); return null; // Return null to trigger an error } } // Public method to check if there's an active connection public hasActiveConnection(): boolean { return this.activeConnection !== null; } // Add new endpoint for programmatic screenshot capture async captureScreenshot(req: express.Request, res: express.Response) { console.log("Browser Connector: Starting captureScreenshot method"); console.log("Browser Connector: Request headers:", req.headers); console.log("Browser Connector: Request method:", req.method); if (!this.activeConnection) { console.log( "Browser Connector: No active WebSocket connection to Chrome extension" ); return res.status(503).json({ error: "Chrome extension not connected" }); } try { console.log("Browser Connector: Starting screenshot capture..."); const requestId = Date.now().toString(); console.log("Browser Connector: Generated requestId:", requestId); // Create promise that will resolve when we get the screenshot data const screenshotPromise = new Promise<{ data: string; path?: string; autoPaste?: boolean; }>((resolve, reject) => { console.log( `Browser Connector: Setting up screenshot callback for requestId: ${requestId}` ); // Store callback in map screenshotCallbacks.set(requestId, { resolve, reject }); console.log( "Browser Connector: Current callbacks:", Array.from(screenshotCallbacks.keys()) ); // Set timeout to clean up if we don't get a response setTimeout(() => { if (screenshotCallbacks.has(requestId)) { console.log( `Browser Connector: Screenshot capture timed out for requestId: ${requestId}` ); screenshotCallbacks.delete(requestId); reject( new Error( "Screenshot capture timed out - no response from Chrome extension" ) ); } }, 10000); }); // Send screenshot request to extension const message = JSON.stringify({ type: "take-screenshot", requestId: requestId, }); console.log( `Browser Connector: Sending WebSocket message to extension:`, message ); this.activeConnection.send(message); // Wait for screenshot data console.log("Browser Connector: Waiting for screenshot data..."); const { data: base64Data, path: customPath, autoPaste, } = await screenshotPromise; console.log("Browser Connector: Received screenshot data, saving..."); console.log("Browser Connector: Custom path from extension:", customPath); console.log("Browser Connector: Auto-paste setting:", autoPaste); // Always prioritize the path from the Chrome extension let targetPath = customPath; // If no path provided by extension, fall back to defaults if (!targetPath) { targetPath = currentSettings.screenshotPath || getDefaultDownloadsFolder(); } // Convert the path for the current platform targetPath = convertPathForCurrentPlatform(targetPath); console.log(`Browser Connector: Using path: ${targetPath}`); if (!base64Data) { throw new Error("No screenshot data received from Chrome extension"); } try { fs.mkdirSync(targetPath, { recursive: true }); console.log(`Browser Connector: Created directory: ${targetPath}`); } catch (err) { console.error( `Browser Connector: Error creating directory: ${targetPath}`, err ); throw new Error( `Failed to create screenshot directory: ${ err instanceof Error ? err.message : String(err) }` ); } const timestamp = new Date().toISOString().replace(/[:.]/g, "-"); const filename = `screenshot-${timestamp}.png`; const fullPath = path.join(targetPath, filename); console.log(`Browser Connector: Full screenshot path: ${fullPath}`); // Remove the data:image/png;base64, prefix if present const cleanBase64 = base64Data.replace(/^data:image\/png;base64,/, ""); // Save the file try { fs.writeFileSync(fullPath, cleanBase64, "base64"); console.log(`Browser Connector: Screenshot saved to: ${fullPath}`); } catch (err) { console.error( `Browser Connector: Error saving screenshot to: ${fullPath}`, err ); throw new Error( `Failed to save screenshot: ${ err instanceof Error ? err.message : String(err) }` ); } // Check if running on macOS before executing AppleScript if (os.platform() === "darwin" && autoPaste === true) { console.log( "Browser Connector: Running on macOS with auto-paste enabled, executing AppleScript to paste into Cursor" ); // Create the AppleScript to copy the image to clipboard and paste into Cursor // This version is more robust and includes debugging const appleScript = ` -- Set path to the screenshot set imagePath to "${fullPath}" -- Copy the image to clipboard try set the clipboard to (read (POSIX file imagePath) as «class PNGf») on error errMsg log "Error copying image to clipboard: " & errMsg return "Failed to copy image to clipboard: " & errMsg end try -- Activate Cursor application try tell application "Cursor" activate end tell on error errMsg log "Error activating Cursor: " & errMsg return "Failed to activate Cursor: " & errMsg end try -- Wait for the application to fully activate delay 3 -- Try to interact with Cursor try tell application "System Events" tell process "Cursor" -- Get the frontmost window if (count of windows) is 0 then return "No windows found in Cursor" end if set cursorWindow to window 1 -- Try Method 1: Look for elements of class "Text Area" set foundElements to {} -- Try different selectors to find the text input area try -- Try with class set textAreas to UI elements of cursorWindow whose class is "Text Area" if (count of textAreas) > 0 then set foundElements to textAreas end if end try if (count of foundElements) is 0 then try -- Try with AXTextField role set textFields to UI elements of cursorWindow whose role is "AXTextField" if (count of textFields) > 0 then set foundElements to textFields end if end try end if if (count of foundElements) is 0 then try -- Try with AXTextArea role in nested elements set allElements to UI elements of cursorWindow repeat with anElement in allElements try set childElements to UI elements of anElement repeat with aChild in childElements try if role of aChild is "AXTextArea" or role of aChild is "AXTextField" then set end of foundElements to aChild end if end try end repeat end try end repeat end try end if -- If no elements found with specific attributes, try a broader approach if (count of foundElements) is 0 then -- Just try to use the Command+V shortcut on the active window -- This assumes Cursor already has focus on the right element keystroke "v" using command down delay 1 keystroke "here is the screenshot" delay 1 -- Try multiple methods to press Enter key code 36 -- Use key code for Return key delay 0.5 keystroke return -- Use keystroke return as alternative return "Used fallback method: Command+V on active window" else -- We found a potential text input element set inputElement to item 1 of foundElements -- Try to focus and paste try set focused of inputElement to true delay 0.5 -- Paste the image keystroke "v" using command down delay 1 -- Type the text keystroke "here is the screenshot" delay 1 -- Try multiple methods to press Enter key code 36 -- Use key code for Return key delay 0.5 keystroke return -- Use keystroke return as alternative return "Successfully pasted screenshot into Cursor text element" on error errMsg log "Error interacting with found element: " & errMsg -- Fallback to just sending the key commands keystroke "v" using command down delay 1 keystroke "here is the screenshot" delay 1 -- Try multiple methods to press Enter key code 36 -- Use key code for Return key delay 0.5 keystroke return -- Use keystroke return as alternative return "Used fallback after element focus error: " & errMsg end try end if end tell end tell on error errMsg log "Error in System Events block: " & errMsg return "Failed in System Events: " & errMsg end try `; // Execute the AppleScript exec(`osascript -e '${appleScript}'`, (error, stdout, stderr) => { if (error) { console.error( `Browser Connector: Error executing AppleScript: ${error.message}` ); console.error(`Browser Connector: stderr: ${stderr}`); // Don't fail the response; log the error and proceed } else { console.log(`Browser Connector: AppleScript executed successfully`); console.log(`Browser Connector: stdout: ${stdout}`); } }); } else { if (os.platform() === "darwin" && !autoPaste) { console.log( `Browser Connector: Running on macOS but auto-paste is disabled, skipping AppleScript execution` ); } else { console.log( `Browser Connector: Not running on macOS, skipping AppleScript execution` ); } } res.json({ path: fullPath, filename: filename, }); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); console.error( "Browser Connector: Error capturing screenshot:", errorMessage ); res.status(500).json({ error: errorMessage, }); } } // Add shutdown method public shutdown() { return new Promise((resolve) => { console.log("Shutting down WebSocket server..."); // Send close message to client if connection is active if ( this.activeConnection && this.activeConnection.readyState === WebSocket.OPEN ) { console.log("Notifying client to close connection..."); try { this.activeConnection.send( JSON.stringify({ type: "server-shutdown" }) ); } catch (err) { console.error("Error sending shutdown message to client:", err); } } // Set a timeout to force close after 2 seconds const forceCloseTimeout = setTimeout(() => { console.log("Force closing connections after timeout..."); if (this.activeConnection) { this.activeConnection.terminate(); // Force close the connection this.activeConnection = null; } this.wss.close(); resolve(); }, 2000); // Close active WebSocket connection if exists if (this.activeConnection) { this.activeConnection.close(1000, "Server shutting down"); this.activeConnection = null; } // Close WebSocket server this.wss.close(() => { clearTimeout(forceCloseTimeout); console.log("WebSocket server closed gracefully"); resolve(); }); }); } // Sets up the accessibility audit endpoint private setupAccessibilityAudit() { this.setupAuditEndpoint( AuditCategory.ACCESSIBILITY, "/accessibility-audit", runAccessibilityAudit ); } // Sets up the performance audit endpoint private setupPerformanceAudit() { this.setupAuditEndpoint( AuditCategory.PERFORMANCE, "/performance-audit", runPerformanceAudit ); } // Set up SEO audit endpoint private setupSEOAudit() { this.setupAuditEndpoint(AuditCategory.SEO, "/seo-audit", runSEOAudit); } // Add a setup method for Best Practices audit private setupBestPracticesAudit() { this.setupAuditEndpoint( AuditCategory.BEST_PRACTICES, "/best-practices-audit", runBestPracticesAudit ); } /** * Generic method to set up an audit endpoint * @param auditType The type of audit (accessibility, performance, SEO) * @param endpoint The endpoint path * @param auditFunction The audit function to call */ private setupAuditEndpoint( auditType: string, endpoint: string, auditFunction: (url: string) => Promise ) { // Add server identity validation endpoint this.app.get("/.identity", (req, res) => { res.json({ signature: "mcp-browser-connector-24x7", version: "1.2.0", }); }); this.app.post(endpoint, async (req: any, res: any) => { try { console.log(`${auditType} audit request received`); // Get URL using our helper method const url = await this.getUrlForAudit(); if (!url) { console.log(`No URL available for ${auditType} audit`); return res.status(400).json({ error: `URL is required for ${auditType} audit. Make sure you navigate to a page in the browser first, and the browser-tool extension tab is open.`, }); } // If we're using the stored URL (not from request body), log it now if (!req.body?.url && url === currentUrl) { console.log(`Using stored URL for ${auditType} audit:`, url); } // Check if we're using the default URL if (url === "about:blank") { console.log(`Cannot run ${auditType} audit on about:blank`); return res.status(400).json({ error: `Cannot run ${auditType} audit on about:blank`, }); } console.log(`Preparing to run ${auditType} audit for: ${url}`); // Run the audit using the provided function try { const result = await auditFunction(url); console.log(`${auditType} audit completed successfully`); // Return the results res.json(result); } catch (auditError) { console.error(`${auditType} audit failed:`, auditError); const errorMessage = auditError instanceof Error ? auditError.message : String(auditError); res.status(500).json({ error: `Failed to run ${auditType} audit: ${errorMessage}`, }); } } catch (error) { console.error(`Error in ${auditType} audit endpoint:`, error); const errorMessage = error instanceof Error ? error.message : String(error); res.status(500).json({ error: `Error in ${auditType} audit endpoint: ${errorMessage}`, }); } }); } } // Use an async IIFE to allow for async/await in the initial setup (async () => { try { console.log(`Starting Browser Tools Server...`); console.log(`Requested port: ${REQUESTED_PORT}`); // Find an available port try { PORT = await getAvailablePort(REQUESTED_PORT); if (PORT !== REQUESTED_PORT) { console.log(`\n====================================`); console.log(`NOTICE: Requested port ${REQUESTED_PORT} was in use.`); console.log(`Using port ${PORT} instead.`); console.log(`====================================\n`); } } catch (portError) { console.error(`Failed to find an available port:`, portError); process.exit(1); } // Create the server with the available port const server = app.listen(PORT, currentSettings.serverHost, () => { console.log(`\n=== Browser Tools Server Started ===`); console.log( `Aggregator listening on http://${currentSettings.serverHost}:${PORT}` ); if (PORT !== REQUESTED_PORT) { console.log( `NOTE: Using fallback port ${PORT} instead of requested port ${REQUESTED_PORT}` ); } // Log all available network interfaces for easier discovery const networkInterfaces = os.networkInterfaces(); console.log("\nAvailable on the following network addresses:"); Object.keys(networkInterfaces).forEach((interfaceName) => { const interfaces = networkInterfaces[interfaceName]; if (interfaces) { interfaces.forEach((iface) => { if (!iface.internal && iface.family === "IPv4") { console.log(` - http://${iface.address}:${PORT}`); } }); } }); console.log(`\nFor local access use: http://localhost:${PORT}`); }); // Handle server startup errors server.on("error", (err: any) => { if (err.code === "EADDRINUSE") { console.error( `ERROR: Port ${PORT} is still in use, despite our checks!` ); console.error( `This might indicate another process started using this port after our check.` ); } else { console.error(`Server error:`, err); } process.exit(1); }); // Initialize the browser connector with the existing app AND server const browserConnector = new BrowserConnector(app, server); // Handle shutdown gracefully with improved error handling process.on("SIGINT", async () => { console.log("\nReceived SIGINT signal. Starting graceful shutdown..."); try { // First shutdown WebSocket connections await browserConnector.shutdown(); // Then close the HTTP server await new Promise((resolve, reject) => { server.close((err) => { if (err) { console.error("Error closing HTTP server:", err); reject(err); } else { console.log("HTTP server closed successfully"); resolve(); } }); }); // Clear all logs clearAllLogs(); console.log("Shutdown completed successfully"); process.exit(0); } catch (error) { console.error("Error during shutdown:", error); // Force exit in case of error process.exit(1); } }); // Also handle SIGTERM process.on("SIGTERM", () => { console.log("\nReceived SIGTERM signal"); process.emit("SIGINT"); }); } catch (error) { console.error("Failed to start server:", error); process.exit(1); } })().catch((err) => { console.error("Unhandled error during server startup:", err); process.exit(1); }); ================================================ FILE: browser-tools-server/lighthouse/accessibility.ts ================================================ import { Result as LighthouseResult } from "lighthouse"; import { AuditCategory, LighthouseReport } from "./types.js"; import { runLighthouseAudit } from "./index.js"; // === Accessibility Report Types === /** * Accessibility-specific report content structure */ export interface AccessibilityReportContent { score: number; // Overall score (0-100) audit_counts: { // Counts of different audit types failed: number; passed: number; manual: number; informative: number; not_applicable: number; }; issues: AIAccessibilityIssue[]; categories: { [category: string]: { score: number; issues_count: number; }; }; critical_elements: AIAccessibilityElement[]; prioritized_recommendations?: string[]; // Ordered list of recommendations } /** * Full accessibility report implementing the base LighthouseReport interface */ export type AIOptimizedAccessibilityReport = LighthouseReport; /** * AI-optimized accessibility issue */ interface AIAccessibilityIssue { id: string; // e.g., "color-contrast" title: string; // e.g., "Color contrast is sufficient" impact: "critical" | "serious" | "moderate" | "minor"; category: string; // e.g., "contrast", "aria", "forms", "keyboard" elements?: AIAccessibilityElement[]; // Elements with issues score: number | null; // 0-1 or null } /** * Accessibility element with issues */ interface AIAccessibilityElement { selector: string; // CSS selector snippet?: string; // HTML snippet label?: string; // Element label issue_description?: string; // Description of the issue value?: string | number; // Current value (e.g., contrast ratio) } // Original interfaces for backward compatibility interface AccessibilityAudit { id: string; // e.g., "color-contrast" title: string; // e.g., "Color contrast is sufficient" description: string; // e.g., "Ensures text is readable..." score: number | null; // 0-1 (normalized), null for manual/informative scoreDisplayMode: string; // e.g., "binary", "numeric", "manual" details?: AuditDetails; // Optional, structured details weight?: number; // Optional, audit weight for impact calculation } type AuditDetails = { items?: Array<{ node?: { selector: string; // e.g., ".my-class" snippet?: string; // HTML snippet nodeLabel?: string; // e.g., "Modify logging size limits / truncation" explanation?: string; // Explanation of why the node fails the audit }; value?: string | number; // Specific value (e.g., contrast ratio) explanation?: string; // Explanation at the item level }>; debugData?: string; // Optional, debug information [key: string]: any; // Flexible for other detail types (tables, etc.) }; // Original limits were optimized for human consumption // This ensures we always include critical issues while limiting less important ones const DETAIL_LIMITS = { critical: Number.MAX_SAFE_INTEGER, // No limit for critical issues serious: 15, // Up to 15 items for serious issues moderate: 10, // Up to 10 items for moderate issues minor: 3, // Up to 3 items for minor issues }; /** * Runs an accessibility audit on the specified URL * @param url The URL to audit * @returns Promise resolving to AI-optimized accessibility audit results */ export async function runAccessibilityAudit( url: string ): Promise { try { const lhr = await runLighthouseAudit(url, [AuditCategory.ACCESSIBILITY]); return extractAIOptimizedData(lhr, url); } catch (error) { throw new Error( `Accessibility audit failed: ${ error instanceof Error ? error.message : String(error) }` ); } } /** * Extract AI-optimized accessibility data from Lighthouse results */ const extractAIOptimizedData = ( lhr: LighthouseResult, url: string ): AIOptimizedAccessibilityReport => { const categoryData = lhr.categories[AuditCategory.ACCESSIBILITY]; const audits = lhr.audits || {}; // Add metadata const metadata = { url, timestamp: lhr.fetchTime || new Date().toISOString(), device: "desktop", // This could be made configurable lighthouseVersion: lhr.lighthouseVersion, }; // Initialize variables const issues: AIAccessibilityIssue[] = []; const criticalElements: AIAccessibilityElement[] = []; const categories: { [category: string]: { score: number; issues_count: number }; } = {}; // Count audits by type let failedCount = 0; let passedCount = 0; let manualCount = 0; let informativeCount = 0; let notApplicableCount = 0; // Process audit refs const auditRefs = categoryData?.auditRefs || []; // First pass: count audits by type and initialize categories auditRefs.forEach((ref) => { const audit = audits[ref.id]; if (!audit) return; // Count by scoreDisplayMode if (audit.scoreDisplayMode === "manual") { manualCount++; } else if (audit.scoreDisplayMode === "informative") { informativeCount++; } else if (audit.scoreDisplayMode === "notApplicable") { notApplicableCount++; } else if (audit.score !== null) { // Binary pass/fail if (audit.score >= 0.9) { passedCount++; } else { failedCount++; } } // Process categories if (ref.group) { // Initialize category if not exists if (!categories[ref.group]) { categories[ref.group] = { score: 0, issues_count: 0 }; } // Update category score and issues count if (audit.score !== null && audit.score < 0.9) { categories[ref.group].issues_count++; } } }); // Second pass: process failed audits into AI-friendly format auditRefs .filter((ref) => { const audit = audits[ref.id]; return audit && audit.score !== null && audit.score < 0.9; }) .sort((a, b) => (b.weight || 0) - (a.weight || 0)) // No limit on number of failed audits - we'll show them all .forEach((ref) => { const audit = audits[ref.id]; // Determine impact level based on score and weight let impact: "critical" | "serious" | "moderate" | "minor" = "moderate"; if (audit.score === 0) { impact = "critical"; } else if (audit.score !== null && audit.score <= 0.5) { impact = "serious"; } else if (audit.score !== null && audit.score > 0.7) { impact = "minor"; } // Create elements array const elements: AIAccessibilityElement[] = []; if (audit.details) { const details = audit.details as any; if (details.items && Array.isArray(details.items)) { const items = details.items; // Apply limits based on impact level const itemLimit = DETAIL_LIMITS[impact]; items.slice(0, itemLimit).forEach((item: any) => { if (item.node) { const element: AIAccessibilityElement = { selector: item.node.selector, snippet: item.node.snippet, label: item.node.nodeLabel, issue_description: item.node.explanation || item.explanation, }; if (item.value !== undefined) { element.value = item.value; } elements.push(element); // Add to critical elements if impact is critical or serious if (impact === "critical" || impact === "serious") { criticalElements.push(element); } } }); } } // Create the issue const issue: AIAccessibilityIssue = { id: ref.id, title: audit.title, impact, category: ref.group || "other", elements: elements.length > 0 ? elements : undefined, score: audit.score, }; issues.push(issue); }); // Calculate overall score const score = Math.round((categoryData?.score || 0) * 100); // Generate prioritized recommendations const prioritized_recommendations: string[] = []; // Add category-specific recommendations Object.entries(categories) .filter(([_, data]) => data.issues_count > 0) .sort(([_, a], [__, b]) => b.issues_count - a.issues_count) .forEach(([category, data]) => { let recommendation = ""; switch (category) { case "a11y-color-contrast": recommendation = "Improve color contrast for better readability"; break; case "a11y-names-labels": recommendation = "Add proper labels to all interactive elements"; break; case "a11y-aria": recommendation = "Fix ARIA attributes and roles"; break; case "a11y-navigation": recommendation = "Improve keyboard navigation and focus management"; break; case "a11y-language": recommendation = "Add proper language attributes to HTML"; break; case "a11y-tables-lists": recommendation = "Fix table and list structures for screen readers"; break; default: recommendation = `Fix ${data.issues_count} issues in ${category}`; } prioritized_recommendations.push(recommendation); }); // Add specific high-impact recommendations if (issues.some((issue) => issue.id === "color-contrast")) { prioritized_recommendations.push( "Fix low contrast text for better readability" ); } if (issues.some((issue) => issue.id === "document-title")) { prioritized_recommendations.push("Add a descriptive page title"); } if (issues.some((issue) => issue.id === "image-alt")) { prioritized_recommendations.push("Add alt text to all images"); } // Create the report content const reportContent: AccessibilityReportContent = { score, audit_counts: { failed: failedCount, passed: passedCount, manual: manualCount, informative: informativeCount, not_applicable: notApplicableCount, }, issues, categories, critical_elements: criticalElements, prioritized_recommendations: prioritized_recommendations.length > 0 ? prioritized_recommendations : undefined, }; // Return the full report following the LighthouseReport interface return { metadata, report: reportContent, }; }; ================================================ FILE: browser-tools-server/lighthouse/best-practices.ts ================================================ import { Result as LighthouseResult } from "lighthouse"; import { AuditCategory, LighthouseReport } from "./types.js"; import { runLighthouseAudit } from "./index.js"; // === Best Practices Report Types === /** * Best Practices-specific report content structure */ export interface BestPracticesReportContent { score: number; // Overall score (0-100) audit_counts: { // Counts of different audit types failed: number; passed: number; manual: number; informative: number; not_applicable: number; }; issues: AIBestPracticesIssue[]; categories: { [category: string]: { score: number; issues_count: number; }; }; prioritized_recommendations?: string[]; // Ordered list of recommendations } /** * Full Best Practices report implementing the base LighthouseReport interface */ export type AIOptimizedBestPracticesReport = LighthouseReport; /** * AI-optimized Best Practices issue */ interface AIBestPracticesIssue { id: string; // e.g., "js-libraries" title: string; // e.g., "Detected JavaScript libraries" impact: "critical" | "serious" | "moderate" | "minor"; category: string; // e.g., "security", "trust", "user-experience", "browser-compat" details?: { name?: string; // Name of the item (e.g., library name, vulnerability) version?: string; // Version information if applicable value?: string; // Current value or status issue?: string; // Description of the issue }[]; score: number | null; // 0-1 or null } // Original interfaces for backward compatibility interface BestPracticesAudit { id: string; title: string; description: string; score: number | null; scoreDisplayMode: string; details?: BestPracticesAuditDetails; } interface BestPracticesAuditDetails { items?: Array>; type?: string; // e.g., "table" } // This ensures we always include critical issues while limiting less important ones const DETAIL_LIMITS: Record = { critical: Number.MAX_SAFE_INTEGER, // No limit for critical issues serious: 15, // Up to 15 items for serious issues moderate: 10, // Up to 10 items for moderate issues minor: 3, // Up to 3 items for minor issues }; /** * Runs a Best Practices audit on the specified URL * @param url The URL to audit * @returns Promise resolving to AI-optimized Best Practices audit results */ export async function runBestPracticesAudit( url: string ): Promise { try { const lhr = await runLighthouseAudit(url, [AuditCategory.BEST_PRACTICES]); return extractAIOptimizedData(lhr, url); } catch (error) { throw new Error( `Best Practices audit failed: ${ error instanceof Error ? error.message : String(error) }` ); } } /** * Extract AI-optimized Best Practices data from Lighthouse results */ const extractAIOptimizedData = ( lhr: LighthouseResult, url: string ): AIOptimizedBestPracticesReport => { const categoryData = lhr.categories[AuditCategory.BEST_PRACTICES]; const audits = lhr.audits || {}; // Add metadata const metadata = { url, timestamp: lhr.fetchTime || new Date().toISOString(), device: lhr.configSettings?.formFactor || "desktop", lighthouseVersion: lhr.lighthouseVersion || "unknown", }; // Process audit results const issues: AIBestPracticesIssue[] = []; const categories: { [key: string]: { score: number; issues_count: number } } = { security: { score: 0, issues_count: 0 }, trust: { score: 0, issues_count: 0 }, "user-experience": { score: 0, issues_count: 0 }, "browser-compat": { score: 0, issues_count: 0 }, other: { score: 0, issues_count: 0 }, }; // Counters for audit types let failedCount = 0; let passedCount = 0; let manualCount = 0; let informativeCount = 0; let notApplicableCount = 0; // Process failed audits (score < 1) const failedAudits = Object.entries(audits) .filter(([, audit]) => { const score = audit.score; return ( score !== null && score < 1 && audit.scoreDisplayMode !== "manual" && audit.scoreDisplayMode !== "notApplicable" ); }) .map(([auditId, audit]) => ({ auditId, ...audit })); // Update counters Object.values(audits).forEach((audit) => { const { score, scoreDisplayMode } = audit; if (scoreDisplayMode === "manual") { manualCount++; } else if (scoreDisplayMode === "informative") { informativeCount++; } else if (scoreDisplayMode === "notApplicable") { notApplicableCount++; } else if (score === 1) { passedCount++; } else if (score !== null && score < 1) { failedCount++; } }); // Process failed audits into AI-friendly format failedAudits.forEach((ref: any) => { // Determine impact level based on audit score and weight let impact: "critical" | "serious" | "moderate" | "minor" = "moderate"; const score = ref.score || 0; // Use a more reliable approach to determine impact if (score === 0) { impact = "critical"; } else if (score < 0.5) { impact = "serious"; } else if (score < 0.9) { impact = "moderate"; } else { impact = "minor"; } // Categorize the issue let category = "other"; // Security-related issues if ( ref.auditId.includes("csp") || ref.auditId.includes("security") || ref.auditId.includes("vulnerab") || ref.auditId.includes("password") || ref.auditId.includes("cert") || ref.auditId.includes("deprecat") ) { category = "security"; } // Trust and legitimacy issues else if ( ref.auditId.includes("doctype") || ref.auditId.includes("charset") || ref.auditId.includes("legit") || ref.auditId.includes("trust") ) { category = "trust"; } // User experience issues else if ( ref.auditId.includes("user") || ref.auditId.includes("experience") || ref.auditId.includes("console") || ref.auditId.includes("errors") || ref.auditId.includes("paste") ) { category = "user-experience"; } // Browser compatibility issues else if ( ref.auditId.includes("compat") || ref.auditId.includes("browser") || ref.auditId.includes("vendor") || ref.auditId.includes("js-lib") ) { category = "browser-compat"; } // Count issues by category categories[category].issues_count++; // Create issue object const issue: AIBestPracticesIssue = { id: ref.auditId, title: ref.title, impact, category, score: ref.score, details: [], }; // Extract details if available const refDetails = ref.details as BestPracticesAuditDetails | undefined; if (refDetails?.items && Array.isArray(refDetails.items)) { const itemLimit = DETAIL_LIMITS[impact]; const detailItems = refDetails.items.slice(0, itemLimit); detailItems.forEach((item: Record) => { issue.details = issue.details || []; // Different audits have different detail structures const detail: Record = {}; if (typeof item.name === "string") detail.name = item.name; if (typeof item.version === "string") detail.version = item.version; if (typeof item.issue === "string") detail.issue = item.issue; if (item.value !== undefined) detail.value = String(item.value); // For JS libraries, extract name and version if ( ref.auditId === "js-libraries" && typeof item.name === "string" && typeof item.version === "string" ) { detail.name = item.name; detail.version = item.version; } // Add other generic properties that might exist for (const [key, value] of Object.entries(item)) { if (!detail[key] && typeof value === "string") { detail[key] = value; } } issue.details.push(detail as any); }); } issues.push(issue); }); // Calculate category scores (0-100) Object.keys(categories).forEach((category) => { // Simplified scoring: if there are issues in this category, score is reduced proportionally const issueCount = categories[category].issues_count; if (issueCount > 0) { // More issues = lower score, max penalty of 25 points per issue const penalty = Math.min(100, issueCount * 25); categories[category].score = Math.max(0, 100 - penalty); } else { categories[category].score = 100; } }); // Generate prioritized recommendations const prioritized_recommendations: string[] = []; // Prioritize recommendations by category with most issues Object.entries(categories) .filter(([_, data]) => data.issues_count > 0) .sort(([_, a], [__, b]) => b.issues_count - a.issues_count) .forEach(([category, data]) => { let recommendation = ""; switch (category) { case "security": recommendation = `Address ${data.issues_count} security issues: vulnerabilities, CSP, deprecations`; break; case "trust": recommendation = `Fix ${data.issues_count} trust & legitimacy issues: doctype, charset`; break; case "user-experience": recommendation = `Improve ${data.issues_count} user experience issues: console errors, user interactions`; break; case "browser-compat": recommendation = `Resolve ${data.issues_count} browser compatibility issues: outdated libraries, vendor prefixes`; break; default: recommendation = `Fix ${data.issues_count} other best practice issues`; } prioritized_recommendations.push(recommendation); }); // Return the optimized report return { metadata, report: { score: categoryData?.score ? Math.round(categoryData.score * 100) : 0, audit_counts: { failed: failedCount, passed: passedCount, manual: manualCount, informative: informativeCount, not_applicable: notApplicableCount, }, issues, categories, prioritized_recommendations, }, }; }; ================================================ FILE: browser-tools-server/lighthouse/index.ts ================================================ import lighthouse from "lighthouse"; import type { Result as LighthouseResult, Flags } from "lighthouse"; import { connectToHeadlessBrowser, scheduleBrowserCleanup, } from "../puppeteer-service.js"; import { LighthouseConfig, AuditCategory } from "./types.js"; /** * Creates a Lighthouse configuration object * @param categories Array of categories to audit * @returns Lighthouse configuration and flags */ export function createLighthouseConfig( categories: string[] = [AuditCategory.ACCESSIBILITY] ): LighthouseConfig { return { flags: { output: ["json"], onlyCategories: categories, formFactor: "desktop", port: undefined as number | undefined, screenEmulation: { mobile: false, width: 1350, height: 940, deviceScaleFactor: 1, disabled: false, }, }, config: { extends: "lighthouse:default", settings: { onlyCategories: categories, emulatedFormFactor: "desktop", throttling: { cpuSlowdownMultiplier: 1 }, }, }, }; } /** * Runs a Lighthouse audit on the specified URL via CDP * @param url The URL to audit * @param categories Array of categories to audit, defaults to ["accessibility"] * @returns Promise resolving to the Lighthouse result * @throws Error if the URL is invalid or if the audit fails */ export async function runLighthouseAudit( url: string, categories: string[] ): Promise { console.log(`Starting Lighthouse ${categories.join(", ")} audit for: ${url}`); if (!url || url === "about:blank") { console.error("Invalid URL for Lighthouse audit"); throw new Error( "Cannot run audit on an empty page or about:blank. Please navigate to a valid URL first." ); } try { // Always use a dedicated headless browser for audits console.log("Using dedicated headless browser for audit"); // Determine if this is a performance audit - we need to load all resources for performance audits const isPerformanceAudit = categories.includes(AuditCategory.PERFORMANCE); // For performance audits, we want to load all resources // For accessibility or other audits, we can block non-essential resources try { const { port } = await connectToHeadlessBrowser(url, { blockResources: !isPerformanceAudit, }); console.log(`Connected to browser on port: ${port}`); // Create Lighthouse config const { flags, config } = createLighthouseConfig(categories); flags.port = port; console.log( `Running Lighthouse with categories: ${categories.join(", ")}` ); const runnerResult = await lighthouse(url, flags as Flags, config); console.log("Lighthouse scan completed"); if (!runnerResult?.lhr) { console.error("Lighthouse audit failed to produce results"); throw new Error("Lighthouse audit failed to produce results"); } // Schedule browser cleanup after a delay to allow for subsequent audits scheduleBrowserCleanup(); // Return the result const result = runnerResult.lhr; return result; } catch (browserError) { // Check if the error is related to Chrome/Edge not being available const errorMessage = browserError instanceof Error ? browserError.message : String(browserError); if ( errorMessage.includes("Chrome could not be found") || errorMessage.includes("Failed to launch browser") || errorMessage.includes("spawn ENOENT") ) { throw new Error( "Chrome or Edge browser could not be found. Please ensure that Chrome or Edge is installed on your system to run audits." ); } // Re-throw other errors throw browserError; } } catch (error) { console.error("Lighthouse audit failed:", error); // Schedule browser cleanup even if the audit fails scheduleBrowserCleanup(); throw new Error( `Lighthouse audit failed: ${ error instanceof Error ? error.message : String(error) }` ); } } // Export from specific audit modules export * from "./accessibility.js"; export * from "./performance.js"; export * from "./seo.js"; export * from "./types.js"; ================================================ FILE: browser-tools-server/lighthouse/performance.ts ================================================ import { Result as LighthouseResult } from "lighthouse"; import { AuditCategory, LighthouseReport } from "./types.js"; import { runLighthouseAudit } from "./index.js"; // === Performance Report Types === /** * Performance-specific report content structure */ export interface PerformanceReportContent { score: number; // Overall score (0-100) audit_counts: { // Counts of different audit types failed: number; passed: number; manual: number; informative: number; not_applicable: number; }; metrics: AIOptimizedMetric[]; opportunities: AIOptimizedOpportunity[]; page_stats?: AIPageStats; // Optional page statistics prioritized_recommendations?: string[]; // Ordered list of recommendations } /** * Full performance report implementing the base LighthouseReport interface */ export type AIOptimizedPerformanceReport = LighthouseReport; // AI-optimized performance metric format interface AIOptimizedMetric { id: string; // Short ID like "lcp", "fcp" score: number | null; // 0-1 score value_ms: number; // Value in milliseconds element_type?: string; // For LCP: "image", "text", etc. element_selector?: string; // DOM selector for the element element_url?: string; // For images/videos element_content?: string; // For text content (truncated) passes_core_web_vital?: boolean; // Whether this metric passes as a Core Web Vital } // AI-optimized opportunity format interface AIOptimizedOpportunity { id: string; // Like "render_blocking", "http2" savings_ms: number; // Time savings in ms severity?: "critical" | "serious" | "moderate" | "minor"; // Severity classification resources: Array<{ url: string; // Resource URL savings_ms?: number; // Individual resource savings size_kb?: number; // Size in KB type?: string; // Resource type (js, css, img, etc.) is_third_party?: boolean; // Whether this is a third-party resource }>; } // Page stats for AI analysis interface AIPageStats { total_size_kb: number; // Total page weight in KB total_requests: number; // Total number of requests resource_counts: { // Count by resource type js: number; css: number; img: number; font: number; other: number; }; third_party_size_kb: number; // Size of third-party resources main_thread_blocking_time_ms: number; // Time spent blocking the main thread } // This ensures we always include critical issues while limiting less important ones const DETAIL_LIMITS = { critical: Number.MAX_SAFE_INTEGER, // No limit for critical issues serious: 15, // Up to 15 items for serious issues moderate: 10, // Up to 10 items for moderate issues minor: 3, // Up to 3 items for minor issues }; /** * Performance audit adapted for AI consumption * This format is optimized for AI agents with: * - Concise, relevant information without redundant descriptions * - Key metrics and opportunities clearly structured * - Only actionable data that an AI can use for recommendations */ export async function runPerformanceAudit( url: string ): Promise { try { const lhr = await runLighthouseAudit(url, [AuditCategory.PERFORMANCE]); return extractAIOptimizedData(lhr, url); } catch (error) { throw new Error( `Performance audit failed: ${ error instanceof Error ? error.message : String(error) }` ); } } /** * Extract AI-optimized performance data from Lighthouse results */ const extractAIOptimizedData = ( lhr: LighthouseResult, url: string ): AIOptimizedPerformanceReport => { const audits = lhr.audits || {}; const categoryData = lhr.categories[AuditCategory.PERFORMANCE]; const score = Math.round((categoryData?.score || 0) * 100); // Add metadata const metadata = { url, timestamp: lhr.fetchTime || new Date().toISOString(), device: "desktop", // This could be made configurable lighthouseVersion: lhr.lighthouseVersion, }; // Count audits by type const auditRefs = categoryData?.auditRefs || []; let failedCount = 0; let passedCount = 0; let manualCount = 0; let informativeCount = 0; let notApplicableCount = 0; auditRefs.forEach((ref) => { const audit = audits[ref.id]; if (!audit) return; if (audit.scoreDisplayMode === "manual") { manualCount++; } else if (audit.scoreDisplayMode === "informative") { informativeCount++; } else if (audit.scoreDisplayMode === "notApplicable") { notApplicableCount++; } else if (audit.score !== null) { if (audit.score >= 0.9) { passedCount++; } else { failedCount++; } } }); const audit_counts = { failed: failedCount, passed: passedCount, manual: manualCount, informative: informativeCount, not_applicable: notApplicableCount, }; const metrics: AIOptimizedMetric[] = []; const opportunities: AIOptimizedOpportunity[] = []; // Extract core metrics if (audits["largest-contentful-paint"]) { const lcp = audits["largest-contentful-paint"]; const lcpElement = audits["largest-contentful-paint-element"]; const metric: AIOptimizedMetric = { id: "lcp", score: lcp.score, value_ms: Math.round(lcp.numericValue || 0), passes_core_web_vital: lcp.score !== null && lcp.score >= 0.9, }; // Enhanced LCP element detection // 1. Try from largest-contentful-paint-element audit if (lcpElement && lcpElement.details) { const lcpDetails = lcpElement.details as any; // First attempt - try to get directly from items if ( lcpDetails.items && Array.isArray(lcpDetails.items) && lcpDetails.items.length > 0 ) { const item = lcpDetails.items[0]; // For text elements in tables format if (item.type === "table" && item.items && item.items.length > 0) { const firstTableItem = item.items[0]; if (firstTableItem.node) { if (firstTableItem.node.selector) { metric.element_selector = firstTableItem.node.selector; } // Determine element type based on path or selector const path = firstTableItem.node.path; const selector = firstTableItem.node.selector || ""; if (path) { if ( selector.includes(" > img") || selector.includes(" img") || selector.endsWith("img") || path.includes(",IMG") ) { metric.element_type = "image"; // Try to extract image name from selector const imgMatch = selector.match(/img[.][^> ]+/); if (imgMatch && !metric.element_url) { metric.element_url = imgMatch[0]; } } else if ( path.includes(",SPAN") || path.includes(",P") || path.includes(",H") ) { metric.element_type = "text"; } } // Try to extract text content if available if (firstTableItem.node.nodeLabel) { metric.element_content = firstTableItem.node.nodeLabel.substring( 0, 100 ); } } } // Original handling for direct items else if (item.node?.nodeLabel) { // Determine element type from node label if (item.node.nodeLabel.startsWith(" 0 ) { const item = lcpImageDetails.items[0]; if (item.url) { metric.element_type = "image"; metric.element_url = item.url; } } } // 3. Try directly from the LCP audit details if (!metric.element_url && lcp.details) { const lcpDirectDetails = lcp.details as any; if (lcpDirectDetails.items && Array.isArray(lcpDirectDetails.items)) { for (const item of lcpDirectDetails.items) { if (item.url || (item.node && item.node.path)) { if (item.url) { metric.element_url = item.url; metric.element_type = item.url.match( /\.(jpg|jpeg|png|gif|webp|svg)$/i ) ? "image" : "resource"; } if (item.node && item.node.selector) { metric.element_selector = item.node.selector; } break; } } } } // 4. Check for specific audit that might contain image info const largestImageAudit = audits["largest-image-paint"]; if (largestImageAudit && largestImageAudit.details) { const imageDetails = largestImageAudit.details as any; if ( imageDetails.items && Array.isArray(imageDetails.items) && imageDetails.items.length > 0 ) { const item = imageDetails.items[0]; if (item.url) { // If we have a large image that's close in time to LCP, it's likely the LCP element metric.element_type = "image"; metric.element_url = item.url; } } } // 5. Check for network requests audit to find image resources if (!metric.element_url) { const networkRequests = audits["network-requests"]; if (networkRequests && networkRequests.details) { const networkDetails = networkRequests.details as any; if (networkDetails.items && Array.isArray(networkDetails.items)) { // Get all image resources loaded close to the LCP time const lcpTime = lcp.numericValue || 0; const imageResources = networkDetails.items .filter( (item: any) => item.url && item.mimeType && item.mimeType.startsWith("image/") && item.endTime && Math.abs(item.endTime - lcpTime) < 500 // Within 500ms of LCP ) .sort( (a: any, b: any) => Math.abs(a.endTime - lcpTime) - Math.abs(b.endTime - lcpTime) ); if (imageResources.length > 0) { const closestImage = imageResources[0]; if (!metric.element_type) { metric.element_type = "image"; metric.element_url = closestImage.url; } } } } } metrics.push(metric); } if (audits["first-contentful-paint"]) { const fcp = audits["first-contentful-paint"]; metrics.push({ id: "fcp", score: fcp.score, value_ms: Math.round(fcp.numericValue || 0), passes_core_web_vital: fcp.score !== null && fcp.score >= 0.9, }); } if (audits["speed-index"]) { const si = audits["speed-index"]; metrics.push({ id: "si", score: si.score, value_ms: Math.round(si.numericValue || 0), }); } if (audits["interactive"]) { const tti = audits["interactive"]; metrics.push({ id: "tti", score: tti.score, value_ms: Math.round(tti.numericValue || 0), }); } // Add CLS (Cumulative Layout Shift) if (audits["cumulative-layout-shift"]) { const cls = audits["cumulative-layout-shift"]; metrics.push({ id: "cls", score: cls.score, // CLS is not in ms, but a unitless value value_ms: Math.round((cls.numericValue || 0) * 1000) / 1000, // Convert to 3 decimal places passes_core_web_vital: cls.score !== null && cls.score >= 0.9, }); } // Add TBT (Total Blocking Time) if (audits["total-blocking-time"]) { const tbt = audits["total-blocking-time"]; metrics.push({ id: "tbt", score: tbt.score, value_ms: Math.round(tbt.numericValue || 0), passes_core_web_vital: tbt.score !== null && tbt.score >= 0.9, }); } // Extract opportunities if (audits["render-blocking-resources"]) { const rbrAudit = audits["render-blocking-resources"]; // Determine impact level based on potential savings let impact: "critical" | "serious" | "moderate" | "minor" = "moderate"; const savings = Math.round(rbrAudit.numericValue || 0); if (savings > 2000) { impact = "critical"; } else if (savings > 1000) { impact = "serious"; } else if (savings < 300) { impact = "minor"; } const opportunity: AIOptimizedOpportunity = { id: "render_blocking_resources", savings_ms: savings, severity: impact, resources: [], }; const rbrDetails = rbrAudit.details as any; if (rbrDetails && rbrDetails.items && Array.isArray(rbrDetails.items)) { // Determine how many items to include based on impact const itemLimit = DETAIL_LIMITS[impact]; rbrDetails.items .slice(0, itemLimit) .forEach((item: { url?: string; wastedMs?: number }) => { if (item.url) { // Extract file name from full URL const fileName = item.url.split("/").pop() || item.url; opportunity.resources.push({ url: fileName, savings_ms: Math.round(item.wastedMs || 0), }); } }); } if (opportunity.resources.length > 0) { opportunities.push(opportunity); } } if (audits["uses-http2"]) { const http2Audit = audits["uses-http2"]; // Determine impact level based on potential savings let impact: "critical" | "serious" | "moderate" | "minor" = "moderate"; const savings = Math.round(http2Audit.numericValue || 0); if (savings > 2000) { impact = "critical"; } else if (savings > 1000) { impact = "serious"; } else if (savings < 300) { impact = "minor"; } const opportunity: AIOptimizedOpportunity = { id: "http2", savings_ms: savings, severity: impact, resources: [], }; const http2Details = http2Audit.details as any; if ( http2Details && http2Details.items && Array.isArray(http2Details.items) ) { // Determine how many items to include based on impact const itemLimit = DETAIL_LIMITS[impact]; http2Details.items .slice(0, itemLimit) .forEach((item: { url?: string }) => { if (item.url) { // Extract file name from full URL const fileName = item.url.split("/").pop() || item.url; opportunity.resources.push({ url: fileName }); } }); } if (opportunity.resources.length > 0) { opportunities.push(opportunity); } } // After extracting all metrics and opportunities, collect page stats // Extract page stats let page_stats: AIPageStats | undefined; // Total page stats const totalByteWeight = audits["total-byte-weight"]; const networkRequests = audits["network-requests"]; const thirdPartyAudit = audits["third-party-summary"]; const mainThreadWork = audits["mainthread-work-breakdown"]; if (networkRequests && networkRequests.details) { const resourceDetails = networkRequests.details as any; if (resourceDetails.items && Array.isArray(resourceDetails.items)) { const resources = resourceDetails.items; const totalRequests = resources.length; // Calculate total size and counts by type let totalSizeKb = 0; let jsCount = 0, cssCount = 0, imgCount = 0, fontCount = 0, otherCount = 0; resources.forEach((resource: any) => { const sizeKb = resource.transferSize ? Math.round(resource.transferSize / 1024) : 0; totalSizeKb += sizeKb; // Count by mime type const mimeType = resource.mimeType || ""; if (mimeType.includes("javascript") || resource.url.endsWith(".js")) { jsCount++; } else if (mimeType.includes("css") || resource.url.endsWith(".css")) { cssCount++; } else if ( mimeType.includes("image") || /\.(jpg|jpeg|png|gif|webp|svg)$/i.test(resource.url) ) { imgCount++; } else if ( mimeType.includes("font") || /\.(woff|woff2|ttf|otf|eot)$/i.test(resource.url) ) { fontCount++; } else { otherCount++; } }); // Calculate third-party size let thirdPartySizeKb = 0; if (thirdPartyAudit && thirdPartyAudit.details) { const thirdPartyDetails = thirdPartyAudit.details as any; if (thirdPartyDetails.items && Array.isArray(thirdPartyDetails.items)) { thirdPartyDetails.items.forEach((item: any) => { if (item.transferSize) { thirdPartySizeKb += Math.round(item.transferSize / 1024); } }); } } // Get main thread blocking time let mainThreadBlockingTimeMs = 0; if (mainThreadWork && mainThreadWork.numericValue) { mainThreadBlockingTimeMs = Math.round(mainThreadWork.numericValue); } // Create page stats object page_stats = { total_size_kb: totalSizeKb, total_requests: totalRequests, resource_counts: { js: jsCount, css: cssCount, img: imgCount, font: fontCount, other: otherCount, }, third_party_size_kb: thirdPartySizeKb, main_thread_blocking_time_ms: mainThreadBlockingTimeMs, }; } } // Generate prioritized recommendations const prioritized_recommendations: string[] = []; // Add key recommendations based on failed audits with high impact if ( audits["render-blocking-resources"] && audits["render-blocking-resources"].score !== null && audits["render-blocking-resources"].score === 0 ) { prioritized_recommendations.push("Eliminate render-blocking resources"); } if ( audits["uses-responsive-images"] && audits["uses-responsive-images"].score !== null && audits["uses-responsive-images"].score === 0 ) { prioritized_recommendations.push("Properly size images"); } if ( audits["uses-optimized-images"] && audits["uses-optimized-images"].score !== null && audits["uses-optimized-images"].score === 0 ) { prioritized_recommendations.push("Efficiently encode images"); } if ( audits["uses-text-compression"] && audits["uses-text-compression"].score !== null && audits["uses-text-compression"].score === 0 ) { prioritized_recommendations.push("Enable text compression"); } if ( audits["uses-http2"] && audits["uses-http2"].score !== null && audits["uses-http2"].score === 0 ) { prioritized_recommendations.push("Use HTTP/2"); } // Add more specific recommendations based on Core Web Vitals if ( audits["largest-contentful-paint"] && audits["largest-contentful-paint"].score !== null && audits["largest-contentful-paint"].score < 0.5 ) { prioritized_recommendations.push("Improve Largest Contentful Paint (LCP)"); } if ( audits["cumulative-layout-shift"] && audits["cumulative-layout-shift"].score !== null && audits["cumulative-layout-shift"].score < 0.5 ) { prioritized_recommendations.push("Reduce layout shifts (CLS)"); } if ( audits["total-blocking-time"] && audits["total-blocking-time"].score !== null && audits["total-blocking-time"].score < 0.5 ) { prioritized_recommendations.push("Reduce JavaScript execution time"); } // Create the performance report content const reportContent: PerformanceReportContent = { score, audit_counts, metrics, opportunities, page_stats, prioritized_recommendations: prioritized_recommendations.length > 0 ? prioritized_recommendations : undefined, }; // Return the full report following the LighthouseReport interface return { metadata, report: reportContent, }; }; ================================================ FILE: browser-tools-server/lighthouse/seo.ts ================================================ import { Result as LighthouseResult } from "lighthouse"; import { AuditCategory, LighthouseReport } from "./types.js"; import { runLighthouseAudit } from "./index.js"; // === SEO Report Types === /** * SEO-specific report content structure */ export interface SEOReportContent { score: number; // Overall score (0-100) audit_counts: { // Counts of different audit types failed: number; passed: number; manual: number; informative: number; not_applicable: number; }; issues: AISEOIssue[]; categories: { [category: string]: { score: number; issues_count: number; }; }; prioritized_recommendations?: string[]; // Ordered list of recommendations } /** * Full SEO report implementing the base LighthouseReport interface */ export type AIOptimizedSEOReport = LighthouseReport; /** * AI-optimized SEO issue */ interface AISEOIssue { id: string; // e.g., "meta-description" title: string; // e.g., "Document has a meta description" impact: "critical" | "serious" | "moderate" | "minor"; category: string; // e.g., "content", "mobile", "crawlability" details?: { selector?: string; // CSS selector if applicable value?: string; // Current value issue?: string; // Description of the issue }[]; score: number | null; // 0-1 or null } // Original interfaces for backward compatibility interface SEOAudit { id: string; // e.g., "meta-description" title: string; // e.g., "Document has a meta description" description: string; // e.g., "Meta descriptions improve SEO..." score: number | null; // 0-1 or null scoreDisplayMode: string; // e.g., "binary" details?: SEOAuditDetails; // Optional, structured details weight?: number; // For prioritization } interface SEOAuditDetails { items?: Array<{ selector?: string; // e.g., "meta[name='description']" issue?: string; // e.g., "Meta description is missing" value?: string; // e.g., Current meta description text }>; type?: string; // e.g., "table" } // This ensures we always include critical issues while limiting less important ones const DETAIL_LIMITS = { critical: Number.MAX_SAFE_INTEGER, // No limit for critical issues serious: 15, // Up to 15 items for serious issues moderate: 10, // Up to 10 items for moderate issues minor: 3, // Up to 3 items for minor issues }; /** * Runs an SEO audit on the specified URL * @param url The URL to audit * @returns Promise resolving to AI-optimized SEO audit results */ export async function runSEOAudit(url: string): Promise { try { const lhr = await runLighthouseAudit(url, [AuditCategory.SEO]); return extractAIOptimizedData(lhr, url); } catch (error) { throw new Error( `SEO audit failed: ${ error instanceof Error ? error.message : String(error) }` ); } } /** * Extract AI-optimized SEO data from Lighthouse results */ const extractAIOptimizedData = ( lhr: LighthouseResult, url: string ): AIOptimizedSEOReport => { const categoryData = lhr.categories[AuditCategory.SEO]; const audits = lhr.audits || {}; // Add metadata const metadata = { url, timestamp: lhr.fetchTime || new Date().toISOString(), device: "desktop", // This could be made configurable lighthouseVersion: lhr.lighthouseVersion, }; // Initialize variables const issues: AISEOIssue[] = []; const categories: { [category: string]: { score: number; issues_count: number }; } = { content: { score: 0, issues_count: 0 }, mobile: { score: 0, issues_count: 0 }, crawlability: { score: 0, issues_count: 0 }, other: { score: 0, issues_count: 0 }, }; // Count audits by type let failedCount = 0; let passedCount = 0; let manualCount = 0; let informativeCount = 0; let notApplicableCount = 0; // Process audit refs const auditRefs = categoryData?.auditRefs || []; // First pass: count audits by type and initialize categories auditRefs.forEach((ref) => { const audit = audits[ref.id]; if (!audit) return; // Count by scoreDisplayMode if (audit.scoreDisplayMode === "manual") { manualCount++; } else if (audit.scoreDisplayMode === "informative") { informativeCount++; } else if (audit.scoreDisplayMode === "notApplicable") { notApplicableCount++; } else if (audit.score !== null) { // Binary pass/fail if (audit.score >= 0.9) { passedCount++; } else { failedCount++; } } // Categorize the issue let category = "other"; if ( ref.id.includes("crawl") || ref.id.includes("http") || ref.id.includes("redirect") || ref.id.includes("robots") ) { category = "crawlability"; } else if ( ref.id.includes("viewport") || ref.id.includes("font-size") || ref.id.includes("tap-targets") ) { category = "mobile"; } else if ( ref.id.includes("document") || ref.id.includes("meta") || ref.id.includes("description") || ref.id.includes("canonical") || ref.id.includes("title") || ref.id.includes("link") ) { category = "content"; } // Update category score and issues count if (audit.score !== null && audit.score < 0.9) { categories[category].issues_count++; } }); // Second pass: process failed audits into AI-friendly format auditRefs .filter((ref) => { const audit = audits[ref.id]; return audit && audit.score !== null && audit.score < 0.9; }) .sort((a, b) => (b.weight || 0) - (a.weight || 0)) // No limit on failed audits - we'll filter dynamically based on impact .forEach((ref) => { const audit = audits[ref.id]; // Determine impact level based on score and weight let impact: "critical" | "serious" | "moderate" | "minor" = "moderate"; if (audit.score === 0) { impact = "critical"; } else if (audit.score !== null && audit.score <= 0.5) { impact = "serious"; } else if (audit.score !== null && audit.score > 0.7) { impact = "minor"; } // Categorize the issue let category = "other"; if ( ref.id.includes("crawl") || ref.id.includes("http") || ref.id.includes("redirect") || ref.id.includes("robots") ) { category = "crawlability"; } else if ( ref.id.includes("viewport") || ref.id.includes("font-size") || ref.id.includes("tap-targets") ) { category = "mobile"; } else if ( ref.id.includes("document") || ref.id.includes("meta") || ref.id.includes("description") || ref.id.includes("canonical") || ref.id.includes("title") || ref.id.includes("link") ) { category = "content"; } // Extract details const details: { selector?: string; value?: string; issue?: string }[] = []; if (audit.details) { const auditDetails = audit.details as any; if (auditDetails.items && Array.isArray(auditDetails.items)) { // Determine item limit based on impact const itemLimit = DETAIL_LIMITS[impact]; auditDetails.items.slice(0, itemLimit).forEach((item: any) => { const detail: { selector?: string; value?: string; issue?: string; } = {}; if (item.selector) { detail.selector = item.selector; } if (item.value !== undefined) { detail.value = item.value; } if (item.issue) { detail.issue = item.issue; } if (Object.keys(detail).length > 0) { details.push(detail); } }); } } // Create the issue const issue: AISEOIssue = { id: ref.id, title: audit.title, impact, category, details: details.length > 0 ? details : undefined, score: audit.score, }; issues.push(issue); }); // Calculate overall score const score = Math.round((categoryData?.score || 0) * 100); // Generate prioritized recommendations const prioritized_recommendations: string[] = []; // Add category-specific recommendations Object.entries(categories) .filter(([_, data]) => data.issues_count > 0) .sort(([_, a], [__, b]) => b.issues_count - a.issues_count) .forEach(([category, data]) => { if (data.issues_count === 0) return; let recommendation = ""; switch (category) { case "content": recommendation = `Improve SEO content (${data.issues_count} issues): titles, descriptions, and headers`; break; case "mobile": recommendation = `Optimize for mobile devices (${data.issues_count} issues)`; break; case "crawlability": recommendation = `Fix crawlability issues (${data.issues_count} issues): robots.txt, sitemaps, and redirects`; break; default: recommendation = `Fix ${data.issues_count} SEO issues in category: ${category}`; } prioritized_recommendations.push(recommendation); }); // Add specific high-impact recommendations if (issues.some((issue) => issue.id === "meta-description")) { prioritized_recommendations.push( "Add a meta description to improve click-through rate" ); } if (issues.some((issue) => issue.id === "document-title")) { prioritized_recommendations.push( "Add a descriptive page title with keywords" ); } if (issues.some((issue) => issue.id === "hreflang")) { prioritized_recommendations.push( "Fix hreflang implementation for international SEO" ); } if (issues.some((issue) => issue.id === "canonical")) { prioritized_recommendations.push("Implement proper canonical tags"); } // Create the report content const reportContent: SEOReportContent = { score, audit_counts: { failed: failedCount, passed: passedCount, manual: manualCount, informative: informativeCount, not_applicable: notApplicableCount, }, issues, categories, prioritized_recommendations: prioritized_recommendations.length > 0 ? prioritized_recommendations : undefined, }; // Return the full report following the LighthouseReport interface return { metadata, report: reportContent, }; }; ================================================ FILE: browser-tools-server/lighthouse/types.ts ================================================ /** * Audit categories available in Lighthouse */ export enum AuditCategory { ACCESSIBILITY = "accessibility", PERFORMANCE = "performance", SEO = "seo", BEST_PRACTICES = "best-practices", // Not yet implemented PWA = "pwa", // Not yet implemented } /** * Base interface for Lighthouse report metadata */ export interface LighthouseReport { metadata: { url: string; timestamp: string; // ISO 8601, e.g., "2025-02-27T14:30:00Z" device: string; // e.g., "mobile", "desktop" lighthouseVersion: string; // e.g., "10.4.0" }; // For backward compatibility with existing report formats overallScore?: number; failedAuditsCount?: number; passedAuditsCount?: number; manualAuditsCount?: number; informativeAuditsCount?: number; notApplicableAuditsCount?: number; failedAudits?: any[]; // New format for specialized reports report?: T; // Generic report data that will be specialized by each audit type } /** * Configuration options for Lighthouse audits */ export interface LighthouseConfig { flags: { output: string[]; onlyCategories: string[]; formFactor: string; port: number | undefined; screenEmulation: { mobile: boolean; width: number; height: number; deviceScaleFactor: number; disabled: boolean; }; }; config: { extends: string; settings: { onlyCategories: string[]; emulatedFormFactor: string; throttling: { cpuSlowdownMultiplier: number; }; }; }; } ================================================ FILE: browser-tools-server/package.json ================================================ { "name": "@agentdeskai/browser-tools-server", "version": "1.2.0", "description": "A browser tools server for capturing and managing browser events, logs, and screenshots", "type": "module", "main": "dist/browser-connector.js", "bin": { "browser-tools-server": "./dist/browser-connector.js" }, "scripts": { "build": "tsc", "start": "tsc && node dist/browser-connector.js", "prepublishOnly": "npm run build" }, "keywords": [ "browser", "tools", "debugging", "logging", "screenshots", "chrome", "extension" ], "author": "AgentDesk AI", "license": "MIT", "dependencies": { "@modelcontextprotocol/sdk": "^1.4.1", "body-parser": "^1.20.3", "cors": "^2.8.5", "express": "^4.21.2", "lighthouse": "^11.6.0", "llm-cost": "^1.0.5", "node-fetch": "^2.7.0", "puppeteer-core": "^22.4.1", "ws": "^8.18.0" }, "optionalDependencies": { "chrome-launcher": "^1.1.2" }, "devDependencies": { "@types/ws": "^8.5.14", "@types/body-parser": "^1.19.5", "@types/cors": "^2.8.17", "@types/express": "^5.0.0", "@types/node": "^22.13.1", "@types/node-fetch": "^2.6.11", "@types/puppeteer-core": "^7.0.4", "typescript": "^5.7.3" } } ================================================ FILE: browser-tools-server/puppeteer-service.ts ================================================ import fs from "fs"; import puppeteer from "puppeteer-core"; import path from "path"; import os from "os"; import { execSync } from "child_process"; import * as ChromeLauncher from "chrome-launcher"; // ===== Configuration Types and Defaults ===== /** * Configuration interface for the Puppeteer service */ export interface PuppeteerServiceConfig { // Browser preferences preferredBrowsers?: string[]; // Order of browser preference ("chrome", "edge", "brave", "firefox") customBrowserPaths?: { [key: string]: string }; // Custom browser executable paths // Connection settings debugPorts?: number[]; // Ports to try when connecting to existing browsers connectionTimeout?: number; // Timeout for connection attempts in ms maxRetries?: number; // Maximum number of retries for connections // Browser cleanup settings browserCleanupTimeout?: number; // Timeout before closing inactive browsers (ms) // Performance settings blockResourceTypes?: string[]; // Resource types to block for performance } // Default configuration values const DEFAULT_CONFIG: PuppeteerServiceConfig = { preferredBrowsers: ["chrome", "edge", "brave", "firefox"], debugPorts: [9222, 9223, 9224, 9225], connectionTimeout: 10000, maxRetries: 3, browserCleanupTimeout: 60000, blockResourceTypes: ["image", "font", "media"], }; // Browser support notes: // - Chrome/Chromium: Fully supported (primary target) // - Edge: Fully supported (Chromium-based) // - Brave: Fully supported (Chromium-based) // - Firefox: Partially supported (some features may not work) // - Safari: Not supported by Puppeteer // ===== Global State ===== // Current active configuration let currentConfig: PuppeteerServiceConfig = { ...DEFAULT_CONFIG }; // Browser instance management let headlessBrowserInstance: puppeteer.Browser | null = null; let launchedBrowserWSEndpoint: string | null = null; // Cleanup management let browserCleanupTimeout: NodeJS.Timeout | null = null; let BROWSER_CLEANUP_TIMEOUT = 60000; // 60 seconds default // Cache for browser executable paths let detectedBrowserPath: string | null = null; // ===== Configuration Functions ===== /** * Configure the Puppeteer service with custom settings * @param config Partial configuration to override defaults */ export function configurePuppeteerService( config: Partial ): void { currentConfig = { ...DEFAULT_CONFIG, ...config }; // Update the timeout if it was changed if ( config.browserCleanupTimeout && config.browserCleanupTimeout !== BROWSER_CLEANUP_TIMEOUT ) { BROWSER_CLEANUP_TIMEOUT = config.browserCleanupTimeout; } console.log("Puppeteer service configured:", currentConfig); } // ===== Browser Management ===== /** * Get or create a headless browser instance * @returns Promise resolving to a browser instance */ async function getHeadlessBrowserInstance(): Promise { console.log("Browser instance request started"); // Cancel any scheduled cleanup cancelScheduledCleanup(); // Try to reuse existing browser if (headlessBrowserInstance) { try { const pages = await headlessBrowserInstance.pages(); console.log( `Reusing existing headless browser with ${pages.length} pages` ); return headlessBrowserInstance; } catch (error) { console.log( "Existing browser instance is no longer valid, creating a new one" ); headlessBrowserInstance = null; launchedBrowserWSEndpoint = null; } } // Create a new browser instance return launchNewBrowser(); } /** * Launches a new browser instance * @returns Promise resolving to a browser instance */ async function launchNewBrowser(): Promise { console.log("Creating new headless browser instance"); // Setup temporary user data directory const userDataDir = createTempUserDataDir(); let browser: puppeteer.Browser | null = null; try { // Configure launch options const launchOptions = configureLaunchOptions(userDataDir); // Set custom browser executable await setCustomBrowserExecutable(launchOptions); // Launch the browser console.log( "Launching browser with options:", JSON.stringify({ headless: launchOptions.headless, executablePath: launchOptions.executablePath, }) ); browser = await puppeteer.launch(launchOptions); // Store references to the browser instance launchedBrowserWSEndpoint = browser.wsEndpoint(); headlessBrowserInstance = browser; // Setup cleanup handlers setupBrowserCleanupHandlers(browser, userDataDir); console.log("Browser ready"); return browser; } catch (error) { console.error("Failed to launch browser:", error); // Clean up resources if (browser) { try { await browser.close(); } catch (closeError) { console.error("Error closing browser:", closeError); } headlessBrowserInstance = null; launchedBrowserWSEndpoint = null; } // Clean up the temporary directory try { fs.rmSync(userDataDir, { recursive: true, force: true }); } catch (fsError) { console.error("Error removing temporary directory:", fsError); } throw error; } } /** * Creates a temporary user data directory for the browser * @returns Path to the created directory */ function createTempUserDataDir(): string { const tempDir = os.tmpdir(); const uniqueId = `${Date.now().toString()}-${Math.random() .toString(36) .substring(2)}`; const userDataDir = path.join(tempDir, `browser-debug-profile-${uniqueId}`); fs.mkdirSync(userDataDir, { recursive: true }); console.log(`Using temporary user data directory: ${userDataDir}`); return userDataDir; } /** * Configures browser launch options * @param userDataDir Path to the user data directory * @returns Launch options object */ function configureLaunchOptions(userDataDir: string): any { const launchOptions: any = { args: [ "--remote-debugging-port=0", // Use dynamic port `--user-data-dir=${userDataDir}`, "--no-first-run", "--no-default-browser-check", "--disable-dev-shm-usage", "--disable-extensions", "--disable-component-extensions-with-background-pages", "--disable-background-networking", "--disable-backgrounding-occluded-windows", "--disable-default-apps", "--disable-sync", "--disable-translate", "--metrics-recording-only", "--no-pings", "--safebrowsing-disable-auto-update", ], }; // Add headless mode (using any to bypass type checking issues) launchOptions.headless = "new"; return launchOptions; } /** * Sets a custom browser executable path if configured * @param launchOptions Launch options object to modify */ async function setCustomBrowserExecutable(launchOptions: any): Promise { // First, try to use a custom browser path from configuration if ( currentConfig.customBrowserPaths && Object.keys(currentConfig.customBrowserPaths).length > 0 ) { const preferredBrowsers = currentConfig.preferredBrowsers || [ "chrome", "edge", "brave", "firefox", ]; for (const browser of preferredBrowsers) { if ( currentConfig.customBrowserPaths[browser] && fs.existsSync(currentConfig.customBrowserPaths[browser]) ) { launchOptions.executablePath = currentConfig.customBrowserPaths[browser]; // Set product to firefox if using Firefox browser if (browser === "firefox") { launchOptions.product = "firefox"; } console.log( `Using custom ${browser} path: ${launchOptions.executablePath}` ); return; } } } // If no custom path is found, use cached path or detect a new one try { if (detectedBrowserPath && fs.existsSync(detectedBrowserPath)) { console.log(`Using cached browser path: ${detectedBrowserPath}`); launchOptions.executablePath = detectedBrowserPath; // Check if the detected browser is Firefox if (detectedBrowserPath.includes("firefox")) { launchOptions.product = "firefox"; console.log("Setting product to firefox for Firefox browser"); } } else { detectedBrowserPath = await findBrowserExecutablePath(); launchOptions.executablePath = detectedBrowserPath; // Check if the detected browser is Firefox if (detectedBrowserPath.includes("firefox")) { launchOptions.product = "firefox"; console.log("Setting product to firefox for Firefox browser"); } console.log( `Using detected browser path: ${launchOptions.executablePath}` ); } } catch (error) { console.error("Failed to detect browser executable path:", error); throw new Error( "No browser executable path found. Please specify a custom browser path in the configuration." ); } } /** * Find a browser executable path on the current system * @returns Path to a browser executable */ async function findBrowserExecutablePath(): Promise { // Try to use chrome-launcher (most reliable method) try { console.log("Attempting to find Chrome using chrome-launcher..."); // Launch Chrome using chrome-launcher const chrome = await ChromeLauncher.launch({ chromeFlags: ["--headless"], handleSIGINT: false, }); // chrome-launcher stores the Chrome executable path differently than Puppeteer // Let's try different approaches to get it // First check if we can access it directly let chromePath = ""; // Chrome version data often contains the path if (chrome.process && chrome.process.spawnfile) { chromePath = chrome.process.spawnfile; console.log("Found Chrome path from process.spawnfile"); } else { // Try to get the Chrome path from chrome-launcher // In newer versions, it's directly accessible console.log("Trying to determine Chrome path using other methods"); // This will actually return the real Chrome path for us // chrome-launcher has this inside but doesn't expose it directly const possiblePaths = [ process.env.CHROME_PATH, // Common paths by OS ...(process.platform === "darwin" ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"] : process.platform === "win32" ? [ `${process.env.PROGRAMFILES}\\Google\\Chrome\\Application\\chrome.exe`, `${process.env["PROGRAMFILES(X86)"]}\\Google\\Chrome\\Application\\chrome.exe`, ] : ["/usr/bin/google-chrome"]), ].filter(Boolean); // Use the first valid path for (const p of possiblePaths) { if (p && fs.existsSync(p)) { chromePath = p; console.log("Found Chrome path from common locations"); break; } } } // Always kill the Chrome instance we just launched await chrome.kill(); if (chromePath) { console.log(`Chrome found via chrome-launcher: ${chromePath}`); return chromePath; } else { console.log("Chrome launched but couldn't determine executable path"); } } catch (error) { // Check if it's a ChromeNotInstalledError const errorMessage = error instanceof Error ? error.message : String(error); if ( errorMessage.includes("No Chrome installations found") || (error as any)?.code === "ERR_LAUNCHER_NOT_INSTALLED" ) { console.log("Chrome not installed. Falling back to manual detection"); } else { console.error("Failed to find Chrome using chrome-launcher:", error); console.log("Falling back to manual detection"); } } // If chrome-launcher failed, use manual detection const platform = process.platform; const preferredBrowsers = currentConfig.preferredBrowsers || [ "chrome", "edge", "brave", "firefox", ]; console.log(`Attempting to detect browser executable path on ${platform}...`); // Platform-specific detection strategies if (platform === "win32") { // Windows - try registry detection for Chrome let registryPath = null; try { console.log("Checking Windows registry for Chrome..."); // Try HKLM first const regOutput = execSync( 'reg query "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\chrome.exe" /ve', { encoding: "utf8" } ); // Extract path from registry output const match = regOutput.match(/REG_(?:SZ|EXPAND_SZ)\s+([^\s]+)/i); if (match && match[1]) { registryPath = match[1].replace(/\\"/g, ""); // Verify the path exists if (fs.existsSync(registryPath)) { console.log(`Found Chrome via HKLM registry: ${registryPath}`); return registryPath; } } } catch (e) { // Try HKCU if HKLM fails try { console.log("Checking user registry for Chrome..."); const regOutput = execSync( 'reg query "HKEY_CURRENT_USER\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\chrome.exe" /ve', { encoding: "utf8" } ); // Extract path from registry output const match = regOutput.match(/REG_(?:SZ|EXPAND_SZ)\s+([^\s]+)/i); if (match && match[1]) { registryPath = match[1].replace(/\\"/g, ""); // Verify the path exists if (fs.existsSync(registryPath)) { console.log(`Found Chrome via HKCU registry: ${registryPath}`); return registryPath; } } } catch (innerError) { console.log( "Failed to find Chrome via registry, continuing with path checks" ); } } // Try to find Chrome through BLBeacon registry key (version info) try { console.log("Checking Chrome BLBeacon registry..."); const regOutput = execSync( 'reg query "HKEY_CURRENT_USER\\Software\\Google\\Chrome\\BLBeacon" /v version', { encoding: "utf8" } ); if (regOutput) { // If BLBeacon exists, Chrome is likely installed in the default location const programFiles = process.env.PROGRAMFILES || "C:\\Program Files"; const programFilesX86 = process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)"; const defaultChromePaths = [ path.join(programFiles, "Google\\Chrome\\Application\\chrome.exe"), path.join(programFilesX86, "Google\\Chrome\\Application\\chrome.exe"), ]; for (const chromePath of defaultChromePaths) { if (fs.existsSync(chromePath)) { console.log( `Found Chrome via BLBeacon registry hint: ${chromePath}` ); return chromePath; } } } } catch (e) { console.log("Failed to find Chrome via BLBeacon registry"); } // Continue with regular path checks const programFiles = process.env.PROGRAMFILES || "C:\\Program Files"; const programFilesX86 = process.env["PROGRAMFILES(X86)"] || "C:\\Program Files (x86)"; // Common Windows browser paths const winBrowserPaths = { chrome: [ path.join(programFiles, "Google\\Chrome\\Application\\chrome.exe"), path.join(programFilesX86, "Google\\Chrome\\Application\\chrome.exe"), ], edge: [ path.join(programFiles, "Microsoft\\Edge\\Application\\msedge.exe"), path.join(programFilesX86, "Microsoft\\Edge\\Application\\msedge.exe"), ], brave: [ path.join( programFiles, "BraveSoftware\\Brave-Browser\\Application\\brave.exe" ), path.join( programFilesX86, "BraveSoftware\\Brave-Browser\\Application\\brave.exe" ), ], firefox: [ path.join(programFiles, "Mozilla Firefox\\firefox.exe"), path.join(programFilesX86, "Mozilla Firefox\\firefox.exe"), ], }; // Check each browser in preferred order for (const browser of preferredBrowsers) { const paths = winBrowserPaths[browser as keyof typeof winBrowserPaths] || []; for (const browserPath of paths) { if (fs.existsSync(browserPath)) { console.log(`Found ${browser} at ${browserPath}`); return browserPath; } } } } else if (platform === "darwin") { // macOS browser paths const macBrowserPaths = { chrome: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"], edge: ["/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"], brave: ["/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"], firefox: ["/Applications/Firefox.app/Contents/MacOS/firefox"], safari: ["/Applications/Safari.app/Contents/MacOS/Safari"], }; // Check each browser in preferred order for (const browser of preferredBrowsers) { const paths = macBrowserPaths[browser as keyof typeof macBrowserPaths] || []; for (const browserPath of paths) { if (fs.existsSync(browserPath)) { console.log(`Found ${browser} at ${browserPath}`); // Safari is detected but not supported by Puppeteer if (browser === "safari") { console.log( "Safari detected but not supported by Puppeteer. Continuing search..." ); continue; } return browserPath; } } } } else if (platform === "linux") { // Linux browser commands const linuxBrowserCommands = { chrome: ["google-chrome", "chromium", "chromium-browser"], edge: ["microsoft-edge"], brave: ["brave-browser"], firefox: ["firefox"], }; // Check each browser in preferred order for (const browser of preferredBrowsers) { const commands = linuxBrowserCommands[browser as keyof typeof linuxBrowserCommands] || []; for (const cmd of commands) { try { // Use more universal commands for Linux to find executables // command -v works in most shells, fallback to which or type const browserPath = execSync( `command -v ${cmd} || which ${cmd} || type -p ${cmd} 2>/dev/null`, { encoding: "utf8" } ).trim(); if (browserPath && fs.existsSync(browserPath)) { console.log(`Found ${browser} at ${browserPath}`); return browserPath; } } catch (e) { // Command not found, continue to next } } } // Additional check for unusual locations on Linux const alternativeLocations = [ "/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser", "/snap/bin/chromium", "/snap/bin/google-chrome", "/opt/google/chrome/chrome", ]; for (const location of alternativeLocations) { if (fs.existsSync(location)) { console.log(`Found browser at alternative location: ${location}`); return location; } } } throw new Error( `No browser executable found for platform ${platform}. Please specify a custom browser path.` ); } /** * Sets up cleanup handlers for the browser instance * @param browser Browser instance * @param userDataDir Path to the user data directory to clean up */ function setupBrowserCleanupHandlers( browser: puppeteer.Browser, userDataDir: string ): void { browser.on("disconnected", () => { console.log(`Browser disconnected. Scheduling cleanup for: ${userDataDir}`); // Clear any existing cleanup timeout when browser is disconnected cancelScheduledCleanup(); // Delayed cleanup to avoid conflicts with potential new browser instances setTimeout(() => { // Only remove the directory if no new browser has been launched if (!headlessBrowserInstance) { console.log(`Cleaning up temporary directory: ${userDataDir}`); try { fs.rmSync(userDataDir, { recursive: true, force: true }); console.log(`Successfully removed directory: ${userDataDir}`); } catch (error) { console.error(`Failed to remove directory ${userDataDir}:`, error); } } else { console.log( `Skipping cleanup for ${userDataDir} as new browser instance is active` ); } }, 5000); // 5-second delay for cleanup // Reset browser instance variables launchedBrowserWSEndpoint = null; headlessBrowserInstance = null; }); } // ===== Cleanup Management ===== /** * Cancels any scheduled browser cleanup */ function cancelScheduledCleanup(): void { if (browserCleanupTimeout) { console.log("Cancelling scheduled browser cleanup"); clearTimeout(browserCleanupTimeout); browserCleanupTimeout = null; } } /** * Schedules automatic cleanup of the browser instance after inactivity */ export function scheduleBrowserCleanup(): void { // Clear any existing timeout first cancelScheduledCleanup(); // Only schedule cleanup if we have an active browser instance if (headlessBrowserInstance) { console.log( `Scheduling browser cleanup in ${BROWSER_CLEANUP_TIMEOUT / 1000} seconds` ); browserCleanupTimeout = setTimeout(() => { console.log("Executing scheduled browser cleanup"); if (headlessBrowserInstance) { console.log("Closing headless browser instance"); headlessBrowserInstance.close(); headlessBrowserInstance = null; launchedBrowserWSEndpoint = null; } browserCleanupTimeout = null; }, BROWSER_CLEANUP_TIMEOUT); } } // ===== Public Browser Connection API ===== /** * Connects to a headless browser for web operations * @param url The URL to navigate to * @param options Connection and emulation options * @returns Promise resolving to browser, port, and page objects */ export async function connectToHeadlessBrowser( url: string, options: { blockResources?: boolean; customResourceBlockList?: string[]; emulateDevice?: "mobile" | "tablet" | "desktop"; emulateNetworkCondition?: "slow3G" | "fast3G" | "4G" | "offline"; viewport?: { width: number; height: number }; locale?: string; timezoneId?: string; userAgent?: string; waitForSelector?: string; waitForTimeout?: number; cookies?: Array<{ name: string; value: string; domain?: string; path?: string; }>; headers?: Record; } = {} ): Promise<{ browser: puppeteer.Browser; port: number; page: puppeteer.Page; }> { console.log( `Connecting to headless browser for ${url}${ options.blockResources ? " (blocking non-essential resources)" : "" }` ); try { // Validate URL format try { new URL(url); } catch (e) { throw new Error(`Invalid URL format: ${url}`); } // Get or create a browser instance const browser = await getHeadlessBrowserInstance(); if (!launchedBrowserWSEndpoint) { throw new Error("Failed to retrieve WebSocket endpoint for browser"); } // Extract port from WebSocket endpoint const port = parseInt( launchedBrowserWSEndpoint.split(":")[2].split("/")[0] ); // Always create a new page for each audit to avoid request interception conflicts console.log("Creating a new page for this audit"); const page = await browser.newPage(); // Set a longer timeout for navigation const navigationTimeout = 10000; // 10 seconds page.setDefaultNavigationTimeout(navigationTimeout); // Navigate to the URL console.log(`Navigating to ${url}`); await page.goto(url, { waitUntil: "networkidle2", // Wait until there are no more network connections for at least 500ms timeout: navigationTimeout, }); // Set custom headers if provided if (options.headers && Object.keys(options.headers).length > 0) { await page.setExtraHTTPHeaders(options.headers); console.log("Set custom HTTP headers"); } // Set cookies if provided if (options.cookies && options.cookies.length > 0) { const urlObj = new URL(url); const cookiesWithDomain = options.cookies.map((cookie) => ({ ...cookie, domain: cookie.domain || urlObj.hostname, path: cookie.path || "/", })); await page.setCookie(...cookiesWithDomain); console.log(`Set ${options.cookies.length} cookies`); } // Set custom viewport if specified if (options.viewport) { await page.setViewport(options.viewport); console.log( `Set viewport to ${options.viewport.width}x${options.viewport.height}` ); } else if (options.emulateDevice) { // Set common device emulation presets let viewport; let userAgent = options.userAgent; switch (options.emulateDevice) { case "mobile": viewport = { width: 375, height: 667, isMobile: true, hasTouch: true, }; userAgent = userAgent || "Mozilla/5.0 (iPhone; CPU iPhone OS 13_2_3 like Mac OS X)"; break; case "tablet": viewport = { width: 768, height: 1024, isMobile: true, hasTouch: true, }; userAgent = userAgent || "Mozilla/5.0 (iPad; CPU OS 13_2_3 like Mac OS X)"; break; case "desktop": default: viewport = { width: 1280, height: 800, isMobile: false, hasTouch: false, }; break; } await page.setViewport(viewport); if (userAgent) await page.setUserAgent(userAgent); console.log(`Emulating ${options.emulateDevice} device`); } // Set locale and timezone if provided if (options.locale) { await page.evaluateOnNewDocument((locale) => { Object.defineProperty(navigator, "language", { get: () => locale }); Object.defineProperty(navigator, "languages", { get: () => [locale] }); }, options.locale); console.log(`Set locale to ${options.locale}`); } if (options.timezoneId) { await page.emulateTimezone(options.timezoneId); console.log(`Set timezone to ${options.timezoneId}`); } // Emulate network conditions if specified if (options.emulateNetworkCondition) { // Define network condition types that match puppeteer's expected format interface PuppeteerNetworkConditions { offline: boolean; latency?: number; download?: number; upload?: number; } let networkConditions: PuppeteerNetworkConditions; switch (options.emulateNetworkCondition) { case "slow3G": networkConditions = { offline: false, latency: 400, download: (500 * 1024) / 8, upload: (500 * 1024) / 8, }; break; case "fast3G": networkConditions = { offline: false, latency: 150, download: (1.5 * 1024 * 1024) / 8, upload: (750 * 1024) / 8, }; break; case "4G": networkConditions = { offline: false, latency: 50, download: (4 * 1024 * 1024) / 8, upload: (2 * 1024 * 1024) / 8, }; break; case "offline": networkConditions = { offline: true }; break; default: networkConditions = { offline: false }; } // @ts-ignore - Property might not be in types but is supported await page.emulateNetworkConditions(networkConditions); console.log( `Emulating ${options.emulateNetworkCondition} network conditions` ); } // Check if we should block resources based on the options if (options.blockResources) { const resourceTypesToBlock = options.customResourceBlockList || currentConfig.blockResourceTypes || ["image", "font", "media"]; await page.setRequestInterception(true); page.on("request", (request) => { // Block unnecessary resources to speed up loading const resourceType = request.resourceType(); if (resourceTypesToBlock.includes(resourceType)) { request.abort(); } else { request.continue(); } }); console.log( `Blocking resource types: ${resourceTypesToBlock.join(", ")}` ); } // Wait for a specific selector if requested if (options.waitForSelector) { try { console.log(`Waiting for selector: ${options.waitForSelector}`); await page.waitForSelector(options.waitForSelector, { timeout: options.waitForTimeout || 30000, }); } catch (selectorError: any) { console.warn( `Failed to find selector "${options.waitForSelector}": ${selectorError.message}` ); // Continue anyway, don't fail the whole operation } } return { browser, port, page }; } catch (error) { console.error("Failed to connect to headless browser:", error); throw new Error( `Failed to connect to headless browser: ${ error instanceof Error ? error.message : String(error) }` ); } } ================================================ FILE: browser-tools-server/tsconfig.json ================================================ { "compilerOptions": { "target": "ES2020", "module": "NodeNext", "moduleResolution": "NodeNext", "esModuleInterop": true, "outDir": "./dist", "rootDir": ".", "strict": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "resolveJsonModule": true }, "include": ["**/*.ts"], "exclude": ["node_modules", "dist"] } ================================================ FILE: chrome-extension/background.js ================================================ // Listen for messages from the devtools panel chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { if (message.type === "GET_CURRENT_URL" && message.tabId) { getCurrentTabUrl(message.tabId) .then((url) => { sendResponse({ success: true, url: url }); }) .catch((error) => { sendResponse({ success: false, error: error.message }); }); return true; // Required to use sendResponse asynchronously } // Handle explicit request to update the server with the URL if (message.type === "UPDATE_SERVER_URL" && message.tabId && message.url) { console.log( `Background: Received request to update server with URL for tab ${message.tabId}: ${message.url}` ); updateServerWithUrl( message.tabId, message.url, message.source || "explicit_update" ) .then(() => { if (sendResponse) sendResponse({ success: true }); }) .catch((error) => { console.error("Background: Error updating server with URL:", error); if (sendResponse) sendResponse({ success: false, error: error.message }); }); return true; // Required to use sendResponse asynchronously } if (message.type === "CAPTURE_SCREENSHOT" && message.tabId) { // First get the server settings chrome.storage.local.get(["browserConnectorSettings"], (result) => { const settings = result.browserConnectorSettings || { serverHost: "localhost", serverPort: 3025, }; // Validate server identity first validateServerIdentity(settings.serverHost, settings.serverPort) .then((isValid) => { if (!isValid) { console.error( "Cannot capture screenshot: Not connected to a valid browser tools server" ); sendResponse({ success: false, error: "Not connected to a valid browser tools server. Please check your connection settings.", }); return; } // Continue with screenshot capture captureAndSendScreenshot(message, settings, sendResponse); }) .catch((error) => { console.error("Error validating server:", error); sendResponse({ success: false, error: "Failed to validate server identity: " + error.message, }); }); }); return true; // Required to use sendResponse asynchronously } }); // Validate server identity async function validateServerIdentity(host, port) { try { const response = await fetch(`http://${host}:${port}/.identity`, { signal: AbortSignal.timeout(3000), // 3 second timeout }); if (!response.ok) { console.error(`Invalid server response: ${response.status}`); return false; } const identity = await response.json(); // Validate the server signature if (identity.signature !== "mcp-browser-connector-24x7") { console.error("Invalid server signature - not the browser tools server"); return false; } return true; } catch (error) { console.error("Error validating server identity:", error); return false; } } // Helper function to process the tab and run the audit function processTabForAudit(tab, tabId) { const url = tab.url; if (!url) { console.error(`No URL available for tab ${tabId}`); return; } // Update our cache and the server with this URL tabUrls.set(tabId, url); updateServerWithUrl(tabId, url); } // Track URLs for each tab const tabUrls = new Map(); // Function to get the current URL for a tab async function getCurrentTabUrl(tabId) { try { console.log("Background: Getting URL for tab", tabId); // First check if we have it cached if (tabUrls.has(tabId)) { const cachedUrl = tabUrls.get(tabId); console.log("Background: Found cached URL:", cachedUrl); return cachedUrl; } // Otherwise get it from the tab try { const tab = await chrome.tabs.get(tabId); if (tab && tab.url) { // Cache the URL tabUrls.set(tabId, tab.url); console.log("Background: Got URL from tab:", tab.url); return tab.url; } else { console.log("Background: Tab exists but no URL found"); } } catch (tabError) { console.error("Background: Error getting tab:", tabError); } // If we can't get the tab directly, try querying for active tabs try { const tabs = await chrome.tabs.query({ active: true, currentWindow: true, }); if (tabs && tabs.length > 0 && tabs[0].url) { const activeUrl = tabs[0].url; console.log("Background: Got URL from active tab:", activeUrl); // Cache this URL as well tabUrls.set(tabId, activeUrl); return activeUrl; } } catch (queryError) { console.error("Background: Error querying tabs:", queryError); } console.log("Background: Could not find URL for tab", tabId); return null; } catch (error) { console.error("Background: Error getting tab URL:", error); return null; } } // Listen for tab updates to detect page refreshes and URL changes chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => { // Track URL changes if (changeInfo.url) { console.log(`URL changed in tab ${tabId} to ${changeInfo.url}`); tabUrls.set(tabId, changeInfo.url); // Send URL update to server if possible updateServerWithUrl(tabId, changeInfo.url, "tab_url_change"); } // Check if this is a page refresh (status becoming "complete") if (changeInfo.status === "complete") { // Update URL in our cache if (tab.url) { tabUrls.set(tabId, tab.url); // Send URL update to server if possible updateServerWithUrl(tabId, tab.url, "page_complete"); } retestConnectionOnRefresh(tabId); } }); // Listen for tab activation (switching between tabs) chrome.tabs.onActivated.addListener((activeInfo) => { const tabId = activeInfo.tabId; console.log(`Tab activated: ${tabId}`); // Get the URL of the newly activated tab chrome.tabs.get(tabId, (tab) => { if (chrome.runtime.lastError) { console.error("Error getting tab info:", chrome.runtime.lastError); return; } if (tab && tab.url) { console.log(`Active tab changed to ${tab.url}`); // Update our cache tabUrls.set(tabId, tab.url); // Send URL update to server updateServerWithUrl(tabId, tab.url, "tab_activated"); } }); }); // Function to update the server with the current URL async function updateServerWithUrl(tabId, url, source = "background_update") { if (!url) { console.error("Cannot update server with empty URL"); return; } console.log(`Updating server with URL for tab ${tabId}: ${url}`); // Get the saved settings chrome.storage.local.get(["browserConnectorSettings"], async (result) => { const settings = result.browserConnectorSettings || { serverHost: "localhost", serverPort: 3025, }; // Maximum number of retry attempts const maxRetries = 3; let retryCount = 0; let success = false; while (retryCount < maxRetries && !success) { try { // Send the URL to the server const serverUrl = `http://${settings.serverHost}:${settings.serverPort}/current-url`; console.log( `Attempt ${ retryCount + 1 }/${maxRetries} to update server with URL: ${url}` ); const response = await fetch(serverUrl, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ url: url, tabId: tabId, timestamp: Date.now(), source: source, }), // Add a timeout to prevent hanging requests signal: AbortSignal.timeout(5000), }); if (response.ok) { const responseData = await response.json(); console.log( `Successfully updated server with URL: ${url}`, responseData ); success = true; } else { console.error( `Server returned error: ${response.status} ${response.statusText}` ); retryCount++; // Wait before retrying await new Promise((resolve) => setTimeout(resolve, 500)); } } catch (error) { console.error(`Error updating server with URL: ${error.message}`); retryCount++; // Wait before retrying await new Promise((resolve) => setTimeout(resolve, 500)); } } if (!success) { console.error( `Failed to update server with URL after ${maxRetries} attempts` ); } }); } // Clean up when tabs are closed chrome.tabs.onRemoved.addListener((tabId) => { tabUrls.delete(tabId); }); // Function to retest connection when a page is refreshed async function retestConnectionOnRefresh(tabId) { console.log(`Page refreshed in tab ${tabId}, retesting connection...`); // Get the saved settings chrome.storage.local.get(["browserConnectorSettings"], async (result) => { const settings = result.browserConnectorSettings || { serverHost: "localhost", serverPort: 3025, }; // Test the connection with the last known host and port const isConnected = await validateServerIdentity( settings.serverHost, settings.serverPort ); // Notify all devtools instances about the connection status chrome.runtime.sendMessage({ type: "CONNECTION_STATUS_UPDATE", isConnected: isConnected, tabId: tabId, }); // Always notify for page refresh, whether connected or not // This ensures any ongoing discovery is cancelled and restarted chrome.runtime.sendMessage({ type: "INITIATE_AUTO_DISCOVERY", reason: "page_refresh", tabId: tabId, forceRestart: true, // Add a flag to indicate this should force restart any ongoing processes }); if (!isConnected) { console.log( "Connection test failed after page refresh, initiating auto-discovery..." ); } else { console.log("Connection test successful after page refresh"); } }); } // Function to capture and send screenshot function captureAndSendScreenshot(message, settings, sendResponse) { // Get the inspected window's tab chrome.tabs.get(message.tabId, (tab) => { if (chrome.runtime.lastError) { console.error("Error getting tab:", chrome.runtime.lastError); sendResponse({ success: false, error: chrome.runtime.lastError.message, }); return; } // Get all windows to find the one containing our tab chrome.windows.getAll({ populate: true }, (windows) => { const targetWindow = windows.find((w) => w.tabs.some((t) => t.id === message.tabId) ); if (!targetWindow) { console.error("Could not find window containing the inspected tab"); sendResponse({ success: false, error: "Could not find window containing the inspected tab", }); return; } // Capture screenshot of the window containing our tab chrome.tabs.captureVisibleTab( targetWindow.id, { format: "png" }, (dataUrl) => { // Ignore DevTools panel capture error if it occurs if ( chrome.runtime.lastError && !chrome.runtime.lastError.message.includes("devtools://") ) { console.error( "Error capturing screenshot:", chrome.runtime.lastError ); sendResponse({ success: false, error: chrome.runtime.lastError.message, }); return; } // Send screenshot data to browser connector using configured settings const serverUrl = `http://${settings.serverHost}:${settings.serverPort}/screenshot`; console.log(`Sending screenshot to ${serverUrl}`); fetch(serverUrl, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ data: dataUrl, path: message.screenshotPath, }), }) .then((response) => response.json()) .then((result) => { if (result.error) { console.error("Error from server:", result.error); sendResponse({ success: false, error: result.error }); } else { console.log("Screenshot saved successfully:", result.path); // Send success response even if DevTools capture failed sendResponse({ success: true, path: result.path, title: tab.title || "Current Tab", }); } }) .catch((error) => { console.error("Error sending screenshot data:", error); sendResponse({ success: false, error: error.message || "Failed to save screenshot", }); }); } ); }); }); } ================================================ FILE: chrome-extension/devtools.html ================================================ BrowserTools MCP ================================================ FILE: chrome-extension/devtools.js ================================================ // devtools.js // Store settings with defaults let settings = { logLimit: 50, queryLimit: 30000, stringSizeLimit: 500, maxLogSize: 20000, showRequestHeaders: false, showResponseHeaders: false, screenshotPath: "", // Add new setting for screenshot path serverHost: "localhost", // Default server host serverPort: 3025, // Default server port allowAutoPaste: false, // Default auto-paste setting }; // Keep track of debugger state let isDebuggerAttached = false; let attachDebuggerRetries = 0; const currentTabId = chrome.devtools.inspectedWindow.tabId; const MAX_ATTACH_RETRIES = 3; const ATTACH_RETRY_DELAY = 1000; // 1 second // Load saved settings on startup chrome.storage.local.get(["browserConnectorSettings"], (result) => { if (result.browserConnectorSettings) { settings = { ...settings, ...result.browserConnectorSettings }; } }); // Listen for settings updates chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { if (message.type === "SETTINGS_UPDATED") { settings = message.settings; // If server settings changed and we have a WebSocket, reconnect if ( ws && (message.settings.serverHost !== settings.serverHost || message.settings.serverPort !== settings.serverPort) ) { console.log("Server settings changed, reconnecting WebSocket..."); setupWebSocket(); } } // Handle connection status updates from page refreshes if (message.type === "CONNECTION_STATUS_UPDATE") { console.log( `DevTools received connection status update: ${ message.isConnected ? "Connected" : "Disconnected" }` ); // If connection is lost, try to reestablish WebSocket only if we had a previous connection if (!message.isConnected && ws) { console.log( "Connection lost after page refresh, will attempt to reconnect WebSocket" ); // Only reconnect if we actually have a WebSocket that might be stale if ( ws && (ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) ) { console.log("WebSocket is already closed or closing, will reconnect"); setupWebSocket(); } } } // Handle auto-discovery requests after page refreshes if (message.type === "INITIATE_AUTO_DISCOVERY") { console.log( `DevTools initiating WebSocket reconnect after page refresh (reason: ${message.reason})` ); // For page refreshes with forceRestart, we should always reconnect if our current connection is not working if ( (message.reason === "page_refresh" || message.forceRestart === true) && (!ws || ws.readyState !== WebSocket.OPEN) ) { console.log( "Page refreshed and WebSocket not open - forcing reconnection" ); // Close existing WebSocket if any if (ws) { console.log("Closing existing WebSocket due to page refresh"); intentionalClosure = true; // Mark as intentional to prevent auto-reconnect try { ws.close(); } catch (e) { console.error("Error closing WebSocket:", e); } ws = null; intentionalClosure = false; // Reset flag } // Clear any pending reconnect timeouts if (wsReconnectTimeout) { clearTimeout(wsReconnectTimeout); wsReconnectTimeout = null; } // Try to reestablish the WebSocket connection setupWebSocket(); } } }); // Utility to recursively truncate strings in any data structure function truncateStringsInData(data, maxLength, depth = 0, path = "") { // Add depth limit to prevent circular references if (depth > 100) { console.warn("Max depth exceeded at path:", path); return "[MAX_DEPTH_EXCEEDED]"; } console.log(`Processing at path: ${path}, type:`, typeof data); if (typeof data === "string") { if (data.length > maxLength) { console.log( `Truncating string at path ${path} from ${data.length} to ${maxLength}` ); return data.substring(0, maxLength) + "... (truncated)"; } return data; } if (Array.isArray(data)) { console.log(`Processing array at path ${path} with length:`, data.length); return data.map((item, index) => truncateStringsInData(item, maxLength, depth + 1, `${path}[${index}]`) ); } if (typeof data === "object" && data !== null) { console.log( `Processing object at path ${path} with keys:`, Object.keys(data) ); const result = {}; for (const [key, value] of Object.entries(data)) { try { result[key] = truncateStringsInData( value, maxLength, depth + 1, path ? `${path}.${key}` : key ); } catch (e) { console.error(`Error processing key ${key} at path ${path}:`, e); result[key] = "[ERROR_PROCESSING]"; } } return result; } return data; } // Helper to calculate the size of an object function calculateObjectSize(obj) { return JSON.stringify(obj).length; } // Helper to process array of objects with size limit function processArrayWithSizeLimit(array, maxTotalSize, processFunc) { let currentSize = 0; const result = []; for (const item of array) { // Process the item first const processedItem = processFunc(item); const itemSize = calculateObjectSize(processedItem); // Check if adding this item would exceed the limit if (currentSize + itemSize > maxTotalSize) { console.log( `Reached size limit (${currentSize}/${maxTotalSize}), truncating array` ); break; } // Add item and update size result.push(processedItem); currentSize += itemSize; console.log( `Added item of size ${itemSize}, total size now: ${currentSize}` ); } return result; } // Modified processJsonString to handle arrays with size limit function processJsonString(jsonString, maxLength) { console.log("Processing string of length:", jsonString?.length); try { let parsed; try { parsed = JSON.parse(jsonString); console.log( "Successfully parsed as JSON, structure:", JSON.stringify(Object.keys(parsed)) ); } catch (e) { console.log("Not valid JSON, treating as string"); return truncateStringsInData(jsonString, maxLength, 0, "root"); } // If it's an array, process with size limit if (Array.isArray(parsed)) { console.log("Processing array of objects with size limit"); const processed = processArrayWithSizeLimit( parsed, settings.maxLogSize, (item) => truncateStringsInData(item, maxLength, 0, "root") ); const result = JSON.stringify(processed); console.log( `Processed array: ${parsed.length} -> ${processed.length} items` ); return result; } // Otherwise process as before const processed = truncateStringsInData(parsed, maxLength, 0, "root"); const result = JSON.stringify(processed); console.log("Processed JSON string length:", result.length); return result; } catch (e) { console.error("Error in processJsonString:", e); return jsonString.substring(0, maxLength) + "... (truncated)"; } } // Helper to send logs to browser-connector async function sendToBrowserConnector(logData) { if (!logData) { console.error("No log data provided to sendToBrowserConnector"); return; } // First, ensure we're connecting to the right server if (!(await validateServerIdentity())) { console.error( "Cannot send logs: Not connected to a valid browser tools server" ); return; } console.log("Sending log data to browser connector:", { type: logData.type, timestamp: logData.timestamp, }); // Process any string fields that might contain JSON const processedData = { ...logData }; if (logData.type === "network-request") { console.log("Processing network request"); if (processedData.requestBody) { console.log( "Request body size before:", processedData.requestBody.length ); processedData.requestBody = processJsonString( processedData.requestBody, settings.stringSizeLimit ); console.log("Request body size after:", processedData.requestBody.length); } if (processedData.responseBody) { console.log( "Response body size before:", processedData.responseBody.length ); processedData.responseBody = processJsonString( processedData.responseBody, settings.stringSizeLimit ); console.log( "Response body size after:", processedData.responseBody.length ); } } else if ( logData.type === "console-log" || logData.type === "console-error" ) { console.log("Processing console message"); if (processedData.message) { console.log("Message size before:", processedData.message.length); processedData.message = processJsonString( processedData.message, settings.stringSizeLimit ); console.log("Message size after:", processedData.message.length); } } // Add settings to the request const payload = { data: { ...processedData, timestamp: Date.now(), }, settings: { logLimit: settings.logLimit, queryLimit: settings.queryLimit, showRequestHeaders: settings.showRequestHeaders, showResponseHeaders: settings.showResponseHeaders, }, }; const finalPayloadSize = JSON.stringify(payload).length; console.log("Final payload size:", finalPayloadSize); if (finalPayloadSize > 1000000) { console.warn("Warning: Large payload detected:", finalPayloadSize); console.warn( "Payload preview:", JSON.stringify(payload).substring(0, 1000) + "..." ); } const serverUrl = `http://${settings.serverHost}:${settings.serverPort}/extension-log`; console.log(`Sending log to ${serverUrl}`); fetch(serverUrl, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload), }) .then((response) => { if (!response.ok) { throw new Error(`HTTP error ${response.status}`); } return response.json(); }) .then((data) => { console.log("Log sent successfully:", data); }) .catch((error) => { console.error("Error sending log:", error); }); } // Validate server identity async function validateServerIdentity() { try { console.log( `Validating server identity at ${settings.serverHost}:${settings.serverPort}...` ); // Use fetch with a timeout to prevent long-hanging requests const response = await fetch( `http://${settings.serverHost}:${settings.serverPort}/.identity`, { signal: AbortSignal.timeout(3000), // 3 second timeout } ); if (!response.ok) { console.error( `Server identity validation failed: HTTP ${response.status}` ); // Notify about the connection failure chrome.runtime.sendMessage({ type: "SERVER_VALIDATION_FAILED", reason: "http_error", status: response.status, serverHost: settings.serverHost, serverPort: settings.serverPort, }); return false; } const identity = await response.json(); // Validate signature if (identity.signature !== "mcp-browser-connector-24x7") { console.error("Server identity validation failed: Invalid signature"); // Notify about the invalid signature chrome.runtime.sendMessage({ type: "SERVER_VALIDATION_FAILED", reason: "invalid_signature", serverHost: settings.serverHost, serverPort: settings.serverPort, }); return false; } console.log( `Server identity confirmed: ${identity.name} v${identity.version}` ); // Notify about successful validation chrome.runtime.sendMessage({ type: "SERVER_VALIDATION_SUCCESS", serverInfo: identity, serverHost: settings.serverHost, serverPort: settings.serverPort, }); return true; } catch (error) { console.error("Server identity validation failed:", error); // Notify about the connection error chrome.runtime.sendMessage({ type: "SERVER_VALIDATION_FAILED", reason: "connection_error", error: error.message, serverHost: settings.serverHost, serverPort: settings.serverPort, }); return false; } } // Function to clear logs on the server function wipeLogs() { console.log("Wiping all logs..."); const serverUrl = `http://${settings.serverHost}:${settings.serverPort}/wipelogs`; console.log(`Sending wipe request to ${serverUrl}`); fetch(serverUrl, { method: "POST", headers: { "Content-Type": "application/json" }, }) .then((response) => { if (!response.ok) { throw new Error(`HTTP error ${response.status}`); } return response.json(); }) .then((data) => { console.log("Logs wiped successfully:", data); }) .catch((error) => { console.error("Error wiping logs:", error); }); } // Listen for page refreshes chrome.devtools.network.onNavigated.addListener((url) => { console.log("Page navigated/refreshed - wiping logs"); wipeLogs(); // Send the new URL to the server if (ws && ws.readyState === WebSocket.OPEN && url) { console.log( "Chrome Extension: Sending page-navigated event with URL:", url ); ws.send( JSON.stringify({ type: "page-navigated", url: url, tabId: chrome.devtools.inspectedWindow.tabId, timestamp: Date.now(), }) ); } }); // 1) Listen for network requests chrome.devtools.network.onRequestFinished.addListener((request) => { if (request._resourceType === "xhr" || request._resourceType === "fetch") { request.getContent((responseBody) => { const entry = { type: "network-request", url: request.request.url, method: request.request.method, status: request.response.status, requestHeaders: request.request.headers, responseHeaders: request.response.headers, requestBody: request.request.postData?.text ?? "", responseBody: responseBody ?? "", }; sendToBrowserConnector(entry); }); } }); // Helper function to attach debugger async function attachDebugger() { // First check if we're already attached to this tab chrome.debugger.getTargets((targets) => { const isAlreadyAttached = targets.some( (target) => target.tabId === currentTabId && target.attached ); if (isAlreadyAttached) { console.log("Found existing debugger attachment, detaching first..."); // Force detach first to ensure clean state chrome.debugger.detach({ tabId: currentTabId }, () => { // Ignore any errors during detach if (chrome.runtime.lastError) { console.log("Error during forced detach:", chrome.runtime.lastError); } // Now proceed with fresh attachment performAttach(); }); } else { // No existing attachment, proceed directly performAttach(); } }); } function performAttach() { console.log("Performing debugger attachment to tab:", currentTabId); chrome.debugger.attach({ tabId: currentTabId }, "1.3", () => { if (chrome.runtime.lastError) { console.error("Failed to attach debugger:", chrome.runtime.lastError); isDebuggerAttached = false; return; } isDebuggerAttached = true; console.log("Debugger successfully attached"); // Add the event listener when attaching chrome.debugger.onEvent.addListener(consoleMessageListener); chrome.debugger.sendCommand( { tabId: currentTabId }, "Runtime.enable", {}, () => { if (chrome.runtime.lastError) { console.error("Failed to enable runtime:", chrome.runtime.lastError); return; } console.log("Runtime API successfully enabled"); } ); }); } // Helper function to detach debugger function detachDebugger() { // Remove the event listener first chrome.debugger.onEvent.removeListener(consoleMessageListener); // Check if debugger is actually attached before trying to detach chrome.debugger.getTargets((targets) => { const isStillAttached = targets.some( (target) => target.tabId === currentTabId && target.attached ); if (!isStillAttached) { console.log("Debugger already detached"); isDebuggerAttached = false; return; } chrome.debugger.detach({ tabId: currentTabId }, () => { if (chrome.runtime.lastError) { console.warn( "Warning during debugger detach:", chrome.runtime.lastError ); } isDebuggerAttached = false; console.log("Debugger detached"); }); }); } // Move the console message listener outside the panel creation const consoleMessageListener = (source, method, params) => { // Only process events for our tab if (source.tabId !== currentTabId) { return; } if (method === "Runtime.exceptionThrown") { const entry = { type: "console-error", message: params.exceptionDetails.exception?.description || JSON.stringify(params.exceptionDetails), level: "error", timestamp: Date.now(), }; console.log("Sending runtime exception:", entry); sendToBrowserConnector(entry); } if (method === "Runtime.consoleAPICalled") { // Process all arguments from the console call let formattedMessage = ""; const args = params.args || []; // Extract all arguments and combine them if (args.length > 0) { // Try to build a meaningful representation of all arguments try { formattedMessage = args .map((arg) => { // Handle different types of arguments if (arg.type === "string") { return arg.value; } else if (arg.type === "object" && arg.preview) { // For objects, include their preview or description return JSON.stringify(arg.preview); } else if (arg.description) { // Some objects have descriptions return arg.description; } else { // Fallback for other types return arg.value || arg.description || JSON.stringify(arg); } }) .join(" "); } catch (e) { // Fallback if processing fails console.error("Failed to process console arguments:", e); formattedMessage = args[0]?.value || "Unable to process console arguments"; } } const entry = { type: params.type === "error" ? "console-error" : "console-log", level: params.type, message: formattedMessage, timestamp: Date.now(), }; console.log("Sending console entry:", entry); sendToBrowserConnector(entry); } }; // 2) Use DevTools Protocol to capture console logs chrome.devtools.panels.create("BrowserToolsMCP", "", "panel.html", (panel) => { // Initial attach - we'll keep the debugger attached as long as DevTools is open attachDebugger(); // Handle panel showing panel.onShown.addListener((panelWindow) => { if (!isDebuggerAttached) { attachDebugger(); } }); }); // Clean up when DevTools closes window.addEventListener("unload", () => { // Detach debugger detachDebugger(); // Set intentional closure flag before closing intentionalClosure = true; if (ws) { try { ws.close(); } catch (e) { console.error("Error closing WebSocket during unload:", e); } ws = null; } if (wsReconnectTimeout) { clearTimeout(wsReconnectTimeout); wsReconnectTimeout = null; } if (heartbeatInterval) { clearInterval(heartbeatInterval); heartbeatInterval = null; } }); // Function to capture and send element data function captureAndSendElement() { chrome.devtools.inspectedWindow.eval( `(function() { const el = $0; // $0 is the currently selected element in DevTools if (!el) return null; const rect = el.getBoundingClientRect(); return { tagName: el.tagName, id: el.id, className: el.className, textContent: el.textContent?.substring(0, 100), attributes: Array.from(el.attributes).map(attr => ({ name: attr.name, value: attr.value })), dimensions: { width: rect.width, height: rect.height, top: rect.top, left: rect.left }, innerHTML: el.innerHTML.substring(0, 500) }; })()`, (result, isException) => { if (isException || !result) return; console.log("Element selected:", result); // Send to browser connector sendToBrowserConnector({ type: "selected-element", timestamp: Date.now(), element: result, }); } ); } // Listen for element selection in the Elements panel chrome.devtools.panels.elements.onSelectionChanged.addListener(() => { captureAndSendElement(); }); // WebSocket connection management let ws = null; let wsReconnectTimeout = null; let heartbeatInterval = null; const WS_RECONNECT_DELAY = 5000; // 5 seconds const HEARTBEAT_INTERVAL = 30000; // 30 seconds // Add a flag to track if we need to reconnect after identity validation let reconnectAfterValidation = false; // Track if we're intentionally closing the connection let intentionalClosure = false; // Function to send a heartbeat to keep the WebSocket connection alive function sendHeartbeat() { if (ws && ws.readyState === WebSocket.OPEN) { console.log("Chrome Extension: Sending WebSocket heartbeat"); ws.send(JSON.stringify({ type: "heartbeat" })); } } async function setupWebSocket() { // Clear any pending timeouts if (wsReconnectTimeout) { clearTimeout(wsReconnectTimeout); wsReconnectTimeout = null; } if (heartbeatInterval) { clearInterval(heartbeatInterval); heartbeatInterval = null; } // Close existing WebSocket if any if (ws) { // Set flag to indicate this is an intentional closure intentionalClosure = true; try { ws.close(); } catch (e) { console.error("Error closing existing WebSocket:", e); } ws = null; intentionalClosure = false; // Reset flag } // Validate server identity before connecting console.log("Validating server identity before WebSocket connection..."); const isValid = await validateServerIdentity(); if (!isValid) { console.error( "Cannot establish WebSocket: Not connected to a valid browser tools server" ); // Set flag to indicate we need to reconnect after a page refresh check reconnectAfterValidation = true; // Try again after delay wsReconnectTimeout = setTimeout(() => { console.log("Attempting to reconnect WebSocket after validation failure"); setupWebSocket(); }, WS_RECONNECT_DELAY); return; } // Reset reconnect flag since validation succeeded reconnectAfterValidation = false; const wsUrl = `ws://${settings.serverHost}:${settings.serverPort}/extension-ws`; console.log(`Connecting to WebSocket at ${wsUrl}`); try { ws = new WebSocket(wsUrl); ws.onopen = () => { console.log(`Chrome Extension: WebSocket connected to ${wsUrl}`); // Start heartbeat to keep connection alive heartbeatInterval = setInterval(sendHeartbeat, HEARTBEAT_INTERVAL); // Notify that connection is successful chrome.runtime.sendMessage({ type: "WEBSOCKET_CONNECTED", serverHost: settings.serverHost, serverPort: settings.serverPort, }); // Send the current URL to the server right after connection // This ensures the server has the URL even if no navigation occurs chrome.runtime.sendMessage( { type: "GET_CURRENT_URL", tabId: chrome.devtools.inspectedWindow.tabId, }, (response) => { if (chrome.runtime.lastError) { console.error( "Chrome Extension: Error getting URL from background on connection:", chrome.runtime.lastError ); // If normal method fails, try fallback to chrome.tabs API directly tryFallbackGetUrl(); return; } if (response && response.url) { console.log( "Chrome Extension: Sending initial URL to server:", response.url ); // Send the URL to the server via the background script chrome.runtime.sendMessage({ type: "UPDATE_SERVER_URL", tabId: chrome.devtools.inspectedWindow.tabId, url: response.url, source: "initial_connection", }); } else { // If response exists but no URL, try fallback tryFallbackGetUrl(); } } ); // Fallback method to get URL directly function tryFallbackGetUrl() { console.log("Chrome Extension: Trying fallback method to get URL"); // Try to get the URL directly using the tabs API chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => { if (chrome.runtime.lastError) { console.error( "Chrome Extension: Fallback URL retrieval failed:", chrome.runtime.lastError ); return; } if (tabs && tabs.length > 0 && tabs[0].url) { console.log( "Chrome Extension: Got URL via fallback method:", tabs[0].url ); // Send the URL to the server chrome.runtime.sendMessage({ type: "UPDATE_SERVER_URL", tabId: chrome.devtools.inspectedWindow.tabId, url: tabs[0].url, source: "fallback_method", }); } else { console.warn( "Chrome Extension: Could not retrieve URL through fallback method" ); } }); } }; ws.onerror = (error) => { console.error(`Chrome Extension: WebSocket error for ${wsUrl}:`, error); }; ws.onclose = (event) => { console.log(`Chrome Extension: WebSocket closed for ${wsUrl}:`, event); // Stop heartbeat if (heartbeatInterval) { clearInterval(heartbeatInterval); heartbeatInterval = null; } // Don't reconnect if this was an intentional closure if (intentionalClosure) { console.log( "Chrome Extension: Intentional WebSocket closure, not reconnecting" ); return; } // Only attempt to reconnect if the closure wasn't intentional // Code 1000 (Normal Closure) and 1001 (Going Away) are normal closures // Code 1005 often happens with clean closures in Chrome const isAbnormalClosure = !(event.code === 1000 || event.code === 1001); // Check if this was an abnormal closure or if we need to reconnect after validation if (isAbnormalClosure || reconnectAfterValidation) { console.log( `Chrome Extension: Will attempt to reconnect WebSocket (closure code: ${event.code})` ); // Try to reconnect after delay wsReconnectTimeout = setTimeout(() => { console.log( `Chrome Extension: Attempting to reconnect WebSocket to ${wsUrl}` ); setupWebSocket(); }, WS_RECONNECT_DELAY); } else { console.log( `Chrome Extension: Normal WebSocket closure, not reconnecting automatically` ); } }; ws.onmessage = async (event) => { try { const message = JSON.parse(event.data); // Don't log heartbeat responses to reduce noise if (message.type !== "heartbeat-response") { console.log("Chrome Extension: Received WebSocket message:", message); if (message.type === "server-shutdown") { console.log("Chrome Extension: Received server shutdown signal"); // Clear any reconnection attempts if (wsReconnectTimeout) { clearTimeout(wsReconnectTimeout); wsReconnectTimeout = null; } // Close the connection gracefully ws.close(1000, "Server shutting down"); return; } } if (message.type === "heartbeat-response") { // Just a heartbeat response, no action needed // Uncomment the next line for debug purposes only // console.log("Chrome Extension: Received heartbeat response"); } else if (message.type === "take-screenshot") { console.log("Chrome Extension: Taking screenshot..."); // Capture screenshot of the current tab chrome.tabs.captureVisibleTab(null, { format: "png" }, (dataUrl) => { if (chrome.runtime.lastError) { console.error( "Chrome Extension: Screenshot capture failed:", chrome.runtime.lastError ); ws.send( JSON.stringify({ type: "screenshot-error", error: chrome.runtime.lastError.message, requestId: message.requestId, }) ); return; } console.log("Chrome Extension: Screenshot captured successfully"); // Just send the screenshot data, let the server handle paths const response = { type: "screenshot-data", data: dataUrl, requestId: message.requestId, // Only include path if it's configured in settings ...(settings.screenshotPath && { path: settings.screenshotPath }), // Include auto-paste setting autoPaste: settings.allowAutoPaste, }; console.log("Chrome Extension: Sending screenshot data response", { ...response, data: "[base64 data]", }); ws.send(JSON.stringify(response)); }); } else if (message.type === "get-current-url") { console.log("Chrome Extension: Received request for current URL"); // Get the current URL from the background script instead of inspectedWindow.eval let retryCount = 0; const maxRetries = 2; const requestCurrentUrl = () => { chrome.runtime.sendMessage( { type: "GET_CURRENT_URL", tabId: chrome.devtools.inspectedWindow.tabId, }, (response) => { if (chrome.runtime.lastError) { console.error( "Chrome Extension: Error getting URL from background:", chrome.runtime.lastError ); // Retry logic if (retryCount < maxRetries) { retryCount++; console.log( `Retrying URL request (${retryCount}/${maxRetries})...` ); setTimeout(requestCurrentUrl, 500); // Wait 500ms before retrying return; } ws.send( JSON.stringify({ type: "current-url-response", url: null, tabId: chrome.devtools.inspectedWindow.tabId, error: "Failed to get URL from background: " + chrome.runtime.lastError.message, requestId: message.requestId, }) ); return; } if (response && response.success && response.url) { console.log( "Chrome Extension: Got URL from background:", response.url ); ws.send( JSON.stringify({ type: "current-url-response", url: response.url, tabId: chrome.devtools.inspectedWindow.tabId, requestId: message.requestId, }) ); } else { console.error( "Chrome Extension: Invalid URL response from background:", response ); // Last resort - try to get URL directly from the tab chrome.tabs.query( { active: true, currentWindow: true }, (tabs) => { const url = tabs && tabs[0] && tabs[0].url; console.log( "Chrome Extension: Got URL directly from tab:", url ); ws.send( JSON.stringify({ type: "current-url-response", url: url || null, tabId: chrome.devtools.inspectedWindow.tabId, error: response?.error || "Failed to get URL from background", requestId: message.requestId, }) ); } ); } } ); }; requestCurrentUrl(); } } catch (error) { console.error( "Chrome Extension: Error processing WebSocket message:", error ); } }; } catch (error) { console.error("Error creating WebSocket:", error); // Try again after delay wsReconnectTimeout = setTimeout(setupWebSocket, WS_RECONNECT_DELAY); } } // Initialize WebSocket connection when DevTools opens setupWebSocket(); // Clean up WebSocket when DevTools closes window.addEventListener("unload", () => { if (ws) { ws.close(); } if (wsReconnectTimeout) { clearTimeout(wsReconnectTimeout); } }); ================================================ FILE: chrome-extension/manifest.json ================================================ { "name": "BrowserTools MCP", "version": "1.2.0", "description": "MCP tool for AI code editors to capture data from a browser such as console logs, network requests, screenshots and more", "manifest_version": 3, "devtools_page": "devtools.html", "permissions": [ "activeTab", "debugger", "storage", "tabs", "tabCapture", "windows" ], "host_permissions": [ "" ], "background": { "service_worker": "background.js" } } ================================================ FILE: chrome-extension/panel.html ================================================

Quick Actions

Screenshot Settings

Server Connection Settings

Advanced Settings

================================================ FILE: chrome-extension/panel.js ================================================ // Store settings let settings = { logLimit: 50, queryLimit: 30000, stringSizeLimit: 500, showRequestHeaders: false, showResponseHeaders: false, maxLogSize: 20000, screenshotPath: "", // Add server connection settings serverHost: "localhost", serverPort: 3025, allowAutoPaste: false, // Default auto-paste setting }; // Track connection status let serverConnected = false; let reconnectAttemptTimeout = null; // Add a flag to track ongoing discovery operations let isDiscoveryInProgress = false; // Add an AbortController to cancel fetch operations let discoveryController = null; // Load saved settings on startup chrome.storage.local.get(["browserConnectorSettings"], (result) => { if (result.browserConnectorSettings) { settings = { ...settings, ...result.browserConnectorSettings }; updateUIFromSettings(); } // Create connection status banner at the top createConnectionBanner(); // Automatically discover server on panel load with quiet mode enabled discoverServer(true); }); // Add listener for connection status updates from background script (page refresh events) chrome.runtime.onMessage.addListener((message, sender, sendResponse) => { if (message.type === "CONNECTION_STATUS_UPDATE") { console.log( `Received connection status update: ${ message.isConnected ? "Connected" : "Disconnected" }` ); // Update UI based on connection status if (message.isConnected) { // If already connected, just maintain the current state if (!serverConnected) { // Connection was re-established, update UI serverConnected = true; updateConnectionBanner(true, { name: "Browser Tools Server", version: "reconnected", host: settings.serverHost, port: settings.serverPort, }); } } else { // Connection lost, update UI to show disconnected serverConnected = false; updateConnectionBanner(false, null); } } if (message.type === "INITIATE_AUTO_DISCOVERY") { console.log( `Initiating auto-discovery after page refresh (reason: ${message.reason})` ); // For page refreshes or if forceRestart is set to true, always cancel any ongoing discovery and restart if (message.reason === "page_refresh" || message.forceRestart === true) { // Cancel any ongoing discovery operation cancelOngoingDiscovery(); // Update UI to indicate we're starting a fresh scan if (connectionStatusDiv) { connectionStatusDiv.style.display = "block"; if (statusIcon) statusIcon.className = "status-indicator"; if (statusText) statusText.textContent = "Page refreshed. Restarting server discovery..."; } // Always update the connection banner when a page refresh occurs updateConnectionBanner(false, null); // Start a new discovery process with quiet mode console.log("Starting fresh discovery after page refresh"); discoverServer(true); } // For other types of auto-discovery requests, only start if not already in progress else if (!isDiscoveryInProgress) { // Use quiet mode for auto-discovery to minimize UI changes discoverServer(true); } } // Handle successful server validation if (message.type === "SERVER_VALIDATION_SUCCESS") { console.log( `Server validation successful: ${message.serverHost}:${message.serverPort}` ); // Update the connection status banner serverConnected = true; updateConnectionBanner(true, message.serverInfo); // If we were showing the connection status dialog, we can hide it now if (connectionStatusDiv && connectionStatusDiv.style.display === "block") { connectionStatusDiv.style.display = "none"; } } // Handle failed server validation if (message.type === "SERVER_VALIDATION_FAILED") { console.log( `Server validation failed: ${message.reason} - ${message.serverHost}:${message.serverPort}` ); // Update the connection status serverConnected = false; updateConnectionBanner(false, null); // Start auto-discovery if this was a page refresh validation if ( message.reason === "connection_error" || message.reason === "http_error" ) { // If we're not already trying to discover the server, start the process if (!isDiscoveryInProgress) { console.log("Starting auto-discovery after validation failure"); discoverServer(true); } } } // Handle successful WebSocket connection if (message.type === "WEBSOCKET_CONNECTED") { console.log( `WebSocket connected to ${message.serverHost}:${message.serverPort}` ); // Update connection status if it wasn't already connected if (!serverConnected) { serverConnected = true; updateConnectionBanner(true, { name: "Browser Tools Server", version: "connected via WebSocket", host: message.serverHost, port: message.serverPort, }); } } }); // Create connection status banner function createConnectionBanner() { // Check if banner already exists if (document.getElementById("connection-banner")) { return; } // Create the banner const banner = document.createElement("div"); banner.id = "connection-banner"; banner.style.cssText = ` padding: 6px 0px; margin-bottom: 4px; width: 40%; display: flex; flex-direction: column; align-items: flex-start; background-color:rgba(0,0,0,0); border-radius: 11px; font-size: 11px; font-weight: 500; color: #ffffff; `; // Create reconnect button (now placed at the top) const reconnectButton = document.createElement("button"); reconnectButton.id = "banner-reconnect-btn"; reconnectButton.textContent = "Reconnect"; reconnectButton.style.cssText = ` background-color: #333333; color: #ffffff; border: 1px solid #444444; border-radius: 3px; padding: 2px 8px; font-size: 10px; cursor: pointer; margin-bottom: 6px; align-self: flex-start; display: none; transition: background-color 0.2s; `; reconnectButton.addEventListener("mouseover", () => { reconnectButton.style.backgroundColor = "#444444"; }); reconnectButton.addEventListener("mouseout", () => { reconnectButton.style.backgroundColor = "#333333"; }); reconnectButton.addEventListener("click", () => { // Hide the button while reconnecting reconnectButton.style.display = "none"; reconnectButton.textContent = "Reconnecting..."; // Update UI to show searching state updateConnectionBanner(false, null); // Try to discover server discoverServer(false); }); // Create a container for the status indicator and text const statusContainer = document.createElement("div"); statusContainer.style.cssText = ` display: flex; align-items: center; width: 100%; `; // Create status indicator const indicator = document.createElement("div"); indicator.id = "banner-status-indicator"; indicator.style.cssText = ` width: 6px; height: 6px; position: relative; top: 1px; border-radius: 50%; background-color: #ccc; margin-right: 8px; flex-shrink: 0; transition: background-color 0.3s ease; `; // Create status text const statusText = document.createElement("div"); statusText.id = "banner-status-text"; statusText.textContent = "Searching for server..."; statusText.style.cssText = "flex-grow: 1; font-weight: 400; letter-spacing: 0.1px; font-size: 11px;"; // Add elements to statusContainer statusContainer.appendChild(indicator); statusContainer.appendChild(statusText); // Add elements to banner - reconnect button first, then status container banner.appendChild(reconnectButton); banner.appendChild(statusContainer); // Add banner to the beginning of the document body // This ensures it's the very first element document.body.prepend(banner); // Set initial state updateConnectionBanner(false, null); } // Update the connection banner with current status function updateConnectionBanner(connected, serverInfo) { const indicator = document.getElementById("banner-status-indicator"); const statusText = document.getElementById("banner-status-text"); const banner = document.getElementById("connection-banner"); const reconnectButton = document.getElementById("banner-reconnect-btn"); if (!indicator || !statusText || !banner || !reconnectButton) return; if (connected && serverInfo) { // Connected state with server info indicator.style.backgroundColor = "#4CAF50"; // Green indicator statusText.style.color = "#ffffff"; // White text for contrast on black statusText.textContent = `Connected to ${serverInfo.name} v${serverInfo.version} at ${settings.serverHost}:${settings.serverPort}`; // Hide reconnect button when connected reconnectButton.style.display = "none"; } else if (connected) { // Connected without server info indicator.style.backgroundColor = "#4CAF50"; // Green indicator statusText.style.color = "#ffffff"; // White text for contrast on black statusText.textContent = `Connected to server at ${settings.serverHost}:${settings.serverPort}`; // Hide reconnect button when connected reconnectButton.style.display = "none"; } else { // Disconnected state indicator.style.backgroundColor = "#F44336"; // Red indicator statusText.style.color = "#ffffff"; // White text for contrast on black // Only show "searching" message if discovery is in progress if (isDiscoveryInProgress) { statusText.textContent = "Not connected to server. Searching..."; // Hide reconnect button while actively searching reconnectButton.style.display = "none"; } else { statusText.textContent = "Not connected to server."; // Show reconnect button above status message when disconnected and not searching reconnectButton.style.display = "block"; reconnectButton.textContent = "Reconnect"; } } } // Initialize UI elements const logLimitInput = document.getElementById("log-limit"); const queryLimitInput = document.getElementById("query-limit"); const stringSizeLimitInput = document.getElementById("string-size-limit"); const showRequestHeadersCheckbox = document.getElementById( "show-request-headers" ); const showResponseHeadersCheckbox = document.getElementById( "show-response-headers" ); const maxLogSizeInput = document.getElementById("max-log-size"); const screenshotPathInput = document.getElementById("screenshot-path"); const captureScreenshotButton = document.getElementById("capture-screenshot"); // Server connection UI elements const serverHostInput = document.getElementById("server-host"); const serverPortInput = document.getElementById("server-port"); const discoverServerButton = document.getElementById("discover-server"); const testConnectionButton = document.getElementById("test-connection"); const connectionStatusDiv = document.getElementById("connection-status"); const statusIcon = document.getElementById("status-icon"); const statusText = document.getElementById("status-text"); // Initialize collapsible advanced settings const advancedSettingsHeader = document.getElementById( "advanced-settings-header" ); const advancedSettingsContent = document.getElementById( "advanced-settings-content" ); const chevronIcon = advancedSettingsHeader.querySelector(".chevron"); advancedSettingsHeader.addEventListener("click", () => { advancedSettingsContent.classList.toggle("visible"); chevronIcon.classList.toggle("open"); }); // Get all inputs by ID const allowAutoPasteCheckbox = document.getElementById("allow-auto-paste"); // Update UI from settings function updateUIFromSettings() { logLimitInput.value = settings.logLimit; queryLimitInput.value = settings.queryLimit; stringSizeLimitInput.value = settings.stringSizeLimit; showRequestHeadersCheckbox.checked = settings.showRequestHeaders; showResponseHeadersCheckbox.checked = settings.showResponseHeaders; maxLogSizeInput.value = settings.maxLogSize; screenshotPathInput.value = settings.screenshotPath; serverHostInput.value = settings.serverHost; serverPortInput.value = settings.serverPort; allowAutoPasteCheckbox.checked = settings.allowAutoPaste; } // Save settings function saveSettings() { chrome.storage.local.set({ browserConnectorSettings: settings }); // Notify devtools.js about settings change chrome.runtime.sendMessage({ type: "SETTINGS_UPDATED", settings, }); } // Add event listeners for all inputs logLimitInput.addEventListener("change", (e) => { settings.logLimit = parseInt(e.target.value, 10); saveSettings(); }); queryLimitInput.addEventListener("change", (e) => { settings.queryLimit = parseInt(e.target.value, 10); saveSettings(); }); stringSizeLimitInput.addEventListener("change", (e) => { settings.stringSizeLimit = parseInt(e.target.value, 10); saveSettings(); }); showRequestHeadersCheckbox.addEventListener("change", (e) => { settings.showRequestHeaders = e.target.checked; saveSettings(); }); showResponseHeadersCheckbox.addEventListener("change", (e) => { settings.showResponseHeaders = e.target.checked; saveSettings(); }); maxLogSizeInput.addEventListener("change", (e) => { settings.maxLogSize = parseInt(e.target.value, 10); saveSettings(); }); screenshotPathInput.addEventListener("change", (e) => { settings.screenshotPath = e.target.value; saveSettings(); }); // Add event listeners for server settings serverHostInput.addEventListener("change", (e) => { settings.serverHost = e.target.value; saveSettings(); // Automatically test connection when host is changed testConnection(settings.serverHost, settings.serverPort); }); serverPortInput.addEventListener("change", (e) => { settings.serverPort = parseInt(e.target.value, 10); saveSettings(); // Automatically test connection when port is changed testConnection(settings.serverHost, settings.serverPort); }); // Add event listener for auto-paste checkbox allowAutoPasteCheckbox.addEventListener("change", (e) => { settings.allowAutoPaste = e.target.checked; saveSettings(); }); // Function to cancel any ongoing discovery operations function cancelOngoingDiscovery() { if (isDiscoveryInProgress) { console.log("Cancelling ongoing discovery operation"); // Abort any fetch requests in progress if (discoveryController) { try { discoveryController.abort(); } catch (error) { console.error("Error aborting discovery controller:", error); } discoveryController = null; } // Reset the discovery status isDiscoveryInProgress = false; // Update UI to indicate the operation was cancelled if ( statusText && connectionStatusDiv && connectionStatusDiv.style.display === "block" ) { statusText.textContent = "Server discovery operation cancelled"; } // Clear any pending network timeouts that might be part of the discovery process clearTimeout(reconnectAttemptTimeout); reconnectAttemptTimeout = null; console.log("Discovery operation cancelled successfully"); } } // Test server connection testConnectionButton.addEventListener("click", async () => { // Cancel any ongoing discovery operations before testing cancelOngoingDiscovery(); await testConnection(settings.serverHost, settings.serverPort); }); // Function to test server connection async function testConnection(host, port) { // Cancel any ongoing discovery operations cancelOngoingDiscovery(); connectionStatusDiv.style.display = "block"; statusIcon.className = "status-indicator"; statusText.textContent = "Testing connection..."; try { // Use the identity endpoint instead of .port for more reliable validation const response = await fetch(`http://${host}:${port}/.identity`, { signal: AbortSignal.timeout(5000), // 5 second timeout }); if (response.ok) { const identity = await response.json(); // Verify this is actually our server by checking the signature if (identity.signature !== "mcp-browser-connector-24x7") { statusIcon.className = "status-indicator status-disconnected"; statusText.textContent = `Connection failed: Found a server at ${host}:${port} but it's not the Browser Tools server`; serverConnected = false; updateConnectionBanner(false, null); scheduleReconnectAttempt(); return false; } statusIcon.className = "status-indicator status-connected"; statusText.textContent = `Connected successfully to ${identity.name} v${identity.version} at ${host}:${port}`; serverConnected = true; updateConnectionBanner(true, identity); // Clear any scheduled reconnect attempts if (reconnectAttemptTimeout) { clearTimeout(reconnectAttemptTimeout); reconnectAttemptTimeout = null; } // Update settings if different port was discovered if (parseInt(identity.port, 10) !== port) { console.log(`Detected different port: ${identity.port}`); settings.serverPort = parseInt(identity.port, 10); serverPortInput.value = settings.serverPort; saveSettings(); } return true; } else { statusIcon.className = "status-indicator status-disconnected"; statusText.textContent = `Connection failed: Server returned ${response.status}`; serverConnected = false; // Make sure isDiscoveryInProgress is false so the reconnect button will show isDiscoveryInProgress = false; // Now update the connection banner to show the reconnect button updateConnectionBanner(false, null); scheduleReconnectAttempt(); return false; } } catch (error) { statusIcon.className = "status-indicator status-disconnected"; statusText.textContent = `Connection failed: ${error.message}`; serverConnected = false; // Make sure isDiscoveryInProgress is false so the reconnect button will show isDiscoveryInProgress = false; // Now update the connection banner to show the reconnect button updateConnectionBanner(false, null); scheduleReconnectAttempt(); return false; } } // Schedule a reconnect attempt if server isn't found function scheduleReconnectAttempt() { // Clear any existing reconnect timeout if (reconnectAttemptTimeout) { clearTimeout(reconnectAttemptTimeout); } // Schedule a reconnect attempt in 30 seconds reconnectAttemptTimeout = setTimeout(() => { console.log("Attempting to reconnect to server..."); // Only show minimal UI during auto-reconnect discoverServer(true); }, 30000); // 30 seconds } // Helper function to try connecting to a server async function tryServerConnection(host, port) { try { // Check if the discovery process was cancelled if (!isDiscoveryInProgress) { return false; } // Create a local timeout that won't abort the entire discovery process const controller = new AbortController(); const timeoutId = setTimeout(() => { controller.abort(); }, 500); // 500ms timeout for each connection attempt try { // Use identity endpoint for validation const response = await fetch(`http://${host}:${port}/.identity`, { // Use a local controller for this specific request timeout // but also respect the global discovery cancellation signal: discoveryController ? AbortSignal.any([controller.signal, discoveryController.signal]) : controller.signal, }); clearTimeout(timeoutId); // Check again if discovery was cancelled during the fetch if (!isDiscoveryInProgress) { return false; } if (response.ok) { const identity = await response.json(); // Verify this is actually our server by checking the signature if (identity.signature !== "mcp-browser-connector-24x7") { console.log( `Found a server at ${host}:${port} but it's not the Browser Tools server` ); return false; } console.log(`Successfully found server at ${host}:${port}`); // Update settings with discovered server settings.serverHost = host; settings.serverPort = parseInt(identity.port, 10); serverHostInput.value = settings.serverHost; serverPortInput.value = settings.serverPort; saveSettings(); statusIcon.className = "status-indicator status-connected"; statusText.textContent = `Discovered ${identity.name} v${identity.version} at ${host}:${identity.port}`; // Update connection banner with server info updateConnectionBanner(true, identity); // Update connection status serverConnected = true; // Clear any scheduled reconnect attempts if (reconnectAttemptTimeout) { clearTimeout(reconnectAttemptTimeout); reconnectAttemptTimeout = null; } // End the discovery process isDiscoveryInProgress = false; // Successfully found server return true; } return false; } finally { clearTimeout(timeoutId); } } catch (error) { // Ignore connection errors during discovery // But check if it was an abort (cancellation) if (error.name === "AbortError") { // Check if this was due to the global discovery cancellation if (discoveryController && discoveryController.signal.aborted) { console.log("Connection attempt aborted by global cancellation"); return "aborted"; } // Otherwise it was just a timeout for this specific connection attempt return false; } console.log(`Connection error for ${host}:${port}: ${error.message}`); return false; } } // Server discovery function (extracted to be reusable) async function discoverServer(quietMode = false) { // Cancel any ongoing discovery operations before starting a new one cancelOngoingDiscovery(); // Create a new AbortController for this discovery process discoveryController = new AbortController(); isDiscoveryInProgress = true; // In quiet mode, we don't show the connection status until we either succeed or fail completely if (!quietMode) { connectionStatusDiv.style.display = "block"; statusIcon.className = "status-indicator"; statusText.textContent = "Discovering server..."; } // Always update the connection banner updateConnectionBanner(false, null); try { console.log("Starting server discovery process"); // Add an early cancellation listener that will respond to page navigation/refresh discoveryController.signal.addEventListener("abort", () => { console.log("Discovery aborted via AbortController signal"); isDiscoveryInProgress = false; }); // Common IPs to try (in order of likelihood) const hosts = ["localhost", "127.0.0.1"]; // Add the current configured host if it's not already in the list if ( !hosts.includes(settings.serverHost) && settings.serverHost !== "0.0.0.0" ) { hosts.unshift(settings.serverHost); // Put at the beginning for priority } // Add common local network IPs const commonLocalIps = ["192.168.0.", "192.168.1.", "10.0.0.", "10.0.1."]; for (const prefix of commonLocalIps) { for (let i = 1; i <= 5; i++) { // Reduced from 10 to 5 for efficiency hosts.push(`${prefix}${i}`); } } // Build port list in a smart order: // 1. Start with current configured port // 2. Add default port (3025) // 3. Add sequential ports around the default (for fallback detection) const ports = []; // Current configured port gets highest priority const configuredPort = parseInt(settings.serverPort, 10); ports.push(configuredPort); // Add default port if it's not the same as configured if (configuredPort !== 3025) { ports.push(3025); } // Add sequential fallback ports (from default up to default+10) for (let p = 3026; p <= 3035; p++) { if (p !== configuredPort) { // Avoid duplicates ports.push(p); } } // Remove duplicates const uniquePorts = [...new Set(ports)]; console.log("Will check ports:", uniquePorts); // Create a progress indicator let progress = 0; let totalChecked = 0; // Phase 1: Try the most likely combinations first (current host:port and localhost variants) console.log("Starting Phase 1: Quick check of high-priority hosts/ports"); const priorityHosts = hosts.slice(0, 2); // First two hosts are highest priority for (const host of priorityHosts) { // Check if discovery was cancelled if (!isDiscoveryInProgress) { console.log("Discovery process was cancelled during Phase 1"); return false; } // Try configured port first totalChecked++; if (!quietMode) { statusText.textContent = `Checking ${host}:${uniquePorts[0]}...`; } console.log(`Checking ${host}:${uniquePorts[0]}...`); const result = await tryServerConnection(host, uniquePorts[0]); // Check for cancellation or success if (result === "aborted" || !isDiscoveryInProgress) { console.log("Discovery process was cancelled"); return false; } else if (result === true) { console.log("Server found in priority check"); if (quietMode) { // In quiet mode, only show the connection banner but hide the status box connectionStatusDiv.style.display = "none"; } return true; // Successfully found server } // Then try default port if different if (uniquePorts.length > 1) { // Check if discovery was cancelled if (!isDiscoveryInProgress) { console.log("Discovery process was cancelled"); return false; } totalChecked++; if (!quietMode) { statusText.textContent = `Checking ${host}:${uniquePorts[1]}...`; } console.log(`Checking ${host}:${uniquePorts[1]}...`); const result = await tryServerConnection(host, uniquePorts[1]); // Check for cancellation or success if (result === "aborted" || !isDiscoveryInProgress) { console.log("Discovery process was cancelled"); return false; } else if (result === true) { console.log("Server found in priority check"); if (quietMode) { // In quiet mode, only show the connection banner but hide the status box connectionStatusDiv.style.display = "none"; } return true; // Successfully found server } } } // If we're in quiet mode and the quick checks failed, show the status now // as we move into more intensive scanning if (quietMode) { connectionStatusDiv.style.display = "block"; statusIcon.className = "status-indicator"; statusText.textContent = "Searching for server..."; } // Phase 2: Systematic scan of all combinations const totalAttempts = hosts.length * uniquePorts.length; console.log( `Starting Phase 2: Full scan (${totalAttempts} total combinations)` ); statusText.textContent = `Quick check failed. Starting full scan (${totalChecked}/${totalAttempts})...`; // First, scan through all ports on localhost/127.0.0.1 to find fallback ports quickly const localHosts = ["localhost", "127.0.0.1"]; for (const host of localHosts) { // Skip the first two ports on localhost if we already checked them in Phase 1 const portsToCheck = uniquePorts.slice( localHosts.includes(host) && priorityHosts.includes(host) ? 2 : 0 ); for (const port of portsToCheck) { // Check if discovery was cancelled if (!isDiscoveryInProgress) { console.log("Discovery process was cancelled during local port scan"); return false; } // Update progress progress++; totalChecked++; statusText.textContent = `Scanning local ports... (${totalChecked}/${totalAttempts}) - Trying ${host}:${port}`; console.log(`Checking ${host}:${port}...`); const result = await tryServerConnection(host, port); // Check for cancellation or success if (result === "aborted" || !isDiscoveryInProgress) { console.log("Discovery process was cancelled"); return false; } else if (result === true) { console.log(`Server found at ${host}:${port}`); return true; // Successfully found server } } } // Then scan all the remaining host/port combinations for (const host of hosts) { // Skip hosts we already checked if (localHosts.includes(host)) { continue; } for (const port of uniquePorts) { // Check if discovery was cancelled if (!isDiscoveryInProgress) { console.log("Discovery process was cancelled during remote scan"); return false; } // Update progress progress++; totalChecked++; statusText.textContent = `Scanning remote hosts... (${totalChecked}/${totalAttempts}) - Trying ${host}:${port}`; console.log(`Checking ${host}:${port}...`); const result = await tryServerConnection(host, port); // Check for cancellation or success if (result === "aborted" || !isDiscoveryInProgress) { console.log("Discovery process was cancelled"); return false; } else if (result === true) { console.log(`Server found at ${host}:${port}`); return true; // Successfully found server } } } console.log( `Discovery process completed, checked ${totalChecked} combinations, no server found` ); // If we get here, no server was found statusIcon.className = "status-indicator status-disconnected"; statusText.textContent = "No server found. Please check server is running and try again."; serverConnected = false; // End the discovery process first before updating the banner isDiscoveryInProgress = false; // Update the connection banner to show the reconnect button updateConnectionBanner(false, null); // Schedule a reconnect attempt scheduleReconnectAttempt(); return false; } catch (error) { console.error("Error during server discovery:", error); statusIcon.className = "status-indicator status-disconnected"; statusText.textContent = `Error discovering server: ${error.message}`; serverConnected = false; // End the discovery process first before updating the banner isDiscoveryInProgress = false; // Update the connection banner to show the reconnect button updateConnectionBanner(false, null); // Schedule a reconnect attempt scheduleReconnectAttempt(); return false; } finally { console.log("Discovery process finished"); // Always clean up, even if there was an error if (discoveryController) { discoveryController = null; } } } // Bind discover server button to the extracted function discoverServerButton.addEventListener("click", () => discoverServer(false)); // Screenshot capture functionality captureScreenshotButton.addEventListener("click", () => { captureScreenshotButton.textContent = "Capturing..."; // Send message to background script to capture screenshot chrome.runtime.sendMessage( { type: "CAPTURE_SCREENSHOT", tabId: chrome.devtools.inspectedWindow.tabId, screenshotPath: settings.screenshotPath, }, (response) => { console.log("Screenshot capture response:", response); if (!response) { captureScreenshotButton.textContent = "Failed to capture!"; console.error("Screenshot capture failed: No response received"); } else if (!response.success) { captureScreenshotButton.textContent = "Failed to capture!"; console.error("Screenshot capture failed:", response.error); } else { captureScreenshotButton.textContent = `Captured: ${response.title}`; console.log("Screenshot captured successfully:", response.path); } setTimeout(() => { captureScreenshotButton.textContent = "Capture Screenshot"; }, 2000); } ); }); // Add wipe logs functionality const wipeLogsButton = document.getElementById("wipe-logs"); wipeLogsButton.addEventListener("click", () => { const serverUrl = `http://${settings.serverHost}:${settings.serverPort}/wipelogs`; console.log(`Sending wipe request to ${serverUrl}`); fetch(serverUrl, { method: "POST", headers: { "Content-Type": "application/json" }, }) .then((response) => response.json()) .then((result) => { console.log("Logs wiped successfully:", result.message); wipeLogsButton.textContent = "Logs Wiped!"; setTimeout(() => { wipeLogsButton.textContent = "Wipe All Logs"; }, 2000); }) .catch((error) => { console.error("Failed to wipe logs:", error); wipeLogsButton.textContent = "Failed to Wipe Logs"; setTimeout(() => { wipeLogsButton.textContent = "Wipe All Logs"; }, 2000); }); }); ================================================ FILE: docs/mcp-docs.md ================================================ ## Resources Expose data and content from your servers to LLMs Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions. Resources are designed to be application-controlled, meaning that the client application can decide how and when they should be used. Different MCP clients may handle resources differently. For example: Claude Desktop currently requires users to explicitly select resources before they can be used Other clients might automatically select resources based on heuristics Some implementations may even allow the AI model itself to determine which resources to use Server authors should be prepared to handle any of these interaction patterns when implementing resource support. In order to expose data to models automatically, server authors should use a model-controlled primitive such as Tools. ​ Overview Resources represent any kind of data that an MCP server wants to make available to clients. This can include: File contents Database records API responses Live system data Screenshots and images Log files And more Each resource is identified by a unique URI and can contain either text or binary data. ​ Resource URIs Resources are identified using URIs that follow this format: [protocol]://[host]/[path] For example: file:///home/user/documents/report.pdf postgres://database/customers/schema screen://localhost/display1 The protocol and path structure is defined by the MCP server implementation. Servers can define their own custom URI schemes. ​ Resource types Resources can contain two types of content: ​ Text resources Text resources contain UTF-8 encoded text data. These are suitable for: Source code Configuration files Log files JSON/XML data Plain text ​ Binary resources Binary resources contain raw binary data encoded in base64. These are suitable for: Images PDFs Audio files Video files Other non-text formats ​ Resource discovery Clients can discover available resources through two main methods: ​ Direct resources Servers expose a list of concrete resources via the resources/list endpoint. Each resource includes: { uri: string; // Unique identifier for the resource name: string; // Human-readable name description?: string; // Optional description mimeType?: string; // Optional MIME type } ​ Resource templates For dynamic resources, servers can expose URI templates that clients can use to construct valid resource URIs: { uriTemplate: string; // URI template following RFC 6570 name: string; // Human-readable name for this type description?: string; // Optional description mimeType?: string; // Optional MIME type for all matching resources } ​ Reading resources To read a resource, clients make a resources/read request with the resource URI. The server responds with a list of resource contents: { contents: [ { uri: string; // The URI of the resource mimeType?: string; // Optional MIME type // One of: text?: string; // For text resources blob?: string; // For binary resources (base64 encoded) } ] } Servers may return multiple resources in response to one resources/read request. This could be used, for example, to return a list of files inside a directory when the directory is read. ​ Resource updates MCP supports real-time updates for resources through two mechanisms: ​ List changes Servers can notify clients when their list of available resources changes via the notifications/resources/list_changed notification. ​ Content changes Clients can subscribe to updates for specific resources: Client sends resources/subscribe with resource URI Server sends notifications/resources/updated when the resource changes Client can fetch latest content with resources/read Client can unsubscribe with resources/unsubscribe ​ Example implementation Here’s a simple example of implementing resource support in an MCP server: ## Prompts Create reusable prompt templates and workflows Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions. Prompts are designed to be user-controlled, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use. ​ Overview Prompts in MCP are predefined templates that can: Accept dynamic arguments Include context from resources Chain multiple interactions Guide specific workflows Surface as UI elements (like slash commands) ​ Prompt structure Each prompt is defined with: { name: string; // Unique identifier for the prompt description?: string; // Human-readable description arguments?: [ // Optional list of arguments { name: string; // Argument identifier description?: string; // Argument description required?: boolean; // Whether argument is required } ] } ​ Discovering prompts Clients can discover available prompts through the prompts/list endpoint: // Request { method: "prompts/list" } // Response { prompts: [ { name: "analyze-code", description: "Analyze code for potential improvements", arguments: [ { name: "language", description: "Programming language", required: true } ] } ] } ​ Using prompts To use a prompt, clients make a prompts/get request: // Request { method: "prompts/get", params: { name: "analyze-code", arguments: { language: "python" } } } // Response { description: "Analyze Python code for potential improvements", messages: [ { role: "user", content: { type: "text", text: "Please analyze the following Python code for potential improvements:\n\n`python\ndef calculate_sum(numbers):\n total = 0\n for num in numbers:\n total = total + num\n return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n`" } } ] } ​ Dynamic prompts Prompts can be dynamic and include: ​ Embedded resource context { "name": "analyze-project", "description": "Analyze project logs and code", "arguments": [ { "name": "timeframe", "description": "Time period to analyze logs", "required": true }, { "name": "fileUri", "description": "URI of code file to review", "required": true } ] } When handling the prompts/get request: { "messages": [ { "role": "user", "content": { "type": "text", "text": "Analyze these system logs and the code file for any issues:" } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "logs://recent?timeframe=1h", "text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded", "mimeType": "text/plain" } } }, { "role": "user", "content": { "type": "resource", "resource": { "uri": "file:///path/to/code.py", "text": "def connect_to_service(timeout=30):\n retries = 3\n for attempt in range(retries):\n try:\n return establish_connection(timeout)\n except TimeoutError:\n if attempt == retries - 1:\n raise\n time.sleep(5)\n\ndef establish_connection(timeout):\n # Connection implementation\n pass", "mimeType": "text/x-python" } } } ] } ​ Multi-step workflows const debugWorkflow = { name: "debug-error", async getMessages(error: string) { return [ { role: "user", content: { type: "text", text: `Here's an error I'm seeing: ${error}` } }, { role: "assistant", content: { type: "text", text: "I'll help analyze this error. What have you tried so far?" } }, { role: "user", content: { type: "text", text: "I've tried restarting the service, but the error persists." } } ]; } }; ​ Example implementation Here’s a complete example of implementing prompts in an MCP server: TypeScript Python import { Server } from "@modelcontextprotocol/sdk/server"; import { ListPromptsRequestSchema, GetPromptRequestSchema } from "@modelcontextprotocol/sdk/types"; const PROMPTS = { "git-commit": { name: "git-commit", description: "Generate a Git commit message", arguments: [ { name: "changes", description: "Git diff or description of changes", required: true } ] }, "explain-code": { name: "explain-code", description: "Explain how code works", arguments: [ { name: "code", description: "Code to explain", required: true }, { name: "language", description: "Programming language", required: false } ] } }; const server = new Server({ name: "example-prompts-server", version: "1.0.0" }, { capabilities: { prompts: {} } }); // List available prompts server.setRequestHandler(ListPromptsRequestSchema, async () => { return { prompts: Object.values(PROMPTS) }; }); // Get specific prompt server.setRequestHandler(GetPromptRequestSchema, async (request) => { const prompt = PROMPTS[request.params.name]; if (!prompt) { throw new Error(`Prompt not found: ${request.params.name}`); } if (request.params.name === "git-commit") { return { messages: [ { role: "user", content: { type: "text", text: `Generate a concise but descriptive commit message for these changes:\n\n${request.params.arguments?.changes}` } } ] }; } if (request.params.name === "explain-code") { const language = request.params.arguments?.language || "Unknown"; return { messages: [ { role: "user", content: { type: "text", text: `Explain how this ${language} code works:\n\n${request.params.arguments?.code}` } } ] }; } throw new Error("Prompt implementation not found"); }); ​ Best practices When implementing prompts: Use clear, descriptive prompt names Provide detailed descriptions for prompts and arguments Validate all required arguments Handle missing arguments gracefully Consider versioning for prompt templates Cache dynamic content when appropriate Implement error handling Document expected argument formats Consider prompt composability Test prompts with various inputs ​ UI integration Prompts can be surfaced in client UIs as: Slash commands Quick actions Context menu items Command palette entries Guided workflows Interactive forms ​ Updates and changes Servers can notify clients about prompt changes: Server capability: prompts.listChanged Notification: notifications/prompts/list_changed Client re-fetches prompt list ​ Security considerations When implementing prompts: Validate all arguments Sanitize user input Consider rate limiting Implement access controls Audit prompt usage Handle sensitive data appropriately Validate generated content Implement timeouts Consider prompt injection risks Document security requirements ## Tools Tools Enable LLMs to perform actions through your server Tools are a powerful primitive in the Model Context Protocol (MCP) that enable servers to expose executable functionality to clients. Through tools, LLMs can interact with external systems, perform computations, and take actions in the real world. Tools are designed to be model-controlled, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval). ​ Overview Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions. Key aspects of tools include: Discovery: Clients can list available tools through the tools/list endpoint Invocation: Tools are called using the tools/call endpoint, where servers perform the requested operation and return results Flexibility: Tools can range from simple calculations to complex API interactions Like resources, tools are identified by unique names and can include descriptions to guide their usage. However, unlike resources, tools represent dynamic operations that can modify state or interact with external systems. ​ Tool definition structure Each tool is defined with the following structure: { name: string; // Unique identifier for the tool description?: string; // Human-readable description inputSchema: { // JSON Schema for the tool's parameters type: "object", properties: { ... } // Tool-specific parameters } } ​ Implementing tools Here’s an example of implementing a basic tool in an MCP server: TypeScript Python const server = new Server({ name: "example-server", version: "1.0.0" }, { capabilities: { tools: {} } }); // Define available tools server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [{ name: "calculate_sum", description: "Add two numbers together", inputSchema: { type: "object", properties: { a: { type: "number" }, b: { type: "number" } }, required: ["a", "b"] } }] }; }); // Handle tool execution server.setRequestHandler(CallToolRequestSchema, async (request) => { if (request.params.name === "calculate_sum") { const { a, b } = request.params.arguments; return { content: [ { type: "text", text: String(a + b) } ] }; } throw new Error("Tool not found"); }); ​ Example tool patterns Here are some examples of types of tools that a server could provide: ​ System operations Tools that interact with the local system: { name: "execute_command", description: "Run a shell command", inputSchema: { type: "object", properties: { command: { type: "string" }, args: { type: "array", items: { type: "string" } } } } } ​ API integrations Tools that wrap external APIs: { name: "github_create_issue", description: "Create a GitHub issue", inputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string" }, labels: { type: "array", items: { type: "string" } } } } } ​ Data processing Tools that transform or analyze data: { name: "analyze_csv", description: "Analyze a CSV file", inputSchema: { type: "object", properties: { filepath: { type: "string" }, operations: { type: "array", items: { enum: ["sum", "average", "count"] } } } } } ​ Best practices When implementing tools: Provide clear, descriptive names and descriptions Use detailed JSON Schema definitions for parameters Include examples in tool descriptions to demonstrate how the model should use them Implement proper error handling and validation Use progress reporting for long operations Keep tool operations focused and atomic Document expected return value structures Implement proper timeouts Consider rate limiting for resource-intensive operations Log tool usage for debugging and monitoring ​ Security considerations When exposing tools: ​ Input validation Validate all parameters against the schema Sanitize file paths and system commands Validate URLs and external identifiers Check parameter sizes and ranges Prevent command injection ​ Access control Implement authentication where needed Use appropriate authorization checks Audit tool usage Rate limit requests Monitor for abuse ​ Error handling Don’t expose internal errors to clients Log security-relevant errors Handle timeouts appropriately Clean up resources after errors Validate return values ​ Tool discovery and updates MCP supports dynamic tool discovery: Clients can list available tools at any time Servers can notify clients when tools change using notifications/tools/list_changed Tools can be added or removed during runtime Tool definitions can be updated (though this should be done carefully) ​ Error handling Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error: Set isError to true in the result Include error details in the content array Here’s an example of proper error handling for tools: TypeScript Python try { // Tool operation const result = performOperation(); return { content: [ { type: "text", text: `Operation successful: ${result}` } ] }; } catch (error) { return { isError: true, content: [ { type: "text", text: `Error: ${error.message}` } ] }; } This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention. ​ Testing tools A comprehensive testing strategy for MCP tools should cover: Functional testing: Verify tools execute correctly with valid inputs and handle invalid inputs appropriately Integration testing: Test tool interaction with external systems using both real and mocked dependencies Security testing: Validate authentication, authorization, input sanitization, and rate limiting Performance testing: Check behavior under load, timeout handling, and resource cleanup Error handling: Ensure tools properly report errors through the MCP protocol and clean up resources ## Sampling Sampling Let your servers request completions from LLMs Sampling is a powerful MCP feature that allows servers to request LLM completions through the client, enabling sophisticated agentic behaviors while maintaining security and privacy. This feature of MCP is not yet supported in the Claude Desktop client. ​ How sampling works The sampling flow follows these steps: Server sends a sampling/createMessage request to the client Client reviews the request and can modify it Client samples from an LLM Client reviews the completion Client returns the result to the server This human-in-the-loop design ensures users maintain control over what the LLM sees and generates. ​ Message format Sampling requests use a standardized message format: { messages: [ { role: "user" | "assistant", content: { type: "text" | "image", // For text: text?: string, // For images: data?: string, // base64 encoded mimeType?: string } } ], modelPreferences?: { hints?: [{ name?: string // Suggested model name/family }], costPriority?: number, // 0-1, importance of minimizing cost speedPriority?: number, // 0-1, importance of low latency intelligencePriority?: number // 0-1, importance of capabilities }, systemPrompt?: string, includeContext?: "none" | "thisServer" | "allServers", temperature?: number, maxTokens: number, stopSequences?: string[], metadata?: Record } ​ Request parameters ​ Messages The messages array contains the conversation history to send to the LLM. Each message has: role: Either “user” or “assistant” content: The message content, which can be: Text content with a text field Image content with data (base64) and mimeType fields ​ Model preferences The modelPreferences object allows servers to specify their model selection preferences: hints: Array of model name suggestions that clients can use to select an appropriate model: name: String that can match full or partial model names (e.g. “claude-3”, “sonnet”) Clients may map hints to equivalent models from different providers Multiple hints are evaluated in preference order Priority values (0-1 normalized): costPriority: Importance of minimizing costs speedPriority: Importance of low latency response intelligencePriority: Importance of advanced model capabilities Clients make the final model selection based on these preferences and their available models. ​ System prompt An optional systemPrompt field allows servers to request a specific system prompt. The client may modify or ignore this. ​ Context inclusion The includeContext parameter specifies what MCP context to include: "none": No additional context "thisServer": Include context from the requesting server "allServers": Include context from all connected MCP servers The client controls what context is actually included. ​ Sampling parameters Fine-tune the LLM sampling with: temperature: Controls randomness (0.0 to 1.0) maxTokens: Maximum tokens to generate stopSequences: Array of sequences that stop generation metadata: Additional provider-specific parameters ​ Response format The client returns a completion result: { model: string, // Name of the model used stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string, role: "user" | "assistant", content: { type: "text" | "image", text?: string, data?: string, mimeType?: string } } ​ Example request Here’s an example of requesting sampling from a client: { "method": "sampling/createMessage", "params": { "messages": [ { "role": "user", "content": { "type": "text", "text": "What files are in the current directory?" } } ], "systemPrompt": "You are a helpful file system assistant.", "includeContext": "thisServer", "maxTokens": 100 } } ​ Best practices When implementing sampling: Always provide clear, well-structured prompts Handle both text and image content appropriately Set reasonable token limits Include relevant context through includeContext Validate responses before using them Handle errors gracefully Consider rate limiting sampling requests Document expected sampling behavior Test with various model parameters Monitor sampling costs ​ Human in the loop controls Sampling is designed with human oversight in mind: ​ For prompts Clients should show users the proposed prompt Users should be able to modify or reject prompts System prompts can be filtered or modified Context inclusion is controlled by the client ​ For completions Clients should show users the completion Users should be able to modify or reject completions Clients can filter or modify completions Users control which model is used ​ Security considerations When implementing sampling: Validate all message content Sanitize sensitive information Implement appropriate rate limits Monitor sampling usage Encrypt data in transit Handle user data privacy Audit sampling requests Control cost exposure Implement timeouts Handle model errors gracefully ​ Common patterns ​ Agentic workflows Sampling enables agentic patterns like: Reading and analyzing resources Making decisions based on context Generating structured data Handling multi-step tasks Providing interactive assistance ​ Context management Best practices for context: Request minimal necessary context Structure context clearly Handle context size limits Update context as needed Clean up stale context ​ Error handling Robust error handling should: Catch sampling failures Handle timeout errors Manage rate limits Validate responses Provide fallback behaviors Log errors appropriately ​ Limitations Be aware of these limitations: Sampling depends on client capabilities Users control sampling behavior Context size has limits Rate limits may apply Costs should be considered Model availability varies Response times vary Not all content types supported ## Roots Roots Understanding roots in MCP Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations. ​ What are Roots? A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs. For example, roots could be: file:///home/user/projects/myapp https://api.example.com/v1 ​ Why Use Roots? Roots serve several important purposes: Guidance: They inform servers about relevant resources and locations Clarity: Roots make it clear which resources are part of your workspace Organization: Multiple roots let you work with different resources simultaneously ​ How Roots Work When a client supports roots, it: Declares the roots capability during connection Provides a list of suggested roots to the server Notifies the server when roots change (if supported) While roots are informational and not strictly enforcing, servers should: Respect the provided roots Use root URIs to locate and access resources Prioritize operations within root boundaries ​ Common Use Cases Roots are commonly used to define: Project directories Repository locations API endpoints Configuration locations Resource boundaries ​ Best Practices When working with roots: Only suggest necessary resources Use clear, descriptive names for roots Monitor root accessibility Handle root changes gracefully ​ Example Here’s how a typical MCP client might expose roots: { "roots": [ { "uri": "file:///home/user/projects/frontend", "name": "Frontend Repository" }, { "uri": "https://api.example.com/v1", "name": "API Endpoint" } ] } This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated. ## Transports Transports Learn about MCP’s communication mechanisms Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received. ​ Message Format MCP uses JSON-RPC 2.0 as its wire format. The transport layer is responsible for converting MCP protocol messages into JSON-RPC format for transmission and converting received JSON-RPC messages back into MCP protocol messages. There are three types of JSON-RPC messages used: ​ Requests { jsonrpc: "2.0", id: number | string, method: string, params?: object } ​ Responses { jsonrpc: "2.0", id: number | string, result?: object, error?: { code: number, message: string, data?: unknown } } ​ Notifications { jsonrpc: "2.0", method: string, params?: object } ​ Built-in Transport Types MCP includes two standard transport implementations: ​ Standard Input/Output (stdio) The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools. Use stdio when: Building command-line tools Implementing local integrations Needing simple process communication Working with shell scripts TypeScript (Server) TypeScript (Client) Python (Server) Python (Client) const server = new Server({ name: "example-server", version: "1.0.0" }, { capabilities: {} }); const transport = new StdioServerTransport(); await server.connect(transport); ​ Server-Sent Events (SSE) SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication. Use SSE when: Only server-to-client streaming is needed Working with restricted networks Implementing simple updates TypeScript (Server) TypeScript (Client) Python (Server) Python (Client) import express from "express"; const app = express(); const server = new Server({ name: "example-server", version: "1.0.0" }, { capabilities: {} }); let transport: SSEServerTransport | null = null; app.get("/sse", (req, res) => { transport = new SSEServerTransport("/messages", res); server.connect(transport); }); app.post("/messages", (req, res) => { if (transport) { transport.handlePostMessage(req, res); } }); app.listen(3000); ​ Custom Transports MCP makes it easy to implement custom transports for specific needs. Any transport implementation just needs to conform to the Transport interface: You can implement custom transports for: Custom network protocols Specialized communication channels Integration with existing systems Performance optimization TypeScript Python interface Transport { // Start processing messages start(): Promise; // Send a JSON-RPC message send(message: JSONRPCMessage): Promise; // Close the connection close(): Promise; // Callbacks onclose?: () => void; onerror?: (error: Error) => void; onmessage?: (message: JSONRPCMessage) => void; } ​ Error Handling Transport implementations should handle various error scenarios: Connection errors Message parsing errors Protocol errors Network timeouts Resource cleanup Example error handling: TypeScript Python class ExampleTransport implements Transport { async start() { try { // Connection logic } catch (error) { this.onerror?.(new Error(`Failed to connect: ${error}`)); throw error; } } async send(message: JSONRPCMessage) { try { // Sending logic } catch (error) { this.onerror?.(new Error(`Failed to send message: ${error}`)); throw error; } } } ​ Best Practices When implementing or using MCP transport: Handle connection lifecycle properly Implement proper error handling Clean up resources on connection close Use appropriate timeouts Validate messages before sending Log transport events for debugging Implement reconnection logic when appropriate Handle backpressure in message queues Monitor connection health Implement proper security measures ​ Security Considerations When implementing transport: ​ Authentication and Authorization Implement proper authentication mechanisms Validate client credentials Use secure token handling Implement authorization checks ​ Data Security Use TLS for network transport Encrypt sensitive data Validate message integrity Implement message size limits Sanitize input data ​ Network Security Implement rate limiting Use appropriate timeouts Handle denial of service scenarios Monitor for unusual patterns Implement proper firewall rules ​ Debugging Transport Tips for debugging transport issues: Enable debug logging Monitor message flow Check connection states Validate message formats Test error scenarios Use network analysis tools Implement health checks Monitor resource usage Test edge cases Use proper error tracking ================================================ FILE: docs/mcp.md ================================================ # MCP TypeScript SDK ![NPM Version](mdc:https:/img.shields.io/npm/v/%40modelcontextprotocol%2Fsdk) ![MIT licensed](mdc:https:/img.shields.io/npm/l/%40modelcontextprotocol%2Fsdk) ## Table of Contents - [Overview](mdc:#overview) - [Installation](mdc:#installation) - [Quickstart](mdc:#quickstart) - [What is MCP?](mdc:#what-is-mcp) - [Core Concepts](mdc:#core-concepts) - [Server](mdc:#server) - [Resources](mdc:#resources) - [Tools](mdc:#tools) - [Prompts](mdc:#prompts) - [Running Your Server](mdc:#running-your-server) - [stdio](mdc:#stdio) - [HTTP with SSE](mdc:#http-with-sse) - [Testing and Debugging](mdc:#testing-and-debugging) - [Examples](mdc:#examples) - [Echo Server](mdc:#echo-server) - [SQLite Explorer](mdc:#sqlite-explorer) - [Advanced Usage](mdc:#advanced-usage) - [Low-Level Server](mdc:#low-level-server) - [Writing MCP Clients](mdc:#writing-mcp-clients) - [Server Capabilities](mdc:#server-capabilities) ## Overview The Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This TypeScript SDK implements the full MCP specification, making it easy to: - Build MCP clients that can connect to any MCP server - Create MCP servers that expose resources, prompts and tools - Use standard transports like stdio and SSE - Handle all MCP protocol messages and lifecycle events ## Installation ```bash npm install @modelcontextprotocol/sdk ``` ## Quick Start Let's create a simple MCP server that exposes a calculator tool and some data: ```typescript import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // Create an MCP server const server = new McpServer({ name: "Demo", version: "1.0.0", }); // Add an addition tool server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }], })); // Add a dynamic greeting resource server.resource( "greeting", new ResourceTemplate("greeting://{name}", { list: undefined }), async (uri, { name }) => ({ contents: [ { uri: uri.href, text: `Hello, ${name}!`, }, ], }) ); // Start receiving messages on stdin and sending messages on stdout const transport = new StdioServerTransport(); await server.connect(transport); ``` ## What is MCP? The [Model Context Protocol (MCP)](mdc:https:/modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can: - Expose data through **Resources** (think of these sort of like GET endpoints; they are used to load information into the LLM's context) - Provide functionality through **Tools** (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect) - Define interaction patterns through **Prompts** (reusable templates for LLM interactions) - And more! ## Core Concepts ### Server The McpServer is your core interface to the MCP protocol. It handles connection management, protocol compliance, and message routing: ```typescript const server = new McpServer({ name: "My App", version: "1.0.0", }); ``` ### Resources Resources are how you expose data to LLMs. They're similar to GET endpoints in a REST API - they provide data but shouldn't perform significant computation or have side effects: ```typescript // Static resource server.resource("config", "config://app", async (uri) => ({ contents: [ { uri: uri.href, text: "App configuration here", }, ], })); // Dynamic resource with parameters server.resource( "user-profile", new ResourceTemplate("users://{userId}/profile", { list: undefined }), async (uri, { userId }) => ({ contents: [ { uri: uri.href, text: `Profile data for user ${userId}`, }, ], }) ); ``` ### Tools Tools let LLMs take actions through your server. Unlike resources, tools are expected to perform computation and have side effects: ```typescript // Simple tool with parameters server.tool( "calculate-bmi", { weightKg: z.number(), heightM: z.number(), }, async ({ weightKg, heightM }) => ({ content: [ { type: "text", text: String(weightKg / (heightM * heightM)), }, ], }) ); // Async tool with external API call server.tool("fetch-weather", { city: z.string() }, async ({ city }) => { const response = await fetch(`https://api.weather.com/${city}`); const data = await response.text(); return { content: [{ type: "text", text: data }], }; }); ``` ### Prompts Prompts are reusable templates that help LLMs interact with your server effectively: ```typescript server.prompt("review-code", { code: z.string() }, ({ code }) => ({ messages: [ { role: "user", content: { type: "text", text: `Please review this code:\n\n${code}`, }, }, ], })); ``` ## Running Your Server MCP servers in TypeScript need to be connected to a transport to communicate with clients. How you start the server depends on the choice of transport: ### stdio For command-line tools and direct integrations: ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new McpServer({ name: "example-server", version: "1.0.0", }); // ... set up server resources, tools, and prompts ... const transport = new StdioServerTransport(); await server.connect(transport); ``` ### HTTP with SSE For remote servers, start a web server with a Server-Sent Events (SSE) endpoint, and a separate endpoint for the client to send its messages to: ```typescript import express from "express"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js"; const server = new McpServer({ name: "example-server", version: "1.0.0", }); // ... set up server resources, tools, and prompts ... const app = express(); app.get("/sse", async (req, res) => { const transport = new SSEServerTransport("/messages", res); await server.connect(transport); }); app.post("/messages", async (req, res) => { // Note: to support multiple simultaneous connections, these messages will // need to be routed to a specific matching transport. (This logic isn't // implemented here, for simplicity.) await transport.handlePostMessage(req, res); }); app.listen(3001); ``` ### Testing and Debugging To test your server, you can use the [MCP Inspector](mdc:https:/github.com/modelcontextprotocol/inspector). See its README for more information. ## Examples ### Echo Server A simple server demonstrating resources, tools, and prompts: ```typescript import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod"; const server = new McpServer({ name: "Echo", version: "1.0.0", }); server.resource( "echo", new ResourceTemplate("echo://{message}", { list: undefined }), async (uri, { message }) => ({ contents: [ { uri: uri.href, text: `Resource echo: ${message}`, }, ], }) ); server.tool("echo", { message: z.string() }, async ({ message }) => ({ content: [{ type: "text", text: `Tool echo: ${message}` }], })); server.prompt("echo", { message: z.string() }, ({ message }) => ({ messages: [ { role: "user", content: { type: "text", text: `Please process this message: ${message}`, }, }, ], })); ``` ### SQLite Explorer A more complex example showing database integration: ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import sqlite3 from "sqlite3"; import { promisify } from "util"; import { z } from "zod"; const server = new McpServer({ name: "SQLite Explorer", version: "1.0.0", }); // Helper to create DB connection const getDb = () => { const db = new sqlite3.Database("database.db"); return { all: promisify(db.all.bind(db)), close: promisify(db.close.bind(db)), }; }; server.resource("schema", "schema://main", async (uri) => { const db = getDb(); try { const tables = await db.all( "SELECT sql FROM sqlite_master WHERE type='table'" ); return { contents: [ { uri: uri.href, text: tables.map((t: { sql: string }) => t.sql).join("\n"), }, ], }; } finally { await db.close(); } }); server.tool("query", { sql: z.string() }, async ({ sql }) => { const db = getDb(); try { const results = await db.all(sql); return { content: [ { type: "text", text: JSON.stringify(results, null, 2), }, ], }; } catch (err: unknown) { const error = err as Error; return { content: [ { type: "text", text: `Error: ${error.message}`, }, ], isError: true, }; } finally { await db.close(); } }); ``` ## Advanced Usage ### Low-Level Server For more control, you can use the low-level Server class directly: ```typescript import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; const server = new Server( { name: "example-server", version: "1.0.0", }, { capabilities: { prompts: {}, }, } ); server.setRequestHandler(ListPromptsRequestSchema, async () => { return { prompts: [ { name: "example-prompt", description: "An example prompt template", arguments: [ { name: "arg1", description: "Example argument", required: true, }, ], }, ], }; }); server.setRequestHandler(GetPromptRequestSchema, async (request) => { if (request.params.name !== "example-prompt") { throw new Error("Unknown prompt"); } return { description: "Example prompt", messages: [ { role: "user", content: { type: "text", text: "Example prompt text", }, }, ], }; }); const transport = new StdioServerTransport(); await server.connect(transport); ``` ### Writing MCP Clients The SDK provides a high-level client interface: ```typescript import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"; const transport = new StdioClientTransport({ command: "node", args: ["server.js"], }); const client = new Client( { name: "example-client", version: "1.0.0", }, { capabilities: { prompts: {}, resources: {}, tools: {}, }, } ); await client.connect(transport); // List prompts const prompts = await client.listPrompts(); // Get a prompt const prompt = await client.getPrompt("example-prompt", { arg1: "value", }); // List resources const resources = await client.listResources(); // Read a resource const resource = await client.readResource("file:///example.txt"); // Call a tool const result = await client.callTool({ name: "example-tool", arguments: { arg1: "value", }, }); ``` ## Documentation - [Model Context Protocol documentation](mdc:https:/modelcontextprotocol.io) - [MCP Specification](mdc:https:/spec.modelcontextprotocol.io) - [Example Servers](mdc:https:/github.com/modelcontextprotocol/servers) ## Contributing Issues and pull requests are welcome on GitHub at https://github.com/modelcontextprotocol/typescript-sdk. ## License This project is licensed under the MIT License—see the [LICENSE](mdc:LICENSE) file for details.