mt4ctl 0.1.0__tar.gz

mt4ctl-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Format check (ruff)
+        run: ruff format --check src tests
+
+      - name: Type-check (mypy)
+        run: mypy
+
+      - name: Test (pytest)
+        run: pytest --cov=mt4ctl --cov-report=term-missing

mt4ctl-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+# Tag a release to publish:  git tag v0.1.0 && git push origin v0.1.0
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify tag matches project version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "tag=$TAG project=$VER"
+          test "$TAG" = "$VER" || { echo "::error::tag v$TAG does not match pyproject version $VER"; exit 1; }
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the environment registered with the PyPI Trusted Publisher.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mt4ctl
+    permissions:
+      id-token: write # OIDC token for PyPI Trusted Publishing (no API token needed)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the GitHub Release and attach artifacts
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes

mt4ctl-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# --- private infrastructure: never commit real hosts/accounts/secrets ---
+/terminals.yaml
+terminals.local.yaml
+credentials.json
+*.secret
+.env
+.env.*
+
+# --- python ---
+venv/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# --- tooling caches ---
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# --- local scratch ---
+.cache/
+*.png
+plans/
+
+# --- editors / OS ---
+.idea/
+.vscode/
+.DS_Store

mt4ctl-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+# Run `pre-commit install` once; hooks then run on every commit.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.14
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: detect-private-key

mt4ctl-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-23
+
+Initial release.
+
+### Added
+
+- MCP stdio server exposing six tools: `mt4_list`, `mt4_status`, `mt4_logs`,
+  `mt4_screenshot`, `mt4_control`, `mt4_login`.
+- YAML registry with validation; supports native Linux and WSL2 hosts.
+- Concurrent, per-terminal status with cgroup-based broker-connection attribution
+  (gated on root or matching service user, otherwise reported as unknown).
+- Headless first-login bootstrap with process-group-scoped cleanup and
+  credential shredding via a cleanup trap.
+- Live-trading guardrails (`confirm=true`) on mutating operations.
+- Credential resolution chain (argument → env var → secrets file) with a
+  permission check on the secrets file.
+- Human-friendly entry point (`--help`/`--version` and a TTY guard) plus
+  fail-fast config resolution and actionable SSH-failure errors.
+- Test suite, strict `mypy`, `ruff`, and a 3.11–3.13 CI matrix.
+
+[Unreleased]: https://github.com/ak40u/mt4ctl/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ak40u/mt4ctl/releases/tag/v0.1.0

mt4ctl-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Thanks for your interest in `mt4ctl`.
+
+## Dev setup
+
+```bash
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Before opening a PR
+
+All three must pass (CI enforces them on Python 3.11–3.13):
+
+```bash
+ruff check src tests
+mypy
+pytest
+```
+
+## Conventions
+
+- **Keep the core network-free.** Shell logic belongs in `scripts.py` /
+  `login.py` as pure builders; `ssh.py` is the only module that executes
+  commands. New behavior should be testable without a live host.
+- **Type everything.** `mypy` runs in strict mode.
+- **Actionable errors.** Raise the typed errors in `errors.py`; messages should
+  tell the caller how to recover.
+- **Never log secrets.** Passwords flow only through `auth.py` and the transient
+  remote login config, which is shredded after use.
+- **Conventional commits** (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`,
+  `chore:`).
+
+## Releasing
+
+Tagging a version publishes to **PyPI** via Trusted Publishing (OIDC — no stored
+tokens) and creates a **GitHub Release** with the wheel + sdist attached.
+
+One-time PyPI setup (account owner): add a pending publisher at
+https://pypi.org/manage/account/publishing/ for project `mt4ctl`, owner `ak40u`,
+repo `mt4ctl`, workflow `release.yml`, environment `pypi`.
+
+To cut a release:
+
+1. Bump `version` in `pyproject.toml` and `__version__` in
+   `src/mt4ctl/__init__.py`; update `CHANGELOG.md`.
+2. Commit, then tag and push:
+
+   ```bash
+   git tag v0.1.0 && git push origin v0.1.0
+   ```
+
+`release.yml` verifies the tag matches the project version, builds and
+`twine check`s the artifacts, publishes to PyPI, and creates the GitHub Release.
+
+## Adding a tool
+
+1. Implement the operation in `operations.py` (or a focused module) against the
+   `Registry`.
+2. Add a thin `@mcp.tool()` wrapper in `server.py` with a clear docstring.
+3. Cover the parsing / command construction with unit tests.
+4. Document it in `docs/tools.md`.

mt4ctl-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pavel Volkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mt4ctl-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: mt4ctl
+Version: 0.1.0
+Summary: MCP server for managing headless MetaTrader terminals over SSH (Wine + systemd)
+Project-URL: Homepage, https://github.com/ak40u/mt4ctl
+Project-URL: Repository, https://github.com/ak40u/mt4ctl
+Project-URL: Issues, https://github.com/ak40u/mt4ctl/issues
+Author-email: Pavel Volkov <pvolkov@live.ru>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: devops,mcp,metatrader,model-context-protocol,mt4,ssh,systemd,trading,wine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.2
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# mt4ctl
+
+**An MCP server for operating headless MetaTrader terminals — over SSH, from your agent.**
+
+Manage MetaTrader 4 terminals running under **Wine + systemd** on remote hosts
+(native Linux *or* WSL2) entirely through the [Model Context Protocol](https://modelcontextprotocol.io):
+check status, read logs, capture screenshots, control the systemd lifecycle, and
+perform the tricky **headless first-login** — all as clean, typed tools.
+
+[![CI](https://github.com/ak40u/mt4ctl/actions/workflows/ci.yml/badge.svg)](https://github.com/ak40u/mt4ctl/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mt4ctl)](https://pypi.org/project/mt4ctl/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![MCP](https://img.shields.io/badge/MCP-server-7C3AED)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+</div>
+
+---
+
+## Why
+
+Algo traders increasingly run MetaTrader 4 **headless on Linux** — Wine under
+`Xvfb`, supervised by `systemd`, no GUI. That's great for uptime and terrible for
+day-to-day operations: every "is it connected?", "restart that one", or "log this
+new account in" turns into a fragile chain of
+`ssh → (Windows cmd → wsl) → bash → systemctl → wine`, with quoting hazards at
+every hop.
+
+`mt4ctl` collapses that chain into a handful of MCP tools. Point it at a registry
+of your hosts and terminals, wire it into Claude (or any MCP client), and operate
+the whole farm conversationally:
+
+> *"Which demo terminals are down?"* · *"Restart demo2."* ·
+> *"Log demo2 into account 1000002 on ExampleBroker-Demo."* ·
+> *"Screenshot the live terminal so I can see the AutoTrading state."*
+
+## Quickstart (5 minutes)
+
+`mt4_list` works **offline** (no SSH/MT4 needed), so you can confirm the wiring
+before anything else lines up:
+
+```bash
+# 1. create a minimal registry
+mkdir -p ~/.config/mt4ctl
+cat > ~/.config/mt4ctl/terminals.yaml <<'YAML'
+hosts:
+  box: { ssh: my-ssh-alias, kind: native }
+terminals:
+  t1: { host: box, service: mt4-t1, data_dir: /home/trader/mt4/t1, account: "1000001" }
+YAML
+
+# 2. add to Claude Code (uvx runs the server straight from git — no install)
+claude mcp add --scope user mt4ctl \
+  --env MT4CTL_CONFIG="$HOME/.config/mt4ctl/terminals.yaml" \
+  -- uvx --from git+https://github.com/ak40u/mt4ctl mt4ctl
+```
+
+Then ask Claude: **"Use mt4_list to show my configured terminals."** You should
+see your `t1` row. Once the SSH alias and `systemd` unit line up, ask for
+**"mt4_status t1"**. Full setup and other clients are below.
+
+## Features
+
+- **Per-terminal connection detection** — attributes established broker sockets
+  to each terminal's `systemd` cgroup, so terminals sharing a host (and a Wine
+  prefix) are reported independently — not guessed from a host-wide count.
+- **Headless first-login** — automates the one-time bootstrap a migrated terminal
+  needs (MetaTrader's saved password is machine-bound), then hands control back
+  to `systemd` for automatic reconnection on every restart.
+- **Native *and* WSL2 hosts** — one registry, two execution models; commands are
+  base64-shipped so nothing breaks in the `cmd.exe → wsl.exe → bash` gauntlet.
+- **Live-trading guardrails** — terminals tagged `env: live` reject mutating
+  operations unless you pass `confirm=true`.
+- **Concurrent status** — hosts are polled in parallel via `asyncio`.
+- **Secrets stay secret** — passwords resolve from arg → env → secrets file,
+  are never logged, and the transient remote login config is `shred`-ed after use.
+
+## How it works
+
+```
+┌────────────┐   MCP/stdio   ┌──────────────────┐
+│ MCP client │ ────────────► │     mt4ctl       │
+│ (Claude…)  │               │  FastMCP server  │
+└────────────┘               └────────┬─────────┘
+                                       │ asyncio SSH (base64-framed)
+                 ┌─────────────────────┼─────────────────────┐
+                 ▼                                           ▼
+        ┌─────────────────┐                        ┌──────────────────┐
+        │  native Linux   │                        │  Windows + WSL2  │
+        │  sudo systemctl │                        │  wsl -u root --  │
+        ├─────────────────┤                        ├──────────────────┤
+        │ mt4-live-main…  │  systemd units running │ mt4-demo1…       │
+        │ wine terminal.exe (Xvfb display)         │ wine terminal.exe│
+        └─────────────────┘                        └──────────────────┘
+```
+
+A thin, typed core (`models` → `config` → `ssh` → `scripts` → `operations`/`login`)
+sits under the `server` adapter, so the logic is testable without a network and
+the MCP layer stays a one-line-per-tool shell.
+
+## Install
+
+The fastest path needs no clone and no global install — [`uv`](https://docs.astral.sh/uv/)
+runs `mt4ctl` straight from the repo and fetches a matching Python itself:
+
+```bash
+uvx --from git+https://github.com/ak40u/mt4ctl mt4ctl   # runs the stdio server
+```
+
+No `uv` yet? `curl -LsSf https://astral.sh/uv/install.sh | sh` — or skip it and use
+the `pipx` path below.
+
+Prefer a persistent `mt4ctl` command? Install it with `uv` or `pipx`:
+
+```bash
+uv tool install git+https://github.com/ak40u/mt4ctl
+# or
+pipx install git+https://github.com/ak40u/mt4ctl
+```
+
+For development:
+
+```bash
+git clone https://github.com/ak40u/mt4ctl.git && cd mt4ctl
+python -m venv venv && source venv/bin/activate
+pip install -e ".[dev]"
+```
+
+The server machine needs either `uv` or Python 3.11+, plus SSH access to your
+hosts. The remote hosts need the usual tools `mt4ctl` shells out to: `systemctl`,
+`ss`, `getent`, and (for screenshots) `imagemagick`/`scrot` + `xdotool`.
+
+## Configure
+
+Copy the example registry and fill in your real hosts and terminals:
+
+```bash
+mkdir -p ~/.config/mt4ctl
+cp examples/terminals.example.yaml ~/.config/mt4ctl/terminals.yaml
+```
+
+The registry is resolved from `MT4CTL_CONFIG`, then
+`~/.config/mt4ctl/terminals.yaml`, then `./terminals.yaml`. See
+[`examples/terminals.example.yaml`](examples/terminals.example.yaml) for the full
+schema and [`docs/configuration.md`](docs/configuration.md) for details.
+
+> **Keep your populated registry private.** It maps your accounts and
+> infrastructure. The default `.gitignore` excludes `terminals.yaml`.
+
+## Connect to an MCP client
+
+**Claude Code** — one command wires it up (user scope = available in every project):
+
+```bash
+claude mcp add --scope user mt4ctl \
+  --env MT4CTL_CONFIG="$HOME/.config/mt4ctl/terminals.yaml" \
+  -- uvx --from git+https://github.com/ak40u/mt4ctl mt4ctl
+```
+
+Or commit a project `.mcp.json` to share with a team (Claude Code expands `${HOME}`):
+
+```json
+{
+  "mcpServers": {
+    "mt4ctl": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/ak40u/mt4ctl", "mt4ctl"],
+      "env": { "MT4CTL_CONFIG": "${HOME}/.config/mt4ctl/terminals.yaml" }
+    }
+  }
+}
+```
+
+**Claude Desktop** — Settings → Developer → Edit Config (`claude_desktop_config.json`),
+same shape but use an **absolute** config path (Desktop does not expand `${HOME}`),
+and an absolute `command` path if `uvx` is not on the GUI app's `PATH` (`which uvx`):
+
+```json
+{
+  "mcpServers": {
+    "mt4ctl": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/ak40u/mt4ctl", "mt4ctl"],
+      "env": { "MT4CTL_CONFIG": "/Users/you/.config/mt4ctl/terminals.yaml" }
+    }
+  }
+}
+```
+
+> Installed `mt4ctl` persistently (uv/pipx)? Replace `command`/`args` with just
+> `"command": "mt4ctl"`.
+
+## Tools
+
+| Tool | Mutates | Description |
+| --- | :---: | --- |
+| `mt4_list` | – | List configured terminals (offline). |
+| `mt4_status` | – | Per-terminal service state + broker connection + log age. |
+| `mt4_logs` | – | Tail / grep a terminal's newest log file. |
+| `mt4_screenshot` | – | Capture a terminal window as PNG. |
+| `mt4_control` | ✓ | `start` / `stop` / `restart` a unit (live needs `confirm`). |
+| `mt4_login` | ✓ | One-time headless login for auto-reconnect (live needs `confirm`). |
+
+Full reference: [`docs/tools.md`](docs/tools.md).
+
+## Security
+
+- Mutations on `env: live` terminals require explicit `confirm=true`.
+- Credentials resolve from argument → `MT4CTL_PASSWORD_<account>` →
+  secrets file; they are never written to logs and the transient remote login
+  config is shredded after use.
+- All remote execution goes through your existing SSH config and key-based auth;
+  `mt4ctl` stores no credentials of its own.
+- During `mt4_login` the password is embedded in the base64-framed script handed
+  to `ssh`, so it is briefly visible in the local process list to your own user.
+  On the remote side it is written only to a fresh `mktemp` config (mode 600) that
+  a cleanup trap `shred`s on any exit path. On POSIX, the local secrets file is
+  rejected if it is readable by group/other.
+
+## Development
+
+```bash
+ruff check src tests      # lint
+mypy                      # type-check (strict)
+pytest                    # tests
+```
+
+See [`docs/architecture.md`](docs/architecture.md) for the module boundaries.
+
+## License
+
+MIT © Pavel Volkov. See [LICENSE](LICENSE).