remote-server-mcp 0.2.0__tar.gz

remote_server_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: remote-server-mcp
+Version: 0.2.0
+Summary: Security-first MCP server for managing Docker services on a remote server or on the local host.
+Author-email: Alessio Elmi <alessio.elmi@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/elmuz/server-mcp
+Project-URL: Repository, https://github.com/elmuz/server-mcp
+Project-URL: Documentation, https://github.com/elmuz/server-mcp/tree/main/docs
+Project-URL: Issues, https://github.com/elmuz/server-mcp/issues
+Project-URL: Changelog, https://github.com/elmuz/server-mcp/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,linux,server-management,docker,homelab,self-hosting
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: server-management-lib<0.3,>=0.2
+
+# remote-server-mcp
+
+Security-first MCP server for Docker service management over SSH or on the local host.
+
+Part of the [Server MCP suite](../../README.md). It exposes a fixed catalog of 21 tools
+(directory and container discovery, container and host-service logs, status and health,
+start/stop/restart, scoped Compose operations, confined file reads, server health and
+read-only InfluxDB/Prometheus queries). No generic command execution.
+
+The container CLI is configurable (`docker`, `podman` or `nerdctl`). `restart_service`,
+`stop_service`, `compose_pull`, `compose_up` and `compose_down` require `confirm=true` and
+are bounded by a per-process rate limit. Streamable HTTP is available with
+`--transport streamable-http`: it binds to loopback by default and requires a bearer token
+for any other address.
+
+Host infrastructure services such as `telegraf`, `smartd` and `docker` are systemd units,
+not containers. `get_host_service_status` and `get_host_service_logs` read them with
+`systemctl`/`journalctl` and only accept units listed in `security.host_units`.
+
+Container logs always include timestamps. A log request can add a `since`/`until` window
+and target one container in a compose project; search matches the exact literal pattern.
+Every tool publishes a structured `ToolResponse` next to the readable text. Composite and
+listing responses receive a final `output.max_bytes` cap. When the audit log
+is enabled, InfluxDB and Prometheus queries are recorded by length/SHA-256 fingerprint
+rather than by query text.
+
+Prometheus is optional. Its metric endpoints can be reached through an HTTPS reverse proxy
+or a loopback-only `ssh_tunnel` created by the MCP; see
+[configuration](../../docs/configuration.md#database-endpoints).
+
+- [Tools](../../docs/tools.md)
+- [Configuration](../../docs/configuration.md)
+- [Security model](../../docs/security-model.md)
+- [Getting started](../../docs/getting-started.md)
+
+```bash
+uv run --directory apps/remote-server-mcp remote-server-mcp
+```
+
+Requires a config file; see `config.example.yaml` in this directory.

remote_server_mcp-0.2.0/README.md

@@ -0,0 +1,40 @@
+# remote-server-mcp
+
+Security-first MCP server for Docker service management over SSH or on the local host.
+
+Part of the [Server MCP suite](../../README.md). It exposes a fixed catalog of 21 tools
+(directory and container discovery, container and host-service logs, status and health,
+start/stop/restart, scoped Compose operations, confined file reads, server health and
+read-only InfluxDB/Prometheus queries). No generic command execution.
+
+The container CLI is configurable (`docker`, `podman` or `nerdctl`). `restart_service`,
+`stop_service`, `compose_pull`, `compose_up` and `compose_down` require `confirm=true` and
+are bounded by a per-process rate limit. Streamable HTTP is available with
+`--transport streamable-http`: it binds to loopback by default and requires a bearer token
+for any other address.
+
+Host infrastructure services such as `telegraf`, `smartd` and `docker` are systemd units,
+not containers. `get_host_service_status` and `get_host_service_logs` read them with
+`systemctl`/`journalctl` and only accept units listed in `security.host_units`.
+
+Container logs always include timestamps. A log request can add a `since`/`until` window
+and target one container in a compose project; search matches the exact literal pattern.
+Every tool publishes a structured `ToolResponse` next to the readable text. Composite and
+listing responses receive a final `output.max_bytes` cap. When the audit log
+is enabled, InfluxDB and Prometheus queries are recorded by length/SHA-256 fingerprint
+rather than by query text.
+
+Prometheus is optional. Its metric endpoints can be reached through an HTTPS reverse proxy
+or a loopback-only `ssh_tunnel` created by the MCP; see
+[configuration](../../docs/configuration.md#database-endpoints).
+
+- [Tools](../../docs/tools.md)
+- [Configuration](../../docs/configuration.md)
+- [Security model](../../docs/security-model.md)
+- [Getting started](../../docs/getting-started.md)
+
+```bash
+uv run --directory apps/remote-server-mcp remote-server-mcp
+```
+
+Requires a config file; see `config.example.yaml` in this directory.

remote_server_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "remote-server-mcp"
+version = "0.2.0"
+description = "Security-first MCP server for managing Docker services on a remote server or on the local host."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=2.3,<3",
+    "server-management-lib>=0.2,<0.3",
+]
+
+authors = [
+    { name = "Alessio Elmi", email = "alessio.elmi@gmail.com" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "linux",
+    "server-management",
+    "docker",
+    "homelab",
+    "self-hosting",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/elmuz/server-mcp"
+Repository = "https://github.com/elmuz/server-mcp"
+Documentation = "https://github.com/elmuz/server-mcp/tree/main/docs"
+Issues = "https://github.com/elmuz/server-mcp/issues"
+Changelog = "https://github.com/elmuz/server-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+remote-server-mcp = "remote_server_mcp:cli"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-data]
+remote_server_mcp = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "integration: marks integration tests that require real SSH/DB access",
+]
+# Keep the default suite deterministic. Run integration tests explicitly with:
+#   uv run pytest -m integration
+addopts = "-m 'not integration' --cov=src/remote_server_mcp --cov-report=term-missing"
+
+[tool.coverage.run]
+source = ["remote_server_mcp"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 60
+show_missing = true
+skip_covered = true

remote_server_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

remote_server_mcp-0.2.0/src/remote_server_mcp/__init__.py

@@ -0,0 +1,12 @@
+"""
+Remote Server MCP - Main entry point
+"""
+
+from .server import cli, main, mcp
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__", "cli", "main", "mcp"]
+
+if __name__ == "__main__":
+    cli()

remote_server_mcp-0.2.0/src/remote_server_mcp/operations.py

@@ -0,0 +1,241 @@
+"""
+Operation catalog for the remote-server MCP.
+
+Commands are built as argument vectors and rendered with :func:`shlex.join`, so
+no user-controlled value is ever concatenated into a shell string. Operations
+also declare their safety level, which is used for MCP tool annotations and
+audit records.
+
+The container CLI is configurable (``container_runtime``): Docker, Podman and
+nerdctl share the same command surface for the operations below. The module
+level constants remain the Docker catalog for backwards compatibility and for
+the command-policy tests.
+"""
+
+from dataclasses import dataclass
+
+from server_management_lib import Operation
+
+# ``docker ps``/``docker stats`` expand ``\\n`` and ``\\t`` inside their format
+# strings, but ``docker inspect`` does not: it passes the text to the Go
+# template verbatim, so a literal ``\\n`` ends up in the output and every
+# field stays on one line. Emitting the newline from inside a template action
+# (``{{"\\n"}}``) keeps the argv free of control characters (the command
+# policy rejects those) and still produces real line breaks.
+NEWLINE = '{{"\\n"}}'
+
+INSPECT_FORMAT = (
+    f"Name: {{{{.Name}}}}{NEWLINE}"
+    f"State: {{{{.State.Status}}}}{NEWLINE}"
+    f"Running: {{{{.State.Running}}}}{NEWLINE}"
+    f"Health: {{{{if .State.Health}}}}{{{{.State.Health.Status}}}}{{{{else}}}}none"
+    f"{{{{end}}}}{NEWLINE}"
+    f"FailingStreak: {{{{if .State.Health}}}}{{{{.State.Health.FailingStreak}}}}"
+    f"{{{{else}}}}0{{{{end}}}}{NEWLINE}"
+    f"RestartCount: {{{{.RestartCount}}}}{NEWLINE}"
+    f"ExitCode: {{{{.State.ExitCode}}}}{NEWLINE}"
+    f"StartedAt: {{{{.State.StartedAt}}}}"
+)
+
+# ``docker stats`` *does* expand ``\\n`` before it parses the template, so it
+# must keep the plain escape. Using the ``NEWLINE`` action here would turn the
+# string literal into a real newline and fail with "unterminated quoted
+# string".
+STATS_FORMAT = "CPU: {{.CPUPerc}}\\nMemory: {{.MemUsage}}\\nNet I/O: {{.NetIO}}"
+HEALTH_FORMAT = "{{json .State.Health}}"
+
+# One line per container, including stopped and crashed ones. The compose
+# project label is how a service directory resolves to its containers.
+CONTAINER_LIST_FORMAT = (
+    '{{.Names}}\\t{{.Label "com.docker.compose.project"}}\\t{{.Status}}'
+)
+
+
+def container_logs_operation(
+    *, runtime: str = "docker", since: str | None = None, until: str | None = None
+) -> Operation:
+    """Build a ``<runtime> logs`` operation with optional time filters.
+
+    ``--timestamps`` is always enabled so log lines can be correlated with
+    host events. Time values are validated by the security layer before they
+    reach this function.
+    """
+    argv = [runtime, "logs", "--tail", "$lines", "--timestamps"]
+    if since:
+        argv.extend(("--since", "$since"))
+    if until:
+        argv.extend(("--until", "$until"))
+    argv.extend(("--", "$service"))
+    return Operation(tuple(argv))
+
+
+@dataclass(frozen=True)
+class ContainerCatalog:
+    """Every container operation for one runtime."""
+
+    runtime: str
+    ps: Operation
+    ps_all: Operation
+    ps_unhealthy: Operation
+    inspect: Operation
+    stats: Operation
+    ports: Operation
+    health: Operation
+    restart: Operation
+    start: Operation
+    stop: Operation
+    compose_ps: Operation
+    compose_pull: Operation
+    compose_up: Operation
+    compose_down: Operation
+
+    def logs(self, *, since: str | None = None, until: str | None = None) -> Operation:
+        return container_logs_operation(runtime=self.runtime, since=since, until=until)
+
+
+def build_container_catalog(runtime: str = "docker") -> ContainerCatalog:
+    """Build the container operation catalog for ``runtime``.
+
+    ``runtime`` is validated by :class:`SecurityValidator` before it reaches
+    this function; the command policy also rejects unknown runtimes.
+    """
+    return ContainerCatalog(
+        runtime=runtime,
+        ps=Operation((runtime, "ps", "--format", "{{.Names}}\\t{{.Status}}")),
+        ps_all=Operation((runtime, "ps", "-a", "--format", CONTAINER_LIST_FORMAT)),
+        ps_unhealthy=Operation(
+            (
+                runtime,
+                "ps",
+                "-a",
+                "--filter",
+                "health=unhealthy",
+                "--format",
+                "{{.Names}}\\t{{.Status}}",
+            )
+        ),
+        inspect=Operation(
+            (runtime, "inspect", "--format", INSPECT_FORMAT, "--", "$service")
+        ),
+        stats=Operation(
+            (
+                runtime,
+                "stats",
+                "--no-stream",
+                "--format",
+                STATS_FORMAT,
+                "--",
+                "$service",
+            )
+        ),
+        ports=Operation((runtime, "port", "--", "$service")),
+        health=Operation(
+            (runtime, "inspect", "--format", HEALTH_FORMAT, "--", "$service")
+        ),
+        restart=Operation(
+            (runtime, "restart", "--", "$service"),
+            read_only=False,
+            destructive=True,
+        ),
+        start=Operation((runtime, "start", "--", "$service"), read_only=False),
+        stop=Operation(
+            (runtime, "stop", "--", "$service"),
+            read_only=False,
+            destructive=True,
+        ),
+        # Compose commands are scoped to a service directory below
+        # services_path. The security layer validates the directory and the
+        # exact subcommand arguments.
+        compose_ps=Operation(
+            (
+                runtime,
+                "compose",
+                "--project-directory",
+                "$directory",
+                "ps",
+                "--format",
+                "{{.Name}} {{.Status}}",
+            )
+        ),
+        compose_pull=Operation(
+            (runtime, "compose", "--project-directory", "$directory", "pull"),
+            read_only=False,
+        ),
+        compose_up=Operation(
+            (
+                runtime,
+                "compose",
+                "--project-directory",
+                "$directory",
+                "up",
+                "-d",
+                "--remove-orphans",
+            ),
+            read_only=False,
+        ),
+        compose_down=Operation(
+            (
+                runtime,
+                "compose",
+                "--project-directory",
+                "$directory",
+                "down",
+                "--remove-orphans",
+            ),
+            read_only=False,
+            destructive=True,
+        ),
+    )
+
+
+DEFAULT_CATALOG = build_container_catalog("docker")
+
+ECHO_CONNECTION = Operation(("echo", "Connection successful"))
+LS_SERVICES = Operation(("ls", "-1", "$path"))
+# The trailing slash from -p distinguishes directories from plain files.
+LS_SERVICE_DIRS = Operation(("ls", "-1", "-p", "$path"))
+DOCKER_PS = DEFAULT_CATALOG.ps
+DOCKER_PS_ALL = DEFAULT_CATALOG.ps_all
+# Health status is only reported for containers with a healthcheck. Including
+# stopped containers keeps a crashed or exited unhealthy service visible.
+DOCKER_PS_UNHEALTHY = DEFAULT_CATALOG.ps_unhealthy
+DOCKER_LOGS = DEFAULT_CATALOG.logs()
+DOCKER_INSPECT = DEFAULT_CATALOG.inspect
+DOCKER_STATS = DEFAULT_CATALOG.stats
+DOCKER_PORTS = DEFAULT_CATALOG.ports
+DOCKER_HEALTH = DEFAULT_CATALOG.health
+DOCKER_RESTART = DEFAULT_CATALOG.restart
+DOCKER_START = DEFAULT_CATALOG.start
+DOCKER_STOP = DEFAULT_CATALOG.stop
+COMPOSE_PS = DEFAULT_CATALOG.compose_ps
+COMPOSE_PULL = DEFAULT_CATALOG.compose_pull
+COMPOSE_UP = DEFAULT_CATALOG.compose_up
+COMPOSE_DOWN = DEFAULT_CATALOG.compose_down
+
+UPTIME = Operation(("uptime",))
+FREE_MEMORY = Operation(("free", "-h"))
+DISK_USAGE = Operation(("df", "-h", "$path"))
+
+# Host infrastructure services are systemd units, not Docker containers. The
+# unit name is validated against security.host_units before rendering.
+SYSTEMCTL_STATUS = Operation(("systemctl", "status", "--no-pager", "--full", "$unit"))
+JOURNALCTL_UNIT = Operation(
+    (
+        "journalctl",
+        "-u",
+        "$unit",
+        "-n",
+        "$lines",
+        "--no-pager",
+        "--output",
+        "short-iso",
+    )
+)
+
+
+# Backwards-compatible alias used by the server and its tests.
+def docker_logs_operation(
+    *, since: str | None = None, until: str | None = None
+) -> Operation:
+    """Docker ``logs`` operation (kept for existing callers)."""
+    return DEFAULT_CATALOG.logs(since=since, until=until)