ff-mcp

ff-mcp brinda a los clientes MCP locales acceso controlado al perfil de Firefox que ya usas. Está compuesto por una extensión web de Firefox Manifest V3 y un host de mensajería nativa de Python que sirve MCP sobre HTTP Streamable en 127.0.0.1.

La extensión—no el proceso localhost—es el límite final de autorización. Enumerar metadatos de pestañas no otorga acceso al contenido de la página. La lectura, la interacción y las capturas de pantalla requieren capacidades independientes y revocables.

Capacidades actuales

• Enumerar metadatos de pestañas sin acceso a la página.

• Solicitar READ, INTERACT, SCRIPT y SCREENSHOT en una pestaña específica.

• Otorgar acceso una vez, para un documento, para una sesión de pestaña o de forma persistente para un host.

• Leer instantáneas serializadas limitadas y resultados de consultas CSS. Los objetos DOM en vivo nunca cruzan el puente.

• Hacer clic, escribir, desplazarse y navegar mediante operaciones estructuradas.

• Capturar una pestaña solo con una concesión de captura de pantalla separada.

• Ejecutar JavaScript arbitrario en el mundo de scripts de usuario aislado o en el mundo principal de la página solo con una concesión SCRIPT separada y el permiso opcional userScripts de Firefox.

• Hacer coincidir políticas persistentes con predicados host, glob, regex y scheme compuestos con AND, OR y NOT.

• Auditar decisiones de autorización y operaciones sensibles dentro de Firefox.

• Vincular MCP solo a loopback, requerir un token de portador generado y rechazar orígenes HTTP por defecto.

Requisitos

• Firefox 150 o más reciente.

• Python 3.14 (el paquete está fijado a la línea menor 3.14).

• Se recomienda uv para la instalación.

La ejecución única de SCRIPT requiere Firefox 153 o más reciente porque esa versión introdujo userScripts.execute(). Las capacidades restantes admiten Firefox 150 en adelante.

Instalar desde un clon

Instala el compañero nativo como herramienta persistente y luego regístralo con Firefox:

uv tool install .
ff-mcp install-native

Para desarrollo, carga extension/manifest.json desde about:debugging → Este Firefox → Cargar complemento temporal.

Abre la ventana emergente de la barra de herramientas de ff-mcp y presiona Iniciar. El primer inicio crea un archivo de configuración privado que contiene un token aleatorio:

• Linux: $XDG_CONFIG_HOME/ff-mcp/config.json o ~/.config/ff-mcp/config.json

• macOS: ~/.config/ff-mcp/config.json

• Windows: %APPDATA%\ff-mcp\config.json

La ventana emergente muestra y puede copiar un objeto de conexión genérico:

{
  "url": "http://127.0.0.1:8765/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_GENERATED_TOKEN"
  }
}

Configura esos valores en un cliente MCP que admita HTTP Streamable y encabezados personalizados. El endpoint existe solo mientras la extensión mantiene abierta su conexión de mensajería nativa.

Flujo de permisos

1. Llama a browser_tabs y elige un ID de pestaña.

2. Llama a browser_request_access con una o más capacidades.

3. Aprueba la solicitud de la barra de herramientas en Firefox.

4. Llama a la herramienta de lectura, interacción o captura de pantalla.

5. Revoca la concesión desde la barra de herramientas o con browser_revoke.

READ está permitido por defecto solo para localhost, subdominios de .localhost, 127.0.0.0/8 y ::1. Este valor predeterminado no incluye interacción, scripting ni capturas de pantalla.

Reglas de política

La página de opciones tiene un editor visual de políticas. Cada nueva regla comienza con un contenedor AND principal que contiene un grupo de permitidos OR y un grupo de exclusión NAND. Agrega condiciones de host, patrón de URL, regex o esquema; anida más contenedores AND, OR, NAND o NOR cuando sea necesario; luego elige las capacidades que otorga la regla coincidente.

Los contenedores vacíos no negados no coinciden con nada. Los contenedores vacíos negados coinciden con todo, por lo que una nueva regla permanece inactiva hasta que su grupo de permitidos tenga al menos una condición. La regla READ de localhost siempre habilitada se muestra por separado y no se puede editar ni eliminar.

Las reglas existentes basadas en expresiones se migran al árbol visual cuando se abre la página de configuración. El formato de expresión sigue siendo la representación almacenada para compatibilidad hacia atrás.

Los patrones regex tienen límite de longitud y rechazan referencias inversas, lookarounds y cuantificadores anidados obvios. Este es un subconjunto de seguridad, no una implementación completa de RE2.

Desarrollo

UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv sync --group dev
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q
# Opt-in: launches the installed Firefox headlessly with a fresh temporary profile.
FF_MCP_RUN_FIREFOX_TESTS=1 UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run pytest -q tests/test_firefox_integration.py
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff check .
UV_CACHE_DIR=/tmp/ff-mcp-uv-cache uv run ruff format --check .
node tests/policy.test.js
node tests/rule-model.test.js
node tests/background.test.js
node tests/content.test.js
node --check extension/background.js
node --check extension/content.js
node --check extension/options.js
node --check scripts/check-web-ext-lint.js

Establece FIREFOX_BINARY para instalaciones que Selenium no puede descubrir automáticamente. La prueba de integración reconoce la ubicación estándar de Linux Snap sin configuración adicional.

La extensión de Firefox no tiene dependencias de terceros en tiempo de ejecución ni paso de compilación.

Lanzamientos

Las etiquetas llamadas vX.Y.Z ejecutan el flujo de trabajo de lanzamiento. La versión de la etiqueta debe coincidir tanto con project.version en pyproject.toml como con version en extension/manifest.json. El flujo de trabajo solicita a Mozilla Add-ons que firme la extensión en el canal unlisted, verifica el XPI devuelto y adjunta el XPI firmado junto con su suma de verificación SHA-256 a un lanzamiento de GitHub. Los artefactos generados permanecen sin seguimiento.

Configura estos secretos en el entorno release del repositorio antes de empujar una etiqueta:

• AMO_JWT_ISSUER: el emisor de una credencial de API de AMO.

• AMO_JWT_SECRET: el secreto de API de AMO correspondiente.

Crea las credenciales desde la página de claves de API de AMO. La firma no listada no publica la extensión en la búsqueda ni en los listados de AMO.

Límites de seguridad

• La extensión necesariamente solicita acceso amplio al sitio para poder mediar en pestañas arbitrarias y usar la API de captura de pantalla de pestañas en segundo plano de Firefox. Por lo tanto, sus comprobaciones internas de capacidades son críticas.

• Los metadatos del navegador aprobados, el contenido del sitio web y la actividad del sitio web se transmiten al host nativo local y al cliente MCP. AMO declara estas categorías de datos requeridas durante la instalación.

• Las páginas restringidas de Firefox, como about: y la tienda de complementos, no pueden ser leídas por los scripts de contenido.

• Una concesión de sesión de pestaña sobrevive intencionalmente a la navegación en esa pestaña; las concesiones de documento no.

• La identidad del cliente MCP es descriptiva dentro del único dominio de confianza del token de portador. Usa una configuración y token separados si los clientes locales que no se confían mutuamente necesitan aislamiento.

• Los clics y la entrada estructurados aún pueden desencadenar el comportamiento de la página. Otorga INTERACT con moderación.

• SCRIPT es efectivamente control total de la página. Firefox solicita su permiso opcional userScripts durante la aprobación, y ff-mcp aún requiere una capacidad de pestaña separada. Los scripts del mundo MAIN pueden acceder y alterar el estado de JavaScript propiedad de la página; otorga esto solo a clientes y sitios en los que confíes.

Consulta firefox_mcp_extension_findings.html para la investigación de diseño que precedió a esta implementación.

Licencia

MIT. Consulta LICENSE y THIRD_PARTY.md.