# 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

- Präsentationen, Dokumente, Social Posts und Webseiten generieren
- Generierung aus bestehenden Vorlagen (Templates, Beta)
- Interaktive Rückfragen vor der Generierung (Sprache, Zielgruppe, Ton, Textmenge)
- Fortschrittsanzeige beim Warten auf Fertigstellung
- Themes und Ordner auflisten und verwenden
- Export als PDF oder PPTX
- 60+ Sprachen
- Automatisches Polling bis Fertigstellung
- Session-basiertes Credit-Tracking
- Tool Timeouts für zuverlässigen Betrieb

## Architektur

```mermaid
flowchart TD
    Agent["KI-Agent / Chat"] -->|"Tool-Aufruf"| MCP["gamma31 MCP Server\n(FastMCP 3.x, stdio/SSE)"]

    subgraph elicit [Interaktive Rueckfragen]
        MCP -->|"ctx.elicit()"| User["Nutzer"]
        User -->|"Sprache, Zielgruppe,\nTon, Textmenge"| MCP
    end

    MCP -->|"POST /generations"| GammaAPI["Gamma.app API\n(public-api.gamma.app)"]
    MCP -->|"GET /generations/id\n+ ctx.report_progress()"| GammaAPI
    MCP -->|"GET /themes"| GammaAPI
    MCP -->|"GET /folders"| GammaAPI
    GammaAPI -->|"gammaUrl, pdfUrl,\npptxUrl, Credits"| MCP
    MCP -->|"ctx.set_state()\nCredit-Tracking"| SessionState["Session State"]
    MCP -->|"JSON-Ergebnis"| Agent
```

**Ablauf:** Der KI-Agent ruft ein Tool auf. Bei `gamma_generieren` fragt der Server den Nutzer optional nach Sprache, Zielgruppe, Ton und Textmenge (Elicitation). Dann wird die Gamma.app API angesprochen. Beim Polling zeigt `gamma_status_abrufen` den Fortschritt an und trackt verbrauchte Credits in der Session.

## 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://localhost:8000/sse` (oder der ngrok-URL für externen Zugriff).

### 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 |
|---|---|---|
| `gamma_generieren` | Erstellt eine neue Gamma mit optionaler interaktiver Rückfrage (Sprache, Zielgruppe, Ton, Textmenge) | `core` |
| `gamma_aus_vorlage_erstellen` | Erstellt eine Gamma aus einem bestehenden Template (Beta) | `beta` |
| `gamma_status_abrufen` | Wartet auf Fertigstellung mit Fortschrittsanzeige, liefert URL + Downloads | `core` |
| `gamma_themes_auflisten` | Listet verfügbare Themes mit Paginierung | `lookup` |
| `gamma_ordner_auflisten` | Listet Workspace-Ordner mit Paginierung | `lookup` |

## Typischer Workflow

```
1. Optional: gamma_themes_auflisten  → Theme-ID auswählen
2. Optional: gamma_ordner_auflisten  → Ordner-ID auswählen
3. gamma_generieren                  → Rückfragen → erhält generationId
4. gamma_status_abrufen              → Fortschritt → Gamma-URL + Downloads
```

## 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.

## Entwicklung

```bash
git clone https://github.com/localmind-ai/gamma31.git
cd gamma31
uv sync
GAMMA_API_KEY=sk-gamma-xxx fastmcp dev inspector src/gamma31/server.py -e .
```

## Testen

```bash
# Tools auflisten
fastmcp list tools src/gamma31/server.py

# Tool direkt aufrufen
GAMMA_API_KEY=sk-gamma-xxx fastmcp call src/gamma31/server.py gamma_themes_auflisten '{"limit": 3}'
```

## Veröffentlichen auf PyPI

```bash
# Bauen
uv build

# Veröffentlichen
uv publish --token pypi-xxxx

# Testen ob es funktioniert
GAMMA_API_KEY=sk-gamma-xxx uvx gamma31
```

## Lizenz

MIT — siehe [LICENSE](LICENSE).
