{ "markdown": "

\n \"ellmos\n

\n\n# ellmos-servercommander-mcp\n\nAlpha Model Context Protocol (MCP) server for local-first server operations: deployment dry-runs, mail configuration status, access-log analysis, and resilient HTTP health checks.\n\nGerman README: [README_de.md](README_de.md)\n\n*Part of the [ellmos-ai](https://github.com/ellmos-ai) family under the [open-bricks](https://github.com/open-bricks) open-source umbrella.*\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm version](https://img.shields.io/npm/v/ellmos-servercommander-mcp.svg)](https://www.npmjs.com/package/ellmos-servercommander-mcp)\n[![CI](https://img.shields.io/badge/CI-passing-brightgreen.svg)](.github/workflows/ci.yml)\n[![Pytest](https://img.shields.io/badge/pytest-44%20passed%20%7C%20100%25-brightgreen.svg)](tests/)\n[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://www.python.org/)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)\n[![Platforms](https://img.shields.io/badge/platforms-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey.svg)](.github/workflows/ci.yml)\n[![MCP](https://img.shields.io/badge/MCP-stdio-blueviolet.svg)](https://modelcontextprotocol.io/)\n[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://www.npmjs.com/package/ellmos-servercommander-mcp)\n[![Privacy: Local-First](https://img.shields.io/badge/privacy-100%25%20Local--First%20%7C%20Dry--Run-success.svg)](SECURITY.md)\n[![Security: Bilingual Policy](https://img.shields.io/badge/security-Bilingual%20Policy%20(48h%20SLA)-blue.svg)](SECURITY.md)\n[![Ecosystem: ellmos--ai](https://img.shields.io/badge/ecosystem-ellmos--ai-blue.svg)](https://github.com/ellmos-ai)\n[![open-bricks](https://img.shields.io/badge/umbrella-open--bricks-blue.svg)](https://github.com/open-bricks)\n[![LLM--Ready: llms.txt](https://img.shields.io/badge/LLM--Ready-llms.txt-orange.svg)](llms.txt)\n\n> [!NOTE]\n> **Discoverability & AI Search:** Published on [npm](https://www.npmjs.com/package/ellmos-servercommander-mcp) as `ellmos-servercommander-mcp`, cataloged for MCP ecosystems in [`server.json`](server.json), [`glama.json`](glama.json), and [`smithery.yaml`](smithery.yaml), and indexed for AI/LLM search in [`llms.txt`](llms.txt).\n\n---\n\n## Quick Navigation\n\n- [Architecture Visualized](#architecture-visualized)\n- [Start Here](#start-here)\n- [Key Capabilities & Safety Invariants](#key-capabilities--safety-invariants)\n- [Status & Protocol Support](#status--protocol-support)\n- [Installation](#installation)\n- [MCP Client Configuration](#mcp-client-configuration)\n- [Configuration & Profiles](#configuration--profiles)\n- [Tools & Handlers](#tools--handlers)\n- [End-to-End Operations Lifecycle](#end-to-end-operations-lifecycle)\n- [Search And Disambiguation](#search-and-disambiguation)\n- [Sibling Ecosystem](#sibling-ecosystem)\n- [Development & Verification](#development--verification)\n- [Security & Governance](#security--governance)\n\n---\n\n## Architecture Visualized\n\n```mermaid\nflowchart TD\n subgraph HostLayer [\"1. MCP Host & AI Client Layer\"]\n Host[\"MCP Host: Claude Desktop / Claude Code / Cursor\"]\n end\n\n subgraph GatewayLayer [\"2. Gateway & Process Supervision Layer\"]\n NodeWrapper[\"Node.js CLI Wrapper (bin/ellmos-servercommander.js)\"]\n end\n\n subgraph CoreLayer [\"3. Python MCP Server Core Layer\"]\n FastMCP[\"Python MCP Server (FastMCP Transport stdio)\"]\n Dispatcher[\"Tool Dispatcher & Parameter Validator\"]\n i18nEngine[\"i18n Translation Engine (en, de, es, zh, ja, ru)\"]\n end\n\n subgraph OperationsLayer [\"4. Operations & Diagnostics Engines\"]\n HTTPProbe[\"HTTP Health Probe (sc_health_check)\"]\n LogAnalyzer[\"Apache/Nginx Log Analyzer (sc_logs_analyze)\"]\n DeployStaging[\"Deployment Staging & Manifest Planner (sc_deploy / sc_deploy_status)\"]\n MailDiagnostics[\"IMAP/SMTP Safety Diagnostics (sc_mail_*)\"]\n end\n\n subgraph SinkLayer [\"5. Local Storage & Audit Sink Layer\"]\n SQLiteHist[(\"Local SQLite Deploy History (deploy-history.db)\")]\n JSONReports[(\"Sanitized JSON Log Reports\")]\n AuditSink[\"Local Diagnostic Outputs & Stdout Stream\"]\n end\n\n Host <-->|\"stdio / JSON-RPC\"| NodeWrapper\n NodeWrapper <-->|\"Child Process Stdio\"| FastMCP\n FastMCP --> Dispatcher\n Dispatcher <--> i18nEngine\n Dispatcher --> HTTPProbe\n Dispatcher --> LogAnalyzer\n Dispatcher --> DeployStaging\n Dispatcher --> MailDiagnostics\n DeployStaging -.->|\"Optional opt-in persist\"| SQLiteHist\n LogAnalyzer -.->|\"Optional persist_report\"| JSONReports\n HTTPProbe -.-> AuditSink\n MailDiagnostics -.-> AuditSink\n```\n\n---\n\n## Start Here\n\n| Goal | Start with | Key Features |\n|---|---|---|\n| Add ServerCommander to Claude Desktop, Claude Code, Cursor, or another MCP host | [MCP Client Configuration](#mcp-client-configuration) | Zero-friction global npm install or npx invocation |\n| Check a public or internal HTTP endpoint before a deploy | `sc_health_check` | Concurrent non-blocking requests, latency timings, resilient batch error handling |\n| Inspect Apache/Nginx access logs for errors, bots, referrers, and suspicious paths | `sc_logs_analyze` | Status code breakdown, byte transfer sums, bot markers, optional JSON reports |\n| Build a deterministic dry-run deployment manifest before SFTP/SSH execution | `sc_deploy` and `sc_deploy_status` | Recursive SHA-256 tree hashing, symlink bypass protection, SQLite history |\n| Wire mail operations later without accidental email dispatches today | `sc_mail_list`, `sc_mail_read`, `sc_mail_send`, `sc_mail_search` | Protocol readiness validation, credential inspection, safe alpha staging |\n\n---\n\n## Key Capabilities & Safety Invariants\n\n| Capability / Invariant | Implementation Guarantee | Technical Details |\n|---|---|---|\n| **100% Local-First & Dry-Run Staging** | Strict non-destructive default | Deployment tools calculate SHA-256 hashes locally without executing unauthorized remote writes. |\n| **Unprivileged Execution (Non-Elevation)** | Zero root/administrator requirements | Runs entirely within standard user permissions; never requires sudo or privilege elevation. |\n| **Secret & Credential Isolation** | Zero-leak release packaging | `.env`, `.npmrc`, `.pypirc`, private keys (`id_rsa`, `*.pem`), and tokens are excluded by `.gitignore` and `.npmignore`. |\n| **Deterministic Manifest Verification** | Cryptographic release integrity | Calculates recursive SHA-256 digests; nested symlinks are tracked but excluded from tree traversal. |\n| **Resilient Health Probes** | Non-blocking batch worker threads | HTTP probes execute via `asyncio.to_thread` with strict timeouts; malformed URLs never abort batches. |\n| **Structured Log Breakdown** | Local forensic inspection | Parses Common/Combined log formats; detects HTTP 4xx/5xx spikes, bots, suspicious traversal attempts. |\n| **Mail Readiness Diagnostic** | Non-executing safe staging | Reuses verified `mail-connector` module for IMAP probes only when explicitly configured; SMTP send stays disabled. |\n| **6-Language i18n Engine** | Comprehensive multilingual support | Full localization for tool descriptions, schema arguments, and errors in `en`, `de`, `es`, `zh`, `ja`, `ru`. |\n\n---\n\n## Status & Protocol Support\n\n- **Transport**: Standard I/O (`stdio`) via the Python MCP SDK and Node.js process wrapper.\n- **Package Status**: Public alpha package under the `ellmos-ai` organization.\n- **Current Core**: MCP tool listing, tool dispatch, TOML configuration loader, HTTP health checks, richer access-log analysis with optional persisted JSON reports, and optional local dry-run deployment history.\n- **Safe Alpha Handlers**: `sc_deploy` builds local SHA-256 manifests, configuration diagnostics, and opt-in SQLite history records in dry-run mode; `sc_mail_*` reports protocol-specific IMAP/SMTP readiness without opening mail connections by default.\n- **i18n Localization**: Localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for `en`, `de`, `es`, `zh`, `ja`, `ru` with automatic English fallback.\n\n---\n\n## Installation\n\nThe 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`.\n\n### Option 1: Install From npm\n\n```powershell\nnpm install -g ellmos-servercommander-mcp@alpha\nellmos-servercommander\n```\n\n### Option 2: Install From Source\n\n```powershell\ngit clone https://github.com/ellmos-ai/ellmos-servercommander-mcp.git\ncd ellmos-servercommander-mcp\n$env:PYTHONIOENCODING = \"utf-8\"\npython -m pip install -e \".[dev]\"\npython -m pytest -q\n```\n\nAvoid creating a `.venv` inside cloud-synced folders if your sync client locks files. If you need an isolated environment, create it outside that folder.\n\n---\n\n## MCP Client Configuration\n\n### Global npm Install\n\n```json\n{\n \"mcpServers\": {\n \"servercommander\": {\n \"command\": \"ellmos-servercommander\"\n }\n }\n}\n```\n\n### npx Without Global Install\n\n```json\n{\n \"mcpServers\": {\n \"servercommander\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"ellmos-servercommander-mcp@alpha\"]\n }\n }\n}\n```\n\n### Direct Python Execution\n\n```json\n{\n \"mcpServers\": {\n \"servercommander\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"servercommander.server\"],\n \"env\": {\n \"PYTHONPATH\": \"C:/path/to/ellmos-servercommander-mcp/src\",\n \"SERVERCOMMANDER_CONFIG_PATH\": \"C:/path/to/config/servercommander.toml\"\n }\n }\n }\n}\n```\n\n---\n\n## Configuration & Profiles\n\nServerCommander searches for configuration files in this hierarchical order:\n\n1. Environment variable `SERVERCOMMANDER_CONFIG_PATH`\n2. `./servercommander.toml`\n3. `./config/servercommander.toml`\n4. `~/.config/servercommander/servercommander.toml`\n\nAn annotated template is included at [`config/servercommander.example.toml`](config/servercommander.example.toml).\n\n```toml\n[server]\nname = \"servercommander\"\nlog_level = \"INFO\"\nlanguage = \"en\"\n\n[deploy.profiles.staging]\ntarget = \"sftp://staging.example.com/var/www/app\"\nlocal_path = \"./dist\"\nprotocol = \"sftp\"\ndry_run = true\nrecord_history = true\n\n[mail]\nexecution_enabled = false\nsmtp_host = \"smtp.example.com\"\nsmtp_port = 587\nimap_host = \"imap.example.com\"\nimap_port = 993\n```\n\nSecrets should always be referenced through environment variables, for example `$MAIL_PASSWORD` or `$SFTP_PASSWORD`.\n\n---\n\n## Tools & Handlers\n\n- `sc_health_check`: Checks HTTP/HTTPS endpoints and reports status codes, response headers, and latency. Malformed endpoint URLs are captured gracefully as failed checks rather than aborting the batch.\n- `sc_logs_analyze`: Analyzes Apache/Nginx access logs from inline text or local files, reporting HTTP status classes (2xx/3xx/4xx/5xx), total bytes transferred, top referrers, 404/500 error paths, suspicious bot markers, and optional JSON report persistence via `persist_report`.\n- `sc_deploy`: Creates a dry-run deployment plan with a local SHA-256 manifest and profile diagnostics without performing remote mutations. Nested symbolic links are tracked as `skipped_symlinks` to prevent unexpected directory traversal.\n- `sc_deploy_status`: Displays configured deployment profiles, profile diagnostics, and recent dry-run deployment records retrieved from the local SQLite history database.\n- `sc_mail_list`, `sc_mail_read`, `sc_mail_send`, `sc_mail_search`: Safe alpha status responses with action-specific IMAP/SMTP readiness diagnostics. With `[mail].execution_enabled = true`, `sc_mail_list` executes a read-only IMAP reachability probe (connect + folder listing) by reusing the canonical `mail-connector` module without reimplementing an IMAP client.\n\n---\n\n## End-to-End Operations Lifecycle\n\n```mermaid\nsequenceDiagram\n autonumber\n actor User as AI Assistant / User\n participant Host as MCP Host (Claude / Cursor)\n participant Wrapper as Node.js Wrapper\n participant Server as ServerCommander Server\n participant Handler as Operation Handler\n participant Disk as Local Disk / SQLite Sink\n participant Target as Network Endpoint\n\n User->>Host: \"Check API health and prepare deploy manifest\"\n Host->>Wrapper: JSON-RPC request (stdio)\n Wrapper->>Server: Forward request via child process\n Server->>Server: Parse parameters & validate config\n\n alt HTTP Health Probe\n Server->>Handler: Dispatch sc_health_check\n Handler->>Target: HTTP/HTTPS GET (async worker thread)\n Target-->>Handler: Status code + Latency response\n Handler-->>Server: Health result dictionary\n else Access Log Analysis\n Server->>Handler: Dispatch sc_logs_analyze\n Handler->>Disk: Read access.log & parse entries\n Handler->>Disk: Optional write structured JSON report\n Handler-->>Server: Aggregated log statistics\n else Deployment Staging\n Server->>Handler: Dispatch sc_deploy (dry_run=True)\n Handler->>Disk: Scan local_path & calculate SHA-256 tree\n Handler->>Disk: Optional insert record into deploy-history.db\n Handler-->>Server: Manifest digest & profile readiness\n end\n\n Server->>Server: Localize response messages (i18n engine)\n Server-->>Wrapper: JSON-RPC response\n Wrapper-->>Host: Formatted stdio output\n Host-->>User: Structured operations summary & next steps\n```\n\n---\n\n## Search And Disambiguation\n\nServerCommander is the ellmos operations MCP server for local-first server administration workflows. Use this repository when searching for:\n\n- MCP server operations tools\n- MCP deploy dry-run server\n- MCP access log analyzer\n- MCP HTTP health check tool\n- local-first server management MCP\n- Claude Code server operations MCP\n- safe SFTP deployment planning MCP\n- AI assistant server preflight checks\n- Apache Nginx log analysis MCP\n- resilient HTTP health check MCP\n- SQLite deploy history MCP\n\nIt is **not** the GitHub MCP server, **not** a generic arbitrary shell-execution MCP server, **not** a cloud hosting provider control panel, and **not** an unverified production SFTP/IMAP auto-executor. The current alpha surface is intentionally diagnostic, dry-run first, and safe by default.\n\n---\n\n## Sibling Ecosystem\n\nThis MCP server is an integral component of the **[ellmos-ai](https://github.com/ellmos-ai)** ecosystem and the **[open-bricks](https://github.com/open-bricks)** open-source software family.\n\n### MCP Server Family\n\n| Server | Tools | Primary Focus | npm Package |\n|---|---|---|---|\n| [FileCommander](https://github.com/ellmos-ai/ellmos-filecommander-mcp) | 46 | Filesystem operations, process supervision, sessions, cloud-lock handling | [`ellmos-filecommander-mcp`](https://www.npmjs.com/package/ellmos-filecommander-mcp) |\n| [CodeCommander](https://github.com/ellmos-ai/ellmos-codecommander-mcp) | 22 | Code analysis, AST inspection, JSON repair, imports, diffs, regex | [`ellmos-codecommander-mcp`](https://www.npmjs.com/package/ellmos-codecommander-mcp) |\n| [Clatcher](https://github.com/ellmos-ai/ellmos-clatcher-mcp) | 12 | File repair, encoding correction, format conversion, batch tools | [`ellmos-clatcher-mcp`](https://www.npmjs.com/package/ellmos-clatcher-mcp) |\n| [n8n Manager](https://github.com/ellmos-ai/n8n-manager-mcp) | 18 | n8n workflow management, deployment, node exploration | [`n8n-manager-mcp`](https://www.npmjs.com/package/n8n-manager-mcp) |\n| [ControlCenter](https://github.com/ellmos-ai/ellmos-controlcenter-mcp) | 20 | MCP stack discovery, profile management, control plane routing | [`ellmos-controlcenter-mcp`](https://www.npmjs.com/package/ellmos-controlcenter-mcp) |\n| [Homebase](https://github.com/ellmos-ai/ellmos-homebase-mcp) | 45 | Local-first LLM memory, knowledge base, swarm orchestration | [`ellmos-homebase-mcp`](https://www.npmjs.com/package/ellmos-homebase-mcp) |\n| **[ServerCommander](https://github.com/ellmos-ai/ellmos-servercommander-mcp)** | **8** | **Server operations: health checks, log analysis, dry-run manifests** | **[`ellmos-servercommander-mcp`](https://www.npmjs.com/package/ellmos-servercommander-mcp)** |\n| [Blender Use](https://github.com/ellmos-ai/ellmos-blender-use-mcp) | 3 | Headless Blender 3D asset QA and automated FBX reimport | [`ellmos-blender-use-mcp`](https://www.npmjs.com/package/ellmos-blender-use-mcp) |\n| [Open Compute](https://github.com/ellmos-ai/open-compute-mcp) | 10 | Model-agnostic computer use: screen capture, safety-gated actions | [`open-compute-mcp`](https://www.npmjs.com/package/open-compute-mcp) |\n\n### AI Infrastructure & Developer Tools\n\n| Project | Description |\n|---|---|\n| [BACH](https://github.com/ellmos-ai/bach) | Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory |\n| [open-compute](https://github.com/ellmos-ai/open-compute) | Model-agnostic computer-use core powering Open Compute MCP |\n| [clutch](https://github.com/ellmos-ai/clutch) | Provider-neutral LLM orchestration with auto-routing and budget tracking |\n| [rinnsal](https://github.com/ellmos-ai/rinnsal) | Lightweight agent memory, connectors, and automation infrastructure |\n| [sqlite-transit-sync](https://github.com/ellmos-ai/sqlite-transit-sync) | Encrypted SQLite transit synchronization & additive read-replica engine |\n| [workflowhooker](https://github.com/ellmos-ai/workflowhooker) | Git-hook-driven workflow automation and execution safety boundaries |\n| [system-explorer](https://github.com/ellmos-ai/system-explorer) | Local-first system composition, module introspection, and fleet verification |\n| [companion-for-agy](https://github.com/ellmos-ai/companion-for-agy) | Antigravity developer companion & telemetry bridge |\n\n### Desktop Software Suite\n\nOur partner organization **[open-bricks](https://github.com/open-bricks)** provides desktop productivity applications built for the age of AI:\n- File Management: [ProFiler](https://github.com/file-bricks/ProFiler), [ExplorerPro](https://github.com/file-bricks/ExplorerPro), [CloudLockFixer](https://github.com/file-bricks/CloudLockFixer)\n- Document Processing: [DokuZen](https://github.com/doc-bricks/DokuZen), [PDFtoPDFocr](https://github.com/doc-bricks/PDFtoPDFocr), [FormularErstellen](https://github.com/doc-bricks/FormularErstellen)\n- Developer Tools: [DevCenter](https://github.com/dev-bricks/DevCenter), [CodeBox](https://github.com/dev-bricks/CodeBox), [automizer-for-claude-desktop](https://github.com/dev-bricks/automizer-for-claude-desktop)\n\n---\n\n## Development & Verification\n\n```powershell\n# Set UTF-8 encoding\n$env:PYTHONIOENCODING = \"utf-8\"\n\n# Run complete pytest test suite\npython -m pytest -v\n\n# Run Ruff linter\nruff check .\n\n# Verify Node CLI smoke test\nnpm run smoke\n\n# Verify npm packaging (dry-run)\nnpm pack --dry-run\n```\n\n---\n\n## Security & Governance\n\nFor vulnerability reporting, response SLAs, and local-first security invariant details, see our bilingual [SECURITY.md](SECURITY.md).\n\n- **Vulnerability Reporting**: [GitHub Security Advisories](https://github.com/ellmos-ai/ellmos-servercommander-mcp/security/advisories) or email `security@ellmos.ai` / `security@open-bricks.org`.\n- **Response SLA**: Initial triage within **48 hours**; status updates within 5 business days.\n", "bytes": 19322, "sha": "148b321589765c1d5ab40d26362aad3bbe7adca15babe68db39ccbc112870514", "repo_slug": "ellmos-ai/ellmos-servercommander-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ellmos_ai_ellmos_servercommand_3e080a63/readme" }