ama-cli 0.1.0__py3-none-any.whl

ama_cli/agents/mcp.py

@@ -0,0 +1,275 @@
+"""MCP registration: what to write, and where, for each agent.
+
+There is no cross-agent standard. An MCP RFC to create one was closed as a
+duplicate in Feb 2026, so every client invented its own dialect: the root key is
+`mcpServers` / `servers` / `context_servers` / `mcp_servers`, and the transport
+discriminator is `type: "http"` / `"streamable-http"` / `"streamableHttp"` / an
+`httpUrl` key / a `serverUrl` key / nothing at all. That variation is the reason
+for one adapter per agent rather than one writer with branches.
+
+Adapters do not act. They return a `Plan` describing what they *would* do, which
+`--dry-run` prints and `apply()` executes. Tests assert on plans and never touch
+a real config file.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, replace
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Protocol
+
+from ama_cli.agents.base import AgentSpec, Env
+
+DEFAULT_SERVER_NAME = "ama"
+DEFAULT_TOKEN_ENV_VAR = "AMA_API_KEY"
+
+
+class Scope(str, Enum):
+    """Where a server registration lives.
+
+    GLOBAL is the default everywhere. PROJECT is worse twice over: the file is
+    committed (so it must never hold a literal token) and Claude Code
+    additionally requires interactive approval before a project-scoped server
+    will connect at all.
+    """
+
+    GLOBAL = "global"
+    PROJECT = "project"
+
+
+class UnsupportedScope(Exception):
+    """Raised when an agent cannot honour the requested scope safely."""
+
+
+@dataclass(frozen=True)
+class RemoteServer:
+    """The Ama MCP server, in canonical form. Each adapter lowers it to its own dialect."""
+
+    url: str
+    token: str
+    name: str = DEFAULT_SERVER_NAME
+    token_env_var: str = DEFAULT_TOKEN_ENV_VAR
+
+    def authorization(self, scope: Scope, env_ref: str | None = None) -> str:
+        """The Authorization header value for a scope.
+
+        Global configs are user-owned and uncommitted, so a literal token is
+        both safe and more reliable than indirection (it needs no shell profile
+        edit and works in GUI editors that never inherit a shell env).
+
+        Project configs get committed. A literal token there is a leaked
+        credential, so callers must pass the agent's env-reference syntax.
+        """
+        if scope is Scope.GLOBAL:
+            return f"Bearer {self.token}"
+        if env_ref is None:
+            raise UnsupportedScope(
+                "project scope requires env-var indirection; a literal token would be committed"
+            )
+        return f"Bearer {env_ref}"
+
+
+def mask(text: str, secret: str | None) -> str:
+    """Replace a secret with a placeholder, for anything shown to a human."""
+    if not secret:
+        return text
+    return text.replace(secret, "ama_****")
+
+
+@dataclass(frozen=True)
+class FileWrite:
+    """A pending write to a config file we do not own.
+
+    `after` holds the real token (it is what lands on disk at global scope);
+    `display_after` is what may be printed. --dry-run renders these diffs, so
+    the two must never be confused: a token echoed to the terminal ends up in
+    scrollback and in whatever bug report the user pastes it into.
+    """
+
+    path: Path
+    before: str | None  # None when the file does not exist yet
+    after: str
+    secret: str | None = None
+
+    @property
+    def creates(self) -> bool:
+        """True when this write creates the file rather than modifying it."""
+        return self.before is None
+
+    @property
+    def is_noop(self) -> bool:
+        """True when the file already says exactly this."""
+        return self.before == self.after
+
+    @property
+    def display_after(self) -> str:
+        """`after` with the secret masked. Safe to print."""
+        return mask(self.after, self.secret)
+
+    @property
+    def display_before(self) -> str | None:
+        """`before` with the secret masked. Safe to print.
+
+        Masked too: an existing config already holds a real key, and it is
+        rendered on the `-` side of the diff.
+        """
+        return None if self.before is None else mask(self.before, self.secret)
+
+
+@dataclass(frozen=True)
+class RunCommand:
+    """A pending shell-out to an agent's own MCP CLI.
+
+    Preferred over writing files wherever a CLI exists: it insulates us from
+    path churn and from VS Code's user-profile location, which its docs never
+    actually specify.
+    """
+
+    argv: tuple[str, ...]
+    secret: str | None = None
+    # A pre-emptive `mcp remove` fails on a clean machine. That is expected,
+    # not an error -- see the adapters' replace-on-rerun comment.
+    tolerate_failure: bool = False
+
+    @property
+    def display(self) -> str:
+        """The command with the token masked, safe to print or log."""
+        return " ".join(mask(a, self.secret) for a in self.argv)
+
+
+Step = FileWrite | RunCommand
+
+
+@dataclass(frozen=True)
+class Plan:
+    """What an adapter would do. Print it, or apply it."""
+
+    agent_id: str
+    steps: tuple[Step, ...] = ()
+    unsupported: str | None = None
+
+    @property
+    def is_noop(self) -> bool:
+        """True when nothing would change."""
+        return (
+            all(isinstance(s, FileWrite) and s.is_noop for s in self.steps) if self.steps else True
+        )
+
+
+@dataclass(frozen=True)
+class Result:
+    """The outcome of applying a plan."""
+
+    agent_id: str
+    ok: bool
+    detail: str
+    backups: tuple[Path, ...] = ()
+
+
+class AgentAdapter(Protocol):
+    """One agent's MCP dialect."""
+
+    spec: AgentSpec
+
+    def plan_add(self, server: RemoteServer, scope: Scope, env: Env) -> Plan:
+        """Describe registering `server`. Must not touch the filesystem."""
+        ...
+
+    def plan_remove(self, name: str, scope: Scope, env: Env) -> Plan:
+        """Describe removing a server by name. Must not touch the filesystem."""
+        ...
+
+    def list_servers(self, scope: Scope, env: Env) -> list[str]:
+        """Names of MCP servers currently registered with this agent."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# JSON config helpers, shared by the file-writing adapters
+# ---------------------------------------------------------------------------
+
+
+def read_json(path: Path) -> tuple[dict, str | None]:
+    """Read a JSON config, tolerating absent and empty files.
+
+    Returns (data, raw). `raw` is None when the file does not exist, which is
+    what tells FileWrite whether it is creating or modifying.
+
+    A malformed file is a hard error: silently replacing a config we cannot
+    parse would destroy whatever the user actually had in it.
+    """
+    if not path.exists():
+        return {}, None
+    raw = path.read_text()
+    if not raw.strip():
+        return {}, raw
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path} is not valid JSON ({exc}); refusing to overwrite it") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} is not a JSON object; refusing to overwrite it")
+    return data, raw
+
+
+def dump_json(data: dict) -> str:
+    """Serialise a config the way these files are conventionally formatted."""
+    return json.dumps(data, indent=2) + "\n"
+
+
+def backup_path(path: Path, stamp: str) -> Path:
+    """Where a pre-write backup of `path` goes."""
+    return path.with_name(f"{path.name}.ama-backup-{stamp}")
+
+
+def apply_plan(plan: Plan, *, now: datetime, runner=subprocess.run) -> Result:
+    """Execute a plan, backing up every file before touching it.
+
+    `now` and `runner` are injected so tests can assert on real behaviour with a
+    fixed timestamp and no subprocesses.
+    """
+    if plan.unsupported:
+        return Result(plan.agent_id, ok=False, detail=plan.unsupported)
+
+    backups: list[Path] = []
+    stamp = now.strftime("%Y%m%dT%H%M%S")
+
+    for step in plan.steps:
+        if isinstance(step, FileWrite):
+            if step.is_noop:
+                continue
+            if step.before is not None:
+                # Back up before mutating a file we do not own. Cheap insurance
+                # against a dialect bug costing someone their config.
+                bak = backup_path(step.path, stamp)
+                bak.write_text(step.before)
+                backups.append(bak)
+            step.path.parent.mkdir(parents=True, exist_ok=True)
+            step.path.write_text(step.after)
+        else:
+            proc = runner(step.argv, capture_output=True, text=True)
+            if proc.returncode != 0 and not step.tolerate_failure:
+                err = (proc.stderr or proc.stdout or "").strip().splitlines()
+                detail = err[-1] if err else f"exit {proc.returncode}"
+                return Result(
+                    plan.agent_id,
+                    ok=False,
+                    detail=f"`{step.display}` failed: {detail}",
+                    backups=tuple(backups),
+                )
+
+    return Result(plan.agent_id, ok=True, detail="registered", backups=tuple(backups))
+
+
+def noop_plan(agent_id: str) -> Plan:
+    """A plan that does nothing."""
+    return Plan(agent_id=agent_id)
+
+
+def unsupported_plan(agent_id: str, reason: str) -> Plan:
+    """A plan that cannot be carried out, with a reason worth showing the user."""
+    return replace(noop_plan(agent_id), unsupported=reason)

ama_cli/agents/registry.py

@@ -0,0 +1,179 @@
+"""The agent detector registry.
+
+Adding support for a new agent should mean adding one `AgentSpec` here plus a
+test in `tests/agents/`. Keep the list alphabetical by display name.
+
+Paths are sourced from each vendor's official docs; see `docs_url` on each spec.
+They drift, so treat a failing detection test as a docs-changed signal rather
+than a flaky test.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from ama_cli.agents.base import AgentSpec, Detection, Env, Platform
+
+# ---------------------------------------------------------------------------
+# Platform-specific config roots
+# ---------------------------------------------------------------------------
+
+
+def _vscode_user_dirs(env: Env) -> list[Path]:
+    """VS Code's per-user config root, including the Insiders channel.
+
+    The MCP docs describe the user `mcp.json` as living "in your user profile"
+    but never state OS paths, and these break under named profiles and portable
+    installs. Good enough to *detect* VS Code; registration should prefer
+    `code --add-mcp` over writing these paths.
+    """
+    if env.platform is Platform.DARWIN:
+        roots = [env.home / "Library" / "Application Support"]
+    elif env.platform is Platform.WINDOWS:
+        roots = [env.appdata or env.home / "AppData" / "Roaming"]
+    else:
+        roots = [env.config_home]
+    return [root / channel / "User" for root in roots for channel in ("Code", "Code - Insiders")]
+
+
+def _globalstorage_dirs(env: Env, extension_id: str) -> list[Path]:
+    """A VS Code extension's globalStorage dir, where Cline and Roo keep settings."""
+    return [user / "globalStorage" / extension_id for user in _vscode_user_dirs(env)]
+
+
+def _zed_dirs(env: Env) -> Sequence[Path]:
+    """Zed's config dir.
+
+    Zed uses ~/.config/zed on macOS as well as Linux — *not* ~/Library — which
+    is the mistake worth having a helper for.
+    """
+    if env.platform is Platform.WINDOWS:
+        return [(env.appdata or env.home / "AppData" / "Roaming") / "Zed"]
+    return [env.config_home / "zed"]
+
+
+# ---------------------------------------------------------------------------
+# The registry
+#
+# Note on repo signals: AGENTS.md is deliberately absent from every spec. It is
+# read by Claude Code, Cursor, Copilot, Gemini CLI, Windsurf and Aider, so it
+# identifies no agent and would produce a false positive for all of them.
+# ---------------------------------------------------------------------------
+
+CLAUDE_CODE = AgentSpec(
+    id="claude-code",
+    display_name="Claude Code",
+    docs_url="https://code.claude.com/docs/en/mcp",
+    binaries=("claude",),
+    machine_paths=(".claude.json", ".claude"),
+    repo_paths=("CLAUDE.md", ".claude"),
+)
+
+CLINE = AgentSpec(
+    id="cline",
+    display_name="Cline",
+    docs_url="https://docs.cline.bot/mcp/configuring-mcp-servers",
+    binaries=("cline",),
+    machine_paths=(".cline",),
+    machine_paths_fn=lambda env: _globalstorage_dirs(env, "saoudrizwan.claude-dev"),
+    repo_paths=(".clinerules",),
+)
+
+CODEX = AgentSpec(
+    id="codex",
+    display_name="Codex CLI",
+    docs_url="https://learn.chatgpt.com/docs/extend/mcp?surface=cli",
+    binaries=("codex",),
+    machine_paths=(".codex",),
+    # No repo signal: Codex reads AGENTS.md, which identifies no agent.
+)
+
+CURSOR = AgentSpec(
+    id="cursor",
+    display_name="Cursor",
+    docs_url="https://cursor.com/docs/mcp",
+    binaries=("cursor", "cursor-agent"),
+    machine_paths=(".cursor",),
+    repo_paths=(".cursor", ".cursorrules"),
+)
+
+GEMINI_CLI = AgentSpec(
+    id="gemini-cli",
+    display_name="Gemini CLI",
+    docs_url="https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md",
+    binaries=("gemini",),
+    machine_paths=(".gemini",),
+    repo_paths=(".gemini", "GEMINI.md"),
+)
+
+ROO_CODE = AgentSpec(
+    id="roo-code",
+    display_name="Roo Code",
+    docs_url="https://docs.roocode.com/features/mcp/using-mcp-in-roo",
+    # No binary: Roo is a VS Code extension only.
+    machine_paths_fn=lambda env: _globalstorage_dirs(env, "rooveterinaryinc.roo-cline"),
+    repo_paths=(".roo", ".roomodes", ".roorules"),
+)
+
+VSCODE = AgentSpec(
+    id="vscode",
+    display_name="VS Code (Copilot)",
+    docs_url="https://code.visualstudio.com/docs/agents/reference/mcp-configuration",
+    binaries=("code", "code-insiders"),
+    machine_paths_fn=_vscode_user_dirs,
+    repo_paths=(".vscode", ".github/copilot-instructions.md"),
+)
+
+WINDSURF = AgentSpec(
+    id="windsurf",
+    display_name="Windsurf",
+    # Docs moved to a Devin domain under Cognition ownership; highest churn risk
+    # of the set.
+    docs_url="https://docs.devin.ai/desktop/cascade/mcp",
+    binaries=("windsurf",),
+    machine_paths=(".codeium/windsurf",),
+    repo_paths=(".windsurf", ".windsurfrules"),
+)
+
+ZED = AgentSpec(
+    id="zed",
+    display_name="Zed",
+    docs_url="https://zed.dev/docs/ai/mcp",
+    binaries=("zed",),
+    machine_paths_fn=_zed_dirs,
+    repo_paths=(".zed",),
+)
+
+REGISTRY: tuple[AgentSpec, ...] = (
+    CLAUDE_CODE,
+    CLINE,
+    CODEX,
+    CURSOR,
+    GEMINI_CLI,
+    ROO_CODE,
+    VSCODE,
+    WINDSURF,
+    ZED,
+)
+
+
+def get_spec(agent_id: str) -> AgentSpec | None:
+    """Look up a spec by id, or None when unknown."""
+    return next((spec for spec in REGISTRY if spec.id == agent_id), None)
+
+
+def detect_all(env: Env, specs: Sequence[AgentSpec] = REGISTRY) -> list[Detection]:
+    """Detect every registered agent, strongest evidence first.
+
+    Returns a Detection for *every* spec, including undetected ones, so callers
+    can show "not detected" rows. Filter on `.detected` for the positives.
+
+    Ordering is by confidence descending, then display name, so the list is
+    stable across runs — a UI that reshuffles between invocations is a bug.
+    """
+    detections = [spec.detect(env) for spec in specs]
+    return sorted(
+        detections,
+        key=lambda d: (-(d.confidence or 0), d.display_name),
+    )