oase-mcp

Ein MCP-Server, der es Claude ermöglicht, in einer Oase zu chatten. Gib Claude einen Einladungslink, und er kann in den Gruppenchat dieser oase posten, Beiträge (opslag) im Feed der oase veröffentlichen, die Konversation lesen und reagieren – praktisch für Statusupdates, „Ich habe X erledigt“ oder um eine Notiz zu hinterlassen, wo du sie siehst.

Es ist ein REST-Client: Jedes Tool ist ein einfacher HTTP-Request/Response-Aufruf.

📖 Dokumentation: https://dev.oase.app/mcp/

Status / Haftungsausschluss

Dies ist experimentell und wird wie besehen bereitgestellt. Es basiert auf der internen API von Oase, die sich ohne Vorankündigung ändern kann – daher kann es jederzeit kaputtgehen, sich ändern oder eingestellt werden, und es gibt keine Garantie, dass es heute funktioniert oder morgen weiter funktioniert. Es gibt keine Support-Zusage: Issues sind willkommen (siehe SUPPORT.md), bleiben aber möglicherweise unbeantwortet. Wenn du einen unterstützten Integrationsweg benötigst, nutze stattdessen die Identity- & SCIM-Integration.

Es spricht genau wie die App mit dem Produktions-Backend von Oase (api.oase.app): Anmelden → über Einladungslink beitreten → den oase-Schlüssel vom KMS abrufen → AES-256-GCM-Verschlüsselung → POST .../messaging/messages. Nachrichten werden clientseitig mit dem symmetrischen AES-256-GCM-Schlüssel der oase verschlüsselt (über einen mainframe-signierten Nachweis vom KMS abgerufen), sodass sie in der App normal dargestellt werden.

Related MCP server: WAHA WhatsApp MCP Server

Architektur

Die Codebasis ist ein passiver REST-Client mit einem darauf aufsetzenden MCP-Server:

• Passiver REST-Client – src/client/. Alles, was weiß, wie man über HTTP mit Oase spricht: Promise-Login/Auth (promiseLogin.ts), Token-Aktualisierung und die gemeinsame Konfigurationsdatei (config.ts) sowie der vollständige REST-Client (oaseClient.ts) – Beitritt über Einladungslink, KMS-Schlüsselabruf, AES-256-GCM-Ver-/Entschlüsselung und Senden/Lesen von Nachrichten und Feed-Beiträgen, Reaktionen und Medien. Kein Agentenverhalten, keine MCP-Abhängigkeit: Es tut nur dann etwas, wenn es aufgerufen wird. Von anderen Konsumenten über die Paketwurzel oder oase-mcp/client importierbar (import { OaseClient, loadConfig } from "oase-mcp"), ohne die MCP-Ebene einzubinden.

• MCP-Server – src/mcp/. Die MCP-Tool-Oberfläche über dem REST-Client (server.ts). Jedes Tool ist ein On-Demand-Request/Response-Wrapper. Einstiegspunkt: dist/index.js (claude mcp add oase -- node /path/to/dist/index.js).

So funktioniert es

• Identität. Claude meldet sich über einen einmaligen Browser-Login als dauerhafter Promise-Benutzer an (dem Identitätsanbieter, den die Oase-App verwendet) – siehe Anmelden. Der resultierende langlebige Oase-Refresh-Token wird in ~/.oase-mcp/config.json (Modus 0600) gespeichert; kurzlebige Access-Tokens werden im Speicher gehalten und automatisch aktualisiert.

• Verschlüsselung. Oase verschlüsselt Nachrichteninhalte mit einem pro oase symmetrischen AES-256-GCM-Schlüssel, der vom Backend treuhänderisch verwahrt wird. Jeder Teilnehmer kann den rohen oase-Schlüssel über einen mainframe-signierten Nachweis vom KMS abrufen, sodass Ver- und Entschlüsselung unkompliziert sind – keine Geräteschlüsselpaare oder Registrierung. Wir erzeugen genau die Cipher-Bundle-Form, die die App erwartet.

• Keine Nachricht wird im Klartext gesendet – der Send-Endpunkt erfordert ein Cipher-Bundle.

Einrichtung

npm install
npm run build

Registriere es bei Claude Code (verwende den absoluten Pfad zu diesem Checkout):

claude mcp add oase -- node /path/to/oase-mcp/dist/index.js

Oder füge es manuell zu deiner MCP-Client-Konfiguration hinzu:

{
  "mcpServers": {
    "oase": {
      "command": "node",
      "args": ["/path/to/oase-mcp/dist/index.js"]
    }
  }
}

Anmelden

Claude meldet sich als dauerhafter Promise-Benutzer an – eine einmalige Einrichtung:

1. Rufe promise_login_start auf – es gibt eine URL zurück. Öffne sie in einem Browser (inkognito ist am sichersten, damit eine bestehende Promise-Sitzung nicht wiederverwendet wird).

2. Melde dich beim Promise-Konto für Claude an (oder erstelle es). Die Seite zeigt „Token captured“ an.

3. Rufe promise_login_finish auf – es tauscht den Token gegen eine dauerhafte Oase-Identität.

Im Hintergrund hostet der Server einen localhost-OIDC-Callback und erfasst das einmalige id_token aus der Weiterleitung – kein Kopieren und Einfügen. (Wenn du bereits ein id_token hast, nimmt login_with_promise es direkt entgegen.)

Der Austausch gibt Oases eigenen langlebigen Refresh-Token zurück (gebunden an die person_id von Promise), sodass Promise nie wieder kontaktiert wird – es werden keine Promise-Anmeldedaten gespeichert, sondern nur der resultierende Oase-Refresh-Token.

Eine Anmeldung ist erforderlich: Jedes andere Tool (join, send, read, ask) verweigert die Ausführung, bis eine Promise-Identität eingerichtet ist.

Tools

Threads und Antworten

Threads in Oase haben nur eine Ebene: Jede Antwort auf eine Nachricht lebt unter der Ressourcen-ID dieser Nachricht (chat_id <oaseId>/m/<messageId>), und du kannst nicht auf eine Antwort antworten – ein verschachtelter Thread würde in der App nie angezeigt. Der Server erzwingt dies: Eine thread_id, die auf eine Antwort verweist, wird automatisch auf die Root-Nachricht des Threads aufgelöst, sodass nichts jemals in einem unsichtbaren verschachtelten Chat landet. Um auf eine Nachricht zu antworten, übergib ihre ID als thread_id an send_message; nutze read_messages, um den Kontext nachzulesen und die IDs zu erhalten.

Anhänge (Bilder, Sprachnachrichten, Dateien)

Nachrichten mit Anhängen zeigen diese als [attachment <n>: <mime> "<name>"]-Tags in jedem Leseergebnis (eine Sprachnachricht ist einfach ein audio/*-Anhang, meist audio/mp4). read_media lädt den Blob herunter und entschlüsselt ihn bei modernen Uploads: Die App lädt Medien als verschlüsselten .oase-Container hoch — [4-byte length][metadata JSON {alg, kid, oaseId, ivBase64}] [ciphertext][16-byte GCM tag] — verschlüsselt mit demselben beim Server hinterlegten oase-Schlüssel wie für Text, während der ursprüngliche Dateiname und MIME-Typ als Cipher-Bundles am Medienobjekt mitgeführt werden (Legacy-Anhänge sind Klartext-Blobs hinter signierten CDN-URLs und werden unverändert durchgereicht; giphy-Anhänge werden über ihr verschlüsseltes giphy-Objekt aufgelöst).

Was der Agent zurückbekommt:

• Bilder (jpeg/png/gif/webp bis 3 MB) werden inline als MCP-Bildinhalt zurückgegeben, sodass der Agent sie direkt ansehen und das Gesehene in seiner Antwort verwenden kann