chore: experimental tool provider

Author: ruifigueira

cloudflare/.npmignore

@@ -7,3 +7,4 @@
 
 # Include playwright core and test entry points
 !index.d.ts
+!experimental.d.ts

cloudflare/experimental.d.ts

@@ -0,0 +1,23 @@
+import { Browser, BrowserEndpoint } from '@cloudflare/playwright';
+import { ToolSet } from 'ai';
+import { ToolCapability } from './index.js';
+
+/**
+ * ToolsProvider interface for providing Playwright MCP tools.
+ */
+export interface ToolsProvider {
+  /**
+   * Returns a ToolSet containing all available tools mapped from the context
+   * Each tool includes parameters, description, and execute function
+   */
+  tools(): ToolSet;
+
+  /**
+   * Closes the underlying browser context and cleans up resources
+   */
+  close(): Promise<void>;
+
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+export declare function createToolsProvider(endpoint: BrowserEndpoint | Browser, options?: { vision?: boolean; capabilities?: ToolCapability[] }): Promise<ToolsProvider>;

cloudflare/index.d.ts

@@ -19,7 +19,7 @@ import { env } from 'cloudflare:workers';
 import { McpAgent } from 'agents/mcp';
 import { BrowserEndpoint } from '@cloudflare/playwright';
 
-type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files';
+export type ToolCapability = 'core' | 'tabs' | 'pdf' | 'history' | 'wait' | 'files';
 
 type Options = {
     /**

cloudflare/package-lock.json

@@ -22,6 +22,12 @@
       "import": "./lib/esm/index.js",
       "require": "./lib/cjs/index.js",
       "default": "./lib/esm/index.js"
+    },
+    "./experimental": {
+      "types": "./experimental.d.ts",
+      "import": "./lib/esm/experimental.js",
+      "require": "./lib/cjs/experimental.js",
+      "default": "./lib/esm/experimental.js"
     }
   },
   "dependencies": {
@@ -34,5 +40,8 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250725.0",
     "vite": "^7.0.6"
+  },
+  "peerDependencies": {
+    "ai": "^4.3.19"
   }
 }

cloudflare/package.json

@@ -0,0 +1,84 @@
+import { Browser, BrowserEndpoint, endpointURLString } from '@cloudflare/playwright';
+import type { ToolCapability } from '../../config';
+import { Context } from '../../src/context.js';
+import { snapshotTools, visionTools } from '../../src/tools.js';
+import { FullConfig, resolveConfig } from '../../src/config.js';
+import { BrowserContextFactory, contextFactory } from '../../src/browserContextFactory.js';
+import type { ToolSet } from 'ai';
+import { ToolsProvider } from '../experimental.js';
+
+class ToolsProviderImpl implements ToolsProvider {
+  private context: Context;
+  private _tools: ToolSet;
+
+  constructor(context: Context) {
+    this.context = context;
+  }
+
+  tools(): ToolSet {
+    if (!this._tools) {
+      this._tools = Object.fromEntries(
+          this.context.tools.map(tool => [
+            tool.schema.name,
+            {
+              parameters: tool.schema.inputSchema,
+              description: tool.schema.description,
+              execute: async (args: any) => {
+                return await this.context.run(tool, args);
+              },
+            },
+          ])
+      );
+    }
+    return this._tools;
+  }
+
+  async close() {
+    await this.context.close();
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+}
+
+function isBrowser(browser: BrowserEndpoint | Browser): browser is Browser {
+  return (
+    typeof (browser as Browser).newPage === 'function' &&
+    typeof (browser as Browser).newContext === 'function' &&
+    // Fetcher may match the previous ones
+    typeof (browser as Browser)[Symbol.asyncDispose] === 'function'
+  );
+}
+
+export async function createToolsProvider(endpoint: BrowserEndpoint | Browser, options?: { vision?: boolean, capabilities?: ToolCapability[] }): Promise<ToolsProvider> {
+  const allTools = options?.vision ? visionTools : snapshotTools;
+  const tools = options?.capabilities ? allTools.filter(tool => options.capabilities.includes(tool.capability)) : allTools;
+  let config: FullConfig;
+  let browserContextFactory: BrowserContextFactory;
+
+  if (isBrowser(endpoint)) {
+    config = await resolveConfig({});
+    browserContextFactory = {
+      createContext: async () => {
+        const browserContext = await endpoint.newContext();
+        return { browserContext, close: () => browserContext.close() };
+      },
+    } as BrowserContextFactory;
+  } else {
+    const cdpEndpoint = typeof endpoint === 'string'
+      ? endpoint
+      : endpoint instanceof URL
+        ? endpoint.toString()
+        : endpointURLString(endpoint);
+    config = await resolveConfig({
+      browser: {
+        cdpEndpoint,
+      },
+    });
+    browserContextFactory = contextFactory(config.browser);
+  }
+
+  const context = new Context(tools, config, browserContextFactory);
+  return new ToolsProviderImpl(context);
+}

cloudflare/src/experimental.ts

@@ -9,6 +9,8 @@ import { ToolCapability } from '../../config.js';
 
 import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
 
+export { createToolsProvider as experimental_createToolsProvider } from './experimental.js';
+
 type Options = {
   vision?: boolean;
   capabilities?: ToolCapability[];

cloudflare/src/index.ts

@@ -47,6 +47,7 @@ export default defineConfig({
       name: '@cloudflare/playwright',
       entry: [
         path.resolve(__dirname, './src/index.ts'),
+        path.resolve(__dirname, './src/experimental.ts'),
       ],
     },
     // prevents __defProp, __defNormalProp, __publicField in compiled code