contextual-engine 0.1.0__py3-none-any.whl

contextual/cli_docs.py

@@ -0,0 +1,685 @@
+"""Phase 2 CLI extensions for Contextual.
+
+Adds to the existing Typer app (``contextual/cli.py``):
+
+  Docs sub-commands:
+    contextual docs index   — index all markdown/RST docs in a repo
+    contextual docs search  — search indexed docs from the terminal
+    contextual docs files   — list all indexed doc files
+
+  Setup sub-commands (one per MCP client):
+    contextual setup claude-desktop
+    contextual setup claude-code
+    contextual setup cursor
+    contextual setup vscode
+    contextual setup gemini-cli
+    contextual setup antigravity
+
+HOW TO WIRE INTO cli.py
+========================
+Add at the bottom of ``contextual/cli.py``:
+
+    from contextual.cli_docs import docs_app, setup_app
+    app.add_typer(docs_app,  name="docs",  help="Index and search documentation.")
+    app.add_typer(setup_app, name="setup", help="Configure Contextual in your IDE/AI client.")
+
+Nothing else needs to change. The existing ``app`` stays untouched.
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shlex
+import shutil
+import subprocess
+import sys
+import textwrap
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated, Optional
+
+import structlog
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn
+from rich.table import Table
+
+logger = structlog.get_logger(__name__)
+console = Console()
+err_console = Console(stderr=True)
+
+# ---------------------------------------------------------------------------
+# Sub-app roots
+# ---------------------------------------------------------------------------
+
+docs_app  = typer.Typer(no_args_is_help=True)
+setup_app = typer.Typer(no_args_is_help=True)
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _resolve_repo(path: Optional[Path]) -> Path:
+    repo = (path or Path.cwd()).resolve()
+    contextual_dir = repo / ".contextual"
+    if not contextual_dir.exists():
+        console.print(
+            f"[red]✗[/red] Repository not initialised. Run [bold]contextual init[/bold] first."
+        )
+        raise typer.Exit(1)
+    return repo
+
+
+def _get_pipeline(repo_path: Path) -> DocsPipeline:
+    """Initialize DocsPipeline with its own embedder and DB pool."""
+    from contextual.docs.pipeline import DocsPipeline
+    from contextual.embedding import get_docs_embedder
+    from contextual.storage.sqlite_pool import SQLitePool
+
+    db_path = repo_path / ".contextual" / "contextual.db"
+    pool = SQLitePool(db_path)
+    embedder = get_docs_embedder()
+    return DocsPipeline(repo_root=repo_path, pool=pool, embedder=embedder)
+
+
+# ---------------------------------------------------------------------------
+# docs index
+# ---------------------------------------------------------------------------
+
+@docs_app.command("index")
+def docs_index(
+    path: Annotated[
+        Optional[Path],
+        typer.Argument(help="Repository path (default: current directory)"),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Re-index all files, ignore content hash cache."),
+    ] = False,
+    watch: Annotated[
+        bool,
+        typer.Option("--watch", "-w", help="Keep running and watch for file changes."),
+    ] = False,
+) -> None:
+    """Index all documentation files (.md, .mdx, .rst, .txt) in a repository.
+
+    Runs heading-aware chunking, embeds chunks, and stores them alongside
+    Phase 1 code chunks in the same SQLite database.
+
+    Set CONTEXTUAL_DOCS_ENABLED=1 to activate docs tools in the MCP server.
+    """
+    repo = _resolve_repo(path)
+    pipeline = _get_pipeline(repo)
+
+    console.print(f"\n[bold cyan]Contextual Docs Indexer[/bold cyan]")
+    console.print(f"  Repository : [dim]{repo}[/dim]")
+    console.print(f"  Force      : [dim]{force}[/dim]\n")
+
+    discovered_count: list[int] = [0]
+
+    def _progress_cb(current: int, total: int, filename: str) -> None:
+        if total > 0 and discovered_count[0] != total:
+            discovered_count[0] = total
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
+        console=console,
+        transient=True,
+    ) as progress:
+        task = progress.add_task("Indexing docs…", total=None)
+
+        def _cb(current: int, total: int, filename: str) -> None:
+            progress.update(task, total=total, completed=current, description=f"[cyan]{filename}[/cyan]")
+
+        pipeline._progress = _cb  # type: ignore[attr-defined]
+        stats = pipeline.index_all(force=force)
+
+    # Summary panel
+    summary = Table.grid(padding=(0, 2))
+    summary.add_row("[green]✓ Files indexed[/green]",     str(stats.files_indexed))
+    summary.add_row("[dim]  Unchanged (skipped)[/dim]",   str(stats.files_skipped_unchanged))
+    summary.add_row("[red]  Failed[/red]",                str(stats.files_failed))
+    summary.add_row("[cyan]  Chunks created[/cyan]",      str(stats.chunks_created))
+    summary.add_row("[dim]  Duration[/dim]",              f"{stats.duration_seconds:.2f}s")
+    console.print(Panel(summary, title="Docs Index Complete", border_style="cyan"))
+
+    if stats.files_indexed > 0:
+        console.print(
+            "\n[dim]Tip:[/dim] Set [bold]CONTEXTUAL_DOCS_ENABLED=1[/bold] to activate "
+            "docs tools in your MCP server config.\n"
+        )
+
+    if watch:
+        _run_docs_watch(repo, pipeline)
+
+
+def _run_docs_watch(repo: Path, pipeline) -> None:
+    """Start a blocking docs file watcher loop."""
+    from contextual.docs.watcher import DocsFileWatcher
+
+    console.print(f"\n[bold]Watching[/bold] [cyan]{repo}[/cyan] for doc changes…")
+    console.print("[dim]Press Ctrl+C to stop.[/dim]\n")
+
+    watcher = DocsFileWatcher(repo, pipeline)
+    watcher.start()
+    try:
+        import time
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        watcher.stop()
+        console.print("\n[dim]Watcher stopped.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# docs search
+# ---------------------------------------------------------------------------
+
+@docs_app.command("search")
+def docs_search_cmd(
+    query: Annotated[str, typer.Argument(help="Search query")],
+    path: Annotated[
+        Optional[Path],
+        typer.Option("--path", "-p", help="Repository path (default: cwd)"),
+    ] = None,
+    k: Annotated[int, typer.Option("--top-k", "-k", help="Number of results")] = 5,
+    source_type: Annotated[
+        Optional[str],
+        typer.Option("--type", "-t", help="Filter: docs | docs_code"),
+    ] = None,
+) -> None:
+    """Search indexed documentation semantically.
+
+    Uses hybrid BM25 + vector search with RRF fusion.
+    """
+    repo = _resolve_repo(path)
+    pipeline = _get_pipeline(repo)
+    db_path = repo / ".contextual" / "contextual.db"
+
+    from contextual.docs.retrieval import docs_search
+    from contextual.embedding.embedder import get_docs_embedder
+    from contextual.storage import SQLitePool
+
+    pool = SQLitePool(db_path)
+    embedder = get_docs_embedder()
+
+    sf = {"source_type": [source_type]} if source_type else None
+
+    with pool.reader() as conn:
+        hits = docs_search(query=query, conn=conn, embedder=embedder, k=k, source_filter=sf)
+
+    if not hits:
+        console.print("[yellow]No results found.[/yellow]")
+        raise typer.Exit(0)
+
+    console.print(f"\n[bold cyan]Docs Search[/bold cyan] — [dim]{query!r}[/dim]\n")
+    for i, hit in enumerate(hits, 1):
+        table = Table.grid(padding=(0, 1))
+        table.add_row(
+            f"[bold]{i}.[/bold]",
+            f"[cyan]{hit.file_path}[/cyan]",
+            f"[dim]{hit.heading_path}[/dim]" if hit.heading_path else "",
+            f"[green]score={hit.score:.4f}[/green]",
+        )
+        console.print(table)
+        snippet = hit.content[:200].replace("\n", " ").strip()
+        console.print(f"   [dim]{snippet}…[/dim]\n")
+
+
+# ---------------------------------------------------------------------------
+# docs files
+# ---------------------------------------------------------------------------
+
+@docs_app.command("files")
+def docs_files_cmd(
+    path: Annotated[
+        Optional[Path],
+        typer.Argument(help="Repository path (default: cwd)"),
+    ] = None,
+    repo_filter: Annotated[
+        Optional[str],
+        typer.Option("--repo", help="Path prefix filter (e.g. 'docs')"),
+    ] = None,
+    glob: Annotated[
+        Optional[str],
+        typer.Option("--glob", help="fnmatch glob (e.g. 'docs/adr/*.md')"),
+    ] = None,
+    headings: Annotated[
+        bool,
+        typer.Option("--headings", help="Show heading structure per file"),
+    ] = False,
+) -> None:
+    """List all documentation files indexed in this repository."""
+    repo = _resolve_repo(path)
+    db_path = repo / ".contextual" / "contextual.db"
+
+    from contextual.docs.retrieval import docs_list_files
+    from contextual.storage import SQLitePool
+
+    pool = SQLitePool(db_path)
+    with pool.reader() as conn:
+        files = docs_list_files(conn=conn, repo=repo_filter, glob=glob, include_headings=headings)
+
+    if not files:
+        console.print("[yellow]No indexed doc files found.[/yellow]")
+        raise typer.Exit(0)
+
+    table = Table(title=f"Indexed Docs ({len(files)} files)", border_style="cyan")
+    table.add_column("File", style="cyan")
+    table.add_column("Chunks", justify="right")
+    if headings:
+        table.add_column("Headings")
+
+    for fi in files:
+        row = [fi.file_path, str(fi.chunk_count)]
+        if headings:
+            row.append(", ".join(fi.headings[:5]) + ("…" if len(fi.headings) > 5 else ""))
+        table.add_row(*row)
+
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# setup helpers
+# ---------------------------------------------------------------------------
+
+_UVX_PATH_HINT = (
+    "The MCP server runs via uvx. On macOS the GUI apps (Claude Desktop, Cursor) "
+    "inherit a sparse PATH that excludes ~/.local/bin. We write the absolute path."
+)
+
+def _find_uvx() -> str:
+    """Find absolute path to uvx binary."""
+    # uv's default install location
+    candidates = [
+        Path.home() / ".local" / "bin" / "uvx",
+        Path.home() / ".cargo" / "bin" / "uvx",
+        Path("/opt/homebrew/bin/uvx"),
+        Path("/usr/local/bin/uvx"),
+    ]
+    for c in candidates:
+        if c.exists():
+            return str(c)
+    # Fall back to which
+    found = shutil.which("uvx")
+    if found:
+        return found
+    return "uvx"   # best-effort; user must fix PATH themselves
+
+
+def _backup_and_write(config_path: Path, new_content: str, label: str) -> None:
+    """Backup existing config then write new content."""
+    if config_path.exists():
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup = config_path.with_suffix(f".bak.{ts}")
+        shutil.copy2(config_path, backup)
+        console.print(f"  [dim]Backed up existing config → {backup.name}[/dim]")
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(new_content, encoding="utf-8")
+    console.print(f"  [green]✓[/green] Written: [cyan]{config_path}[/cyan]")
+
+
+def _merge_mcp_servers(config_path: Path, server_key: str, server_entry: dict, root_key: str = "mcpServers") -> None:
+    """Merge a single MCP server entry into an existing JSON config file."""
+    existing: dict = {}
+    if config_path.exists():
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        backup = config_path.with_suffix(f".bak.{ts}")
+        shutil.copy2(config_path, backup)
+        console.print(f"  [dim]Backed up → {backup.name}[/dim]")
+        try:
+            existing = json.loads(config_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            console.print(f"  [yellow]⚠[/yellow] Existing config has JSON errors — overwriting.")
+
+    if root_key not in existing:
+        existing[root_key] = {}
+    existing[root_key][server_key] = server_entry
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
+    console.print(f"  [green]✓[/green] Merged into: [cyan]{config_path}[/cyan]")
+
+
+def _print_restart_note(client: str) -> None:
+    console.print(f"\n  [bold yellow]↻[/bold yellow] Restart [bold]{client}[/bold] to load the new MCP server.\n")
+
+
+# ---------------------------------------------------------------------------
+# setup claude-desktop
+# ---------------------------------------------------------------------------
+
+@setup_app.command("claude-desktop")
+def setup_claude_desktop(
+    docs: Annotated[bool, typer.Option("--docs/--no-docs", help="Enable docs tools")] = False,
+) -> None:
+    """Configure Contextual in Claude Desktop (macOS).
+
+    Writes to ~/Library/Application Support/Claude/claude_desktop_config.json.
+    Backs up any existing config before modifying.
+    """
+    if platform.system() != "Darwin":
+        console.print("[red]✗[/red] Claude Desktop setup is macOS only.")
+        raise typer.Exit(1)
+
+    uvx = _find_uvx()
+    env: dict = {}
+    if docs:
+        env["CONTEXTUAL_DOCS_ENABLED"] = "1"
+
+    entry = {
+        "command": uvx,
+        "args": ["contextual"],
+        "env": env,
+    }
+
+    config_path = (
+        Path.home()
+        / "Library"
+        / "Application Support"
+        / "Claude"
+        / "claude_desktop_config.json"
+    )
+
+    console.print("\n[bold cyan]Setup: Claude Desktop[/bold cyan]")
+    console.print(f"  [dim]{_UVX_PATH_HINT}[/dim]\n")
+    _merge_mcp_servers(config_path, "contextual", entry, root_key="mcpServers")
+    _print_restart_note("Claude Desktop")
+
+    console.print("  [dim]Logs will appear at:[/dim]")
+    console.print(f"  [dim]~/Library/Logs/Claude/mcp-server-contextual.log[/dim]\n")
+
+
+# ---------------------------------------------------------------------------
+# setup claude-code
+# ---------------------------------------------------------------------------
+
+@setup_app.command("claude-code")
+def setup_claude_code(
+    scope: Annotated[
+        str,
+        typer.Option("--scope", help="Scope: user | project | local"),
+    ] = "user",
+    docs: Annotated[bool, typer.Option("--docs/--no-docs", help="Enable docs tools")] = False,
+) -> None:
+    """Configure Contextual in Claude Code via the claude CLI.
+
+    Runs: claude mcp add contextual --scope <scope> --transport stdio -- uvx contextual
+    """
+    uvx = _find_uvx()
+    claude_bin = shutil.which("claude")
+    if not claude_bin:
+        console.print("[red]✗[/red] 'claude' CLI not found. Install Claude Code first.")
+        raise typer.Exit(1)
+
+    console.print("\n[bold cyan]Setup: Claude Code[/bold cyan]\n")
+
+    cmd = [
+        claude_bin, "mcp", "add",
+        "contextual",
+        "--scope", scope,
+        "--transport", "stdio",
+        "--",
+        uvx, "contextual",
+    ]
+    if docs:
+        cmd = [claude_bin, "mcp", "add", "contextual",
+               "--scope", scope, "--transport", "stdio",
+               "--env", "CONTEXTUAL_DOCS_ENABLED=1",
+               "--", uvx, "contextual"]
+
+    console.print(f"  Running: [dim]{shlex.join(cmd)}[/dim]\n")
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+        if result.returncode == 0:
+            console.print(f"  [green]✓[/green] Contextual registered (scope={scope})")
+        else:
+            console.print(f"  [red]✗[/red] claude CLI error:\n{result.stderr}")
+            raise typer.Exit(1)
+    except FileNotFoundError:
+        console.print("[red]✗[/red] 'claude' binary not executable.")
+        raise typer.Exit(1)
+
+    _print_restart_note("Claude Code")
+
+
+# ---------------------------------------------------------------------------
+# setup cursor
+# ---------------------------------------------------------------------------
+
+@setup_app.command("cursor")
+def setup_cursor(
+    project: Annotated[
+        bool,
+        typer.Option("--project/--global", help="Write to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)"),
+    ] = True,
+    docs: Annotated[bool, typer.Option("--docs/--no-docs", help="Enable docs tools")] = False,
+) -> None:
+    """Configure Contextual in Cursor IDE.
+
+    Writes .cursor/mcp.json in the current directory (project scope, default)
+    or ~/.cursor/mcp.json (global scope).
+
+    Also prints the one-click deeplink for your README badge.
+    """
+    uvx = _find_uvx()
+    env: dict = {}
+    if docs:
+        env["CONTEXTUAL_DOCS_ENABLED"] = "1"
+
+    entry = {"command": uvx, "args": ["contextual"], "env": env}
+
+    if project:
+        config_path = Path.cwd() / ".cursor" / "mcp.json"
+    else:
+        config_path = Path.home() / ".cursor" / "mcp.json"
+
+    console.print("\n[bold cyan]Setup: Cursor[/bold cyan]")
+    console.print(f"  Scope: [dim]{'project' if project else 'global'}[/dim]\n")
+
+    _merge_mcp_servers(config_path, "contextual", entry, root_key="mcpServers")
+
+    # Deeplink badge
+    import base64
+    badge_payload = base64.b64encode(
+        json.dumps({"mcpServers": {"contextual": entry}}).encode()
+    ).decode()
+    deeplink = f"cursor://anysphere.cursor-deeplink/mcp/install?name=Contextual&config={badge_payload}"
+    console.print(f"\n  [bold]One-click deeplink (add to README):[/bold]")
+    console.print(f"  [dim]{deeplink[:120]}…[/dim]")
+
+    _print_restart_note("Cursor")
+    console.print(
+        "  [yellow]⚠[/yellow] Cursor has a 40-tool ceiling. "
+        "If docs + code tools exceed it, some will be silently truncated.\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# setup vscode
+# ---------------------------------------------------------------------------
+
+@setup_app.command("vscode")
+def setup_vscode(
+    workspace: Annotated[
+        bool,
+        typer.Option("--workspace/--user", help="Write to .vscode/mcp.json (workspace) or user settings"),
+    ] = True,
+    docs: Annotated[bool, typer.Option("--docs/--no-docs", help="Enable docs tools")] = False,
+) -> None:
+    """Configure Contextual in VS Code Copilot (Agent Mode).
+
+    VS Code uses 'servers' (NOT 'mcpServers') as the root key.
+    Writes .vscode/mcp.json in the current directory (workspace scope).
+
+    Requires: VS Code ≥ 1.102 with GitHub Copilot Chat extension.
+    Agent Mode must be active (tools are invisible in Ask/Edit mode).
+    """
+    uvx = _find_uvx()
+    env: dict = {}
+    if docs:
+        env["CONTEXTUAL_DOCS_ENABLED"] = "1"
+
+    # VS Code requires "type": "stdio" explicitly — without it, it assumes HTTP
+    entry = {"type": "stdio", "command": uvx, "args": ["contextual"], "env": env}
+
+    if workspace:
+        config_path = Path.cwd() / ".vscode" / "mcp.json"
+    else:
+        # User settings — complex path, guide user instead
+        console.print(
+            "\n[yellow]User-scope VS Code MCP config requires manual edit.[/yellow]\n"
+            "Add to your User settings.json:\n"
+        )
+        console.print(json.dumps({"mcp": {"servers": {"contextual": entry}}}, indent=2))
+        raise typer.Exit(0)
+
+    console.print("\n[bold cyan]Setup: VS Code Copilot[/bold cyan]")
+    console.print("  [dim]Root key is 'servers' (not 'mcpServers') — VS Code specific![/dim]\n")
+
+    # VS Code mcp.json uses "servers" at root
+    _merge_mcp_servers(config_path, "contextual", entry, root_key="servers")
+
+    _print_restart_note("VS Code")
+    console.print(
+        "  [dim]Ensure Agent Mode is active — MCP tools are invisible in Ask/Edit mode.[/dim]\n"
+    )
+
+
+# ---------------------------------------------------------------------------
+# setup gemini-cli
+# ---------------------------------------------------------------------------
+
+@setup_app.command("gemini-cli")
+def setup_gemini_cli(
+    project: Annotated[
+        bool,
+        typer.Option("--project/--global", help="Write to .gemini/settings.json (project) or ~/.gemini/settings.json (global)"),
+    ] = False,
+    docs: Annotated[bool, typer.Option("--docs/--no-docs", help="Enable docs tools")] = False,
+) -> None:
+    """Configure Contextual in Google Gemini CLI.
+
+    Writes to ~/.gemini/settings.json (global, default) or
+    .gemini/settings.json (project scope).
+
+    Note: Gemini CLI does NOT auto-load .env files for mcpServer env vars.
+    Env vars must be set in the shell or passed explicitly.
+    """
+    uvx = _find_uvx()
+    env: dict = {}
+    if docs:
+        env["CONTEXTUAL_DOCS_ENABLED"] = "1"
+
+    entry: dict = {"command": uvx, "args": ["contextual"]}
+    if env:
+        entry["env"] = env
+
+    if project:
+        config_path = Path.cwd() / ".gemini" / "settings.json"
+    else:
+        config_path = Path.home() / ".gemini" / "settings.json"
+
+    console.print("\n[bold cyan]Setup: Gemini CLI[/bold cyan]")
+    console.print(f"  Scope: [dim]{'project' if project else 'global'}[/dim]")
+    console.print("  [dim]⚠ Gemini CLI does not load .env — set CONTEXTUAL_DOCS_ENABLED in shell.[/dim]\n")
+
+    _merge_mcp_servers(config_path, "contextual", entry, root_key="mcpServers")
+    _print_restart_note("Gemini CLI (gemini)")
+
+
+# ---------------------------------------------------------------------------
+# setup antigravity
+# ---------------------------------------------------------------------------
+
+@setup_app.command("antigravity")
+def setup_antigravity(
+    docs: Annotated[bool, typer.Option("--docs/--no-docs", help="Enable docs tools")] = False,
+) -> None:
+    """Configure Contextual in Google Antigravity IDE.
+
+    Writes to ~/.gemini/antigravity/mcp_config.json.
+    Antigravity uses 'serverUrl' (HTTP) or 'command' (stdio) — NOT 'url' or 'httpUrl'.
+
+    Note: Antigravity only supports global config (no per-workspace MCP config yet).
+    Your code is processed on Google's cloud — review data-residency implications.
+    """
+    uvx = _find_uvx()
+    env: dict = {}
+    if docs:
+        env["CONTEXTUAL_DOCS_ENABLED"] = "1"
+
+    # Antigravity stdio entry — uses 'command' key (same as Gemini CLI)
+    entry: dict = {"command": uvx, "args": ["contextual"]}
+    if env:
+        entry["env"] = env
+
+    config_path = Path.home() / ".gemini" / "antigravity" / "mcp_config.json"
+
+    console.print("\n[bold cyan]Setup: Google Antigravity IDE[/bold cyan]")
+    console.print("  [dim]Global config only — no per-workspace support yet.[/dim]")
+    console.print("  [yellow]⚠[/yellow] [dim]Code is processed on Google cloud. Review data-residency.[/dim]\n")
+
+    _merge_mcp_servers(config_path, "contextual", entry, root_key="mcpServers")
+    _print_restart_note("Antigravity IDE")
+
+
+# ---------------------------------------------------------------------------
+# setup (show all options)
+# ---------------------------------------------------------------------------
+
+@setup_app.callback(invoke_without_command=True)
+def setup_callback(ctx: typer.Context) -> None:
+    """Configure Contextual in your AI IDE or MCP client.
+
+    Available clients:
+      claude-desktop   Claude Desktop (macOS)
+      claude-code      Claude Code CLI
+      cursor           Cursor IDE
+      vscode           VS Code Copilot (Agent Mode)
+      gemini-cli       Google Gemini CLI
+      antigravity      Google Antigravity IDE
+
+    For Perplexity and ChatGPT Desktop, use UI-based configuration.
+    Run 'contextual setup --help' for copy-paste config snippets.
+    """
+    if ctx.invoked_subcommand is None:
+        uvx = _find_uvx()
+        console.print("\n[bold cyan]Contextual MCP — Client Setup Guide[/bold cyan]\n")
+
+        table = Table(border_style="dim", show_header=True)
+        table.add_column("Client",    style="cyan")
+        table.add_column("Command")
+        table.add_column("Status")
+
+        table.add_row("Claude Desktop",  "contextual setup claude-desktop", "[green]✓ Supported[/green]")
+        table.add_row("Claude Code",     "contextual setup claude-code",    "[green]✓ Supported[/green]")
+        table.add_row("Cursor",          "contextual setup cursor",          "[green]✓ Supported[/green]")
+        table.add_row("VS Code Copilot", "contextual setup vscode",          "[green]✓ Supported[/green]")
+        table.add_row("Gemini CLI",      "contextual setup gemini-cli",      "[green]✓ Supported[/green]")
+        table.add_row("Antigravity",     "contextual setup antigravity",     "[green]✓ Supported[/green]")
+        table.add_row("Perplexity",      "UI only — no file config",         "[yellow]Copy-paste[/yellow]")
+        table.add_row("ChatGPT Desktop", "UI only — needs mcp-proxy",        "[yellow]Copy-paste[/yellow]")
+
+        console.print(table)
+
+        # Universal copy-paste snippet
+        snippet = {
+            "mcpServers": {
+                "contextual": {
+                    "command": uvx,
+                    "args": ["contextual"],
+                }
+            }
+        }
+        console.print(f"\n[bold]Universal config snippet:[/bold]")
+        console.print(f"[dim]{json.dumps(snippet, indent=2)}[/dim]\n")

contextual/config.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+import pathlib
+
+
+def get_log_dir():
+    return pathlib.Path("~/.local/state/contextual/logs").expanduser()