ellmos ServerCommander

ellmos-servercommander-mcp

Alpha Model Context Protocol (MCP) server for local-first server operations: deployment dry-runs, mail configuration status, access-log analysis, and resilient HTTP health checks.

German README: README_de.md

*Part of the ellmos-ai family under the open-bricks open-source umbrella.*

-blue.svg)

[!NOTE]

Discoverability & AI Search: Published on npm as ellmos-servercommander-mcp, cataloged for MCP ecosystems in server.json, glama.json, and smithery.yaml, and indexed for AI/LLM search in llms.txt.

---

Quick Navigation

1. Executive Summary & Core Identity
2. Visual Architecture & System Topology
3. Operations Lifecycle & Execution Sequence Flow
4. Target Personas & High-Intent SEO Queries
5. Comparative Matrix vs. Alternatives
6. Key Capabilities & Safety Invariants
7. Start Here & Quick Guidance
8. Status & Protocol Support
9. Installation & Prerequisites
10. MCP Client Configuration & Deployment Modes
11. Configuration & Profiles Specification
12. Tools & Handlers Reference
13. Search, Disambiguation & Discovery Keywords
14. Sibling Ecosystem Matrix
15. Third-Party Licenses & Level 1 SBOM
16. Security Policy & Operational Limits (48h SLA)
17. Development, Verification & CI Matrix
18. Statutory Notice, Liability Limitation & License (§ 521 BGB)

---

1. Executive Summary & Core Identity

ellmos-servercommander-mcp is an authoritative, local-first Model Context Protocol (MCP) server engineered specifically for AI coding assistants and autonomous agent platforms (Claude Code, Cursor, Codex, Antigravity, Gemini). It enables agents to safely diagnose server health, analyze web server access logs, inspect mail readiness, and build dry-run deployment plans without exposing production infrastructure to unverified, destructive mutations or arbitrary shell execution.

Every operation is governed by strict local-first and zero-elevation guarantees:

• 100% Local-First & Zero-Egress by Default: Diagnostic parsing and manifest hashing execute locally; zero telemetry and zero unverified outbound network requests.
• Dry-Run & Staging First: Deployment operations calculate SHA-256 tree digests and check target profiles before any remote command is staged.
• Unprivileged Execution (`RunAsInvoker`): Operates within standard unprivileged user space without requiring root or administrator elevation.

---

2. Visual Architecture & System Topology

The following diagram illustrates the decoupled layers of ServerCommander, from MCP host transport and Node.js process supervision to Python dispatching, operational engines, and local persistence sinks:

flowchart TD

subgraph HostLayer ["1. MCP Host & AI Client Layer"] Host["MCP Host: Claude Desktop / Claude Code / Cursor"] end

subgraph GatewayLayer ["2. Gateway & Process Supervision Layer"] NodeWrapper["Node.js CLI Wrapper (bin/ellmos-servercommander.js)"] end

subgraph CoreLayer ["3. Python MCP Server Core Layer"] FastMCP["Python MCP Server (FastMCP Transport stdio)"] Dispatcher["Tool Dispatcher & Parameter Validator"] i18nEngine["i18n Translation Engine (en, de, es, zh, ja, ru)"] end

subgraph OperationsLayer ["4. Operations & Diagnostics Engines"] HTTPProbe["HTTP Health Probe (sc_health_check)"] LogAnalyzer["Apache/Nginx Log Analyzer (sc_logs_analyze)"] DeployStaging["Deployment Staging & Manifest Planner (sc_deploy / sc_deploy_status)"] MailDiagnostics["IMAP/SMTP Safety Diagnostics (sc_mail_*)"] end

subgraph SinkLayer ["5. Local Storage & Audit Sink Layer"] SQLiteHist[("Local SQLite Deploy History (deploy-history.db)")] JSONReports[("Sanitized JSON Log Reports")] AuditSink["Local Diagnostic Outputs & Stdout Stream"] end

Host <-->|"stdio / JSON-RPC"| NodeWrapper NodeWrapper <-->|"Child Process Stdio"| FastMCP FastMCP --> Dispatcher Dispatcher <--> i18nEngine Dispatcher --> HTTPProbe Dispatcher --> LogAnalyzer Dispatcher --> DeployStaging Dispatcher --> MailDiagnostics DeployStaging -.->|"Optional opt-in persist"| SQLiteHist LogAnalyzer -.->|"Optional persist_report"| JSONReports HTTPProbe -.-> AuditSink MailDiagnostics -.-> AuditSink

ASCII Architectural Topology (Four-View Projection)

========================================================================================

ellmos-servercommander-mcp: Four-View Architectural Topology ========================================================================================

[VIEW 1: COMPONENT STRUCTURE & TRANSPORT BOUNDARIES] +----------------------------------------------------------------------------------+ | 1. MCP Host & AI Client (Claude Desktop / Claude Code / Cursor / Codex) | | - Stdio JSON-RPC transport protocol | +----------------------------------------------------------------------------------+ | | (JSON-RPC via stdio stream) v +----------------------------------------------------------------------------------+ | 2. Gateway & Process Supervision (bin/ellmos-servercommander.js) | | - Node.js CLI launcher & process supervisor (update-notifier checks) | | - Working directory isolation: PYTHONSAFEPATH=1 prevents rogue import hijack | +----------------------------------------------------------------------------------+ | | (Supervised child process stdio) v +----------------------------------------------------------------------------------+ | 3. FastMCP Dispatcher & i18n Localization Engine (src/servercommander/) | | - FastMCP server lifecycle, tool schema generation & parameter validation | | - Multi-language localization engine (6 locales: en, de, es, zh, ja, ru) | +----------------------------------------------------------------------------------+

[VIEW 2: OPERATIONAL ENGINES & DRY-RUN EXECUTION] +----------------------------------------------------------------------------------+ | 4. Tool Handlers & Diagnostic Engines | | - sc_health_check: Non-blocking HTTP/HTTPS probe with timeout & batch error | | - sc_logs_analyze: Sanitized Apache/Nginx access-log parser & threat detector| | - sc_deploy / sc_deploy_status: Fail-safe SHA-256 tree hashing & dry-run plan| | - sc_mail_list / sc_mail_read / sc_mail_send: Dry-run IMAP/SMTP diagnostics | +----------------------------------------------------------------------------------+

[VIEW 3: LOCAL PERSISTENCE & CONCURRENCY MODEL] +----------------------------------------------------------------------------------+ | 5. Local Storage & Audit Sinks | | - Local SQLite Deploy History (deploy-history.db) with explicit lease release | | - Sanitized JSON diagnostic reports (optional persist_report) | | - Thread-isolated HTTP GET workers preventing event-loop stalling | +----------------------------------------------------------------------------------+

[VIEW 4: SECURITY BOUNDARY & ZERO-EGRESS PERIMETER] +----------------------------------------------------------------------------------+ | 6. Governance & Defense Invariants (INV-LOCAL-01 through INV-SLA-10) | | - RunAsInvoker: 100% unprivileged user mode; zero root/sudo/UAC requirement | | - Zero-Egress by default: zero telemetry, zero unverified background outbound | | - Safe Process Isolation: cwd package exclusion, sanitized error messages | | - 48h Response SLA & statutory liability limitation (§ 521 BGB) | +----------------------------------------------------------------------------------+ ========================================================================================

---

3. Operations Lifecycle & Execution Sequence Flow

The following sequence diagram demonstrates the lifecycle of operations dispatched by an AI agent through ServerCommander, showing concurrent HTTP probing, log parsing, and dry-run manifest calculation:

sequenceDiagram

autonumber actor User as AI Assistant / User participant Host as MCP Host (Claude / Cursor) participant Wrapper as Node.j