gsearch-mcp-cli 0.0.1__tar.gz

gsearch_mcp_cli-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,167 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Run tests
+        run: uv run pytest tests/ -v -k "not integration"
+
+  build:
+    name: Build package
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Verify all versions match tag
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          ERRORS=0
+
+          # 1. pyproject.toml
+          TOML_VERSION=$(grep -oP '(?<=^version = ")[^"]+' pyproject.toml)
+          if [ "$TOML_VERSION" != "$TAG_VERSION" ]; then
+            echo "❌ pyproject.toml version ($TOML_VERSION) != tag ($TAG_VERSION)"
+            ERRORS=$((ERRORS + 1))
+          else
+            echo "✅ pyproject.toml: $TOML_VERSION"
+          fi
+
+          # 2. __init__.py fallback
+          INIT_VERSION=$(grep -oP '(?<=__version__ = ")[^"]+' src/gsearch_mcp_cli/__init__.py)
+          if [ "$INIT_VERSION" != "$TAG_VERSION" ]; then
+            echo "❌ __init__.py fallback ($INIT_VERSION) != tag ($TAG_VERSION)"
+            ERRORS=$((ERRORS + 1))
+          else
+            echo "✅ __init__.py: $INIT_VERSION"
+          fi
+
+          # 3. SKILL.md frontmatter
+          SKILL_VERSION=$(grep -oP '(?<=^version: ")[^"]+' src/gsearch_mcp_cli/data/SKILL.md)
+          if [ "$SKILL_VERSION" != "$TAG_VERSION" ]; then
+            echo "❌ SKILL.md version ($SKILL_VERSION) != tag ($TAG_VERSION)"
+            ERRORS=$((ERRORS + 1))
+          else
+            echo "✅ SKILL.md: $SKILL_VERSION"
+          fi
+
+          if [ "$ERRORS" -gt 0 ]; then
+            echo ""
+            echo "VERSION MISMATCH: Update all 3 files before tagging:"
+            echo "  1. pyproject.toml  -> version = \"$TAG_VERSION\""
+            echo "  2. src/gsearch_mcp_cli/__init__.py -> __version__ = \"$TAG_VERSION\""
+            echo "  3. src/gsearch_mcp_cli/data/SKILL.md -> version: \"$TAG_VERSION\""
+            exit 1
+          fi
+
+          echo ""
+          echo "All versions match: $TAG_VERSION ✅"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gsearch-mcp-cli
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          VERSION="v${{ steps.version.outputs.VERSION }}"
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || git rev-list --max-parents=0 HEAD)
+
+          {
+            echo "## What's Changed"
+            echo ""
+            echo "| Date (UTC) | Commit Message | Link |"
+            echo "|------------|----------------|------|"
+            git log --date=iso-strict --pretty=format:"| %ad | %s | [\`%h\`](https://github.com/${{ github.repository }}/commit/%H) |" $PREVIOUS_TAG..HEAD | tac
+            echo ""
+            echo ""
+            echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/$PREVIOUS_TAG...$VERSION"
+          } > changelog.md
+
+          echo "changelog<<EOF" >> $GITHUB_OUTPUT
+          cat changelog.md >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: v${{ steps.version.outputs.VERSION }}
+          body: ${{ steps.changelog.outputs.changelog }}
+          files: dist/*
+          draft: false
+          prerelease: false

gsearch_mcp_cli-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.coverage
+htmlcov/

gsearch_mcp_cli-0.0.1/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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.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

gsearch_mcp_cli-0.0.1/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: gsearch-mcp-cli
+Version: 0.0.1
+Summary: Google Search CLI and MCP server for AI agents
+Project-URL: Homepage, https://github.com/jacob-bd/gsearch-mcp-cli
+Project-URL: Repository, https://github.com/jacob-bd/gsearch-mcp-cli
+Project-URL: Issues, https://github.com/jacob-bd/gsearch-mcp-cli/issues
+Project-URL: Changelog, https://github.com/jacob-bd/gsearch-mcp-cli/blob/main/CHANGELOG.md
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: fastmcp>=0.1
+Requires-Dist: html-to-markdown>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: orjson>=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich-click>=1.7
+Requires-Dist: rich>=13.0
+Requires-Dist: trafilatura>=1.8
+Requires-Dist: truststore>=0.9
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest-mock>=3.12; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gsearch-mcp-cli
+
+Google Search CLI and MCP server for AI agents. Search Google (regular + AI Mode), fetch web pages as Markdown, with time filtering. No Google account needed.
+
+## Install
+
+```bash
+pip install gsearch-mcp-cli
+```
+
+Or with uv / pipx:
+
+```bash
+uv pip install gsearch-mcp-cli    # uv
+pipx install gsearch-mcp-cli      # pipx (isolated)
+```
+
+Run without installing:
+
+```bash
+uvx --from gsearch-mcp-cli gsearch "your query"
+```
+
+**Requirements:** A Chromium-based browser (Chrome, Brave, Edge, Chromium, Vivaldi, or Opera).
+
+## Quick Start
+
+```bash
+gsearch setup                              # one-time profile warmup (~8s)
+gsearch "what is kubernetes"               # search Google
+gsearch "AI news" --time day               # last 24 hours
+gsearch "breaking news" --time 1h          # last hour
+gsearch ai "explain docker architecture"   # AI Mode (g.ai)
+gsearch fetch "https://example.com"        # page to Markdown
+```
+
+## Time Filtering
+
+Filter results by time period -- critical for news and recent events:
+
+```bash
+gsearch "query" --time hour      # last hour
+gsearch "query" --time 12h       # last 12 hours
+gsearch "query" --time day       # last 24 hours
+gsearch "query" --time week      # last 7 days
+gsearch "query" --time month     # last month
+gsearch "query" --time year      # last year
+gsearch "query" --after 2026-01-01 --before 2026-03-31  # custom range
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gsearch "query"` | Google Search (default) with AI Overview + organic results |
+| `gsearch ai "query"` | Google AI Mode -- synthesized answer with citations |
+| `gsearch fetch "url"` | Fetch URL and convert to clean Markdown |
+| `gsearch setup` | Browser profile warmup (one-time) |
+| `gsearch setup add <tool>` | Configure MCP server for an AI tool |
+| `gsearch config show` | Show configuration |
+| `gsearch doctor` | Run diagnostics |
+| `gsearch skill install <tool>` | Install skill for AI tools |
+| `gsearch --ai` | Print AI-optimized documentation |
+
+## MCP Server
+
+For AI agents via Model Context Protocol:
+
+```bash
+gsearch-mcp                       # start MCP server (stdio)
+gsearch setup add cursor          # configure for Cursor
+gsearch setup add claude-code     # configure for Claude Code
+```
+
+**MCP Tools:**
+
+- `gsearch_search(query, time_filter="day", ...)` -- Google Search
+- `gsearch_ai(query, time_filter="week", ...)` -- AI Mode
+- `gsearch_fetch(url, format="md", ...)` -- Fetch page as Markdown
+
+## How It Works
+
+Uses headless Chrome via CDP (Chrome DevTools Protocol) with a persistent anonymous profile. Google's BotGuard requires a warmed-up browser session -- `gsearch setup` establishes this once. No Google account or login needed.
+
+## Supported AI Tools
+
+**MCP Setup** (`gsearch setup add`): Claude Code, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, Codex, OpenCode
+
+**Skill Install** (`gsearch skill install`): Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity, Cline, OpenClaw, CC-Claw
+
+## License
+
+MIT

gsearch_mcp_cli-0.0.1/README.md

@@ -0,0 +1,93 @@
+# gsearch-mcp-cli
+
+Google Search CLI and MCP server for AI agents. Search Google (regular + AI Mode), fetch web pages as Markdown, with time filtering. No Google account needed.
+
+## Install
+
+```bash
+pip install gsearch-mcp-cli
+```
+
+Or with uv / pipx:
+
+```bash
+uv pip install gsearch-mcp-cli    # uv
+pipx install gsearch-mcp-cli      # pipx (isolated)
+```
+
+Run without installing:
+
+```bash
+uvx --from gsearch-mcp-cli gsearch "your query"
+```
+
+**Requirements:** A Chromium-based browser (Chrome, Brave, Edge, Chromium, Vivaldi, or Opera).
+
+## Quick Start
+
+```bash
+gsearch setup                              # one-time profile warmup (~8s)
+gsearch "what is kubernetes"               # search Google
+gsearch "AI news" --time day               # last 24 hours
+gsearch "breaking news" --time 1h          # last hour
+gsearch ai "explain docker architecture"   # AI Mode (g.ai)
+gsearch fetch "https://example.com"        # page to Markdown
+```
+
+## Time Filtering
+
+Filter results by time period -- critical for news and recent events:
+
+```bash
+gsearch "query" --time hour      # last hour
+gsearch "query" --time 12h       # last 12 hours
+gsearch "query" --time day       # last 24 hours
+gsearch "query" --time week      # last 7 days
+gsearch "query" --time month     # last month
+gsearch "query" --time year      # last year
+gsearch "query" --after 2026-01-01 --before 2026-03-31  # custom range
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gsearch "query"` | Google Search (default) with AI Overview + organic results |
+| `gsearch ai "query"` | Google AI Mode -- synthesized answer with citations |
+| `gsearch fetch "url"` | Fetch URL and convert to clean Markdown |
+| `gsearch setup` | Browser profile warmup (one-time) |
+| `gsearch setup add <tool>` | Configure MCP server for an AI tool |
+| `gsearch config show` | Show configuration |
+| `gsearch doctor` | Run diagnostics |
+| `gsearch skill install <tool>` | Install skill for AI tools |
+| `gsearch --ai` | Print AI-optimized documentation |
+
+## MCP Server
+
+For AI agents via Model Context Protocol:
+
+```bash
+gsearch-mcp                       # start MCP server (stdio)
+gsearch setup add cursor          # configure for Cursor
+gsearch setup add claude-code     # configure for Claude Code
+```
+
+**MCP Tools:**
+
+- `gsearch_search(query, time_filter="day", ...)` -- Google Search
+- `gsearch_ai(query, time_filter="week", ...)` -- AI Mode
+- `gsearch_fetch(url, format="md", ...)` -- Fetch page as Markdown
+
+## How It Works
+
+Uses headless Chrome via CDP (Chrome DevTools Protocol) with a persistent anonymous profile. Google's BotGuard requires a warmed-up browser session -- `gsearch setup` establishes this once. No Google account or login needed.
+
+## Supported AI Tools
+
+**MCP Setup** (`gsearch setup add`): Claude Code, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, Codex, OpenCode
+
+**Skill Install** (`gsearch skill install`): Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity, Cline, OpenClaw, CC-Claw
+
+## License
+
+MIT