# Changelog

All notable changes to gsearch-mcp-cli will be documented in this file.

Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.0.3] - 2026-03-22

### Fixed

- **`--type news` + `--json` returns empty results** — Google's News tab (`tbm=nws`) uses `role="heading"` instead of `h3` elements, so the standard DOM extractor found nothing. Added `NEWS_EXTRACT_JS` with two-strategy extraction (role="heading" primary, external-link fallback) and automatic routing when `search_type="news"`

## [0.0.2] - 2026-03-22

### Added

- **Search type filtering** -- `--type` flag for news, images, videos, shopping, books, forums, short_videos. Combines with time filters for powerful queries like `gsearch "AI news" --type news --time day`
- **Granular time filters** -- 12h, arbitrary Nh patterns (e.g., 6h), and aliases (1h, 24h, 7d, 1w, 1m, 1y)
- **MCP setup command** -- `gsearch setup add <tool>` configures MCP server for Claude Code, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, Codex, OpenCode
- **Expanded skill targets** -- cc-claw, opencode, antigravity, cline, agents, other (11 total)
- **Default command** -- `gsearch "query"` works without typing `search`
- **Date range filtering** -- `--after` and `--before` flags with YYYY-MM-DD format

### Fixed

- Lint clean (ruff) across all source and test files
- CDP test race condition on Python 3.11
- `uv tool install` in README (was `uv pip install`)
- `--ai` flag restored (was incorrectly renamed to `--docs`)

## [0.0.1] - 2026-03-22

### Added

- **Google Search** (`gsearch search` / `gsearch "query"`) — regular Google search with AI Overview, organic results, People Also Ask, and related searches
- **Google AI Mode** (`gsearch ai`) — synthesized AI response with structured sections and cited sources, equivalent to g.ai
- **Page Fetching** (`gsearch fetch`) — fetch any URL and convert to clean Markdown using trafilatura + html-to-markdown. SSRF-safe with IPv4/IPv6 validation
- **MCP Server** (`gsearch-mcp`) — 3 tools: `gsearch_search`, `gsearch_ai`, `gsearch_fetch` for AI agent integration via Model Context Protocol
- **Time/Date Filtering** — `--time` flag (hour, 1h, 12h, day, 24h, week, 7d, month, year) and `--after`/`--before` for custom date ranges. Supports arbitrary `Nh` patterns (e.g., 6h = last 6 hours)
- **Browser Automation** — headless Chrome via CDP (Chrome DevTools Protocol) with persistent warmed profile. No authentication needed
- **Multi-Browser Support** — auto-detects Chrome, Brave, Edge, Chromium, Vivaldi, Opera, Opera GX on macOS, Linux, and Windows
- **MCP Setup** (`gsearch setup add`) — configure MCP server for Claude Code, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, Codex, and OpenCode
- **Skill Installer** (`gsearch skill install`) — install SKILL.md for Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity, Cline, OpenClaw, CC-Claw, and generic agents
- **Profile Warmup** (`gsearch setup`) — one-time ~8s warmup establishes BotGuard trust cookies for anonymous Google access
- **Configuration** (`gsearch config`) — persistent config for browser preference, language, region, rate limits, timeouts
- **Diagnostics** (`gsearch doctor`) — check browser, profile, config, and connectivity
- **Rate Limiting** — built-in token bucket (default 1 search/2s, burst of 3) to prevent Google blocking
- **Crash Recovery** — auto-relaunch Chrome on CDP connection failure
- **Tab Context Manager** — guaranteed tab cleanup on error, max 5 concurrent tabs
- **Error Sanitization** — MCP responses strip file paths, PIDs, and port numbers
- **JSON Output** — `--json` flag on all search/fetch commands for programmatic use
- **AI Documentation** — `gsearch --docs` prints LLM-optimized reference for AI agents

### Security

- SSRF prevention in `gsearch fetch`: scheme whitelist (http/https only), private IP blocklist, DNS pre-resolution, IPv6 validation
- CDP restricted to `--remote-allow-origins=http://localhost`
- TOCTOU-safe port allocation via `--remote-debugging-port=0` + stderr parsing
- Error sanitization prevents information leakage to MCP clients

### Technical

- Python 3.10+, async throughout (websockets library for CDP)
- Pydantic BaseModel for all data models with automatic JSON serialization
- Single shared backend (`shared.py`) serves both CLI and MCP
- Click + rich-click for CLI, FastMCP for MCP server
- 86 unit tests, 1 integration test
