Node Mantis
chính thứcTự động hóa web: mô tả tác vụ trên website bằng tiếng Anh thông thường, Node Mantis thao tác trên trang web trong trình duyệt thực và trả về dữ liệu có cấu trúc.
Bạn có thể làm gì với Node Mantis MCP?
- Thực hiện tác vụ trên website — Nêu mục tiêu bằng ngôn ngữ thông thường, Node Mantis sẽ nhấp, nhập liệu và điền biểu mẫu trong trình duyệt thực.
- Trả về dữ liệu có cấu trúc — Cung cấp JSON Schema và nhận kết quả tác vụ dưới dạng dữ liệu khớp với cấu trúc đó.
- Đọc một trang duy nhất — Dùng
retrieve_datađể trích xuất thông tin cụ thể từ một URL mà không thay đổi nội dung nào. - Quản lý tác vụ chạy lâu — Kiểm tra tiến độ hoặc dừng tác vụ chạy nền bằng
get_taskvàcancel_task. - Không đưa bí mật vào cuộc trò chuyện — Tham chiếu các giá trị đã lưu bằng
<secret:NAME>để mật khẩu và mã không bao giờ xuất hiện trong cuộc trò chuyện.
Tài liệu
Máy chủ MCP
Node Mantis bao gồm một máy chủ Model Context Protocol (MCP). Thêm máy chủ này vào một trợ lý AI hỗ trợ MCP, chẳng hạn như Claude Code, Claude Desktop, Cursor, VS Code hoặc Codex, để trợ lý có thể thực hiện các tác vụ trên trang web thay bạn: trợ lý mô tả tác vụ, Node Mantis thao tác trên trang web bằng trình duyệt thực và trả về kết quả dưới dạng dữ liệu có cấu trúc.
Thêm máy chủ vào tác nhân lập trình hoặc trợ lý của bạn để có thể:
- Thực hiện tác vụ trên trang web. Đưa ra mục tiêu bằng ngôn ngữ thông thường và Node Mantis thao tác trên trang web như người dùng thực: nhấp, nhập và xử lý biểu mẫu, danh sách thả xuống cũng như bộ chọn ngày.
- Nhận kết quả có cấu trúc. Cung cấp JSON Schema và Node Mantis trả về kết quả dưới dạng dữ liệu phù hợp với schema đó.
- Chạy tác vụ dài trong nền. Tác vụ mất vài phút vẫn tiếp tục chạy trong khi trợ lý kiểm tra, báo cáo tiến độ hoặc hủy tác vụ.
Máy chủ nằm trong gói node-mantis trên npm và PyPI, nên không cần cài đặt riêng. Trợ lý khởi chạy máy chủ bằng một lệnh, thông qua Node.js:
npx -y node-mantis mcp
hoặc thông qua Python với uv:
uvx node-mantis mcp
Cả hai đều cung cấp cho trợ lý cùng một bộ công cụ. Bạn cần Node.js hoặc Python, Google Chrome và khóa API từ bảng điều khiển. Nếu chưa cài Chrome, tác vụ đầu tiên sẽ tải Chrome for Testing.
Thêm vào trợ lý
Mỗi trợ lý lưu danh sách máy chủ MCP trong phần cài đặt. Bạn thêm một mục cho Node Mantis, bằng một lệnh hoặc bằng cách chỉnh sửa tệp cài đặt của trợ lý; trợ lý sẽ tự khởi chạy máy chủ bất cứ khi nào cần. Có ba bước:
- Sao chép khóa API từ bảng điều khiển.
- Thêm mục bên dưới vào trợ lý. Vị trí thêm tùy thuộc vào trợ lý; xem bảng và các phần tiếp theo.
- Khởi động lại trợ lý và kiểm tra xem máy chủ có hoạt động không.
Hầu hết trợ lý đều đọc cùng một mục JSON. Với Node.js:
{
"mcpServers": {
"node-mantis": {
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Với Python:
{
"mcpServers": {
"node-mantis": {
"command": "uvx",
"args": ["node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Mục này gồm ba phần:
node-mantislà tên trợ lý hiển thị cho máy chủ. Bạn có thể đổi tên.commandvàargslà cách trợ lý khởi chạy máy chủ. Dùng phiên bản Node.js hoặc Python; cả hai đều cung cấp cho trợ lý cùng một bộ công cụ.envchứa các cài đặt mà trợ lý truyền cho máy chủ khi khởi chạy. Thay phần giữ chỗ bằng khóa API của bạn. Nếu bạn đã lưu khóa bằngnodemantis configure, có thể bỏenv.
Nếu tệp cài đặt đã có phần mcpServers, hãy thêm mục node-mantis vào bên trong, cạnh các mục khác, thay vì dán thêm một mcpServers thứ hai.
| Trợ lý | Vị trí thêm mục |
|---|---|
| Claude Code | Một lệnh trong terminal. |
| Claude Desktop | claude_desktop_config.json, mở từ Settings. |
| Cursor | ~/.cursor/mcp.json cho mọi dự án hoặc .cursor/mcp.json trong một dự án. |
| VS Code | .vscode/mcp.json trong workspace. |
| Codex | Một lệnh trong terminal hoặc ~/.codex/config.toml. |
Claude Code
Chạy một trong các lệnh sau trong terminal. Với Node.js:
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Với Python:
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
Sau đó, claude mcp list sẽ hiển thị node-mantis là đã kết nối.
Claude Desktop
Mở Settings, rồi chọn Developer, sau đó chọn Edit Config. Thao tác này mở claude_desktop_config.json, được lưu tại ~/Library/Application Support/Claude/ trên macOS và tại %APPDATA%\Claude\ trên Windows. Thêm mục JSON ở trên, lưu tệp rồi khởi động lại ứng dụng.
Cursor
Thêm mục JSON ở trên vào ~/.cursor/mcp.json để dùng trong mọi dự án, hoặc vào .cursor/mcp.json bên trong một dự án. Tạo tệp nếu tệp chưa tồn tại.
VS Code
VS Code dùng servers thay vì mcpServers. Thêm nội dung sau vào .vscode/mcp.json trong workspace:
{
"servers": {
"node-mantis": {
"type": "stdio",
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Với Python, đặt command thành uvx và args thành ["node-mantis", "mcp"].
Codex
Chạy một trong các lệnh sau trong terminal. Với Node.js:
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Với Python:
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
Hoặc chỉnh sửa ~/.codex/config.toml. Giới hạn khởi động dài hơn giúp lần khởi chạy đầu tiên có đủ thời gian tải gói xuống:
[mcp_servers.node-mantis]
command = "npx"
args = ["-y", "node-mantis", "mcp"]
startup_timeout_sec = 60
[mcp_servers.node-mantis.env]
NODEMANTIS_API_KEY = "sk_live_<copy-from-dashboard>"
Với Python, đặt command thành "uvx" và args thành ["node-mantis", "mcp"].
Python không dùng uv
Các ví dụ Python ở trên dùng uv, công cụ tải gói từ PyPI trong lần sử dụng đầu tiên. Nếu không dùng uv, hãy cài gói một lần bằng python -m pip install node-mantis và dùng nodemantis làm lệnh với mcp là đối số duy nhất:
{
"mcpServers": {
"node-mantis": {
"command": "nodemantis",
"args": ["mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Kiểm tra xem máy chủ có hoạt động không
Sau khi khởi động lại, trợ lý sẽ liệt kê node-mantis trong số các máy chủ MCP cùng với bốn công cụ. Sau đó, hãy yêu cầu trợ lý thực hiện một tác vụ, chẳng hạn:
Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.
Trợ lý gọi run_task và trả lời bằng những gì tác vụ tìm được. Nếu không, hãy xem Khắc phục sự cố.
Windows
Nếu trợ lý không thể khởi chạy trực tiếp npx, hãy chạy thông qua cmd:
{
"mcpServers": {
"node-mantis": {
"command": "cmd",
"args": ["/c", "npx", "-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Công cụ
| Công cụ | Mô tả |
|---|---|
run_task | Thực hiện tác vụ trên trang web dựa trên mục tiêu bằng ngôn ngữ thông thường: điều hướng, nhấp, nhập, điền biểu mẫu và đọc kết quả. |
retrieve_data | Mở một trang và đọc dữ liệu trên đó mà không thay đổi nội dung. |
get_task | Chờ tác vụ và trả về trạng thái, tiến độ mới nhất cùng kết quả. |
cancel_task | Dừng tác vụ đang chạy và đóng trình duyệt. |
Mỗi tác vụ chạy trong một phiên trình duyệt mới riêng, không có thông tin đăng nhập được lưu và phiên sẽ đóng khi tác vụ kết thúc.
run_task
Hoạt động giống run trong SDK. Chỉ cần goal.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
goal | string | bắt buộc | Việc cần hoàn thành, mô tả bằng ngôn ngữ thông thường và kèm mọi chi tiết cần thiết để hoàn tất. |
start_url | string | không có | Trang cần mở đầu tiên. Nếu không cung cấp, tác vụ sẽ tự tìm cách thực hiện dựa trên mục tiêu. |
result_schema | object | tùy ý | JSON Schema cho dữ liệu cần trả về. Kết quả sẽ chứa dữ liệu theo cấu trúc đó. |
effort | low | medium | high | xhigh | trung bình | Mức năng lực cần sử dụng. Mức cao hơn có thể xử lý các trang khó hơn và tốn kém hơn. |
max_cost_usd | number | không giới hạn | Ngân sách USD được kiểm tra giữa các bước. Bước cuối có thể khiến tổng chi tiêu vượt quá mức này. |
max_steps | integer | 30 | Số bước tối đa trước khi tác vụ dừng. |
timeout_seconds | integer | 300 | Giới hạn thời gian tổng thể cho tác vụ. |
secrets | string[] | không có | Tên các giá trị riêng tư mà tác vụ có thể nhập. Mỗi giá trị được đọc từ NODEMANTIS_SECRET_<NAME> trong môi trường của máy chủ. |
use_proxy | boolean | false | Định tuyến trình duyệt qua proxy được cấu hình trong môi trường của máy chủ. |
show_browser | boolean | false | Hiển thị cửa sổ trình duyệt trong khi tác vụ chạy. |
retrieve_data
Hoạt động giống retrieve trong SDK. Thay vào đó, hãy dùng run_task khi cần nhấp, nhập hoặc mở nhiều trang mới lấy được dữ liệu.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
url | string | bắt buộc | Trang cần đọc. |
prompt | string | bắt buộc | Nội dung cần đọc trên trang. |
result_schema | object | tùy ý | JSON Schema mô tả cấu trúc dữ liệu trả về. |
effort | low | medium | high | xhigh | trung bình | Mức năng lực cần sử dụng để đọc trang. |
use_proxy | boolean | false | Định tuyến trình duyệt qua proxy được cấu hình trong môi trường của máy chủ. |
show_browser | boolean | false | Hiển thị cửa sổ trình duyệt trong khi đọc trang. |
get_task
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
task_id | string | bắt buộc | task_id do run_task hoặc retrieve_data trả về. |
wait_seconds | integer | 45 | Thời gian chờ tối đa để tác vụ hoàn tất trước khi trả lời. Giá trị 0 sẽ trả lời ngay lập tức. |
cancel_task
Nhận một task_id. Tác vụ đã hoàn tất sẽ không bị thay đổi.
Tác vụ dài
Một tác vụ trên trang web có thể mất nhiều thời gian hơn mức trợ lý sẵn sàng chờ cho một lần gọi công cụ. Vì vậy, run_task và retrieve_data chờ tối đa 45 giây. Nếu tác vụ hoàn tất trong khoảng thời gian đó, lệnh gọi sẽ trả về kết quả. Nếu không, lệnh gọi trả về trạng thái running cùng với task_id, còn tác vụ tiếp tục chạy trong nền:
{
"task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
"tool": "run_task",
"status": "running",
"elapsed_seconds": 45,
"progress": {
"step": 6,
"max_steps": 30,
"message": "Step 6/30: The cart shows one book. — click(\"Checkout\")"
},
"next_step": "Still running. Call get_task with task_id \"task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10\" to wait for the result, or cancel_task to stop it."
}
Sau đó, trợ lý gọi get_task với mã đó cho đến khi trạng thái là succeeded, failed hoặc cancelled:
{
"task_id": "task_6f0c2a54-8f0e-4f0a-9d2b-2f6c1f1f8a10",
"tool": "run_task",
"status": "succeeded",
"elapsed_seconds": 71,
"result": {
"ok": true,
"reason": "Added the book to the cart and read the cart.",
"value": { "title": "Journey to the Center of the Earth", "quantity": 1 },
"steps": 9,
"cost_usd": 0.04,
"trace_id": "op_1794979105280_5c3e8996"
}
}
Tác vụ failed vẫn trả về những gì đã tìm được cùng lý do, để trợ lý có thể điều chỉnh mục tiêu và thử lại. Tác vụ đã hoàn tất được lưu trong một giờ. Tác vụ thuộc về máy chủ đang chạy: chúng sẽ dừng khi trợ lý đóng máy chủ.
Bí mật
Mật khẩu và mã dùng một lần không bao giờ đi qua cuộc trò chuyện. Đặt từng giá trị trong môi trường của máy chủ dưới dạng NODEMANTIS_SECRET_<NAME>, cạnh khóa API trong env. Trợ lý chỉ truyền các tên trong secrets và tham chiếu đến giá trị trong mục tiêu bằng <secret:NAME>. Xem Bí mật.
Proxy
Để định tuyến trình duyệt của tác vụ qua proxy, hãy đặt NODEMANTIS_PROXY trong môi trường của máy chủ và yêu cầu tác vụ truyền use_proxy. Danh sách proxy và tệp hoạt động như mô tả trong Cấu hình proxy.
Tùy chọn máy chủ
Thêm các mục này sau mcp trong danh sách args.
| Tham số | Kiểu | Mặc định | Mô tả |
|---|---|---|---|
--wait-seconds <n> | number | 45 | Thời gian một lần gọi công cụ chờ tác vụ trước khi trả về mã tác vụ. Giảm giá trị này nếu trợ lý của bạn từ bỏ các lần gọi công cụ sớm hơn. |
--max-tasks <n> | number | 4 | Số tác vụ có thể chạy cùng lúc. |
-H, --headed | flag | headless | Hiển thị cửa sổ trình duyệt cho mọi tác vụ, trừ khi một lần gọi công cụ đặt show_browser. |
Khắc phục sự cố
- Trợ lý báo chưa cấu hình khóa API. Thêm
NODEMANTIS_API_KEYvàoenvcủa máy chủ hoặc chạynodemantis configuremột lần rồi thử lại. Không cần khởi động lại sau khi chạyconfigure. - Máy chủ hết thời gian chờ trong lần khởi chạy đầu tiên. Lần khởi chạy
npxđầu tiên sẽ tải gói xuống. Cài đặt gói một lần bằngnpm install -g node-mantisrồi khởi chạy lệnh đã cài đặt:{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - Không thể khởi chạy tác vụ. Chạy
nodemantis doctorđể kiểm tra quá trình cài đặt, trình duyệt và khóa API.