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.
