🐢🚀 Node.js Sandbox MCP Server

Model Context Protocol (MCP) uygulayan ve keyfi JavaScript kodunu geçici Docker konteynerlerinde çalıştıran, anında npm bağımlılığı kurulumunu destekleyen Node.js sunucusu.

👉 Resmi websiteyi ziyaret edin

📦 Docker Hub'da mevcut

Özellikler

• İzole edilmiş Node.js sandbox konteynerlerini başlatma ve yönetme
• Konteynerler içinde keyfi shell komutlarını çalıştırma
• Her iş için belirtilen npm bağımlılıklarını kurma
• ES module JavaScript kod parçacıklarını çalıştırma ve stdout yakalama
• Konteynerları temiz bir şekilde kapatma
• Detached Mode: Komut dosyası yürütüldükten sonra konteyneri canlı tutma (örn. uzun süreli sunucular için)

Not: Konteynerler kontrollü CPU/bellek limitleriyle çalışır.

Harika Kullanım Durumlarını Keşfet

Bu kütüphaneyi kullanmanın harika ve güçlü yollarıyla ilgili fikirler istiyorsanız, websitedeki kullanım durumları bölümünü kontrol edin. Bu bölümde Node.js Sandbox MCP Server ile deneyebileceğiniz küratörlü bir prompt listesi, örnekler ve yaratıcı deneyler yer almaktadır.

⚠️ Ön Koşullar

Bu MCP sunucusunu kullanmak için Docker'ın makinenizde yüklü ve çalışıyor olması gerekir.

İpucu: İlk yürütme sırasında gecikmeleri önlemek için ihtiyacınız olacak Docker imajlarını önceden çekin.

Önerilen imaj örnekleri:

• node:lts-slim
• mcr.microsoft.com/playwright:v1.55.0-noble
• alfonsograziano/node-chartjs-canvas:latest

Başlangıç

Bu MCP sunucusunu kullanmaya başlamak için öncelikle onu bir istemciye (örneğin Claude Desktop) bağlamanız gerekir.

Çalıştıktan sonra, birkaç test promptu ile tam olarak çalışıp çalışmadığını doğrulayabilirsiniz:

• Aracın çalışabildiğini doğrulayın:

  console.log("Hello World") içeren bir JS scripti oluştur ve çalıştır
  

  Bu bir console.log çalıştırmalı ve araç yanıtında Hello World'ü görebilmeniz gerekir.

• Bağımlılıkları kurup dosya kaydedebileceğinizi doğrulayın

  `https://nodejs.org/en` URL'si için QR kodu üreten bir JS scripti oluştur, çalıştır ve `qrcode.png` olarak kaydet **İpucu:** `qrcode` paketini kullan.
  

  Bu işlem, bağlı dizininizde (örneğin Masaüstü) "qrcode.png" adlı bir dosya oluşturmalıdır.

Claude Desktop ile Kullanım

Bunu claude_desktop_config.json dosyanıza ekleyin: Bu MCP sunucusunu yüklemek için Resmi Rehberi takip edebilirsiniz.

{
  "mcpServers": {
    "js-sandbox": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "-v",
        "$HOME/Desktop/sandbox-output:/root",
        "-e",
        "FILES_DIR=$HOME/Desktop/sandbox-output",
        "-e",
        "SANDBOX_MEMORY_LIMIT=512m", // optional
        "-e",
        "SANDBOX_CPU_LIMIT=0.75", // optional
        "mcp/node-code-sandbox"
      ]
    }
  }
}

ya da NPX ile:

{
  "mcpServers": {
    "node-code-sandbox-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "node-code-sandbox-mcp"],
      "env": {
        "FILES_DIR": "/Users/alfonsograziano/Desktop/node-sandbox",
        "SANDBOX_MEMORY_LIMIT": "512m", // optional
        "SANDBOX_CPU_LIMIT": "0.75" // optional
      }
    }
  }
}

Not: Çalışma dizininizin derlenen sunucuya işaret ettiğini ve Docker'ın yüklü/çalışıyor olduğunu sağlayın.

Docker

Sunucuyu bir konteynerde çalıştırın (gerekirse Docker soketini bağlayın) ve istenen ana bilgisayar çıkış dizinini bir env değişkeni olarak iletin:

# Gerekirse yerel olarak oluşturun
# docker build -t mcp/node-code-sandbox .

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$HOME/Desktop/sandbox-output":"/root" \
  -e FILES_DIR="$HOME/Desktop/sandbox-output" \
  -e SANDBOX_MEMORY_LIMIT="512m" \
  -e SANDBOX_CPU_LIMIT="0.5" \
  mcp/node-code-sandbox stdio

Bu, ana bilgisayar klasörünü konteynerin içine aynı mutlak yol konumunda bağlar ve MCP sunucusu içinde FILES_DIR'yi kullanılabilir hale getirir.

Geçici kullanım – kalıcı depolama yok

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  alfonsograziano/node-code-sandbox-mcp stdio

VS Code ile Kullanım

Hızlı kurulum düğmeleri (VS Code & Insiders):

js-sandbox-mcp'yi kur (NPX) js-sandbox-mcp'yi kur (Docker)

Manuel yapılandırma: VS Code settings.json veya .vscode/mcp.json dosyanıza ekleyin:

"mcp": {
    "servers": {
        "js-sandbox": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-v", "/var/run/docker.sock:/var/run/docker.sock",
                "-v", "$HOME/Desktop/sandbox-output:/root", // optional
                "-e", "FILES_DIR=$HOME/Desktop/sandbox-output",  // optional
                "-e", "SANDBOX_MEMORY_LIMIT=512m",
                "-e", "SANDBOX_CPU_LIMIT=1",
                "mcp/node-code-sandbox"
              ]
        }
    }
}

API

Araçlar

run_js_ephemeral

Yepyeni tek kullanımlık bir konteynerde JS scripti çalıştırın.

Girdiler:

• image (string, opsiyonel): Kullanılacak Docker imajı (varsayılan: node:lts-slim).
• code (string, gerekli): Çalıştırılacak JavaScript kaynağı.
• dependencies (array of { name, version }, opsiyonel): Kurulacak NPM paketleri ve sürümleri (varsayılan: []).

Davranış:

1. Yeni bir konteyner oluşturur.
2. index.js ve minimal bir package.json yazar.
3. Belirtilen bağımlılıkları kurar.
4. Scripti çalıştırır.
5. Konteyneri kapatır (kaldırır).
6. Yakalanan stdout'u döndürür.
7. Kodunuz mevcut dizine dosya kaydederse, bu dosyalar otomatik olarak döndürülür.
   • Resimler (örn. PNG, JPEG) image içeriği olarak döndürülür.
   • Diğer dosyalar (örn. .txt, .json) resource içeriği olarak döndürülür.
   • Not: dosya kaydetme özelliği şu anda yalnızca geçici araçta mevcuttur.

İpucu: Dosyaları geri almak için script yürütülürken onları kaydetmeniz yeterlidir.

Örnek Çağrı:

{
  "name": "run_js_ephemeral",
  "arguments": {
    "image": "node:lts-slim",
    "code": "console.log('One-shot run!');",
    "dependencies": [{ "name": "lodash", "version": "^4.17.21" }],
  },
}

Dosya kaydetme örneği:

import fs from 'fs/promises';

await fs.writeFile('hello.txt', 'Hello world!');
console.log('Saved hello.txt');

Bu, konsol çıkışı ve hello.txt dosyasını döndürecektir.

sandbox_initialize

Yeni bir sandbox konteyneri başlatın.

• Giriş:
  • image (string, opsiyonel, varsayılan: node:lts-slim): Sandbox için Docker imajı
  • port (number, opsiyonel): Ayarlanmışsa, bu konteyner portunu ana bilgisayara eşler
• Çıkış: Container ID string'i

sandbox_exec

Çalışan sandbox içinde shell komutlarını çalıştırın.

• Giriş:
  • container_id (string): sandbox_initialize'dan gelen ID
  • commands (string[]): Çalıştırılacak shell komutları dizisi
• Çıkış: Her komutun birleştirilmiş stdout'u

run_js

NPM bağımlılıklarını kurun ve JavaScript kodunu çalıştırın.

• Giriş:

  • container_id (string): sandbox_initialize'dan gelen ID
  • code (string): Çalıştırılacak JS kaynağı (ES modules desteklenir)
  • dependencies (array of { name, version }, opsiyonel, varsayılan: []): npm paket adları → semver sürümleri
  • listenOnPort (number, opsiyonel): Ayarlanmışsa, işlemi çalışır durumda bırakır ve bu portu ana bilgisayara açar (Detached Mode)

• Davranış:

  1. Konteyner içinde geçici bir çalışma alanı oluşturur
  2. index.js ve minimal bir package.json yazar
  3. npm install --omit=dev --ignore-scripts --no-audit --loglevel=error komutunu çalıştırır
  4. node index.js komutunu çalıştırır ve stdout'u yakalar, ya da listenOnPort ayarlanmışsa işlemi arka planda çalışır durumda bırakır
  5. Detached modda çalışmıyorsa çalışma alanını temizler

• Çıkış: Script stdout'u veya arka plan yürütme bildirimi

sandbox_stop

Sandbox konteynerini sonlandırın ve kaldırın.

• Giriş:
  • container_id (string): sandbox_initialize'dan gelen ID
• Çıkış: Onay mesajı

search_npm_packages

NPM paketlerini bir arama terimiyle arayın ve adlarını, açıklamalarını ve README parçacığını alın.

• Giriş:

  • searchTerm (string, gerekli): NPM paketlerinde aranacak terim. Tüm ilgili bağlamı içermelidir. İlgili terimleri birleştirmek için artı işaretleri (+) kullanın (örn. React bileşen kütüphaneleri için "react+components").
  • qualifiers (object, opsiyonel): Arama sonuçlarını filtrelemek için opsiyonel niteleyiciler:
    • author (string, opsiyonel): Paket yazar adına göre filtrele
    • maintainer (string, opsiyonel): Paket bakıcısı adına göre filtrele
    • scope (string, opsiyonel): NPM kapsamına göre filtrele (örn. Vue.js paketleri için "@vue")
    • keywords (string, opsiyonel): Paket anahtar kelimelerine göre filtrele
    • not (string, opsiyonel): Bu kriterlere uyan paketleri hariç tut (örn. "insecure")
    • is (string, opsiyonel): Yalnızca bu kriterlere uyan paketleri dahil et (örn. "unstable")
    • boostExact (string, opsiyonel): Arama sonuçlarında bu terimin tam eşleşmelerini artır

• Davranış:

  1. Sağlanan arama terimi ve niteleyicileri kullanarak npm kayıt defterinde arama yapar
  2. Popülarite sırasına göre en fazla 5 paket döndürür
  3. Her paket için ad, açıklama ve README parçacığı (ilk 500 karakter) sağlar

• Çıkış: Paket detaylarını ad, açıklama ve README parçacığıyla içeren JSON dizisi

Kullanım İpuçları

• Oturum tabanlı araçlar (sandbox_initialize ➔ run_js ➔ sandbox_stop) şu durumlarda idealdir:
  • Uzun süreli bir sandbox konteynerini açık tutmak istediğinizde.
  • Aynı ortamda birden çok komut veya script çalıştırmak istediğinizde.
  • Bağımlılıkları aşamalı olarak kurup yeniden kullanmak istediğinizde.
• Tek çalıştırma yürütme run_js_ephemeral ile mükemmeldir:
  • Hızlı deneyler veya basit scriptler için.
  • Durumu korumaya veya bağımlılıkları önbelleğe almaya ihtiyacınız olmadığı durumlarda.
  • Manuel kapatma konusunda endişe duymadan temiz, atomik çalıştırışlar için.
• Detached mode şu durumlarda faydalıdır:
  • Anında sunucuları veya uzun süreli hizmetleri başlatmak
  • Çalışan konteynerlerden endpointleri açığa çıkarmak ve test etmek

Kullanım durumunuza en uygun iş akışını seçin!

Derleme

Derleyin ve paketleyin:

npm install
npm run build

Lisans

MIT Lisansı

Bu yazılımın ve ilişkili dokümantasyon dosyalarının ("Yazılım") bir kopyasını elde eden herhangi bir kişiye, Yazılımı sınırsız olarak kullanma, kopyalama, değiştirme, birleştirme, yayımlama, dağıtma, alt lisanslama ve/veya satma hakkı ve Yazılımın sağlanmış olduğu kişilere bunu yapma hakkı vermek dahil, ancak bununla sınırlı olmamak üzere, aşağıdaki koşullar uygulanması kaydıyla, hiçbir ücret ödenmeksizin bedelsiz olarak izin verilir:

Yukarıdaki telif hakkı bildirimi ve bu izin bildirimi, Yazılımın tüm kopyalarında veya önemli kısımlarında yer almalıdır.

YAZILIM "OLDUĞU GİBİ" SAĞLANIR, AÇIK VEYA ZIMNİ HERHANGI BİR GARANTİ OLMAKSIZIN; TİCARİLİK, BELİRLİ BİR AMACA UYGUNLUK VE İHLAL EDİLMEMESİ GARANTİLERİ DAHİL ANCAK BUNLARLA SINIRLI OLMAMAK ÜZERE. HİÇBİR DURUMDA YAZARLAR VEYA TELİF HAKKI SAHİPLERİ, YAZILIM VEYA YAZILIMIN KULLANILMASI VEYA DİĞER İŞLEMLERİNDEN KAYNAKLANAN, SÖZLEŞME, HAKSIZ FİİL VEYA BAŞKA HERHANGI BİR NEDENLE HERHANGİ BİR İDDİA, ZARAR VEYA DİĞER YÜKÜMLÜLÜKTEN SORUMLU OLMAYACAKTIR.