foxmcp 1.5.0__py3-none-any.whl

foxmcp/__init__.py

@@ -0,0 +1,8 @@
+"""
+FoxMCP Server Package
+"""
+
+from .server import FoxMCPServer
+from .mcp_tools import FoxMCPTools
+
+__all__ = ["FoxMCPServer", "FoxMCPTools"]

foxmcp/browser_proxy.py

@@ -0,0 +1,257 @@
+"""Discovery and browser-command forwarding on the extension's existing port."""
+
+import asyncio
+from http import HTTPStatus
+import ipaddress
+import json
+import logging
+import math
+import os
+import re
+import time
+import uuid
+
+from websockets.exceptions import ConnectionClosed
+
+logger = logging.getLogger(__name__)
+SERVER_NAME = "FoxMCP"
+PROTOCOL_VERSION = 2
+EXTENSION_ORIGIN_PATTERN = re.compile(r"moz-extension://.+")
+
+
+class BrowserProxyHub:
+    """Route extension and local-client sockets without mixing their identities."""
+
+    def __init__(self, server):
+        self.server = server
+        self.clients = {}
+        self.idle_timeout = None  # Manually started servers have no idle shutdown.
+        self.last_departure = time.monotonic()
+        self.stopping = False
+
+    @staticmethod
+    def _is_local_host(authority):
+        # Validate the authority independently of the listener port: a local
+        # TCP forwarder preserves Host while connecting to a different port.
+        match = re.fullmatch(
+            r"(?:localhost|127\.0\.0\.1|\[::1\])(?::([0-9]{1,5}))?",
+            authority.lower(),
+        )
+        return match is not None and (
+            match[1] is None or 1 <= int(match[1]) <= 65535
+        )
+
+    def discovery(self):
+        return {
+            "server": SERVER_NAME,
+            "protocol_version": PROTOCOL_VERSION,
+            "proxy_path": "/proxy",
+            "pid": os.getpid(),
+            "lifetime": "automatic" if self.idle_timeout is not None else "manual",
+        }
+
+    def process_request(self, connection, request):
+        """Apply route-specific access checks before a socket can replace Firefox."""
+        host = request.headers.get_all("Host")
+        origin = request.headers.get_all("Origin")
+        remote = ipaddress.ip_address(connection.remote_address[0])
+        if not remote.is_loopback or len(host) != 1 or not self._is_local_host(host[0]):
+            return connection.respond(HTTPStatus.FORBIDDEN, "Localhost clients only\n")
+
+        if request.path == "/":
+            if not request.headers.get_all("Upgrade"):
+                return connection.respond(
+                    HTTPStatus.UPGRADE_REQUIRED, "WebSocket required\n"
+                )
+            if len(origin) != 1 or not EXTENSION_ORIGIN_PATTERN.fullmatch(origin[0]):
+                return connection.respond(
+                    HTTPStatus.FORBIDDEN, "Extension origin required\n"
+                )
+        elif request.path in ("/discovery", "/proxy"):
+            # Browser scripts always send Origin on WebSockets. Discovery has
+            # no CORS allowance either; reject even simple HTTP page requests.
+            if origin:
+                return connection.respond(
+                    HTTPStatus.FORBIDDEN, "Browser origins are refused\n"
+                )
+            if self.stopping:
+                return connection.respond(
+                    HTTPStatus.SERVICE_UNAVAILABLE, "Server stopping\n"
+                )
+            if request.path == "/discovery":
+                response = connection.respond(
+                    HTTPStatus.OK, json.dumps(self.discovery())
+                )
+                del response.headers["Content-Type"]
+                response.headers["Content-Type"] = "application/json"
+                response.headers["Cache-Control"] = "no-store"
+                return response
+        else:
+            return connection.respond(HTTPStatus.NOT_FOUND, "Unknown endpoint\n")
+        return None
+
+    async def handle_connection(self, websocket):
+        if websocket.request.path == "/proxy":
+            await self.handle_proxy(websocket)
+        else:
+            await self.server.handle_extension_connection(websocket)
+
+    async def handle_proxy(self, websocket):
+        owner = f"proxy:{uuid.uuid4().hex}"
+        self.clients[websocket] = owner
+        pending = {}
+        try:
+            await websocket.send(json.dumps({"type": "hello", **self.discovery()}))
+            async for message in websocket:
+                try:
+                    request = json.loads(message)
+                    if not isinstance(request, dict):
+                        raise ValueError("Request must be an object")
+                    request_id = request.get("id")
+                    timeout = request.get("timeout", 30.0)
+                    if (
+                        not isinstance(request_id, str)
+                        or not request_id
+                        or request.get("type") != "request"
+                        or not isinstance(request.get("action"), str)
+                        or not isinstance(request.get("data", {}), dict)
+                        or not isinstance(timeout, (float, int))
+                        or isinstance(timeout, bool)
+                        or not 0 < timeout <= 300
+                        or not math.isfinite(timeout)
+                    ):
+                        raise ValueError("Invalid browser request")
+                    if request_id in pending:
+                        raise ValueError("Request ID is already in flight")
+                except (ValueError, TypeError):
+                    await websocket.close(code=1008, reason="Invalid browser request")
+                    break
+                task = asyncio.create_task(
+                    self.forward(websocket, owner, request, timeout)
+                )
+                pending[request_id] = task
+                task.add_done_callback(
+                    lambda _task, key=request_id: pending.pop(key, None)
+                )
+        except ConnectionClosed:
+            pass
+        finally:
+            # A start-monitoring call may finish after the client goes away.
+            # Finish tracking its reply before cleaning up everything it owned.
+            await asyncio.gather(*list(pending.values()), return_exceptions=True)
+            self.clients.pop(websocket, None)
+            try:
+                await self.server.stop_monitors_of_gone_clients()
+            finally:
+                self.last_departure = time.monotonic()
+
+    async def forward(self, websocket, owner, request, timeout):
+        original_id = request["id"]
+        action = request["action"]
+        try:
+            if action == "proxy.status":
+                response = {
+                    "type": "response",
+                    "action": action,
+                    "data": {"status": await self.server.get_extension_status()},
+                }
+            else:
+                upstream = {**request, "id": uuid.uuid4().hex}
+                upstream.pop("timeout", None)
+                response = await self.server.send_request_and_wait(
+                    upstream, timeout=timeout
+                )
+                if response.get("type") == "response":
+                    data = response.get("data", {})
+                    if action == "requests.start_monitoring":
+                        self.server.register_monitor(data.get("monitor_id"), owner)
+                    elif action == "requests.stop_monitoring":
+                        self.server.forget_monitor(
+                            request.get("data", {}).get("monitor_id")
+                        )
+            await websocket.send(json.dumps({**response, "id": original_id}))
+        except ConnectionClosed:
+            pass
+        except Exception:
+            logger.exception("Browser proxy request failed: %s", action)
+            try:
+                await websocket.send(
+                    json.dumps(
+                        {"id": original_id, "error": "Browser proxy request failed"}
+                    )
+                )
+            except ConnectionClosed:
+                pass
+
+    async def wait_until_idle(self):
+        while True:
+            await asyncio.sleep(min(self.idle_timeout, 1.0))
+            if (
+                not self.clients
+                and time.monotonic() - self.last_departure >= self.idle_timeout
+            ):
+                self.stopping = True
+                return
+
+
+class RemoteBrowser:
+    """The browser interface used by local MCP tools, over a shared proxy socket."""
+
+    def __init__(self, websocket, file_transfers):
+        self.websocket = websocket
+        self.file_transfers = file_transfers
+        self.pending = {}
+        self.reader = asyncio.create_task(self.read_responses())
+
+    async def read_responses(self):
+        try:
+            async for message in self.websocket:
+                response = json.loads(message)
+                future = self.pending.get(response.get("id"))
+                if future is not None and not future.done():
+                    future.set_result(response)
+        except (ConnectionClosed, ValueError, TypeError, AttributeError):
+            pass
+        finally:
+            for future in self.pending.values():
+                if not future.done():
+                    future.set_result(
+                        {
+                            "error": "Browser proxy disconnected; reconnect the MCP client"
+                        }
+                    )
+
+    async def send_request_and_wait(self, request, timeout=30.0):
+        if self.reader.done():
+            return {"error": "Browser proxy disconnected; reconnect the MCP client"}
+        request_id = request["id"]
+        if request_id in self.pending:
+            return {"error": "Request ID is already in flight"}
+        future = asyncio.get_running_loop().create_future()
+        self.pending[request_id] = future
+        try:
+            await self.websocket.send(json.dumps({**request, "timeout": timeout}))
+            return await asyncio.wait_for(future, timeout + 1)
+        except ConnectionClosed:
+            return {"error": "Browser proxy disconnected; reconnect the MCP client"}
+        except asyncio.TimeoutError:
+            return {"error": f"Request timed out after {timeout} seconds"}
+        finally:
+            self.pending.pop(request_id, None)
+
+    async def get_extension_status(self):
+        response = await self.send_request_and_wait(
+            {
+                "id": uuid.uuid4().hex,
+                "type": "request",
+                "action": "proxy.status",
+                "data": {},
+            }
+        )
+        return response.get("data", {}).get("status") or response.get(
+            "error", "Unknown browser status"
+        )
+
+    async def close(self):
+        await self.websocket.close()
+        await self.reader

foxmcp/cli.py

@@ -0,0 +1,14 @@
+"""Console entry point for the installed FoxMCP distribution."""
+
+import os
+from pathlib import Path
+
+from .server import run
+
+
+def main() -> None:
+    """Use bundled examples unless configured, then start the existing server."""
+    examples = Path(__file__).with_name("examples")
+    if examples.is_dir():
+        os.environ.setdefault("FOXMCP_EXT_SCRIPTS", str(examples))
+    run()

foxmcp/examples/dom-summarize.sh

@@ -0,0 +1,207 @@
+#!/bin/bash
+# foxmcp-description: List the page's visible interactive elements as an indented tree, tagging each with a persistent dsid attribute to select it by later
+# foxmcp-args: [onscreen [withpos]]
+# DOM Summarization Script
+# Extracts visible interactive elements (input, textarea, select, button, a, option) from the current page
+# Assigns persistent dsid attributes to each element for future reference
+# Outputs a hierarchical structure with indentation showing nesting relationships
+#
+# Usage: Called via foxmcp content_execute_predefined
+# Arguments:
+#   $1 - Optional: "onscreen" to filter only elements visible in viewport
+#   $2 - Optional: "withpos" to include position/size info (only valid with "onscreen")
+#
+# Output format:
+# - Elements show only dsid attribute (and type for input, value/selected for options)
+# - With "withpos": adds pos="x,y,width,height" attribute showing element's screen position
+# - Text nodes shown as quoted strings without prefix
+# - 2-space indentation shows nesting hierarchy
+# - Non-interesting containers are flattened (their children promoted to parent level)
+
+FILTER_MODE="${1:-all}"
+INCLUDE_POS="${2:-}"
+
+# Validate that withpos is only used with onscreen
+if [ "$INCLUDE_POS" = "withpos" ] && [ "$FILTER_MODE" != "onscreen" ]; then
+  echo "Error: 'withpos' option requires 'onscreen' mode" >&2
+  exit 1
+fi
+
+# Generate JavaScript with filter mode injected
+cat << 'OUTER_EOF'
+(function() {
+OUTER_EOF
+
+echo "  const FILTER_MODE = \"${FILTER_MODE}\";"
+echo "  const INCLUDE_POS = \"${INCLUDE_POS}\";"
+
+cat << 'INNER_EOF'
+  let dsIdCounter = 1;
+
+  // Find the highest existing dsid to continue numbering from there
+  const allElements = document.querySelectorAll('[dsid]');
+  allElements.forEach(el => {
+    const id = parseInt(el.getAttribute('dsid'));
+    if (id >= dsIdCounter) {
+      dsIdCounter = id + 1;
+    }
+  });
+
+  function isElementVisible(element) {
+    if (!element) return false;
+
+    const style = window.getComputedStyle(element);
+
+    if (style.display === 'none') return false;
+    if (style.visibility === 'hidden') return false;
+    if (parseFloat(style.opacity) === 0) return false;
+
+    return true;
+  }
+
+  function isElementOnScreen(element) {
+    if (!element) return false;
+
+    const rect = element.getBoundingClientRect();
+    return (
+      rect.top < window.innerHeight &&
+      rect.bottom > 0 &&
+      rect.left < window.innerWidth &&
+      rect.right > 0
+    );
+  }
+
+  function hasEventListeners(element) {
+    for (let attr of element.attributes) {
+      if (attr.name.startsWith('on')) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  function isInterestingElement(node) {
+    if (node.nodeType !== Node.ELEMENT_NODE) return false;
+    const tagName = node.tagName.toLowerCase();
+    if (tagName === 'input' || tagName === 'textarea' || tagName === 'select' || tagName === 'button' || tagName === 'a' || tagName === 'option') {
+      return true;
+    }
+    if (hasEventListeners(node)) {
+      return true;
+    }
+    return false;
+  }
+
+  function traverseDOM(node, depth = 0) {
+    const result = [];
+    const indent = '  '.repeat(depth);
+
+    if (node.nodeType === Node.TEXT_NODE) {
+      const text = node.textContent.trim();
+      if (text.length > 0) {
+        result.push(`${indent}"${text.substring(0, 100)}${text.length > 100 ? '...' : ''}"`);
+      }
+    } else if (node.nodeType === Node.ELEMENT_NODE) {
+      if (!isElementVisible(node)) {
+        return result;
+      }
+
+      // Apply onscreen filter if requested
+      if (FILTER_MODE === 'onscreen' && !isElementOnScreen(node)) {
+        return result;
+      }
+
+      const isInteresting = isInterestingElement(node);
+
+      if (isInteresting) {
+        // Assign dsid if not already present
+        if (!node.hasAttribute('dsid')) {
+          node.setAttribute('dsid', dsIdCounter++);
+        }
+        const dsId = node.getAttribute('dsid');
+        const tagName = node.tagName.toLowerCase();
+
+        let elementStr = `${indent}<${tagName} dsid="${dsId}"`;
+
+        // Include type attribute for input elements
+        if (tagName === 'input') {
+          const type = node.type || 'text';
+          elementStr += ` type="${type}"`;
+        }
+
+        // Only include value and selected attributes for options
+        if (tagName === 'option') {
+          if (node.value) elementStr += ` value="${node.value}"`;
+          if (node.selected) elementStr += ` selected="true"`;
+        }
+
+        // Include position and size if requested
+        if (INCLUDE_POS === 'withpos') {
+          const rect = node.getBoundingClientRect();
+          const x = Math.round(rect.left);
+          const y = Math.round(rect.top);
+          const width = Math.round(rect.width);
+          const height = Math.round(rect.height);
+          elementStr += ` pos="${x},${y},${width},${height}"`;
+        }
+
+        elementStr += '>';
+        result.push(elementStr);
+
+        for (let child of node.childNodes) {
+          result.push(...traverseDOM(child, depth + 1));
+        }
+      } else {
+        // Not interesting, flatten: process children at same depth
+        for (let child of node.childNodes) {
+          result.push(...traverseDOM(child, depth));
+        }
+      }
+    }
+
+    return result;
+  }
+
+  function concatenateAdjacentText(lines) {
+    const result = [];
+    let i = 0;
+
+    while (i < lines.length) {
+      const line = lines[i];
+      const indent = line.match(/^(\s*)/)[1];
+      const isText = line.trim().startsWith('"');
+
+      if (isText) {
+        // Collect all adjacent text nodes at the same indentation level
+        let concatenated = line.trim().slice(1, -1); // Remove quotes
+        let j = i + 1;
+
+        while (j < lines.length) {
+          const nextLine = lines[j];
+          const nextIndent = nextLine.match(/^(\s*)/)[1];
+          const nextIsText = nextLine.trim().startsWith('"');
+
+          if (nextIsText && nextIndent === indent) {
+            concatenated += ' ' + nextLine.trim().slice(1, -1);
+            j++;
+          } else {
+            break;
+          }
+        }
+
+        result.push(`${indent}"${concatenated}"`);
+        i = j;
+      } else {
+        result.push(line);
+        i++;
+      }
+    }
+
+    return result;
+  }
+
+  const output = traverseDOM(document.body);
+  const concatenated = concatenateAdjacentText(output);
+  return concatenated.join('\n');
+})();
+INNER_EOF