ellmos-servercommander-mcp 0.1.0-alpha.1

package/KONZEPT.md

@@ -0,0 +1,91 @@
+# ellmos-servercommander-mcp — Konzept
+
+> Server-Operations als MCP: Deploy, Mail, Logs, Health-Checks.
+> Aus .UMBRUCH-Tools extrahiert und parametrisiert.
+
+## Tools
+
+| Tool | Quelle | Beschreibung |
+|---|---|---|
+| `sc_deploy` | .UMBRUCH deploy.py (~221 LoC) | SFTP-Delta-Deploy mit SHA256 (parametrisiert: host, user, remote_path) |
+| `sc_deploy_status` | .UMBRUCH deploy.py | Letztes Deployment prüfen (Zeitstempel, geänderte Dateien, Dauer) |
+| `sc_mail_list` | .UMBRUCH cli.py (~516 LoC) | IMAP-Postfach auflisten (Ordner, ungelesen, letzte N) |
+| `sc_mail_read` | .UMBRUCH cli.py | E-Mail lesen (nach ID oder Suchfilter) |
+| `sc_mail_send` | .UMBRUCH cli.py | E-Mail senden (SMTP, mit Anhängen) |
+| `sc_mail_search` | .UMBRUCH cli.py | E-Mails durchsuchen (FTS, Datum, Absender) |
+| `sc_logs_analyze` | .UMBRUCH traffic_analyzer.py | Server-Logs parsen (Apache/Nginx), Bot-Filterung, Traffic-Stats |
+| `sc_health_check` | neu | HTTP-Endpoint(s) prüfen, Status-Codes + Latenz melden |
+
+## Vorarbeiten
+
+### De-Hardcoding (deploy.py)
+- Aktuell hardcoded: projektspezifischer Host, SFTP-Account und feste Pfade
+- Ziel: host/user/remote_path/local_path als Tool-Argumente ODER Config-Profile
+- Config-Profile für wiederkehrende Deploys: `[profiles.umbruch]`, `[profiles.other]`
+
+### Mail-Kern extrahieren (cli.py)
+- GUI-Code (gui.py, 2935 LoC) bleibt draußen
+- CLI-Kern (~516 LoC) als Basis: IMAP-Verbindung, SMTP-Versand, FTS5-Cache
+- Credential-Handling: Config-Datei mit verschlüsseltem Passwort oder Env-Variable
+
+### Kein Hardcoding von Credentials
+- Alle Secrets via Config oder Env-Variablen
+- Referenz: `$SFTP_PASSWORD`, `$IMAP_PASSWORD` etc.
+
+## Architektur
+
+```
+ellmos-servercommander-mcp/
+├── src/servercommander/
+│   ├── server.py        # MCP-Server Entry Point
+│   ├── config.py        # Konfiguration
+│   ├── deploy.py        # sc_deploy, sc_deploy_status
+│   ├── mail.py          # sc_mail_list/read/send/search
+│   ├── logs.py          # sc_logs_analyze
+│   └── health.py        # sc_health_check
+├── config/
+│   └── servercommander.example.toml
+├── tests/
+└── pyproject.toml
+```
+
+## Konfigurationsbeispiel
+
+```toml
+[server]
+name = "ellmos-servercommander"
+
+[deploy.profiles.example_site]
+host = "sftp.example.com"
+user = "deploy-user"
+remote_path = "/var/www/example"
+local_path = "./dist"
+protocol = "sftp"
+
+[mail]
+imap_host = "imap.example.com"
+imap_port = 993
+smtp_host = "smtp.example.com"
+smtp_port = 587
+username = "$MAIL_USER"
+password = "$MAIL_PASSWORD"
+cache_db = "~/.servercommander/mail_cache.db"
+
+[logs]
+default_format = "apache"
+
+[health]
+timeout = 5
+endpoints = [
+    "https://example.com/health",
+]
+```
+
+## Quellmodule
+
+| Modul | Quellpfad | LoC | Dependencies |
+|---|---|---|---|
+| deploy.py | `.TOPICS/.UMBRUCH/deploy.py` | ~221 | paramiko (SFTP) |
+| cli.py (Mail) | `.TOPICS/.UMBRUCH/cli.py` | ~516 | stdlib (imaplib, smtplib) |
+| traffic_analyzer.py | `.TOPICS/.UMBRUCH/traffic_analyzer.py` | ~300 | stdlib |
+| health.py | neu | ~50 | stdlib (urllib) |

package/README.md

@@ -0,0 +1,72 @@
+# ellmos-servercommander-mcp
+
+Alpha-MCP-Server für Server-Operationen: Deployment-Planung, Mail-Status, Log-Analyse und HTTP-Health-Checks.
+
+## Status
+
+- Transport: stdio über das Python-MCP-SDK
+- Paketstatus: Alpha-Paket, GitHub-Repo unter `ellmos-ai` vorgesehen
+- Aktiver Kern: MCP-Tool-Liste, MCP-Tool-Dispatch, Config-Lader, `sc_logs_analyze`, `sc_health_check`
+- Sichere Alpha-Handler: `sc_deploy` erstellt lokale SHA256-Manifeste im Dry-run, `sc_mail_*` führt noch keine IMAP/SMTP-Aktionen aus
+
+## Installation für lokale Tests
+
+```powershell
+cd "C:\Users\User\OneDrive\.TOPICS\.AI\.MCP\ellmos-servercommander-mcp"
+$env:PYTHONIOENCODING = "utf-8"
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Keine `.venv` im OneDrive-Ordner anlegen. Falls eine isolierte Umgebung gebraucht wird, außerhalb von OneDrive erstellen.
+
+## npm Alpha
+
+Das npm-Paket enthält einen Node-Wrapper, der den Python-Server startet. Voraussetzung bleibt Python 3.10+ mit installiertem Python-Paket `mcp>=1.0.0`.
+
+```powershell
+npm install -g ellmos-servercommander-mcp@alpha
+ellmos-servercommander
+```
+
+## Start
+
+```powershell
+ellmos-servercommander
+```
+
+Oder direkt aus dem Quellbaum:
+
+```powershell
+$env:PYTHONPATH = "src"
+python -m servercommander.server
+```
+
+## Konfiguration
+
+Beispiel: [config/servercommander.example.toml](config/servercommander.example.toml)
+
+Standardpfade:
+
+- `%USERPROFILE%\.servercommander\config.toml`
+- `%USERPROFILE%\.config\servercommander\config.toml`
+- Override per `SERVERCOMMANDER_CONFIG`
+
+Secrets sollen als Umgebungsvariablen referenziert werden, zum Beispiel `$MAIL_PASSWORD` oder `$SFTP_PASSWORD`.
+
+## Tools
+
+- `sc_health_check`: prüft HTTP-Endpunkte und meldet Status-Code plus Latenz
+- `sc_logs_analyze`: analysiert Apache-/Nginx-Access-Logs aus Text oder Datei
+- `sc_deploy`: erstellt im Alpha-Modus einen Deployment-Plan mit lokalem SHA256-Manifest, führt aber noch keinen Upload aus
+- `sc_deploy_status`: zeigt konfigurierte Deploy-Profile und den noch fehlenden History-Status
+- `sc_mail_list`, `sc_mail_read`, `sc_mail_send`, `sc_mail_search`: liefern aktuell sichere Alpha-Statusantworten ohne IMAP/SMTP-Verbindung
+
+## Entwicklung
+
+```powershell
+$env:PYTHONIOENCODING = "utf-8"
+python -m pytest -q
+```
+
+Der nächste sinnvolle Schritt ist die Extraktion der echten SFTP-, IMAP/SMTP- und erweiterten Traffic-Module aus `.UMBRUCH` in credential-freie Adapter mit lokalen Tests.

package/bin/ellmos-servercommander.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+const { spawn } = require("node:child_process");
+const path = require("node:path");
+const pkg = require("../package.json");
+
+if (process.argv.includes("--version")) {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const python = process.env.PYTHON || (process.platform === "win32" ? "python" : "python3");
+const srcPath = path.resolve(__dirname, "..", "src");
+const env = {
+  ...process.env,
+  PYTHONPATH: process.env.PYTHONPATH ? `${srcPath}${path.delimiter}${process.env.PYTHONPATH}` : srcPath,
+};
+
+const child = spawn(python, ["-m", "servercommander.server"], {
+  stdio: "inherit",
+  env,
+});
+
+child.on("error", (error) => {
+  console.error(`Failed to start Python runtime '${python}': ${error.message}`);
+  console.error("Install Python 3.10+ and the Python dependency 'mcp>=1.0.0'.");
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 0);
+});

package/config/servercommander.example.toml

@@ -0,0 +1,38 @@
+# ellmos-servercommander-mcp — Konfiguration
+# Kopieren nach ~/.servercommander/config.toml und anpassen.
+
+[server]
+name = "ellmos-servercommander"
+
+# --- Deploy-Profile ---
+[deploy.profiles.example_site]
+host = "sftp.example.com"
+user = "deploy-user"
+remote_path = "/var/www/example"
+local_path = "./dist"
+protocol = "sftp"
+# password = "$SFTP_PASSWORD"    # Env-Variable referenzieren
+
+# [deploy.profiles.other]
+# host = "..."
+
+# --- Mail ---
+[mail]
+imap_host = "imap.example.com"
+imap_port = 993
+smtp_host = "smtp.example.com"
+smtp_port = 587
+username = "$MAIL_USER"
+password = "$MAIL_PASSWORD"
+cache_db = "~/.servercommander/mail_cache.db"
+
+# --- Log-Analyse ---
+[logs]
+default_format = "apache"   # apache | nginx
+
+# --- Health-Checks ---
+[health]
+timeout = 5
+endpoints = [
+    "https://example.com/health",
+]

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ellmos-servercommander-mcp",
+  "version": "0.1.0-alpha.1",
+  "description": "Alpha MCP server for server operations: deploy dry-runs, mail status, log analysis, and health checks.",
+  "type": "commonjs",
+  "license": "MIT",
+  "author": "Lukas Geiger",
+  "homepage": "https://github.com/ellmos-ai/ellmos-servercommander-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ellmos-ai/ellmos-servercommander-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ellmos-ai/ellmos-servercommander-mcp/issues"
+  },
+  "bin": {
+    "ellmos-servercommander": "bin/ellmos-servercommander.js"
+  },
+  "files": [
+    "bin/",
+    "config/",
+    "src/",
+    "README.md",
+    "KONZEPT.md",
+    "pyproject.toml"
+  ],
+  "keywords": [
+    "mcp",
+    "server",
+    "deploy",
+    "logs",
+    "health-checks",
+    "ellmos"
+  ],
+  "scripts": {
+    "test": "python -m pytest -q",
+    "smoke": "node bin/ellmos-servercommander.js --version"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ellmos-servercommander-mcp"
+version = "0.1.0"
+description = "MCP server for server operations: deploy, mail, log analysis, health checks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Lukas Geiger" }]
+keywords = ["mcp", "deploy", "server-management", "ellmos"]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.optional-dependencies]
+sftp = ["paramiko>=3.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+ellmos-servercommander = "servercommander.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/servercommander"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

package/src/servercommander/__init__.py

@@ -0,0 +1,3 @@
+"""ellmos-servercommander-mcp — Server operations via MCP."""
+
+__version__ = "0.1.0"

package/src/servercommander/config.py

@@ -0,0 +1,71 @@
+"""Configuration loader for ServerCommander MCP."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+
+DEFAULT_CONFIG_PATHS = [
+    Path.home() / ".servercommander" / "config.toml",
+    Path.home() / ".config" / "servercommander" / "config.toml",
+]
+
+
+@dataclass
+class ServerCommanderConfig:
+    server_name: str = "ellmos-servercommander"
+    deploy_profiles: dict[str, dict[str, Any]] = field(default_factory=dict)
+    mail: dict[str, Any] = field(default_factory=dict)
+    logs: dict[str, Any] = field(default_factory=dict)
+    health: dict[str, Any] = field(default_factory=dict)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def deploy_profile(self, name: str) -> dict[str, Any]:
+        return self.deploy_profiles.get(name, {})
+
+
+def load_config(path: str | Path | None = None) -> ServerCommanderConfig:
+    """Load TOML config. Missing config is valid for alpha-safe defaults."""
+    if path is None:
+        env_path = os.environ.get("SERVERCOMMANDER_CONFIG")
+        if env_path:
+            path = Path(env_path)
+        else:
+            for candidate in DEFAULT_CONFIG_PATHS:
+                if candidate.exists():
+                    path = candidate
+                    break
+
+    if path is None or not Path(path).exists():
+        return ServerCommanderConfig()
+
+    with open(path, "rb") as f:
+        raw = tomllib.load(f)
+
+    deploy = raw.get("deploy", {})
+    profiles = deploy.get("profiles", {}) if isinstance(deploy, dict) else {}
+    server = raw.get("server", {})
+
+    return ServerCommanderConfig(
+        server_name=server.get("name", "ellmos-servercommander"),
+        deploy_profiles=profiles if isinstance(profiles, dict) else {},
+        mail=raw.get("mail", {}),
+        logs=raw.get("logs", {}),
+        health=raw.get("health", {}),
+        raw=raw,
+    )
+
+
+def resolve_env_value(value: Any) -> Any:
+    """Resolve config values of the form '$ENV_NAME' without exposing secrets."""
+    if isinstance(value, str) and value.startswith("$") and len(value) > 1:
+        return os.environ.get(value[1:], "")
+    return value

package/src/servercommander/deploy.py

@@ -0,0 +1,100 @@
+"""Alpha deploy handlers for ServerCommander.
+
+Real SFTP deployment is intentionally not executed in this alpha layer.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from servercommander.config import ServerCommanderConfig
+
+SKIP_DIRS = {".git", "__pycache__", ".pytest_cache", ".ruff_cache", ".mypy_cache", ".venv", "venv"}
+
+
+async def sc_deploy(
+    config: ServerCommanderConfig,
+    profile: str | None = None,
+    local_path: str | None = None,
+    remote_path: str | None = None,
+    dry_run: bool = True,
+) -> dict[str, Any]:
+    """Return a deploy plan. Non-dry-run execution is not implemented yet."""
+    if not dry_run:
+        raise ValueError("sc_deploy execution is not implemented in the alpha server; use dry_run=true")
+
+    profile_config = config.deploy_profile(profile or "") if profile else {}
+    plan = {
+        "profile": profile,
+        "host": profile_config.get("host"),
+        "user": profile_config.get("user"),
+        "local_path": local_path or profile_config.get("local_path"),
+        "remote_path": remote_path or profile_config.get("remote_path"),
+        "protocol": profile_config.get("protocol", "sftp"),
+    }
+    missing = [key for key in ("host", "user", "local_path", "remote_path") if not plan.get(key)]
+    manifest = _build_manifest(plan["local_path"]) if plan.get("local_path") else None
+
+    return {
+        "status": "dry_run",
+        "ready": not missing,
+        "missing": missing,
+        "plan": plan,
+        "manifest": manifest,
+    }
+
+
+async def sc_deploy_status(
+    config: ServerCommanderConfig,
+    profile: str | None = None,
+) -> dict[str, Any]:
+    """Report configured deploy profile status for the alpha server."""
+    profiles = sorted(config.deploy_profiles)
+    selected = config.deploy_profile(profile or "") if profile else None
+    return {
+        "status": "not_recorded",
+        "message": "Deployment history storage is not implemented yet.",
+        "profiles": profiles,
+        "selected_profile": selected,
+    }
+
+
+def _build_manifest(local_path: str) -> dict[str, Any]:
+    root = Path(local_path).expanduser()
+    if not root.exists():
+        return {"status": "missing_local_path", "path": str(root), "files": [], "total_bytes": 0}
+    if root.is_file():
+        return {"status": "ok", "path": str(root), "files": [_file_entry(root, root.parent)], "total_bytes": root.stat().st_size}
+
+    files = []
+    total_bytes = 0
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
+            continue
+        entry = _file_entry(path, root)
+        files.append(entry)
+        total_bytes += entry["size"]
+
+    return {
+        "status": "ok",
+        "path": str(root),
+        "file_count": len(files),
+        "total_bytes": total_bytes,
+        "files": files,
+    }
+
+
+def _file_entry(path: Path, root: Path) -> dict[str, Any]:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return {
+        "path": path.relative_to(root).as_posix(),
+        "size": path.stat().st_size,
+        "sha256": digest.hexdigest(),
+    }

package/src/servercommander/health.py

@@ -0,0 +1,65 @@
+"""HTTP health checks for ServerCommander."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from servercommander.config import ServerCommanderConfig
+
+
+async def sc_health_check(
+    config: ServerCommanderConfig,
+    endpoints: list[str] | None = None,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Check HTTP endpoints and report status codes plus latency."""
+    configured_endpoints = config.health.get("endpoints", [])
+    selected_endpoints = endpoints if endpoints is not None else configured_endpoints
+    check_timeout = float(timeout if timeout is not None else config.health.get("timeout", 5))
+
+    if not selected_endpoints:
+        return {
+            "status": "no_endpoints",
+            "ok": False,
+            "timeout": check_timeout,
+            "results": [],
+        }
+
+    results = [_check_one(endpoint, check_timeout) for endpoint in selected_endpoints]
+    return {
+        "status": "ok" if all(result["ok"] for result in results) else "degraded",
+        "ok": all(result["ok"] for result in results),
+        "timeout": check_timeout,
+        "results": results,
+    }
+
+
+def _check_one(endpoint: str, timeout: float) -> dict[str, Any]:
+    started = time.perf_counter()
+    request = Request(endpoint, method="GET", headers={"User-Agent": "ellmos-servercommander/0.1"})
+
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            status_code = int(response.status)
+            ok = 200 <= status_code < 400
+            error = None
+    except HTTPError as exc:
+        status_code = int(exc.code)
+        ok = False
+        error = str(exc)
+    except (URLError, TimeoutError, OSError) as exc:
+        status_code = None
+        ok = False
+        error = str(exc)
+
+    elapsed_ms = round((time.perf_counter() - started) * 1000, 2)
+    return {
+        "endpoint": endpoint,
+        "ok": ok,
+        "status_code": status_code,
+        "latency_ms": elapsed_ms,
+        "error": error,
+    }

package/src/servercommander/logs.py

@@ -0,0 +1,78 @@
+"""Apache/Nginx access-log analysis for ServerCommander."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from servercommander.config import ServerCommanderConfig
+
+
+LOG_PATTERN = re.compile(
+    r'(?P<host>\S+)\s+\S+\s+\S+\s+\[(?P<time>[^\]]+)\]\s+'
+    r'"(?P<method>[A-Z]+)\s+(?P<path>\S+)(?:\s+HTTP/[0-9.]+)?"\s+'
+    r'(?P<status>\d{3})\s+(?P<size>\S+)'
+    r'(?:\s+"(?P<referer>[^"]*)"\s+"(?P<agent>[^"]*)")?'
+)
+
+BOT_MARKERS = ("bot", "crawler", "spider", "slurp", "bingpreview")
+
+
+async def sc_logs_analyze(
+    config: ServerCommanderConfig,
+    log_text: str | None = None,
+    log_path: str | None = None,
+    top_paths: int = 10,
+    format: str | None = None,
+) -> dict[str, Any]:
+    """Analyze access logs from inline text or a local file path."""
+    _ = config, format
+    text = _load_log_text(log_text, log_path)
+    lines = [line for line in text.splitlines() if line.strip()]
+
+    status_counts: Counter[str] = Counter()
+    status_classes: Counter[str] = Counter()
+    method_counts: Counter[str] = Counter()
+    path_counts: Counter[str] = Counter()
+    agent_counts: Counter[str] = Counter()
+    bot_requests = 0
+    parsed_lines = 0
+
+    for line in lines:
+        match = LOG_PATTERN.search(line)
+        if not match:
+            continue
+        parsed_lines += 1
+        status = match.group("status")
+        status_counts[status] += 1
+        status_classes[f"{status[0]}xx"] += 1
+        method_counts[match.group("method")] += 1
+        path_counts[match.group("path")] += 1
+        agent = match.group("agent") or ""
+        if agent:
+            agent_counts[agent] += 1
+        if any(marker in agent.lower() for marker in BOT_MARKERS):
+            bot_requests += 1
+
+    return {
+        "status": "ok",
+        "total_lines": len(lines),
+        "parsed_lines": parsed_lines,
+        "unparsed_lines": len(lines) - parsed_lines,
+        "status_counts": dict(status_counts),
+        "status_classes": dict(status_classes),
+        "method_counts": dict(method_counts),
+        "top_paths": path_counts.most_common(int(top_paths)),
+        "top_agents": agent_counts.most_common(10),
+        "bot_requests": bot_requests,
+    }
+
+
+def _load_log_text(log_text: str | None, log_path: str | None) -> str:
+    if log_text is not None:
+        return log_text
+    if log_path is not None:
+        return Path(log_path).expanduser().read_text(encoding="utf-8", errors="replace")
+    raise ValueError("Provide either log_text or log_path")

package/src/servercommander/mail.py

@@ -0,0 +1,50 @@
+"""Alpha mail handlers for ServerCommander.
+
+These handlers expose safe configuration/status checks. Real IMAP/SMTP
+operations will be added after credential handling is finalized.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from servercommander.config import ServerCommanderConfig, resolve_env_value
+
+
+async def sc_mail_list(config: ServerCommanderConfig, folder: str = "INBOX", limit: int = 10) -> dict[str, Any]:
+    return _mail_alpha_response(config, "list", {"folder": folder, "limit": limit})
+
+
+async def sc_mail_read(config: ServerCommanderConfig, message_id: str | None = None) -> dict[str, Any]:
+    return _mail_alpha_response(config, "read", {"message_id": message_id})
+
+
+async def sc_mail_send(
+    config: ServerCommanderConfig,
+    to: str,
+    subject: str,
+    body: str,
+) -> dict[str, Any]:
+    return _mail_alpha_response(
+        config,
+        "send",
+        {"to": to, "subject": subject, "body_preview": body[:80]},
+    )
+
+
+async def sc_mail_search(config: ServerCommanderConfig, query: str, limit: int = 10) -> dict[str, Any]:
+    return _mail_alpha_response(config, "search", {"query": query, "limit": limit})
+
+
+def _mail_alpha_response(config: ServerCommanderConfig, action: str, request: dict[str, Any]) -> dict[str, Any]:
+    mail = config.mail
+    username = resolve_env_value(mail.get("username", ""))
+    password = resolve_env_value(mail.get("password", ""))
+    configured = bool(mail.get("imap_host") and mail.get("smtp_host") and username and password)
+    return {
+        "status": "not_implemented",
+        "action": action,
+        "configured": configured,
+        "request": request,
+        "message": "IMAP/SMTP execution is not implemented in the alpha server.",
+    }

package/src/servercommander/server.py

@@ -0,0 +1,169 @@
+"""ServerCommander MCP Server - Entry Point."""
+
+from __future__ import annotations
+
+import asyncio
+from functools import partial
+import logging
+import sys
+from typing import Any
+
+import mcp.types as types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from servercommander.config import ServerCommanderConfig, load_config
+from servercommander.deploy import sc_deploy, sc_deploy_status
+from servercommander.health import sc_health_check
+from servercommander.logs import sc_logs_analyze
+from servercommander.mail import sc_mail_list, sc_mail_read, sc_mail_search, sc_mail_send
+from servercommander.tooling import ToolDefinition
+
+app = Server("ellmos-servercommander")
+logger = logging.getLogger("servercommander")
+_registry: "ServerCommanderRegistry | None" = None
+
+
+class ServerCommanderRegistry:
+    """Owns ServerCommander tool definitions and dispatch."""
+
+    def __init__(self, config: ServerCommanderConfig):
+        self.config = config
+        self._tools = build_tools(config)
+        self._handlers = {tool.name: tool.handler for tool in self._tools}
+
+    def list_tools(self) -> list[types.Tool]:
+        return [tool.as_mcp_tool() for tool in self._tools]
+
+    async def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:
+        handler = self._handlers.get(name)
+        if handler is None:
+            raise ValueError(f"Unknown ServerCommander tool: {name}")
+        return await handler(**(arguments or {}))
+
+
+def get_registry() -> ServerCommanderRegistry:
+    global _registry
+    if _registry is None:
+        _registry = ServerCommanderRegistry(load_config())
+    return _registry
+
+
+def object_schema(properties: dict[str, Any], required: list[str] | None = None) -> dict[str, Any]:
+    schema: dict[str, Any] = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def build_tools(config: ServerCommanderConfig) -> list[ToolDefinition]:
+    return [
+        ToolDefinition(
+            name="sc_deploy",
+            description="Build a safe deployment plan. Alpha only: execution requires dry_run=true.",
+            input_schema=object_schema(
+                {
+                    "profile": {"type": "string"},
+                    "local_path": {"type": "string"},
+                    "remote_path": {"type": "string"},
+                    "dry_run": {"type": "boolean", "default": True},
+                }
+            ),
+            handler=partial(sc_deploy, config),
+        ),
+        ToolDefinition(
+            name="sc_deploy_status",
+            description="Show configured deployment profiles and alpha deployment-history status.",
+            input_schema=object_schema({"profile": {"type": "string"}}),
+            handler=partial(sc_deploy_status, config),
+        ),
+        ToolDefinition(
+            name="sc_mail_list",
+            description="Alpha mail status endpoint for listing an IMAP folder.",
+            input_schema=object_schema(
+                {
+                    "folder": {"type": "string", "default": "INBOX"},
+                    "limit": {"type": "integer", "default": 10},
+                }
+            ),
+            handler=partial(sc_mail_list, config),
+        ),
+        ToolDefinition(
+            name="sc_mail_read",
+            description="Alpha mail status endpoint for reading a message.",
+            input_schema=object_schema({"message_id": {"type": "string"}}),
+            handler=partial(sc_mail_read, config),
+        ),
+        ToolDefinition(
+            name="sc_mail_send",
+            description="Alpha mail status endpoint for sending mail; does not send yet.",
+            input_schema=object_schema(
+                {
+                    "to": {"type": "string"},
+                    "subject": {"type": "string"},
+                    "body": {"type": "string"},
+                },
+                ["to", "subject", "body"],
+            ),
+            handler=partial(sc_mail_send, config),
+        ),
+        ToolDefinition(
+            name="sc_mail_search",
+            description="Alpha mail status endpoint for searching mail.",
+            input_schema=object_schema(
+                {"query": {"type": "string"}, "limit": {"type": "integer", "default": 10}},
+                ["query"],
+            ),
+            handler=partial(sc_mail_search, config),
+        ),
+        ToolDefinition(
+            name="sc_logs_analyze",
+            description="Analyze Apache/Nginx access logs from inline text or a local file path.",
+            input_schema=object_schema(
+                {
+                    "log_text": {"type": "string"},
+                    "log_path": {"type": "string"},
+                    "top_paths": {"type": "integer", "default": 10},
+                    "format": {"type": "string", "enum": ["apache", "nginx"]},
+                }
+            ),
+            handler=partial(sc_logs_analyze, config),
+        ),
+        ToolDefinition(
+            name="sc_health_check",
+            description="Check HTTP endpoints and return status codes plus latency.",
+            input_schema=object_schema(
+                {
+                    "endpoints": {"type": "array", "items": {"type": "string"}},
+                    "timeout": {"type": "number", "default": 5},
+                }
+            ),
+            handler=partial(sc_health_check, config),
+        ),
+    ]
+
+
+@app.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return get_registry().list_tools()
+
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    return await get_registry().call_tool(name, arguments)
+
+
+async def serve() -> None:
+    logger.info("ServerCommander starting...")
+
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(read_stream, write_stream, app.create_initialization_options())
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+    asyncio.run(serve())
+
+
+if __name__ == "__main__":
+    main()

package/src/servercommander/tooling.py

@@ -0,0 +1,23 @@
+"""Small MCP tool-definition helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+import mcp.types as types
+
+
+@dataclass
+class ToolDefinition:
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: Callable[..., Awaitable[dict[str, Any]]]
+
+    def as_mcp_tool(self) -> types.Tool:
+        return types.Tool(
+            name=self.name,
+            description=self.description,
+            inputSchema=self.input_schema,
+        )