VoiceOS-Instagram-Integration

Steuern Sie Ihr Instagram-Konto per Sprache direkt aus der Mac-Notch. Fragen Sie nach dem Kontostatus, lesen Sie Kommentare und DMs und veröffentlichen Sie ein Foto oder ein Karussell, indem Sie es auf die Notch ziehen und die Bildunterschrift diktieren.

Business- oder Creator-Konto erforderlich. Die Instagram-API stellt für persönliche Konten keine Insights, Kommentare, DMs oder Veröffentlichungen bereit – das ist Metas Regel, nicht unsere, und es gibt keinen Weg daran vorbei.

So stellen Sie um: Instagram-App → Ihr Profil → ☰-Menü → Einstellungen und Datenschutz → Kontotyp und Tools → Zum professionellen Konto wechseln. Wählen Sie Creator oder Business und folgen Sie den Anweisungen. Es ist kostenlos, umkehrbar und macht Ihr Konto nicht öffentlich, wenn es privat war. Verbinden Sie diese Integration danach erneut.

Einrichtung

Sechs Schritte. Die Schritte 3 und 4 werden nur benötigt, wenn Sie veröffentlichen möchten; das Lesen funktioniert auch ohne sie.

1. Abhängigkeiten installieren

cd instagram
bun install

2. Instagram über Composio verbinden

Composio ist die Authentifizierungs- und API-Transportebene, auf der diese Integration läuft.

1. Holen Sie sich einen API-Schlüssel aus dem Composio-Dashboard.

2. Fügen Sie Instagram als App in Ihrem Composio-Projekt hinzu. Das erstellt die Auth-Konfiguration, die der Verbindungsablauf benötigt.

Die eigentliche Instagram-OAuth-Autorisierung bestätigen Sie in Schritt 6 – hier ist noch nichts zu tun.

3. Photo-Relay-Bucket erstellen (Cloudflare R2)

Instagram akzeptiert niemals Bilddaten. Meta ruft stattdessen eine öffentliche URL mit einem eigenen Crawler ab. Ein Foto, das Sie auf die Notch ziehen, wird also in Ihren eigenen R2-Bucket hochgeladen, als Link an Instagram übergeben und Sekunden später gelöscht.

Im Cloudflare-Dashboard → R2:

1. Einen Bucket erstellen.

2. Öffnen Sie ihn → Einstellungen → Public Development URL → Aktivieren. Kopieren Sie diese URL. Der Bucket muss öffentlich sein, sonst kann Meta das Foto nicht abrufen.

3. API-Tokens verwalten → API-Token erstellen, beschränkt auf diesen einen Bucket, mit Object Read & Write. Das Geheimnis wird nur einmal angezeigt – kopieren Sie es jetzt.

4. Optional, aber empfohlen: Fügen Sie eine Lifecycle-Regel hinzu, die Objekte nach 1 Tag löscht. Die Integration löscht jedes Foto selbst; das ist die Absicherung für den seltenen Fehlfall.

Überspringen Sie diesen gesamten Schritt, wenn Sie nur lesen möchten. account_pulse, post_insights, activity und dm_thread funktionieren alle ohne Bucket. Nur create_post und schedule_post benötigen einen.

4. Dem Server die Schlüssel geben

Erstellen Sie eine .env-Datei in diesem Ordner:

COMPOSIO_API_KEY=

# Cloudflare R2 — publishing only, leave blank if you are read-only
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_PUBLIC_URL=

R2_ACCOUNT_ID finden Sie auf der Cloudflare-Seite R2 → Overview oben rechts. R2_PUBLIC_URL ist die Public Development URL aus Schritt 3.

Wenn VoiceOS Sie im Setup nach diesen Werten fragt, hat diese Eingabe Vorrang und die Datei dient nur als Fallback für den eigenständigen Serverbetrieb.

5. In VoiceOS installieren

Beenden Sie VoiceOS zuerst. VoiceOS hält config.json im Speicher und schreibt sie beim Beenden neu – alles, was geschrieben wird, während es läuft, wird also stillschweigend verworfen, ganz ohne Fehlermeldung. Der Installer weigert sich zu laufen, wenn VoiceOS aktiv ist.

osascript -e 'quit app "VoiceOS"'
python3 install-into-voiceos.py
open -a VoiceOS

Das kopiert diesen Ordner nach ~/Library/Application Support/VoiceOS/custom-mcps/, überträgt die Schlüssel aus Schritt 4 und registriert die Integration. Ein einfaches cp reicht nicht – VoiceOS benötigt außerdem zwei Einträge in config.json (einen, der angibt, wie der Server gestartet wird, und einen, der das Manifest enthält), und genau diese zu schreiben ist der Hauptteil des Skripts. Es sichert config.json zuerst.

--update leitet confirmTools jedes Mal neu aus dem Manifest ab. Das ist wichtiger, als es aussieht: Es ist die Liste, mit der VoiceOS entscheidet, welche Tools eine Bestätigungskarte benötigen, und ein veralteter Eintrag von einer Umbenennung würde eine Veröffentlichung ganz ohne Karte zulassen.

6. Ihr Konto verbinden

Sagen Sie „Wie läuft mein Instagram?" Wenn Instagram noch nicht verknüpft ist, erhalten Sie eine Connect Instagram-Karte mit einem OAuth-Link. Bestätigen Sie ihn einmal und schon sind Sie fertig.

Wenn dort steht, dass das Konto persönlich ist, gehen Sie zurück zum Kasten oben auf dieser Seite.

Tools

Ziehen Sie die Fotos auf die Notch und sprechen Sie im selben Atemzug – „poste diese beiden mit einer Bildunterschrift über den Hackathon". Beide Schreib-Tools zeigen Ihnen die Fotos, die Bildunterschrift und (bei einer Planung) die genaue Uhrzeit auf einer Karte, bevor etwas live geht.

So werden Ihre Fotos verarbeitet

Einmal lesen lohnt sich, denn ein Schritt überrascht die Leute.

1. Das Foto wird auf Ihrem Mac mit sips (in macOS integriert) in JPEG konvertiert. Instagram akzeptiert nichts anderes.

2. Es wird unter einem zufälligen, unerratbaren Namen in Ihren R2-Bucket hochgeladen und ist für ein paar Sekunden öffentlich lesbar. Das ist unvermeidbar: Metas Crawler ist anonym und kann sich nicht anmelden, daher ist eine öffentliche URL der einzige Weg, wie Instagram ein Foto annimmt.

3. Instagram ruft es ab und veröffentlicht den Beitrag.

4. Die Datei wird aus dem Bucket gelöscht – bei Erfolg und bei Fehlschlag, in einem finally-Block. Die Lifecycle-Regel aus Schritt 3 ist die Absicherung.

Der Bucket gehört Ihnen. Nichts wird auf einem fremden Server gespeichert, und diese Integration behält keine Kopie Ihrer Fotos.

Geplante Beiträge laufen auf Ihrem Mac, nicht auf Instagrams Servern – Instagram hat keine Scheduling-API. Ein macOS-launchd-Timer wacht zu der von Ihnen genannten Minute auf und veröffentlicht dann. Der Mac muss also eingeschaltet und wach sein. Wenn er zum geplanten Zeitpunkt aus war, wird der Beitrag als verpasst erfasst, statt Stunden später veröffentlicht zu werden, und instagram_activity informiert Sie beim nächsten Nachfragen.

Nicht in v1

Bewusst weggelassen, damit Sie es wissen, bevor Sie es versuchen:

• DMs senden. Meta blockiert das Senden von DMs über die API durch Composios gemeinsame Instagram-App – sie gibt „outside the allowed window"-Fehler zurück, selbst wenn das 24-Stunden-Fenster nachweislich offen ist. Die Integration liest DMs, kann sie aber nicht senden. Antworten Sie in der Instagram-App.

• Auf Kommentare antworten. Gleiche Transport-Einschränkung.

• Video und Reels. Nur Fotos und Foto-Karussells. Die Video-Veröffentlichung benötigt einen fortsetzbaren Upload-Pfad, den dieser Build nicht hat.

• Stories. Vom Toolkit nicht bereitgestellt.

• Planung über 24 Stunden hinaus. Die Obergrenze ist bewusst gewählt: Jede zusätzliche Stunde ist eine weitere Möglichkeit, dass ein aufgeschobener Auftrag ungesehen verrottet – das Foto wird gelöscht, ein Schlüssel wird rotiert, die Verbindung wird widerrufen.

• Andere Konten lesen. Nur Ihr verbundenes Konto.

Fehlerbehebung

Entwicklung

bun install
bun test          # 224 unit and failure-injection tests
bunx tsc --noEmit -p tsconfig.json

Drei Regeln, die die Tests schützen sollen – wissenswert, bevor Sie Änderungen vornehmen:

• stdout ist die MCP-Leitung. Ein einziges console.log im ausgelieferten Code und VoiceOS kann den JSON-RPC-Stream nicht mehr parsen, sodass die Integration stillschweigend aus dem Routing verschwindet, bis die App neu gestartet wird. Alles protokolliert über console.error; stdoutGuard.ts ist der erste Import in server.ts und bindet die Konsole für Abhängigkeiten neu, die das nicht tun.

• Bauen Sie niemals einen Shell-String aus einem Dateipfad. Fotos kommen daher, dass der Benutzer eine Datei auf die Notch zieht. Nur execFile(cmd, [args]) – eine Datei namens holiday.png; rm -rf ~ ist ein einziges undurchsichtiges Argument für sips, und test/media-paths.test.ts stellt das sicher.

• Toolnamen und -beschreibungen müssen exakt mit dem Manifest übereinstimmen, in beide Richtungen. server.ts und voiceos.integration.json sind zwei Kopien eines Vertrags.

confirmations/post_composer.html ist die Quelle der Wahrheit für die Karte vor der Veröffentlichung; das Manifest enthält eine Kopie davon als String. Wenn Sie das HTML bearbeiten, muss die Kopie neu generiert werden, sonst ist die Karte, die vor einer unumkehrbaren Veröffentlichung angezeigt wird, die veraltete.