ellmos-servercommander-mcp 0.1.0-alpha.5 → 0.1.0-alpha.7

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0-alpha.7 - 2026-06-13
+
+### Fixed
+- `sc_health_check`: `urlopen()` runs in worker threads via `asyncio.to_thread` + `asyncio.gather`, so concurrent health checks no longer block the MCP event loop.
+- npm package file selection now includes only Python source files from `src/`, preventing local `__pycache__` bytecode from entering the tarball.
+- Corrected the unreleased changelog entry for log-report persistence to use the implemented `persist_report`, `[logs].persist_reports`, and `[logs].reports_dir` names.
+
+### Added
+- `sc_mail_*`: action-specific readiness diagnostics now distinguish IMAP needs for list/read/search from SMTP needs for send, while keeping mail execution disabled in alpha.
+- `sc_logs_analyze`: optional persistence of log-analysis JSON reports to a configurable output directory; enabled via `persist_report` per call or `[logs].persist_reports` in `servercommander.toml`.
+- Example config keys `[logs].persist_reports` and `[logs].reports_dir` added to `config/servercommander.example.toml`.
+- `server.json` with MCP Registry metadata for `io.github.ellmos-ai/ellmos-servercommander-mcp`.
+- `llms.txt` with canonical project context, search phrases, disambiguation, current tools, and sibling ellmos MCP servers.
+- MIT `LICENSE` text so GitHub and package consumers can detect the repository license directly.
+
+### Changed
+- README and README_de: start tables, search/disambiguation context, and ellmos MCP family links.
+- Expanded npm and Python package keywords for server operations, MCP hosts, access-log analysis, deployment dry-runs, and health checks.
+- Included `server.json`, `llms.txt`, and `LICENSE` in the npm package file list.

package/KONZEPT.md

@@ -1,91 +1,93 @@
-# 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) |
+# 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, optional persistierte JSON-Reports |
+| `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"
+persist_reports = false
+reports_dir = "~/.servercommander/log_reports"
+
+[health]
+timeout = 5
+endpoints = [
+    "https://example.com/health",
+]
+```
+
+## Quellmodule
+
+| Modul | Herkunft | LoC | Dependencies |
+|---|---|---|---|
+| deploy.py | interne Extraktionsnotiz | ~221 | paramiko (SFTP) |
+| cli.py (Mail) | interne Extraktionsnotiz | ~516 | stdlib (imaplib, smtplib) |
+| traffic_analyzer.py | interne Extraktionsnotiz | ~300 | stdlib |
+| health.py | neu | ~50 | stdlib (urllib) |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Geiger
+
+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.

package/README.md

@@ -1,84 +1,168 @@
-# ellmos-servercommander-mcp
-
-<p align="center">
-  <img src="assets/servercommander-logo.jpg" alt="ellmos ServerCommander MCP logo" width="360">
-</p>
-
-Alpha MCP server for server operations: deployment dry-runs, mail status, access-log analysis, and HTTP health checks.
-
-German README: [README_de.md](README_de.md)
-
-## Status
-
-- Transport: stdio via the Python MCP SDK
-- Package status: public alpha package under `ellmos-ai`
-- Current core: MCP tool listing, MCP tool dispatch, config loading, HTTP health checks, richer access-log analysis
-- Safe alpha handlers: `sc_deploy` builds local SHA256 manifests and configuration diagnostics in dry-run mode; `sc_mail_*` reports mail configuration gaps without IMAP/SMTP operations
-- i18n: localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for `en`, `de`, `es`, `zh`, `ja`, `ru` with English fallback
-
-## Install
-
-The npm package contains a Node wrapper that starts the Python server. You still need Python 3.10+ and the Python package `mcp>=1.0.0`.
-
-```powershell
-npm install -g ellmos-servercommander-mcp@alpha
-ellmos-servercommander
-```
-
-For local development:
-
-```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
-```
-
-Do not create a `.venv` inside a OneDrive-synced folder. If you need an isolated environment, create it outside OneDrive.
-
-## Start From Source
-
-```powershell
-$env:PYTHONPATH = "src"
-python -m servercommander.server
-```
-
-## Configuration
-
-Example: [config/servercommander.example.toml](config/servercommander.example.toml)
-
-Default paths:
-
-- `%USERPROFILE%\.servercommander\config.toml`
-- `%USERPROFILE%\.config\servercommander\config.toml`
-- override with `SERVERCOMMANDER_CONFIG`
-
-Language can be configured with `[server].language`, `SERVERCOMMANDER_LANG`, or `SERVERCOMMANDER_LOCALE`.
-
-```toml
-[server]
-name = "ellmos-servercommander"
-language = "en" # en, de, es, zh, ja, ru
-```
-
-Secrets should be referenced through environment variables, for example `$MAIL_PASSWORD` or `$SFTP_PASSWORD`.
-
-## Tools
-
-- `sc_health_check`: checks HTTP endpoints and reports status code plus latency
-- `sc_logs_analyze`: analyzes Apache/Nginx access logs from inline text or a local file, including status classes, bytes, referers, error paths, and suspicious request markers
-- `sc_deploy`: creates a deployment plan with a local SHA256 manifest and profile diagnostics, but does not upload yet
-- `sc_deploy_status`: shows configured deploy profiles, selected-profile diagnostics, and the current alpha history status
-- `sc_mail_list`, `sc_mail_read`, `sc_mail_send`, `sc_mail_search`: safe alpha status responses with mail configuration diagnostics and no IMAP/SMTP connections
-
-## Development
-
-```powershell
-$env:PYTHONIOENCODING = "utf-8"
-$env:PYTHONDONTWRITEBYTECODE = "1"
-python -m pytest -q
-npm run smoke
-npm pack --dry-run
-```
-
-Next useful step: add explicitly configured execution adapters for SFTP and IMAP/SMTP, keep dry-run defaults, and extend log analysis with persisted reports.
+# ellmos-servercommander-mcp
+
+<p align="center">
+  <img src="assets/servercommander-logo.jpg" alt="ellmos ServerCommander MCP logo" width="360">
+</p>
+
+Alpha MCP server for server operations: deployment dry-runs, mail status, access-log analysis, and HTTP health checks.
+
+German README: [README_de.md](README_de.md)
+
+*Part of the [ellmos-ai](https://github.com/ellmos-ai) family.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/ellmos-servercommander-mcp.svg)](https://www.npmjs.com/package/ellmos-servercommander-mcp)
+[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-stdio-blueviolet.svg)](https://modelcontextprotocol.io/)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://www.npmjs.com/package/ellmos-servercommander-mcp)
+
+**Discoverability:** Published on [npm](https://www.npmjs.com/package/ellmos-servercommander-mcp) as `ellmos-servercommander-mcp`, described for MCP catalogs in [`server.json`](server.json), and summarized for AI search/indexing in [`llms.txt`](llms.txt).
+
+## Start Here
+
+| Goal | Start with |
+|---|---|
+| Add ServerCommander to Claude Desktop, Claude Code, Cursor, or another MCP host | [MCP Client Configuration](#mcp-client-configuration) |
+| Check a public or internal HTTP endpoint before a deploy | `sc_health_check` |
+| Inspect Apache/Nginx access logs for errors, bots, referrers, and suspicious paths | `sc_logs_analyze` |
+| Build a dry-run deployment manifest before SFTP/SSH execution exists | `sc_deploy` and `sc_deploy_status` |
+| Wire mail operations later without accidental sends today | `sc_mail_list`, `sc_mail_read`, `sc_mail_send`, `sc_mail_search` |
+
+## Status
+
+- Transport: stdio via the Python MCP SDK
+- Package status: public alpha package under `ellmos-ai`
+- Current core: MCP tool listing, MCP tool dispatch, config loading, HTTP health checks, richer access-log analysis with optional persisted JSON reports
+- Safe alpha handlers: `sc_deploy` builds local SHA256 manifests and configuration diagnostics in dry-run mode; `sc_mail_*` reports protocol-specific IMAP/SMTP readiness without opening mail connections
+- i18n: localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for `en`, `de`, `es`, `zh`, `ja`, `ru` with English fallback
+
+## Install
+
+The npm package contains a Node wrapper that starts the Python server. You still need Python 3.10+ and the Python package `mcp>=1.0.0`.
+
+### Option 1: Install From npm
+
+```powershell
+npm install -g ellmos-servercommander-mcp@alpha
+ellmos-servercommander
+```
+
+### Option 2: Install From Source
+
+```powershell
+git clone https://github.com/ellmos-ai/ellmos-servercommander-mcp.git
+cd ellmos-servercommander-mcp
+$env:PYTHONIOENCODING = "utf-8"
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Avoid creating a `.venv` inside cloud-synced folders if your sync client locks files. If you need an isolated environment, create it outside that folder.
+
+## Start From Source
+
+```powershell
+$env:PYTHONPATH = "src"
+python -m servercommander.server
+```
+
+## MCP Client Configuration
+
+### Global npm Install
+
+```json
+{
+  "mcpServers": {
+    "servercommander": {
+      "command": "ellmos-servercommander"
+    }
+  }
+}
+```
+
+### Source Checkout
+
+```json
+{
+  "mcpServers": {
+    "servercommander": {
+      "command": "python",
+      "args": ["-m", "servercommander.server"],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/ellmos-servercommander-mcp/src"
+      }
+    }
+  }
+}
+```
+
+Replace `/absolute/path/to/ellmos-servercommander-mcp` with your local checkout path.
+
+## Server Configuration
+
+Example: [config/servercommander.example.toml](config/servercommander.example.toml)
+
+Default paths:
+
+- `%USERPROFILE%\.servercommander\config.toml`
+- `%USERPROFILE%\.config\servercommander\config.toml`
+- override with `SERVERCOMMANDER_CONFIG`
+
+Language can be configured with `[server].language`, `SERVERCOMMANDER_LANG`, or `SERVERCOMMANDER_LOCALE`.
+
+```toml
+[server]
+name = "ellmos-servercommander"
+language = "en" # en, de, es, zh, ja, ru
+
+[logs]
+default_format = "apache" # apache | nginx
+persist_reports = false
+reports_dir = "~/.servercommander/log_reports"
+```
+
+Secrets should be referenced through environment variables, for example `$MAIL_PASSWORD` or `$SFTP_PASSWORD`.
+
+## Tools
+
+- `sc_health_check`: checks HTTP endpoints and reports status code plus latency
+- `sc_logs_analyze`: analyzes Apache/Nginx access logs from inline text or a local file, including status classes, bytes, referers, error paths, suspicious request markers, and optional JSON report persistence via `persist_report`
+- `sc_deploy`: creates a deployment plan with a local SHA256 manifest and profile diagnostics, but does not upload yet
+- `sc_deploy_status`: shows configured deploy profiles, selected-profile diagnostics, and the current alpha history status
+- `sc_mail_list`, `sc_mail_read`, `sc_mail_send`, `sc_mail_search`: safe alpha status responses with action-specific IMAP/SMTP readiness diagnostics and no mail connections
+
+## Search And Disambiguation
+
+ServerCommander is the ellmos operations MCP server for local-first server administration workflows. Use this repo when searching for:
+
+- MCP server operations tools
+- MCP deploy dry-run server
+- MCP access log analyzer
+- MCP HTTP health check tool
+- local-first server management MCP
+- Claude Code server operations MCP
+- safe SFTP deployment planning MCP
+
+It is not the GitHub MCP server, not a generic shell-command MCP server, not a hosting provider control panel, and not a production SFTP/IMAP executor yet. The current alpha surface is intentionally diagnostic and dry-run first.
+
+## ellmos MCP Family
+
+- [ellmos-filecommander-mcp](https://github.com/ellmos-ai/ellmos-filecommander-mcp): filesystem operations, process management, OCR, archives, and exports
+- [ellmos-codecommander-mcp](https://github.com/ellmos-ai/ellmos-codecommander-mcp): code analysis, JSON repair, imports, diffs, regex, and format conversion
+- [ellmos-clatcher-mcp](https://github.com/ellmos-ai/ellmos-clatcher-mcp): repair, conversion, duplicate detection, batch operations, and document utilities
+- [n8n-manager-mcp](https://github.com/ellmos-ai/n8n-manager-mcp): n8n workflow management through MCP
+- [ellmos-controlcenter-mcp](https://github.com/ellmos-ai/ellmos-controlcenter-mcp): local MCP discovery, profiles, bundles, and control-plane checks
+- [ellmos-homebase-mcp](https://github.com/ellmos-ai/ellmos-homebase-mcp): BACH integration hub, memory, knowledge base, state, swarm, and auto-chain orchestration
+
+## Development
+
+```powershell
+$env:PYTHONIOENCODING = "utf-8"
+$env:PYTHONDONTWRITEBYTECODE = "1"
+python -m pytest -q
+npm run smoke
+npm pack --dry-run
+```
+
+Next useful step: add explicitly configured execution adapters for SFTP and IMAP/SMTP while keeping dry-run/status-only defaults.