hyperbox-mcp 0.2.1__py3-none-any.whl

hyperbox_mcp/builder.py

@@ -0,0 +1,90 @@
+"""Building custom sandbox environments, from a terminal only.
+
+This is deliberately not reachable from the MCP tool surface. A build
+runs whatever the Dockerfile says — arbitrary commands, as root, with
+network access, under none of the limits policy.py enforces on a
+sandbox. That is a decision for the person at the keyboard, not for a
+model. Agents consume the result by name; they never produce it.
+
+Anything here may print to stdout: it runs under the `hyperbox` CLI,
+never inside the server process, whose stdout belongs to the client.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from hyperbox_mcp import engine, policy, validate
+
+HYPERBOX_DIR = Path.home() / ".hyperbox"
+ENV_DIR = HYPERBOX_DIR / "environments"
+
+
+def list_environments() -> int:
+    """Print every environment the server would currently resolve."""
+    envs = policy.environments()
+    print(f"{'ENVIRONMENT':<20} {'IMAGE':<48} {'DOCKERFILE'}")
+    print("-" * 82)
+    for name, image in sorted(envs.items()):
+        dockerfile = ENV_DIR / name / "Dockerfile"
+        print(f"{name:<20} {image:<48} {'yes' if dockerfile.exists() else 'built-in'}")
+    return 0
+
+
+def run_build(env_name: str, custom_path: str | None = None) -> int:
+    """Build a local Dockerfile into the image `create_sandbox` will use."""
+    # Validated here too, not only at the MCP boundary: env_name becomes a
+    # directory under ~/.hyperbox and an image tag, and this path never
+    # goes through the server.
+    try:
+        name = validate.environment_name(env_name)
+    except validate.InvalidInput as exc:
+        print(f"Error: {exc}")
+        return 2
+
+    env_dir = ENV_DIR / name
+    dockerfile = env_dir / "Dockerfile"
+
+    if custom_path:
+        source = Path(custom_path).expanduser().resolve()
+        if not source.is_file():
+            print(f"Error: no Dockerfile at {source}")
+            return 1
+        env_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, dockerfile)
+        print(f"Copied {source} -> {dockerfile}")
+
+    if not dockerfile.exists():
+        print(f"Error: no Dockerfile at {dockerfile}")
+        print("Provide one with:")
+        print(f"  hyperbox build {name} --custom /path/to/Dockerfile")
+        return 1
+
+    try:
+        backend = engine.detect("auto")
+    except Exception as exc:  # noqa: BLE001 - reported, not swallowed
+        print(f"Error: no container engine available: {exc}")
+        return 1
+
+    target_image = f"hyperbox-local/{name}:latest"
+    binary = engine.client_dialect(backend)
+    cmd = [binary, "build", "-t", target_image, "-f", str(dockerfile), str(env_dir)]
+
+    print(f"Building '{name}' as {target_image} using {binary}...")
+    try:
+        result = subprocess.run(cmd, check=False)
+    except KeyboardInterrupt:
+        print("\nBuild cancelled.")
+        return 130
+    except OSError as exc:
+        print(f"\nCould not run {binary}: {exc}")
+        return 1
+
+    if result.returncode == 0:
+        print(f"\nBuilt '{name}'. Use it with create_sandbox(environment='{name}').")
+        print("A running server picks it up without a restart.")
+    else:
+        print(f"\nBuild failed with exit code {result.returncode}.")
+    return result.returncode

hyperbox_mcp/cli.py

@@ -0,0 +1,164 @@
+"""Terminal subcommands for the `hyperbox` executable.
+
+Kept apart from server.py so that starting the MCP server imports none of
+it. Anything here may print to stdout; the server may not, because a
+stdio MCP client is reading that stream.
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+
+def usage() -> str:
+    return (
+        "Usage:\n"
+        "  hyperbox                 Start the MCP server on stdio (default)\n"
+        "  hyperbox doctor          Check this machine can run sandboxes\n"
+        "    --pull                 Also pull the sandbox image if missing\n"
+        "    --quick                Skip the live create/run/destroy check\n"
+        "  hyperbox config          Print a ready-to-paste MCP client config\n"
+        "    --format json          mcpServers block (Claude Desktop, generic)\n"
+        "    --format cursor        servers block (.vscode/mcp.json)\n"
+        "    --format yaml          YAML list (Continue-based clients)\n"
+        "    --format antigravity   Antigravity mcp_config.json\n"
+        "  hyperbox envs            List environments create_sandbox can use\n"
+        "  hyperbox build <name>    Build an environment from a Dockerfile\n"
+        "    --custom <path>        Copy that Dockerfile in and build it\n"
+        "  hyperbox logs            Show the server log\n"
+        "    --follow               Keep printing as new lines arrive\n"
+        "  hyperbox --version       Print the installed version\n"
+    )
+
+
+def _version() -> str:
+    try:
+        return version("hyperbox-mcp")
+    except PackageNotFoundError:  # pragma: no cover - running from source
+        return "unknown (not installed as a package)"
+
+
+def _logs(follow: bool = False) -> int:
+    """Print the server log, optionally following it.
+
+    Written in Python rather than shelling out to `tail -f`: this package
+    is expected to work on Windows, where there is no tail, and building
+    a shell command out of a home-directory path invites quoting bugs.
+    """
+    import time
+
+    from hyperbox_mcp.server import LOG_FILE
+
+    if not LOG_FILE.exists():
+        print(f"No log yet at {LOG_FILE}")
+        print("It is created when the server next starts.")
+        return 1
+
+    with LOG_FILE.open("r", encoding="utf-8", errors="replace") as fh:
+        sys.stdout.write(fh.read())
+        if not follow:
+            return 0
+        sys.stdout.flush()
+        try:
+            while True:
+                line = fh.readline()
+                if line:
+                    sys.stdout.write(line)
+                    sys.stdout.flush()
+                else:
+                    time.sleep(0.4)
+        except KeyboardInterrupt:
+            return 0
+
+
+def dispatch(argv: list[str]) -> int:
+    command, *rest = argv
+
+    if command in {"--version", "-V"}:
+        print(f"hyperbox {_version()}")
+        return 0
+
+    if command in {"help", "--help", "-h"}:
+        print(usage())
+        return 0
+
+    if command == "doctor":
+        unknown = [a for a in rest if a not in {"--pull", "--quick"}]
+        if unknown:
+            print(f"hyperbox doctor: unknown option {unknown[0]!r}\n")
+            print(usage())
+            return 2
+        from hyperbox_mcp.doctor import run_doctor
+
+        return run_doctor(pull="--pull" in rest, live="--quick" not in rest)
+
+    if command == "config":
+        fmt = "json"
+        rest_iter = list(rest)
+        while rest_iter:
+            arg = rest_iter.pop(0)
+            if arg == "--format":
+                if not rest_iter:
+                    print("hyperbox config: --format needs a value\n")
+                    print(usage())
+                    return 2
+                fmt = rest_iter.pop(0)
+            elif arg.startswith("--format="):
+                fmt = arg.split("=", 1)[1]
+            else:
+                print(f"hyperbox config: unknown option {arg!r}\n")
+                print(usage())
+                return 2
+        if fmt not in {"json", "cursor", "yaml", "antigravity"}:
+            print(f"hyperbox config: unknown format {fmt!r}. "
+                  "Use json, cursor, yaml or antigravity.\n")
+            return 2
+        from hyperbox_mcp.clientconfig import print_config
+
+        return print_config(fmt)
+
+    if command == "logs":
+        unknown = [a for a in rest if a not in {"--follow", "-f"}]
+        if unknown:
+            print(f"hyperbox logs: unknown option {unknown[0]!r}\n")
+            print(usage())
+            return 2
+        return _logs(follow=bool(rest))
+
+    if command == "envs":
+        if rest:
+            print(f"hyperbox envs: unexpected argument {rest[0]!r}\n")
+            print(usage())
+            return 2
+        from hyperbox_mcp.builder import list_environments
+
+        return list_environments()
+
+    if command == "build":
+        if not rest:
+            print("hyperbox build: missing environment name\n")
+            print(usage())
+            return 2
+        name, *opts = rest
+        custom = None
+        while opts:
+            arg = opts.pop(0)
+            if arg == "--custom":
+                if not opts:
+                    print("hyperbox build: --custom needs a path\n")
+                    print(usage())
+                    return 2
+                custom = opts.pop(0)
+            elif arg.startswith("--custom="):
+                custom = arg.split("=", 1)[1]
+            else:
+                print(f"hyperbox build: unknown option {arg!r}\n")
+                print(usage())
+                return 2
+        from hyperbox_mcp.builder import run_build
+
+        return run_build(name, custom)
+
+    print(usage())
+    return 2

hyperbox_mcp/clientconfig.py

@@ -0,0 +1,203 @@
+"""Generate a ready-to-paste MCP client configuration.
+
+Every value in a client config is something this process already knows:
+where its own executable lives, and where the container CLI lives. Asking
+a person to retype those by hand is where setup actually fails — most
+sharply on Windows, where an absolute path routinely contains a space and
+every backslash has to be escaped for JSON, in a file whose only failure
+mode is "no tools appeared" with no error anywhere.
+
+So the escaping is done by serialising rather than by hand. `json.dumps`
+gets Windows paths right by construction, and YAML's double-quoted
+scalars use the same escape rules, so the YAML output quotes its strings
+the same way — which is also why this needs no YAML dependency.
+
+Notes go to stderr and the config to stdout, so `hyperbox config >
+mcp.json` writes a clean file while a person still sees the guidance.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from hyperbox_mcp import engine, policy
+
+#: The server name a client will show these tools under.
+SERVER_NAME = "hyperbox"
+
+#: Directories that must be on PATH for the server to find its engine,
+#: beyond whatever the engine CLI's own directory turns out to be.
+_SYSTEM_PATH_DIRS = {
+    "win32": (r"C:\Windows\System32", r"C:\Windows"),
+}
+_POSIX_PATH_DIRS = ("/usr/local/bin", "/usr/bin", "/bin")
+
+
+def executable_path() -> str:
+    """Absolute path to the `hyperbox` command a client should launch.
+
+    `shutil.which` is preferred over `sys.argv[0]`: it resolves the name
+    the way a client would, which is the thing being configured.
+    """
+    found = shutil.which("hyperbox")
+    if found:
+        return os.path.abspath(found)
+    # Running as `python -m hyperbox_mcp.server`, or a console script not
+    # on PATH. argv[0] still names something launchable.
+    argv0 = sys.argv[0] or ""
+    if argv0 and os.path.exists(argv0):
+        return os.path.abspath(argv0)
+    return "hyperbox"
+
+
+def _looks_like_a_checkout(executable: str) -> bool:
+    """Whether this executable lives inside a source tree rather than an
+    installed tool — `uv run` in a clone produces exactly that."""
+    parts = {p.lower() for p in Path(executable).parts}
+    return bool({".venv", "venv"} & parts)
+
+
+def path_entries() -> list[str]:
+    """Directories a client must put on PATH, most specific first.
+
+    Clients launch servers with a trimmed environment, so the container
+    CLI is frequently unreachable unless it is named explicitly. The
+    engine probe already knows where it is.
+    """
+    entries: list[str] = []
+
+    def add(directory: str) -> None:
+        if directory and directory not in entries:
+            entries.append(directory)
+
+    # The executable's own directory, so a client that resolves by name
+    # still finds it.
+    add(os.path.dirname(executable_path()))
+
+    for backend in policy.BACKENDS:
+        try:
+            status = engine.probe(backend)
+        except Exception:  # noqa: BLE001 - a config is useful without an engine
+            continue
+        if status.binary:
+            add(os.path.dirname(status.binary))
+
+    for directory in _SYSTEM_PATH_DIRS.get(sys.platform, _POSIX_PATH_DIRS):
+        add(directory)
+    return entries
+
+
+def _server_entry() -> dict:
+    separator = ";" if sys.platform == "win32" else ":"
+    return {
+        "command": executable_path(),
+        "args": [],
+        "env": {"PATH": separator.join(path_entries())},
+    }
+
+
+def _yaml_scalar(value: str) -> str:
+    """A double-quoted YAML scalar.
+
+    YAML's double-quoted style uses JSON's escape rules, so serialising
+    with json.dumps produces a correct — and correctly escaped — scalar.
+    That is the whole point: Windows backslashes are handled by the
+    serialiser rather than by whoever is editing the file.
+    """
+    return json.dumps(value)
+
+
+def render(fmt: str = "json") -> str:
+    """The configuration block for `fmt`, ready to paste."""
+    entry = _server_entry()
+
+    if fmt == "yaml":
+        # Continue-based clients: a YAML list under mcpServers.
+        lines = [
+            "mcpServers:",
+            f"  - name: {SERVER_NAME}",
+            f"    command: {_yaml_scalar(entry['command'])}",
+            "    args: []",
+            "    env:",
+            f"      PATH: {_yaml_scalar(entry['env']['PATH'])}",
+        ]
+        return "\n".join(lines)
+
+    # Cursor and VS Code use "servers" in .vscode/mcp.json; Claude Desktop,
+    # Antigravity and most others use "mcpServers". Same object either way,
+    # so antigravity needs no branch here — only a different file to put it
+    # in, which notes() names.
+    key = "servers" if fmt == "cursor" else "mcpServers"
+    return json.dumps({key: {SERVER_NAME: entry}}, indent=2)
+
+
+def notes(fmt: str) -> list[str]:
+    """Guidance printed to stderr, so stdout stays paste-clean."""
+    executable = executable_path()
+    out = []
+
+    if fmt == "yaml":
+        out.append(
+            "Continue-based clients: merge into your mcpservers YAML "
+            "config (often mcpservers/config.yaml)"
+        )
+    elif fmt == "cursor":
+        out.append("Cursor / VS Code: merge into .vscode/mcp.json")
+    elif fmt == "antigravity":
+        out.append(
+            "Antigravity: merge into ~/.gemini/antigravity/mcp_config.json"
+        )
+        out.append(
+            "  (restart Antigravity afterwards; it reads the file at startup)"
+        )
+    else:
+        out.append("Merge into your client's MCP config (Claude Desktop: "
+                   "claude_desktop_config.json)")
+
+    out.append("")
+    if _looks_like_a_checkout(executable):
+        out.append(
+            "WARNING: this command lives inside a source checkout, so the "
+            "config below is tied to that folder and breaks if you move or "
+            "delete it. Install it as a tool, then run this again:"
+        )
+        out.append("    uv tool install hyperbox-mcp")
+        out.append(f"  (current: {executable})")
+    else:
+        out.append(
+            "No checkout is needed: this launches the installed executable "
+            "directly, so the repository can be moved or deleted."
+        )
+
+    reachable = [b for b in policy.BACKENDS if engine.probe(b).reachable]
+    if reachable:
+        out.append("")
+        out.append(f"Container engine found: {', '.join(reachable)}")
+    else:
+        out.append("")
+        out.append(
+            "WARNING: no container engine is reachable right now. The "
+            "config below is still correct — start Docker or Podman, then "
+            "run `hyperbox doctor`."
+        )
+
+    out.append("")
+    out.append(
+        "Before the first sandbox, pull the image once so a multi-gigabyte "
+        "download never happens inside a client request (clients time a "
+        "request out long before it could finish):"
+    )
+    out.append("    hyperbox doctor --pull")
+    return out
+
+
+def print_config(fmt: str = "json") -> int:
+    for line in notes(fmt):
+        print(line, file=sys.stderr)
+    print("", file=sys.stderr)
+    print(render(fmt))
+    return 0