camel-ai 0.2.23a0__py3-none-any.whl → 0.2.24__py3-none-any.whl

camel/toolkits/mcp_toolkit.py

@@ -0,0 +1,251 @@
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+# 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.
+# ========= Copyright 2023-2024 @ CAMEL-AI.org. All Rights Reserved. =========
+import inspect
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Set,
+    Union,
+)
+from urllib.parse import urlparse
+
+if TYPE_CHECKING:
+    from mcp import ListToolsResult, Tool
+
+from camel.toolkits import BaseToolkit, FunctionTool
+
+
+class MCPToolkit(BaseToolkit):
+    r"""MCPToolkit provides an abstraction layer to interact with external
+    tools using the Model Context Protocol (MCP). It supports two modes of
+    connection:
+
+    1. stdio mode: Connects via standard input/output streams for local
+       command-line interactions.
+
+    2. SSE mode (HTTP Server-Sent Events): Connects via HTTP for persistent,
+       event-based interactions.
+
+    Attributes:
+        command_or_url (str): URL for SSE mode or command executable for stdio
+            mode. (default: :obj:`'None'`)
+        args (List[str]): List of command-line arguments if stdio mode is used.
+            (default: :obj:`'None'`)
+        env (Dict[str, str]): Environment variables for the stdio mode command.
+            (default: :obj:`'None'`)
+        timeout (Optional[float]): Connection timeout. (default: :obj:`'None'`)
+    """
+
+    def __init__(
+        self,
+        command_or_url: str,
+        args: Optional[List[str]] = None,
+        env: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ):
+        from mcp import Tool
+        from mcp.client.session import ClientSession
+
+        super().__init__(timeout=timeout)
+
+        self.command_or_url = command_or_url
+        self.args = args or []
+        self.env = env or {}
+
+        self._mcp_tools: List[Tool] = []
+        self._session: Optional['ClientSession'] = None
+        self._exit_stack = AsyncExitStack()
+        self._is_connected = False
+
+    @asynccontextmanager
+    async def connection(self):
+        r"""Async context manager for establishing and managing the connection
+        with the MCP server. Automatically selects SSE or stdio mode based
+        on the provided `command_or_url`.
+
+        Yields:
+            MCPToolkit: Instance with active connection ready for tool
+                interaction.
+        """
+        from mcp.client.session import ClientSession
+        from mcp.client.sse import sse_client
+        from mcp.client.stdio import StdioServerParameters, stdio_client
+
+        try:
+            if urlparse(self.command_or_url).scheme in ("http", "https"):
+                (
+                    read_stream,
+                    write_stream,
+                ) = await self._exit_stack.enter_async_context(
+                    sse_client(self.command_or_url)
+                )
+            else:
+                server_parameters = StdioServerParameters(
+                    command=self.command_or_url, args=self.args, env=self.env
+                )
+                (
+                    read_stream,
+                    write_stream,
+                ) = await self._exit_stack.enter_async_context(
+                    stdio_client(server_parameters)
+                )
+
+            self._session = await self._exit_stack.enter_async_context(
+                ClientSession(read_stream, write_stream)
+            )
+            await self._session.initialize()
+            list_tools_result = await self.list_mcp_tools()
+            self._mcp_tools = list_tools_result.tools
+            self._is_connected = True
+            yield self
+
+        finally:
+            self._is_connected = False
+            await self._exit_stack.aclose()
+            self._session = None
+
+    async def list_mcp_tools(self) -> Union[str, "ListToolsResult"]:
+        r"""Retrieves the list of available tools from the connected MCP
+        server.
+
+        Returns:
+            ListToolsResult: Result containing available MCP tools.
+        """
+        if not self._session:
+            return "MCP Client is not connected. Call `connection()` first."
+        try:
+            return await self._session.list_tools()
+        except Exception as e:
+            return f"Failed to list MCP tools: {e!s}"
+
+    def generate_function_from_mcp_tool(self, mcp_tool: "Tool") -> Callable:
+        r"""Dynamically generates a Python callable function corresponding to
+        a given MCP tool.
+
+        Args:
+            mcp_tool (Tool): The MCP tool definition received from the MCP
+                server.
+
+        Returns:
+            Callable: A dynamically created async Python function that wraps
+                the MCP tool.
+        """
+        func_name = mcp_tool.name
+        func_desc = mcp_tool.description or "No description provided."
+        parameters_schema = mcp_tool.inputSchema.get("properties", {})
+        required_params = mcp_tool.inputSchema.get("required", [])
+
+        type_map = {
+            "string": str,
+            "integer": int,
+            "number": float,
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+        }
+        annotations = {}  # used to type hints
+        defaults: Dict[str, Any] = {}  # store default values
+
+        func_params = []
+        for param_name, param_schema in parameters_schema.items():
+            param_type = param_schema.get("type", "Any")
+            param_type = type_map.get(param_type, Any)
+
+            annotations[param_name] = param_type
+            if param_name not in required_params:
+                defaults[param_name] = None
+
+            func_params.append(param_name)
+
+        async def dynamic_function(**kwargs):
+            r"""Auto-generated function for MCP Tool interaction.
+
+            Args:
+                kwargs: Keyword arguments corresponding to MCP tool parameters.
+
+            Returns:
+                str: The textual result returned by the MCP tool.
+            """
+            from mcp.types import CallToolResult
+
+            missing_params: Set[str] = set(required_params) - set(
+                kwargs.keys()
+            )
+            if missing_params:
+                raise ValueError(
+                    f"Missing required parameters: {missing_params}"
+                )
+
+            result: CallToolResult = await self._session.call_tool(
+                func_name, kwargs
+            )
+
+            if not result.content:
+                return "No data available for this request."
+
+            # Handle different content types
+            content = result.content[0]
+            if content.type == "text":
+                return content.text
+            elif content.type == "image":
+                # Return image URL or data URI if available
+                if hasattr(content, "url") and content.url:
+                    return f"Image available at: {content.url}"
+                return "Image content received (data URI not shown)"
+            elif content.type == "embedded_resource":
+                # Return resource information if available
+                if hasattr(content, "name") and content.name:
+                    return f"Embedded resource: {content.name}"
+                return "Embedded resource received"
+            else:
+                msg = f"Received content of type '{content.type}'"
+                return f"{msg} which is not fully supported yet."
+
+        dynamic_function.__name__ = func_name
+        dynamic_function.__doc__ = func_desc
+        dynamic_function.__annotations__ = annotations
+
+        sig = inspect.Signature(
+            parameters=[
+                inspect.Parameter(
+                    name=param,
+                    kind=inspect.Parameter.KEYWORD_ONLY,
+                    default=defaults.get(param, inspect.Parameter.empty),
+                    annotation=annotations[param],
+                )
+                for param in func_params
+            ]
+        )
+        dynamic_function.__signature__ = sig  # type: ignore[attr-defined]
+
+        return dynamic_function
+
+    def get_tools(self) -> List[FunctionTool]:
+        r"""Returns a list of FunctionTool objects representing the
+        functions in the toolkit. Each function is dynamically generated
+        based on the MCP tool definitions received from the server.
+
+        Returns:
+            List[FunctionTool]: A list of FunctionTool objects
+                representing the functions in the toolkit.
+        """
+        return [
+            FunctionTool(self.generate_function_from_mcp_tool(mcp_tool))
+            for mcp_tool in self._mcp_tools
+        ]

camel/toolkits/page_script.js

@@ -0,0 +1,376 @@
+var MultimodalWebSurfer = MultimodalWebSurfer || (function() {
+    let nextLabel = 10;
+  
+    let roleMapping = {
+        "a": "link",
+        "area": "link",
+        "button": "button",
+        "input, type=button": "button",
+        "input, type=checkbox": "checkbox",
+        "input, type=email": "textbox",
+        "input, type=number": "spinbutton",
+        "input, type=radio": "radio",
+        "input, type=range": "slider",
+        "input, type=reset": "button",
+        "input, type=search": "searchbox",
+        "input, type=submit": "button",
+        "input, type=tel": "textbox",
+        "input, type=text": "textbox",
+        "input, type=url": "textbox",
+        "search": "search",
+        "select": "combobox",
+        "option": "option",
+        "textarea": "textbox"
+    };
+  
+    let getCursor = function(elm) {
+        return window.getComputedStyle(elm)["cursor"];
+    };
+  
+    let getInteractiveElements = function() {
+  
+        let results = []
+        let roles = ["scrollbar", "searchbox", "slider", "spinbutton", "switch", "tab", "treeitem", "button", "checkbox", "gridcell", "link", "menuitem", "menuitemcheckbox", "menuitemradio", "option", "progressbar", "radio", "textbox", "combobox", "menu", "tree", "treegrid", "grid", "listbox", "radiogroup", "widget"];
+        let inertCursors = ["auto", "default", "none", "text", "vertical-text", "not-allowed", "no-drop"];
+  
+        // Get the main interactive elements
+        let nodeList = document.querySelectorAll("input, select, textarea, button, [href], [onclick], [contenteditable], [tabindex]:not([tabindex='-1'])");
+        for (let i=0; i<nodeList.length; i++) { // Copy to something mutable
+            results.push(nodeList[i]);
+        }
+  
+        // Anything not already included that has a suitable role
+        nodeList = document.querySelectorAll("[role]");
+        for (let i=0; i<nodeList.length; i++) { // Copy to something mutable
+            if (results.indexOf(nodeList[i]) == -1) {
+                let role = nodeList[i].getAttribute("role");
+            if (roles.indexOf(role) > -1) {
+                    results.push(nodeList[i]);
+            }
+        }
+        }
+  
+        // Any element that changes the cursor to something implying interactivity
+        nodeList = document.querySelectorAll("*");
+        for (let i=0; i<nodeList.length; i++) {
+           let node = nodeList[i];
+  
+           // Cursor is default, or does not suggest interactivity
+           let cursor = getCursor(node);
+           if (inertCursors.indexOf(cursor) >= 0) {
+               continue;
+           }
+  
+           // Move up to the first instance of this cursor change
+           parent = node.parentNode;
+           while (parent && getCursor(parent) == cursor) {
+               node = parent;
+           parent = node.parentNode;
+           }
+  
+           // Add the node if it is new
+           if (results.indexOf(node) == -1) {
+               results.push(node);
+           }
+        }
+  
+        return results;
+    };
+  
+    let labelElements = function(elements) {
+        for (let i=0; i<elements.length; i++) {
+            if (!elements[i].hasAttribute("__elementId")) {
+                elements[i].setAttribute("__elementId", "" + (nextLabel++));
+            }
+        }
+    };
+  
+    let isTopmost = function(element, x, y) {
+       let hit = document.elementFromPoint(x, y);
+  
+       // Hack to handle elements outside the viewport
+       if (hit === null) {
+           return true; 
+       }
+  
+       while (hit) {
+           if (hit == element) return true;
+           hit = hit.parentNode;
+       }
+       return false;
+    };
+  
+    let getFocusedElementId = function() {
+       let elm = document.activeElement;
+       while (elm) {
+           if (elm.hasAttribute && elm.hasAttribute("__elementId")) {
+           return elm.getAttribute("__elementId");
+       }
+           elm = elm.parentNode;
+       }
+       return null;
+    };
+  
+    let trimmedInnerText = function(element) {
+        if (!element) {
+            return "";
+        }
+        let text = element.innerText;
+        if (!text) {
+            return "";
+        }
+        return text.trim();
+    };
+  
+    let getApproximateAriaName = function(element) {
+        // Check for aria labels
+        if (element.hasAttribute("aria-labelledby")) {
+            let buffer = "";
+        let ids = element.getAttribute("aria-labelledby").split(" ");
+        for (let i=0; i<ids.length; i++) {
+                let label = document.getElementById(ids[i]);
+            if (label) {
+                buffer = buffer + " " + trimmedInnerText(label);
+                }
+            }
+        return buffer.trim();
+        }
+  
+        if (element.hasAttribute("aria-label")) {
+        return element.getAttribute("aria-label");
+        }
+  
+        // Check for labels
+        if (element.hasAttribute("id")) {
+            let label_id = element.getAttribute("id");
+            let label = "";
+            let labels = document.querySelectorAll("label[for='" + label_id + "']");
+            for (let j=0; j<labels.length; j++) {
+                label += labels[j].innerText + " ";
+            }
+            label = label.trim();
+            if (label != "") {
+                return label;
+            }
+        }
+  
+        if (element.parentElement && element.parentElement.tagName == "LABEL") {
+            return element.parentElement.innerText;
+        }
+  
+        // Check for alt text or titles
+        if (element.hasAttribute("alt")) {
+        return element.getAttribute("alt")
+        }
+  
+        if (element.hasAttribute("title")) {
+        return element.getAttribute("title")
+        }
+  
+        return trimmedInnerText(element);
+    };
+  
+    let getApproximateAriaRole = function(element) {
+        let tag = element.tagName.toLowerCase();
+        if (tag == "input" && element.hasAttribute("type")) {
+            tag = tag + ", type=" + element.getAttribute("type");
+        }
+  
+        if (element.hasAttribute("role")) {
+            return [element.getAttribute("role"), tag];
+        }
+        else if (tag in roleMapping) {
+            return [roleMapping[tag], tag];
+        }
+        else {
+        return ["", tag];
+        }
+    };
+  
+    let getInteractiveRects = function() {
+        labelElements(getInteractiveElements());
+        let elements = document.querySelectorAll("[__elementId]");
+        let results = {};
+        for (let i=0; i<elements.length; i++) {
+           let key = elements[i].getAttribute("__elementId");
+           let rects = elements[i].getClientRects();
+       let ariaRole = getApproximateAriaRole(elements[i]);
+       let ariaName = getApproximateAriaName(elements[i]);
+       let vScrollable = elements[i].scrollHeight - elements[i].clientHeight >= 1;
+  
+       let record = {
+               "tag_name": ariaRole[1],
+           "role": ariaRole[0],
+           "aria-name": ariaName,
+           "v-scrollable": vScrollable,
+           "rects": []
+       };
+  
+           for (const rect of rects) {
+           let x = rect.left + rect.width/2;
+               let y = rect.top + rect.height/2;
+               if (isTopmost(elements[i], x, y)) {
+           record["rects"].push(JSON.parse(JSON.stringify(rect)));
+               }
+           }
+  
+       if (record["rects"].length > 0) {
+               results[key] = record;
+           }
+        }
+        return results;
+    };
+  
+    let getVisualViewport = function() {
+        let vv = window.visualViewport;
+        let de = document.documentElement;
+        return {
+            "height":     vv ? vv.height : 0,
+        "width":      vv ? vv.width : 0,
+        "offsetLeft": vv ? vv.offsetLeft : 0,
+        "offsetTop":  vv ? vv.offsetTop : 0,
+        "pageLeft":   vv ? vv.pageLeft  : 0,
+        "pageTop":    vv ? vv.pageTop : 0,
+        "scale":      vv ? vv.scale : 0,
+        "clientWidth":  de ? de.clientWidth : 0,
+        "clientHeight": de ? de.clientHeight : 0,
+        "scrollWidth":  de ? de.scrollWidth : 0,
+        "scrollHeight": de ? de.scrollHeight : 0
+        };
+    };
+  
+    let _getMetaTags = function() {
+        let meta = document.querySelectorAll("meta");
+        let results = {};
+        for (let i = 0; i<meta.length; i++) {
+            let key = null;
+            if (meta[i].hasAttribute("name")) {
+                key = meta[i].getAttribute("name");
+            }
+            else if (meta[i].hasAttribute("property")) {
+                key = meta[i].getAttribute("property");
+            }
+            else {
+                continue;
+            }
+            if (meta[i].hasAttribute("content")) {
+                results[key] = meta[i].getAttribute("content");
+            }
+        }
+        return results;
+    };
+  
+    let _getJsonLd = function() {
+        let jsonld = [];
+        let scripts = document.querySelectorAll('script[type="application/ld+json"]');
+        for (let i=0; i<scripts.length; i++) {
+            jsonld.push(scripts[i].innerHTML.trim());
+        }
+        return jsonld;
+     };
+  
+     // From: https://www.stevefenton.co.uk/blog/2022/12/parse-microdata-with-javascript/
+     let _getMicrodata = function() {
+        function sanitize(input) {
+            return input.replace(/\s/gi, ' ').trim();
+        }
+  
+        function addValue(information, name, value) {
+            if (information[name]) {
+                if (typeof information[name] === 'array') {
+                    information[name].push(value);
+                } else {
+                    const arr = [];
+                    arr.push(information[name]);
+                    arr.push(value);
+                    information[name] = arr;
+                }
+            } else {
+                information[name] = value;
+            }
+        }
+  
+        function traverseItem(item, information) {
+           const children = item.children;
+          
+           for (let i = 0; i < children.length; i++) {
+               const child = children[i];
+  
+               if (child.hasAttribute('itemscope')) {
+                   if (child.hasAttribute('itemprop')) {
+                       const itemProp = child.getAttribute('itemprop');
+                       const itemType = child.getAttribute('itemtype');
+  
+                       const childInfo = {
+                           itemType: itemType
+                       };
+  
+                       traverseItem(child, childInfo);
+  
+                       itemProp.split(' ').forEach(propName => {
+                           addValue(information, propName, childInfo);
+                       });
+                   }
+  
+               } else if (child.hasAttribute('itemprop')) {
+                   const itemProp = child.getAttribute('itemprop');
+                   itemProp.split(' ').forEach(propName => {
+                       if (propName === 'url') {
+                           addValue(information, propName, child.href);
+                       } else {
+                           addValue(information, propName, sanitize(child.getAttribute("content") || child.content || child.textContent || child.src || ""));
+                       }
+                   });
+                   traverseItem(child, information);
+               } else {
+                   traverseItem(child, information);
+               }
+           }
+        }
+  
+        const microdata = [];
+  
+        document.querySelectorAll("[itemscope]").forEach(function(elem, i) {
+           const itemType = elem.getAttribute('itemtype');
+           const information = {
+               itemType: itemType
+           };
+           traverseItem(elem, information);
+           microdata.push(information);
+        });
+      
+        return microdata;
+     };
+  
+     let getPageMetadata = function() {
+         let jsonld = _getJsonLd();
+         let metaTags = _getMetaTags();
+         let microdata = _getMicrodata();
+         let results = {}
+         if (jsonld.length > 0) {
+             try {
+                 results["jsonld"] = JSON.parse(jsonld);
+             } 
+         catch (e) {
+                 results["jsonld"] = jsonld;
+         }
+         }
+         if (microdata.length > 0) {
+         results["microdata"] = microdata;
+         }
+         for (let key in metaTags) {
+         if (metaTags.hasOwnProperty(key)) {
+             results["meta_tags"] = metaTags;
+             break;
+             }
+         }
+         return results;
+     };	
+  
+     return {
+         getInteractiveRects: getInteractiveRects,
+         getVisualViewport: getVisualViewport,
+         getFocusedElementId: getFocusedElementId,
+         getPageMetadata: getPageMetadata,
+     };
+  })();