mcp-as-code 0.1.0__py3-none-any.whl

maco/runner.py

@@ -0,0 +1,104 @@
+"""Run Python scripts with generated MCP wrappers on PYTHONPATH."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+
+class RunnerError(RuntimeError):
+    """Raised when maco cannot prepare a code execution run."""
+
+
+def run_code(
+    code_path: str | os.PathLike[str],
+    script_args: list[str] | None = None,
+    *,
+    workspace: str | os.PathLike[str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+    python: str | None = None,
+) -> int:
+    """Run a Python script with the generated maco workspace available."""
+
+    script = Path(code_path).expanduser().resolve()
+    if not script.exists():
+        raise RunnerError(f"code file not found: {script}")
+    workspace_path = find_workspace(script, workspace)
+    gateway_file = workspace_path / "gateway.json"
+
+    env = os.environ.copy()
+    env["MACO_WORKSPACE"] = str(workspace_path)
+    env["MACO_GATEWAY_FILE"] = str(gateway_file)
+    gateway = _read_gateway(gateway_file)
+    if gateway.get("url") and not env.get("MACO_GATEWAY_URL"):
+        env["MACO_GATEWAY_URL"] = str(gateway["url"])
+    if gateway.get("token") and not env.get("MACO_GATEWAY_TOKEN"):
+        env["MACO_GATEWAY_TOKEN"] = str(gateway["token"])
+    env["PYTHONPATH"] = _prepend_path(str(workspace_path), env.get("PYTHONPATH"))
+
+    uv = shutil.which("uv")
+    if uv is None:
+        raise RunnerError("uv is required to run code; install uv or run the script manually with PYTHONPATH set")
+
+    command = [uv, "run"]
+    if python:
+        command.extend(["--python", python])
+    command.extend([str(script), *(script_args or [])])
+    completed = subprocess.run(command, env=env, cwd=str(Path(cwd).resolve()) if cwd else None)
+    return completed.returncode
+
+
+def find_workspace(
+    script: Path,
+    explicit_workspace: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Find the generated workspace for a script."""
+
+    candidates: list[Path] = []
+    if explicit_workspace:
+        candidates.append(Path(explicit_workspace).expanduser())
+    if os.environ.get("MACO_WORKSPACE"):
+        candidates.append(Path(os.environ["MACO_WORKSPACE"]).expanduser())
+    candidates.extend(parent / ".maco" for parent in [script.parent, *script.parents])
+    cwd = Path.cwd().resolve()
+    candidates.extend(parent / ".maco" for parent in [cwd, *cwd.parents])
+
+    seen: set[Path] = set()
+    for candidate in candidates:
+        resolved = candidate.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        if (resolved / "maco_generated" / "client.py").exists():
+            return resolved
+    raise RunnerError(
+        "could not find a generated maco workspace. Run `maco gen`, pass --workspace, "
+        "or set MACO_WORKSPACE."
+    )
+
+
+def _read_gateway(path: Path) -> dict[str, object]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+    except Exception as exc:
+        raise RunnerError(f"failed to read gateway file {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise RunnerError(f"gateway file {path} must contain a JSON object")
+    return data
+
+
+def _prepend_path(prefix: str, existing: str | None) -> str:
+    if not existing:
+        return prefix
+    return os.pathsep.join([prefix, existing])
+
+
+def exit_with_error(exc: BaseException) -> None:
+    print(f"maco: {exc}", file=sys.stderr)
+    raise SystemExit(1)

maco/sandbox/__init__.py

@@ -0,0 +1,43 @@
+"""Sandbox providers for maco serve-mcp execution."""
+
+from .core import (
+    DEFAULT_MATCHLOCK_GATEWAY_IP,
+    DEFAULT_SANDBOX_IMAGE,
+    GatewayInfo,
+    SANDBOX_SDK_ROOT,
+    SANDBOX_TOOLS_ROOT,
+    SANDBOX_USER,
+    SandboxContext,
+    SandboxError,
+    SandboxExec,
+    SandboxProvider,
+    SandboxRunResult,
+    guest_path_for,
+    provider_from_name,
+    translate_loopback_url,
+    write_code_file,
+)
+from .providers.docker import DockerSandboxProvider
+from .providers.local import LocalSandboxProvider
+from .providers.matchlock import MatchlockSandboxProvider
+
+__all__ = [
+    "DEFAULT_SANDBOX_IMAGE",
+    "DEFAULT_MATCHLOCK_GATEWAY_IP",
+    "DockerSandboxProvider",
+    "GatewayInfo",
+    "LocalSandboxProvider",
+    "MatchlockSandboxProvider",
+    "SANDBOX_SDK_ROOT",
+    "SANDBOX_TOOLS_ROOT",
+    "SANDBOX_USER",
+    "SandboxContext",
+    "SandboxError",
+    "SandboxExec",
+    "SandboxProvider",
+    "SandboxRunResult",
+    "guest_path_for",
+    "provider_from_name",
+    "translate_loopback_url",
+    "write_code_file",
+]

maco/sandbox/core.py

@@ -0,0 +1,216 @@
+"""Core sandbox types and provider factory."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from importlib.metadata import PackageNotFoundError, version
+import json
+import os
+from pathlib import Path
+from typing import Mapping, Protocol
+from urllib.parse import urlsplit, urlunsplit
+
+
+class SandboxError(RuntimeError):
+    """Raised when a sandbox provider cannot run a command."""
+
+
+def _maco_version() -> str:
+    try:
+        return version("maco")
+    except PackageNotFoundError:
+        for parent in Path(__file__).resolve().parents:
+            version_file = parent / "VERSION.txt"
+            if version_file.exists():
+                return version_file.read_text(encoding="utf-8").strip()
+        return "0.0.0"
+
+
+DEFAULT_SANDBOX_IMAGE = f"ghcr.io/jingkaihe/maco:{_maco_version()}-alpine"
+DEFAULT_MATCHLOCK_GATEWAY_IP = "192.168.100.1"
+SANDBOX_UID = 1000
+SANDBOX_GID = 1000
+SANDBOX_USER = f"{SANDBOX_UID}:{SANDBOX_GID}"
+SANDBOX_SDK_ROOT = "/workspace/macosdk"
+SANDBOX_TOOLS_ROOT = f"{SANDBOX_SDK_ROOT}/tools"
+
+
+@dataclass(frozen=True)
+class GatewayInfo:
+    """Host-side maco gateway coordinates."""
+
+    url: str
+    token: str | None = None
+
+    @classmethod
+    def from_file(cls, path: str | os.PathLike[str]) -> GatewayInfo:
+        gateway_path = Path(path).expanduser()
+        try:
+            payload = json.loads(gateway_path.read_text(encoding="utf-8"))
+        except FileNotFoundError as exc:
+            raise SandboxError(f"gateway file not found: {gateway_path}") from exc
+        except Exception as exc:
+            raise SandboxError(f"failed to read gateway file {gateway_path}: {exc}") from exc
+        if not isinstance(payload, dict):
+            raise SandboxError(f"gateway file {gateway_path} must contain a JSON object")
+        url = payload.get("url")
+        if not isinstance(url, str) or not url:
+            raise SandboxError(f"gateway file {gateway_path} must contain a non-empty url")
+        token = payload.get("token")
+        return cls(url=url, token=token if isinstance(token, str) and token else None)
+
+
+@dataclass(frozen=True)
+class SandboxRunResult:
+    """Result from a sandbox command."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.exit_code == 0
+
+
+@dataclass(frozen=True)
+class SandboxContext:
+    """Provider-independent paths and gateway details."""
+
+    workspace: Path
+    scratch: Path
+    gateway: GatewayInfo
+    timeout: int = 60
+    python_command: str | None = None
+    debug: bool = False
+
+
+@dataclass(frozen=True)
+class SandboxExec:
+    """Command request for a sandbox provider."""
+
+    command: str
+    timeout: int | None = None
+    env: Mapping[str, str] = field(default_factory=dict)
+
+
+class SandboxProvider(Protocol):
+    """Common execution surface for local, Docker, and Matchlock sandboxes."""
+
+    guest_workspace: str
+    guest_scratch: str
+
+    def start(self) -> None:
+        """Start or bootstrap provider resources."""
+
+    def stop(self) -> None:
+        """Release provider resources."""
+
+    def run(self, request: SandboxExec) -> SandboxRunResult:
+        """Run a non-interactive command in the sandbox."""
+
+    def write_file(self, relative_path: str, content: str) -> str:
+        """Write a file inside sandbox scratch and return its guest path."""
+
+    def python_script_command(self, guest_script_path: str, args: list[str]) -> str:
+        """Build the shell command used by code_execute for a guest script."""
+
+
+def provider_from_name(
+    name: str,
+    context: SandboxContext,
+    *,
+    image: str | None = None,
+    docker_binary: str = "docker",
+    docker_network: str | None = None,
+    docker_gateway_host: str = "host.docker.internal",
+    docker_gateway_ip: str | None = None,
+    matchlock_binary: str = "matchlock",
+    matchlock_gateway_host: str = "maco-gateway.internal",
+    matchlock_gateway_ip: str | None = None,
+    matchlock_extra_allow_hosts: list[str] | None = None,
+) -> SandboxProvider:
+    """Construct a sandbox provider from a CLI-friendly name."""
+
+    # Imports are local to avoid importing provider subprocess dependencies when
+    # callers only need the data types/helpers.
+    from .providers.docker import DockerSandboxProvider
+    from .providers.local import LocalSandboxProvider
+    from .providers.matchlock import MatchlockSandboxProvider
+
+    normalized = name.replace("_", "-").lower()
+    if normalized == "local":
+        return LocalSandboxProvider(context)
+    if normalized == "docker":
+        return DockerSandboxProvider(
+            context,
+            image=image or DEFAULT_SANDBOX_IMAGE,
+            docker_binary=docker_binary,
+            network=docker_network,
+            gateway_host=docker_gateway_host,
+            gateway_ip=docker_gateway_ip,
+        )
+    if normalized == "matchlock":
+        return MatchlockSandboxProvider(
+            context,
+            image=image or DEFAULT_SANDBOX_IMAGE,
+            matchlock_binary=matchlock_binary,
+            gateway_host=matchlock_gateway_host,
+            gateway_ip=matchlock_gateway_ip,
+            extra_allow_hosts=matchlock_extra_allow_hosts or [],
+        )
+    raise SandboxError(f"unknown sandbox provider {name!r}; expected local, docker, or matchlock")
+
+
+def write_code_file(scratch: Path, filename: str, code: str) -> Path:
+    """Write code into the scratch directory after constraining the path."""
+
+    if not filename.strip():
+        raise SandboxError("filename must be non-empty")
+    relative = Path(filename)
+    if relative.is_absolute() or ".." in relative.parts:
+        raise SandboxError("filename must be a relative path inside the sandbox scratch directory")
+    path = scratch / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(code, encoding="utf-8")
+    return path
+
+
+def guest_path_for(local_path: Path, scratch: Path, guest_scratch: str) -> str:
+    """Translate a local scratch path to the corresponding guest path."""
+
+    try:
+        relative = local_path.resolve().relative_to(scratch.resolve())
+    except ValueError as exc:
+        raise SandboxError(f"path {local_path} is not inside scratch directory {scratch}") from exc
+    return posix_join(guest_scratch, relative.as_posix())
+
+
+def translate_loopback_url(url: str, host: str) -> str:
+    """Replace localhost in a gateway URL with a guest-reachable host alias."""
+
+    parts = urlsplit(url)
+    if parts.hostname not in {"127.0.0.1", "localhost", "::1"}:
+        return url
+    netloc = host
+    if parts.port is not None:
+        netloc = f"{host}:{parts.port}"
+    return urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment))
+
+
+def normalize_context(context: SandboxContext) -> SandboxContext:
+    workspace = context.workspace.expanduser().resolve()
+    scratch = context.scratch.expanduser().resolve()
+    scratch.mkdir(parents=True, exist_ok=True)
+    return SandboxContext(
+        workspace=workspace,
+        scratch=scratch,
+        gateway=context.gateway,
+        timeout=context.timeout,
+        python_command=context.python_command,
+        debug=context.debug,
+    )
+
+
+def posix_join(root: str, child: str) -> str:
+    return f"{root.rstrip('/')}/{child.lstrip('/')}"

maco/sandbox/providers/__init__.py

@@ -0,0 +1,7 @@
+"""Provider implementations for maco-sandbox."""
+
+from .docker import DockerSandboxProvider
+from .local import LocalSandboxProvider
+from .matchlock import MatchlockSandboxProvider
+
+__all__ = ["DockerSandboxProvider", "LocalSandboxProvider", "MatchlockSandboxProvider"]

maco/sandbox/providers/base.py

@@ -0,0 +1,69 @@
+"""Shared helpers for concrete sandbox providers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import shlex
+from typing import Mapping
+
+from ..core import SANDBOX_SDK_ROOT, SandboxContext, SandboxError, SandboxExec, normalize_context, posix_join
+
+
+class BaseSandboxProvider:
+    guest_workspace: str
+    guest_scratch: str
+    default_python_command = "python"
+
+    def __init__(self, context: SandboxContext) -> None:
+        self.context = normalize_context(context)
+
+    def start(self) -> None:
+        """Start provider resources. Local/one-shot providers can no-op."""
+
+    def stop(self) -> None:
+        """Release provider resources. Local/one-shot providers can no-op."""
+
+    def write_file(self, relative_path: str, content: str) -> str:
+        path = self._local_scratch_path(relative_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+        return self._guest_scratch_path(relative_path)
+
+    def python_script_command(self, guest_script_path: str, args: list[str]) -> str:
+        command = self.context.python_command or self.default_python_command
+        return " ".join([command, shlex.quote(guest_script_path), *[shlex.quote(arg) for arg in args]])
+
+    def _timeout(self, request: SandboxExec) -> int:
+        return request.timeout or self.context.timeout
+
+    def _guest_env(self, request_env: Mapping[str, str], *, gateway_url: str) -> dict[str, str]:
+        env = {
+            "MACO_WORKSPACE": self.guest_workspace,
+            "MACO_GATEWAY_FILE": posix_join(self.guest_workspace, "gateway.json"),
+            "MACO_GATEWAY_URL": gateway_url,
+            "PYTHONPATH": self.guest_workspace,
+        }
+        if self.context.gateway.token:
+            env["MACO_GATEWAY_TOKEN"] = self.context.gateway.token
+        env.update(request_env)
+        return env
+
+    def _local_scratch_path(self, relative_path: str) -> Path:
+        relative = self._relative_scratch_path(relative_path)
+        return self.context.scratch / relative
+
+    def _guest_scratch_path(self, relative_path: str) -> str:
+        return posix_join(self.guest_scratch, self._relative_scratch_path(relative_path).as_posix())
+
+    def _relative_scratch_path(self, relative_path: str) -> Path:
+        if not relative_path.strip():
+            raise SandboxError("path must be non-empty")
+        relative = Path(relative_path)
+        if relative.is_absolute() or ".." in relative.parts:
+            raise SandboxError("path must be relative and inside the sandbox scratch directory")
+        return relative
+
+
+class RemoteSandboxProvider(BaseSandboxProvider):
+    guest_workspace = SANDBOX_SDK_ROOT
+    guest_scratch = "/workspace"

maco/sandbox/providers/docker.py

@@ -0,0 +1,228 @@
+"""Docker sandbox provider."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+import sys
+import uuid
+from urllib.parse import urlsplit, urlunsplit
+
+from ..core import (
+    SANDBOX_SDK_ROOT,
+    SANDBOX_USER,
+    SandboxContext,
+    SandboxError,
+    SandboxExec,
+    SandboxRunResult,
+    translate_loopback_url,
+)
+from .base import RemoteSandboxProvider
+
+
+class DockerSandboxProvider(RemoteSandboxProvider):
+    """Run commands inside one long-lived Docker container."""
+
+    def __init__(
+        self,
+        context: SandboxContext,
+        *,
+        image: str,
+        docker_binary: str = "docker",
+        network: str | None = None,
+        gateway_host: str = "host.docker.internal",
+        gateway_ip: str | None = None,
+    ) -> None:
+        super().__init__(context)
+        self.image = image
+        self.docker_binary = docker_binary
+        self.network = network
+        self.gateway_host = gateway_host
+        self.gateway_ip = gateway_ip
+        self.container_name = self._container_name()
+        self.container_id: str | None = None
+        self._start_attempted = False
+
+    def start(self) -> None:
+        if self.container_id is not None:
+            return
+        gateway_url = _docker_gateway_url(
+            self.context.gateway.url,
+            gateway_host=self.gateway_host,
+            gateway_ip=self.gateway_ip,
+        )
+        env = self._guest_env({}, gateway_url=gateway_url)
+        host_env = os.environ.copy()
+        command = [
+            self.docker_binary,
+            "run",
+            "-d",
+            "--rm",
+            "--user",
+            SANDBOX_USER,
+            "--name",
+            self.container_name,
+            "--label",
+            "org.opencontainers.image.title=maco-sandbox",
+            "--label",
+            "maco.managed=true",
+        ]
+        if self.network:
+            command.extend(["--network", self.network])
+        if self.gateway_ip:
+            command.extend(["--add-host", f"{self.gateway_host}:{self.gateway_ip}"])
+        for key, value in sorted(env.items()):
+            if key == "MACO_GATEWAY_TOKEN" and self.context.gateway.token:
+                host_env[key] = self.context.gateway.token
+                command.extend(["-e", key])
+            else:
+                command.extend(["-e", f"{key}={value}"])
+        command.extend(["-w", self.guest_scratch, self.image])
+        self._start_attempted = True
+        try:
+            completed = subprocess.run(
+                command,
+                env=host_env,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=self.context.timeout,
+                check=False,
+            )
+            if completed.returncode != 0:
+                raise SandboxError(f"failed to start Docker sandbox: {completed.stderr.strip()}")
+            self.container_id = completed.stdout.strip()
+            self._bootstrap_sdk()
+        except BaseException:
+            self.stop()
+            raise
+
+    def stop(self) -> None:
+        if self.container_id is None and not self._start_attempted:
+            return
+        target = self.container_id or self.container_name
+        try:
+            subprocess.run(
+                [self.docker_binary, "rm", "-f", target],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=10,
+                check=False,
+            )
+        except Exception:
+            pass
+        finally:
+            self.container_id = None
+            self._start_attempted = False
+
+    def run(self, request: SandboxExec) -> SandboxRunResult:
+        self.start()
+        assert self.container_id is not None
+        command = [
+            self.docker_binary,
+            "exec",
+            "--user",
+            SANDBOX_USER,
+            "-w",
+            self.guest_scratch,
+            self.container_id,
+            "sh",
+            "-lc",
+            request.command,
+        ]
+        completed = subprocess.run(
+            command,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=self._timeout(request),
+            check=False,
+        )
+        if self.context.debug:
+            print(f"maco docker command: {self._command_summary(command)!r}", file=sys.stderr)
+        return SandboxRunResult(completed.returncode, completed.stdout, completed.stderr)
+
+    def write_file(self, relative_path: str, content: str) -> str:
+        self.start()
+        assert self.container_id is not None
+        guest_path = self._guest_scratch_path(relative_path)
+        parent = guest_path.rsplit("/", 1)[0]
+        command = [
+            self.docker_binary,
+            "exec",
+            "-i",
+            "--user",
+            SANDBOX_USER,
+            self.container_id,
+            "sh",
+            "-lc",
+            f"mkdir -p {shlex.quote(parent)} && cat > {shlex.quote(guest_path)}",
+        ]
+        completed = subprocess.run(
+            command,
+            input=content,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=self.context.timeout,
+            check=False,
+        )
+        if completed.returncode != 0:
+            raise SandboxError(f"failed to write Docker sandbox file {guest_path}: {completed.stderr.strip()}")
+        return guest_path
+
+    def _bootstrap_sdk(self) -> None:
+        assert self.container_id is not None
+        command = [
+            self.docker_binary,
+            "exec",
+            "--user",
+            SANDBOX_USER,
+            self.container_id,
+            "maco",
+            "sandbox-bootstrap",
+            "--workspace",
+            SANDBOX_SDK_ROOT,
+        ]
+        completed = subprocess.run(
+            command,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=self.context.timeout,
+            check=False,
+        )
+        if completed.returncode != 0:
+            raise SandboxError(f"failed to bootstrap Docker sandbox SDK: {completed.stderr.strip()}")
+
+    def _command_summary(self, command: list[str]) -> list[str]:
+        redacted: list[str] = []
+        for part in command:
+            if self.context.gateway.token and part == self.context.gateway.token:
+                redacted.append("<redacted>")
+            else:
+                redacted.append(part)
+        return redacted
+
+    def _container_name(self) -> str:
+        return f"maco-sandbox-{uuid.uuid4().hex[:12]}"
+
+
+def _docker_gateway_url(url: str, *, gateway_host: str, gateway_ip: str | None) -> str:
+    translated = translate_loopback_url(url, gateway_host)
+    if gateway_ip and _url_host(translated) in {gateway_ip, "0.0.0.0"}:
+        return _replace_url_host(translated, gateway_host)
+    return translated
+
+
+def _url_host(url: str) -> str | None:
+    return urlsplit(url).hostname
+
+
+def _replace_url_host(url: str, host: str) -> str:
+    parts = urlsplit(url)
+    netloc = host
+    if parts.port is not None:
+        netloc = f"{host}:{parts.port}"
+    return urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment))