Content
# ruyi-mcp
[English](README_EN.md)
[](https://github.com/Facetomyself/ruyi-mcp/actions/workflows/ci.yml)
[](https://pypi.org/project/ruyiPage/1.2.46/)
[](LICENSE)
`ruyi-mcp` is a community MCP Server for [ruyiPage](https://github.com/LoseNine/ruyipage), providing Firefox / WebDriver BiDi browser automation, runtime observation, fingerprint analysis, Trace, network interception, and human behavior simulation capabilities to MCP clients such as Claude Code, Codex, and Cursor.
This project is independently maintained by the community and is not an official integration, nor does it represent the official ruyiPage project.
## Core Capabilities
- Provides 56 MCP tools covering page lifecycle, script and runtime analysis, network crawling, Cookie, DOM, Frame, request/response interception, WebSocket, browser fingerprinting, human behavior simulation, Session export, and Trace.
- Node.js MCP Server calls ruyiPage through a resident Python JSON-RPC Bridge.
- The repository tracks TypeScript build artifacts; after dependency installation, the MCP Host can be started directly from `build/src/index.js`.
## Environment Requirements
- Node.js 20 or higher.
- Python 3.10 or higher; currently verified on Python 3.13.
- `ruyiPage==1.2.46`, and Firefox installed or compatible with ruyiPage.
## Compatibility
| ruyi-mcp | ruyiPage | Node.js | Python | Verified Environment |
|----------|----------|---------|--------|----------------------|
| `v0.1.1` | `1.2.46` | `>=20` | `>=3.10` | GitHub Actions: Node.js 20 + Python 3.13 |
The repository uses precise version locking for `ruyiPage`. Before upgrading compatible versions, the Bridge contract, TypeScript build, and 56 tools stdio smoke test will be re-executed.
## Installation
```bash
git clone https://github.com/Facetomyself/ruyi-mcp.git
cd ruyi-mcp
npm ci
python -m pip install -r requirements.txt
python -m ruyipage install
npm run check
```
## Environment Variables
- `RUYI_MCP_PYTHON`: The Python executable used by the Node Bridge. Defaults to `python` on Windows and `python3` on other platforms.
- `RUYI_FIREFOX_PATH`: The path to the Firefox executable. If not set, the Bridge will check the reverse_ENV portable directory, Windows RuyiPage browser cache, and `PATH` in sequence.
## Firefox Runtime Selection
- `ruyi_trace_*` exposes the WebDriver BiDi JSON Trace in RuyiPage's memory, not the Firefox kernel DOMTrace.
- The installer for ruyiPage `1.2.46` still uses the `151-ruyi` runtime; to verify credentialed HTTP / SOCKS5 proxy, download the upstream [`151-proxy`](https://github.com/LoseNine/ruyipage/releases/tag/151-proxy) release and explicitly point to the extracted `firefox.exe` via `RUYI_FIREFOX_PATH`.
- This repository does not distribute Firefox binaries, browser Profiles, or DOMTrace kernels.
## MCP Configuration
```json
{
"mcpServers": {
"ruyi-mcp": {
"command": "node",
"args": ["/absolute/path/to/ruyi-mcp/build/src/index.js"],
"env": {
"RUYI_MCP_PYTHON": "/absolute/path/to/python",
"RUYI_FIREFOX_PATH": "/absolute/path/to/firefox"
}
}
}
}
```
## Usage in reverse_ENV
`ruyi-mcp` is maintained as a public Git submodule in reverse_ENV. To use it for the first time, execute:
```powershell
git -C "D:\reverse_ENV" submodule update --init "mcp/ruyi-mcp"
& "D:\reverse_ENV\tools\node\npm.cmd" --prefix "D:\reverse_ENV\mcp\ruyi-mcp" ci
```
The main repository fixes the verified version through gitlink; when modifying this project, verify, commit, and push in the submodule first, then update the gitlink in the reverse_ENV main repository.
## Verification
```bash
npm run check
npm audit --audit-level=high
```
`npm run check` performs TypeScript type checking, Python syntax checking, Bridge contract, build, and 56 tools stdio smoke testing; this command does not start Firefox.
## Data and Credential Boundaries
- Credentials, Cookies, proxy keys, browser Profiles, crawled data, or runtime artifacts must not be submitted in Git.
- Python and Firefox paths must be provided through environment variables or runtime discovery mechanisms; absolute paths of developers must not be submitted.
## License
MIT, see [LICENSE](LICENSE).
