# gamma31

MCP-Server für die [Gamma.app](https://gamma.app) API — erstellt Präsentationen, Dokumente, Social Posts und Webseiten über KI-Agenten.

Basiert auf [FastMCP 3.x](https://gofastmcp.com/) mit Session State, Elicitation, Tool Timeouts und Tags.

## Features

- Intelligente Vorbereitung: Alle Optionen (Formate, Designs, Ordner) in einem Aufruf
- Clientseitige Design-Suche nach Stichwort
- Automatisches Polling bis Fertigstellung mit Fortschrittsanzeige
- Interaktive Rückfragen (Elicitation) als Sicherheitsnetz
- Generierung aus bestehenden Vorlagen (Templates, Beta)
- Export als PDF oder PPTX
- 60+ Sprachen
- Session-basiertes Credit-Tracking
- Tool Timeouts für zuverlässigen Betrieb

## Architektur

```mermaid
flowchart TD
    User["Nutzer"] --> Agent["KI-Agent / Chat"]

    Agent -->|"1. Optionen holen"| Prep["praesentation_vorbereiten"]
    Prep -->|"Formate, Designs, Ordner"| Agent

    Agent -->|"2. Optional: Design suchen"| Search["designs_durchsuchen"]
    Search -->|"id + name Liste"| Agent

    Agent -->|"3. Erstellen + automatisches Polling"| Create["praesentation_erstellen"]
    Create -->|"POST /generations"| API["Gamma.app API"]
    Create -->|"GET /generations/id + Polling"| API
    API -->|"gammaUrl, Downloads"| Create
    Create -->|"Fertige URL"| Agent

    Agent -->|"4. Ergebnis"| User
```

**Ablauf:** Der Agent ruft zuerst `praesentation_vorbereiten` auf, um alle verfügbaren Optionen (Formate, Textmengen, Designs, Ordner) zu erhalten. Dann fragt er den Nutzer nach Präferenzen. Mit `praesentation_erstellen` wird die Gamma generiert — das Tool pollt automatisch bis Fertigstellung und gibt die URL direkt zurück.

## Voraussetzungen

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (empfohlen)
- Gamma Pro/Ultra/Teams/Business Account
- Gamma API-Key — [gamma.app/settings/api](https://gamma.app/settings/api)

## Installation & Nutzung

### 1. Als uvx-Paket (empfohlen)

```bash
GAMMA_API_KEY=sk-gamma-xxx uvx gamma31
```

### 2. In einer MCP-Plattform (Python-Paket, stdio)

| Einstellung | Wert |
|---|---|
| Paketname | `gamma31` |
| Umgebungsvariable | `GAMMA_API_KEY` = `sk-gamma-xxx` |

### 3. Als Remote-Server (SSE/HTTP)

```bash
GAMMA_API_KEY=sk-gamma-xxx uv run gamma31 --transport sse --port 8000
```

Verbinden Sie dann Ihre MCP-Plattform als Remote-HTTP mit der URL `http://<host>:8000/sse`.

### 4. In Claude Desktop

Fügen Sie folgendes in Ihre Claude Desktop Konfigurationsdatei ein:

```json
{
  "mcpServers": {
    "gamma": {
      "command": "uvx",
      "args": ["gamma31"],
      "env": {
        "GAMMA_API_KEY": "sk-gamma-xxx"
      }
    }
  }
}
```

## Verfügbare Tools

| Tool | Beschreibung | Tags |
|---|---|---|
| `praesentation_vorbereiten` | Alle Optionen auf einen Blick: Formate, Designs, Ordner, Textmengen etc. | `workflow` |
| `designs_durchsuchen` | Designs nach Name durchsuchen (clientseitige Filterung) | `lookup` |
| `praesentation_erstellen` | Erstellt eine Gamma und wartet automatisch auf Fertigstellung | `core` |
| `praesentation_aus_vorlage` | Erstellt eine Gamma aus einem Template (Beta) mit Auto-Polling | `beta` |
| `ergebnis_abrufen` | Status erneut prüfen / URL abrufen (Fallback bei Timeout) | `core` |
| `ordner_anzeigen` | Workspace-Ordner auflisten | `lookup` |

## Typischer Workflow

```
1. praesentation_vorbereiten         → Optionen + Top-Designs + Ordner
2. Optional: designs_durchsuchen     → Design nach Name suchen
3. praesentation_erstellen           → Generierung + Auto-Polling → fertige URL
```

## Umgebungsvariablen

| Variable | Pflicht | Beschreibung | Standard |
|---|---|---|---|
| `GAMMA_API_KEY` | Ja | Gamma API-Key (Format: `sk-gamma-xxx`) | — |
| `MCP_TRANSPORT` | Nein | Transport-Modus: `stdio` oder `sse` | `stdio` |
| `MCP_PORT` | Nein | Port für SSE-Transport | `8000` |
| `MCP_HOST` | Nein | Host für SSE-Transport | `0.0.0.0` |

> **Sicherheit:** Der API-Key wird ausschließlich über die Umgebungsvariable `GAMMA_API_KEY` übergeben und ist nirgends im Quellcode enthalten. Das Paket auf PyPI enthält keine Secrets.

## Lizenz

MIT — siehe [LICENSE](LICENSE).
