<h2 align="center">Obscura</h2>

<p align="center">
  <strong>Rust-native headless browser with built-in MCP server — no Chrome required</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/rust-1.75%2B-orange" alt="Rust 1.75+" />
  <img src="https://img.shields.io/badge/MCP-stdio-blue" alt="MCP stdio" />
  <img src="https://img.shields.io/badge/version-0.3.0-green" alt="v0.3.0" />
  <img src="https://img.shields.io/badge/license-Apache--2.0-lightgrey" alt="Apache-2.0" />
</p>

---

## What is Obscura?

**Obscura** is a Rust-based headless browser engine that provides both a Chrome DevTools Protocol (CDP) server and an MCP (Model Context Protocol) server. Run web automation, scraping, and AI-agent workflows without Chrome, Chromium, or Node.js — just a single native binary (~40MB) with built-in stealth mode and AI-optimized content extraction.

---

## Why Obscura?

| Feature | Obscura | puppeteer-mcp | playwright-mcp |
|---------|---------|---------------|----------------|
| Chrome required | ❌ No | ✅ Yes | ✅ Yes |
| Binary size | ~40MB | N/A (needs Node+Chrome) | N/A (needs Node+Chromium) |
| Stealth mode | ✅ Built-in | ❌ No | ❌ No |
| AI-native extraction | ✅ LP domain | ❌ No | ❌ No |
| Language | Rust | Node.js | Node.js |
| Dep. services | ❌ None | Node.js ecosystem | Node.js ecosystem |

---

## Quick Start

### Download prebuilt binary (recommended)

**Linux x86_64:**
```bash
curl -fsSL https://github.com/SmongsDev/my-obscura-mcp/releases/latest/download/obscura-x86_64-unknown-linux-gnu.tar.gz | tar xz
chmod +x obscura && sudo mv obscura /usr/local/bin/
obscura --version
```

**Linux ARM64:**
```bash
curl -fsSL https://github.com/SmongsDev/my-obscura-mcp/releases/latest/download/obscura-aarch64-unknown-linux-gnu.tar.gz | tar xz
chmod +x obscura && sudo mv obscura /usr/local/bin/
obscura --version
```

**macOS (Apple Silicon):**
```bash
curl -fsSL https://github.com/SmongsDev/my-obscura-mcp/releases/latest/download/obscura-aarch64-apple-darwin.tar.gz | tar xz
chmod +x obscura && sudo mv obscura /usr/local/bin/
obscura --version
```

**macOS (Intel):**
```bash
curl -fsSL https://github.com/SmongsDev/my-obscura-mcp/releases/latest/download/obscura-x86_64-apple-darwin.tar.gz | tar xz
chmod +x obscura && sudo mv obscura /usr/local/bin/
obscura --version
```

**Windows (PowerShell):**
```powershell
$ProgressPreference = 'SilentlyContinue'
Invoke-WebRequest -Uri "https://github.com/SmongsDev/my-obscura-mcp/releases/latest/download/obscura-x86_64-pc-windows-msvc.zip" -OutFile obscura.zip
Expand-Archive obscura.zip -DestinationPath .
.\obscura.exe --version
```

---

## Build from Source

**Prerequisites**: Rust 1.75+ (install via [rustup.rs](https://rustup.rs))

```bash
cargo build --release
```

**Note**: First build takes ~5 minutes due to V8 compilation. Subsequent builds use cached artifacts.

The binary will be at `target/release/obscura`.

---

## MCP Setup

### Claude Desktop (macOS / Linux / Windows)

Edit `~/.config/Claude/claude_desktop_config.json` (or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "obscura": {
      "command": "~/.cargo/bin/obscura",
      "args": ["mcp"]
    }
  }
}
```

**Note**: Replace `~/.cargo/bin/obscura` with the full path to your binary if it's not in the default Cargo installation directory.

Restart Claude Desktop. Obscura tools will appear in the Tools panel.

### Cursor

Edit `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "obscura": {
      "command": "~/.cargo/bin/obscura",
      "args": ["mcp"]
    }
  }
}
```

Restart Cursor.

### Claude Code (CLI)

Add to your Claude Code settings:

```bash
# ~/.claude/settings.json or ~/.claude/settings.local.json
{
  "mcpServers": {
    "obscura": {
      "command": "~/.cargo/bin/obscura",
      "args": ["mcp"]
    }
  }
}
```

Then restart the Claude Code CLI.

---

## Available Tools

All 29 tools (22 existing + 7 new in v0.3.0):

| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL. Call this first before any extraction. |
| `browser_evaluate` | Evaluate a JavaScript expression on the current page. |
| `browser_get_page_status` | Fetch current URL, page title, and lifecycle state (Idle/Loading/Loaded/NetworkIdle). |
| `browser_get_html` | Get the full page source HTML. |
| `browser_get_markdown` | Convert page to Markdown format. |
| `browser_get_readable_content` | Extract main article text, removing ads and navigation. Returns text + word count. |
| `browser_get_metadata` | Extract meta tags: title, description, OG (Open Graph), Twitter Card, canonical URL, etc. |
| `browser_get_links` | Get all links on page as array of `{ href, text }`. All URLs converted to absolute. |
| `browser_get_forms` | Extract form structure: input types, labels, select options, field names. |
| `browser_get_table_data` | Convert HTML tables to structured JSON with header-based keys. |
| `browser_get_structured_data` | Extract JSON-LD, OpenGraph, and microdata schemas. |
| `browser_get_element_text` | Get text content of an element by CSS selector. |
| `browser_get_element_attribute` | Read HTML attribute value (href, src, data-*, etc.) by CSS selector. |
| `browser_click` | Click an element by CSS selector. Triggers click events. |
| `browser_type_text` | Type text into an input field. Triggers input/change events. |
| `browser_select` | Select an option in a `<select>` dropdown by value or visible text. |
| `browser_get_elements` | Query multiple elements by CSS selector, return array of `{ text, attributes }`. |
| `browser_get_headings` | Extract all headings (h1–h6) as array of `{ level, text }`. |
| `browser_get_all_images` | Get all images with `{ src, alt, title, width, height }`. |
| `browser_find_text` | Find elements containing keyword text. Returns tag, id, class, and text (max 50 matches). |
| `browser_scroll` | Scroll to coordinates or element into view. Useful for lazy-loaded content. |
| `browser_keyboard_press` | Dispatch keyboard events (Enter, Escape, etc.) to focused element or target by selector. |
| `browser_navigate_and_extract` | Combine navigate + readable_content in one call (reduces round-trips). |
| `browser_get_console_logs` | Capture all `console.log/warn/error` output from the page. |
| `browser_set_emulation` | Spoof User-Agent, viewport dimensions. Use for mobile page access. |
| `browser_wait_for_selector` * | Wait for an element to appear in the DOM (useful for async rendering). |
| `browser_get_cookies` * | Retrieve all cookies for the current page. |
| `browser_set_cookie` * | Set a cookie (name, value, domain, path, expiry, etc.). |
| `browser_delete_cookie` * | Delete a cookie by name. |
| `browser_get_local_storage` * | Fetch all localStorage items for the current origin. |
| `browser_set_local_storage` * | Set a localStorage key–value pair. |
| `browser_clear_storage` * | Clear localStorage and sessionStorage. |

**\* = New in v0.3.0**

### Stealth Mode

Obscura includes built-in stealth mode to avoid bot detection. Use the `--stealth` flag when starting:

```bash
obscura mcp --stealth
```

Or set via CDP/MCP requests. Stealth mode spoofs TLS fingerprints and browser identifiers.

---

## License

Apache 2.0 — see [LICENSE](LICENSE)

---

<details>
<summary>한국어</summary>

## 개요

**Obscura**는 Chrome 없이 웹 자동화, 스크래핑, AI 에이전트 워크플로우를 실행할 수 있는 Rust 기반 헤드리스 브라우저 엔진입니다. CDP(Chrome DevTools Protocol) 서버와 MCP(Model Context Protocol) 서버를 제공하며, 단일 네이티브 바이너리(~40MB)로 구동되며 내장 스텔스 모드와 AI 최적화 콘텐츠 추출 기능을 갖추고 있습니다.

---

## 제공 도구

모든 29개 도구 (기존 22개 + v0.3.0 신규 7개):

| 도구 | 설명 |
|------|------|
| `browser_navigate` | URL 탐색. 다른 도구 사용 전 반드시 먼저 호출 |
| `browser_evaluate` | 현재 페이지에서 JS 표현식 평가 |
| `browser_get_page_status` | 현재 URL / 제목 / 라이프사이클 상태 |
| `browser_get_html` | 페이지 원본 HTML |
| `browser_get_markdown` | 페이지 → Markdown 변환 |
| `browser_get_readable_content` | 광고·네비게이션 제거 후 본문 텍스트 + 단어 수 |
| `browser_get_metadata` | 제목, 설명, OG 태그, Twitter Card, 카노니컬 URL 등 |
| `browser_get_links` | 페이지 내 전체 링크 (절대 URL 변환 포함) |
| `browser_get_forms` | 폼 필드 구조 (입력 타입, 레이블, 셀렉트 옵션 등) |
| `browser_get_table_data` | 표 → 헤더 키 기반 구조화 JSON |
| `browser_get_structured_data` | JSON-LD / OpenGraph / microdata 추출 |
| `browser_get_element_text` | CSS 셀렉터로 요소 텍스트 추출 |
| `browser_get_element_attribute` | CSS 셀렉터로 속성값 읽기 (href, src, data-* 등) |
| `browser_click` | CSS 셀렉터로 요소 클릭 |
| `browser_type_text` | 입력 필드에 텍스트 입력 (input/change 이벤트 발생) |
| `browser_select` | `<select>` 드롭다운 옵션 선택 (값 또는 텍스트로 매칭) |
| `browser_get_elements` | `querySelectorAll`로 여러 요소의 텍스트·속성 배열 반환 |
| `browser_get_headings` | h1~h6 전체를 `[{ level, text }]` JSON으로 반환 |
| `browser_get_all_images` | img 태그의 src, alt, title, width, height 목록 |
| `browser_find_text` | 키워드 포함 요소 텍스트·태그·id·클래스명 반환 (최대 50건) |
| `browser_scroll` | 좌표 스크롤 또는 요소 `scrollIntoView` (lazy load 트리거용) |
| `browser_keyboard_press` | CSS 셀렉터 요소 또는 포커스 요소에 키보드 이벤트 디스패치 |
| `browser_navigate_and_extract` | navigate + readable_content 단일 호출로 라운드트립 절감 |
| `browser_get_console_logs` | 페이지 JS `console.*` 캡처 로그 배열 반환 |
| `browser_set_emulation` | User-Agent·뷰포트 너비/높이 설정 (모바일 페이지 접근용) |
| `browser_wait_for_selector` * | DOM에 요소가 나타날 때까지 대기 (비동기 렌더링용) |
| `browser_get_cookies` * | 현재 페이지의 모든 쿠키 조회 |
| `browser_set_cookie` * | 쿠키 설정 (이름, 값, 도메인, 경로, 만료 등) |
| `browser_delete_cookie` * | 쿠키 삭제 |
| `browser_get_local_storage` * | 현재 origin의 localStorage 전체 조회 |
| `browser_set_local_storage` * | localStorage 키–값 쌍 설정 |
| `browser_clear_storage` * | localStorage·sessionStorage 전체 삭제 |

**\* = v0.3.0 신규**

---

## 스택

- **언어**: Rust 1.75+ · Tokio `current_thread`
- **JS 엔진**: Deno Core / V8
- **HTML 파싱**: html5ever
- **MCP 프레임워크**: rmcp

---

## 라이선스

Apache 2.0 — [LICENSE](LICENSE) 참고

</details>