Metadata-Version: 2.4
Name: mcp-host-agent
Version: 1.0.1
Summary: Host-level deployment and supervision agent for the MCP Worker platform: manage local Worker services (git/pip/systemd/launchd), health polling, heartbeat aggregation, and self-healing.
Author: Mavis AI Platform
License: Apache-2.0
Keywords: mcp,host-agent,worker,deployment,supervision,self-healing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp-worker-protocol>=1.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.23.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# mcp-host-agent

Host-level deployment and supervision agent for the MCP Worker platform.

Installed once per host, `mcp-host-agent` manages the local Worker services end
to end: deployment (git clone/pull + dependency install), health polling,
heartbeat aggregation to the Hub, crash self-healing, and the Hub-facing
control endpoints.

## Installation

```bash
pip install mcp-host-agent
```

Requires Python 3.10+.

## Quick start

```bash
# 1. Write the agent configuration (see below).
# 2. Validate it and run the control API.
mcp-host-agent run --config /etc/mavis/agent.yaml
```

## Configuration

The agent is driven by a single `agent.yaml` file:

```yaml
hub_url: "https://hub.example.com"
agent_id: "agent-example"
jwt_token: "<jwt>"
agent_token: "<agent-token>"   # optional; required for control endpoints

platform: linux                # linux | macos
agent_port: 9200               # control API port (default 9200)

workers:
  - name: demo-worker
    repo: "https://git.example.com/owner/demo-worker.git"
    branch: main
    port: 9101
    python: "3.11"
    auto_restart: true
    max_restart: 3
```

## How it works

- **Deployment** — clones/pulls each worker repo into the working directory and
  manages it as a `systemd` (Linux) or `launchd` (macOS) service.
- **Supervision** — polls each worker's process state and `/health` endpoint,
  derives its status, and aggregates everything into an `AgentHeartbeat`.
- **Self-healing** — applies a decision tree (restart → rollback → give up) and
  escalates unrecoverable failures to the Hub orchestrator.
- **Control plane** — exposes `/health`, `/meta`, and authenticated
  `/api/v1/agent/*` endpoints for the Hub orchestrator.

## Supported platforms

| Platform | Runner |
|----------|--------|
| Linux | systemd |
| macOS | launchd |

Windows is not supported in v1. The agent does not self-heal containers
(Docker/K3s pods are managed by their own orchestrators); it manages native
host processes only.

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

Apache-2.0. See `LICENSE`.
