install_mcp.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/tools/install_mcp.py
 
"""
Purpose
-------
Implements the ``oct install-mcp`` CLI subcommand. Detects the target
AI host (Claude Code, Cursor, VS Code, or ``auto``) and writes (or
previews) the ``oct-mcp`` server entry into the host's MCP config file.
 
Responsibilities
----------------
- Define :data:`MCP_HOSTS` mapping each supported host to its config
  file location(s) and the JSON schema for the ``oct-mcp`` entry.
- Implement :func:`run_install_mcp` which detects the host config path,
  merges the ``oct-mcp`` server entry, and writes the result (or
  previews it in dry-run mode).
- Print a human-readable summary of what was / would be changed.
 
Diagnostics
-----------
Domain: OCT-CLI
Levels:
    L2 - lifecycle: file read, file written
    L3 - (none): this module emits lifecycle only
    L4 - (none): no deep trace is emitted
 
Contracts
---------
- This module does not import ``click`` or any MCP SDK.
- Writes only to known, allowlisted config file paths - never to
  arbitrary locations (design decision D-5B-7).
- ``dry_run=True`` (the default) never modifies any file.
- If the host config file already contains an ``oct-mcp`` server entry,
  the entry is updated in-place without duplicating it.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
import json
import sys
from pathlib import Path
from typing import Any
 
from oct.core.diagnostics import _dbg
 
 
# ---------------------------------------------------------------------
# MCP server entry for oct-mcp
# ---------------------------------------------------------------------
 
def _make_oct_mcp_entry(project_root: Path) -> dict:
    """Return the oct-mcp server entry for the current Python executable."""
    return {
        "command": sys.executable,
        "args": ["-m", "oct.mcp", "--project-root", str(project_root)],
        "type": "stdio",
    }
 
 
# ---------------------------------------------------------------------
# Host definitions
# ---------------------------------------------------------------------
 
#: Supported MCP host names.
SUPPORTED_HOSTS: tuple[str, ...] = ("claude-code", "cursor", "vscode")
 
 
def _get_host_config_paths(host: str) -> list[Path]:
    """Return candidate config file paths for *host* in preference order."""
    if host == "claude-code":
        home = Path.home()
        if sys.platform == "win32":
            # Claude Code on Windows: %APPDATA%\Claude\claude_desktop_config.json
            # and the local settings.json
            appdata = Path.home() / "AppData" / "Roaming" / "Claude"
            return [
                appdata / "claude_desktop_config.json",
                home / ".claude" / "settings.json",
            ]
        else:
            # macOS / Linux
            return [
                home / ".config" / "Claude" / "claude_desktop_config.json",
                home / ".claude" / "settings.json",
            ]
    elif host == "cursor":
        return [Path(".cursor") / "mcp.json"]
    elif host == "vscode":
        return [Path(".vscode") / "mcp.json"]
    return []
 
 
def _detect_host(project_root: Path) -> str | None:
    """Auto-detect the first installed host whose config file exists."""
    for host in SUPPORTED_HOSTS:
        for p in _get_host_config_paths(host):
            resolved = p if p.is_absolute() else (project_root / p)
            if resolved.exists():
                return host
    return None
 
 
# ---------------------------------------------------------------------
# Config file merge
# ---------------------------------------------------------------------
 
 
def _read_json_safe(path: Path) -> dict:
    """Read JSON from *path*, returning ``{}`` on any error."""
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except Exception:
        return {}
 
 
def _merge_server_entry(config: dict, server_entry: dict) -> dict:
    """Merge the oct-mcp server entry into *config*.
 
    For Claude Code ``settings.json`` the schema is::
 
        {"mcpServers": {"oct-mcp": {...}}}
 
    For Cursor / VS Code ``mcp.json`` the schema is::
 
        {"servers": {"oct-mcp": {...}}}
 
    If the key ``"mcpServers"`` is present (or the file is a Claude Code
    settings.json) we use the Claude Code schema; otherwise we use the
    Cursor/VS Code schema.
    """
    updated = dict(config)
    # Detect schema type
    if "mcpServers" in config or "mcpServers" not in config and "servers" not in config:
        # Default to Claude Code schema
        servers = dict(updated.get("mcpServers", {}))
        servers["oct-mcp"] = server_entry
        updated["mcpServers"] = servers
    else:
        servers = dict(updated.get("servers", {}))
        servers["oct-mcp"] = server_entry
        updated["servers"] = servers
    return updated
 
 
# ---------------------------------------------------------------------
# Main entry point
# ---------------------------------------------------------------------
 
 
def run_install_mcp(
    host: str,
    project_root: Path,
    dry_run: bool = True,
) -> int:
    """Install or preview the oct-mcp server entry for the given host.
 
    Parameters
    ----------
    host
        One of ``"claude-code"``, ``"cursor"``, ``"vscode"``, or
        ``"auto"`` (auto-detect).
    project_root
        Absolute project root path (used as ``--project-root`` arg in
        the server entry).
    dry_run
        When ``True`` (the default), print what would be written without
        modifying any files.
 
    Returns
    -------
    Exit code: 0 on success, 1 on failure.
    """
    func = "run_install_mcp"
    _dbg("OCT-CLI", func, f"host={host} dry_run={dry_run}", 2)
 
    # Resolve host
    if host == "auto":
        detected = _detect_host(project_root)
        if detected is None:
            print(
                "oct install-mcp: could not auto-detect an MCP host. "
                "Use --host to specify one of: claude-code, cursor, vscode.",
                file=sys.stderr,
            )
            return 1
        host = detected
        print(f"Detected host: {host}")
 
    if host not in SUPPORTED_HOSTS:
        print(
            f"oct install-mcp: unsupported host {host!r}. "
            f"Supported: {', '.join(SUPPORTED_HOSTS)}",
            file=sys.stderr,
        )
        return 1
 
    candidates = _get_host_config_paths(host)
    if not candidates:
        print(f"oct install-mcp: no config paths defined for host {host!r}", file=sys.stderr)
        return 1
 
    # Pick the first candidate whose parent exists, or the first one overall.
    config_path: Path | None = None
    for c in candidates:
        resolved = c if c.is_absolute() else (project_root / c)
        if resolved.parent.exists():
            config_path = resolved
            break
    if config_path is None:
        config_path = candidates[0] if candidates[0].is_absolute() else (project_root / candidates[0])
 
    # Build the server entry
    server_entry = _make_oct_mcp_entry(project_root)
 
    # Read existing config (empty dict if file not found)
    existing = _read_json_safe(config_path) if config_path.exists() else {}
 
    # Merge
    updated = _merge_server_entry(existing, server_entry)
 
    output = json.dumps(updated, indent=2)
 
    if dry_run:
        print(f"[DRY RUN] Would write to: {config_path}")
        print("Content:")
        print(output)
        print(
            "\nRe-run without --dry-run to apply, "
            "or use --no-dry-run to apply immediately."
        )
        return 0
 
    # Write
    try:
        config_path.parent.mkdir(parents=True, exist_ok=True)
        config_path.write_text(output + "\n", encoding="utf-8")
        print(f"Wrote oct-mcp server entry to: {config_path}")
        print("Restart your AI host to pick up the new configuration.")
        _dbg("OCT-CLI", func, f"wrote {config_path}", 2)
        return 0
    except OSError as exc:
        print(f"oct install-mcp: failed to write {config_path}: {exc}", file=sys.stderr)
        return 1