mcp-shipyard 0.1.0__tar.gz

mcp_shipyard-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: mcp-shipyard
+Version: 0.1.0
+Summary: Application-independent MCP hosting, payloads, and responses.
+License-Expression: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# MCP Shipyard
+
+Install the `mcp-shipyard` distribution and import `mcp_shipyard`:
+
+```sh
+python -m pip install mcp-shipyard
+shipyard --help
+```
+
+`mcp_shipyard` manages MCP applications independently of their tool set.
+It contains no Exactus, District, Conjure, FastAPI, or Docker imports.
+
+- `models.py`: JSON types, server identity, protocol failures, and outcomes.
+- `payloads.py`: request envelope decoding and validation.
+- `responses.py`: protocol and tool result encoding.
+- `server.py`: negotiation, discovery, authenticated dispatch, and observers.
+- `tools.py`: tool registration and explicit application authorization.
+- `pipelines.py`: pipeline request and executor contracts, and tool adapter.
+- `stdio.py`: bounded newline-delimited transport with caller-owned streams.
+- `environments.py`: approved profiles, enforceable permissions, and disposable
+  worker lifecycle shared by providers.
+- `lease_store.py` and `leases.py`: durable ownership, expiration, serialization,
+  restart recovery contracts and confirmed worker cleanup.
+- `cli.py` and `__main__.py`: explicit application factory and local principal
+  for `python -m mcp_shipyard serve`.
+- `__init__.py`: public API.
+- `features.py`: optional terminal, package-install and resource-relay contracts.
+- `pyproject.toml`: the independently installable `mcp-shipyard` distribution.
+
+Applications supply identity, schemas, handlers, and authorization. Monitoring
+is an injected observer; District can consume those events without becoming
+the MCP application's protocol core. Pipeline adapters own worker selection,
+queues, leases, cancellation, and cleanup. The host never interprets arbitrary
+payload values as executable code. Unexpected application errors propagate;
+only explicitly configured safe error types become MCP tool-error content.
+
+The Exactus adapter in `mcp/exactus_mcp/mcp_server.py` now uses this shared
+host and registry while retaining its existing tool names and permissions.
+Its environment and REST services remain application adapters; importing this
+library never imports or starts them. Observer parameters are transient and
+must be redacted by a monitor before persistence. Stdio adapters do not close
+streams owned by their callers.
+
+Run the independent example from the repository root:
+
+```sh
+python -m mcp_shipyard serve \
+  --application examples.tools.mcp_shipyard.echo:create --principal example-user
+```
+
+The application factory and stdio principal are trusted operator configuration.
+They must never be populated directly from remote request arguments.
+
+Environment callers choose a registered profile and an argv vector. They
+cannot override that profile's network, privilege, package, or exposure policy.
+Providers must enforce both grants and denials before starting a worker.
+The Conjure Docker adapter currently enforces Linux containers, non-root
+execution, dropped capabilities, no privilege escalation, bounded CPU/memory,
+read-only root, private scratch, bounded output and destruction on every exit.
+Network `none` disables guest networking; `internet` enables Docker bridge
+networking, including reachable private destinations. It is not an Internet-only
+firewall. Allow-list egress, privilege grants, managed package installs, resource
+publishing and interactive shell installation are refused by this adapter.
+
+VM providers use the same interface, but no audited Windows or macOS template
+is shipped here. Contract tests for those platform names are not native guest
+execution evidence. A future VM adapter must clone immutable prepared images
+and enforce host-side egress plus guest account policy before advertising those
+capabilities. A shell for a network-isolated guest needs staged artifacts and an
+explicit control channel; enabling arbitrary networking for bootstrap is unsafe.

mcp_shipyard-0.1.0/README.md

@@ -0,0 +1,70 @@
+# MCP Shipyard
+
+Install the `mcp-shipyard` distribution and import `mcp_shipyard`:
+
+```sh
+python -m pip install mcp-shipyard
+shipyard --help
+```
+
+`mcp_shipyard` manages MCP applications independently of their tool set.
+It contains no Exactus, District, Conjure, FastAPI, or Docker imports.
+
+- `models.py`: JSON types, server identity, protocol failures, and outcomes.
+- `payloads.py`: request envelope decoding and validation.
+- `responses.py`: protocol and tool result encoding.
+- `server.py`: negotiation, discovery, authenticated dispatch, and observers.
+- `tools.py`: tool registration and explicit application authorization.
+- `pipelines.py`: pipeline request and executor contracts, and tool adapter.
+- `stdio.py`: bounded newline-delimited transport with caller-owned streams.
+- `environments.py`: approved profiles, enforceable permissions, and disposable
+  worker lifecycle shared by providers.
+- `lease_store.py` and `leases.py`: durable ownership, expiration, serialization,
+  restart recovery contracts and confirmed worker cleanup.
+- `cli.py` and `__main__.py`: explicit application factory and local principal
+  for `python -m mcp_shipyard serve`.
+- `__init__.py`: public API.
+- `features.py`: optional terminal, package-install and resource-relay contracts.
+- `pyproject.toml`: the independently installable `mcp-shipyard` distribution.
+
+Applications supply identity, schemas, handlers, and authorization. Monitoring
+is an injected observer; District can consume those events without becoming
+the MCP application's protocol core. Pipeline adapters own worker selection,
+queues, leases, cancellation, and cleanup. The host never interprets arbitrary
+payload values as executable code. Unexpected application errors propagate;
+only explicitly configured safe error types become MCP tool-error content.
+
+The Exactus adapter in `mcp/exactus_mcp/mcp_server.py` now uses this shared
+host and registry while retaining its existing tool names and permissions.
+Its environment and REST services remain application adapters; importing this
+library never imports or starts them. Observer parameters are transient and
+must be redacted by a monitor before persistence. Stdio adapters do not close
+streams owned by their callers.
+
+Run the independent example from the repository root:
+
+```sh
+python -m mcp_shipyard serve \
+  --application examples.tools.mcp_shipyard.echo:create --principal example-user
+```
+
+The application factory and stdio principal are trusted operator configuration.
+They must never be populated directly from remote request arguments.
+
+Environment callers choose a registered profile and an argv vector. They
+cannot override that profile's network, privilege, package, or exposure policy.
+Providers must enforce both grants and denials before starting a worker.
+The Conjure Docker adapter currently enforces Linux containers, non-root
+execution, dropped capabilities, no privilege escalation, bounded CPU/memory,
+read-only root, private scratch, bounded output and destruction on every exit.
+Network `none` disables guest networking; `internet` enables Docker bridge
+networking, including reachable private destinations. It is not an Internet-only
+firewall. Allow-list egress, privilege grants, managed package installs, resource
+publishing and interactive shell installation are refused by this adapter.
+
+VM providers use the same interface, but no audited Windows or macOS template
+is shipped here. Contract tests for those platform names are not native guest
+execution evidence. A future VM adapter must clone immutable prepared images
+and enforce host-side egress plus guest account policy before advertising those
+capabilities. A shell for a network-isolated guest needs staged artifacts and an
+explicit control channel; enabling arbitrary networking for bootstrap is unsafe.

mcp_shipyard-0.1.0/__init__.py

@@ -0,0 +1,31 @@
+"""Application-independent Model Context Protocol server infrastructure."""
+
+from .environments import (
+    EnvironmentPipeline,
+    EnvironmentProfile,
+    ResourcePolicy,
+)
+from .features import ExtendedEnvironment, TerminalChannel
+from .lease_store import Lease, LeaseStore
+from .leases import EnvironmentLeases, ManagedProvider
+from .models import JsonObject, JsonValue, Outcome, RpcError, ServerIdentity
+from .server import McpServer, RequestEvent
+
+__all__: tuple[str, ...] = (
+    "EnvironmentLeases",
+    "EnvironmentPipeline",
+    "EnvironmentProfile",
+    "ExtendedEnvironment",
+    "JsonObject",
+    "JsonValue",
+    "Lease",
+    "LeaseStore",
+    "ManagedProvider",
+    "McpServer",
+    "Outcome",
+    "RequestEvent",
+    "ResourcePolicy",
+    "RpcError",
+    "ServerIdentity",
+    "TerminalChannel",
+)

mcp_shipyard-0.1.0/__main__.py

@@ -0,0 +1,6 @@
+"""Launch a configured MCP application with ``python -m mcp_shipyard``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcp_shipyard-0.1.0/cli.py

@@ -0,0 +1,85 @@
+"""Launch an operator-selected MCP application over the shared stdio host."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace
+from importlib import import_module
+from re import fullmatch
+from sys import stdin, stdout
+from typing import TYPE_CHECKING, Protocol, cast
+
+from .stdio import serve
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+    from .server import McpServer
+
+
+class ApplicationFactory(Protocol):
+    """Construct an application from trusted launcher configuration."""
+
+    def __call__(self) -> McpServer[str]:
+        """Create a fully configured MCP application.
+
+        Returns:
+            Host, registered tools, authorization, and optional observers.
+
+        """
+        ...
+
+
+def main(arguments: list[str] | None = None) -> int:
+    """Launch a configured application without embedding its tool set.
+
+    The module is operator configuration, never an agent payload. Stdio
+    authority belongs to the launching parent process; HTTP authentication
+    must be supplied by that transport's adapter.
+
+    Args:
+        arguments: Optional command-line argument list.
+
+    Returns:
+        Zero after clean stdin EOF.
+
+    """
+    parser: ArgumentParser = ArgumentParser(description=__doc__)
+    launcher: ArgumentParser = parser.add_subparsers(
+        dest="command",
+        required=True,
+    ).add_parser(name="serve")
+    launcher.add_argument(
+        "--application",
+        required=True,
+        metavar="MODULE:FACTORY",
+        help="Trusted local application factory; never accepted from MCP.",
+    )
+    launcher.add_argument(
+        "--principal",
+        required=True,
+        help="Parent-established identity interpreted by the application.",
+    )
+    parsed: Namespace = parser.parse_args(args=arguments)
+    target: str = parsed.application
+    if (
+        fullmatch(
+            pattern=r"[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*:[A-Za-z_]\w*",
+            string=target,
+        )
+        is None
+    ):
+        parser.error(message="--application must be a local MODULE:FACTORY")
+    module_name: str
+    factory_name: str
+    module_name, _, factory_name = target.partition(":")
+    module: ModuleType = import_module(name=module_name)
+    factory: ApplicationFactory = cast(
+        typ="ApplicationFactory",
+        val=getattr(module, factory_name),
+    )
+    return serve(
+        server=factory(),
+        principal=parsed.principal,
+        reader=stdin.buffer,
+        writer=stdout.buffer,
+    )

mcp_shipyard-0.1.0/environments.py

@@ -0,0 +1,327 @@
+"""Define one fail-closed disposable-environment workflow for every backend.
+
+Profiles and providers are registered by the operator, never constructed from
+agent-supplied capability claims. A provider must implement every requested
+grant and denial. Merely running a command on a host is not sandboxing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+from secrets import token_hex
+from typing import TYPE_CHECKING, Final, Literal, Protocol, final
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from .models import JsonObject, JsonValue
+    from .pipelines import PipelineRequest
+
+type NetworkMode = Literal["none", "internet", "allowlist"]
+type PackageMode = Literal["disabled", "environment", "system"]
+
+
+@final
+class Constants:
+    """Bound agent-controlled command vectors.
+
+    Attributes:
+        max_arguments: Maximum command argument count.
+
+    """
+
+    max_arguments: Final[int] = 256
+
+
+class EnvironmentPolicyError(ValueError):
+    """Reject an unenforceable policy before starting any worker."""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResourcePolicy:
+    """Express grants and denials independently of host and guest OS.
+
+    Package policy applies to the broker's managed installation operation.
+    It does not claim that arbitrary writable code cannot import local files.
+
+    Attributes:
+        network: Egress mode enforced outside agent control.
+        allowed_hosts: Egress destinations when an allow-list is selected.
+        elevation: Whether guest elevation may be offered, never host sudo.
+        packages: Managed package installation scope.
+        expose_resources: Whether authenticated resources may be published.
+        timeout_seconds: Maximum pipeline command lifetime.
+
+    """
+
+    network: NetworkMode = "none"
+    allowed_hosts: tuple[str, ...] = ()
+    elevation: bool = False
+    packages: PackageMode = "disabled"
+    expose_resources: bool = False
+    timeout_seconds: float = 300.0
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous and unbounded security requests.
+
+        Raises:
+            EnvironmentPolicyError: When policy dimensions are inconsistent.
+
+        """
+        if (
+            type(self.elevation) is not bool
+            or type(self.expose_resources) is not bool
+            or isinstance(self.timeout_seconds, bool)
+            or self.network not in ("none", "internet", "allowlist")
+            or self.packages not in ("disabled", "environment", "system")
+            or not isfinite(self.timeout_seconds)
+            or self.timeout_seconds <= 0
+            or bool(self.allowed_hosts) != (self.network == "allowlist")
+            or any(not host or "\x00" in host for host in self.allowed_hosts)
+        ):
+            msg: str = "Invalid disposable environment policy"
+            raise EnvironmentPolicyError(msg)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RuntimeCapabilities:
+    """Declare policy combinations a trusted provider can enforce.
+
+    These declarations belong to audited provider implementations, not to
+    clients or unverified image metadata. Denying a capability is itself a
+    capability: a VM with default administrator credentials cannot claim
+    ``elevation_modes={False}``.
+
+    Attributes:
+        isolated: Whether this is a real disposable isolation boundary.
+        platforms: Supported guest OS identifiers.
+        network_modes: Egress modes this provider enforces.
+        elevation_modes: Guest privilege modes this provider enforces.
+        package_modes: Managed package installation modes.
+        exposure_modes: Whether resources may be published.
+        supports_district_shell: Whether a scoped shell can be installed.
+
+    """
+
+    isolated: bool
+    platforms: frozenset[str]
+    network_modes: frozenset[NetworkMode]
+    elevation_modes: frozenset[bool]
+    package_modes: frozenset[PackageMode]
+    exposure_modes: frozenset[bool]
+    supports_district_shell: bool = False
+
+    def require(self, *, profile: EnvironmentProfile) -> None:
+        """Refuse unsupported grants and denials before worker creation.
+
+        Args:
+            profile: Operator-approved environment configuration.
+
+        Raises:
+            EnvironmentPolicyError: When any requested dimension is missing.
+
+        """
+        policy: ResourcePolicy = profile.policy
+        if not (
+            self.isolated
+            and profile.platform in self.platforms
+            and policy.network in self.network_modes
+            and policy.elevation in self.elevation_modes
+            and policy.packages in self.package_modes
+            and policy.expose_resources in self.exposure_modes
+            and (not profile.district_shell or self.supports_district_shell)
+        ):
+            msg: str = "Provider cannot enforce the complete requested policy"
+            raise EnvironmentPolicyError(msg)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class EnvironmentProfile:
+    """Select one operator-approved template and security policy.
+
+    Attributes:
+        provider: Registered driver identifier.
+        template: Immutable prepared image or snapshot identifier.
+        platform: Guest OS identifier understood by the driver.
+        policy: Explicit resource policy.
+        district_shell: Whether to install an environment-scoped shell.
+
+    """
+
+    provider: str
+    template: str
+    platform: str
+    policy: ResourcePolicy = ResourcePolicy()
+    district_shell: bool = False
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class EnvironmentCommandResult:
+    """Return a command result without prescribing a transport.
+
+    Attributes:
+        exit_code: Actual guest command exit status.
+        stdout: Bounded command output.
+        stderr: Bounded diagnostic output.
+
+    """
+
+    exit_code: int
+    stdout: str
+    stderr: str
+
+
+class DisposableEnvironment(Protocol):
+    """Own one disposable worker and its full cleanup lifecycle."""
+
+    def run(
+        self,
+        *,
+        argv: tuple[str, ...],
+        timeout_seconds: float,
+    ) -> EnvironmentCommandResult:
+        """Execute argv without implicit shell interpolation.
+
+        Args:
+            argv: Guest command vector.
+            timeout_seconds: Command deadline enforced by the provider.
+
+        Returns:
+            Real command status and bounded output.
+
+        """
+        ...
+
+    def install_shell(self) -> None:
+        """Install the approved shell using scoped bootstrap credentials."""
+        ...
+
+    def close(self) -> None:
+        """Destroy only this disposable worker and its owned scratch data.
+
+        Providers must make this idempotent and preserve immutable templates.
+        """
+        ...
+
+
+class EnvironmentProvider(Protocol):
+    """Provide OS-specific isolation behind the same lifecycle contract."""
+
+    @property
+    def capabilities(self) -> RuntimeCapabilities:
+        """Describe policy combinations this driver actually enforces.
+
+        Returns:
+            Trusted runtime capabilities.
+
+        """
+        ...
+
+    def create(
+        self,
+        *,
+        name: str,
+        profile: EnvironmentProfile,
+    ) -> DisposableEnvironment:
+        """Create a disposable clone, cleaning up partial failures itself.
+
+        Args:
+            name: Unique name generated by the host, never supplied by agents.
+            profile: Validated operator-approved template and policy.
+
+        Returns:
+            Started worker whose lifecycle belongs to the caller.
+
+        """
+        ...
+
+
+class EnvironmentPipeline[Identity]:
+    """Use one workflow for Docker and every registered VM guest OS."""
+
+    def __init__(
+        self,
+        *,
+        profiles: Mapping[str, EnvironmentProfile],
+        providers: Mapping[str, EnvironmentProvider],
+    ) -> None:
+        """Freeze the operator's approved environment catalog.
+
+        Args:
+            profiles: Agent-selectable names mapped to approved policies.
+            providers: Trusted implementations, such as Conjure adapters.
+
+        """
+        self._profiles: dict[str, EnvironmentProfile] = dict(profiles)
+        self._providers: dict[str, EnvironmentProvider] = dict(providers)
+
+    def execute(self, *, request: PipelineRequest[Identity]) -> JsonObject:
+        """Validate, clone, optionally install a shell, execute, and destroy.
+
+        Args:
+            request: Authorized tool payload with ``profile`` and ``argv``.
+                Client-supplied policy overrides are rejected.
+
+        Returns:
+            Command outcome after required cleanup has completed.
+
+        Raises:
+            EnvironmentPolicyError: When the request or policy is unsafe.
+            BaseExceptionGroup: When both execution and cleanup fail.
+
+        """
+        name: JsonValue = request.payload.get("profile")
+        raw: JsonValue = request.payload.get("argv")
+        if (
+            not isinstance(name, str)
+            or name not in self._profiles
+            or not isinstance(raw, list)
+            or not raw
+            or len(raw) > Constants.max_arguments
+            or any(not isinstance(arg, str) or "\x00" in arg for arg in raw)
+            or set(request.payload) - {"profile", "argv"}
+        ):
+            msg: str = "Expected an approved profile and a safe argv vector"
+            raise EnvironmentPolicyError(msg)
+        argv: tuple[str, ...] = tuple(
+            arg for arg in raw if isinstance(arg, str)
+        )
+        profile: EnvironmentProfile = self._profiles[name]
+        provider: EnvironmentProvider | None = self._providers.get(
+            profile.provider,
+        )
+        if provider is None:
+            msg = "Environment provider is not registered"
+            raise EnvironmentPolicyError(msg)
+        provider.capabilities.require(profile=profile)
+        environment: DisposableEnvironment = provider.create(
+            name=f"mcp-{token_hex(nbytes=12)}",
+            profile=profile,
+        )
+        result: EnvironmentCommandResult
+        try:
+            if profile.district_shell:
+                environment.install_shell()
+            result = environment.run(
+                argv=argv,
+                timeout_seconds=profile.policy.timeout_seconds,
+            )
+        except BaseException as primary:
+            try:
+                environment.close()
+            except (OSError, RuntimeError, ValueError) as cleanup:
+                msg = "Environment execution and cleanup failed"
+                raise BaseExceptionGroup(
+                    msg,
+                    [primary, cleanup],
+                ) from None
+            raise
+        environment.close()
+        return {
+            "exit_code": result.exit_code,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+            "provider": profile.provider,
+            "platform": profile.platform,
+        }

mcp_shipyard-0.1.0/features.py

@@ -0,0 +1,98 @@
+"""Describe optional guest operations without depending on a VM backend."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from .environments import DisposableEnvironment
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from .environments import EnvironmentCommandResult
+    from .models import JsonObject
+
+
+class TerminalChannel(Protocol):
+    """Own a bounded terminal stream until the environment is destroyed."""
+
+    def read(self, *, maximum: int = 65536) -> bytes:
+        """Read one bounded chunk, returning empty bytes at EOF.
+
+        Args:
+            maximum: Maximum bytes returned by one read.
+
+        Returns:
+            Terminal output bytes.
+
+        """
+        ...
+
+    def write(self, *, data: bytes) -> None:
+        """Write bounded terminal input without interpreting it on the host.
+
+        Args:
+            data: Raw input for the guest terminal.
+
+        """
+        ...
+
+    def close(self) -> None:
+        """Stop and reap the owned control process."""
+        ...
+
+
+@runtime_checkable
+class ExtendedEnvironment(DisposableEnvironment, Protocol):
+    """Provide optional operations within the same isolation boundary."""
+
+    def open_terminal(self) -> TerminalChannel:
+        """Open a guest terminal without enabling guest Internet access.
+
+        Returns:
+            Owned byte stream; closing its lease destroys all guest children.
+
+        """
+        ...
+
+    def install_packages(
+        self,
+        *,
+        wheels: tuple[Path, ...],
+        system: bool,
+    ) -> EnvironmentCommandResult:
+        """Install only staged, approved wheel artifacts without index access.
+
+        Args:
+            wheels: Verified local wheel copies selected by the broker.
+            system: Whether an explicit guest system-package grant applies.
+
+        Returns:
+            Actual offline pip outcome.
+
+        """
+        ...
+
+    def request_resource(
+        self,
+        *,
+        port: int,
+        method: str,
+        path: str,
+        body: bytes,
+        content_type: str,
+    ) -> JsonObject:
+        """Relay bounded HTTP to guest loopback without opening a host port.
+
+        Args:
+            port: Operator-approved guest service port.
+            method: Allowed HTTP method.
+            path: Relative HTTP request target.
+            body: Bounded request body.
+            content_type: Validated request media type.
+
+        Returns:
+            Bounded response status, headers and base64 content.
+
+        """
+        ...