remote-server-mcp 0.2.0__py3-none-any.whl

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/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)

remote_server_mcp/resolution.py

@@ -0,0 +1,265 @@
+"""
+Resolve a service directory or a container name to Docker containers.
+
+A directory below ``services_path`` is a service. Its containers are
+discovered through the ``com.docker.compose.project`` label, so the directory
+and the container name no longer have to match. A container name is accepted
+directly when it belongs to a service directory or is listed in
+``security.allowed_containers``.
+
+The resolver never builds a command from untrusted values: it only feeds
+validated names into the operation catalog (``docker ps -a`` and
+``test -d`` via the executor).
+"""
+
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+from server_management_lib import Executor, SecurityValidator
+
+from .operations import DEFAULT_CATALOG, LS_SERVICE_DIRS, ContainerCatalog
+
+EXIT_CODE_PATTERN = re.compile(r"⚠️ Exit code:\s*(-?\d+)")
+ERROR_MARKER = "❌"
+
+
+class ResolutionError(RuntimeError):
+    """Raised when a target cannot be resolved to an allowed container."""
+
+
+@dataclass(frozen=True)
+class Container:
+    """One row from ``docker ps -a``."""
+
+    name: str
+    project: str
+    status: str
+
+
+@dataclass(frozen=True)
+class Resolution:
+    """The containers a service directory or container name maps to."""
+
+    target: str
+    service: str | None
+    containers: tuple[str, ...]
+    #: ``service`` (directory), ``container`` (via its compose project) or
+    #: ``allowlist`` (``security.allowed_containers``).
+    source: str
+
+    @property
+    def multiple(self) -> bool:
+        return len(self.containers) > 1
+
+
+def command_failure(output: str) -> str | None:
+    """Return an error description when a command result represents a failure."""
+    if ERROR_MARKER in output:
+        return output.strip()
+    match = EXIT_CODE_PATTERN.search(output)
+    if match and int(match.group(1)) != 0:
+        return output.strip()
+    return None
+
+
+def parse_container_listing(output: str) -> list[Container]:
+    """Parse ``docker ps -a --format`` output into container records."""
+    containers = []
+    for line in output.splitlines():
+        if not line.strip() or line.startswith(ERROR_MARKER):
+            continue
+        parts = line.split("\t")
+        if len(parts) < 2 or not parts[0].strip():
+            continue
+        name = parts[0].strip()
+        project = parts[1].strip() if len(parts) > 1 else ""
+        status = parts[2].strip() if len(parts) > 2 else ""
+        containers.append(Container(name=name, project=project, status=status))
+    return containers
+
+
+async def collect_containers(
+    executor: Executor, catalog: ContainerCatalog = DEFAULT_CATALOG
+) -> list[Container]:
+    """List every container, including stopped and crashed ones."""
+    output = await executor.execute_safe_command(catalog.ps_all.render())
+    failure = command_failure(output)
+    if failure is not None:
+        raise ResolutionError(f"❌ Could not list Docker containers:\n{failure}")
+    return parse_container_listing(output)
+
+
+async def collect_service_directories(
+    executor: Executor, security: SecurityValidator
+) -> set[str]:
+    """Return the directory names below ``services_path``."""
+    base_path = security.services_base_path.rstrip("/") + "/"
+    output = await executor.execute_safe_command(LS_SERVICE_DIRS.render(path=base_path))
+    failure = command_failure(output)
+    if failure is not None:
+        raise ResolutionError(
+            f"❌ Could not list service directories in {base_path}:\n{failure}"
+        )
+    return {
+        line.strip().rstrip("/")
+        for line in output.splitlines()
+        if line.strip().endswith("/")
+    }
+
+
+def containers_for_service(
+    containers: Iterable[Container], service: str
+) -> list[Container]:
+    """Return the containers of a compose project, falling back to its name."""
+    by_project = [container for container in containers if container.project == service]
+    if by_project:
+        return by_project
+    return [container for container in containers if container.name == service]
+
+
+def _unknown_target(target: str, base_path: str) -> ResolutionError:
+    return ResolutionError(
+        f"❌ Unknown service or container: '{target}'\n"
+        f"No directory at {base_path.rstrip('/')}/{target} and no Docker "
+        f"container named '{target}'.\n"
+        "Use list_services() for directories and list_containers() for "
+        "Docker containers."
+    )
+
+
+def _service_without_containers(target: str, base_path: str) -> ResolutionError:
+    return ResolutionError(
+        f"❌ Service '{target}' exists in {base_path.rstrip('/')}/ but no Docker "
+        "container is associated with it.\n"
+        f"Expected a container whose com.docker.compose.project label or name "
+        f"is '{target}'. Use list_containers() to inspect the labels."
+    )
+
+
+def _container_not_allowed(
+    target: str, project: str, base_path: str
+) -> ResolutionError:
+    project_hint = (
+        f"Its compose project is '{project}'."
+        if project
+        else "It is not part of a compose project."
+    )
+    return ResolutionError(
+        f"❌ Container '{target}' is not backed by a service directory under "
+        f"{base_path.rstrip('/')}/.\n"
+        f"{project_hint}\n"
+        "Create the matching directory or add the container name to "
+        "security.allowed_containers."
+    )
+
+
+async def resolve_service_target(
+    executor: Executor,
+    security: SecurityValidator,
+    target: str,
+    catalog: ContainerCatalog = DEFAULT_CATALOG,
+) -> Resolution:
+    """Resolve a service directory or container name to allowed containers.
+
+    The caller must validate ``target`` with
+    :meth:`SecurityValidator.validate_service_name` first.
+    """
+    base_path = security.services_base_path
+    is_service_dir = await executor.check_service_exists(target)
+    containers = await collect_containers(executor, catalog)
+
+    if is_service_dir:
+        matches = containers_for_service(containers, target)
+        if not matches:
+            if containers:
+                raise _service_without_containers(target, base_path)
+            # An empty listing can mean "no containers" or an environment where
+            # the listing could not be parsed. Keep the legacy behavior and let
+            # Docker report the missing object.
+            return Resolution(
+                target=target,
+                service=target,
+                containers=(target,),
+                source="service",
+            )
+        return Resolution(
+            target=target,
+            service=target,
+            containers=tuple(container.name for container in matches),
+            source="service",
+        )
+
+    match = next(
+        (container for container in containers if container.name == target), None
+    )
+    if match is None:
+        raise _unknown_target(target, base_path)
+
+    if match.name in security.allowed_containers:
+        return Resolution(
+            target=target,
+            service=match.project or None,
+            containers=(match.name,),
+            source="allowlist",
+        )
+
+    project = match.project
+    if (
+        project
+        and security.validate_service_name(project)
+        and await executor.check_service_exists(project)
+    ):
+        return Resolution(
+            target=target,
+            service=project,
+            containers=(match.name,),
+            source="container",
+        )
+
+    raise _container_not_allowed(target, project, base_path)
+
+
+def service_target(
+    container: Container,
+    directories: set[str] | frozenset[str] = frozenset(),
+    allowed_containers: frozenset[str] = frozenset(),
+) -> str:
+    """Return how a container can be addressed, or ``-`` when it cannot."""
+    if container.name in allowed_containers:
+        return "(allowlisted)"
+    if container.project and container.project in directories:
+        return container.project
+    if container.name in directories:
+        return container.name
+    if container.project:
+        return "(no directory)"
+    return "-"
+
+
+def format_container_table(
+    containers: Sequence[Container],
+    *,
+    directories: set[str] | frozenset[str] = frozenset(),
+    allowed_containers: frozenset[str] = frozenset(),
+) -> str:
+    """Render a readable ``docker ps -a`` table with a service mapping."""
+    rows = [("NAME", "PROJECT", "SERVICE", "STATUS")]
+    for container in sorted(containers, key=lambda item: item.name):
+        rows.append(
+            (
+                container.name,
+                container.project or "-",
+                service_target(container, directories, allowed_containers),
+                container.status or "-",
+            )
+        )
+
+    widths = [max(len(row[index]) for row in rows) for index in range(3)]
+    lines = []
+    for row in rows:
+        lines.append(
+            "  ".join(row[index].ljust(widths[index]) for index in range(3))
+            + f"  {row[3]}"
+        )
+    return "\n".join(lines)