@wordbricks/playwright-mcp 0.1.3

package/lib/hooks/registry.js

@@ -0,0 +1,39 @@
+import { pipe, reduce, values } from '@fxts/core';
+import { createHookRegistry, setToolHooks } from './core.js';
+import { networkTrackingHooks } from './networkTrackingHook.js';
+import { pageHeightHooks } from './pageHeightHook.js';
+import { waitHooks } from './waitHook.js';
+import { frameworkStateHooks } from './frameworkStateHook.js';
+import { jsonLdDetectionHooks } from './jsonLdDetectionHook.js';
+import { toolNameSchema } from './schema.js';
+import { requireTabHooks } from './requireTabHook.js';
+import { registerGroupingRule } from './grouping.js';
+import { networkGroupingRule } from './networkTrackingHook.js';
+const COMMON_HOOKS = {
+    preHooks: [
+        requireTabHooks.pre,
+        networkTrackingHooks.pre,
+        pageHeightHooks.pre,
+        frameworkStateHooks.pre,
+        jsonLdDetectionHooks.pre
+    ],
+    postHooks: [
+        frameworkStateHooks.post,
+        jsonLdDetectionHooks.post,
+        networkTrackingHooks.post,
+        pageHeightHooks.post,
+        waitHooks.post
+    ],
+};
+const toolHooksConfig = [
+// Example hook registration
+// {
+//   toolName: toolNameSchema.enum.browser_click,
+//   preHooks: [],
+//   postHooks: [],
+// },
+];
+export const buildHookRegistry = () => {
+    registerGroupingRule('network-request', networkGroupingRule);
+    return pipe(createHookRegistry(), registry => reduce((acc, toolName) => setToolHooks(acc, { toolName, ...COMMON_HOOKS }), registry, values(toolNameSchema.enum)), registry => reduce(setToolHooks, registry, toolHooksConfig));
+};

package/lib/hooks/requireTabHook.js

@@ -0,0 +1,26 @@
+import { Ok, Err } from '../utils/result.js';
+import { hookNameSchema, toolNameSchema } from './schema.js';
+const MESSAGE = 'No open tabs. Use the "browser_navigate" tool to navigate to a page first.';
+const requireTabPreHook = {
+    name: hookNameSchema.enum['require-tab-pre'],
+    handler: async (ctx) => {
+        try {
+            // Allow navigate tool to create/open a tab
+            if (ctx.toolName === toolNameSchema.enum.browser_navigate)
+                return Ok(undefined);
+            // If no current tab, emit a standardized error and stop execution
+            if (!ctx.context.currentTab()) {
+                // Include tabs section in response so the message is rendered consistently
+                ctx.response.setIncludeTabs();
+                return Err(new Error(MESSAGE));
+            }
+            return Ok(undefined);
+        }
+        catch (error) {
+            return Err(error);
+        }
+    },
+};
+export const requireTabHooks = {
+    pre: requireTabPreHook,
+};

package/lib/hooks/schema.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+export const hookNameSchema = z.enum([
+    'network-tracking-pre',
+    'network-tracking-post',
+    'page-height-pre',
+    'page-height-post',
+    'wait-post',
+    'framework-state-pre',
+    'framework-state-post',
+    'json-ld-detection-pre',
+    'json-ld-detection-post',
+    'require-tab-pre',
+]);
+// Tool names enum - should match actual tool names in
+export const toolNameSchema = z.enum([
+    'browser_click',
+    'browser_extract_framework_state',
+    'browser_get_snapshot',
+    // 'browser_get_visible_html',
+    'browser_navigate',
+    // 'browser_navigate_back',
+    // 'browser_navigate_forward',
+    'browser_network_detail',
+    'browser_network_search',
+    'browser_press_key',
+    'browser_reload',
+    'browser_repl',
+    'browser_scroll',
+    'browser_wait',
+]);
+export const EventTypeSchema = z.enum([
+    'network-request',
+    'page-height-change',
+    'wait',
+    'tool-call',
+    'framework-state',
+    'json-ld',
+]);
+export const NetworkRequestEventDataSchema = z.object({
+    method: z.string(),
+    url: z.string(),
+    status: z.number(),
+    resourceType: z.string(),
+    postData: z.string().optional(),
+    responseSize: z.number().optional(),
+});
+export const PageHeightChangeEventDataSchema = z.object({
+    previousHeight: z.number(),
+    currentHeight: z.number(),
+    heightChange: z.number(),
+    scrollY: z.number(),
+    url: z.string(),
+});
+export const WaitEventDataSchema = z.object({
+    duration: z.number(),
+});
+export const ToolCallEventDataSchema = z.object({
+    toolName: z.string(),
+    params: z.record(z.unknown()).optional(),
+    executionTime: z.number().optional(),
+    success: z.boolean().optional(),
+});
+export const FrameworkStateEventDataSchema = z.object({
+    state: z.record(z.any()),
+    changes: z.array(z.string()).optional(),
+    action: z.enum(['detected', 'changed']),
+});
+export const JsonLdEventDataSchema = z.object({
+    state: z.record(z.object({
+        count: z.number(),
+        indices: z.array(z.number()),
+    })),
+    changes: z.array(z.string()).optional(),
+    action: z.enum(['detected', 'changed']),
+});

package/lib/hooks/waitHook.js

@@ -0,0 +1,33 @@
+import ms from 'ms';
+import { Ok, Err } from '../utils/result.js';
+import { trackEvent } from './events.js';
+import { hookNameSchema } from './schema.js';
+export const WAIT_TIME_STR = '0.5s';
+export const WAIT_TIME_MS = ms(WAIT_TIME_STR);
+const waitPostHook = {
+    name: hookNameSchema.enum['wait-post'],
+    handler: async (ctx) => {
+        try {
+            const tab = ctx.tab || ctx.context.currentTab();
+            if (!tab)
+                return Ok(undefined);
+            const startTime = Date.now();
+            await tab.page.waitForTimeout(WAIT_TIME_MS);
+            trackEvent(ctx.context, {
+                type: 'wait',
+                data: {
+                    duration: WAIT_TIME_MS,
+                },
+                timestamp: startTime,
+            });
+            return Ok(undefined);
+        }
+        catch (error) {
+            return Err(error);
+        }
+    },
+};
+export const waitHooks = {
+    post: waitPostHook,
+};
+export const formatWaitEvent = (event) => `Waited ${event.data.duration}ms`;

package/lib/index.js

@@ -0,0 +1,39 @@
+/**
+ * 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 { BrowserServerBackend } from './browserServerBackend.js';
+import { resolveConfig } from './config.js';
+import { contextFactory } from './browserContextFactory.js';
+import * as mcpServer from './mcp/server.js';
+export async function createConnection(userConfig = {}, contextGetter) {
+    const config = await resolveConfig(userConfig);
+    const factory = contextGetter ? new SimpleBrowserContextFactory(contextGetter) : contextFactory(config);
+    return mcpServer.createServer(new BrowserServerBackend(config, factory), false);
+}
+class SimpleBrowserContextFactory {
+    name = 'custom';
+    description = 'Connect to a browser using a custom context getter';
+    _contextGetter;
+    constructor(contextGetter) {
+        this._contextGetter = contextGetter;
+    }
+    async createContext() {
+        const browserContext = await this._contextGetter();
+        return {
+            browserContext,
+            close: () => browserContext.close()
+        };
+    }
+}

package/lib/loop/loop.js

@@ -0,0 +1,69 @@
+/**
+ * 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 debug from 'debug';
+export async function runTask(delegate, client, task, oneShot = false) {
+    const { tools } = await client.listTools();
+    const taskContent = oneShot ? `Perform following task: ${task}.` : `Perform following task: ${task}. Once the task is complete, call the "done" tool.`;
+    const conversation = delegate.createConversation(taskContent, tools, oneShot);
+    for (let iteration = 0; iteration < 5; ++iteration) {
+        debug('history')('Making API call for iteration', iteration);
+        const toolCalls = await delegate.makeApiCall(conversation);
+        if (toolCalls.length === 0)
+            throw new Error('Call the "done" tool when the task is complete.');
+        const toolResults = [];
+        for (const toolCall of toolCalls) {
+            const doneResult = delegate.checkDoneToolCall(toolCall);
+            if (doneResult !== null)
+                return conversation.messages;
+            const { name, arguments: args, id } = toolCall;
+            try {
+                debug('tool')(name, args);
+                const response = await client.callTool({
+                    name,
+                    arguments: args,
+                });
+                const responseContent = (response.content || []);
+                debug('tool')(responseContent);
+                const text = responseContent.filter(part => part.type === 'text').map(part => part.text).join('\n');
+                toolResults.push({
+                    toolCallId: id,
+                    content: text,
+                });
+            }
+            catch (error) {
+                debug('tool')(error);
+                toolResults.push({
+                    toolCallId: id,
+                    content: `Error while executing tool "${name}": ${error instanceof Error ? error.message : String(error)}\n\nPlease try to recover and complete the task.`,
+                    isError: true,
+                });
+                // Skip remaining tool calls for this iteration
+                for (const remainingToolCall of toolCalls.slice(toolCalls.indexOf(toolCall) + 1)) {
+                    toolResults.push({
+                        toolCallId: remainingToolCall.id,
+                        content: `This tool call is skipped due to previous error.`,
+                        isError: true,
+                    });
+                }
+                break;
+            }
+        }
+        delegate.addToolResults(conversation, toolResults);
+        if (oneShot)
+            return conversation.messages;
+    }
+    throw new Error('Failed to perform step, max attempts reached');
+}

package/lib/loop/loopClaude.js

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+const model = 'claude-sonnet-4-20250514';
+export class ClaudeDelegate {
+    _anthropic;
+    async anthropic() {
+        if (!this._anthropic) {
+            const anthropic = await import('@anthropic-ai/sdk');
+            this._anthropic = new anthropic.Anthropic();
+        }
+        return this._anthropic;
+    }
+    createConversation(task, tools, oneShot) {
+        const llmTools = tools.map(tool => ({
+            name: tool.name,
+            description: tool.description || '',
+            inputSchema: tool.inputSchema,
+        }));
+        if (!oneShot) {
+            llmTools.push({
+                name: 'done',
+                description: 'Call this tool when the task is complete.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            });
+        }
+        return {
+            messages: [{
+                    role: 'user',
+                    content: task
+                }],
+            tools: llmTools,
+        };
+    }
+    async makeApiCall(conversation) {
+        // Convert generic messages to Claude format
+        const claudeMessages = [];
+        for (const message of conversation.messages) {
+            if (message.role === 'user') {
+                claudeMessages.push({
+                    role: 'user',
+                    content: message.content
+                });
+            }
+            else if (message.role === 'assistant') {
+                const content = [];
+                // Add text content
+                if (message.content) {
+                    content.push({
+                        type: 'text',
+                        text: message.content,
+                        citations: []
+                    });
+                }
+                // Add tool calls
+                if (message.toolCalls) {
+                    for (const toolCall of message.toolCalls) {
+                        content.push({
+                            type: 'tool_use',
+                            id: toolCall.id,
+                            name: toolCall.name,
+                            input: toolCall.arguments
+                        });
+                    }
+                }
+                claudeMessages.push({
+                    role: 'assistant',
+                    content
+                });
+            }
+            else if (message.role === 'tool') {
+                // Tool results are added differently - we need to find if there's already a user message with tool results
+                const lastMessage = claudeMessages[claudeMessages.length - 1];
+                const toolResult = {
+                    type: 'tool_result',
+                    tool_use_id: message.toolCallId,
+                    content: message.content,
+                    is_error: message.isError,
+                };
+                if (lastMessage && lastMessage.role === 'user' && Array.isArray(lastMessage.content)) {
+                    // Add to existing tool results message
+                    lastMessage.content.push(toolResult);
+                }
+                else {
+                    // Create new tool results message
+                    claudeMessages.push({
+                        role: 'user',
+                        content: [toolResult]
+                    });
+                }
+            }
+        }
+        // Convert generic tools to Claude format
+        const claudeTools = conversation.tools.map(tool => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.inputSchema,
+        }));
+        const anthropic = await this.anthropic();
+        const response = await anthropic.messages.create({
+            model,
+            max_tokens: 10000,
+            messages: claudeMessages,
+            tools: claudeTools,
+        });
+        // Extract tool calls and add assistant message to generic conversation
+        const toolCalls = response.content.filter(block => block.type === 'tool_use');
+        const textContent = response.content.filter(block => block.type === 'text').map(block => block.text).join('');
+        const llmToolCalls = toolCalls.map(toolCall => ({
+            name: toolCall.name,
+            arguments: toolCall.input,
+            id: toolCall.id,
+        }));
+        // Add assistant message to generic conversation
+        conversation.messages.push({
+            role: 'assistant',
+            content: textContent,
+            toolCalls: llmToolCalls.length > 0 ? llmToolCalls : undefined
+        });
+        return llmToolCalls;
+    }
+    addToolResults(conversation, results) {
+        for (const result of results) {
+            conversation.messages.push({
+                role: 'tool',
+                toolCallId: result.toolCallId,
+                content: result.content,
+                isError: result.isError,
+            });
+        }
+    }
+    checkDoneToolCall(toolCall) {
+        if (toolCall.name === 'done')
+            return toolCall.arguments.result;
+        return null;
+    }
+}

package/lib/loop/loopOpenAI.js

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+const model = 'gpt-4.1';
+export class OpenAIDelegate {
+    _openai;
+    async openai() {
+        if (!this._openai) {
+            const oai = await import('openai');
+            this._openai = new oai.OpenAI();
+        }
+        return this._openai;
+    }
+    createConversation(task, tools, oneShot) {
+        const genericTools = tools.map(tool => ({
+            name: tool.name,
+            description: tool.description || '',
+            inputSchema: tool.inputSchema,
+        }));
+        if (!oneShot) {
+            genericTools.push({
+                name: 'done',
+                description: 'Call this tool when the task is complete.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            });
+        }
+        return {
+            messages: [{
+                    role: 'user',
+                    content: task
+                }],
+            tools: genericTools,
+        };
+    }
+    async makeApiCall(conversation) {
+        // Convert generic messages to OpenAI format
+        const openaiMessages = [];
+        for (const message of conversation.messages) {
+            if (message.role === 'user') {
+                openaiMessages.push({
+                    role: 'user',
+                    content: message.content
+                });
+            }
+            else if (message.role === 'assistant') {
+                const toolCalls = [];
+                if (message.toolCalls) {
+                    for (const toolCall of message.toolCalls) {
+                        toolCalls.push({
+                            id: toolCall.id,
+                            type: 'function',
+                            function: {
+                                name: toolCall.name,
+                                arguments: JSON.stringify(toolCall.arguments)
+                            }
+                        });
+                    }
+                }
+                const assistantMessage = {
+                    role: 'assistant'
+                };
+                if (message.content)
+                    assistantMessage.content = message.content;
+                if (toolCalls.length > 0)
+                    assistantMessage.tool_calls = toolCalls;
+                openaiMessages.push(assistantMessage);
+            }
+            else if (message.role === 'tool') {
+                openaiMessages.push({
+                    role: 'tool',
+                    tool_call_id: message.toolCallId,
+                    content: message.content,
+                });
+            }
+        }
+        // Convert generic tools to OpenAI format
+        const openaiTools = conversation.tools.map(tool => ({
+            type: 'function',
+            function: {
+                name: tool.name,
+                description: tool.description,
+                parameters: tool.inputSchema,
+            },
+        }));
+        const openai = await this.openai();
+        const response = await openai.chat.completions.create({
+            model,
+            messages: openaiMessages,
+            tools: openaiTools,
+            tool_choice: 'auto'
+        });
+        const message = response.choices[0].message;
+        // Extract tool calls and add assistant message to generic conversation
+        const toolCalls = message.tool_calls || [];
+        const genericToolCalls = toolCalls.map(toolCall => {
+            const functionCall = toolCall.function;
+            return {
+                name: functionCall.name,
+                arguments: JSON.parse(functionCall.arguments),
+                id: toolCall.id,
+            };
+        });
+        // Add assistant message to generic conversation
+        conversation.messages.push({
+            role: 'assistant',
+            content: message.content || '',
+            toolCalls: genericToolCalls.length > 0 ? genericToolCalls : undefined
+        });
+        return genericToolCalls;
+    }
+    addToolResults(conversation, results) {
+        for (const result of results) {
+            conversation.messages.push({
+                role: 'tool',
+                toolCallId: result.toolCallId,
+                content: result.content,
+                isError: result.isError,
+            });
+        }
+    }
+    checkDoneToolCall(toolCall) {
+        if (toolCall.name === 'done')
+            return toolCall.arguments.result;
+        return null;
+    }
+}

package/lib/loop/main.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+/* eslint-disable no-console */
+import path from 'path';
+import url from 'url';
+import dotenv from 'dotenv';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { program } from 'commander';
+import { OpenAIDelegate } from './loopOpenAI.js';
+import { ClaudeDelegate } from './loopClaude.js';
+import { runTask } from './loop.js';
+dotenv.config();
+const __filename = url.fileURLToPath(import.meta.url);
+async function run(delegate) {
+    const transport = new StdioClientTransport({
+        command: 'node',
+        args: [
+            path.resolve(__filename, '../../../cli.js'),
+            '--save-session',
+            '--output-dir', path.resolve(__filename, '../../../sessions')
+        ],
+        stderr: 'inherit',
+        env: process.env,
+    });
+    const client = new Client({ name: 'test', version: '1.0.0' });
+    await client.connect(transport);
+    await client.ping();
+    for (const task of tasks) {
+        const messages = await runTask(delegate, client, task);
+        for (const message of messages)
+            console.log(`${message.role}: ${message.content}`);
+    }
+    await client.close();
+}
+const tasks = [
+    'Open https://playwright.dev/',
+];
+program
+    .option('--model <model>', 'model to use')
+    .action(async (options) => {
+    if (options.model === 'claude')
+        await run(new ClaudeDelegate());
+    else
+        await run(new OpenAIDelegate());
+});
+void program.parseAsync(process.argv);