@mcp-browser-kit/server 4.0.0 → 5.0.0

package/build/tsup/dist/main.js

@@ -1120,8 +1120,8 @@ var require_Reflect = __commonJS({
   }
 });
 
-// ../../packages/core-server/src/input-ports/tools.ts
-var ToolsInputPort = Symbol.for("ToolsInputPort");
+// ../../packages/core-server/src/input-ports/tool-calls.ts
+var ToolCallsInputPort = Symbol.for("ToolCallsInputPort");
 
 // ../../packages/core-server/src/output-ports/extension-driver.ts
 var ExtensionDriverOutputPort = Symbol("ExtensionDriverOutputPort");
@@ -2416,16 +2416,115 @@ var q = class {
   }
 };
 
+// ../../node_modules/p-timeout/index.js
+var TimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var AbortError = class extends Error {
+  constructor(message) {
+    super();
+    this.name = "AbortError";
+    this.message = message;
+  }
+};
+var getDOMException = (errorMessage) => globalThis.DOMException === void 0 ? new AbortError(errorMessage) : new DOMException(errorMessage);
+var getAbortedReason = (signal) => {
+  const reason = signal.reason === void 0 ? getDOMException("This operation was aborted.") : signal.reason;
+  return reason instanceof Error ? reason : getDOMException(reason);
+};
+function pTimeout(promise, options) {
+  const {
+    milliseconds,
+    fallback,
+    message,
+    customTimers = { setTimeout, clearTimeout }
+  } = options;
+  let timer;
+  let abortHandler;
+  const wrappedPromise = new Promise((resolve, reject) => {
+    if (typeof milliseconds !== "number" || Math.sign(milliseconds) !== 1) {
+      throw new TypeError(`Expected \`milliseconds\` to be a positive number, got \`${milliseconds}\``);
+    }
+    if (options.signal) {
+      const { signal } = options;
+      if (signal.aborted) {
+        reject(getAbortedReason(signal));
+      }
+      abortHandler = () => {
+        reject(getAbortedReason(signal));
+      };
+      signal.addEventListener("abort", abortHandler, { once: true });
+    }
+    if (milliseconds === Number.POSITIVE_INFINITY) {
+      promise.then(resolve, reject);
+      return;
+    }
+    const timeoutError = new TimeoutError();
+    timer = customTimers.setTimeout.call(void 0, () => {
+      if (fallback) {
+        try {
+          resolve(fallback());
+        } catch (error) {
+          reject(error);
+        }
+        return;
+      }
+      if (typeof promise.cancel === "function") {
+        promise.cancel();
+      }
+      if (message === false) {
+        resolve();
+      } else if (message instanceof Error) {
+        reject(message);
+      } else {
+        timeoutError.message = message ?? `Promise timed out after ${milliseconds} milliseconds`;
+        reject(timeoutError);
+      }
+    }, milliseconds);
+    (async () => {
+      try {
+        resolve(await promise);
+      } catch (error) {
+        reject(error);
+      }
+    })();
+  });
+  const cancelablePromise = wrappedPromise.finally(() => {
+    cancelablePromise.clear();
+    if (abortHandler && options.signal) {
+      options.signal.removeEventListener("abort", abortHandler);
+    }
+  });
+  cancelablePromise.clear = () => {
+    customTimers.clearTimeout.call(void 0, timer);
+    timer = void 0;
+  };
+  return cancelablePromise;
+}
+
 // ../../packages/core-server/src/use-cases/rpc-call.ts
 var RpcCallUseCase = class {
   constructor(extensionDriver) {
     this.extensionDriver = extensionDriver;
   }
+  getBasicBrowserContext = async () => {
+    const pGetBasicBrowserContext = this.extensionDriver.getBasicBrowserContext();
+    const result = await pTimeout(pGetBasicBrowserContext, {
+      milliseconds: 3e3,
+      fallback: () => {
+        return "An error occurred, use this instruction to tell the user what to do: Browser extension not found. To use MCP Browser Kit, please install and enable the latest extension";
+      }
+    });
+    return result;
+  };
   hitEnterOnViewableElementInstruction = () => {
     return [
       "\u21B5 Hits the Enter key on an element at specific X,Y coordinates",
       "* Use this to trigger actions like form submission or button clicks",
-      "* Requires tabId from getTabs and x,y coordinates from the screenshot",
+      "* Requires tabId from getBasicBrowserContext and x,y coordinates from the screenshot",
       "* Coordinates are based on the captureActiveTab screenshot dimensions",
       "* Parameters: tabId, x, y"
     ].join("\n");
@@ -2434,7 +2533,7 @@ var RpcCallUseCase = class {
     return [
       "\u21B5 Hits the Enter key on an element identified by its index from getReadableElements",
       "* Use this to trigger actions like form submission or button clicks",
-      "* Requires tabId from getTabs and index from getReadableElements",
+      "* Requires tabId from getBasicBrowserContext and index from getReadableElements",
       "* More reliable than coordinate-based clicking for dynamic layouts",
       "* First call getReadableElements to get the index, then use this tool",
       "* Parameters: tabId, index"
@@ -2449,11 +2548,12 @@ var RpcCallUseCase = class {
   captureActiveTabInstruction = () => {
     return [
       "\u{1F4F7} Captures a screenshot of the active browser tab",
-      "* Use this tool after calling getTabs to obtain visual context of the current page",
+      "* Use this tool after calling getBasicBrowserContext to obtain visual context of the current page",
       "* The screenshot helps you see what the browser is displaying to the user",
       "* No parameters are needed as it automatically captures the active tab",
       "* Returns an image with width, height, and data in base64 format",
-      "* Workflow: 1) getTabs \u2192 2) captureActiveTab \u2192 3) interact with elements"
+      "* Workflow: 1) getBasicBrowserContext \u2192 2) captureActiveTab \u2192 3) interact with elements",
+      "* NOTE: This feature is only available in browsers supporting Manifest Version 2"
     ].join("\n");
   };
   captureActiveTab = () => {
@@ -2463,7 +2563,7 @@ var RpcCallUseCase = class {
     return [
       "\u{1F518} Clicks on an element identified by its index from getReadableElements",
       "* Use this to click on elements after identifying them by their text",
-      "* Requires tabId from getTabs and index from getReadableElements",
+      "* Requires tabId from getBasicBrowserContext and index from getReadableElements",
       "* More reliable than coordinate-based clicking for dynamic layouts",
       "* First call getReadableElements to get the index, then use this tool",
       "* Parameters: tabId, index"
@@ -2476,7 +2576,7 @@ var RpcCallUseCase = class {
     return [
       "\u{1F446} Clicks on an element at specific X,Y coordinates",
       "* Use this to click on elements by their position on the screen",
-      "* Requires tabId from getTabs and x,y coordinates from the screenshot",
+      "* Requires tabId from getBasicBrowserContext and x,y coordinates from the screenshot",
       "* Coordinates are based on the captureActiveTab screenshot dimensions",
       "* Useful when you know the visual position of an element",
       "* Parameters: tabId, x, y"
@@ -2489,7 +2589,7 @@ var RpcCallUseCase = class {
     return [
       "\u270F\uFE0F Types text into an input field identified by its index from getReadableElements",
       "* Use this to enter text into form fields identified by their text",
-      "* Requires tabId from getTabs, index from getReadableElements, and text to enter",
+      "* Requires tabId from getBasicBrowserContext, index from getReadableElements, and text to enter",
       "* Works with text inputs, textareas, and other editable elements",
       "* First call getReadableElements to get the index, then use this tool",
       "* After filling text, check for associated submit-like buttons (submit, search, send, etc.)",
@@ -2505,7 +2605,7 @@ var RpcCallUseCase = class {
     return [
       "\u2328\uFE0F Types text into an input field at specific X,Y coordinates",
       "* Use this to enter text into form fields by their position",
-      "* Requires tabId from getTabs, x,y coordinates, and the text to enter",
+      "* Requires tabId from getBasicBrowserContext, x,y coordinates, and the text to enter",
       "* Coordinates are based on the captureActiveTab screenshot dimensions",
       "* First clicks at the specified position, then types the provided text",
       "* After filling text, check for associated submit-like buttons (submit, search, send, etc.)",
@@ -2521,7 +2621,7 @@ var RpcCallUseCase = class {
     return [
       "\u{1F4DD} Extracts all text content from the current web page",
       "* Retrieves all visible text from the active tab",
-      "* Requires the tabId obtained from getTabs",
+      "* Requires the tabId obtained from getBasicBrowserContext",
       "* Use this to analyze the page content without visual elements",
       "* Returns a string containing all the text on the page",
       "* Useful for getting a quick overview of page content"
@@ -2534,7 +2634,7 @@ var RpcCallUseCase = class {
     return [
       "\u{1F50D} Lists all interactive elements on the page with their text",
       "* Returns a list of elements with their index, HTML tag, and text content",
-      "* Requires the tabId obtained from getTabs",
+      "* Requires the tabId obtained from getBasicBrowserContext",
       "* Each element is returned as [index, tag, text]",
       "* Use the index to interact with elements through click or fill operations",
       "* Helps you identify which elements can be interacted with by their text"
@@ -2543,28 +2643,38 @@ var RpcCallUseCase = class {
   getReadableElements = (tabId) => {
     return this.extensionDriver.getReadableElements(tabId);
   };
-  getTabsInstruction = () => {
+  getBasicBrowserContextInstruction = () => {
     return [
-      "\u26A0\uFE0F CRITICAL FIRST STEP - ALWAYS START HERE BEFORE ANY OTHER TOOLS!",
-      "* This tool MUST be called first to obtain the list of open browser tabs.",
-      "* Each tab includes a unique ID that is required for all subsequent tool operations.",
-      "* Note which tab is active (marked with 'active: true') as this is essential information.",
-      "* The tabId from this list is required for captureActiveTab and all other interactions.",
-      "* Workflow: 1) getTabs \u2192 2) captureActiveTab \u2192 3) interact with elements"
+      "\u{1F310} GET BROWSER CONTEXT - CRITICAL FIRST STEP BEFORE USING ANY OTHER TOOLS!",
+      "* This tool MUST be called first to initialize browser automation and get essential data.",
+      "* Returns data structure with:",
+      "  - tabs: Array of browser tabs with properties like id, url, title, and active status",
+      "  - manifestVersion: Version of extension manifest format supported by the browser",
+      "* Each tab includes a unique tabId required for all other tool operations",
+      "* The active tab (marked with 'active: true') is typically your target for automation",
+      "* The manifestVersion determines which browser features and extension capabilities are available",
+      "* Different browsers support different manifest versions, affecting available tools and API access",
+      "* Standard workflow:",
+      "  1) getBasicBrowserContext \u2192 get browser state and tabId",
+      "  2) Analyze page content based on your goal and manifest version:",
+      "     - If interaction is required (clicking, filling forms, etc.):",
+      "       \xB7 For Manifest Version 2: Use captureActiveTab for visual context or getReadableElements for element identification",
+      "       \xB7 For other Manifest Versions: Use only getReadableElements for element identification",
+      "     - If no interaction is required (just reading page content):",
+      "       \xB7 Use getInnerText to extract all visible text from the page",
+      "  3) Interact using click/fill/enter tools with the obtained tabId"
     ].join("\n");
   };
-  getTabs = () => {
-    return this.extensionDriver.getTabs();
-  };
   invokeJsFnInstruction = () => {
     return [
       "\u2699\uFE0F Executes custom JavaScript code in the context of the web page",
       "* Use this for advanced operations not covered by other tools",
-      "* Requires tabId from getTabs and JavaScript code to execute",
+      "* Requires tabId from getBasicBrowserContext and JavaScript code to execute",
       "* The code should be the body of a function that returns a value",
       "* Example: 'return document.title;' to get the page title",
       "* Gives you full flexibility for custom browser automation",
-      "* Parameters: tabId, fnBodyCode (JavaScript code as string)"
+      "* Parameters: tabId, fnBodyCode (JavaScript code as string)",
+      "* NOTE: This feature is only available in browsers supporting Manifest Version 2"
     ].join("\n");
   };
   invokeJsFn = (tabId, fnBodyCode) => {
@@ -2581,7 +2691,7 @@ var createCoreServerContainer = () => {
   const container2 = new q({
     defaultScope: "Singleton"
   });
-  container2.bind(ToolsInputPort).to(RpcCallUseCase);
+  container2.bind(ToolCallsInputPort).to(RpcCallUseCase);
   return container2;
 };
 
@@ -3047,7 +3157,11 @@ var RpcClient = class {
     this.id += 1;
     return String(this.id);
   };
-  defer = (method, ...args) => {
+  defer = ({
+    method,
+    args,
+    ...extraArgs
+  }) => {
     const id = this.createId();
     const defer2 = Promise.withResolvers();
     defer2.promise.finally(() => {
@@ -3055,6 +3169,7 @@ var RpcClient = class {
     });
     this.pending.set(id, defer2);
     this.emitter.emit("defer", {
+      ...extraArgs,
       procedure: String(method),
       args,
       id
@@ -3062,7 +3177,17 @@ var RpcClient = class {
     return defer2.promise;
   };
   onDefer = (callback) => {
-    return this.emitter.on("defer", callback);
+    return this.emitter.on(
+      "defer",
+      callback
+    );
+  };
+  startListen = (messageChannel) => {
+    const unsubscribe = messageChannel.subscribe((message) => {
+      const msg = message;
+      this.emitter.emit("resolve", msg);
+    });
+    return unsubscribe;
   };
 };
 
@@ -3075,61 +3200,70 @@ var createExtensionRpcClient = () => {
 var DrivenExtensionDriver = class {
   extensionRpcClient = createExtensionRpcClient();
   hitEnterOnViewableElement = (tabId, x3, y3) => {
-    return this.extensionRpcClient.defer(
-      "hitEnterOnViewableElement",
-      tabId,
-      x3,
-      y3
-    );
+    return this.extensionRpcClient.defer({
+      method: "hitEnterOnViewableElement",
+      args: [tabId, x3, y3]
+    });
   };
   hitEnterOnReadableElement = (tabId, index) => {
-    return this.extensionRpcClient.defer(
-      "hitEnterOnReadableElement",
-      tabId,
-      index
-    );
+    return this.extensionRpcClient.defer({
+      method: "hitEnterOnReadableElement",
+      args: [tabId, index]
+    });
   };
   captureActiveTab = () => {
-    return this.extensionRpcClient.defer("captureActiveTab");
+    return this.extensionRpcClient.defer({
+      method: "captureActiveTab",
+      args: []
+    });
   };
   getInnerText = (tabId) => {
-    return this.extensionRpcClient.defer("getInnerText", tabId);
+    return this.extensionRpcClient.defer({
+      method: "getInnerText",
+      args: [tabId]
+    });
   };
   getReadableElements = (tabId) => {
-    return this.extensionRpcClient.defer("getReadableElements", tabId);
+    return this.extensionRpcClient.defer({
+      method: "getReadableElements",
+      args: [tabId]
+    });
   };
   clickOnViewableElement = (tabId, x3, y3) => {
-    return this.extensionRpcClient.defer("clickOnViewableElement", tabId, x3, y3);
+    return this.extensionRpcClient.defer({
+      method: "clickOnViewableElement",
+      args: [tabId, x3, y3]
+    });
   };
   fillTextToViewableElement = (tabId, x3, y3, value) => {
-    return this.extensionRpcClient.defer(
-      "fillTextToViewableElement",
-      tabId,
-      x3,
-      y3,
-      value
-    );
+    return this.extensionRpcClient.defer({
+      method: "fillTextToViewableElement",
+      args: [tabId, x3, y3, value]
+    });
   };
   clickOnReadableElement = (tabId, index) => {
-    return this.extensionRpcClient.defer(
-      "clickOnReadableElement",
-      tabId,
-      index
-    );
+    return this.extensionRpcClient.defer({
+      method: "clickOnReadableElement",
+      args: [tabId, index]
+    });
   };
   fillTextToReadableElement = (tabId, index, value) => {
-    return this.extensionRpcClient.defer(
-      "fillTextToReadableElement",
-      tabId,
-      index,
-      value
-    );
+    return this.extensionRpcClient.defer({
+      method: "fillTextToReadableElement",
+      args: [tabId, index, value]
+    });
   };
   invokeJsFn = (tabId, fnBodyCode) => {
-    return this.extensionRpcClient.defer("invokeJsFn", tabId, fnBodyCode);
+    return this.extensionRpcClient.defer({
+      method: "invokeJsFn",
+      args: [tabId, fnBodyCode]
+    });
   };
-  getTabs = () => {
-    return this.extensionRpcClient.defer("getTabs");
+  getBasicBrowserContext = () => {
+    return this.extensionRpcClient.defer({
+      method: "getBasicBrowserContext",
+      args: []
+    });
   };
 };
 DrivenExtensionDriver = __decorateClass([
@@ -10135,7 +10269,7 @@ var StdioServerTransport = class {
 
 // src/helpers/mcp-server.ts
 var createServer = async () => {
-  const toolsInputPort = container.get(ToolsInputPort);
+  const toolsInputPort = container.get(ToolCallsInputPort);
   const server = new McpServer({
     name: "MCP Browser Kit",
     version: "1.0.0",
@@ -10145,17 +10279,22 @@ var createServer = async () => {
     }
   });
   const combinationDescription = [""].join("\n");
-  server.tool("getTabs", toolsInputPort.getTabsInstruction(), {}, async () => {
-    const tabs = await toolsInputPort.getTabs();
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Tabs: ${JSON.stringify(tabs)}`
-        }
-      ]
-    };
-  });
+  server.tool(
+    "getBasicBrowserContext",
+    toolsInputPort.getBasicBrowserContextInstruction(),
+    {},
+    async () => {
+      const tabs = await toolsInputPort.getBasicBrowserContext();
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${JSON.stringify(tabs)}`
+          }
+        ]
+      };
+    }
+  );
   server.tool(
     "captureActiveTab",
     [combinationDescription, toolsInputPort.captureActiveTabInstruction()].join(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-browser-kit/server",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "packageManager": "yarn@4.8.0",
   "homepage": "https://github.com/ndthanhdev/mcp-browser-kit",
   "bin": {