# appbyggaren-mcp

An MCP server that lets an agent publish small static web apps: source into
[Gitea](https://about.gitea.com/), build and TLS via [Coolify](https://coolify.io/).
Five verbs, hard boundaries.

Built to give a household assistant a "mini Lovable" — *"build me a page that
counts down to the summer holidays"* — without giving it the keys to the PaaS.

## Why it exists

Coolify's own MCP server is read-only, and its API tokens are **instance-wide
capabilities** (`read` / `write` / `deploy` / `root`) with no per-project scoping.
Handing that token to a model means handing it every application on the instance,
including the ones you care about.

This server sits in between. It holds the write credentials; the model gets five
verbs that cannot express anything outside the configured project, organisation
and domain. The asymmetry is the whole design.

## Tools

| Tool | Does |
|------|------|
| `list_apps` | Apps published by this server, with status and URL |
| `get_app` | Status, URL and repository for one app |
| `create_app` | Create repo, push files, create the Coolify app, deploy |
| `update_app` | Replace files and redeploy |
| `get_deploy_logs` | Last deployment log — for when a build fails |
| `delete_app` | Remove the app; keeps the repo unless asked otherwise |

Apps are static sites served by nginx: HTML, CSS and client-side JS. No
server-side runtime, no database.

## Boundaries

Enforced in [`guards.py`](src/appbyggaren_mcp/guards.py), on every mutating call:

- **Project** — an application's project UUID is re-checked against the configured
  one before it can be touched. The UUID is the only thing the caller supplies, so
  it is never trusted.
- **Domain** — publishing is limited to `<name>.<APPBYGGAREN_DOMAIN_SUFFIX>`. An app
  re-pointed elsewhere in the Coolify UI drops out of scope and becomes immutable here.
- **Organisation** — repositories are only created under `GITEA_ORG`.
- **Names** — `^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$`, with a reserved list. The slug
  becomes a DNS label, a repo name and a container name, so it must survive all three.
- **Payload** — max 40 files, 2 MB total, `index.html` required, and paths are
  normalised to reject traversal. Gitea's contents API takes the path verbatim, so
  `../` would otherwise escape the repository.

## Configuration

All via environment variables — see [`.env.example`](.env.example). The Coolify,
Gitea and domain settings are required; everything else is optional.

Nothing about a particular deployment is baked into the source. Which hostnames
are already taken, which domains count as internal, and which names are worth
flagging are all properties of *your* installation — hard-coding them here would
publish your DNS layout to anyone reading the repository.

| Variable | Effect when unset |
|----------|-------------------|
| `APPBYGGAREN_RESERVED_NAMES` | Only the generic baseline is reserved |
| `APPBYGGAREN_INTERNAL_DOMAINS` | The internal-hostname check does not run |
| `APPBYGGAREN_PII_NAMES` | No names are flagged |
| `CLOUDFLARE_ACCESS_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` | `publish_app` refuses, with a message saying why |

### The content scan is a filter, not a judgement

`publish_app` refuses when it finds personal numbers, email addresses, phone
numbers, private IPs, secrets, or anything you listed above. It will not notice
that "countdown to our holiday, 14 July" says when a house will be empty. Read
what the app actually says before publishing it.

## Install

```bash
uv venv .venv && uv pip install --python .venv/bin/python .
.venv/bin/appbyggaren-mcp          # stdio transport
```

Register with an MCP client (example: Hermes Agent):

```bash
hermes mcp add appbyggaren --command /opt/appbyggaren-mcp/.venv/bin/appbyggaren-mcp
```

If your client passes no environment to stdio children, reference the variables as
`${VAR}` placeholders in its config rather than inlining secrets.

## Known Coolify quirks

**`/applications/public` truncates the git URL.** It stores only `owner/repo` and
leaves `git_full_url`, `source_type` and `source_id` null, assuming a hosted
provider. A self-hosted Gitea URL then never clones — and the failure is silent:
HTTP 201, no deployment recorded, no container, status `exited:unhealthy`, no error
anywhere. This server issues a `PATCH` with the full `.git` URL immediately after
creation and refuses to deploy if the stored value still looks truncated.

**Certificates lag the deploy.** Traefik requests the certificate when the router
appears, so the first seconds after publishing serve `TRAEFIK DEFAULT CERT`. That is
not a failure; it resolves on its own.

## Development

```bash
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/pytest
.venv/bin/ruff check .
```

## Licence

MIT