Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

8.6 KB
Raw Blame
/**
 * 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 { fileURLToPath } from 'url';

import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import debug from 'debug';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { startMcpHttpServer } from './http';
import { toMcpTool } from './tool';

import type { CallToolResult, CallToolRequest, Root, Tool } from '@modelcontextprotocol/sdk/types.js';
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
export type { Server } from '@modelcontextprotocol/sdk/server/index.js';
export type { Tool, CallToolResult, CallToolRequest, Root } from '@modelcontextprotocol/sdk/types.js';
import type { Server as ServerType } from '@modelcontextprotocol/sdk/server/index.js';
import type { ToolSchema } from './tool';

const serverDebug = debug('pw:mcp:server');
const serverDebugResponse = debug('pw:mcp:server:response');

export type ClientInfo = {
  cwd: string;
  clientName: string;
};

export interface ServerBackend {
  initialize?(clientInfo: ClientInfo): Promise<void>;
  callTool(name: string, args: CallToolRequest['params']['arguments'], signal: AbortSignal): Promise<CallToolResult>;
  dynamicTools?(): Tool[];
  on?(event: 'dynamictoolschange', listener: () => void): void;
  dispose?(): Promise<void>;
  once(event: 'disconnected', listener: () => void): void;
}

export type ServerBackendFactory = {
  name: string;
  nameInConfig: string;
  version: string;
  toolSchemas: ToolSchema<any>[];
  ignoreRoots?: boolean;
  create: (clientInfo: ClientInfo) => Promise<ServerBackend>;
};

export async function connect(factory: ServerBackendFactory, transport: Transport, transportInitialized: Promise<void>, runHeartbeat: boolean) {
  const server = createServer(factory.name, factory.version, factory, transportInitialized, runHeartbeat);
  await server.connect(transport);
}

export function createServer(name: string, version: string, factory: ServerBackendFactory, transportInitialized: Promise<void>, runHeartbeat: boolean): ServerType {
  const server = new Server({ name, version }, {
    capabilities: {
      tools: { listChanged: true },
    }
  });

  let backendPromise: Promise<ServerBackend> | undefined;
  let heartbeatStarted = false;

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    serverDebug('listTools');
    const tools = factory.toolSchemas.map(s => toMcpTool(s));
    const backend = await backendPromise?.catch(() => undefined);
    tools.push(...backend?.dynamicTools?.() ?? []);
    return { tools };
  });

  const onClose = () => backendPromise?.then(b => b.dispose?.()).catch(serverDebug);
  addServerListener(server, 'close', onClose);

  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
    serverDebug('callTool', request);

    try {
      if (!backendPromise) {
        const promise = initializeServer(server, factory, transportInitialized).then(backend => {
          backend.on?.('dynamictoolschange', () => {
            if (backendPromise === promise)
              void server.sendToolListChanged().catch(serverDebug);
          });
          backend.once('disconnected', () => {
            if (backendPromise === promise)
              backendPromise = undefined;
            void backend.dispose?.().catch(serverDebug);
          });
          if (runHeartbeat && !heartbeatStarted) {
            heartbeatStarted = true;
            void transportInitialized.then(() => startHeartbeat(server));
          }
          return backend;
        }).catch(e => {
          if (backendPromise === promise)
            backendPromise = undefined;
          throw e;
        });
        backendPromise = promise;
      }

      const backend = await backendPromise;
      const toolResult = await backend.callTool(request.params.name, request.params.arguments || {}, extra.signal);
      const mergedResult = mergeTextParts(toolResult);
      serverDebugResponse('callResult', mergedResult);
      return mergedResult;
    } catch (error) {
      return {
        content: [{ type: 'text', text: '### Error\n' + String(error) }],
        isError: true,
      };
    }
  });
  return server;
}

const initializeServer = async (server: ServerType, factory: ServerBackendFactory, transportInitialized: Promise<void>): Promise<ServerBackend> => {
  const capabilities = server.getClientCapabilities();
  let clientRoots: Root[] = [];
  if (capabilities?.roots && !factory.ignoreRoots) {
    await Promise.race([transportInitialized, new Promise<void>(f => setTimeout(f, 5000))]);
    const { roots } = await server.listRoots().catch(e => {
      serverDebug(e);
      return { roots: [] };
    });
    clientRoots = roots;
  }

  const clientInfo: ClientInfo = {
    cwd: firstRootPath(clientRoots),
    clientName: server.getClientVersion()?.name ?? 'Playwright MCP',
  };

  const backend = await factory.create(clientInfo);
  await backend.initialize?.(clientInfo);
  return backend;
};

const defaultPingTimeout = 5000;

const pingTimeout = (): number => {
  const value = process.env.PLAYWRIGHT_MCP_PING_TIMEOUT_MS;
  if (value === undefined)
    return defaultPingTimeout;
  const parsed = Number(value);
  if (!Number.isFinite(parsed))
    return defaultPingTimeout;
  return parsed;
};

const startHeartbeat = (server: ServerType) => {
  const timeout = pingTimeout();
  if (timeout <= 0)
    return;

  const beat = () => {
    Promise.race([
      server.ping(),
      new Promise((_, reject) => setTimeout(() => reject(new Error('ping timeout')), timeout)),
    ]).then(() => {
      setTimeout(beat, 3000);
    }).catch(() => {
      void server.close();
    });
  };

  beat();
};

function addServerListener(server: ServerType, event: 'close' | 'initialized', listener: () => void) {
  const oldListener = server[`on${event}`];
  server[`on${event}`] = () => {
    oldListener?.();
    listener();
  };
}

export async function start(serverBackendFactory: ServerBackendFactory, options: { host?: string; port?: number, allowedHosts?: string[], socketPath?: string } = {}) {
  if (options.port === undefined) {
    const transport = new StdioServerTransport();
    // Do not close the transport on stdin end. The exit watchdog closes the browsers on stdin
    // close, and closing a browser that is already closing force-kills it.
    await connect(serverBackendFactory, transport, Promise.resolve(), false);
    return;
  }

  const url = await startMcpHttpServer(options, serverBackendFactory, options.allowedHosts);

  const mcpConfig: any = { mcpServers: { } };
  mcpConfig.mcpServers[serverBackendFactory.nameInConfig] = {
    url: `${url}/mcp`
  };
  const message = [
    `Listening on ${url}`,
    'Put this in your client config:',
    JSON.stringify(mcpConfig, 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);
}

export function firstRootPath(roots: Root[]): string {
  return allRootPaths(roots)[0];
}

export function allRootPaths(roots: Root[]): string[] {
  const paths: string[] = [];
  for (const root of roots) {
    const url = new URL(root.uri);
    let rootPath;
    try {
      rootPath = fileURLToPath(url);
    } catch (e) {
      // Support WSL paths on Windows.
      if (e.code === 'ERR_INVALID_FILE_URL_PATH' && process.platform === 'win32')
        rootPath = decodeURIComponent(url.pathname);
    }
    if (!rootPath)
      continue;
    paths.push(rootPath);
  }
  if (paths.length === 0)
    paths.push(process.cwd());
  return paths;
}

function mergeTextParts(result: CallToolResult): CallToolResult {
  const content: CallToolResult['content'] = [];
  const testParts: string[] = [];
  for (const part of result.content) {
    if (part.type === 'text') {
      testParts.push(part.text);
      continue;
    }
    if (testParts.length > 0) {
      content.push({ type: 'text', text: testParts.join('\n') });
      testParts.length = 0;
    }
    content.push(part);
  }
  if (testParts.length > 0)
    content.push({ type: 'text', text: testParts.join('\n') });
  return {
    ...result,
    content,
  };
}