de en es ja ko ru zh

ruyipage-mcp

Name: ruyipage-mcp
Author: neverl805

by neverl805

Overview Schema Source Related Servers Discussions Admin

Python

Local

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
설정 파일을 찾을 수 없는 경우 내장 기본값 사용

설정 항목	타입	기본값	설명
`browser_path`	string	`E:\ruyi_firefox\firefox.exe`	Firefox 실행 파일 경로
`disable_run_js`	bool	`false`	`true`로 설정 시 `js_run` 도구 비활성화
`disable_extensions`	bool	`false`	`true`로 설정 시 확장 프로그램 관련 기능 비활성화
`browser_path_whitelist`	list	`[]` (모든 경로 허용)	허용된 브라우저 경로 목록
`max_elements`	int	`512`	세션당 요소 레지스트리 LRU 용량
`event_buffer_size`	int	`500`	BiDi 이벤트 버퍼 크기
`wait_timeout_ceiling`	int	`60`	모든 대기 관련 도구의 최대 타임아웃(초)

환경 변수 오버라이드

환경 변수는 설정 파일보다 우선순위가 높으며, CI 또는 임시 오버라이드 시나리오에 적합합니다:

환경 변수	대응 설정 항목
`RUYIPAGE_MCP_BROWSER_PATH`	`browser_path`
`RUYIPAGE_MCP_DISABLE_RUN_JS`	`disable_run_js` (`1` = true)
`RUYIPAGE_MCP_DISABLE_EXTENSIONS`	`disable_extensions` (`1` = true)
`RUYIPAGE_MCP_BROWSER_PATH_WHITELIST`	`browser_path_whitelist` (쉼표로 구분)
`RUYIPAGE_MCP_MAX_ELEMENTS`	`max_elements`
`RUYIPAGE_MCP_EVENT_BUFFER_SIZE`	`event_buffer_size`
`RUYIPAGE_MCP_WAIT_TIMEOUT_CEILING`	`wait_timeout_ceiling`
`RUYIPAGE_MCP_CONFIG`	설정 파일 경로 지정

도구 목록 (34개)

session — 브라우저 생명 주기

도구	설명
`session_launch`	새 Firefox 브라우저 시작. 사용자 지정 포트, 헤드리스 모드, 프라이빗 모드, XPath Picker, 창 크기 등 지원
`session_attach`	`host:port`를 통해 실행 중인 Firefox 연결
`session_auto_attach`	프로세스 특성에 따라 Firefox / ADS / FlowerBrowser 자동 탐지 및 연결
`session_quit`	브라우저 세션 종료. `owned` 세션은 프로세스를 직접 종료하고, `attached` 세션은 연결만 해제

일반적인 흐름:

session_launch(port=9222)
  → 操作页面...
  → session_quit()

# 接管已打开的指纹浏览器
session_auto_attach(latest_tab=true)
  → 操作页面...
  → session_quit()  # 仅释放连接，浏览器继续运行

nav — 페이지 탐색

도구	설명
`nav_get`	URL 열기, `complete` / `interactive` / `none` 대기 전략 지원
`nav_back`	뒤로 가기
`nav_forward`	앞으로 가기
`nav_refresh`	새로 고침
`nav_info`	현재 페이지의 URL, 제목, ready state 가져오기

dom — 요소 검색 및 읽기

도구	설명
`dom_find`	단일 요소 검색, `element_id` 반환. `#id`, `css:`, `xpath:`, `text:`, `tag:` 위치 지정 지원
`dom_find_all`	일치하는 모든 요소 검색, 목록 반환 (기본 상한 20, 최대 100)
`dom_read`	요소 속성 읽기: `text` / `html` / `inner_html` / `outer_html` / `value` / `attrs` / `rect` / `all`
`dom_query_in`	기존 요소 내부에서 하위 요소 검색
`dom_wait_for`	요소가 나타날 때까지 대기 (타임아웃 포함)
`dom_release`	요소 핸들 해제, 레지스트리 공간 회수

위치 지정자 형식:

형식	예시	설명
`#id`	`#search-box`	ID 선택자
`css:`	`css:div.card > a`	CSS 선택자
`xpath:`	`xpath://button[text()='Login']`	XPath
`text:`	`text:로그인`	텍스트 일치
`tag:`	`tag:input`	태그 이름

act — 요소 상호작용

도구	설명
`act_click`	요소 클릭. 좌클릭 / 우클릭 / 더블 클릭 지원, JS 클릭 옵션. 기본적으로 네이티브 BiDi 동작 사용 (`isTrusted=true`)
`act_input`	텍스트 입력. 네이티브 BiDi 키보드 입력, 기존 내용 삭제 옵션. JS 폴백 지원
`act_simple`	간단한 작업: `hover` / `clear` / `focus` / `scroll_into_view`
`act_chain`	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 — 페이지 상태

도구	설명
`state_screenshot`	스크린샷. 전체 페이지 스크린샷, 요소 스크린샷, 파일 저장 지원. 자동 압축, 초대형 이미지 자동 파일 저장
`state_save_pdf`	현재 페이지를 PDF로 저장
`state_cookies`	쿠키 관리: `get` / `set` / `delete`. 이름/도메인별 필터링 지원
`state_storage`	localStorage / sessionStorage 관리: `items` / `get` / `set` / `delete` / `clear`

js — JavaScript 실행

도구	설명
`js_run`	페이지에서 JS 코드 실행. 표현식 평가 (`as_expr=true`) 또는 함수 본문 실행 가능. 환경 변수를 통해 비활성화 가능
`js_preload`	preload 스크립트 관리: `add` (페이지 로드 전마다 주입) / `remove`

net — 네트워크 제어

도구	설명
`net_intercept`	요청 가로채기: `start` → `wait_and_resolve` (continue/mock/fail) → `stop`
`net_listen`	네트워크 모니터링: `start` → `wait` (URL/method별 필터링) → `stop`
`net_collector`	데이터 수집기: `add` → `get` (request_id별 요청/응답 본문 가져오기) → `remove`
`net_headers`	추가 요청 헤더 설정/삭제
`net_cache`	캐시 동작 설정: `default` (일반 캐시) / `bypass` (강제 재요청)

요청 가로채기 일반적인 흐름:

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 — 컨텍스트 관리

도구	설명
`ctx_tabs`	탭 관리: `list` / `create` / `close` / `activate` / `reload`
`ctx_emulation`	기기 에뮬레이션: 지리적 위치, 시간대, 언어, 모바일 기기 프리셋, 오프라인 모드, JS 스위치
`ctx_events`	BiDi 이벤트 구독: `page.events` / `page.navigation` / `page.downloads` 통합 관리

에뮬레이션 작업 예시:

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 — 서버 정보

도구	설명
`ruyipage_describe_capabilities`	현재 서버 상태 반환: 활성 세션, 요소 수, 설정 스위치, 도구 네임스페이스 목록

핵심 개념

세션 관리

각 브라우저 연결은 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를 초과할 경우 파일 경로를 반환합니다.

아키텍처

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

This server cannot be deployed

Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
Firecrawl MCP Server A
io.github.firecrawl
MCP server for Firecrawl — web search, scraping, and biomedical/arXiv paper search.
Browser Automation Web Scraping Search
317,570
sncro A
io.github.scottconfusedgorilla
Live browser debugging for AI assistants — DOM, console, network via MCP.
Browser Automation Developer Tools Monitoring
2
Mercado PagoOAuth
com.mercadopago.mcp
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Finance E-commerce & Retail App Automation
2

Related MCP Servers

Browser Control MCP
Browser Automation Agent Orchestration
eyalzh
A
license
Not graded
quality
C
maintenance
An 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.
Updated a month ago (2026-08-23 18:44 UTC)
13 npm
327
MIT
MCP Selenium Server
sapangupta63
A
license
Not graded
quality
D
maintenance
A 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.
Updated a year ago (2025-07-28 10:36 UTC)
1,195 npm
MIT
mcp-browser-kit
Browser Automation Web Scraping App Automation
ndthanhdev
A
license
Not graded
quality
A
maintenance
An MCP Server that enables AI assistants to interact with your local browsers.
Updated 3 days ago (2026-10-05 13:52 UTC)
3,059 npm
55
MIT
FoxBridge MCP
Browser Automation Web Scraping
sinamohsenifar
A
license
C
quality
C
maintenance
Enables 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.
Updated 3 months ago (2026-07-06 17:16 UTC)
52
15 npm
MIT

ruyipage-mcp

특징

설치

사전 요구 사항

소스 코드에서 설치

AI에게 GitHub 링크를 직접 제공하여 설치를 요청할 수도 있습니다.

설정

Claude Code

Cursor / 기타 MCP 클라이언트

독립 실행

설정

설정 파일

환경 변수 오버라이드

도구 목록 (34개)

session — 브라우저 생명 주기

nav — 페이지 탐색

dom — 요소 검색 및 읽기

act — 요소 상호작용

state — 페이지 상태

js — JavaScript 실행

net — 네트워크 제어

ctx — 컨텍스트 관리

meta — 서버 정보

핵심 개념

세션 관리

요소 레지스트리

응답 형식

관련 프로젝트

아키텍처

사용 선언

라이선스

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Browser Control MCP

MCP Selenium Server

mcp-browser-kit

FoxBridge MCP