ff-mcp

ff-mcp는 로컬 MCP 클라이언트가 이미 사용 중인 Firefox 프로필에 통제된 접근 권한을 부여합니다. Firefox Manifest V3 WebExtension과 Python Native Messaging 호스트로 구성되며, 호스트는 127.0.0.1에서 Streamable HTTP를 통해 MCP를 제공합니다.

확장 프로그램(로컬호스트 프로세스가 아닌)이 최종 인증 경계입니다. 탭 메타데이터를 나열하는 것은 페이지 콘텐츠에 대한 접근을 부여하지 않습니다. 읽기, 상호작용, 스크린샷은 독립적이고 취소 가능한 권한이 필요합니다.

현재 기능

• 페이지 접근 없이 탭 메타데이터를 나열합니다.

• 특정 탭에 대해 READ, INTERACT, SCRIPT, SCREENSHOT을 요청합니다.

• 문서, 탭 세션, 또는 호스트에 대해 한 번, 지속적으로 접근을 부여합니다.

• 제한된 직렬화된 스냅샷과 CSS 쿼리 결과를 읽습니다. 라이브 DOM 객체는 브리지를 절대 건너지 않습니다.

• 구조화된 작업을 통해 클릭, 입력, 스크롤, 탐색을 수행합니다.

• 별도의 스크린샷 권한이 있어야만 탭을 캡처할 수 있습니다.

• 격리된 사용자 스크립트 세계 또는 페이지의 메인 세계에서 임의의 JavaScript를 실행하려면 별도의 SCRIPT 권한과 Firefox의 선택적 userScripts 권한이 필요합니다.

• host, glob, regex, scheme 조건자를 AND, OR, NOT으로 결합하여 영구 정책을 매칭합니다.

• Firefox 내에서 인증 결정과 민감한 작업을 감사합니다.

• MCP를 루프백에만 바인딩하고, 생성된 베어러 토큰을 요구하며, 기본적으로 HTTP 출처를 거부합니다.

요구 사항

• Firefox 150 이상.

• Python 3.14 (패키지는 3.14 마이너 라인에 고정됨).

• 설치에는 uv를 권장합니다.

일회성 SCRIPT 실행은 Firefox 153 이상이 필요합니다. 해당 릴리스에서 userScripts.execute()가 도입되었기 때문입니다. 나머지 기능은 Firefox 150부터 지원됩니다.

체크아웃에서 설치

네이티브 컴패니언을 영구 도구로 설치한 다음 Firefox에 등록합니다:

uv tool install .
ff-mcp install-native

개발 중에는 extension/manifest.json을 about:debugging → This Firefox → Load Temporary Add-on에서 로드합니다.

ff-mcp 툴바 팝업을 열고 Start를 누릅니다. 첫 시작 시 임의의 토큰이 포함된 개인 구성 파일이 생성됩니다:

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

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

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

팝업은 일반 연결 객체를 표시하고 복사할 수 있습니다:

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

Streamable HTTP와 사용자 정의 헤더를 지원하는 MCP 클라이언트에서 해당 값을 구성합니다. 엔드포인트는 확장 프로그램이 Native Messaging 연결을 유지하는 동안에만 존재합니다.

권한 흐름

1. browser_tabs를 호출하고 탭 ID를 선택합니다.

2. 하나 이상의 기능으로 browser_request_access를 호출합니다.

3. Firefox에서 툴바 요청을 승인합니다.

4. 읽기, 상호작용 또는 스크린샷 도구를 호출합니다.

5. 툴바에서 또는 browser_revoke로 권한을 취소합니다.

READ는 기본적으로 localhost, .localhost의 하위 도메인, 127.0.0.0/8, ::1에 대해서만 허용됩니다. 이 기본값에는 상호작용, 스크립팅 또는 스크린샷이 포함되지 않습니다.

정책 규칙

옵션 페이지에는 시각적 정책 편집기가 있습니다. 각 새 규칙은 OR 허용 그룹과 NAND 제외 그룹을 포함하는 메인 AND 컨테이너로 시작합니다. 호스트, URL 패턴, 정규식 또는 체계 조건을 추가하고, 필요에 따라 더 많은 AND, OR, NAND 또는 NOR 컨테이너를 중첩한 다음, 일치하는 규칙이 부여하는 기능을 선택합니다.

비어 있는 비부정 컨테이너는 아무것도 매칭하지 않습니다. 비어 있는 부정 컨테이너는 모든 것을 매칭하므로, 허용 그룹에 조건이 하나 이상 있을 때까지 새 규칙은 비활성 상태로 유지됩니다. 항상 활성화된 localhost READ 규칙은 별도로 표시되며 편집하거나 제거할 수 없습니다.

기존 표현식 기반 규칙은 설정 페이지가 열릴 때 시각적 트리로 마이그레이션됩니다. 표현식 형식은 이전 버전과의 호환성을 위해 저장된 표현으로 유지됩니다.

정규식 패턴은 길이가 제한되며 역참조, lookaround, 명백한 중첩 수량자를 거부합니다. 이는 완전한 RE2 구현이 아닌 안전 하위 집합입니다.

개발

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

Selenium이 자동으로 찾을 수 없는 설치의 경우 FIREFOX_BINARY를 설정합니다. 통합 테스트는 추가 구성 없이 표준 Linux Snap 위치를 인식합니다.

Firefox 확장 프로그램에는 런타임 타사 종속성이나 빌드 단계가 없습니다.

릴리스

vX.Y.Z 태그는 릴리스 워크플로를 실행합니다. 태그 버전은 pyproject.toml의 project.version과 extension/manifest.json의 version 모두와 일치해야 합니다. 워크플로는 Mozilla Add-ons에 unlisted 채널에서 확장 프로그램 서명을 요청하고, 반환된 XPI를 확인한 다음, 서명된 XPI와 SHA-256 체크섬을 GitHub 릴리스에 첨부합니다. 생성된 아티팩트는 추적되지 않습니다.

태그를 푸시하기 전에 저장소의 release 환경에 다음 시크릿을 구성합니다:

• AMO_JWT_ISSUER: AMO API 자격 증명의 발급자.

• AMO_JWT_SECRET: 해당 AMO API 시크릿.

AMO API 키 페이지에서 자격 증명을 생성합니다. 비공개 서명은 AMO 검색 또는 목록에 확장 프로그램을 게시하지 않습니다.

보안 제한

• 확장 프로그램은 임의의 탭을 중재하고 Firefox의 백그라운드 탭 스크린샷 API를 사용할 수 있도록 광범위한 사이트 접근을 필연적으로 요청합니다. 따라서 내부 기능 검사가 중요합니다.

• 승인된 브라우저 메타데이터, 웹사이트 콘텐츠 및 웹사이트 활동은 로컬 네이티브 호스트와 MCP 클라이언트로 전송됩니다. AMO는 설치 중에 이러한 필수 데이터 범주를 선언합니다.

• about: 및 애드온 스토어와 같은 Firefox 제한 페이지는 콘텐츠 스크립트로 읽을 수 없습니다.

• 탭 세션 권한은 해당 탭의 탐색을 의도적으로 유지합니다. 문서 권한은 그렇지 않습니다.

• MCP 클라이언트 ID는 단일 베어러 토큰 신뢰 도메인 내에서 설명적입니다. 상호 신뢰되지 않는 로컬 클라이언트가 격리되어야 하는 경우 별도의 구성과 토큰을 사용하십시오.

• 구조화된 클릭과 입력은 여전히 페이지 동작을 트리거할 수 있습니다. INTERACT를 아껴서 부여하십시오.

• SCRIPT는 사실상 전체 페이지 제어입니다. Firefox는 승인 중에 선택적 userScripts 권한을 요청하며, ff-mcp는 여전히 별도의 탭 기능을 요구합니다. MAIN 세계 스크립트는 페이지 소유 JavaScript 상태에 접근하고 변경할 수 있습니다. 신뢰하는 클라이언트와 사이트에만 부여하십시오.

이 구현에 앞선 설계 연구는 firefox_mcp_extension_findings.html을 참조하십시오.

라이선스

MIT. LICENSE 및 THIRD_PARTY.md를 참조하십시오.