contextual-engine 0.8.0__tar.gz → 0.8.5__tar.gz

{contextual_engine-0.8.0 → contextual_engine-0.8.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextual-engine
-Version: 0.8.0
+Version: 0.8.5
 Summary: Temporal-first local code memory for AI tools via MCP
 Project-URL: Homepage, https://contextuallabs.dev
 Project-URL: Documentation, https://contextuallabs.dev/docs

contextual_engine-0.8.5/contextual/cli/commands/client.py

@@ -0,0 +1,680 @@
+"""Client configuration commands for MCP clients."""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from contextual.cli.core import register_command, require_config, open_in_editor
+from contextual.cli.core.output import (
+    console,
+    print_client_configured,
+    print_error,
+    print_info,
+    print_md_injected,
+    print_agents_md_hint,
+    print_client_list,
+)
+from contextual.integrations.client_content import (
+    cursor_file_content,
+    antigravity_file_content,
+    marker_block,
+)
+from contextual.integrations.client_writer import write_type_a, write_type_b
+
+
+def _find_uvx() -> str | None:
+    """Locate a usable uvx executable."""
+    uvx_path = shutil.which("uvx")
+    if uvx_path:
+        return uvx_path
+
+    for candidate in [
+        Path.home() / ".local" / "bin" / "uvx",
+        Path("/usr/local/bin/uvx"),
+        Path("/opt/homebrew/bin/uvx"),
+    ]:
+        if candidate.exists():
+            return str(candidate)
+
+    return None
+
+
+def _backup_config(config_path: Path) -> dict:
+    """Load an existing config, backing it up first when present."""
+    existing: dict = {}
+    if config_path.exists():
+        backup_path = config_path.with_suffix(".json.bak")
+        try:
+            shutil.copy2(config_path, backup_path)
+        except OSError:
+            pass
+
+        try:
+            existing = json.loads(config_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    return existing
+
+
+def _extract_workspace_from_entry(entry: dict) -> str | None:
+    """Return the resolved workspace path embedded in an MCP entry's args, or None."""
+    args = entry.get("args", [])
+    if not isinstance(args, list):
+        return None
+    # Standard entry: [..., "--workspace", "/path"]
+    try:
+        idx = args.index("--workspace")
+        if idx + 1 < len(args):
+            return str(Path(args[idx + 1]).resolve())
+    except ValueError:
+        pass
+    # Shell entry (Claude Desktop zsh -lc "... --workspace /path ..."):
+    # workspace path is the token immediately after --workspace in the shell string.
+    for arg in args:
+        if isinstance(arg, str) and "--workspace" in arg:
+            after = arg.split("--workspace", 1)[1].strip()
+            try:
+                tokens = shlex.split(after)
+                if tokens:
+                    return str(Path(tokens[0]).resolve())
+            except ValueError:
+                pass
+    return None
+
+
+def _persist_client_config(config_path: Path, document: dict, mcp_servers: dict) -> None:
+    """Atomically write the merged config back to disk."""
+    document["mcpServers"] = mcp_servers
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = config_path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(document, indent=2), encoding="utf-8")
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, config_path)
+    except OSError as exc:
+        print_error(
+            f"Failed to write config: {exc}",
+            hint=f"Check permissions on {config_path.parent}",
+        )
+        raise typer.Exit(1) from exc
+
+
+def _write_client_config(config_path: Path, mcp_entry: dict, workspace_root: Path) -> str:
+    """Merge the Contextual entry into a client config. Returns the key written.
+
+    Smart workspace detection:
+    - If an existing contextual entry already points at this workspace → update it in-place
+      (preserves the user's key, avoids accumulating duplicate entries).
+    - If no contextual entry exists → add under the bare ``contextual`` key.
+    - If ``contextual`` is taken by a different workspace → add as ``contextual-<dirname>``,
+      with a short path-hash suffix if that key is also taken.
+    """
+    import hashlib
+
+    existing = _backup_config(config_path)
+    mcp_servers = existing.get("mcpServers")
+    if not isinstance(mcp_servers, dict):
+        mcp_servers = {}
+
+    ws_str = str(workspace_root.resolve())
+
+    # 1. Look for an existing contextual entry that already owns this workspace.
+    for key, val in mcp_servers.items():
+        if isinstance(val, dict) and (key == "contextual" or key.startswith("contextual-")):
+            if _extract_workspace_from_entry(val) == ws_str:
+                mcp_servers[key] = mcp_entry
+                _persist_client_config(config_path, existing, mcp_servers)
+                return key
+
+    # 2. No match — pick the least-surprising new key.
+    if "contextual" not in mcp_servers:
+        key = "contextual"
+    else:
+        key = f"contextual-{workspace_root.name}"
+        if key in mcp_servers:
+            suffix = hashlib.sha256(ws_str.encode()).hexdigest()[:6]
+            key = f"contextual-{workspace_root.name}-{suffix}"
+
+    mcp_servers[key] = mcp_entry
+    _persist_client_config(config_path, existing, mcp_servers)
+    return key
+
+
+def _build_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+    """Build the default MCP launcher entry for Contextual."""
+    return {
+        "command": uvx_path,
+        "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)],
+    }
+
+
+def _build_claude_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+    """Build the Claude Desktop MCP entry with an explicit workspace cd."""
+    return {
+        "command": "/bin/zsh",
+        "args": [
+            "-lc",
+            (
+                f"cd {shlex.quote(str(workspace_root))} "
+                f"&& exec {shlex.quote(uvx_path)} --from contextual-engine contextual-mcp "
+                f"--workspace {shlex.quote(str(workspace_root))}"
+            ),
+        ],
+    }
+
+
+def _build_vscode_mcp_entry(uvx_path: str, workspace_root: Path) -> dict:
+    """Build the VS Code / GitHub Copilot MCP entry.
+
+    VS Code requires an explicit ``"type": "stdio"`` field — other clients
+    accept entries without it.
+    """
+    return {
+        "type": "stdio",
+        "command": uvx_path,
+        "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)],
+    }
+
+
+# ── VS Code / GitHub Copilot writer ──────────────────────────────────────────
+# VS Code's mcp.json uses a "servers" root key (not "mcpServers").
+
+def _persist_vscode_config(config_path: Path, document: dict, servers: dict) -> None:
+    """Atomically write VS Code mcp.json using the 'servers' root key."""
+    document["servers"] = servers
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = config_path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(document, indent=2), encoding="utf-8")
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, config_path)
+    except OSError as exc:
+        print_error(
+            f"Failed to write config: {exc}",
+            hint=f"Check permissions on {config_path.parent}",
+        )
+        raise typer.Exit(1) from exc
+
+
+def _write_vscode_config(config_path: Path, mcp_entry: dict, workspace_root: Path) -> str:
+    """Merge the Contextual entry into a VS Code mcp.json. Returns the key written."""
+    import hashlib
+
+    existing = _backup_config(config_path)
+    servers = existing.get("servers")
+    if not isinstance(servers, dict):
+        servers = {}
+
+    ws_str = str(workspace_root.resolve())
+
+    for key, val in servers.items():
+        if isinstance(val, dict) and (key == "contextual" or key.startswith("contextual-")):
+            if _extract_workspace_from_entry(val) == ws_str:
+                servers[key] = mcp_entry
+                _persist_vscode_config(config_path, existing, servers)
+                return key
+
+    if "contextual" not in servers:
+        key = "contextual"
+    else:
+        key = f"contextual-{workspace_root.name}"
+        if key in servers:
+            suffix = hashlib.sha256(ws_str.encode()).hexdigest()[:6]
+            key = f"contextual-{workspace_root.name}-{suffix}"
+
+    servers[key] = mcp_entry
+    _persist_vscode_config(config_path, existing, servers)
+    return key
+
+
+def _configure_vscode_client(
+    config_path: Path,
+    mcp_entry: dict,
+    workspace_root: Path,
+    dry_run: bool = False,
+) -> None:
+    """Write Contextual MCP entry into a VS Code mcp.json."""
+    if dry_run:
+        from rich.syntax import Syntax
+        print_info(f"Dry run — would write to: {config_path}")
+        console.print()
+        console.print(
+            Syntax(
+                json.dumps({"servers": {"contextual": mcp_entry}}, indent=2),
+                "json",
+                theme="ansi_dark",
+                background_color="default",
+            )
+        )
+        console.print()
+        return
+
+    key = _write_vscode_config(config_path, mcp_entry, workspace_root)
+    print_client_configured("GitHub Copilot", key, config_path)
+
+
+# ── Codex TOML writer ─────────────────────────────────────────────────────────
+# Codex uses ~/.codex/config.toml with [mcp_servers.<name>] TOML tables.
+
+def _persist_codex_toml(config_path: Path, document: dict) -> None:
+    """Atomically write Codex config.toml."""
+    import tomli_w
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = config_path.with_suffix(".toml.tmp")
+        tmp.write_bytes(tomli_w.dumps(document).encode("utf-8"))
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, config_path)
+    except OSError as exc:
+        print_error(
+            f"Failed to write config: {exc}",
+            hint=f"Check permissions on {config_path.parent}",
+        )
+        raise typer.Exit(1) from exc
+
+
+def _write_codex_toml_config(config_path: Path, uvx_path: str, workspace_root: Path) -> str:
+    """Merge the Contextual entry into Codex config.toml. Returns the key written."""
+    import hashlib
+    import tomllib
+
+    existing: dict = {}
+    if config_path.exists():
+        backup_path = config_path.with_suffix(".toml.bak")
+        try:
+            shutil.copy2(config_path, backup_path)
+        except OSError:
+            pass
+        try:
+            with open(config_path, "rb") as fh:
+                existing = tomllib.load(fh)
+        except Exception:
+            existing = {}
+
+    mcp_servers = existing.setdefault("mcp_servers", {})
+    ws_str = str(workspace_root.resolve())
+    entry = {
+        "command": uvx_path,
+        "args": ["--from", "contextual-engine", "contextual-mcp", "--workspace", str(workspace_root)],
+    }
+
+    for key, val in mcp_servers.items():
+        if isinstance(val, dict) and (key == "contextual" or key.startswith("contextual-")):
+            args = val.get("args", [])
+            try:
+                idx = args.index("--workspace")
+                if idx + 1 < len(args) and str(Path(args[idx + 1]).resolve()) == ws_str:
+                    mcp_servers[key] = entry
+                    _persist_codex_toml(config_path, existing)
+                    return key
+            except (ValueError, IndexError):
+                pass
+
+    if "contextual" not in mcp_servers:
+        key = "contextual"
+    else:
+        key = f"contextual-{workspace_root.name}"
+        if key in mcp_servers:
+            suffix = hashlib.sha256(ws_str.encode()).hexdigest()[:6]
+            key = f"contextual-{workspace_root.name}-{suffix}"
+
+    mcp_servers[key] = entry
+    _persist_codex_toml(config_path, existing)
+    return key
+
+
+def _configure_codex_client(
+    config_path: Path,
+    uvx_path: str,
+    workspace_root: Path,
+    dry_run: bool = False,
+) -> None:
+    """Write Contextual MCP entry into Codex config.toml."""
+    if dry_run:
+        from rich.syntax import Syntax
+        print_info(f"Dry run — would write to: {config_path}")
+        console.print()
+        console.print(
+            Syntax(
+                f"[mcp_servers.contextual]\ncommand = {json.dumps(uvx_path)}\n"
+                f'args = ["--from", "contextual-engine", "contextual-mcp", '
+                f'"--workspace", {json.dumps(str(workspace_root))}]',
+                "toml",
+                theme="ansi_dark",
+                background_color="default",
+            )
+        )
+        console.print()
+        return
+
+    key = _write_codex_toml_config(config_path, uvx_path, workspace_root)
+    print_client_configured("Codex", key, config_path)
+
+
+# ── Manual / UI-based clients ─────────────────────────────────────────────────
+# ChatGPT and Perplexity have no writable local config file — MCP servers are
+# added through their desktop UI.  Display what the user needs to paste.
+
+def _display_manual_config(
+    client_name: str,
+    uvx_path: str,
+    workspace_root: Path,
+    ui_steps: list[str],
+) -> None:
+    """Print manual setup instructions for UI-based MCP clients."""
+    from rich.syntax import Syntax
+    from rich.panel import Panel
+    from rich.text import Text
+
+    cmd = (
+        f"{uvx_path} --from contextual-engine contextual-mcp "
+        f"--workspace {shlex.quote(str(workspace_root))}"
+    )
+
+    console.print()
+    console.print(Panel(
+        Text(
+            f"{client_name} does not support a local config file — "
+            "MCP servers must be added through the app UI.",
+            style="white",
+        ),
+        title=f"[white bold]{client_name} — Manual Setup Required[/white bold]",
+        border_style="bright_black",
+        padding=(0, 1),
+    ))
+    console.print()
+
+    for i, step in enumerate(ui_steps, 1):
+        console.print(f"  [white bold]{i}.[/white bold] [#6b6b6b]{step}[/#6b6b6b]")
+
+    console.print()
+    console.print("  [white bold]Server name:[/white bold]  [white]contextual[/white]")
+    console.print("  [white bold]Command:[/white bold]")
+    console.print()
+    console.print(
+        Syntax(cmd, "bash", theme="ansi_dark", background_color="default")
+    )
+    console.print()
+
+
+def _config_paths() -> dict[str, Path]:
+    """Return per-client config file paths, platform-aware.
+
+    Paths verified against docs/DRs/PERPLEXITY-DR-mcp-config.md (June 2026).
+    chatgpt / perplexity are intentionally absent — both are UI-only; no local
+    config file exists for them.  They are handled by _display_manual_config().
+    """
+    home = Path.home()
+    is_mac = sys.platform == "darwin"
+    is_win = sys.platform == "win32"
+    app_support = (
+        home / "Library" / "Application Support"
+        if is_mac
+        else Path(os.environ.get("APPDATA", str(home)))
+        if is_win
+        else home / ".config"
+    )
+    return {
+        "claude": app_support / "Claude" / "claude_desktop_config.json",
+        "gemini-cli": home / ".gemini" / "settings.json",
+        "cursor": home / ".cursor" / "mcp.json",
+        "copilot": home / ".vscode" / "mcp.json",
+        "windsurf": home / ".codeium" / "windsurf" / "mcp_config.json",
+        "codex": home / ".codex" / "config.toml",
+        "antigravity": home / ".gemini" / "config" / "mcp_config.json",
+    }
+
+
+def _configure_client(
+    client_name: str,
+    config_path: Path,
+    mcp_entry: dict,
+    workspace_root: Path,
+    dry_run: bool = False,
+) -> None:
+    """Write Contextual MCP entry into a client config file."""
+    if dry_run:
+        from rich.syntax import Syntax
+        print_info(f"Dry run — would write to: {config_path}")
+        console.print()
+        console.print(
+            Syntax(
+                json.dumps({"contextual": mcp_entry}, indent=2),
+                "json",
+                theme="ansi_dark",
+                background_color="default",
+            )
+        )
+        console.print()
+        return
+
+    key = _write_client_config(config_path, mcp_entry, workspace_root)
+    print_client_configured(client_name, key, config_path)
+
+
+@register_command(group="client")
+@require_config
+def client(
+    typer_ctx: typer.Context,
+    claude: Annotated[
+        bool,
+        typer.Option("--claude", help="Configure Claude Desktop to use Contextual via MCP."),
+    ] = False,
+    claude_code: Annotated[
+        bool,
+        typer.Option("--claude-code", help="Configure Claude Code (CLI) to use Contextual via MCP."),
+    ] = False,
+    chatgpt: Annotated[
+        bool,
+        typer.Option("--chatgpt", help="Configure ChatGPT to use Contextual via MCP."),
+    ] = False,
+    perplexity: Annotated[
+        bool,
+        typer.Option("--perplexity", help="Configure Perplexity to use Contextual via MCP."),
+    ] = False,
+    gemini_cli: Annotated[
+        bool,
+        typer.Option("--gemini-cli", help="Configure Gemini CLI to use Contextual via MCP."),
+    ] = False,
+    cursor: Annotated[
+        bool,
+        typer.Option("--cursor", help="Configure Cursor IDE to use Contextual via MCP."),
+    ] = False,
+    copilot: Annotated[
+        bool,
+        typer.Option("--copilot", help="Configure GitHub Copilot (VS Code) to use Contextual via MCP."),
+    ] = False,
+    windsurf: Annotated[
+        bool,
+        typer.Option("--windsurf", help="Configure Windsurf to use Contextual via MCP."),
+    ] = False,
+    codex: Annotated[
+        bool,
+        typer.Option("--codex", help="Configure Codex CLI to use Contextual via MCP."),
+    ] = False,
+    antigravity: Annotated[
+        bool,
+        typer.Option("--antigravity", help="Configure Antigravity to use Contextual via MCP."),
+    ] = False,
+    cline: Annotated[
+        bool,
+        typer.Option("--cline", help="Inject Contextual tool instructions into AGENTS.md for Cline."),
+    ] = False,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Show what would be written without writing."),
+    ] = False,
+) -> None:
+    """Configure an MCP client to use Contextual."""
+    if typer_ctx.invoked_subcommand is not None:
+        return
+
+    flags = [claude, claude_code, chatgpt, perplexity, gemini_cli, cursor, copilot, windsurf, codex, antigravity, cline]
+    selected = sum(flags)
+
+    if selected == 0:
+        print_error(
+            "Specify a client to configure.",
+            hint=(
+                "contextual client --claude\n"
+                "  contextual client --claude-code\n"
+                "  contextual client --cursor\n"
+                "  contextual client --copilot\n"
+                "  contextual client --windsurf\n"
+                "  contextual client --antigravity\n"
+                "  contextual client --cline\n"
+                "  contextual client --gemini-cli\n"
+                "  contextual client --codex\n"
+                "  contextual client --chatgpt\n"
+                "  contextual client --perplexity"
+            ),
+        )
+        raise typer.Exit(1)
+
+    if selected > 1:
+        print_error(
+            "Only one client can be configured at a time.",
+            hint="Run the command separately for each client.",
+        )
+        raise typer.Exit(1)
+
+    uvx_path = _find_uvx()
+    if not uvx_path:
+        print_error(
+            "uvx not found on PATH.",
+            hint="Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh",
+        )
+        raise typer.Exit(1)
+
+    paths = _config_paths()
+    workspace_root = Path.cwd().resolve()
+
+    agents_md = workspace_root / ".contextual" / "AGENTS.md"
+
+    if claude:
+        entry = _build_claude_mcp_entry(uvx_path, workspace_root)
+        _configure_client("Claude Desktop", paths["claude"], entry, workspace_root, dry_run)
+        print_agents_md_hint(agents_md, "Claude → Project → Custom Instructions")
+
+    elif claude_code:
+        _configure_client("Claude Code", workspace_root / ".mcp.json", _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        if not dry_run:
+            result = write_type_b(workspace_root / "CLAUDE.md", marker_block("claude-code"))
+            print_md_injected(workspace_root / "CLAUDE.md", result)
+
+    elif chatgpt:
+        _display_manual_config(
+            "ChatGPT",
+            uvx_path,
+            workspace_root,
+            ui_steps=[
+                "Open ChatGPT Desktop and go to Settings",
+                "Navigate to Connectors → Advanced → Developer mode",
+                "Click 'Add server' and enter the name and command below",
+                "Toggle the server on and restart ChatGPT",
+            ],
+        )
+        print_agents_md_hint(agents_md, "ChatGPT → Project → Custom Instructions")
+
+    elif perplexity:
+        _display_manual_config(
+            "Perplexity",
+            uvx_path,
+            workspace_root,
+            ui_steps=[
+                "Open Perplexity Desktop (macOS) and go to Settings",
+                "Navigate to Connectors → Add Connector",
+                "Enter the server name and command below",
+                "Toggle MCP on under Sources on the homepage",
+            ],
+        )
+        print_agents_md_hint(agents_md, "Perplexity → Space → System Prompt")
+
+    elif gemini_cli:
+        _configure_client("Gemini CLI", paths["gemini-cli"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+
+    elif cursor:
+        _configure_client("Cursor", paths["cursor"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        if not dry_run:
+            result = write_type_a(workspace_root / ".cursor" / "rules" / "contextual.mdc", cursor_file_content())
+            print_md_injected(workspace_root / ".cursor" / "rules" / "contextual.mdc", result)
+
+    elif copilot:
+        _configure_vscode_client(paths["copilot"], _build_vscode_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        if not dry_run:
+            result = write_type_b(workspace_root / ".github" / "copilot-instructions.md", marker_block("copilot"))
+            print_md_injected(workspace_root / ".github" / "copilot-instructions.md", result)
+
+    elif windsurf:
+        _configure_client("Windsurf", paths["windsurf"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        if not dry_run:
+            result = write_type_b(workspace_root / ".windsurfrules", marker_block("windsurf"))
+            print_md_injected(workspace_root / ".windsurfrules", result)
+
+    elif codex:
+        _configure_codex_client(paths["codex"], uvx_path, workspace_root, dry_run)
+
+    elif antigravity:
+        _configure_client("Antigravity", paths["antigravity"], _build_mcp_entry(uvx_path, workspace_root), workspace_root, dry_run)
+        if not dry_run:
+            result = write_type_a(workspace_root / ".agent" / "rules" / "contextual.md", antigravity_file_content())
+            print_md_injected(workspace_root / ".agent" / "rules" / "contextual.md", result)
+
+    elif cline:
+        # Cline: markdown-only — no separate MCP config file.
+        if not dry_run:
+            result = write_type_b(workspace_root / "AGENTS.md", marker_block("cline"))
+            print_md_injected(workspace_root / "AGENTS.md", result)
+        else:
+            from rich.syntax import Syntax
+            print_info("Dry run — would inject into: AGENTS.md")
+            console.print()
+            console.print(Syntax(marker_block("cline")[:300] + "\n...", "markdown", theme="ansi_dark", background_color="default"))
+            console.print()
+
+
+@register_command(group="client", name="list")
+def client_list() -> None:
+    """List configured MCP clients."""
+    from contextual.mcp.access import registry
+
+    try:
+        registry.load_from_disk()
+    except Exception:
+        pass
+
+    clients_list = []
+    for name, info in registry._by_name.items():
+        clients_list.append({
+            "name": name,
+            "access": info.get("access", "none"),
+            "workspaces": info.get("workspaces", ["*"])
+        })
+    print_client_list(clients_list)
+
+
+@register_command(group="client", name="config")
+def client_config() -> None:
+    """Open global mcp.json client access policy configuration in editor."""
+    from contextual.config.paths import MCP_CONFIG_FILE as MCP_JSON_PATH
+    if not MCP_JSON_PATH.exists():
+        try:
+            MCP_JSON_PATH.parent.mkdir(parents=True, exist_ok=True)
+            MCP_JSON_PATH.write_text("{\n  \"clients\": {}\n}\n")
+        except Exception as e:
+            print_error(f"Could not create mcp.json config: {e}")
+            raise typer.Exit(1)
+    try:
+        open_in_editor(MCP_JSON_PATH)
+    except Exception as e:
+        print_error(f"Failed to open config file: {e}")
+        raise typer.Exit(1)