Node Mantis
resmiWeb otomasyonu: Bir web sitesi görevini sade bir İngilizceyle açıklayın; Node Mantis gerçek bir tarayıcıda web sayfası üzerinde çalışır ve yapılandırılmış veriler döndürür.
Node Mantis MCP ile neler yapabilirsiniz?
- Web sitesi görevlerini çalıştırın — Hedefi sade bir dille belirtin; Node Mantis gerçek bir tarayıcıda tıklar, metin girer ve formları doldurur.
- Yapılandırılmış veriler döndürün — Bir JSON Schema sağlayın ve görev sonucunu bu yapıya uygun veri olarak alın.
- Tek bir sayfayı okuyun — Hiçbir şeyi değiştirmeden tek bir URL'den belirli bilgileri çıkarmak için
retrieve_datakullanın. - Uzun süren görevleri yönetin —
get_taskvecancel_taskile arka plan görevlerinin ilerlemesini kontrol edin veya onları durdurun. - Gizli bilgileri sohbetten uzak tutun — Parolaların ve kodların konuşma üzerinden asla aktarılmaması için kayıtlı değerleri
<secret:NAME>olarak belirtin.
Dokümantasyon
MCP sunucusu
Node Mantis, bir Model Context Protocol (MCP) sunucusu içerir. Sunucuyu Claude Code, Claude Desktop, Cursor, VS Code veya Codex gibi MCP'yi destekleyen bir yapay zekâ asistanına ekleyin; asistan sizin için web sitelerinde görevleri yerine getirebilir: görevi açıklar, Node Mantis siteyi gerçek bir tarayıcıda kullanır ve sonucu yapılandırılmış veri olarak döndürür.
Sunucuyu kodlama aracınıza veya asistanınıza eklemek şunları yapmanızı sağlar:
- Web sitesi görevlerini yerine getirin. Hedefi günlük dille belirtin; Node Mantis de tıklama, yazma ve formlar, açılır menüler ile tarih seçicilerle etkileşim kurma gibi işlemleri gerçek bir kullanıcının yapacağı şekilde gerçekleştirir.
- Yapılandırılmış sonuçlar alın. Bir JSON Schema sağlayın; Node Mantis sonucu bu şemaya uyan veri olarak döndürür.
- Uzun görevleri arka planda çalıştırın. Dakikalar süren bir görev çalışmaya devam ederken asistanınız görev durumunu kontrol edebilir, ilerlemeyi bildirebilir veya görevi iptal edebilir.
Sunucu, npm ve PyPI üzerindeki node-mantis paketinin bir parçasıdır; ayrıca bir şey yüklemeniz gerekmez. Asistan sunucuyu Node.js üzerinden tek bir komutla başlatır:
npx -y node-mantis mcp
veya uv ile Python üzerinden:
uvx node-mantis mcp
Her iki seçenek de asistana aynı araçları sunar. Node.js veya Python'a, Google Chrome'a ve kontrol panelinden alacağınız bir API anahtarına ihtiyacınız vardır. Chrome yüklü değilse ilk görev, Chrome for Testing'i indirir.
Asistanınıza ekleyin
Her asistan, ayarlarında MCP sunucularının listesini tutar. Node Mantis için bir komutla veya asistanın ayar dosyasını düzenleyerek bir kayıt eklersiniz; asistan da gerektiğinde sunucuyu kendisi başlatır. Üç adım vardır:
- Kontrol panelinden bir API anahtarı kopyalayın.
- Aşağıdaki kaydı asistanınıza ekleyin. Kaydın nereye ekleneceği asistana bağlıdır; tabloya ve devamındaki bölümlere bakın.
- Asistanı yeniden başlatın ve çalıştığını doğrulayın.
Çoğu asistan aynı JSON kaydını okur. Node.js ile:
{
"mcpServers": {
"node-mantis": {
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Python ile:
{
"mcpServers": {
"node-mantis": {
"command": "uvx",
"args": ["node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Kayıt üç bölümden oluşur:
node-mantis, asistanın sunucu için gösterdiği addır. Bu adı değiştirebilirsiniz.commandveargs, asistanın sunucuyu nasıl başlatacağını belirtir. Node.js veya Python sürümünden birini kullanın; ikisi de asistana aynı araçları sunar.env, asistanın sunucuyu başlatırken ona ilettiği ayarları içerir. Yer tutucuyu API anahtarınızla değiştirin. Anahtarı daha öncenodemantis configureile kaydettiysenizenvöğesini eklemeniz gerekmez.
Ayar dosyasında zaten bir mcpServers bölümü varsa, ikinci bir mcpServers yapıştırmak yerine node-mantis kaydını diğerlerinin yanına, bu bölümün içine ekleyin.
| Asistan | Kaydın ekleneceği yer |
|---|---|
| Claude Code | Terminalinizde tek bir komut. |
| Claude Desktop | Ayarlar'dan açılan claude_desktop_config.json. |
| Cursor | Her proje için ~/.cursor/mcp.json veya tek bir projede .cursor/mcp.json. |
| VS Code | Çalışma alanınızdaki .vscode/mcp.json. |
| Codex | Terminalinizde tek bir komut veya ~/.codex/config.toml. |
Claude Code
Terminalinizde aşağıdaki komutlardan birini çalıştırın. Node.js ile:
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Python ile:
claude mcp add node-mantis -e NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
Ardından claude mcp list, node-mantis öğesini bağlı olarak gösterir.
Claude Desktop
Ayarlar'ı, ardından Developer'ı ve sonra Edit Config'i açın. Bu işlem, macOS'te ~/Library/Application Support/Claude/, Windows'ta ise %APPDATA%\Claude\ konumunda bulunan claude_desktop_config.json dosyasını açar. Yukarıdaki JSON kaydını ekleyin, dosyayı kaydedin ve uygulamayı yeniden başlatın.
Cursor
Her projede kullanmak için yukarıdaki JSON kaydını ~/.cursor/mcp.json dosyasına, tek bir projede kullanmak içinse proje içindeki .cursor/mcp.json dosyasına ekleyin. Dosya yoksa oluşturun.
VS Code
VS Code, mcpServers yerine servers kullanır. Çalışma alanınızdaki .vscode/mcp.json dosyasına şunu ekleyin:
{
"servers": {
"node-mantis": {
"type": "stdio",
"command": "npx",
"args": ["-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Python için command değerini uvx, args değerini ise ["node-mantis", "mcp"] olarak ayarlayın.
Codex
Terminalinizde aşağıdaki komutlardan birini çalıştırın. Node.js ile:
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- npx -y node-mantis mcp
Python ile:
codex mcp add node-mantis --env NODEMANTIS_API_KEY="sk_live_<copy-from-dashboard>" -- uvx node-mantis mcp
Ya da ~/.codex/config.toml dosyasını düzenleyin. Daha uzun başlatma süresi sınırı, ilk başlatmada paketin indirilmesine zaman tanır:
[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>"
Python için command değerini "uvx", args değerini ise ["node-mantis", "mcp"] olarak ayarlayın.
uv olmadan Python
Yukarıdaki Python örneklerinde, ilk kullanımda paketi PyPI'dan getiren uv kullanılır. uv olmadan, paketi bir kez python -m pip install node-mantis ile yükleyin ve komut olarak nodemantis, tek argüman olarak da mcp kullanın:
{
"mcpServers": {
"node-mantis": {
"command": "nodemantis",
"args": ["mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Çalıştığını doğrulayın
Yeniden başlatmanın ardından asistan, MCP sunucuları arasında node-mantis öğesini dört araçla birlikte listeler. Ardından asistandan bir görev isteyin. Örneğin:
Use Node Mantis to open https://sandbox.nodemantis.com and tell me the title and price of the first book.
Asistan run_task çağrısını yapar ve görevin bulduklarını yanıt olarak verir. Böyle olmazsa Sorun giderme bölümüne bakın.
Windows
Asistan npx öğesini doğrudan başlatamıyorsa, cmd üzerinden çalıştırın:
{
"mcpServers": {
"node-mantis": {
"command": "cmd",
"args": ["/c", "npx", "-y", "node-mantis", "mcp"],
"env": { "NODEMANTIS_API_KEY": "sk_live_<copy-from-dashboard>" }
}
}
}
Araçlar
| Araç | Açıklama |
|---|---|
run_task | Günlük dille belirtilen bir hedef doğrultusunda web sitesinde görev gerçekleştirir: gezinir, tıklar, yazar, formları doldurur ve sonucu okur. |
retrieve_data | Tek bir sayfayı açar ve sayfada değişiklik yapmadan verileri okur. |
get_task | Bir görevi bekler ve durumunu, en son ilerleme bilgisini ve sonucunu döndürür. |
cancel_task | Çalışan bir görevi durdurur ve tarayıcısını kapatır. |
Her görev, kayıtlı oturum açma bilgileri olmayan yeni bir tarayıcı oturumunda çalışır. Görev sona erdiğinde oturum kapatılır.
run_task
SDK'deki run gibi çalışır. Yalnızca goal gereklidir.
| Parametre | Tür | Varsayılan | Açıklama |
|---|---|---|---|
goal | string | gerekli | Tamamlanması için gereken tüm ayrıntıları içeren, günlük dille yazılmış hedef. |
start_url | string | yok | Önce açılacak sayfa. Belirtilmezse görev, hedef doğrultusunda kendi yolunu bulur. |
result_schema | object | serbest biçimli | Döndürülecek verilerin JSON Schema'sı. Sonuç, verileri bu yapıda içerir. |
effort | low | medium | high | xhigh | orta | Harcanacak işlem kapasitesi. Daha yüksek kapasite, daha zor sayfaların işlenmesini sağlar ve maliyeti artırır. |
max_cost_usd | number | üst sınır yok | Adımlar arasında denetlenen USD bütçesi. Son adım, toplam harcamayı bu tutarın üzerine çıkarabilir. |
max_steps | integer | 30 | Görev durdurulmadan önce izin verilen en fazla adım sayısı. |
timeout_seconds | integer | 300 | Görevin toplam süre sınırı. |
secrets | string[] | yok | Görevin yazabileceği özel değerlerin adları. Her değer, sunucunun ortamındaki NODEMANTIS_SECRET_<NAME> değişkeninden okunur. |
use_proxy | boolean | false | Tarayıcıyı sunucunun ortamında yapılandırılmış proxy üzerinden yönlendirir. |
show_browser | boolean | false | Görev çalışırken tarayıcı penceresini gösterir. |
retrieve_data
SDK'deki retrieve gibi çalışır. Verilere ulaşmak için tıklama, yazma veya birden fazla sayfada gezinme gerekiyorsa bunun yerine run_task kullanın.
| Parametre | Tür | Varsayılan | Açıklama |
|---|---|---|---|
url | string | gerekli | Okunacak sayfa. |
prompt | string | gerekli | Sayfadan okunacaklar. |
result_schema | object | serbest biçimli | Döndürülen verilerin yapısını belirten JSON Schema. |
effort | low | medium | high | xhigh | orta | Sayfayı okumak için harcanacak işlem kapasitesi. |
use_proxy | boolean | false | Tarayıcıyı sunucunun ortamında yapılandırılmış proxy üzerinden yönlendirir. |
show_browser | boolean | false | Sayfa okunurken tarayıcı penceresini gösterir. |
get_task
| Parametre | Tür | Varsayılan | Açıklama |
|---|---|---|---|
task_id | string | gerekli | run_task veya retrieve_data tarafından döndürülen task_id. |
wait_seconds | integer | 45 | Yanıt vermeden önce görevin tamamlanması için beklenecek süre. 0, hemen yanıt verir. |
cancel_task
Bir task_id alır. Zaten tamamlanmış bir görev değiştirilmez.
Uzun görevler
Bir web sitesi görevinin tamamlanması, asistanın tek bir araç çağrısı için beklemeye razı olduğu süreden uzun sürebilir. Bu nedenle run_task ve retrieve_data en fazla 45 saniye bekler. Görev bu süre içinde tamamlanırsa çağrı sonucu döndürür. Aksi takdirde, task_id içeren running durumunu döndürür ve görev arka planda çalışmaya devam eder:
{
"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."
}
Asistan daha sonra durum succeeded, failed veya cancelled olana kadar bu kimlikle get_task çağrısını yapar:
{
"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"
}
}
failed durumundaki bir görev de bulduklarını ve nedenini döndürür; böylece asistan hedefi düzenleyip yeniden deneyebilir. Tamamlanan görevler bir saat boyunca saklanır. Görevler çalışan sunucuya bağlıdır: asistanınız sunucuyu kapattığında görevler durur.
Gizli bilgiler
Parolalar ve tek kullanımlık kodlar konuşma üzerinden iletilmez. Her değeri sunucunun ortamında env içindeki API anahtarının yanına NODEMANTIS_SECRET_<NAME> olarak ayarlayın. Asistan yalnızca secrets içindeki adları iletir ve hedefte bir değere <secret:NAME> olarak başvurur. Gizli bilgiler bölümüne bakın.
Proxy
Bir görevin tarayıcı trafiğini proxy üzerinden göndermek için sunucunun ortamında NODEMANTIS_PROXY ayarlayın ve görevin use_proxy iletmesini sağlayın. Proxy listeleri ve dosyaları, Proxy yapılandırması bölümünde açıklandığı şekilde çalışır.
Sunucu seçenekleri
Bunları args listesindeki mcp öğesinden sonra ekleyin.
| Parametre | Tür | Varsayılan | Açıklama |
|---|---|---|---|
--wait-seconds <n> | number | 45 | Araç çağrısının görev kimliğini döndürmeden önce görevi ne kadar süre bekleyeceği. Asistanınız araç çağrılarından daha erken vazgeçiyorsa bu değeri düşürün. |
--max-tasks <n> | number | 4 | Aynı anda çalışabilecek görev sayısı. |
-H, --headed | flag | headless | Bir araç çağrısı show_browser ayarlamadığı sürece her görev için tarayıcı penceresini gösterir. |
Sorun giderme
- Asistan, API anahtarının yapılandırılmadığını bildiriyor. Sunucunun
envayarınaNODEMANTIS_API_KEYekleyin veyanodemantis configurekomutunu bir kez çalıştırıp yeniden deneyin.configuresonrasında yeniden başlatma gerekmez. - Sunucu ilk başlatmada zaman aşımına uğruyor. İlk
npxbaşlatması paketi indirir. Paketi bir keznpm install -g node-mantisile yükleyin ve bunun yerine yüklenmiş komutu başlatın:{ "mcpServers": { "node-mantis": { "command": "nodemantis", "args": ["mcp"] } } } - Görevler başlatılamıyor. Kurulumu, tarayıcıyı ve API anahtarını denetlemek için
nodemantis doctorkomutunu çalıştırın.