Node Mantis

resmi

Web 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_data kullanın.
  • Uzun süren görevleri yönetin — get_task ve cancel_task ile 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:

  1. Kontrol panelinden bir API anahtarı kopyalayın.
  2. 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.
  3. 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.
  • command ve args, 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 önce nodemantis configure ile kaydettiyseniz env öğ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.

AsistanKaydın ekleneceği yer
Claude CodeTerminalinizde tek bir komut.
Claude DesktopAyarlar'dan açılan claude_desktop_config.json.
CursorHer proje için ~/.cursor/mcp.json veya tek bir projede .cursor/mcp.json.
VS CodeÇalışma alanınızdaki .vscode/mcp.json.
CodexTerminalinizde 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_taskGü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_dataTek bir sayfayı açar ve sayfada değişiklik yapmadan verileri okur.
get_taskBir 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.

ParametreTürVarsayılanAçıklama
goalstringgerekliTamamlanması için gereken tüm ayrıntıları içeren, günlük dille yazılmış hedef.
start_urlstringyokÖnce açılacak sayfa. Belirtilmezse görev, hedef doğrultusunda kendi yolunu bulur.
result_schemaobjectserbest biçimliDöndürülecek verilerin JSON Schema'sı. Sonuç, verileri bu yapıda içerir.
effortlow | medium | high | xhighortaHarcanacak işlem kapasitesi. Daha yüksek kapasite, daha zor sayfaların işlenmesini sağlar ve maliyeti artırır.
max_cost_usdnumberüst sınır yokAdımlar arasında denetlenen USD bütçesi. Son adım, toplam harcamayı bu tutarın üzerine çıkarabilir.
max_stepsinteger30Görev durdurulmadan önce izin verilen en fazla adım sayısı.
timeout_secondsinteger300Görevin toplam süre sınırı.
secretsstring[]yokGörevin yazabileceği özel değerlerin adları. Her değer, sunucunun ortamındaki NODEMANTIS_SECRET_<NAME> değişkeninden okunur.
use_proxybooleanfalseTarayıcıyı sunucunun ortamında yapılandırılmış proxy üzerinden yönlendirir.
show_browserbooleanfalseGö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.

ParametreTürVarsayılanAçıklama
urlstringgerekliOkunacak sayfa.
promptstringgerekliSayfadan okunacaklar.
result_schemaobjectserbest biçimliDöndürülen verilerin yapısını belirten JSON Schema.
effortlow | medium | high | xhighortaSayfayı okumak için harcanacak işlem kapasitesi.
use_proxybooleanfalseTarayıcıyı sunucunun ortamında yapılandırılmış proxy üzerinden yönlendirir.
show_browserbooleanfalseSayfa okunurken tarayıcı penceresini gösterir.

get_task

ParametreTürVarsayılanAçıklama
task_idstringgereklirun_task veya retrieve_data tarafından döndürülen task_id.
wait_secondsinteger45Yanı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.

ParametreTürVarsayılanAçıklama
--wait-seconds <n>number45Araç ç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>number4Aynı anda çalışabilecek görev sayısı.
-H, --headedflagheadlessBir 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 env ayarına NODEMANTIS_API_KEY ekleyin veya nodemantis configure komutunu bir kez çalıştırıp yeniden deneyin. configure sonrasında yeniden başlatma gerekmez.
  • Sunucu ilk başlatmada zaman aşımına uğruyor. İlk npx başlatması paketi indirir. Paketi bir kez npm install -g node-mantis ile 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 doctor komutunu çalıştırın.