ruyipage-mcp
ruyipage-mcp
ruyiPage의 Firefox BiDi 자동화 기능을 MCP (Model Context Protocol)를 통해 AI가 호출할 수 있는 도구 세트로 노출합니다.
Claude Code, Cursor 등 모든 MCP 클라이언트를 지원합니다.
특징
34개의 도구, 브라우저 자동화 전체 프로세스 커버: 브라우저 시작/연결, 페이지 탐색, DOM 검색 및 상호작용, 스크린샷/PDF, 쿠키/스토리지, JS 실행, 네트워크 가로채기/모니터링/데이터 수집, 탭 관리, 기기 에뮬레이션, BiDi 이벤트 구독
네이티브 BiDi 동작 우선 — 클릭, 입력, 드래그 등의 작업은
isTrusted=true를 유지하여 높은 보안 환경에 더 적합함지문 브라우저 연결 지원 — ADS / FlowerBrowser 등 Firefox 엔진 기반 지문 브라우저를 자동으로 탐지하고 연결 가능
지능형 요소 관리 — LRU 요소 레지스트리, 자동 회수 + 만료된 요소 자동 재검색
스크린샷 자동 압축 — 초대형 이미지 자동 축소, JPEG 압축, 대용량 이미지 자동 파일 저장
stdio 전송 — 표준 JSON-RPC 2.0, 즉시 사용 가능
Related MCP server: MCP Selenium Server
설치
사전 요구 사항
Python >= 3.10
ruyiPage >= 1.1.0
Firefox 브라우저 (ruyiPage 전용 Firefox 엔진 권장)
소스 코드에서 설치
git clone https://github.com/LoseNine/ruyipage-mcp.git
cd ruyipage-mcp
pip install -e .AI에게 GitHub 링크를 직접 제공하여 설치를 요청할 수도 있습니다.
설정
Claude Code
방법 1: 프로젝트 수준 .mcp.json (권장)
{
"mcpServers": {
"ruyipage": {
"command": "python",
"args": ["-m", "ruyipage_mcp"]
}
}
}Cursor / 기타 MCP 클라이언트
해당 MCP 설정 파일에 다음을 추가하세요:
{
"mcpServers": {
"ruyipage": {
"command": "python",
"args": ["-m", "ruyipage_mcp"]
}
}
}독립 실행
python -m ruyipage_mcp서버는 stdin/stdout을 통해 JSON-RPC 메시지를 전송하며, 로그는 stderr로 출력됩니다.
설정
설정 파일
ruyipage_mcp.example.json을 ruyipage_mcp.json으로 복사하여 필요에 따라 수정하세요:
cp ruyipage_mcp.example.json ruyipage_mcp.json{
"browser_path": "E:\\ruyi_firefox\\firefox.exe",
"disable_run_js": false,
"disable_extensions": false,
"browser_path_whitelist": [],
"max_elements": 512,
"event_buffer_size": 500,
"wait_timeout_ceiling": 60
}설정 파일 검색 순서:
RUYIPAGE_MCP_CONFIG환경 변수로 지정된 경로현재 작업 디렉토리의
ruyipage_mcp.json설정 파일을 찾을 수 없는 경우 내장 기본값 사용
설정 항목 | 타입 | 기본값 | 설명 |
| string |
| Firefox 실행 파일 경로 |
| bool |
|
|
| bool |
|
|
| list |
| 허용된 브라우저 경로 목록 |
| int |
| 세션당 요소 레지스트리 LRU 용량 |
| int |
| BiDi 이벤트 버퍼 크기 |
| int |
| 모든 대기 관련 도구의 최대 타임아웃(초) |
환경 변수 오버라이드
환경 변수는 설정 파일보다 우선순위가 높으며, CI 또는 임시 오버라이드 시나리오에 적합합니다:
환경 변수 | 대응 설정 항목 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 설정 파일 경로 지정 |
도구 목록 (34개)
session — 브라우저 생명 주기
도구 | 설명 |
| 새 Firefox 브라우저 시작. 사용자 지정 포트, 헤드리스 모드, 프라이빗 모드, XPath Picker, 창 크기 등 지원 |
|
|
| 프로세스 특성에 따라 Firefox / ADS / FlowerBrowser 자동 탐지 및 연결 |
| 브라우저 세션 종료. |
일반적인 흐름:
session_launch(port=9222)
→ 操作页面...
→ session_quit()# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
→ 操作页面...
→ session_quit() # 仅释放连接,浏览器继续运行nav — 페이지 탐색
도구 | 설명 |
| URL 열기, |
| 뒤로 가기 |
| 앞으로 가기 |
| 새로 고침 |
| 현재 페이지의 URL, 제목, ready state 가져오기 |
dom — 요소 검색 및 읽기
도구 | 설명 |
| 단일 요소 검색, |
| 일치하는 모든 요소 검색, 목록 반환 (기본 상한 20, 최대 100) |
| 요소 속성 읽기: |
| 기존 요소 내부에서 하위 요소 검색 |
| 요소가 나타날 때까지 대기 (타임아웃 포함) |
| 요소 핸들 해제, 레지스트리 공간 회수 |
위치 지정자 형식:
형식 | 예시 | 설명 |
|
| ID 선택자 |
|
| CSS 선택자 |
|
| XPath |
|
| 텍스트 일치 |
|
| 태그 이름 |
act — 요소 상호작용
도구 | 설명 |
| 요소 클릭. 좌클릭 / 우클릭 / 더블 클릭 지원, JS 클릭 옵션. 기본적으로 네이티브 BiDi 동작 사용 ( |
| 텍스트 입력. 네이티브 BiDi 키보드 입력, 기존 내용 삭제 옵션. JS 폴백 지원 |
| 간단한 작업: |
| BiDi 동작 체인 실행 (JSON 배열), 키 입력, 클릭, 이동, 드래그, 휠, 일시 정지 등 지원 |
act_chain 지원 동작:
[
{"action": "press", "key": "Enter"},
{"action": "click"},
{"action": "click", "element_id": "el_abc123"},
{"action": "move_to", "element_id": "el_abc123"},
{"action": "move_to", "x": 100, "y": 200},
{"action": "double_click"},
{"action": "right_click"},
{"action": "key_down", "key": "Shift"},
{"action": "key_up", "key": "Shift"},
{"action": "type", "text": "hello"},
{"action": "scroll", "x": 0, "y": -300},
{"action": "pause", "duration": 500}
]state — 페이지 상태
도구 | 설명 |
| 스크린샷. 전체 페이지 스크린샷, 요소 스크린샷, 파일 저장 지원. 자동 압축, 초대형 이미지 자동 파일 저장 |
| 현재 페이지를 PDF로 저장 |
| 쿠키 관리: |
| localStorage / sessionStorage 관리: |
js — JavaScript 실행
도구 | 설명 |
| 페이지에서 JS 코드 실행. 표현식 평가 ( |
| preload 스크립트 관리: |
net — 네트워크 제어
도구 | 설명 |
| 요청 가로채기: |
| 네트워크 모니터링: |
| 데이터 수집기: |
| 추가 요청 헤더 설정/삭제 |
| 캐시 동작 설정: |
요청 가로채기 일반적인 흐름:
net_intercept(op="start", url_patterns="api/login")
→ 触发页面操作
→ net_intercept(op="wait_and_resolve", action='{"mode":"mock","status":200,"body":"{}"}')
→ net_intercept(op="stop")네트워크 모니터링 일반적인 흐름:
net_listen(op="start", targets="api/data", method="POST")
→ 触发页面操作
→ net_listen(op="wait", timeout=10)
→ net_listen(op="stop")ctx — 컨텍스트 관리
도구 | 설명 |
| 탭 관리: |
| 기기 에뮬레이션: 지리적 위치, 시간대, 언어, 모바일 기기 프리셋, 오프라인 모드, JS 스위치 |
| BiDi 이벤트 구독: |
에뮬레이션 작업 예시:
ctx_emulation(op="set_geolocation", latitude=39.9, longitude=116.4)
ctx_emulation(op="set_timezone", timezone_id="Asia/Tokyo")
ctx_emulation(op="set_locale", locales="ja-JP,ja")
ctx_emulation(op="apply_mobile_preset", width=390, height=844, device_pixel_ratio=3)
ctx_emulation(op="set_offline", enabled=true)
ctx_emulation(op="set_offline", enabled=false)meta — 서버 정보
도구 | 설명 |
| 현재 서버 상태 반환: 활성 세션, 요소 수, 설정 스위치, 도구 네임스페이스 목록 |
핵심 개념
세션 관리
각 브라우저 연결은 host:port (예: 127.0.0.1:9222)를 식별자로 하는 session에 대응합니다.
활성 세션이 하나뿐일 경우, 모든 도구의
session_id매개변수는 생략 가능하며 자동으로 해석됩니다.세션이 여러 개인 경우,
session_id를 명시적으로 전달해야 합니다.session_launch는 owned 세션을 생성하며,session_quit시 브라우저 프로세스가 종료됩니다.session_attach/session_auto_attach는 attached 세션을 생성하며,session_quit시 연결만 해제됩니다.
요소 레지스트리
dom_find / dom_find_all을 통해 검색된 요소는 현재 세션의 요소 레지스트리에 등록되며, 짧은 ID (예: el_a3f2b1)가 반환됩니다.
LRU 회수 — 용량 상한(기본 512)에 도달하면 가장 오래된 요소가 자동으로 회수됩니다.
만료 시 자동 복구 — 만료된 요소에 접근할 때, 원래의 위치 지정자를 사용하여 자동으로 재검색을 시도합니다.
요소 ID는
act_click,act_input,dom_read,act_chain등 요소 참조가 필요한 모든 도구에 전달할 수 있습니다.target매개변수를 허용하는 모든 도구는dom_find를 먼저 호출할 필요 없이 위치 지정자 문자열(예:css:button.submit)을 직접 전달할 수 있습니다.
응답 형식
모든 도구(state_screenshot 제외)는 통합된 JSON 봉투를 반환합니다:
// 成功
{"ok": true, "data": ...}
// 失败
{"ok": false, "error": "error message"}state_screenshot은 스크린샷 크기가 허용 범위 내일 경우 MCP Image 객체를 직접 반환하며, 800KB를 초과할 경우 파일 경로를 반환합니다.
관련 프로젝트
ruyiPage — 핵심 Firefox BiDi 자동화 라이브러리
ruyipage-skill — AI 자동화 분석 실행 Skill
Firefox 지문 브라우저 — Firefox 지문 환경 지원
아키텍처
python -m ruyipage_mcp
→ __main__.py → server.run()
→ 导入 tools/*.py(触发 @mcp.tool() 注册 34 个工具)
→ 注册 atexit 清理(退出时关闭 owned 浏览器)
→ mcp.run(transport="stdio")
ruyipage_mcp/
├── app.py # FastMCP("ruyipage-mcp") 单例
├── config.py # 环境变量配置
├── registries.py # SessionRegistry + ElementRegistry (LRU)
├── runtime.py # async/sync 桥接 + 响应封装 + 元素解析
├── server.py # 入口 + atexit 清理
└── tools/
├── session.py # 浏览器启动/接管/关闭
├── nav.py # 页面导航
├── dom.py # 元素查找/读取
├── act.py # 元素交互/动作链
├── state.py # 截图/PDF/Cookie/Storage
├── js.py # JS 执行/预加载脚本
├── net.py # 网络拦截/监听/采集
├── ctx.py # 标签页/模拟/事件
└── meta.py # 服务器状态ruyiPage는 동기식 라이브러리이며, MCP FastMCP는 asyncio 기반입니다. 모든 ruyiPage 호출은 asyncio.to_thread()를 통해 브릿지되어 MCP 이벤트 루프가 차단되지 않도록 합니다.
사용 선언
본 프로젝트는 ruyiPage의 사용 선언을 따르며, 합법적이고 규정을 준수하는 비영리 목적의 개인 연구 및 기술 교류 용도로만 제한됩니다.
라이선스
BSD-3-Clause
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server paired with a Firefox extension that enables LLM clients to control the user's browser, supporting tab management, history search, and content reading.353MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that enables browser automation through standardized MCP clients, supporting features like navigation, element interaction, and screenshots across Chrome, Firefox, and Edge browsers.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP Server that enables AI assistants to interact with your local browsers.55MIT
- AlicenseCqualityCmaintenanceEnables AI assistants to read and drive a real, logged-in Firefox browser, including tabs, cookies, history, and site interactions, all through the Model Context Protocol.5216 npmMIT