@natchs/browser-mcp 2.4.0 → 2.5.0

package/README.md

@@ -1,470 +1,367 @@
-# @natchs/browser-mcp
-
-[![npm version](https://img.shields.io/npm/v/%40natchs%2Fbrowser-mcp?label=npm&logo=npm)](https://www.npmjs.com/package/@natchs/browser-mcp)
-[![License](https://img.shields.io/npm/l/%40natchs%2Fbrowser-mcp?color=blue&label=license)](LICENSE)
-[![Node Version](https://img.shields.io/node/v/%40natchs%2Fbrowser-mcp?logo=node.js)](package.json)
-
----
-
-## 🇹🇷 Türkçe
-
-**Browser automation MCP server** — reverse engineering, web scraping ve data extraction için tasarlanmış, AI ajanların tarayıcıyı tam kontrol etmesini sağlayan bir Model Context Protocol sunucusu.
-
-### Quick Start
-
-```bash
-# 1. Install
-npm install @natchs/browser-mcp
-
-# 2. Run (Chromium browser otomatik kurulur, ilk çalıştırmada ~30sn)
-npx @natchs/browser-mcp
-```
-
-#### MCP Client Config
-
-Claude Desktop, Cursor, VS Code veya herhangi bir MCP istemcisine eklemek için:
-
-```json
-{
-  "mcpServers": {
-    "browser-mcp": {
-      "command": "npx",
-      "args": ["@natchs/browser-mcp"]
-    }
-  }
-}
-```
-
-Alternatif: projeyi klonlayıp yerel build ile de kullanabilirsiniz:
-
-```bash
-git clone https://github.com/natchs/browser-mcp.git
-cd browser-mcp
-npm ci
-npm run build
-npx @natchs/browser-mcp
-```
-
-#### Browser Profili: 3 Mod
-
-Ajanın hangi tarayıcıyı kullanacağını `BROWSER_MODE` ortam değişkeni belirler:
-
-| Mod | Açıklama | Ne Zaman Kullanılır? |
-|-----|----------|---------------------|
-| `fresh` (default) | Playwright'ın kendi Chromium'u. Her seferinde sıfır profil, çerez/ext/login yok | Temiz ortam, iz bırakmamak |
-| `persistent` | **Senin Chrome profilin.** Gerçek çerezler, geçmiş, uzantılar, oturum açmış hesaplar — hepsi ajana kullanıma hazır | Ajanın sitelere "sen" olarak girmesi gereken işlemler |
-| `connect` | Halihazırda açık Chrome'una CDP ile bağlanır | Chrome'u elle kontrol ederken ajanın eşlik etmesi |
-
-**Örnek — persistent (otomatik profil tespiti):**
-
-```bash
-BROWSER_MODE=persistent npx @natchs/browser-mcp
-```
-
-v2.3.0 ile Chrome profili otomatik tespit edilir. Hiçbir yol belirtmeniz gerekmez. Windows/macOS/Linux hepsinde çalışır. Manuel yol belirtmek için:
-
-```bash
-BROWSER_MODE=persistent BROWSER_USER_DATA_DIR=C:\Users\...\User Data\Default npx @natchs/browser-mcp
-```
-
-**Örnek — connect (mevcut Chrome'a bağlan):**
-
-```bash
-# Önce Chrome'u debug port ile aç:
-"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
-
-# Sonra ajanı bağla:
-BROWSER_MODE=connect npx @natchs/browser-mcp
-```
-
-**MCP Client Config ile kullanım — her mod için ayrı profil:**
-
-```json
-{
-  "mcpServers": {
-    "browser-mcp-persistent": {
-      "command": "npx",
-      "args": ["@natchs/browser-mcp"],
-      "env": {
-        "BROWSER_MODE": "persistent"
-      }
-    },
-    "browser-mcp-fresh": {
-      "command": "npx",
-      "args": ["@natchs/browser-mcp"],
-      "env": {
-        "BROWSER_MODE": "fresh"
-      }
-    }
-  }
-}
-```
-
----
-
-### Ortam Değişkenleri
-
-Tüm yapılandırma, ortam değişkenleri aracılığıyla yapılabilir. Aşağıdaki tablo, desteklenen tüm değişkenleri listeler.
-
-#### Browser
-
-| Variable | Default | Description | Required |
-|----------|---------|-------------|----------|
-| `BROWSER_MODE` | `fresh` | Browser modu: `fresh`, `persistent`, `connect` | No |
-| `BROWSER_HEADLESS` | `true` | Headless modda çalıştır (`true`/`false`/`1`/`0`/`yes`/`no`) | No |
-| `BROWSER_USER_DATA_DIR` | — | Chrome kullanıcı veri dizini (mutlak yol) | No |
-| `BROWSER_CHANNEL` | `""` | Browser kanalı (`chrome`, `msedge`, `chromium`, vb.) | No |
-| `BROWSER_DEBUG_PORT` | `9222` | CDP debug port numarası | No |
-| `BROWSER_AUTO_DETECT_PROFILE` | `true` | Chrome profilini otomatik tespit et | No |
-| `BROWSER_VIEWPORT_WIDTH` | `1280` | Görüntü alanı genişliği (px) | No |
-| `BROWSER_VIEWPORT_HEIGHT` | `720` | Görüntü alanı yüksekliği (px) | No |
-| `BROWSER_USER_AGENT` | — | Özel User-Agent string'i | No |
-| `BROWSER_LOCALE` | — | Tarayıcı locale değeri (örn. `tr-TR`) | No |
-| `BROWSER_TIMEOUT` | `30000` | Browser işlemleri için timeout (ms) | No |
-| `BROWSER_AUTO_INSTALL` | `true` | Chromium'u otomatik kur (`false` ile devre dışı) | No |
-
-#### Network & Download
-
-| Variable | Default | Description | Required |
-|----------|---------|-------------|----------|
-| `NETWORK_HAR_ENABLED` | `1` | HAR yakalamayı etkinleştir (`0` ile devre dışı) | No |
-| `NETWORK_MAX_ENTRIES` | `5000` | Maksimum network kaydı sayısı | No |
-| `NETWORK_MAX_RESPONSE_BODY_SIZE` | `262144` | Maksimum response body boyutu (bytes) | No |
-| `NETWORK_STORE_RESPONSE_BODIES` | `false` | Response body'leri hafızada tut | No |
-| `NETWORK_EXCLUDE_BODY_TYPES` | `["image","media","font","stylesheet"]` | Body kaydı dışı bırakılacak tipler (JSON array) | No |
-| `NETWORK_EXPORT_DIR` | `./network-logs` | Network log dışa aktarma dizini | No |
-| `NETWORK_CAPTURE_FAILED` | `true` | Başarısız istekleri de yakala | No |
-| `NETWORK_CAPTURE_WS` | `true` | WebSocket frame'lerini yakala | No |
-| `NETWORK_WS_MAX_FRAMES` | `1000` | Maksimum WS frame sayısı | No |
-| `NETWORK_WS_MAX_FRAME_SIZE` | `65536` | Maksimum WS frame payload boyutu | No |
-| `NETWORK_MAX_MEMORY_MB` | `256` | Network capture için maksimum bellek (MB) | No |
-| `NETWORK_CAPTURE_REQUEST_BODY` | `false` | Request body'lerini de yakala | No |
-| `NETWORK_DOWNLOAD_DIR` | `./downloads` | İndirilen dosyalar için dizin | No |
-| `NETWORK_MAX_DOWNLOAD_SIZE` | `104857600` | Maksimum indirme boyutu (bytes, varsayılan 100MB) | No |
-| `NETWORK_DOWNLOAD_ENABLED` | `false` | Dosya indirme özelliğini etkinleştir | No |
-| `NETWORK_SAVE_ENABLED` | `false` | Network capture kaydetme özelliğini etkinleştir (`network_save` tool'u) | No |
-
-#### Rate Limiting
-
-| Variable | Default | Description | Required |
-|----------|---------|-------------|----------|
-| `RATE_LIMIT_ENABLED` | `true` | Rate limiting'i etkinleştir | No |
-| `RATE_LIMIT_GLOBAL_RPM` | `120` | Global dakikalık istek limiti | No |
-| `RATE_LIMIT_PER_TOOL_RPM` | `30` | Tool başına dakikalık istek limiti | No |
-| `RATE_LIMIT_BURST_SIZE` | `10` | Maksimum burst boyutu | No |
-
-#### Cache
-
-| Variable | Default | Description | Required |
-|----------|---------|-------------|----------|
-| `CACHE_MAX_ENTRIES` | `100` | Maksimum önbellek girişi sayısı | No |
-| `CACHE_TTL_SECONDS` | `300` | Önbellek TTL değeri (saniye) | No |
-
-#### Security
-
-| Variable | Default | Description | Required |
-|----------|---------|-------------|----------|
-| `SECURITY_API_KEY` | `""` | API anahtarı (boş = auth kapalı) | No |
-| `SECURITY_ALLOWED_DIRS` | `[]` | İzin verilen dizinler (JSON array) | No |
-| `SECURITY_MAX_MEMORY_MB` | `512` | Maksimum bellek kullanımı (MB) | No |
-| `SECURITY_DEFAULT_TIMEOUT` | `30000` | Varsayılan işlem timeout'u (ms) | No |
-| `SECURITY_MAX_TIMEOUT` | `120000` | Maksimum timeout (ms) | No |
-| `SECURITY_MAX_SESSIONS` | `10` | Maksimum eşzamanlı browser session sayısı | No |
-
-#### Config
-
-| Variable | Default | Description | Required |
-|----------|---------|-------------|----------|
-| `BROWSER_MCP_CONFIG` | — | Yapılandırma dosyası yolu (JSON) | No |
-
----
-
-### Detaylı Özellikler
-
-#### Mevcut Yetenekler
-
-| Kategori | Tool Sayısı | Neler Yapabilir? |
-|----------|------------|-------------------|
-| **Navigation** | 5 | Sayfa açma, geri/ileri gitme, refresh, element/url bekleme |
-| **Interaction** | 8 | Tıklama, form doldurma, select kutusu, hover, drag-drop, klavye, dosya yükleme |
-| **Extraction** | 7 | HTML, Markdown, plain text, CSS selector, tablo, Schema.org, Open Graph |
-| **Network** | 10 | İstek/cevap takibi, HAR/JSON/CSV export, WebSocket frame yakalama, body kaydetme, console log |
-| **Browser Control** | 8 | Screenshot, PDF, çerez yönetimi, JavaScript çalıştırma, dosya indirme |
-| **Session** | 3 | Çoklu session açma/kapama/listeleme, otomatik TTL cleanup |
-| **Admin** | 3 | Server durumu, cache istatistikleri, cache temizleme |
-| **RE Tools** | 4 | JavaScript beautify/deobfuscate, API endpoint discovery, auth analizi |
-| **Stealth** | 2 | Fingerprint değiştirme, human behavior simülasyonu |
-
-**Toplam: 40+ tool, 9 kategori, production-grade mimari**
-
-#### Ne Yapabilir?
-
-- **Reverse Engineering**: JS deobfuscation, API auth analizi, network isteklerini HAR formatında export
-- **Web Scraping**: Cloudflare koruması olmayan sitelerden HTML/Markdown/text çekme, tablo ve Schema.org yapılandırılmış veri extraction
-- **Network Monitoring**: HTTP/HTTPS isteklerini gerçek zamanlı yakalama, WebSocket frame'lerini izleme, binary body'leri diske kaydetme
-- **Form Automation**: Login formları, search, multi-step form doldurma, dosya upload
-- **Session Yönetimi**: Her biri izole, aynı anda birden çok browser session'ı yönetme, otomatik TTL ile cleanup
-- **Güvenlik**: SSRF koruması (internal IP bloklama, DNS rebind engelleme, redirect bypass koruması), path traversal engelleme, MIME tabanlı extension blocklist, cookie leak koruması
-- **Data Export**: network capture'ları HAR/JSON/CSV export, body save, WS frame save (.jsonl)
-- **Observability**: Structured JSON logging, tool metrikleri (call count, süre, hata), LRU cache + TTL
-- **Rate Limiting**: Token bucket, global + per-tool, yapılandırılabilir RPM
-
-#### Browser Profil Yönetimi (v2.3.0)
-
-Ajan, 3 farklı browser modundan biriyle çalışır:
-
-- **`fresh` (default):** Playwright'ın kendi Chromium'unu kullanır, her seferinde sıfır profil. Çerez, geçmiş, uzantı — hiçbiri taşınmaz.
-- **`persistent`:** Gerçek Chrome profilinizi kullanır. Oturum açtığınız tüm sitelere (Gmail, GitHub, ChatGPT, kurumsal VPN) ajan da "sizmiş gibi" erişir. v2.3.0 ile profil otomatik tespit edilir — `BROWSER_MODE=persistent` yazmanız yeterli.
-- **`connect`:** Halihazırda `--remote-debugging-port` ile açılmış Chrome'unuza bağlanır. Mevcut sekmeleri ve oturumları ajanla paylaşırsınız.
-
-#### Ne Yapamaz? (Mevcut Sınırlamalar)
-
-- **Cloudflare/anti-bot korumalı siteler**: Challenge sayfalarını geçemez, manuel çözüm gerekir
-- **Captcha çözümü**: Dahili captcha çözücü yoktur (üçüncü parti servislerle entegre edilebilir)
-- **Görsel tanıma**: Screenshot alabilir ama içeriği yorumlayamaz
-- **Native dosya indirme**: `browser_download` URL bazlıdır, Playwright native download event'ini kapsamaz
-- **Canvas/WebGL fingerprinting**: Temel fingerprint değişir ama gelişmiş anti-bot sistemlerini geçemeyebilir
-- **Mobil browser simülasyonu**: Sadece Chromium desktop, mobile viewport taklidi yapabilir
-
-#### Güvenlik Özellikleri
-
-- `redirect: 'manual'` tüm URL fetch çağrılarında — SSRF redirect bypass koruması
-- `validateUrlAsync` DNS lookup — DNS rebind saldırılarına karşı
-- `DANGEROUS_EXTENSIONS` blocklist (.exe, .bat, .sh vb) → güvenli `.bin` fallback
-- Pseudo-FS path blocking (`/proc/`, `/sys/`, `/etc/` vb)
-- Cookie header filtresi — Stage 3 HTTP re-fetch'te cross-origin credential sızıntısı önlenir
-- `downloadEnabled` (download) ve `networkSaveEnabled` (network_save) varsayılan **false** — kullanıcı açıkça enable etmeden çalışmaz
-- Input sanitizasyonu (null byte, path traversal, fileName injection)
-
-#### MCP Client Uyumluluğu
-
-Claude Desktop, Cursor, VS Code (Cline, Roo Code), Continue.dev, özel MCP istemcileri — protocol uyumlu tüm platformlar.
-
----
-
-### Daha Fazlası Yolda
-
-Bu proje aktif geliştirme aşamasındadır. Kısa süre içinde:
-
-- **Yeni tool'lar**: PDF extraction, screenshot annotation, form detection, cookie manager, session snapshot/restore
-- **Cloudflare bypass**: Playwright Stealth entegrasyonu, rotatable proxy desteği
-- **Batch scraping**: Çoklu sayfa scraping pipeline, queue sistemi
-- **Performance**: Ring buffer optimizasyonu, streaming response, lazy evaluation
-- **Developer Experience**: Interaktif CLI, playground UI, type-safe client SDK
-
----
-
-### Geliştirme
-
-```bash
-# Test
-npm test
-npm run test:coverage
-
-# Type check (tsc --noEmit)
-npm run lint
-
-# Build
-npm run build
-```
-
-### Lisans
-
-MIT
-
----
-
-## 🇬🇧 English
-
-**Browser automation MCP server** — a Model Context Protocol server designed for reverse engineering, web scraping, and data extraction. It gives AI agents full control over a browser.
-
-### Quick Start
-
-```bash
-# 1. Install
-npm install @natchs/browser-mcp
-
-# 2. Run (Chromium installs automatically ~30s on first run)
-npx @natchs/browser-mcp
-```
-
-#### MCP Client Config
-
-Add to Claude Desktop, Cursor, VS Code, or any MCP client:
-
-```json
-{
-  "mcpServers": {
-    "browser-mcp": {
-      "command": "npx",
-      "args": ["@natchs/browser-mcp"]
-    }
-  }
-}
-```
-
-You can also clone and build locally:
-
-```bash
-git clone https://github.com/natchs/browser-mcp.git
-cd browser-mcp
-npm ci
-npm run build
-npx @natchs/browser-mcp
-```
-
-#### Browser Profile: 3 Modes
-
-The `BROWSER_MODE` environment variable determines which browser the agent uses:
-
-| Mode | Description | When to Use |
-|------|-------------|-------------|
-| `fresh` (default) | Playwright's own Chromium. Fresh profile every time, no cookies/extensions/logins | Clean environment, leave no trace |
-| `persistent` | **Your Chrome profile.** Real cookies, history, extensions, logged-in accounts — all available to the agent | When the agent needs to act "as you" on sites |
-| `connect` | Connects to your already-open Chrome via CDP | When manually controlling Chrome alongside the agent |
-
-**Example — persistent (auto-detect profile):**
-
-```bash
-BROWSER_MODE=persistent npx @natchs/browser-mcp
-```
-
-Since v2.3.0 the Chrome profile is auto-detected. No path needed. Works on Windows/macOS/Linux. To specify a manual path:
-
-```bash
-BROWSER_MODE=persistent BROWSER_USER_DATA_DIR=C:\Users\...\User Data\Default npx @natchs/browser-mcp
-```
-
-**Example — connect (attach to existing Chrome):**
-
-```bash
-# First open Chrome with debug port:
-"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
-
-# Then start the agent:
-BROWSER_MODE=connect npx @natchs/browser-mcp
-```
-
-**MCP Client Config — separate profiles per mode:**
-
-```json
-{
-  "mcpServers": {
-    "browser-mcp-persistent": {
-      "command": "npx",
-      "args": ["@natchs/browser-mcp"],
-      "env": {
-        "BROWSER_MODE": "persistent"
-      }
-    },
-    "browser-mcp-fresh": {
-      "command": "npx",
-      "args": ["@natchs/browser-mcp"],
-      "env": {
-        "BROWSER_MODE": "fresh"
-      }
-    }
-  }
-}
-```
-
----
-
-### Environment Variables
-
-All configuration can be done via environment variables. The table below lists all supported variables. (Same as the Turkish table above — see the Turkish section for the full list.)
-
----
-
-### Detailed Features
-
-#### Current Capabilities
-
-| Category | Tools | Capabilities |
-|----------|-------|--------------|
-| **Navigation** | 5 | Open page, back/forward, refresh, wait for element/URL |
-| **Interaction** | 8 | Click, fill form, select box, hover, drag-drop, keyboard, file upload |
-| **Extraction** | 7 | HTML, Markdown, plain text, CSS selector, tables, Schema.org, Open Graph |
-| **Network** | 10 | Request/response tracking, HAR/JSON/CSV export, WebSocket frame capture, body save, console log |
-| **Browser Control** | 8 | Screenshot, PDF, cookie management, JavaScript execution, file download |
-| **Session** | 3 | Multi-session open/close/list, automatic TTL cleanup |
-| **Admin** | 3 | Server status, cache statistics, cache clear |
-| **RE Tools** | 4 | JavaScript beautify/deobfuscate, API endpoint discovery, auth analysis |
-| **Stealth** | 2 | Fingerprint rotation, human behavior simulation |
-
-**Total: 40+ tools, 9 categories, production-grade architecture**
-
-#### What It Can Do
-
-- **Reverse Engineering**: JS deobfuscation, API auth analysis, network request export in HAR format
-- **Web Scraping**: HTML/Markdown/text extraction from non-Cloudflare sites, table and Schema.org structured data extraction
-- **Network Monitoring**: Real-time HTTP/HTTPS interception, WebSocket frame inspection, binary body save to disk
-- **Form Automation**: Login forms, search, multi-step form filling, file upload
-- **Session Management**: Each isolated, concurrent browser sessions with automatic TTL cleanup
-- **Security**: SSRF protection (internal IP blocking, DNS rebind prevention, redirect bypass guard), path traversal prevention, MIME-based extension blocklist, cookie leak protection
-- **Data Export**: Network captures as HAR/JSON/CSV, body save, WS frame save (.jsonl)
-- **Observability**: Structured JSON logging, tool metrics (call count, duration, errors), LRU cache + TTL
-- **Rate Limiting**: Token bucket, global + per-tool, configurable RPM
-
-#### Browser Profile Management (v2.3.0)
-
-The agent works in one of 3 browser modes:
-
-- **`fresh` (default):** Uses Playwright's own Chromium, fresh profile every time. No cookies, history, or extensions are carried over.
-- **`persistent`:** Uses your real Chrome profile. The agent accesses all your logged-in sites (Gmail, GitHub, ChatGPT, corporate VPN) as "you." Since v2.3.0, profiles are auto-detected — just set `BROWSER_MODE=persistent`.
-- **`connect`:** Connects to your already-running Chrome via `--remote-debugging-port`. Share existing tabs and sessions with the agent.
-
-#### Limitations
-
-- **Cloudflare/anti-bot sites**: Cannot bypass challenge pages, manual solving required
-- **Captcha solving**: No built-in captcha solver (third-party services can be integrated)
-- **Visual recognition**: Can take screenshots but cannot interpret content
-- **Native file download**: `browser_download` is URL-based, does not cover Playwright native download events
-- **Canvas/WebGL fingerprinting**: Basic fingerprint changes but may not bypass advanced anti-bot systems
-- **Mobile browser simulation**: Chromium desktop only, can emulate mobile viewport
-
-#### Security Features
-
-- `redirect: 'manual'` on all URL fetch calls — SSRF redirect bypass protection
-- `validateUrlAsync` DNS lookup — DNS rebind attack prevention
-- `DANGEROUS_EXTENSIONS` blocklist (.exe, .bat, .sh etc.) → safe `.bin` fallback
-- Pseudo-FS path blocking (`/proc/`, `/sys/`, `/etc/` etc.)
-- Cookie header filter — prevents cross-origin credential leakage in Stage 3 HTTP re-fetch
-- `downloadEnabled` and `networkSaveEnabled` default to **false** — must be explicitly enabled
-- Input sanitization (null byte, path traversal, fileName injection)
-
-#### MCP Client Compatibility
-
-Claude Desktop, Cursor, VS Code (Cline, Roo Code), Continue.dev, custom MCP clients — all protocol-compliant platforms.
-
----
-
-### Roadmap
-
-This project is under active development. Coming soon:
-
-- **New tools**: PDF extraction, screenshot annotation, form detection, cookie manager, session snapshot/restore
-- **Cloudflare bypass**: Playwright Stealth integration, rotatable proxy support
-- **Batch scraping**: Multi-page scraping pipeline, queue system
-- **Performance**: Ring buffer optimization, streaming response, lazy evaluation
-- **Developer Experience**: Interactive CLI, playground UI, type-safe client SDK
-
----
-
-### Development
-
-```bash
-# Test
-npm test
-npm run test:coverage
-
-# Type check (tsc --noEmit)
-npm run lint
-
-# Build
-npm run build
-```
-
-### License
-
-MIT
+# @natchs/browser-mcp
+
+[![npm version](https://img.shields.io/npm/v/%40natchs%2Fbrowser-mcp?label=npm&logo=npm)](https://www.npmjs.com/package/@natchs/browser-mcp)
+[![License](https://img.shields.io/npm/l/%40natchs%2Fbrowser-mcp?color=blue&label=license)](LICENSE)
+[![Node Version](https://img.shields.io/node/v/%40natchs%2Fbrowser-mcp?logo=node.js)](package.json)
+
+---
+
+# Your AI Agent's Browser Superpowers — Reverse Engineering, Network Interception & Full Browser Control
+
+**`@natchs/browser-mcp`** is a Model Context Protocol server that gives AI agents **complete browser control** — navigate, click, scrape, intercept network traffic, export HAR files, capture WebSocket frames, deobfuscate JavaScript, and more. All through a single MCP interface.
+
+Three browser modes (fresh / persistent / connect), production-grade security, 50+ tools, 9 categories. Built for reverse engineers, data extraction pipelines, and AI-powered automation.
+
+---
+
+## Features
+
+- 🔍 **Reverse Engineering Toolkit** — JS beautify/deobfuscate, API endpoint discovery, auth flow analysis
+- 🌐 **Web Scraping** — HTML, Markdown, text, CSS selectors, tables, Schema.org JSON-LD, Open Graph
+- 📡 **Network Intelligence** — Real-time HTTP/HTTPS interception, WebSocket frame capture, HAR/JSON/CSV export
+- 🕶️ **Stealth Mode** — Fingerprint rotation, human behavior simulation
+- 🔐 **Enterprise Security** — SSRF protection, DNS rebind prevention, path traversal guards, cookie leak prevention
+- 🧩 **3 Browser Profiles** — Fresh (isolated), Persistent (your Chrome profile, auto-detected), Connect (existing browser)
+- 📦 **50+ Tools** — Navigation, interaction, extraction, network, browser control, sessions, admin, RE, stealth
+- ⚡ **Production Ready** — Rate limiting, LRU cache, structured logging, metrics, plugin system, configurable timeouts
+
+---
+
+## Quick Start
+
+```bash
+# Install
+npm install @natchs/browser-mcp
+
+# Run (Chromium installs automatically ~30s on first run)
+npx @natchs/browser-mcp
+```
+
+### MCP Client Config
+
+Add to Claude Desktop, Cursor, VS Code (Cline, Roo Code), Continue.dev, or any MCP-compatible client:
+
+```json
+{
+  "mcpServers": {
+    "browser-mcp": {
+      "command": "npx",
+      "args": ["@natchs/browser-mcp"]
+    }
+  }
+}
+```
+
+### Local Build
+
+```bash
+git clone https://github.com/natchs/browser-mcp.git
+cd browser-mcp
+npm ci
+npm run build
+npx @natchs/browser-mcp
+```
+
+---
+
+## Browser Modes
+
+The `BROWSER_MODE` environment variable controls which browser profile the agent uses:
+
+| Mode | Description | Best For |
+|------|-------------|----------|
+| `fresh` (default) | Playwright's own Chromium. Fresh profile every time — no cookies, history, or extensions carried over | Clean room analysis, leave-no-trace operations |
+| `persistent` | **Your real Chrome profile.** Auto-detected since v2.3.0. All cookies, sessions, extensions, and logged-in accounts available to the agent | When the agent needs to act "as you" — Gmail, GitHub, ChatGPT, corporate portals |
+| `connect` | Attaches to your already-running Chrome via CDP debug port | Hybrid workflows — manually drive Chrome while the agent assists |
+
+### Persistent (auto-detect)
+
+```bash
+BROWSER_MODE=persistent npx @natchs/browser-mcp
+```
+
+Since v2.3.0 the Chrome profile is auto-detected on Windows/macOS/Linux. No path needed. To specify a manual path:
+
+```bash
+BROWSER_MODE=persistent BROWSER_USER_DATA_DIR=C:\Users\...\User Data\Default npx @natchs/browser-mcp
+```
+
+### Connect (attach to existing Chrome)
+
+```bash
+# Start Chrome with debug port first:
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+
+# Then launch the agent:
+BROWSER_MODE=connect npx @natchs/browser-mcp
+```
+
+### Per-Mode Client Profiles
+
+```json
+{
+  "mcpServers": {
+    "browser-mcp-persistent": {
+      "command": "npx",
+      "args": ["@natchs/browser-mcp"],
+      "env": { "BROWSER_MODE": "persistent" }
+    },
+    "browser-mcp-fresh": {
+      "command": "npx",
+      "args": ["@natchs/browser-mcp"],
+      "env": { "BROWSER_MODE": "fresh" }
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+All configuration is managed through environment variables.
+
+### Browser
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `BROWSER_MODE` | `fresh` | Browser mode: `fresh`, `persistent`, `connect` | No |
+| `BROWSER_HEADLESS` | `true` | Run in headless mode (`true`/`false`/`1`/`0`/`yes`/`no`) | No |
+| `BROWSER_USER_DATA_DIR` | — | Chrome user data directory (absolute path) | No |
+| `BROWSER_CHANNEL` | `""` | Browser channel (`chrome`, `msedge`, `chromium`, etc.) | No |
+| `BROWSER_DEBUG_PORT` | `9222` | CDP debug port number | No |
+| `BROWSER_AUTO_DETECT_PROFILE` | `true` | Auto-detect Chrome profile location | No |
+| `BROWSER_VIEWPORT_WIDTH` | `1280` | Viewport width (px) | No |
+| `BROWSER_VIEWPORT_HEIGHT` | `720` | Viewport height (px) | No |
+| `BROWSER_USER_AGENT` | — | Custom User-Agent string | No |
+| `BROWSER_LOCALE` | — | Browser locale (e.g. `en-US`) | No |
+| `BROWSER_TIMEOUT` | `30000` | Browser operation timeout (ms) | No |
+| `BROWSER_AUTO_INSTALL` | `true` | Auto-install Chromium (`false` to disable) | No |
+
+### Network & Download
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `NETWORK_HAR_ENABLED` | `1` | Enable HAR capture (`0` to disable) | No |
+| `NETWORK_MAX_ENTRIES` | `5000` | Max network entries stored | No |
+| `NETWORK_MAX_RESPONSE_BODY_SIZE` | `262144` | Max response body size (bytes) | No |
+| `NETWORK_STORE_RESPONSE_BODIES` | `false` | Keep response bodies in memory | No |
+| `NETWORK_EXCLUDE_BODY_TYPES` | `["image","media","font","stylesheet"]` | Body types excluded from storage (JSON array) | No |
+| `NETWORK_EXPORT_DIR` | `./network-logs` | Network log export directory | No |
+| `NETWORK_CAPTURE_FAILED` | `true` | Capture failed requests too | No |
+| `NETWORK_CAPTURE_WS` | `true` | Capture WebSocket frames | No |
+| `NETWORK_WS_MAX_FRAMES` | `1000` | Max WebSocket frames stored | No |
+| `NETWORK_WS_MAX_FRAME_SIZE` | `65536` | Max WebSocket frame payload (bytes) | No |
+| `NETWORK_MAX_MEMORY_MB` | `256` | Max memory for network capture (MB) | No |
+| `NETWORK_CAPTURE_REQUEST_BODY` | `false` | Capture request bodies too | No |
+| `NETWORK_DOWNLOAD_DIR` | `./downloads` | Download directory | No |
+| `NETWORK_MAX_DOWNLOAD_SIZE` | `104857600` | Max download size (bytes, default 100MB) | No |
+| `NETWORK_DOWNLOAD_ENABLED` | `false` | Enable file downloads (`browser_download` tool) | No |
+| `NETWORK_SAVE_ENABLED` | `false` | Enable network capture save (`network_save` tool) | No |
+
+### Rate Limiting
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `RATE_LIMIT_ENABLED` | `true` | Enable rate limiting | No |
+| `RATE_LIMIT_GLOBAL_RPM` | `120` | Global requests per minute | No |
+| `RATE_LIMIT_PER_TOOL_RPM` | `30` | Per-tool requests per minute | No |
+| `RATE_LIMIT_BURST_SIZE` | `10` | Max burst size | No |
+
+### Cache
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `CACHE_MAX_ENTRIES` | `100` | Max cache entries | No |
+| `CACHE_TTL_SECONDS` | `300` | Cache TTL (seconds) | No |
+
+### Security
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `SECURITY_API_KEY` | `""` | API key for authentication (empty = auth disabled) | No |
+| `SECURITY_ALLOWED_DIRS` | `[]` | Allowed directories for file access (JSON array) | No |
+| `SECURITY_MAX_MEMORY_MB` | `512` | Max memory usage (MB) | No |
+| `SECURITY_DEFAULT_TIMEOUT` | `30000` | Default operation timeout (ms) | No |
+| `SECURITY_MAX_TIMEOUT` | `120000` | Max timeout (ms) | No |
+| `SECURITY_MAX_SESSIONS` | `10` | Max concurrent browser sessions | No |
+
+### Config
+
+| Variable | Default | Description | Required |
+|----------|---------|-------------|----------|
+| `BROWSER_MCP_CONFIG` | — | Config file path (JSON) | No |
+
+---
+
+## All Tools
+
+### Navigation (5)
+
+| Tool | Description |
+|------|-------------|
+| `browser_navigate` | Navigate to a URL |
+| `browser_go_back` | Go back in history |
+| `browser_go_forward` | Go forward in history |
+| `browser_refresh` | Refresh the current page |
+| `browser_wait_for` | Wait for a specified timeout |
+
+### Interaction (8)
+
+| Tool | Description |
+|------|-------------|
+| `browser_click` | Click an element by CSS selector |
+| `browser_fill` | Fill text into an input field |
+| `browser_select` | Select option(s) in a dropdown |
+| `browser_hover` | Hover over an element |
+| `browser_drag` | Drag and drop an element |
+| `browser_type` | Type text character by character |
+| `browser_press_key` | Press a keyboard key |
+| `browser_file_upload` | Upload files via file input |
+
+### Extraction (7)
+
+| Tool | Description |
+|------|-------------|
+| `browser_extract_html` | Extract full page HTML |
+| `browser_extract_markdown` | Extract page as approximate markdown |
+| `browser_extract_text` | Extract visible text |
+| `browser_extract_with_css` | Extract data matching a CSS selector |
+| `browser_extract_table` | Extract tables as structured JSON |
+| `browser_extract_schema_org` | Extract Schema.org JSON-LD data |
+| `browser_extract_open_graph` | Extract Open Graph meta tags |
+
+### Network (10)
+
+| Tool | Description |
+|------|-------------|
+| `browser_network_requests` | List network requests made by the page |
+| `browser_network_response` | Get full response details for a request |
+| `browser_get_console` | Get console messages from the page |
+| `browser_handle_dialog` | Accept or dismiss a browser dialog |
+| `browser_wait_for_navigation` | Wait for the page to navigate |
+| `browser_get_network_entries` | List detailed network entries with timing/sizes/headers |
+| `browser_network_export` | Export network log to HAR, JSON, or CSV |
+| `browser_websocket_frames` | List captured WebSocket frames |
+| `browser_network_clear` | Clear captured network data |
+| `browser_network_save` | Save network response or WS frames to disk |
+
+### Browser Control (9)
+
+| Tool | Description |
+|------|-------------|
+| `browser_screenshot` | Take a screenshot (page or element) |
+| `browser_page_info` | Get page title, URL, viewport info |
+| `browser_get_cookies` | Get all cookies |
+| `browser_set_cookie` | Set a cookie |
+| `browser_delete_cookie` | Delete a cookie by name |
+| `browser_evaluate` | Execute JavaScript in page context |
+| `browser_pdf` | Generate a PDF of the current page |
+| `browser_download` | Download a URL to disk |
+| `browser_scroll` | Scroll the page or an element |
+
+### Session (3)
+
+| Tool | Description |
+|------|-------------|
+| `browser_open_session` | Open a new browser session (tab) |
+| `browser_close_session` | Close a session by ID |
+| `browser_list_sessions` | List all active sessions |
+
+### Admin (3)
+
+| Tool | Description |
+|------|-------------|
+| `browser_server_status` | Server status, version, session/cache stats |
+| `browser_cache_stats` | Cache statistics (hits, misses, size) |
+| `browser_clear_cache` | Clear the entire result cache |
+
+### Reverse Engineering (4)
+
+| Tool | Description |
+|------|-------------|
+| `browser_js_beautify` | Beautify and format JavaScript code |
+| `browser_js_deobfuscate` | Deobfuscate JS (hex, unicode, base64) |
+| `browser_api_discover` | Discover API endpoints in JS source |
+| `browser_auth_analyze` | Analyze network logs for auth flows |
+
+### Stealth (2)
+
+| Tool | Description |
+|------|-------------|
+| `browser_fingerprint` | Generate randomized browser fingerprint |
+| `browser_human_behavior` | Generate human-like typing/mouse/scroll profiles |
+
+**Total: 51 tools across 9 categories, production-grade architecture**
+
+---
+
+## Use Cases
+
+- **Reverse Engineering** — Deobfuscate JavaScript, uncover API endpoints, map auth flows, export HAR for offline analysis
+- **Web Scraping** — Extract HTML, Markdown, structured data (Schema.org, Open Graph, tables) from any browser-accessible page
+- **Network Monitoring** — Intercept HTTP/HTTPS traffic in real time, inspect WebSocket frames, save binary bodies to disk
+- **Form Automation** — Login flows, multi-step forms, file uploads, dropdown selections — all driven by AI
+- **Session Management** — Isolated concurrent browser sessions with automatic TTL cleanup
+- **Data Export** — Network captures in HAR/JSON/CSV, body saves, WebSocket frame logs (.jsonl)
+
+---
+
+## Security
+
+- `redirect: 'manual'` on all URL fetches — SSRF redirect bypass protection
+- `validateUrlAsync` with DNS lookup — DNS rebind attack prevention
+- `DANGEROUS_EXTENSIONS` blocklist (`.exe`, `.bat`, `.sh` etc.) → safe `.bin` fallback
+- Pseudo-FS path blocking (`/proc/`, `/sys/`, `/etc/` etc.) — path traversal prevention
+- Cookie header filter — cross-origin credential leakage prevention in HTTP re-fetch
+- `NETWORK_DOWNLOAD_ENABLED` and `NETWORK_SAVE_ENABLED` default to **false** — must be explicitly enabled
+- Input sanitization — null byte, path traversal, fileName injection guards
+- Rate limiting — token bucket algorithm, global + per-tool, configurable RPM
+- LRU cache with TTL — bounded memory usage
+
+---
+
+## Development
+
+```bash
+# Test
+npm test
+npm run test:coverage
+
+# Type check (tsc --noEmit)
+npm run lint
+
+# Build
+npm run build
+```
+
+---
+
+## Roadmap
+
+- **New tools**: PDF extraction, screenshot annotation, form detection, cookie manager, session snapshot/restore
+- **Cloudflare bypass**: Playwright Stealth integration, rotatable proxy support
+- **Batch scraping**: Multi-page scraping pipeline, queue system
+- **Performance**: Ring buffer optimization, streaming responses, lazy evaluation
+- **Developer Experience**: Interactive CLI, playground UI, type-safe client SDK
+
+---
+
+## 🇹🇷 Türkçe
+
+**`@natchs/browser-mcp`** — reverse engineering, web scraping, network interception ve HAR export için tasarlanmış, AI ajanların tarayıcıyı tam kontrol etmesini sağlayan bir Model Context Protocol sunucusu.
+
+```bash
+npm install @natchs/browser-mcp
+npx @natchs/browser-mcp
+```
+
+Üç browser modu: `fresh` (izole), `persistent` (gerçek Chrome profilin, otomatik tespit), `connect` (mevcut Chrome'a bağlan). 50+ araç, 9 kategori, kurumsal güvenlik.
+
+Detaylı bilgi için yukarıdaki İngilizce dokümantasyonu inceleyin.
+
+---
+
+## License
+
+MIT