mt4ctl 0.1.0__py3-none-any.whl

mt4ctl/__init__.py

@@ -0,0 +1,12 @@
+"""mt4ctl — an MCP server for managing headless MetaTrader terminals.
+
+Manage MetaTrader 4 terminals that run under Wine + systemd on remote hosts
+(native Linux or WSL2) entirely over SSH: status, logs, screenshots, lifecycle
+control, and headless first-login — exposed as Model Context Protocol tools.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

mt4ctl/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m mt4ctl`` to launch the MCP server."""
+
+from __future__ import annotations
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

mt4ctl/auth.py

@@ -0,0 +1,57 @@
+"""Credential resolution for terminal logins.
+
+Resolution order (first hit wins), mirroring common CLI conventions:
+
+1. an explicit ``password`` passed by the caller
+2. ``MT4CTL_PASSWORD_<account>`` environment variable
+3. the ``<account>`` key in a JSON secrets file
+   (``$MT4CTL_CREDENTIALS`` or ``$XDG_CONFIG_HOME/mt4ctl/credentials.json``)
+
+Passwords are never logged, echoed, or written anywhere except the transient
+remote login config, which the login flow shreds after use.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .errors import CredentialError
+
+
+def secrets_file() -> Path:
+    """Return the path of the JSON secrets file (may not exist)."""
+    if env := os.environ.get("MT4CTL_CREDENTIALS"):
+        return Path(env).expanduser()
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return base / "mt4ctl" / "credentials.json"
+
+
+def resolve_password(account: str, explicit: str | None = None) -> str:
+    """Return the password for *account*, raising :class:`CredentialError` if absent."""
+    if explicit:
+        return explicit
+
+    if env := os.environ.get(f"MT4CTL_PASSWORD_{account}"):
+        return env
+
+    path = secrets_file()
+    if path.is_file():
+        if os.name == "posix" and (path.stat().st_mode & 0o077):
+            raise CredentialError(
+                f"secrets file {path} is readable by group/other; run: chmod 600 {path}"
+            )
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            raise CredentialError(f"could not read secrets file {path}: {exc}") from None
+        if isinstance(data, dict) and account in data:
+            return str(data[account])
+
+    raise CredentialError(
+        f"no password for account {account!r}. Provide it via the password "
+        f"argument, the MT4CTL_PASSWORD_{account} env var, or the "
+        f"{account!r} key in {path}."
+    )

mt4ctl/config.py

@@ -0,0 +1,203 @@
+"""Load and validate the terminal registry from YAML.
+
+The registry path is resolved as:
+
+1. an explicit ``path`` argument — must exist
+2. ``MT4CTL_CONFIG`` — if set, must exist (it does *not* fall back to the search
+   paths, so a typo fails loudly instead of using a stale file)
+3. otherwise the first existing of ``$XDG_CONFIG_HOME/mt4ctl/terminals.yaml``
+   (or ``~/.config/...``) then ``./terminals.yaml``
+
+This keeps real infrastructure details out of the source tree: ship the
+``examples/terminals.example.yaml`` template, keep the populated file private.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .errors import ConfigError
+from .models import Env, Host, HostKind, Registry, Terminal
+
+# Ids become systemd targets, dict keys, and (sanitized) filenames, so keep them
+# to a conservative, shell- and protocol-safe character set.
+_ID_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+_DISTRO_RE = re.compile(r"^[A-Za-z0-9._-]+$")
+
+
+def candidate_paths() -> list[Path]:
+    """Default registry search paths (XDG config dir, then CWD); env excluded."""
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
+    return [base / "mt4ctl" / "terminals.yaml", Path.cwd() / "terminals.yaml"]
+
+
+def resolve_path(path: str | os.PathLike[str] | None = None) -> Path:
+    """Find the registry file, raising :class:`ConfigError` if none exists.
+
+    An explicit ``path`` or a set ``MT4CTL_CONFIG`` must point to an existing
+    file — neither falls back to the search paths, so a typo'd path fails loudly
+    instead of silently using a stale registry.
+    """
+    if path is not None:
+        resolved = Path(path).expanduser()
+        if not resolved.is_file():
+            raise ConfigError(f"registry file not found: {resolved}")
+        return resolved
+
+    env = os.environ.get("MT4CTL_CONFIG")
+    if env:
+        resolved = Path(env).expanduser()
+        if not resolved.is_file():
+            raise ConfigError(
+                f"MT4CTL_CONFIG is set to {resolved}, but that file does not exist. "
+                "Create it, fix the path, or unset MT4CTL_CONFIG to use the default "
+                "search paths."
+            )
+        return resolved
+
+    for candidate in candidate_paths():
+        if candidate.is_file():
+            return candidate
+
+    searched = "\n  ".join(str(p) for p in candidate_paths())
+    raise ConfigError(
+        "mt4ctl could not find a terminal registry.\n\n"
+        "Create one:\n"
+        "  mkdir -p ~/.config/mt4ctl\n"
+        "  cp examples/terminals.example.yaml ~/.config/mt4ctl/terminals.yaml\n\n"
+        "Or set MT4CTL_CONFIG=/absolute/path/to/terminals.yaml.\nSearched:\n  " + searched
+    )
+
+
+def _require(mapping: dict[str, Any], key: str, where: str) -> Any:
+    if key not in mapping:
+        raise ConfigError(f"{where}: missing required field {key!r}")
+    return mapping[key]
+
+
+def _require_mapping(value: Any, where: str) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise ConfigError(f"{where}: expected a mapping, got {type(value).__name__}")
+    return value
+
+
+def _validate_id(kind: str, value: str) -> None:
+    if not _ID_RE.match(value):
+        raise ConfigError(
+            f"{kind} id {value!r} is invalid; use letters, digits, '.', '_', '-' only"
+        )
+    if kind == "terminal" and value == "all":
+        raise ConfigError(
+            "terminal id 'all' is reserved (mt4_status uses it for every terminal)"
+        )
+
+
+def _clean_field(value: str, field: str, where: str) -> str:
+    # These values are embedded in the '|'-delimited status protocol and in
+    # shell scripts; forbid separators and control characters outright.
+    if any(c in value for c in ("|", "\n", "\r")):
+        raise ConfigError(f"{where}: {field} must not contain '|' or newlines")
+    return value
+
+
+def _build_host(host_id: str, raw: dict[str, Any]) -> Host:
+    where = f"host {host_id!r}"
+    try:
+        kind = HostKind(raw.get("kind", "native"))
+    except ValueError:
+        raise ConfigError(
+            f"{where}: invalid kind {raw.get('kind')!r} (use native or wsl)"
+        ) from None
+    ssh = str(_require(raw, "ssh", where))
+    if ssh.startswith("-"):
+        raise ConfigError(f"{where}: ssh destination must not start with '-'")
+    distro = raw.get("wsl_distro")
+    if distro is not None and not _DISTRO_RE.match(str(distro)):
+        raise ConfigError(f"{where}: wsl_distro {distro!r} has invalid characters")
+    broker = raw.get("broker_host")
+    try:
+        return Host(
+            id=host_id,
+            ssh=ssh,
+            kind=kind,
+            wsl_distro=str(distro) if distro is not None else None,
+            broker_host=_clean_field(str(broker), "broker_host", where)
+            if broker is not None
+            else None,
+        )
+    except ValueError as exc:  # invariant from Host.__post_init__
+        raise ConfigError(str(exc)) from None
+
+
+def _build_terminal(term_id: str, raw: dict[str, Any], hosts: dict[str, Host]) -> Terminal:
+    where = f"terminal {term_id!r}"
+    host_id = str(_require(raw, "host", where))
+    if host_id not in hosts:
+        raise ConfigError(f"{where}: references unknown host {host_id!r}")
+    try:
+        env = Env(raw.get("env", "demo"))
+    except ValueError:
+        raise ConfigError(
+            f"{where}: invalid env {raw.get('env')!r} (use demo or live)"
+        ) from None
+    account = raw.get("account")
+    window_match = raw.get("window_match")
+    return Terminal(
+        id=term_id,
+        host=host_id,
+        service=_clean_field(str(_require(raw, "service", where)), "service", where),
+        data_dir=_clean_field(str(_require(raw, "data_dir", where)), "data_dir", where),
+        display=_clean_field(str(raw.get("display", ":0")), "display", where),
+        account=_clean_field(str(account), "account", where) if account is not None else None,
+        env=env,
+        window_match=(
+            _clean_field(str(window_match), "window_match", where)
+            if window_match is not None
+            else None
+        ),
+    )
+
+
+def parse_registry(data: dict[str, Any]) -> Registry:
+    """Build a :class:`Registry` from already-parsed YAML data."""
+    if not isinstance(data, dict):
+        raise ConfigError("registry root must be a mapping")
+    raw_hosts = data.get("hosts") or {}
+    raw_terminals = data.get("terminals") or {}
+    _require_mapping(raw_hosts, "hosts")
+    _require_mapping(raw_terminals, "terminals")
+    if not raw_hosts:
+        raise ConfigError("registry defines no hosts")
+    if not raw_terminals:
+        raise ConfigError("registry defines no terminals")
+
+    hosts: dict[str, Host] = {}
+    for hid, raw in raw_hosts.items():
+        _validate_id("host", str(hid))
+        hosts[str(hid)] = _build_host(str(hid), _require_mapping(raw, f"host {hid!r}"))
+
+    terminals: dict[str, Terminal] = {}
+    for tid, raw in raw_terminals.items():
+        _validate_id("terminal", str(tid))
+        terminals[str(tid)] = _build_terminal(
+            str(tid), _require_mapping(raw, f"terminal {tid!r}"), hosts
+        )
+    return Registry(hosts=hosts, terminals=terminals)
+
+
+def load_registry(path: str | os.PathLike[str] | None = None) -> Registry:
+    """Resolve, read, and validate the registry file."""
+    resolved = resolve_path(path)
+    try:
+        data = yaml.safe_load(resolved.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{resolved}: invalid YAML: {exc}") from None
+    if data is None:
+        raise ConfigError(f"{resolved}: file is empty")
+    return parse_registry(data)

mt4ctl/errors.py

@@ -0,0 +1,47 @@
+"""Typed errors with actionable messages.
+
+Errors raised here are caught at the MCP boundary and surfaced to the calling
+agent verbatim, so each message should tell the agent *how to recover* rather
+than just *what went wrong*.
+"""
+
+from __future__ import annotations
+
+
+class Mt4ctlError(Exception):
+    """Base class for all expected, user-facing errors."""
+
+
+class ConfigError(Mt4ctlError):
+    """The registry file is missing, malformed, or internally inconsistent."""
+
+
+class UnknownTargetError(Mt4ctlError):
+    """A referenced terminal or host does not exist in the registry."""
+
+
+class RemoteCommandError(Mt4ctlError):
+    """A command executed over SSH returned a non-zero exit status."""
+
+    def __init__(self, host: str, returncode: int, stderr: str) -> None:
+        self.host = host
+        self.returncode = returncode
+        self.stderr = stderr.strip()
+        detail = self.stderr or "(no stderr)"
+        super().__init__(f"remote command on {host!r} failed (exit {returncode}): {detail}")
+
+
+class ConfirmationRequiredError(Mt4ctlError):
+    """A mutating operation targeted a live terminal without ``confirm=true``."""
+
+    def __init__(self, terminal_id: str, action: str) -> None:
+        self.terminal_id = terminal_id
+        self.action = action
+        super().__init__(
+            f"refusing to {action} live terminal {terminal_id!r} without "
+            f"confirmation; pass confirm=true to proceed"
+        )
+
+
+class CredentialError(Mt4ctlError):
+    """A credential could not be resolved for a login operation."""

mt4ctl/login.py

@@ -0,0 +1,171 @@
+"""Headless first-login for a terminal.
+
+MetaTrader stores its password encrypted with a machine-bound key, so a terminal
+copied to a new host cannot auto-login until it authenticates once on that host.
+This module automates that bootstrap:
+
+1. stop the systemd unit (frees the terminal slot)
+2. write a transient startup config (login/password/server), created fresh by
+   ``mktemp`` with mode 600, inside the unit's working directory
+3. launch the terminal once, in its own process group, reusing the unit's
+   ``WorkingDirectory`` / ``WINEPREFIX`` / ``DISPLAY``
+4. wait for ``config/accounts.ini`` to become newer than a marker stamped right
+   before launch — MetaTrader's signal that authentication succeeded and
+   credentials were re-encrypted for this host
+5. an ``EXIT``/signal trap *always* kills that process group (siblings share the
+   Wine prefix, so a blanket ``wineserver -k`` is wrong) and shreds the config,
+   even if an earlier step fails
+6. restart the unit, which now auto-logins from the saved file
+
+After this runs once, the terminal reconnects on its own across restarts.
+"""
+
+from __future__ import annotations
+
+from . import auth, scripts, ssh
+from .errors import ConfirmationRequiredError, Mt4ctlError, RemoteCommandError
+from .models import Env, Registry
+
+
+def build_login_script(
+    service: str,
+    data_dir: str,
+    account: str,
+    server: str,
+    password: str,
+    *,
+    wait_seconds: int = 120,
+) -> str:
+    """Build the self-contained user-side bootstrap script (see module docstring)."""
+    # Credentials are written into a quoted heredoc below (no shell expansion),
+    # but a newline could still smuggle in a heredoc terminator or corrupt the
+    # ini. MT4 login/server/password are single-line tokens, so reject newlines.
+    for field, value in (("account", account), ("server", server), ("password", password)):
+        if "\n" in value or "\r" in value:
+            raise Mt4ctlError(f"{field} must not contain newlines")
+    svc = scripts.sh_quote(service)
+    ddir = scripts.sh_quote(data_dir)
+    return f"""\
+set +e
+SVC={svc}
+DDIR={ddir}
+WORKDIR=$(systemctl show -p WorkingDirectory --value "$SVC" 2>/dev/null)
+ENV=$(systemctl show -p Environment --value "$SVC" 2>/dev/null)
+WP=$(echo "$ENV" | tr ' ' '\\n' | sed -n 's/^WINEPREFIX=//p' | head -1)
+DISP=$(echo "$ENV" | tr ' ' '\\n' | sed -n 's/^DISPLAY=//p' | head -1)
+[ -z "$WORKDIR" ] && WORKDIR="$DDIR"
+[ -z "$DISP" ] && DISP=:0
+
+INI=""
+MARKER=""
+PGID=""
+cleanup() {{
+  [ -n "$PGID" ] && kill -TERM -"$PGID" 2>/dev/null
+  sleep 1
+  [ -n "$PGID" ] && kill -KILL -"$PGID" 2>/dev/null
+  [ -n "$INI" ] && {{ shred -u "$INI" 2>/dev/null || rm -f "$INI"; }}
+  [ -n "$MARKER" ] && rm -f "$MARKER" 2>/dev/null
+}}
+trap cleanup EXIT HUP INT TERM
+
+INI=$(mktemp "$WORKDIR/mt4ctl-login.XXXXXX.ini" 2>/dev/null) || {{ echo "LOGIN|error=mktemp"; exit 1; }}
+chmod 600 "$INI"
+INIBASE=$(basename "$INI")
+ACCFILE="$DDIR/config/accounts.ini"
+MARKER=$(mktemp 2>/dev/null) || MARKER="/tmp/mt4ctl-marker.$$"
+
+cat > "$INI" <<'INICFG'
+[Common]
+Login={account}
+Password={password}
+Server={server}
+KeepPrivate=1
+NewsEnable=false
+CertInstall=false
+[Experts]
+AllowLiveTrading=false
+Enabled=false
+INICFG
+
+cd "$WORKDIR" || {{ echo "LOGIN|error=workdir"; exit 1; }}
+: > "$MARKER"
+sleep 1
+WINEPREFIX="$WP" DISPLAY="$DISP" setsid wine terminal.exe /portable "$INIBASE" >/dev/null 2>&1 &
+PGID=$!
+
+ok=0
+for _ in $(seq 1 {wait_seconds}); do
+  if [ "$ACCFILE" -nt "$MARKER" ]; then ok=1; break; fi
+  sleep 1
+done
+echo "LOGIN|ok=$ok"
+"""
+
+
+async def login(
+    registry: Registry,
+    terminal_id: str,
+    *,
+    account: str | None = None,
+    server: str,
+    password: str | None = None,
+    confirm: bool = False,
+    wait_seconds: int = 120,
+) -> str:
+    """Perform a one-time headless login, then restart the unit for auto-reconnect.
+
+    Args:
+        terminal_id: terminal to log in.
+        account: login number; defaults to the terminal's configured account.
+        server: broker server name, e.g. ``ExampleBroker-Demo``.
+        password: explicit password; otherwise resolved via :mod:`mt4ctl.auth`.
+        confirm: required (``True``) for live terminals.
+        wait_seconds: how long to wait for authentication to land.
+
+    Returns:
+        A short human-readable summary of the outcome.
+    """
+    term = registry.terminal(terminal_id)
+    host = registry.host_of(term)
+    if term.env is Env.LIVE and not confirm:
+        raise ConfirmationRequiredError(terminal_id, "login")
+
+    login_account = account or term.account
+    if not login_account:
+        raise Mt4ctlError(f"terminal {terminal_id!r} has no account configured; pass account=")
+    secret = auth.resolve_password(login_account, password)
+
+    # Stop the unit so the one-shot owns the terminal slot; abort if it fails.
+    await ssh.run(
+        host, scripts.build_control_script(term.service, "stop"), root=True, check=True
+    )
+    script = build_login_script(
+        term.service, term.data_dir, login_account, server, secret, wait_seconds=wait_seconds
+    )
+    result = await ssh.run(host, script, timeout=wait_seconds + 30, check=False)
+
+    # Bring the unit back; it auto-logins from the now-saved accounts.ini.
+    try:
+        await ssh.run(
+            host, scripts.build_control_script(term.service, "start"), root=True, check=True
+        )
+        restarted = True
+    except RemoteCommandError:
+        restarted = False
+
+    if "LOGIN|ok=1" in result.stdout:
+        msg = (
+            f"{terminal_id}: logged in to account {login_account} on {server}; "
+            f"credentials saved."
+        )
+    else:
+        msg = (
+            f"{terminal_id}: login did NOT confirm within {wait_seconds}s "
+            f"(account {login_account} on {server}); check `mt4_logs` and verify the "
+            f"server name and password."
+        )
+    # The restart outcome is reported on every path so a stopped unit is never
+    # hidden behind a login message.
+    if restarted:
+        return msg + " Unit restarted for auto-reconnect."
+    return msg + " WARNING: restarting the unit failed — run `mt4_control` start."

mt4ctl/models.py

@@ -0,0 +1,139 @@
+"""Domain models for the terminal registry.
+
+The registry is intentionally plain data: a set of *hosts* (machines reachable
+over SSH) and a set of *terminals* (MetaTrader instances managed by ``systemd``
+on those hosts). Everything else in :mod:`mt4ctl` operates on these models.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from .errors import UnknownTargetError
+
+
+class HostKind(StrEnum):
+    """How commands are dispatched on a host.
+
+    ``NATIVE``
+        A plain Linux box. Commands run directly; root is obtained via ``sudo``.
+    ``WSL``
+        A Windows host running WSL2. Commands are wrapped in
+        ``wsl -d <distro> -- ...`` and root is obtained via ``wsl -u root``.
+    """
+
+    NATIVE = "native"
+    WSL = "wsl"
+
+
+class Env(StrEnum):
+    """Risk tier of a terminal.
+
+    ``LIVE`` terminals trade real money, so mutating operations on them require
+    an explicit ``confirm=true`` from the caller.
+    """
+
+    DEMO = "demo"
+    LIVE = "live"
+
+
+@dataclass(frozen=True, slots=True)
+class Host:
+    """A machine reachable over SSH that runs one or more terminals."""
+
+    id: str
+    ssh: str
+    """SSH destination — an alias from ``~/.ssh/config`` or ``user@host``."""
+    kind: HostKind = HostKind.NATIVE
+    wsl_distro: str | None = None
+    """Required when :attr:`kind` is :data:`HostKind.WSL`."""
+    broker_host: str | None = None
+    """Optional broker hostname used to detect live connections via ``ss``."""
+
+    def __post_init__(self) -> None:
+        if self.kind is HostKind.WSL and not self.wsl_distro:
+            raise ValueError(f"host {self.id!r} is kind=wsl but has no wsl_distro")
+
+
+@dataclass(frozen=True, slots=True)
+class Terminal:
+    """A single MetaTrader terminal managed by ``systemd``."""
+
+    id: str
+    host: str
+    """Id of the owning :class:`Host`."""
+    service: str
+    """The ``systemd`` unit name, e.g. ``mt4-demo3``."""
+    data_dir: str
+    """Absolute path to the terminal data folder (parent of ``logs/``)."""
+    display: str = ":0"
+    """X11 display used for screenshots, e.g. ``:99``."""
+    account: str | None = None
+    """Login number — labels output and locates the window for screenshots."""
+    env: Env = Env.DEMO
+    window_match: str | None = None
+    """Override window-search string; defaults to :attr:`account`."""
+
+    @property
+    def window_query(self) -> str | None:
+        """The string used to find this terminal's window with ``xdotool``."""
+        return self.window_match or self.account
+
+
+@dataclass(frozen=True, slots=True)
+class TerminalStatus:
+    """Resolved runtime status of a terminal."""
+
+    id: str
+    host: str
+    env: Env
+    account: str | None
+    service_state: str
+    """Raw ``systemctl is-active`` value: ``active`` / ``inactive`` / ``failed``…"""
+    connected: bool | None
+    """True/False if a broker connection could be determined, else ``None``."""
+    log_age_seconds: int | None
+    """Seconds since the newest log file was written, or ``None`` if no logs."""
+    last_event: str | None = None
+    """Most recent connection-related log line, if any."""
+
+    @property
+    def healthy(self) -> bool:
+        """A terminal is healthy when its service is active and it is connected."""
+        return self.service_state == "active" and self.connected is True
+
+
+@dataclass(frozen=True, slots=True)
+class Registry:
+    """The full set of configured hosts and terminals."""
+
+    hosts: dict[str, Host] = field(default_factory=dict)
+    terminals: dict[str, Terminal] = field(default_factory=dict)
+
+    def terminal(self, terminal_id: str) -> Terminal:
+        try:
+            return self.terminals[terminal_id]
+        except KeyError:
+            raise UnknownTargetError(
+                f"unknown terminal {terminal_id!r}; known: "
+                f"{', '.join(sorted(self.terminals)) or '(none)'}"
+            ) from None
+
+    def host(self, host_id: str) -> Host:
+        try:
+            return self.hosts[host_id]
+        except KeyError:
+            raise UnknownTargetError(
+                f"unknown host {host_id!r}; known: {', '.join(sorted(self.hosts)) or '(none)'}"
+            ) from None
+
+    def host_of(self, terminal: Terminal) -> Host:
+        return self.host(terminal.host)
+
+    def by_host(self) -> dict[str, list[Terminal]]:
+        """Group terminals by their host id (stable order)."""
+        grouped: dict[str, list[Terminal]] = {}
+        for term in self.terminals.values():
+            grouped.setdefault(term.host, []).append(term)
+        return grouped