<div align="center">

# Mac Build Bridge

**Give your AI agent a bridge to your Mac's iOS builds.**

Operate a dedicated Mac from your terminal or MCP client.
Build Flutter and native Xcode apps through your own GitHub Actions runners.

[![Checks](https://github.com/mehiel-victor/mac-build-bridge/actions/workflows/validate.yml/badge.svg)](https://github.com/mehiel-victor/mac-build-bridge/actions/workflows/validate.yml)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/mehiel-victor/mac-build-bridge?style=social)](https://github.com/mehiel-victor/mac-build-bridge/stargazers)

[Quick start](#quick-start) · [MCP setup](docs/mcp.md) · [Contribute](CONTRIBUTING.md) · [Português](docs/README.pt-BR.md)

</div>

```text
Your terminal / MCP client (Linux or macOS)
                 |
         Mac Build Bridge
          /             \
   SSH health check   GitHub Actions
          |             |
          +--- Your Mac + Xcode ---+
                        |
                Build artifacts
```

## Why it exists

You already have a Mac. Let your coding agent check it, start an approved build,
and find the result without handing it a shell or your signing credentials.
Mac Build Bridge combines a reusable iOS workstation toolkit with a local MCP server
and CLI. App repositories keep their workflows, signing secrets and release policy.

## Quick start

Requires Python 3.11+. Try the synthetic demo without a Mac or credentials:

```sh
git clone https://github.com/mehiel-victor/mac-build-bridge.git
cd mac-build-bridge
python3 -m venv .venv
. .venv/bin/activate
pip install .
mac-build-bridge demo
```

For real operations, install and authenticate [GitHub CLI](https://cli.github.com/),
copy `examples/config.json` to `~/.config/mac-build-bridge/config.json`, and edit the
target repository, workflow and ref. Then:

```sh
mac-build-bridge runs example-app
mac-build-bridge artifacts example-app RUN_ID
mac-build-bridge serve
```

Builds require a Mac with Xcode and a registered runner. Follow [Mac setup](docs/mac-setup.md)
and [app onboarding](docs/app-onboarding.md). For SSH checks, configure your SSH key
locally, verify the host fingerprint, then run `mac-build-bridge status`.

## Ask your agent

> Check my Mac's readiness, list recent builds for example-app, and find the artifacts of the latest successful run.

The MCP exposes `workstation_status`, `list_builds`, and `list_artifacts` by default.
Set `enable_dispatch` to `true` and restart the MCP to expose `start_build`.
Dispatch uses the repository, workflow and ref from your local allowlist.
See [MCP configuration](docs/mcp.md) for the standard JSON configuration.

## Included

| Component | What it does |
| --- | --- |
| MCP + CLI | Check health, inspect builds/artifacts, opt into dispatch |
| Mac toolkit | Bootstrap and verify a dedicated Xcode host |
| Runner installer | Verify download digest and register one runner per app |
| Composite Action | Compile Flutter/Xcode, with unsigned or temporary signed builds |
| Agent skill | Guide workstation diagnosis and build operations |

## Status and boundaries

**v0.1.0 is an alpha.** Linux checks cover mocked build paths and a real MCP stdio
handshake. A real Mac build and signing cleanup have not been validated for this release.
The demo is synthetic. Windows support is unverified. Xcode still runs on macOS.
The MCP returns artifact metadata, not downloads or raw build logs.

Repository runner registrations separate GitHub credentials; they do not sandbox
jobs sharing one macOS user. Use dedicated hosts/users for different trust domains.
Never run untrusted pull-request code on this Mac. Dispatch can trigger any side
effects in an allowlisted workflow; configure build-only workflows.
See [security boundaries](SECURITY.md). There is no App Store publishing tool.

## Help build it

Start with [Contributing](CONTRIBUTING.md), [the roadmap](ROADMAP.md), or
[good first issues](https://github.com/mehiel-victor/mac-build-bridge/labels/good%20first%20issue).
Useful contributions include real Mac validation, Flutter fixtures, and onboarding improvements.
If this saves you time, star the repository and share your setup in Discussions.

MIT licensed. Independent community project; not affiliated with Apple, GitHub or MCP vendors.