fastbrowser_cli 1.0.13 → 1.0.16

package/src/fastbrowser_mcp/fastbrowser_types.ts

@@ -0,0 +1,4 @@
+/**
+ * Defines the types used in the FastBrowser MCP implementation.
+ */
+export type FastBrowserMcpTarget = 'chrome_devtools' | 'playwright';

package/src/fastbrowser_mcp/libs/{mcp_client.ts → mcp_client_TOREMOVE.ts}

@@ -4,6 +4,7 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { CallToolResult, Prompt, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
+import { FastBrowserMcpTarget } from "../fastbrowser_types.js";
 
 export type StdioConfig = {
 	type: "stdio";
@@ -23,6 +24,7 @@ export type McpTransportConfig = StdioConfig | HttpConfig;
 export interface McpClientOptions {
 	name: string;
 	version: string;
+	mcpTarget: FastBrowserMcpTarget;
 	transport: McpTransportConfig;
 }
 
@@ -32,16 +34,26 @@ export interface McpClientOptions {
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
 
-export class McpClient {
+// TODO remove this function - it seems to do vastly nothing - more confusing that helpful
+// - i use the McpServer directly, and i got a wrapper for the client... discrepancy is confusing
+export class McpMyClient {
 	private readonly client: Client;
 	private transport?: Transport;
+	private mcpTarget: FastBrowserMcpTarget;
 	private connected = false;
 
 	constructor(private readonly options: McpClientOptions) {
+		this.mcpTarget = options.mcpTarget;
 		this.client = new Client({
 			name: options.name,
 			version: options.version,
 		});
+
+		debugger
+	}
+
+	async getMcpTarget(): Promise<FastBrowserMcpTarget> {
+		return this.mcpTarget;
 	}
 
 	async connect(): Promise<void> {

package/src/fastbrowser_mcp/libs/mcp_my_client.ts

@@ -0,0 +1,128 @@
+// node import
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { CallToolResult, Prompt, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
+import { FastBrowserMcpTarget } from "../fastbrowser_types.js";
+
+export type StdioConfig = {
+	type: "stdio";
+	command: string;
+	args?: string[];
+	env?: Record<string, string>;
+};
+
+export type HttpConfig = {
+	type: "http";
+	url: string;
+	headers?: Record<string, string>;
+};
+
+export type McpTransportConfig = StdioConfig | HttpConfig;
+
+export interface McpClientOptions {
+	name: string;
+	version: string;
+	mcpTarget: FastBrowserMcpTarget;
+	transport: McpTransportConfig;
+}
+
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//	
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+// TODO remove this function - it seems to do vastly nothing - more confusing that helpful
+// - i use the McpServer directly, and i got a wrapper for the client... discrepancy is confusing
+export class McpMyClient {
+	private readonly client: Client;
+	private transport?: Transport;
+	private mcpTarget: FastBrowserMcpTarget;
+	private connected = false;
+
+	constructor(private readonly options: McpClientOptions) {
+		this.mcpTarget = options.mcpTarget;
+		this.client = new Client({
+			name: options.name,
+			version: options.version,
+		});
+		// debugger
+	}
+
+	async getMcpTarget(): Promise<FastBrowserMcpTarget> {
+		return this.mcpTarget;
+	}
+
+	async connect(): Promise<void> {
+		if (this.connected) return;
+
+		this.transport = this.createTransport(this.options.transport);
+		await this.client.connect(this.transport);
+		this.connected = true;
+	}
+
+	async close(): Promise<void> {
+		if (!this.connected) return;
+		await this.client.close();
+		this.connected = false;
+	}
+
+	async listTools(): Promise<Tool[]> {
+		this.assertConnected();
+		const { tools } = await this.client.listTools();
+		return tools;
+	}
+
+	async callTool(
+		name: string,
+		args: Record<string, unknown> = {},
+	): Promise<CallToolResult> {
+		this.assertConnected();
+		return this.client.callTool({ name, arguments: args }) as Promise<CallToolResult>;
+	}
+
+	async listResources(): Promise<Resource[]> {
+		this.assertConnected();
+		const { resources } = await this.client.listResources();
+		return resources;
+	}
+
+	async readResource(uri: string): Promise<unknown> {
+		this.assertConnected();
+		return this.client.readResource({ uri });
+	}
+
+	async listPrompts(): Promise<Prompt[]> {
+		this.assertConnected();
+		const { prompts } = await this.client.listPrompts();
+		return prompts;
+	}
+
+	async getPrompt(name: string, args: Record<string, string> = {}) {
+		this.assertConnected();
+		return this.client.getPrompt({ name, arguments: args });
+	}
+
+	private createTransport(config: McpTransportConfig): Transport {
+		switch (config.type) {
+			case "stdio":
+				return new StdioClientTransport({
+					command: config.command,
+					args: config.args ?? [],
+					env: config.env,
+				});
+			case "http":
+				return new StreamableHTTPClientTransport(new URL(config.url), {
+					requestInit: { headers: config.headers },
+				});
+		}
+	}
+
+	private assertConnected(): void {
+		if (!this.connected) {
+			throw new Error("McpClient is not connected. Call connect() first.");
+		}
+	}
+}

package/src/fastbrowser_mcp/libs/mcp_proxy.ts

@@ -7,7 +7,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { convertJsonSchemaToZod } from 'zod-from-json-schema';
 
 // local imports
-import { McpClient } from "./mcp_client.js";
+import { McpMyClient } from "./mcp_my_client.js";
 
 export class McpProxy {
 	private _mcpServer: McpServer;
@@ -31,7 +31,7 @@ export class McpProxy {
 		return this._mcpServer;
 	}
 
-	async proxyToolCall(mcpClient: McpClient, toolName: string) {
+	async proxyToolCall(mcpClient: McpMyClient, toolName: string) {
 		const mcpClientTools = await mcpClient.listTools()
 		const mcpClientTool = mcpClientTools.find((tool) => tool.name === toolName);
 		Assert.ok(mcpClientTool !== undefined, `Tool ${toolName} not found in mcp client tools`)

package/src/fastbrowser_mcp/libs/mcp_target_helper.ts

@@ -0,0 +1,164 @@
+import { ta } from "zod/locales";
+import { FastBrowserMcpTarget } from "../fastbrowser_types.js";
+
+export type TargetToolConfig = {
+	toolName: string;
+	toolArgs: Record<string, unknown>;
+};
+
+export class McpTargetHelper {
+	static EXTERNAL_TOOL_NAME = {
+		listPages: "list_pages",
+		newPage: "new_page",
+		closePage: "close_page",
+		takeSnapshot: "take_snapshot",
+		navigatePage: "navigate_page",
+		querySelectorsAll: "querySelectorsAll",
+		querySelectors: "querySelectors",
+		pressKeys: "pressKeys",
+		click: "click",
+		fillForm: "fill_form",
+		getCurrentDateTime: "get_current_datetime",
+	}
+
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+	//	For configuration
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+
+	static mcpArgs(mcpTarget: FastBrowserMcpTarget): { command: string; args: string[] } {
+		let mcpCommand: string;
+		let mcpArgs: string[];
+		if (mcpTarget === 'chrome_devtools') {
+			mcpCommand = "npx";
+			mcpArgs = ["chrome-devtools-mcp@latest", "--autoconnect", "--no-performance-crux", "--no-usage-statistics"];
+		} else if (mcpTarget === 'playwright') {
+			// npx @playwright/mcp@latest --cdp-endpoint=chrome
+			// npx @playwright/mcp@latest --cdp-endpoint=http://localhost:9222
+			// npx @playwright/mcp@latest --extension
+			// 
+			// https://playwright.dev/mcp/configuration/browser-extension#connect-via-browser-extension
+			// https://github.com/microsoft/playwright/tree/main/packages/extension
+			mcpCommand = "npx";
+			mcpArgs = ["@playwright/mcp", "--extension"];
+		} else {
+			throw new Error(`Unsupported MCP type: ${mcpTarget}`);
+		}
+
+		return { command: mcpCommand, args: mcpArgs };
+	}
+
+	static async toolsToProxy(mcpTarget: FastBrowserMcpTarget): Promise<string[]> {
+		const toolsToProxys: string[] = []
+		if (mcpTarget === 'chrome_devtools') {
+			toolsToProxys.push(...[
+				// 'list_pages',
+				// 'new_page',
+				// 'close_page',
+				// 'navigate_page',
+				// 'take_snapshot',
+			])
+		} else if (mcpTarget === 'playwright') {
+			toolsToProxys.push(...[
+				// 'browser_tabs',
+				// 'browser_navigate',
+				// 'browser_snapshot',
+			])
+		} else {
+			throw new Error(`Unsupported MCP type: ${mcpTarget}`);
+		}
+		return toolsToProxys;
+	}
+
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+	//	For each target tool
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+
+
+	static async targetToolListPages(mcpTarget: FastBrowserMcpTarget): Promise<TargetToolConfig> {
+		if (mcpTarget === 'chrome_devtools') {
+			return {
+				toolName: 'list_pages', toolArgs: {
+					// No arguments needed for listing pages in Chrome DevTools MCP
+				}
+			};
+		} else if (mcpTarget === 'playwright') {
+			return {
+				toolName: 'browser_tabs', toolArgs: {
+					action: 'list',
+				}
+			};
+		} else {
+			throw new Error(`Unsupported MCP target: ${mcpTarget}`);
+		}
+	}
+
+	static async targetToolNavigatePage(mcpTarget: FastBrowserMcpTarget, url: string): Promise<TargetToolConfig> {
+		if (mcpTarget === 'chrome_devtools') {
+			return {
+				toolName: 'navigate_page', toolArgs: {
+					url
+				}
+			};
+		} else if (mcpTarget === 'playwright') {
+			return {
+				toolName: 'browser_navigate', toolArgs: {
+					url,
+				}
+			};
+		} else {
+			throw new Error(`Unsupported MCP target: ${mcpTarget}`);
+		}
+	}
+
+	static async targetToolTakeSnapshot(mcpTarget: FastBrowserMcpTarget): Promise<TargetToolConfig> {
+		if (mcpTarget === 'chrome_devtools') {
+			return { toolName: 'take_snapshot', toolArgs: {} };
+		} else if (mcpTarget === 'playwright') {
+			return { toolName: 'browser_snapshot', toolArgs: {} };
+		} else {
+			throw new Error(`Unsupported MCP target: ${mcpTarget}`);
+		}
+	}
+
+	static async targetToolPressKey(mcpTarget: FastBrowserMcpTarget, key: string): Promise<TargetToolConfig> {
+		if (mcpTarget === 'chrome_devtools') {
+			return {
+				toolName: 'press_key', toolArgs: {
+					key: key,
+				}
+			};
+		} else if (mcpTarget === 'playwright') {
+			return {
+				toolName: 'browser_press_key', toolArgs: {
+					key: key,
+				}
+			};
+		} else {
+			throw new Error(`Unsupported MCP target: ${mcpTarget}`);
+		}
+	}
+
+	static async targetToolClick(mcpTarget: FastBrowserMcpTarget, uid: string): Promise<TargetToolConfig> {
+		if (mcpTarget === 'chrome_devtools') {
+			return { toolName: 'click', toolArgs: { uid } };
+		} else if (mcpTarget === 'playwright') {
+			return { toolName: 'browser_click', toolArgs: { ref: uid } };
+		} else {
+			throw new Error(`Unsupported MCP target: ${mcpTarget}`);
+		}
+	}
+
+	static async targetToolFillForm(mcpTarget: FastBrowserMcpTarget, elements: { uid: string; value: string }[]): Promise<TargetToolConfig> {
+		if (mcpTarget === 'chrome_devtools') {
+			return { toolName: 'fill_form', toolArgs: { elements } };
+		} else if (mcpTarget === 'playwright') {
+			throw new Error(`Fill form tool is not supported for Playwright MCP target yet`);
+		} else {
+			throw new Error(`Unsupported MCP target: ${mcpTarget}`);
+		}
+	}
+}

package/src/fastbrowser_mcp/libs/playwright_a11y_helper.ts

@@ -0,0 +1,249 @@
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+//	Convert Playwright's get-text-snapshot format to chrome-devtools-mcp's
+//	take_snapshot body format, so that the rest of the pipeline (A11yParse +
+//	selector engine) can be reused unchanged.
+///////////////////////////////////////////////////////////////////////////////
+///////////////////////////////////////////////////////////////////////////////
+
+type Bracket =
+	| { kind: 'attr'; key: string; value: string }
+	| { kind: 'flag'; name: string };
+
+type ParsedLine =
+	| { kind: 'parent_attr'; key: string; value: string }
+	| { kind: 'static_text'; text: string }
+	| {
+		kind: 'node';
+		role: string;
+		name?: string;
+		uid?: string;
+		attrs: Array<[string, string]>;
+		flags: string[];
+		value?: string;
+	};
+
+type EmittedNode = {
+	indent: number;
+	uid: string;
+	role: string;
+	name?: string;
+	attrs: Array<[string, string]>;
+	flags: string[];
+};
+
+export class PlaywrightA11yConverter {
+	/**
+	 * Convert Playwright's `get-text-snapshot` output to the body of chrome-devtools-mcp's `take_snapshot`.
+	 *
+	 * Playwright emits a YAML-like tree with `[ref=eN]` markers, e.g.
+	 * ```
+	 * - link "Welcome" [ref=e7] [cursor=pointer]:
+	 *   - /url: /fr
+	 *   - img "Welcome" [ref=e8]
+	 * ```
+	 *
+	 * chrome-devtools-mcp emits one node per line with `uid=...`, e.g.
+	 * ```
+	 * uid=e7 link "Welcome" url="/fr"
+	 *   uid=e8 image "Welcome"
+	 * ```
+	 *
+	 * The output omits the `## Latest page snapshot` metadata line, so it can be passed directly
+	 * to `A11yParse.A11yTree.parse()`.
+	 */
+	static convertToChromeDevtools(playwrightText: string): string {
+		const lines = playwrightText.split('\n');
+		const stack: EmittedNode[] = [];
+		const allNodes: EmittedNode[] = [];
+		let synthCounter = 0;
+		const synth = () => `s${++synthCounter}`;
+
+		for (const rawLine of lines) {
+			if (rawLine.trim().length === 0) continue;
+
+			const indentMatch = /^( *)/.exec(rawLine);
+			const leadingSpaces = indentMatch !== null ? indentMatch[1].length : 0;
+			const indent = Math.floor(leadingSpaces / 2);
+
+			const trimmed = rawLine.slice(leadingSpaces);
+			if (!trimmed.startsWith('- ')) continue;
+			const body = trimmed.slice(2);
+
+			while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+				stack.pop();
+			}
+			const parent = stack[stack.length - 1] as EmittedNode | undefined;
+
+			const parsed = PlaywrightA11yConverter._parseLine(body);
+
+			if (parsed.kind === 'parent_attr') {
+				if (parent !== undefined) {
+					parent.attrs.push([parsed.key, parsed.value]);
+				}
+				continue;
+			}
+
+			if (parsed.kind === 'static_text') {
+				const node: EmittedNode = {
+					indent,
+					uid: synth(),
+					role: 'StaticText',
+					name: parsed.text,
+					attrs: [],
+					flags: [],
+				};
+				allNodes.push(node);
+				stack.push(node);
+				continue;
+			}
+
+			const uid = parsed.uid !== undefined ? parsed.uid : synth();
+			const attrs: Array<[string, string]> = [...parsed.attrs];
+			if (parsed.value !== undefined) {
+				attrs.push(['value', parsed.value]);
+			}
+			const node: EmittedNode = {
+				indent,
+				uid,
+				role: parsed.role,
+				name: parsed.name,
+				attrs,
+				flags: parsed.flags,
+			};
+			allNodes.push(node);
+			stack.push(node);
+		}
+
+		return allNodes.map((node) => PlaywrightA11yConverter._stringifyNode(node)).join('\n');
+	}
+
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+	//	Internal helpers
+	///////////////////////////////////////////////////////////////////////////////
+	///////////////////////////////////////////////////////////////////////////////
+
+	private static _parseLine(body: string): ParsedLine {
+		if (body.startsWith('/url:')) {
+			return { kind: 'parent_attr', key: 'url', value: body.slice('/url:'.length).trim() };
+		}
+		if (body.startsWith('/placeholder:')) {
+			return { kind: 'parent_attr', key: 'placeholder', value: body.slice('/placeholder:'.length).trim() };
+		}
+		if (body.startsWith('text:')) {
+			const text = PlaywrightA11yConverter._unquoteIfQuoted(body.slice('text:'.length).trim());
+			return { kind: 'static_text', text };
+		}
+
+		let i = 0;
+		const roleMatch = /^(\w+)/.exec(body);
+		if (roleMatch === null) {
+			return { kind: 'node', role: 'unknown', attrs: [], flags: [] };
+		}
+		const role = roleMatch[1];
+		i = role.length;
+
+		const skipSpaces = (): void => {
+			while (i < body.length && body[i] === ' ') i++;
+		};
+
+		skipSpaces();
+
+		let name: string | undefined;
+		if (body[i] === '"') {
+			const parsed = PlaywrightA11yConverter._readQuotedString(body, i);
+			name = parsed.value;
+			i = parsed.next;
+		}
+
+		const brackets: Bracket[] = [];
+		skipSpaces();
+		while (body[i] === '[') {
+			const closeIdx = body.indexOf(']', i);
+			if (closeIdx === -1) break;
+			const content = body.slice(i + 1, closeIdx);
+			const eqIdx = content.indexOf('=');
+			if (eqIdx >= 0) {
+				brackets.push({
+					kind: 'attr',
+					key: content.slice(0, eqIdx),
+					value: content.slice(eqIdx + 1),
+				});
+			} else {
+				brackets.push({ kind: 'flag', name: content });
+			}
+			i = closeIdx + 1;
+			skipSpaces();
+		}
+
+		let value: string | undefined;
+		if (body[i] === ':') {
+			i++;
+			const rest = body.slice(i).trim();
+			if (rest.length > 0) {
+				value = PlaywrightA11yConverter._unquoteIfQuoted(rest);
+			}
+		}
+
+		let uid: string | undefined;
+		const attrs: Array<[string, string]> = [];
+		const flags: string[] = [];
+		for (const b of brackets) {
+			if (b.kind === 'attr') {
+				if (b.key === 'ref') {
+					uid = b.value;
+				} else if (b.key === 'cursor') {
+					// CSS cursor — not a meaningful a11y attribute
+				} else {
+					attrs.push([b.key, b.value]);
+				}
+			} else {
+				flags.push(b.name);
+			}
+		}
+
+		return { kind: 'node', role, name, uid, attrs, flags, value };
+	}
+
+	private static _readQuotedString(input: string, start: number): { value: string; next: number } {
+		let i = start + 1;
+		let result = '';
+		while (i < input.length) {
+			const ch = input[i];
+			if (ch === '\\' && i + 1 < input.length) {
+				result += input[i + 1];
+				i += 2;
+				continue;
+			}
+			if (ch === '"') {
+				return { value: result, next: i + 1 };
+			}
+			result += ch;
+			i++;
+		}
+		return { value: result, next: i };
+	}
+
+	private static _unquoteIfQuoted(s: string): string {
+		if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+			const inner = s.slice(1, -1);
+			return inner.replace(/\\(.)/g, '$1');
+		}
+		return s;
+	}
+
+	private static _stringifyNode(node: EmittedNode): string {
+		const pad = '  '.repeat(node.indent);
+		const name = node.name !== undefined ? ` "${PlaywrightA11yConverter._escapeQuotes(node.name)}"` : '';
+		const parts: string[] = [];
+		for (const flag of node.flags) parts.push(flag);
+		for (const [k, v] of node.attrs) parts.push(`${k}="${PlaywrightA11yConverter._escapeQuotes(v)}"`);
+		const tail = parts.length > 0 ? ' ' + parts.join(' ') : '';
+		return `${pad}uid=${node.uid} ${node.role}${name}${tail}`;
+	}
+
+	private static _escapeQuotes(s: string): string {
+		return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+	}
+}