Node Mantis

chính thức

Tự độ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_task và 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:

  1. Sao chép khóa API từ bảng điều khiển.
  2. 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.
  3. 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-mantis là tên trợ lý hiển thị cho máy chủ. Bạn có thể đổi tên.
  • command và args là 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ụ.
  • env chứ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ằng nodemantis 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 CodeMột lệnh trong terminal.
Claude Desktopclaude_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.
CodexMộ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_taskThự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_dataMở một trang và đọc dữ liệu trên đó mà không thay đổi nội dung.
get_taskChờ tác vụ và trả về trạng thái, tiến độ mới nhất cùng kết quả.
cancel_taskDừ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ểuMặc địnhMô tả
goalstringbắt buộcViệ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_urlstringkhô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_schemaobjecttù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 đó.
effortlow | medium | high | xhightrung bìnhMứ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_usdnumberkhông giới hạnNgâ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_stepsinteger30Số bước tối đa trước khi tác vụ dừng.
timeout_secondsinteger300Giới hạn thời gian tổng thể cho tác vụ.
secretsstring[]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_proxybooleanfalseĐị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_browserbooleanfalseHiể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ểuMặc địnhMô tả
urlstringbắt buộcTrang cần đọc.
promptstringbắt buộcNội dung cần đọc trên trang.
result_schemaobjecttùy ýJSON Schema mô tả cấu trúc dữ liệu trả về.
effortlow | medium | high | xhightrung bìnhMức năng lực cần sử dụng để đọc trang.
use_proxybooleanfalseĐị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_browserbooleanfalseHiển thị cửa sổ trình duyệt trong khi đọc trang.

get_task

Tham sốKiểuMặc địnhMô tả
task_idstringbắt buộctask_id do run_task hoặc retrieve_data trả về.
wait_secondsinteger45Thờ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ểuMặc địnhMô tả
--wait-seconds <n>number45Thờ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>number4Số tác vụ có thể chạy cùng lúc.
-H, --headedflagheadlessHiể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_KEY vào env của máy chủ hoặc chạy nodemantis configure một lần rồi thử lại. Không cần khởi động lại sau khi chạy configure.
  • 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ằng npm install -g node-mantis rồ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.