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

maco/serve_mcp.py

@@ -0,0 +1,527 @@
+"""HTTP MCP server for running maco code inside a sandbox provider."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import threading
+from types import FrameType
+from typing import Annotated, Any
+
+from jinja2 import Environment, PackageLoader, StrictUndefined
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from .codegen import fetch_gateway_tools, generate_sandbox_sdk, server_module_names
+from .config import load_config
+from .gateway import GatewayServer, ServeOptions
+from .sandbox import (
+    DEFAULT_MATCHLOCK_GATEWAY_IP,
+    GatewayInfo,
+    SandboxContext,
+    SandboxExec,
+    SandboxProvider,
+    SandboxRunResult,
+    provider_from_name,
+)
+
+
+_TEMPLATES = Environment(
+    loader=PackageLoader("maco", "templates"),
+    trim_blocks=True,
+    lstrip_blocks=True,
+    undefined=StrictUndefined,
+)
+
+
+@dataclass(frozen=True)
+class ServeMcpOptions:
+    """Configuration for the sandbox-backed MCP server."""
+
+    config: str | Path = "mcp.json"
+    provider: str = "local"
+    workspace: str | Path = ".maco"
+    clean: bool = False
+    scratch: str | Path | None = None
+    gateway_file: str | Path | None = None
+    gateway_host: str | None = None
+    gateway_port: int = 0
+    gateway_token: str | None = None
+    gateway_use_token: bool = True
+    host: str = "127.0.0.1"
+    port: int = 8789
+    timeout: int = 60
+    debug: bool = False
+    image: str | None = None
+    python_command: 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_allow_host: tuple[str, ...] = ()
+
+
+class _ServeMcpShutdown(KeyboardInterrupt):
+    """Raised from signal handlers so provider cleanup can run."""
+
+
+def _install_shutdown_signal_handlers() -> tuple[tuple[int, Any], ...]:
+    if threading.current_thread() is not threading.main_thread():
+        return ()
+
+    def _request_shutdown(signum: int, _frame: FrameType | None) -> None:
+        print(f"\nreceived signal {signum}; stopping maco serve-mcp", file=sys.stderr)
+        raise _ServeMcpShutdown
+
+    return (
+        (signal.SIGINT, signal.signal(signal.SIGINT, _request_shutdown)),
+        (signal.SIGTERM, signal.signal(signal.SIGTERM, _request_shutdown)),
+    )
+
+
+def _restore_signal_handlers(handlers: tuple[tuple[int, Any], ...]) -> None:
+    if threading.current_thread() is not threading.main_thread():
+        return
+    for signum, handler in handlers:
+        signal.signal(signum, handler)
+
+
+def serve_mcp(options: ServeMcpOptions) -> None:
+    """Run a streamable HTTP MCP server exposing sandboxed bash/code tools."""
+
+    gateway_server: GatewayServer | None = None
+    provider: SandboxProvider | None = None
+    old_signal_handlers = _install_shutdown_signal_handlers()
+    try:
+        workspace = Path(options.workspace).expanduser().resolve()
+        scratch = (
+            Path(options.scratch).expanduser().resolve()
+            if options.scratch is not None
+            else workspace.parent / "maco-serve-mcp"
+        )
+        gateway_file = (
+            Path(options.gateway_file).expanduser().resolve()
+            if options.gateway_file is not None
+            else workspace / "gateway.json"
+        )
+        normalized_provider = _normalize_provider(options.provider)
+        managed_gateway = options.gateway_file is None
+        docker_gateway_ip = (
+            _docker_gateway_ip(
+                options.docker_gateway_ip,
+                managed_gateway=managed_gateway,
+                docker_binary=options.docker_binary,
+                docker_network=options.docker_network,
+            )
+            if normalized_provider == "docker"
+            else None
+        )
+        matchlock_gateway_ip = (
+            _matchlock_gateway_ip(
+                options.matchlock_gateway_ip,
+                managed_gateway=managed_gateway,
+                gateway_file=gateway_file,
+            )
+            if normalized_provider == "matchlock"
+            else None
+        )
+        if options.gateway_file is None:
+            config = load_config(options.config)
+            gateway_host = options.gateway_host or _default_gateway_host()
+            extra_hosts = _gateway_extra_hosts(
+                normalized_provider,
+                docker_gateway_ip=docker_gateway_ip,
+                matchlock_gateway_ip=matchlock_gateway_ip,
+                explicit_gateway_host=options.gateway_host,
+            )
+            gateway_server = GatewayServer(
+                config,
+                ServeOptions(
+                    host=gateway_host,
+                    port=options.gateway_port,
+                    workspace=workspace,
+                    token=options.gateway_token,
+                    use_token=options.gateway_use_token,
+                    extra_hosts=extra_hosts,
+                    freebind_hosts=_gateway_freebind_hosts(
+                        gateway_host,
+                        extra_hosts=extra_hosts,
+                        docker_gateway_ip=docker_gateway_ip,
+                        matchlock_gateway_ip=matchlock_gateway_ip,
+                    ),
+                ),
+            ).start()
+            gateway_file = gateway_server.gateway_file
+            print("maco gateway started")
+            print(f"  URL: {gateway_server.url}")
+            for url in gateway_server.extra_urls:
+                print(f"  extra URL: {url}")
+            print(f"  gateway file: {gateway_file}")
+        gateway = GatewayInfo.from_file(gateway_file)
+        tools_by_server = fetch_gateway_tools(gateway.url, token=gateway.token)
+        modules = sorted(server_module_names(tools_by_server.keys()).values())
+        if options.provider.replace("_", "-").lower() == "local":
+            _clean_local_sdk(workspace, clean=options.clean)
+            stats = generate_sandbox_sdk(tools_by_server, workspace=workspace, clean=False)
+            print(f"Generated local sandbox SDK with {stats.tool_count} tools from {stats.server_count} servers")
+            print(f"SDK workspace: {stats.workspace}")
+        context = SandboxContext(
+            workspace=workspace,
+            scratch=scratch,
+            gateway=gateway,
+            timeout=options.timeout,
+            python_command=options.python_command,
+            debug=options.debug,
+        )
+        provider = provider_from_name(
+            options.provider,
+            context,
+            image=options.image,
+            docker_binary=options.docker_binary,
+            docker_network=options.docker_network,
+            docker_gateway_host=options.docker_gateway_host,
+            docker_gateway_ip=docker_gateway_ip,
+            matchlock_binary=options.matchlock_binary,
+            matchlock_gateway_host=options.matchlock_gateway_host,
+            matchlock_gateway_ip=matchlock_gateway_ip,
+            matchlock_extra_allow_hosts=list(options.matchlock_allow_host),
+        )
+        provider.start()
+        app = create_serve_mcp_app(provider, context, server_modules=modules, host=options.host, port=options.port)
+        print("maco serve-mcp started")
+        print(f"  URL: http://{options.host}:{options.port}/mcp")
+        print(f"  provider: {options.provider}")
+        print(f"  SDK: {provider.guest_workspace}")
+        print(f"  scratch: {scratch}")
+        app.run("streamable-http")
+    except _ServeMcpShutdown:
+        pass
+    finally:
+        _restore_signal_handlers(old_signal_handlers)
+        try:
+            if provider is not None:
+                provider.stop()
+        finally:
+            if gateway_server is not None:
+                gateway_server.stop()
+
+
+def create_serve_mcp_app(
+    provider: SandboxProvider,
+    context: SandboxContext,
+    *,
+    server_modules: list[str] | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8789,
+) -> FastMCP:
+    """Create the MCP app used by ``serve_mcp``.
+
+    Separated for tests and future embedding. Tools intentionally return plain
+    JSON-serializable dictionaries so MCP clients can inspect exit status,
+    stdout, and stderr.
+    """
+
+    app = FastMCP(
+        "maco-serve-mcp",
+        instructions=_mcp_instructions(provider, context, server_modules=server_modules),
+        host=host,
+        port=port,
+        json_response=True,
+        stateless_http=True,
+    )
+
+    @app.tool(description=_bash_description(provider, context, server_modules=server_modules))
+    def bash(
+        command: Annotated[
+            str,
+            Field(description="Non-interactive shell command to run in the sandbox scratch directory."),
+        ],
+        timeout: Annotated[
+            int | None,
+            Field(description="Optional command timeout in seconds. Omit to use the server default."),
+        ] = None,
+    ) -> dict[str, Any]:
+        result = provider.run(SandboxExec(command=command, timeout=timeout))
+        return _result_payload(result)
+
+    @app.tool(description=_code_execute_description(provider, context, server_modules=server_modules))
+    def code_execute(
+        code: Annotated[
+            str,
+            Field(
+                description=(
+                    "Python source code to write into the sandbox scratch directory and execute. "
+                    "Import generated tools from tools.<server>."
+                )
+            ),
+        ],
+        filename: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Optional relative .py path in scratch. Leave null to use <hash>.py."
+                )
+            ),
+        ] = None,
+        args: Annotated[
+            list[str] | None,
+            Field(
+                description=(
+                    "Optional command-line arguments passed as sys.argv[1:]. "
+                    "Leave null for no arguments."
+                )
+            ),
+        ] = None,
+        timeout: Annotated[
+            int | None,
+            Field(description="Optional script timeout in seconds. Omit to use the server default."),
+        ] = None,
+    ) -> dict[str, Any]:
+        filename = filename if filename is not None else _content_addressed_script_filename(code)
+        guest_script = provider.write_file(filename, code)
+        command = provider.python_script_command(guest_script, args or [])
+        result = provider.run(SandboxExec(command=command, timeout=timeout))
+        payload = _result_payload(result)
+        payload["script"] = guest_script
+        payload["guest_script"] = guest_script
+        return payload
+
+    return app
+
+
+def _mcp_instructions(
+    provider: SandboxProvider,
+    context: SandboxContext,
+    *,
+    server_modules: list[str] | None = None,
+) -> str:
+    return _render_model_text("serve_mcp_instructions.j2", provider, context, server_modules=server_modules)
+
+
+def _bash_description(
+    provider: SandboxProvider,
+    context: SandboxContext,
+    *,
+    server_modules: list[str] | None = None,
+) -> str:
+    return _render_model_text("bash_description.j2", provider, context, server_modules=server_modules)
+
+
+def _code_execute_description(
+    provider: SandboxProvider,
+    context: SandboxContext,
+    *,
+    server_modules: list[str] | None = None,
+) -> str:
+    return _render_model_text("code_execute_description.j2", provider, context, server_modules=server_modules)
+
+
+def _render_model_text(
+    template_name: str,
+    provider: SandboxProvider,
+    context: SandboxContext,
+    *,
+    server_modules: list[str] | None = None,
+) -> str:
+    wrapper_root = _guest_tools_root(provider)
+    return _TEMPLATES.get_template(template_name).render(
+        server_modules=server_modules if server_modules is not None else _server_modules(context.workspace),
+        wrapper_root=wrapper_root,
+    ).strip()
+
+
+def _server_modules(workspace: Path) -> list[str]:
+    server_root = workspace / "tools"
+    return sorted(
+        path.name
+        for path in server_root.iterdir()
+        if path.is_dir() and (path / "__init__.py").exists()
+    ) if server_root.exists() else []
+
+
+def _guest_tools_root(provider: SandboxProvider) -> str:
+    return f"{provider.guest_workspace.rstrip('/')}/tools"
+
+
+def _clean_local_sdk(workspace: Path, *, clean: bool) -> None:
+    if not clean:
+        return
+    for path in [workspace / "tools", workspace / "manifest.json", workspace / "pyproject.toml"]:
+        if path.is_dir():
+            import shutil
+
+            shutil.rmtree(path)
+        elif path.exists():
+            path.unlink()
+
+
+def _content_addressed_script_filename(code: str) -> str:
+    digest = hashlib.sha256(code.encode("utf-8")).hexdigest()[:16]
+    return f"{digest}.py"
+
+
+def _default_gateway_host() -> str:
+    return "127.0.0.1"
+
+
+def _normalize_provider(provider: str) -> str:
+    return provider.replace("_", "-").lower()
+
+
+def _matchlock_gateway_ip(
+    configured_ip: str | None,
+    *,
+    managed_gateway: bool,
+    gateway_file: Path,
+) -> str | None:
+    if configured_ip:
+        return configured_ip
+    if managed_gateway:
+        return DEFAULT_MATCHLOCK_GATEWAY_IP
+    try:
+        gateway = GatewayInfo.from_file(gateway_file)
+    except Exception:
+        return None
+    host = _url_host(gateway.url)
+    if host == DEFAULT_MATCHLOCK_GATEWAY_IP:
+        return DEFAULT_MATCHLOCK_GATEWAY_IP
+    return None
+
+
+def _docker_gateway_ip(
+    configured_ip: str | None,
+    *,
+    managed_gateway: bool,
+    docker_binary: str,
+    docker_network: str | None,
+) -> str | None:
+    if configured_ip:
+        return configured_ip
+    if not managed_gateway:
+        return None
+    if _is_docker_desktop(docker_binary):
+        return None
+    detected_ip = _detect_docker_gateway_ip(docker_binary, docker_network)
+    if detected_ip:
+        return detected_ip
+    network = docker_network or "bridge"
+    raise ValueError(
+        f"could not detect Docker gateway IP for network {network!r}; "
+        "pass --docker-gateway-ip explicitly"
+    )
+
+
+def _is_docker_desktop(docker_binary: str) -> bool:
+    if not sys.platform.startswith("linux"):
+        return True
+    try:
+        completed = subprocess.run(
+            [docker_binary, "info", "--format", "{{.OperatingSystem}}"],
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+            check=False,
+        )
+    except Exception:
+        return False
+    if completed.returncode != 0:
+        return False
+    return "docker desktop" in completed.stdout.strip().lower()
+
+
+def _detect_docker_gateway_ip(docker_binary: str, docker_network: str | None) -> str | None:
+    network = docker_network or "bridge"
+    try:
+        completed = subprocess.run(
+            [docker_binary, "network", "inspect", network],
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=5,
+            check=False,
+        )
+    except Exception:
+        return None
+    if completed.returncode != 0:
+        return None
+    try:
+        networks = json.loads(completed.stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(networks, list) or not networks or not isinstance(networks[0], dict):
+        return None
+    ipam = networks[0].get("IPAM")
+    configs = ipam.get("Config") if isinstance(ipam, dict) else None
+    if not isinstance(configs, list):
+        return None
+    for config in configs:
+        if not isinstance(config, dict):
+            continue
+        gateway = config.get("Gateway")
+        if isinstance(gateway, str) and gateway and "." in gateway:
+            return gateway
+    return None
+
+
+def _gateway_extra_hosts(
+    provider: str,
+    *,
+    docker_gateway_ip: str | None,
+    matchlock_gateway_ip: str | None,
+    explicit_gateway_host: str | None,
+) -> tuple[str, ...]:
+    gateway_ip = _provider_gateway_ip(provider, docker_gateway_ip, matchlock_gateway_ip)
+    if not gateway_ip:
+        return ()
+    if explicit_gateway_host and explicit_gateway_host not in {"127.0.0.1", "localhost", "::1"}:
+        return ()
+    return (gateway_ip,)
+
+
+def _gateway_freebind_hosts(
+    gateway_host: str,
+    *,
+    extra_hosts: tuple[str, ...],
+    docker_gateway_ip: str | None,
+    matchlock_gateway_ip: str | None,
+) -> tuple[str, ...]:
+    hosts = list(extra_hosts)
+    if gateway_host in {docker_gateway_ip, matchlock_gateway_ip}:
+        hosts.append(gateway_host)
+    return tuple(dict.fromkeys(hosts))
+
+
+def _provider_gateway_ip(
+    provider: str,
+    docker_gateway_ip: str | None,
+    matchlock_gateway_ip: str | None,
+) -> str | None:
+    if provider == "docker":
+        return docker_gateway_ip
+    if provider == "matchlock":
+        return matchlock_gateway_ip
+    return None
+
+
+def _url_host(url: str) -> str | None:
+    from urllib.parse import urlsplit
+
+    return urlsplit(url).hostname
+
+
+def _result_payload(result: SandboxRunResult) -> dict[str, Any]:
+    return {
+        "ok": result.ok,
+        "exit_code": result.exit_code,
+        "stdout": result.stdout,
+        "stderr": result.stderr,
+    }

maco/templates/bash_description.j2

@@ -0,0 +1,8 @@
+Run a non-interactive shell command in the sandbox.
+
+Use this to inspect generated tool files, search for available tool exports, or run small shell/Python probes before using code_execute.
+
+Useful discovery commands:
+  rg --files {{ wrapper_root }}
+  fd . {{ wrapper_root }} -t f
+  rg "^def " {{ wrapper_root }}/<server>

maco/templates/code_execute_description.j2

@@ -0,0 +1,14 @@
+Run Python code in the sandbox. Use this for multi-step MCP work, loops, filtering, joins, or structured output.
+
+For most tasks, pass only the code argument. If filename is omitted, maco writes the code to a deterministic content-addressed path like <hash>.py under the writable scratch directory. Use filename only when a readable traceback path or stable named script matters. Use args only when the script explicitly reads command-line arguments.
+
+Import generated tools with:
+  from tools.<server> import <tool>
+
+{% include "server_catalog.j2" %}
+
+Inspect wrapper code at:
+  {{ wrapper_root }}/<server>/__init__.py
+  {{ wrapper_root }}/<server>/<tool>.py
+
+Use the bash tool with rg/fd for discovery before writing code when needed.

maco/templates/codegen/client.py.j2

@@ -0,0 +1,104 @@
+# This file is automatically generated by maco. Do not edit.
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+_CURRENT_DIR = Path(__file__).resolve().parent
+_WORKSPACE_DIR = _CURRENT_DIR.parent
+
+
+def call_mcp_tool(
+    server_name: str,
+    tool_name: str,
+    arguments: dict[str, Any] | None = None,
+    *,
+    timeout: float | None = 60.0,
+) -> Any:
+    """Call an MCP tool through a running maco gateway.
+
+    The gateway is discovered from MACO_GATEWAY_URL or from gateway.json in the
+    generated workspace. Structured MCP output is returned directly when
+    available; otherwise text content is returned, with a best-effort JSON parse.
+    """
+
+    gateway = _load_gateway()
+    url = gateway.get("url")
+    if not url:
+        raise RuntimeError(
+            "maco gateway URL is not configured. Start `maco serve` and run code with `maco run`, "
+            "or set MACO_GATEWAY_URL."
+        )
+
+    payload = json.dumps(
+        {
+            "server": server_name,
+            "tool": tool_name,
+            "arguments": arguments or {},
+        }
+    ).encode("utf-8")
+    headers = {"Content-Type": "application/json"}
+    token = os.environ.get("MACO_GATEWAY_TOKEN") or gateway.get("token")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    request = Request(url, data=payload, headers=headers, method="POST")
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            raw = response.read().decode("utf-8")
+    except HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"MCP tool {server_name}.{tool_name} failed: HTTP {exc.code}: {detail}") from exc
+    except URLError as exc:
+        raise RuntimeError(f"failed to connect to maco gateway at {url}: {exc}") from exc
+
+    result = json.loads(raw)
+    if result.get("isError"):
+        raise RuntimeError(f"MCP tool {server_name}.{tool_name} returned an error: {_content_text(result)}")
+    if "structuredContent" in result:
+        return result["structuredContent"]
+    text = _content_text(result)
+    try:
+        return json.loads(text)
+    except Exception:
+        return text
+
+
+def _load_gateway() -> dict[str, Any]:
+    gateway: dict[str, Any] = {}
+    gateway_file = os.environ.get("MACO_GATEWAY_FILE")
+    if gateway_file:
+        gateway.update(_read_json(Path(gateway_file)))
+    else:
+        gateway.update(_read_json(_WORKSPACE_DIR / "gateway.json"))
+    if os.environ.get("MACO_GATEWAY_URL"):
+        gateway["url"] = os.environ["MACO_GATEWAY_URL"]
+    if os.environ.get("MACO_GATEWAY_TOKEN"):
+        gateway["token"] = os.environ["MACO_GATEWAY_TOKEN"]
+    return gateway
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return {}
+
+
+def _content_text(result: dict[str, Any]) -> str:
+    parts: list[str] = []
+    for block in result.get("content") or []:
+        if isinstance(block, dict) and block.get("type") == "text":
+            parts.append(str(block.get("text", "")))
+        elif isinstance(block, dict):
+            parts.append(json.dumps(block, sort_keys=True))
+        else:
+            parts.append(str(block))
+    return "".join(parts)
+

maco/templates/codegen/model.py.j2

@@ -0,0 +1,6 @@
+class {{ class_name }}(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra='allow')
+
+{% for field in fields %}
+    {{ field.name }}: {{ field.type_expr }} = {{ field.field_args }}
+{% endfor %}

maco/templates/codegen/package_init.py.j2

@@ -0,0 +1,2 @@
+"""{{ docstring }}"""
+

maco/templates/codegen/pyproject.toml.j2

@@ -0,0 +1,8 @@
+[project]
+name = "maco-generated-workspace"
+version = "0.0.0"
+requires-python = ">=3.11"
+dependencies = [
+  "pydantic>=2.0",
+]
+

maco/templates/codegen/root_model.py.j2

@@ -0,0 +1,3 @@
+class {{ class_name }}(RootModel[{{ type_expr }}]):
+    pass
+

maco/templates/codegen/server_init.py.j2

@@ -0,0 +1,11 @@
+# This file is automatically generated by maco. Do not edit.
+{% for name in exports %}
+from .{{ name }} import {{ name }}
+{% endfor %}
+
+__all__ = [
+{% for name in exports %}
+    {{ name | pyrepr }},
+{% endfor %}
+]
+