# masaro-infra-mcp

Sicherer MCP Server für **Masaro Media** / **Masaro Cloud**. Kapselt Infrastruktur-Aktionen gegen Cloudflare und Coolify zentral und gibt KI-Clients nur kontrollierten, read-only Zugriff.

## Features

- 19 read-only MCP Tools für Cloudflare, Coolify, InternetX, Diagnose und Validierung
- Multi-Source Cloudflare Tunnel-Erkennung (API + DNS + Teamnet)
- Diagnose-Tools: `cloudflare_test_connection`, `coolify_test_connection`
- Umgebungsvalidierung: `infra_validate_environment`
- Automatische API-Versionserkennung (Coolify) und Retry-Logik (HTTP)
- Strikte Sicherheitsregeln (keine Schreibaktionen)
- Secrets nur über Environment Variables
- Automatische Redaktion sensibler Werte in Logs
- Docker- und docker-compose-Support
- Vollständige API-Dokumentation: [docs/api-matrix.md](./docs/api-matrix.md)

## Voraussetzungen

- Node.js 22+
- Cloudflare API Token (read-only empfohlen)
- Coolify API Token
- Zugriff auf die Masaro Cloudflare Zone und den Coolify-Instanz-Endpoint

## Schnellstart (lokal)

```bash
cp .env.example .env
# .env mit echten Werten füllen — niemals committen

npm install
npm run dev
```

Produktionsstart:

```bash
npm run build
npm start
```

## Cursor / MCP Client Konfiguration

Beispiel für `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "masaro-infra-mcp": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/masaro-infra-mcp/dist/index.js"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "…",
        "CLOUDFLARE_ACCOUNT_ID": "…",
        "CLOUDFLARE_ZONE_ID": "…",
        "COOLIFY_API_URL": "https://coolify.example.com",
        "COOLIFY_API_TOKEN": "…",
        "MASARO_CLOUD_DOMAIN": "masaro.cloud",
        "MCP_ALLOW_WRITES": "false"
      }
    }
  }
}
```

Alternativ mit `tsx` während der Entwicklung:

```json
{
  "mcpServers": {
    "masaro-infra-mcp": {
      "command": "npx",
      "args": ["tsx", "/absoluter/pfad/zu/masaro-infra-mcp/src/index.ts"],
      "env": { "...": "..." }
    }
  }
}
```

## Docker

```bash
cp .env.example .env
docker compose build
docker compose up
```

Der Container läuft als nicht-root User `mcp`. Secrets werden über `.env` oder die Shell-Umgebung injiziert.

## Umgebungsvariablen

| Variable | Beschreibung | Standard |
|---|---|---|
| `CLOUDFLARE_API_TOKEN` | Cloudflare API Bearer Token | *erforderlich* |
| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare Account ID | *erforderlich* |
| `CLOUDFLARE_ZONE_ID` | Standard-Zone für DNS/Zone-Tools | *erforderlich* |
| `COOLIFY_API_URL` | Basis-URL der Coolify-Instanz | *erforderlich* |
| `COOLIFY_API_TOKEN` | Coolify API Token | *erforderlich* |
| `MASARO_CLOUD_DOMAIN` | Primäre Masaro-Domain | `masaro.cloud` |
| `MCP_ALLOW_WRITES` | Schreibende Tools aktivieren (v2) | `false` |

## Verfügbare Tools

Siehe [docs/tools.md](./docs/tools.md) und [docs/api-matrix.md](./docs/api-matrix.md).

**Diagnose starten:**

```bash
npm run build
# Dann über MCP-Client die Tools aufrufen:
# cloudflare_test_connection
# coolify_test_connection
# infra_validate_environment
```

## Sicherheit

Siehe [docs/security.md](./docs/security.md).

**Wichtig:** Committen Sie niemals `.env`-Dateien oder API-Tokens.

## Roadmap (v2)

Schreibende Tools sind vorbereitet, aber noch nicht implementiert:

- `cloudflare_create_dns_record`
- `cloudflare_create_tunnel_route`
- `cloudflare_create_access_app`
- `coolify_create_project`
- `coolify_create_application`
- `coolify_trigger_deployment`
- `coolify_set_environment_variable`

## Lizenz

Proprietär — Masaro Media.