Node Mantis

resmi

Otomatisasi web: jelaskan tugas di situs web dalam bahasa Inggris sederhana, Node Mantis bekerja melalui halaman web di browser sungguhan dan mengembalikan data terstruktur.

Apa yang bisa Anda lakukan dengan Node Mantis MCP?

  • Jalankan tugas di situs web — Berikan tujuan dalam bahasa Inggris sederhana, lalu Node Mantis mengeklik, mengetik, dan mengisi formulir di browser sungguhan.
  • Kembalikan data terstruktur — Berikan JSON Schema dan dapatkan hasil tugas dalam bentuk data yang sesuai dengan struktur tersebut.
  • Baca satu halaman — Gunakan retrieve_data untuk mengekstrak informasi tertentu dari satu URL tanpa mengubah apa pun.
  • Kelola tugas yang berjalan lama — Periksa progres atau hentikan tugas latar belakang dengan get_task dan cancel_task.
  • Jauhkan rahasia dari obrolan — Rujuk nilai yang tersimpan sebagai <secret:NAME> agar kata sandi dan kode tidak pernah muncul dalam percakapan.

Dokumentasi

Server MCP

Node Mantis menyertakan server Model Context Protocol (MCP). Tambahkan server ini ke asisten AI yang mendukung MCP, seperti Claude Code, Claude Desktop, Cursor, VS Code, atau Codex, dan asisten tersebut dapat menjalankan tugas di situs web untuk Anda: asisten menjelaskan tugasnya, Node Mantis menjelajahi situs melalui browser sungguhan, lalu mengembalikan hasilnya sebagai data terstruktur.

Dengan menambahkan server ini ke agen coding atau asisten Anda, Anda dapat:

  • Menjalankan tugas di situs web. Berikan tujuan dalam bahasa sehari-hari dan Node Mantis akan menjelajahi situs seperti pengguna sungguhan: mengeklik, mengetik, serta menangani formulir, menu dropdown, dan pemilih tanggal.
  • Mendapatkan hasil terstruktur. Berikan JSON Schema dan Node Mantis akan mengembalikan hasil sebagai data yang sesuai dengannya.
  • Menjalankan tugas panjang di latar belakang. Tugas yang memerlukan waktu beberapa menit akan terus berjalan sementara asisten Anda memeriksa statusnya, melaporkan progres, atau membatalkannya.

Server ini merupakan bagian dari paket node-mantis di npm dan PyPI, jadi tidak perlu menginstal apa pun secara terpisah. Asisten Anda menjalankannya dengan satu perintah melalui Node.js:

npx -y node-mantis mcp

atau melalui Python dengan uv:

uvx node-mantis mcp

Keduanya memberikan alat yang sama kepada asisten. Anda memerlukan Node.js atau Python, Google Chrome, dan kunci API dari dasbor. Jika Chrome belum terinstal, tugas pertama akan mengunduh Chrome for Testing.

Tambahkan ke asisten Anda

Setiap asisten menyimpan daftar server MCP di pengaturannya. Anda menambahkan satu entri untuk Node Mantis, baik dengan perintah maupun dengan mengedit file pengaturan asisten. Asisten akan menjalankan server itu sendiri setiap kali diperlukan. Ada tiga langkah:

  1. Salin kunci API dari dasbor.
  2. Tambahkan entri di bawah ini ke asisten Anda. Lokasinya bergantung pada asistennya; lihat tabel dan bagian berikut.
  3. Mulai ulang asisten dan periksa apakah berfungsi.

Sebagian besar asisten menggunakan entri JSON yang sama. Dengan Node.js:

{
  "mcpServers": {
    "node-mantis": {
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Dengan Python:

{
  "mcpServers": {
    "node-mantis": {
      "command": "uvx",
      "args": ["node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Entri ini terdiri dari tiga bagian:

  • node-mantis adalah nama server yang ditampilkan oleh asisten. Anda dapat mengubahnya.
  • command dan args menentukan cara asisten menjalankan server. Gunakan versi Node.js atau Python; keduanya memberikan alat yang sama kepada asisten.
  • env menyimpan pengaturan yang diteruskan asisten ke server saat menjalankannya. Ganti placeholder dengan kunci API Anda. Jika Anda sudah menyimpan kunci menggunakan nodemantis configure, Anda dapat menghilangkan env.

Jika file pengaturan sudah memiliki bagian mcpServers, tambahkan entri node-mantis di dalamnya bersama entri lainnya, alih-alih menempelkan mcpServers kedua.

AsistenLokasi entri
Claude CodeSatu perintah di terminal Anda.
Claude Desktopclaude_desktop_config.json, dibuka dari Settings.
Cursor~/.cursor/mcp.json untuk setiap proyek, atau .cursor/mcp.json di satu proyek.
VS Code.vscode/mcp.json di ruang kerja Anda.
CodexSatu perintah di terminal Anda, atau ~/.codex/config.toml.

Claude Code

Jalankan salah satu perintah berikut di terminal Anda. Dengan Node.js:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

Dengan Python:

claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

claude mcp list kemudian menampilkan node-mantis sebagai terhubung.

Claude Desktop

Buka Settings, lalu Developer, kemudian Edit Config. Ini akan membuka claude_desktop_config.json, yang disimpan di ~/Library/Application Support/Claude/ pada macOS dan di %APPDATA%\Claude\ pada Windows. Tambahkan entri JSON di atas, simpan file, lalu mulai ulang aplikasi.

Cursor

Tambahkan entri JSON di atas ke ~/.cursor/mcp.json agar dapat digunakan di setiap proyek, atau ke .cursor/mcp.json di dalam satu proyek. Buat file tersebut jika belum ada.

VS Code

VS Code menggunakan servers, bukan mcpServers. Tambahkan ini ke .vscode/mcp.json di ruang kerja Anda:

{
  "servers": {
    "node-mantis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Untuk Python, atur command ke uvx dan args ke ["node-mantis", "mcp"].

Codex

Jalankan salah satu perintah berikut di terminal Anda. Dengan Node.js:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp

Dengan Python:

codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp

Atau edit ~/.codex/config.toml. Batas waktu mulai yang lebih panjang memberi waktu bagi peluncuran pertama untuk mengunduh paket:

[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>"

Untuk Python, atur command ke "uvx" dan args ke ["node-mantis", "mcp"].

Python tanpa uv

Contoh Python di atas menggunakan uv, yang mengambil paket dari PyPI saat pertama kali digunakan. Tanpa uv, instal paket sekali dengan python -m pip install node-mantis dan gunakan nodemantis sebagai perintah dengan mcp sebagai satu-satunya argumennya:

{
  "mcpServers": {
    "node-mantis": {
      "command": "nodemantis",
      "args": ["mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Periksa apakah berfungsi

Setelah dimulai ulang, asisten akan mencantumkan node-mantis di antara server MCP-nya dengan empat alat. Kemudian, minta asisten menjalankan tugas, misalnya:

Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.

Asisten akan memanggil run_task dan menjawab dengan temuan tugas tersebut. Jika tidak, lihat Pemecahan masalah.

Windows

Jika asisten tidak dapat menjalankan npx secara langsung, jalankan melalui cmd:

{
  "mcpServers": {
    "node-mantis": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "node-mantis", "mcp"],
      "env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
    }
  }
}

Alat

AlatDeskripsi
run_taskMenjalankan tugas di situs web berdasarkan tujuan dalam bahasa sehari-hari: membuka halaman, mengeklik, mengetik, mengisi formulir, dan membaca hasilnya.
retrieve_dataMembuka satu halaman dan membaca datanya tanpa mengubah apa pun di halaman tersebut.
get_taskMenunggu tugas dan mengembalikan status, progres terbaru, serta hasilnya.
cancel_taskMenghentikan tugas yang sedang berjalan dan menutup browsernya.

Setiap tugas berjalan dalam sesi browser baru yang terpisah, tanpa login tersimpan, dan sesi ditutup saat tugas berakhir.

run_task

Berfungsi seperti run di SDK. Hanya goal yang wajib diisi.

ParameterTipeDefaultDeskripsi
goalstringwajibHal yang harus dilakukan, dijelaskan dalam bahasa sehari-hari dengan semua detail yang diperlukan untuk menyelesaikannya.
start_urlstringtidak adaHalaman yang dibuka terlebih dahulu. Jika tidak disertakan, tugas akan menentukan sendiri cara memulai berdasarkan tujuannya.
result_schemaobjectbebasJSON Schema untuk data yang akan dikembalikan. Hasilnya akan memuat data dalam bentuk tersebut.
effortlow | medium | high | xhighsedangBesarnya kemampuan yang digunakan. Upaya lebih tinggi dapat menangani halaman yang lebih sulit dan biayanya lebih besar.
max_cost_usdnumbertanpa batasAnggaran dalam USD yang diperiksa di antara langkah-langkah. Langkah terakhir dapat membuat total pengeluaran melampaui jumlah ini.
max_stepsinteger30Jumlah langkah maksimum sebelum tugas dihentikan.
timeout_secondsinteger300Batas waktu keseluruhan untuk tugas.
secretsstring[]tidak adaNama nilai privat yang dapat diketik oleh tugas. Setiap nilai dibaca dari NODEMANTIS_SECRET_<NAME> di lingkungan server.
use_proxybooleanfalseMengarahkan browser melalui proxy yang dikonfigurasi di lingkungan server.
show_browserbooleanfalseMenampilkan jendela browser saat tugas berjalan.

retrieve_data

Berfungsi seperti retrieve di SDK. Gunakan run_task sebagai gantinya jika untuk mendapatkan data perlu mengeklik, mengetik, atau membuka beberapa halaman.

ParameterTipeDefaultDeskripsi
urlstringwajibHalaman yang akan dibaca.
promptstringwajibHal yang akan dibaca dari halaman.
result_schemaobjectbebasJSON Schema untuk bentuk data yang dikembalikan.
effortlow | medium | high | xhighsedangBesarnya kemampuan yang digunakan untuk membaca halaman.
use_proxybooleanfalseMengarahkan browser melalui proxy yang dikonfigurasi di lingkungan server.
show_browserbooleanfalseMenampilkan jendela browser saat halaman dibaca.

get_task

ParameterTipeDefaultDeskripsi
task_idstringwajibtask_id yang dikembalikan oleh run_task atau retrieve_data.
wait_secondsinteger45Lama waktu menunggu tugas selesai sebelum memberikan jawaban. Nilai 0 akan langsung memberikan jawaban.

cancel_task

Menerima task_id. Tugas yang sudah selesai tidak akan diubah.

Tugas panjang

Tugas di situs web dapat berlangsung lebih lama daripada waktu tunggu yang disediakan asisten untuk satu pemanggilan alat. Karena itu, run_task dan retrieve_data menunggu hingga 45 detik. Jika tugas selesai dalam waktu tersebut, pemanggilan akan mengembalikan hasilnya. Jika tidak, pemanggilan akan mengembalikan status running beserta task_id, dan tugas akan terus berjalan di latar belakang:

{
  "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."
}

Asisten kemudian memanggil get_task dengan ID tersebut hingga statusnya menjadi succeeded, failed, atau 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"
  }
}

Tugas failed tetap mengembalikan temuan beserta alasannya, sehingga asisten dapat menyesuaikan tujuan dan mencoba lagi. Tugas yang selesai disimpan selama satu jam. Tugas berjalan di server yang sedang aktif: tugas akan berhenti saat asisten menutup server.

Rahasia

Kata sandi dan kode sekali pakai tidak pernah melewati percakapan. Atur setiap nilai di lingkungan server sebagai NODEMANTIS_SECRET_<NAME>, bersama kunci API di env. Asisten hanya meneruskan nama-nama di secrets dan merujuk nilai dalam tujuan sebagai <secret:NAME>. Lihat Rahasia.

Proxy

Untuk mengarahkan browser tugas melalui proxy, atur NODEMANTIS_PROXY di lingkungan server dan minta tugas meneruskan use_proxy. Daftar dan file proxy berfungsi seperti yang dijelaskan di Konfigurasi proxy.

Opsi server

Tambahkan opsi berikut setelah mcp di dalam daftar args.

ParameterTipeDefaultDeskripsi
--wait-seconds <n>number45Lama waktu pemanggilan alat menunggu tugas sebelum mengembalikan ID tugas. Kurangi nilainya jika asisten Anda lebih cepat menyerah saat menunggu pemanggilan alat.
--max-tasks <n>number4Jumlah tugas yang dapat berjalan secara bersamaan.
-H, --headedflagheadlessMenampilkan jendela browser untuk setiap tugas, kecuali jika pemanggilan alat mengatur show_browser.

Pemecahan masalah

  • Asisten melaporkan bahwa kunci API belum dikonfigurasi. Tambahkan NODEMANTIS_API_KEY ke env server, atau jalankan nodemantis configure sekali, lalu coba lagi. Tidak perlu memulai ulang setelah configure.
  • Server mengalami timeout saat pertama kali dijalankan. Peluncuran npx pertama mengunduh paket. Instal sekali dengan npm install -g node-mantis, lalu jalankan perintah yang sudah terinstal:
    {
      "mcpServers": {
        "node-mantis": {
          "command": "nodemantis",
          "args": ["mcp"]
        }
      }
    }
    
  • Tugas gagal dimulai. Jalankan nodemantis doctor untuk memeriksa instalasi, browser, dan kunci API.