# opencontent-mcp

**English:** A small stdio bridge to the MCP server of [openContent](https://huggenberg.dev), a self-hosted Markdown editor with a social media planner for Instagram and Facebook. It connects to openContent over Streamable HTTP with a bearer token, passes all remote tools through unchanged, and adds one local tool to upload image or video files from disk. Start it with `npx -y github:IonFlux84/opencontent-mcp` and set `OPENCONTENT_TOKEN`. The rest of this document is in German.

---

Mit dieser Brücke kann ein KI-Agent über das Model Context Protocol (MCP) mit openContent arbeiten: Beiträge für Instagram und Facebook planen, Grafiken hochladen, sofort senden, Statistiken lesen und Artikel schreiben.

Die Brücke läuft lokal als stdio-Server. Sie meldet sich mit deinem Schlüssel bei openContent an, holt dort die Werkzeugliste und reicht jedes Werkzeug 1:1 durch. Kommen in openContent neue Werkzeuge dazu, sind sie ohne Update der Brücke da. Zusätzlich bringt sie `social-datei-hochladen` mit, damit dein Agent eine Datei von seinem Rechner an einen Beitrag hängen kann.

## Voraussetzungen

- Node.js 18 oder neuer (`npx` gehört dazu)
- Ein openContent mit MCP-Server, Standard ist `https://content.huggenberg.dev/mcp`
- Ein Schlüssel aus openContent (siehe unten)

## Schlüssel in openContent anlegen

1. In openContent anmelden.
2. **System → Zugänge für Agenten** öffnen.
3. Einen neuen Zugang anlegen, Namen vergeben (zum Beispiel „Grok“) und bei Social **senden** wählen. „Senden“ schliesst Planen und Lesen ein. Wer nur planen soll, bekommt „planen“, wer nur schauen soll, „lesen“. Bei Artikel wählst du „keine“, wenn der Agent nur Social machen soll.
4. Den Schlüssel kopieren. Er wird nur einmal angezeigt.

## Einbinden

Die meisten MCP-Clients nehmen eine Konfiguration in dieser Form:

```json
{
  "mcpServers": {
    "opencontent": {
      "command": "npx",
      "args": ["-y", "github:IonFlux84/opencontent-mcp"],
      "env": {
        "OPENCONTENT_TOKEN": "dein-schluessel-aus-opencontent"
      }
    }
  }
}
```

Läuft dein openContent unter einer anderen Adresse, gib sie zusätzlich mit:

```json
"env": {
  "OPENCONTENT_TOKEN": "dein-schluessel-aus-opencontent",
  "OPENCONTENT_URL": "https://dein-server.example/mcp"
}
```

Die Adresse muss mit `https://` beginnen. Nur für Tests auf dem eigenen Rechner geht auch `http://localhost`.

Zum Ausprobieren in der Kommandozeile:

```sh
OPENCONTENT_TOKEN=dein-schluessel npx -y github:IonFlux84/opencontent-mcp
```

Die Brücke wartet dann auf MCP-Nachrichten über stdin. Meldungen stehen auf stderr.

## Werkzeuge

Dein Agent sieht immer alle Werkzeuge. Was er davon nutzen darf, hängt von den Rechten des Schlüssels ab (Spalte „Recht“). Fehlt das Recht, antwortet das Werkzeug mit einem Fehler, der das fehlende Recht nennt.

### Social

| Werkzeug | Was es tut | Recht |
|---|---|---|
| `social-kanaele` | Verbundene Instagram-Konten und Facebook-Seiten mit Zustand und freien Plätzen der nächsten sieben Tage | lesen |
| `social-liste` | Beiträge einer Ansicht: Warteschlange, Ideen, gesendet oder Fehler, auf Wunsch für einen Kanal | lesen |
| `social-lesen` | Ein Beitrag vollständig: Text, Text je Kanal, Medien, Status, Fehler, Zahlen | lesen |
| `social-statistik` | Summen und beste Beiträge der letzten 7, 30 oder 90 Tage | lesen |
| `social-schreiben` | Legt einen Beitrag an oder ändert ihn | planen |
| `social-einplanen` | Setzt den Termin: nächster freier Platz oder eine feste Zeit (Europe/Berlin) | planen |
| `social-plan-einlesen` | Liest einen ganzen Contentplan als geplante Beiträge ein, standardmässig als Probelauf | planen |
| `social-medium-hochladen` | Hängt ein Bild oder Video an einen Beitrag, als base64 (`daten_base64`) oder per öffentlicher https-Adresse (`url`). Bilder werden zu JPEG. | senden |
| `social-datei-hochladen` | Nur in dieser Brücke: liest eine lokale Datei (`pfad`) und lädt sie über `social-medium-hochladen` hoch | senden |
| `social-medium-loeschen` | Entfernt ein Medium von einem Beitrag | senden |
| `social-jetzt-senden` | Sendet einen Beitrag sofort, wie der Knopf „Jetzt senden“ | senden |
| `social-loeschen` | Löscht einen Beitrag in openContent. Was schon gesendet ist, bleibt bei Instagram und Facebook stehen. | senden |

### Artikel

| Werkzeug | Was es tut | Recht |
|---|---|---|
| `artikel-liste` | Alle Artikel mit Kennung, Titel, Stand und Wortzahl | lesen |
| `artikel-lesen` | Ein Artikel vollständig als Markdown | lesen |
| `artikel-schreiben` | Speichert einen Artikel oder legt einen neuen an. Veröffentlicht wird damit nichts. | schreiben |

### `social-datei-hochladen` im Detail

```json
{ "id": 42, "pfad": "grafiken/herbst.png", "alt": "Drei Darts im Triple 20" }
```

- `id`: Kennung des Beitrags
- `pfad`: absolut oder relativ zum Arbeitsverzeichnis der Brücke
- `alt`: Bildbeschreibung, optional

Erlaubt sind PNG, JPEG, WebP, MP4 und MOV bis 20 MB. Den Typ erkennt die Brücke am Inhalt der Datei, nicht an der Endung. Grössere Dateien lädst du mit `social-medium-hochladen` über eine öffentliche https-Adresse hoch.

## Grenzen

- Kanäle verbindest du nur in der Oberfläche von openContent, nicht über MCP.
- Storys gehen ohne Sticker (also ohne Link, Umfrage oder Erwähnung). Das erlaubt die Schnittstelle von Meta nicht.
- Instagram nimmt höchstens 100 Beiträge in 24 Stunden pro Konto an.
- Medien als Datei oder base64 bis 20 MB, grössere per https-Adresse bis 50 MB.
- Zeiten gelten in Europe/Berlin.

## Sicherheit

- **Behandle den Schlüssel wie ein Passwort.** Er gehört nicht in Repos, Screenshots oder Chats.
- **Ein Schlüssel mit „senden“ kann öffentlich posten**, sofort und ohne Rückfrage. Was dein Agent liest (Kommentare, Webseiten, fremde Texte), kann ihn zu Dingen verleiten, die du nicht willst. Gib „senden“ nur einem Agenten, dem du das zutraust, und schau regelmässig in die Warteschlange und das Protokoll.
- Du kannst jeden Schlüssel jederzeit unter **System → Zugänge für Agenten** zurückziehen. Er gilt dann sofort nicht mehr.
- Die Brücke schreibt den Schlüssel nie in Ausgaben oder Meldungen und schickt ihn nur per https an die eingestellte Adresse.

## Fehlersuche

| Meldung | Was hilft |
|---|---|
| `OPENCONTENT_TOKEN fehlt` | Der Schlüssel ist nicht als Umgebungsvariable gesetzt. Prüfe den `env`-Block deiner Konfiguration. |
| `lehnt den Schlüssel ab (HTTP 401)` | Schlüssel falsch kopiert oder zurückgezogen. Lege einen neuen an. |
| `Diesem Schlüssel fehlt das Recht …` | Dem Schlüssel fehlt das Recht für dieses Werkzeug, zum Beispiel „Social: senden“ für Uploads und sofortiges Senden. Lege unter System einen Schlüssel mit diesem Recht an. |
| `Keine Verbindung zu openContent` | Adresse prüfen (`OPENCONTENT_URL`), Internetverbindung prüfen. Die Brücke versucht es beim nächsten Aufruf selbst erneut. |
| `ist kein unterstütztes Medium` | Die Datei ist kein PNG, JPEG, WebP, MP4 oder MOV. |
| `höchstens 20 MB` | Datei verkleinern oder per https-Adresse mit `social-medium-hochladen` hochladen. |

Meldungen der Brücke stehen auf stderr und beginnen mit `[opencontent-mcp]`. Bei den meisten Clients findest du sie im Log des MCP-Servers.

`npx` merkt sich heruntergeladene Pakete. Holt dein Client nach einem Update noch die alte Version, lösche den Ordner `~/.npm/_npx` und starte den Client neu.

## Entwicklung

```sh
npm install
npm test
```

Die Tests starten einen nachgebauten openContent-Server auf localhost und prüfen das Weiterreichen von Werkzeugliste, Aufrufen und Fehlern, den Bearer-Schlüssel und den Datei-Upload.

## Lizenz

MIT, siehe [LICENSE](LICENSE).