gsearch-mcp-cli 0.0.1__py3-none-any.whl

gsearch_mcp_cli/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gsearch-mcp-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.1"  # Keep in sync with pyproject.toml

gsearch_mcp_cli/cli/ai_cmd.py

@@ -0,0 +1,83 @@
+import asyncio
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from gsearch_mcp_cli import shared
+from gsearch_mcp_cli.exceptions import GSearchError
+
+console = Console()
+
+
+TIME_CHOICES = click.Choice(["hour", "1h", "12h", "day", "24h", "week", "7d", "month", "year"], case_sensitive=False)
+
+
+@click.command("ai")
+@click.argument("query")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--lang", default="en", help="Search language")
+@click.option("--region", default=None, help="Search region (e.g., US, CA, GB)")
+@click.option("--time", "time_filter", type=TIME_CHOICES, default=None,
+              help="Time filter: hour, day, week, month, year")
+@click.option("--after", "date_from", default=None, help="Results after date (YYYY-MM-DD)")
+@click.option("--before", "date_to", default=None, help="Results before date (YYYY-MM-DD)")
+@click.option("--timeout", default=30, type=float, help="Timeout in seconds")
+def ai_cmd(query, json_output, lang, region, time_filter, date_from, date_to, timeout):
+    """Run a Google AI Mode search and return synthesized results."""
+    async def _run():
+        try:
+            result = await shared.ai_search(
+                query=query,
+                language=lang,
+                region=region,
+                time_filter=time_filter,
+                date_from=date_from,
+                date_to=date_to,
+                timeout=timeout,
+            )
+
+            if json_output:
+                click.echo(result.model_dump_json(indent=2))
+            else:
+                _print_ai_result(result)
+
+        except GSearchError as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise SystemExit(1)
+        finally:
+            await shared.shutdown()
+
+    asyncio.run(_run())
+
+
+def _print_ai_result(result):
+    """Pretty-print AI Mode results with Rich panels."""
+    if result.synthesis:
+        console.print()
+        console.print(Panel(
+            result.synthesis,
+            title=f"AI Synthesis — {result.query}",
+            border_style="green",
+        ))
+
+    if result.sections:
+        for section in result.sections:
+            body_parts = []
+            if section.content:
+                body_parts.append(section.content)
+            if section.items:
+                body_parts.extend(f"  • {item}" for item in section.items)
+            console.print(Panel(
+                "\n".join(body_parts) if body_parts else "[dim]No content[/dim]",
+                title=section.heading,
+                border_style="cyan",
+            ))
+
+    if result.sources:
+        console.print("\n[bold]Sources[/bold]")
+        console.print("─" * 60)
+        for src in result.sources:
+            console.print(f"  [link={src.url}]{src.domain}[/link] — {src.title}")
+
+    console.print()

gsearch_mcp_cli/cli/ai_doc.py

@@ -0,0 +1,88 @@
+AI_DOC = """gsearch-mcp-cli v{version} — Google Search CLI and MCP for AI Agents
+
+SETUP
+  gsearch setup              # One-time profile warmup (~8s)
+  gsearch setup --check      # Verify profile works
+  gsearch setup --reset      # Delete and recreate profile
+  gsearch setup add cursor   # Configure MCP for Cursor
+  gsearch setup add claude-code  # Configure MCP for Claude Code
+  gsearch setup list         # Show all MCP setup targets
+  gsearch doctor             # Diagnose browser, profile, connectivity
+
+SEARCH (default command)
+  gsearch "query"                        # Regular Google search (default)
+  gsearch search "query" --json          # JSON output
+  gsearch search "query" --no-ai         # Skip AI Overview
+  gsearch search "query" -n 5            # Max 5 results
+  gsearch search "query" --lang fr       # French results
+  gsearch search "query" --region CA     # Canadian results
+
+TIME-FILTERED SEARCH (use for news, recent events, time-sensitive queries)
+  gsearch "AI news" --time hour          # Last hour
+  gsearch "AI news" --time 1h            # Last hour (alias)
+  gsearch "news" --time 12h              # Last 12 hours
+  gsearch "news" --time day              # Last 24 hours
+  gsearch "news" --time 24h             # Last 24 hours (alias)
+  gsearch "updates" --time week          # Last 7 days
+  gsearch "updates" --time 7d            # Last 7 days (alias)
+  gsearch "developments" --time month    # Last month
+  gsearch "report" --time year           # Last year
+  gsearch "events" --time 6h             # Last 6 hours (arbitrary)
+  gsearch "earnings" --after 2026-01-01 --before 2026-03-31  # Custom date range
+
+  Time filter values: hour, 1h, 12h, day, 24h, week, 7d, month, 1m, year, 1y
+  Arbitrary hours: any "Nh" pattern (e.g., 3h, 6h, 18h)
+  Custom range: --after YYYY-MM-DD and/or --before YYYY-MM-DD
+
+AI MODE (Google AI Mode / g.ai)
+  gsearch ai "query"                     # AI Mode synthesized response
+  gsearch ai "query" --json              # JSON output
+  gsearch ai "query" --time day          # With time filter
+  gsearch ai "query" --after 2026-01-01  # With date range
+
+FETCH (URL to Markdown)
+  gsearch fetch "url"                    # Fetch and convert to Markdown
+  gsearch fetch "url" --raw              # Plain text output
+  gsearch fetch "url" --json             # JSON with metadata
+  gsearch fetch "url" --browser always   # Force browser rendering
+
+CONFIG
+  gsearch config show                    # Show all settings
+  gsearch config set browser brave       # Set preferred browser
+  gsearch config set rate_limit 1.0      # Search throttle (seconds)
+
+SKILL INSTALL
+  gsearch skill install cursor           # Install for Cursor
+  gsearch skill install claude-code      # Install for Claude Code
+  gsearch skill install cc-claw          # Install for CC-Claw
+  gsearch skill list                     # Show all targets
+
+MCP TOOLS (for AI agents via MCP protocol)
+  gsearch_search(query, max_results=10, include_ai=True, language="en",
+                 time_filter=None, date_from=None, date_to=None, timeout_seconds=30)
+  gsearch_ai(query, language="en",
+             time_filter=None, date_from=None, date_to=None, timeout_seconds=30)
+  gsearch_fetch(url, format="md", use_browser="auto", timeout_seconds=30)
+
+  time_filter: "hour", "12h", "day", "week", "month", "year", or any "Nh" (e.g., "6h")
+  date_from / date_to: "YYYY-MM-DD" for custom date range
+
+WHEN TO USE TIME FILTERS
+  "latest news about X"       -> time_filter="day" or "12h"
+  "what happened today"       -> time_filter="day"
+  "breaking news"             -> time_filter="hour"
+  "recent developments"       -> time_filter="week"
+  "this month's updates"      -> time_filter="month"
+  "between Jan and March"     -> date_from="2026-01-01", date_to="2026-03-31"
+
+NOTES
+  - First run: gsearch setup runs automatically on first search
+  - No Google account needed: anonymous, pseudonymous sessions
+  - Rate limited: 1 search/2s default (configurable)
+  - Headless: no visible browser window
+  - SSRF protection: fetch validates URLs against private IP ranges
+"""
+
+
+def get_ai_doc(version: str) -> str:
+    return AI_DOC.format(version=version)

gsearch_mcp_cli/cli/config_cmd.py

@@ -0,0 +1,64 @@
+"""gsearch config — view and modify configuration."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from gsearch_mcp_cli.config import DEFAULTS, Config
+from gsearch_mcp_cli.exceptions import ConfigError
+
+console = Console()
+
+
+@click.group("config")
+def config_cmd() -> None:
+    """View and modify gsearch configuration."""
+
+
+@config_cmd.command("show")
+def config_show() -> None:
+    """Print all configuration values."""
+    cfg = Config()
+    data = cfg.show()
+
+    table = Table(title="gsearch configuration")
+    table.add_column("Key", style="cyan", no_wrap=True)
+    table.add_column("Value", style="green")
+    table.add_column("Default", style="dim")
+
+    for key in sorted(data):
+        current = data[key]
+        default = DEFAULTS.get(key)
+        style = "" if current == default else "bold yellow"
+        table.add_row(key, str(current), str(default), style=style)
+
+    console.print(table)
+
+
+@config_cmd.command("get")
+@click.argument("key")
+def config_get(key: str) -> None:
+    """Get a single configuration value."""
+    cfg = Config()
+    try:
+        value = cfg.get(key)
+        console.print(f"[cyan]{key}[/] = [green]{value}[/]")
+    except ConfigError as exc:
+        console.print(f"[bold red]Error:[/] {exc}")
+        raise SystemExit(1)
+
+
+@config_cmd.command("set")
+@click.argument("key")
+@click.argument("value")
+def config_set(key: str, value: str) -> None:
+    """Set a configuration value."""
+    cfg = Config()
+    try:
+        cfg.set(key, value)
+        console.print(f"[green]✓[/] Set [cyan]{key}[/] = [green]{cfg.get(key)}[/]")
+    except ConfigError as exc:
+        console.print(f"[bold red]Error:[/] {exc}")
+        raise SystemExit(1)

gsearch_mcp_cli/cli/doctor_cmd.py

@@ -0,0 +1,77 @@
+"""gsearch doctor — run diagnostic checks."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+
+from gsearch_mcp_cli.config import Config
+from gsearch_mcp_cli.constants import CHROME_PROFILE_DIR
+from gsearch_mcp_cli.core.browser import find_browser
+from gsearch_mcp_cli.exceptions import BrowserNotFoundError
+
+console = Console()
+
+PASS = "[bold green]✓[/]"
+FAIL = "[bold red]✗[/]"
+
+
+def _check_browser() -> bool:
+    try:
+        path = find_browser()
+        console.print(f"  {PASS} Browser found: {path}")
+        return True
+    except BrowserNotFoundError as exc:
+        console.print(f"  {FAIL} Browser not found: {exc}")
+        return False
+
+
+def _check_profile_dir() -> bool:
+    if CHROME_PROFILE_DIR.exists():
+        console.print(f"  {PASS} Profile directory exists: {CHROME_PROFILE_DIR}")
+        return True
+    console.print(f"  {FAIL} Profile directory missing: {CHROME_PROFILE_DIR}")
+    return False
+
+
+def _check_warmed_up() -> bool:
+    marker = CHROME_PROFILE_DIR / ".warmed_up"
+    if marker.exists():
+        console.print(f"  {PASS} Profile is warmed up")
+        return True
+    console.print(f"  {FAIL} Profile not warmed up — run: gsearch setup")
+    return False
+
+
+def _check_config() -> bool:
+    try:
+        cfg = Config()
+        cfg.show()
+        console.print(f"  {PASS} Config file valid")
+        return True
+    except Exception as exc:
+        console.print(f"  {FAIL} Config error: {exc}")
+        return False
+
+
+@click.command("doctor")
+def doctor_cmd() -> None:
+    """Run diagnostic checks on gsearch environment."""
+    console.print("[bold]Running diagnostics…[/]\n")
+
+    checks = [
+        ("Browser", _check_browser),
+        ("Profile directory", _check_profile_dir),
+        ("Profile warmup", _check_warmed_up),
+        ("Configuration", _check_config),
+    ]
+
+    passed = sum(1 for _, fn in checks if fn())
+    total = len(checks)
+
+    console.print()
+    if passed == total:
+        console.print(f"[bold green]All {total} checks passed.[/]")
+    else:
+        console.print(f"[bold yellow]{passed}/{total} checks passed.[/]")
+        raise SystemExit(1)

gsearch_mcp_cli/cli/fetch_cmd.py

@@ -0,0 +1,50 @@
+import asyncio
+
+import click
+from rich.console import Console
+
+from gsearch_mcp_cli import shared
+from gsearch_mcp_cli.exceptions import GSearchError
+
+console = Console()
+
+
+@click.command("fetch")
+@click.argument("url")
+@click.option("--raw", is_flag=True, help="Output plain text instead of markdown")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--browser", type=click.Choice(["auto", "always", "never"]),
+              default="auto", help="Browser usage mode")
+@click.option("--timeout", default=30, type=float, help="Timeout in seconds")
+def fetch_cmd(url, raw, json_output, browser, timeout):
+    """Fetch a URL and return its content."""
+    async def _run():
+        try:
+            fmt = "txt" if raw else "md"
+            result = await shared.fetch(
+                url=url,
+                format=fmt,
+                use_browser=browser,
+                timeout=timeout,
+            )
+
+            if json_output:
+                click.echo(result.model_dump_json(indent=2))
+            else:
+                _print_fetch_result(result, raw=raw)
+
+        except GSearchError as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise SystemExit(1)
+        finally:
+            await shared.shutdown()
+
+    asyncio.run(_run())
+
+
+def _print_fetch_result(result, *, raw=False):
+    """Print fetched content."""
+    if not raw:
+        console.print(f"\n[bold]{result.title}[/bold]")
+        console.print(f"[dim]{result.url}  •  {result.word_count} words[/dim]\n")
+    click.echo(result.content)

gsearch_mcp_cli/cli/main.py

@@ -0,0 +1,64 @@
+import click
+
+from gsearch_mcp_cli import __version__
+from gsearch_mcp_cli.cli.ai_cmd import ai_cmd
+from gsearch_mcp_cli.cli.ai_doc import get_ai_doc
+from gsearch_mcp_cli.cli.config_cmd import config_cmd
+from gsearch_mcp_cli.cli.doctor_cmd import doctor_cmd
+from gsearch_mcp_cli.cli.fetch_cmd import fetch_cmd
+from gsearch_mcp_cli.cli.search_cmd import search_cmd
+from gsearch_mcp_cli.cli.setup_cmd import setup_cmd
+from gsearch_mcp_cli.cli.skill_cmd import skill_cmd
+
+
+def _print_docs(ctx, param, value):
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(get_ai_doc(__version__))
+    ctx.exit()
+
+
+class DefaultSearchGroup(click.Group):
+    """Click group that falls back to 'search' for unknown commands."""
+
+    def parse_args(self, ctx, args):
+        if args and not args[0].startswith("-"):
+            if args[0] not in self.commands:
+                args = ["search"] + args
+        return super().parse_args(ctx, args)
+
+
+@click.group(cls=DefaultSearchGroup, invoke_without_command=True)
+@click.version_option(__version__, prog_name="gsearch")
+@click.option("--ai", is_flag=True, callback=_print_docs, expose_value=False,
+              is_eager=True, help="Print AI-optimized documentation")
+@click.option("--verbose", is_flag=True, default=False, help="Enable debug logging")
+@click.pass_context
+def cli(ctx, verbose):
+    """gsearch — Google Search CLI for AI agents."""
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+
+    if verbose:
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+cli.add_command(search_cmd, "search")
+cli.add_command(ai_cmd, "ai")
+cli.add_command(fetch_cmd, "fetch")
+cli.add_command(skill_cmd, "skill")
+cli.add_command(setup_cmd, "setup")
+cli.add_command(config_cmd, "config")
+cli.add_command(doctor_cmd, "doctor")
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

gsearch_mcp_cli/cli/search_cmd.py

@@ -0,0 +1,92 @@
+import asyncio
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+
+from gsearch_mcp_cli import shared
+from gsearch_mcp_cli.exceptions import GSearchError
+
+console = Console()
+
+
+TIME_CHOICES = click.Choice(["hour", "1h", "12h", "day", "24h", "week", "7d", "month", "year"], case_sensitive=False)
+
+
+@click.command("search")
+@click.argument("query")
+@click.option("--max-results", "-n", default=10, help="Max organic results")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--no-ai", is_flag=True, help="Skip AI Overview extraction")
+@click.option("--lang", default="en", help="Search language")
+@click.option("--region", default=None, help="Search region (e.g., US, CA, GB)")
+@click.option("--time", "time_filter", type=TIME_CHOICES, default=None,
+              help="Time filter: hour, day, week, month, year")
+@click.option("--after", "date_from", default=None, help="Results after date (YYYY-MM-DD)")
+@click.option("--before", "date_to", default=None, help="Results before date (YYYY-MM-DD)")
+@click.option("--timeout", default=30, type=float, help="Timeout in seconds")
+def search_cmd(query, max_results, json_output, no_ai, lang, region, time_filter, date_from, date_to, timeout):
+    """Search Google and return results with AI Overview."""
+    async def _run():
+        try:
+            result = await shared.search(
+                query=query,
+                max_results=max_results,
+                include_ai=not no_ai,
+                language=lang,
+                region=region,
+                time_filter=time_filter,
+                date_from=date_from,
+                date_to=date_to,
+                timeout=timeout,
+            )
+
+            if json_output:
+                click.echo(result.model_dump_json(indent=2))
+            else:
+                _print_results(result)
+
+        except GSearchError as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise SystemExit(1)
+        finally:
+            await shared.shutdown()
+
+    asyncio.run(_run())
+
+
+def _print_results(result):
+    """Pretty-print search results with Rich."""
+    if result.ai_overview:
+        console.print()
+        console.print(Panel(
+            result.ai_overview.text[:1000],
+            title="AI Overview",
+            border_style="blue",
+        ))
+        if result.ai_overview.sources:
+            sources = ", ".join(s.domain for s in result.ai_overview.sources)
+            console.print(f"  [dim]Sources: {sources}[/dim]")
+        console.print()
+
+    if result.results:
+        console.print("[bold]Search Results[/bold]")
+        console.print("─" * 60)
+        for r in result.results:
+            console.print(f"\n[bold]{r.position}. {r.title}[/bold]")
+            console.print(f"   [link={r.url}]{r.url}[/link]")
+            if r.snippet:
+                console.print(f"   [dim]{r.snippet[:200]}[/dim]")
+
+    if result.people_also_ask:
+        console.print("\n[bold]People Also Ask[/bold]")
+        console.print("─" * 60)
+        for q in result.people_also_ask:
+            console.print(f"  • {q}")
+
+    if result.related_searches:
+        console.print("\n[bold]Related Searches[/bold]")
+        for q in result.related_searches:
+            console.print(f"  • {q}")
+
+    console.print()