@natchs/browser-mcp 2.3.1 → 2.5.0

package/README.md

@@ -1,190 +1,367 @@
-# @natchs/browser-mcp
-
-**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"
-      }
-    }
-  }
-}
-```
-
----
-
-## 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` varsayılan **false** — kullanıcı açıkça enable etmeden download ç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
+# @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

package/dist/core/audit-logger.d.ts

@@ -0,0 +1,3 @@
+export type AuditEvent = 'AUTH_FAILURE' | 'SANDBOX_VIOLATION' | 'FILE_ACCESS' | 'DNS_REBIND' | 'INTERNAL_IP' | 'PATH_TRAVERSAL';
+export declare function auditLog(event: AuditEvent, details: Record<string, unknown>): void;
+//# sourceMappingURL=audit-logger.d.ts.map

package/dist/core/audit-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.d.ts","sourceRoot":"","sources":["../../src/core/audit-logger.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,mBAAmB,GAAG,aAAa,GAAG,YAAY,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAEhI,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAElF"}

package/dist/core/audit-logger.js

@@ -0,0 +1,5 @@
+import { logger } from './logger.js';
+export function auditLog(event, details) {
+    logger.warn(`[AUDIT] ${event}`, details);
+}
+//# sourceMappingURL=audit-logger.js.map

package/dist/core/audit-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.js","sourceRoot":"","sources":["../../src/core/audit-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC,MAAM,UAAU,QAAQ,CAAC,KAAiB,EAAE,OAAgC;IAC1E,MAAM,CAAC,IAAI,CAAC,WAAW,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/dist/core/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/core/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAiBhE"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/core/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CA2ChE"}

package/dist/core/auth.js

@@ -1,3 +1,5 @@
+import * as crypto from 'node:crypto';
+import { auditLog } from './audit-logger.js';
 /**
  * Creates an auth middleware that checks apiKey.
  * If apiKey is not set, the middleware passes through (no auth).
@@ -5,7 +7,33 @@
 export function createAuthMiddleware(apiKey) {
     return async (pc, next) => {
         if (apiKey) {
-            if (!pc.args.api_key || pc.args.api_key !== apiKey) {
+            if (!pc.args.api_key) {
+                auditLog('AUTH_FAILURE', { reason: 'missing_key', tool: pc.toolName });
+                return {
+                    ...pc,
+                    response: {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({ ok: false, error: { code: 'UNAUTHORIZED', message: 'Invalid or missing API key' } }),
+                            }],
+                    },
+                };
+            }
+            const providedKey = String(pc.args.api_key);
+            if (providedKey.length !== apiKey.length) {
+                auditLog('AUTH_FAILURE', { reason: 'length_mismatch', tool: pc.toolName });
+                return {
+                    ...pc,
+                    response: {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({ ok: false, error: { code: 'UNAUTHORIZED', message: 'Invalid or missing API key' } }),
+                            }],
+                    },
+                };
+            }
+            if (!crypto.timingSafeEqual(Buffer.from(providedKey), Buffer.from(apiKey))) {
+                auditLog('AUTH_FAILURE', { reason: 'key_mismatch', tool: pc.toolName });
                 return {
                     ...pc,
                     response: {

package/dist/core/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/core/auth.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAe;IAClD,OAAO,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACxB,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;gBACnD,OAAO;oBACL,GAAG,EAAE;oBACL,QAAQ,EAAE;wBACR,OAAO,EAAE,CAAC;gCACR,IAAI,EAAE,MAAe;gCACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,4BAA4B,EAAE,EAAE,CAAC;6BAC5G,CAAC;qBACH;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/core/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAe;IAClD,OAAO,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;QACxB,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACrB,QAAQ,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACvE,OAAO;oBACL,GAAG,EAAE;oBACL,QAAQ,EAAE;wBACR,OAAO,EAAE,CAAC;gCACR,IAAI,EAAE,MAAe;gCACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,4BAA4B,EAAE,EAAE,CAAC;6BAC5G,CAAC;qBACH;iBACF,CAAC;YACJ,CAAC;YACD,MAAM,WAAW,GAAG,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,WAAW,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;gBACzC,QAAQ,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAC3E,OAAO;oBACL,GAAG,EAAE;oBACL,QAAQ,EAAE;wBACR,OAAO,EAAE,CAAC;gCACR,IAAI,EAAE,MAAe;gCACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,4BAA4B,EAAE,EAAE,CAAC;6BAC5G,CAAC;qBACH;iBACF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;gBAC3E,QAAQ,CAAC,cAAc,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACxE,OAAO;oBACL,GAAG,EAAE;oBACL,QAAQ,EAAE;wBACR,OAAO,EAAE,CAAC;gCACR,IAAI,EAAE,MAAe;gCACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,4BAA4B,EAAE,EAAE,CAAC;6BAC5G,CAAC;qBACH;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/body-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"body-fetch.d.ts","sourceRoot":"","sources":["../../src/core/body-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,qBAAa,gBAAgB;IACf,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEnC,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC;CA0DrK"}
+{"version":3,"file":"body-fetch.d.ts","sourceRoot":"","sources":["../../src/core/body-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAMxC,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACjC,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,qBAAa,gBAAgB;IACf,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAEnC,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,eAAe,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC;CAgFrK"}