playwright-mcp-phantomx 0.0.1

package/lib/mcp/inProcessTransport.js

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export class InProcessTransport {
+    _server;
+    _serverTransport;
+    _connected = false;
+    constructor(server) {
+        this._server = server;
+        this._serverTransport = new InProcessServerTransport(this);
+    }
+    async start() {
+        if (this._connected)
+            throw new Error('InprocessTransport already started!');
+        await this._server.connect(this._serverTransport);
+        this._connected = true;
+    }
+    async send(message, options) {
+        if (!this._connected)
+            throw new Error('Transport not connected');
+        this._serverTransport._receiveFromClient(message);
+    }
+    async close() {
+        if (this._connected) {
+            this._connected = false;
+            this.onclose?.();
+            this._serverTransport.onclose?.();
+        }
+    }
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    setProtocolVersion;
+    _receiveFromServer(message, extra) {
+        this.onmessage?.(message, extra);
+    }
+}
+class InProcessServerTransport {
+    _clientTransport;
+    constructor(clientTransport) {
+        this._clientTransport = clientTransport;
+    }
+    async start() {
+    }
+    async send(message, options) {
+        this._clientTransport._receiveFromServer(message);
+    }
+    async close() {
+        this.onclose?.();
+    }
+    onclose;
+    onerror;
+    onmessage;
+    sessionId;
+    setProtocolVersion;
+    _receiveFromClient(message) {
+        this.onmessage?.(message);
+    }
+}

package/lib/mcp/server.js

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { ManualPromise } from '../manualPromise.js';
+import { logUnhandledError } from '../log.js';
+export async function connect(serverBackendFactory, transport, runHeartbeat) {
+    const backend = serverBackendFactory();
+    const server = createServer(backend, runHeartbeat);
+    await server.connect(transport);
+}
+export function createServer(backend, runHeartbeat) {
+    const initializedPromise = new ManualPromise();
+    const server = new Server({ name: backend.name, version: backend.version }, {
+        capabilities: {
+            tools: {},
+        }
+    });
+    const tools = backend.tools();
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return { tools: tools.map(tool => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: zodToJsonSchema(tool.inputSchema),
+                annotations: {
+                    title: tool.title,
+                    readOnlyHint: tool.type === 'readOnly',
+                    destructiveHint: tool.type === 'destructive',
+                    openWorldHint: true,
+                },
+            })) };
+    });
+    let heartbeatRunning = false;
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        await initializedPromise;
+        if (runHeartbeat && !heartbeatRunning) {
+            heartbeatRunning = true;
+            startHeartbeat(server);
+        }
+        const errorResult = (...messages) => ({
+            content: [{ type: 'text', text: '### Result\n' + messages.join('\n') }],
+            isError: true,
+        });
+        const tool = tools.find(tool => tool.name === request.params.name);
+        if (!tool)
+            return errorResult(`Error: Tool "${request.params.name}" not found`);
+        try {
+            return await backend.callTool(tool, tool.inputSchema.parse(request.params.arguments || {}));
+        }
+        catch (error) {
+            return errorResult(String(error));
+        }
+    });
+    addServerListener(server, 'initialized', () => {
+        backend.initialize?.(server).then(() => initializedPromise.resolve()).catch(logUnhandledError);
+    });
+    addServerListener(server, 'close', () => backend.serverClosed?.());
+    return server;
+}
+const startHeartbeat = (server) => {
+    const beat = () => {
+        Promise.race([
+            server.ping(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('ping timeout')), 5000)),
+        ]).then(() => {
+            setTimeout(beat, 3000);
+        }).catch(() => {
+            void server.close();
+        });
+    };
+    beat();
+};
+function addServerListener(server, event, listener) {
+    const oldListener = server[`on${event}`];
+    server[`on${event}`] = () => {
+        oldListener?.();
+        listener();
+    };
+}

package/lib/mcp/transport.js

@@ -0,0 +1,140 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import crypto from 'crypto';
+import debug from 'debug';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { httpAddressToString, startHttpServer } from '../httpServer.js';
+import * as mcpServer from './server.js';
+export async function start(serverBackendFactory, options) {
+    if (options.port !== undefined) {
+        const httpServer = await startHttpServer(options);
+        startHttpTransport(httpServer, serverBackendFactory);
+    }
+    else {
+        await startStdioTransport(serverBackendFactory);
+    }
+}
+async function startStdioTransport(serverBackendFactory) {
+    await mcpServer.connect(serverBackendFactory, new StdioServerTransport(), false);
+}
+const testDebug = debug('pw:mcp:test');
+function handleHealthCheck(req, res) {
+    if (req.method !== 'GET') {
+        res.statusCode = 405;
+        res.setHeader('Content-Type', 'application/json');
+        return res.end(JSON.stringify({ error: 'Method not allowed' }));
+    }
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'application/json');
+    res.end(JSON.stringify({
+        status: 'ok',
+        service: 'playwright-mcp',
+        timestamp: new Date().toISOString()
+    }));
+}
+async function handleSSE(serverBackendFactory, req, res, url, sessions) {
+    if (req.method === 'POST') {
+        const sessionId = url.searchParams.get('sessionId');
+        if (!sessionId) {
+            res.statusCode = 400;
+            return res.end('Missing sessionId');
+        }
+        const transport = sessions.get(sessionId);
+        if (!transport) {
+            res.statusCode = 404;
+            return res.end('Session not found');
+        }
+        return await transport.handlePostMessage(req, res);
+    }
+    else if (req.method === 'GET') {
+        const transport = new SSEServerTransport('/sse', res);
+        sessions.set(transport.sessionId, transport);
+        testDebug(`create SSE session: ${transport.sessionId}`);
+        await mcpServer.connect(serverBackendFactory, transport, false);
+        res.on('close', () => {
+            testDebug(`delete SSE session: ${transport.sessionId}`);
+            sessions.delete(transport.sessionId);
+        });
+        return;
+    }
+    res.statusCode = 405;
+    res.end('Method not allowed');
+}
+async function handleStreamable(serverBackendFactory, req, res, sessions) {
+    const sessionId = req.headers['mcp-session-id'];
+    if (sessionId) {
+        const transport = sessions.get(sessionId);
+        if (!transport) {
+            res.statusCode = 404;
+            res.end('Session not found');
+            return;
+        }
+        return await transport.handleRequest(req, res);
+    }
+    if (req.method === 'POST') {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => crypto.randomUUID(),
+            onsessioninitialized: async (sessionId) => {
+                testDebug(`create http session: ${transport.sessionId}`);
+                await mcpServer.connect(serverBackendFactory, transport, true);
+                sessions.set(sessionId, transport);
+            }
+        });
+        transport.onclose = () => {
+            if (!transport.sessionId)
+                return;
+            sessions.delete(transport.sessionId);
+            testDebug(`delete http session: ${transport.sessionId}`);
+        };
+        await transport.handleRequest(req, res);
+        return;
+    }
+    res.statusCode = 400;
+    res.end('Invalid request');
+}
+function startHttpTransport(httpServer, serverBackendFactory) {
+    const sseSessions = new Map();
+    const streamableSessions = new Map();
+    httpServer.on('request', async (req, res) => {
+        const url = new URL(`http://localhost${req.url}`);
+        if (url.pathname === '/health' || url.pathname === '/health/') {
+            handleHealthCheck(req, res);
+        }
+        else if (url.pathname.startsWith('/sse')) {
+            await handleSSE(serverBackendFactory, req, res, url, sseSessions);
+        }
+        else {
+            await handleStreamable(serverBackendFactory, req, res, streamableSessions);
+        }
+    });
+    const url = httpAddressToString(httpServer.address());
+    const message = [
+        `Listening on ${url}`,
+        'Put this in your client config:',
+        JSON.stringify({
+            'mcpServers': {
+                'playwright': {
+                    'url': `${url}/mcp`
+                }
+            }
+        }, undefined, 2),
+        'For legacy SSE transport support, you can use the /sse endpoint instead.',
+    ].join('\n');
+    // eslint-disable-next-line no-console
+    console.error(message);
+}

package/lib/package.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'fs';
+import path from 'path';
+import url from 'url';
+const __filename = url.fileURLToPath(import.meta.url);
+export const packageJSON = JSON.parse(fs.readFileSync(path.join(path.dirname(__filename), '..', 'package.json'), 'utf8'));

package/lib/program.js

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { program, Option } from 'commander';
+// @ts-ignore
+import { startTraceViewerServer } from 'playwright-core/lib/server';
+import * as mcpTransport from './mcp/transport.js';
+import { commaSeparatedList, resolveCLIConfig, semicolonSeparatedList } from './config.js';
+import { packageJSON } from './package.js';
+import { createExtensionContextFactory, runWithExtension } from './extension/main.js';
+import { BrowserServerBackend } from './browserServerBackend.js';
+import { Context } from './context.js';
+import { contextFactory } from './browserContextFactory.js';
+import { runLoopTools } from './loopTools/main.js';
+program
+    .version('Version ' + packageJSON.version)
+    .name(packageJSON.name)
+    .option('--allowed-origins <origins>', 'semicolon-separated list of origins to allow the browser to request. Default is to allow all.', semicolonSeparatedList)
+    .option('--blocked-origins <origins>', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
+    .option('--block-service-workers', 'block service workers')
+    .option('--browser <browser>', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.')
+    .option('--caps <caps>', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf.', commaSeparatedList)
+    .option('--cdp-endpoint <endpoint>', 'CDP endpoint to connect to.')
+    .option('--config <path>', 'path to the configuration file.')
+    .option('--device <device>', 'device to emulate, for example: "iPhone 15"')
+    .option('--executable-path <path>', 'path to the browser executable.')
+    .option('--headless', 'run browser in headless mode, headed by default')
+    .option('--host <host>', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
+    .option('--ignore-https-errors', 'ignore https errors')
+    .option('--isolated', 'keep the browser profile in memory, do not save it to disk.')
+    .option('--image-responses <mode>', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".')
+    .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.')
+    .option('--output-dir <path>', 'path to the directory for output files.')
+    .option('--port <port>', 'port to listen on for SSE transport.')
+    .option('--proxy-bypass <bypass>', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"')
+    .option('--proxy-server <proxy>', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"')
+    .option('--save-session', 'Whether to save the Playwright MCP session into the output directory.')
+    .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.')
+    .option('--storage-state <path>', 'path to the storage state file for isolated sessions.')
+    .option('--user-agent <ua string>', 'specify user agent string')
+    .option('--user-data-dir <path>', 'path to the user data directory. If not specified, a temporary directory will be created.')
+    .option('--viewport-size <size>', 'specify browser viewport size in pixels, for example "1280, 720"')
+    .addOption(new Option('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.').hideHelp())
+    .addOption(new Option('--connect-tool', 'Allow to switch between different browser connection methods.').hideHelp())
+    .addOption(new Option('--loop-tools', 'Run loop tools').hideHelp())
+    .addOption(new Option('--vision', 'Legacy option, use --caps=vision instead').hideHelp())
+    .action(async (options) => {
+    setupExitWatchdog();
+    if (options.vision) {
+        // eslint-disable-next-line no-console
+        console.error('The --vision option is deprecated, use --caps=vision instead');
+        options.caps = 'vision';
+    }
+    const config = await resolveCLIConfig(options);
+    if (options.extension) {
+        await runWithExtension(config);
+        return;
+    }
+    if (options.loopTools) {
+        await runLoopTools(config);
+        return;
+    }
+    const browserContextFactory = contextFactory(config);
+    const factories = [browserContextFactory];
+    if (options.connectTool)
+        factories.push(createExtensionContextFactory(config));
+    const serverBackendFactory = () => new BrowserServerBackend(config, factories);
+    await mcpTransport.start(serverBackendFactory, config.server);
+    if (config.saveTrace) {
+        const server = await startTraceViewerServer();
+        const urlPrefix = server.urlPrefix('human-readable');
+        const url = urlPrefix + '/trace/index.html?trace=' + config.browser.launchOptions.tracesDir + '/trace.json';
+        // eslint-disable-next-line no-console
+        console.error('\nTrace viewer listening on ' + url);
+    }
+});
+function setupExitWatchdog() {
+    let isExiting = false;
+    const handleExit = async () => {
+        if (isExiting)
+            return;
+        isExiting = true;
+        setTimeout(() => process.exit(0), 15000);
+        await Context.disposeAll();
+        process.exit(0);
+    };
+    process.stdin.on('close', handleExit);
+    process.on('SIGINT', handleExit);
+    process.on('SIGTERM', handleExit);
+}
+void program.parseAsync(process.argv);

package/lib/response.js

@@ -0,0 +1,165 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { renderModalStates } from './tab.js';
+export class Response {
+    _result = [];
+    _code = [];
+    _images = [];
+    _context;
+    _includeSnapshot = false;
+    _includeTabs = false;
+    _tabSnapshot;
+    toolName;
+    toolArgs;
+    _isError;
+    constructor(context, toolName, toolArgs) {
+        this._context = context;
+        this.toolName = toolName;
+        this.toolArgs = toolArgs;
+    }
+    addResult(result) {
+        this._result.push(result);
+    }
+    addError(error) {
+        this._result.push(error);
+        this._isError = true;
+    }
+    isError() {
+        return this._isError;
+    }
+    result() {
+        return this._result.join('\n');
+    }
+    addCode(code) {
+        this._code.push(code);
+    }
+    code() {
+        return this._code.join('\n');
+    }
+    addImage(image) {
+        this._images.push(image);
+    }
+    images() {
+        return this._images;
+    }
+    setIncludeSnapshot() {
+        this._includeSnapshot = true;
+    }
+    setIncludeTabs() {
+        this._includeTabs = true;
+    }
+    async finish() {
+        // All the async snapshotting post-action is happening here.
+        // Everything below should race against modal states.
+        if (this._includeSnapshot && this._context.currentTab())
+            this._tabSnapshot = await this._context.currentTabOrDie().captureSnapshot();
+        for (const tab of this._context.tabs())
+            await tab.updateTitle();
+    }
+    tabSnapshot() {
+        return this._tabSnapshot;
+    }
+    serialize() {
+        const response = [];
+        // Start with command result.
+        if (this._result.length) {
+            response.push('### Result');
+            response.push(this._result.join('\n'));
+            response.push('');
+        }
+        // Add code if it exists.
+        if (this._code.length) {
+            response.push(`### Ran Playwright code
+\`\`\`js
+${this._code.join('\n')}
+\`\`\``);
+            response.push('');
+        }
+        // List browser tabs.
+        if (this._includeSnapshot || this._includeTabs)
+            response.push(...renderTabsMarkdown(this._context.tabs(), this._includeTabs));
+        // Add snapshot if provided.
+        if (this._tabSnapshot?.modalStates.length) {
+            response.push(...renderModalStates(this._context, this._tabSnapshot.modalStates));
+            response.push('');
+        }
+        else if (this._tabSnapshot) {
+            response.push(renderTabSnapshot(this._tabSnapshot));
+            response.push('');
+        }
+        // Main response part
+        const content = [
+            { type: 'text', text: response.join('\n') },
+        ];
+        // Image attachments.
+        if (this._context.config.imageResponses !== 'omit') {
+            for (const image of this._images)
+                content.push({ type: 'image', data: image.data.toString('base64'), mimeType: image.contentType });
+        }
+        return { content, isError: this._isError };
+    }
+}
+function renderTabSnapshot(tabSnapshot) {
+    const lines = [];
+    if (tabSnapshot.consoleMessages.length) {
+        lines.push(`### New console messages`);
+        for (const message of tabSnapshot.consoleMessages)
+            lines.push(`- ${trim(message.toString(), 100)}`);
+        lines.push('');
+    }
+    if (tabSnapshot.downloads.length) {
+        lines.push(`### Downloads`);
+        for (const entry of tabSnapshot.downloads) {
+            if (entry.finished)
+                lines.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+            else
+                lines.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+        }
+        lines.push('');
+    }
+    lines.push(`### Page state`);
+    lines.push(`- Page URL: ${tabSnapshot.url}`);
+    lines.push(`- Page Title: ${tabSnapshot.title}`);
+    lines.push(`- Page Snapshot:`);
+    lines.push('```yaml');
+    lines.push(tabSnapshot.ariaSnapshot);
+    lines.push('```');
+    return lines.join('\n');
+}
+function renderTabsMarkdown(tabs, force = false) {
+    if (tabs.length === 1 && !force)
+        return [];
+    if (!tabs.length) {
+        return [
+            '### Open tabs',
+            'No open tabs. Use the "browser_navigate" tool to navigate to a page first.',
+            '',
+        ];
+    }
+    const lines = ['### Open tabs'];
+    for (let i = 0; i < tabs.length; i++) {
+        const tab = tabs[i];
+        const current = tab.isCurrentTab() ? ' (current)' : '';
+        lines.push(`- ${i}:${current} [${tab.lastTitle()}] (${tab.page.url()})`);
+    }
+    lines.push('');
+    return lines;
+}
+function trim(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength) + '...';
+}