oase-mcp

Un servidor MCP que permite a Claude chatear dentro de un Oase. Dale a Claude un enlace de invitación y podrá publicar en el chat grupal de ese oase, publicar posts (opslag) en el feed del oase, leer la conversación y reaccionar — útil para actualizaciones de estado, "he terminado X", o dejar una nota donde la verás.

Es un cliente REST: cada herramienta es una simple llamada HTTP de petición/respuesta.

📖 Documentación: https://dev.oase.app/mcp/

Estado / descargo de responsabilidad

Esto es experimental y se proporciona tal cual. Se basa en la API interna de Oase, que puede cambiar sin previo aviso, por lo que puede romperse, cambiar o suspenderse en cualquier momento, y no hay garantía de que funcione hoy ni de que siga funcionando mañana. No hay compromiso de soporte: las incidencias son bienvenidas (consulta SUPPORT.md), pero pueden quedar sin respuesta. Si necesitas una vía de integración compatible, usa la integración de identidad y SCIM en su lugar.

Se comunica con el backend de producción de Oase (api.oase.app) exactamente igual que la aplicación: iniciar sesión → unirse mediante enlace de invitación → obtener la clave del oase desde KMS → cifrar con AES-256-GCM → POST .../messaging/messages. Los mensajes se cifran en el cliente con la clave simétrica AES-256-GCM del oase (obtenida del KMS mediante una prueba firmada por el mainframe), de modo que se muestran con normalidad en la aplicación.

Related MCP server: WAHA WhatsApp MCP Server

Arquitectura

El código base es un cliente REST pasivo con un servidor MCP encima:

• Cliente REST pasivo — src/client/. Todo lo que sabe cómo hablar con Oase por HTTP: inicio de sesión/autenticación de Promise (promiseLogin.ts), renovación de token y el archivo de configuración compartido (config.ts), y el cliente REST completo (oaseClient.ts) — unirse mediante enlace de invitación, obtención de la clave KMS, cifrado/descifrado AES-256-GCM, y envío/lectura de mensajes, publicaciones del feed, reacciones y medios. Sin comportamiento de agente, sin dependencia de MCP: solo hace algo cuando se le llama. Otros consumidores pueden importarlo desde la raíz del paquete o desde oase-mcp/client (import { OaseClient, loadConfig } from "oase-mcp"), sin necesidad de incluir la capa MCP.

• Servidor MCP — src/mcp/. La superficie de herramientas MCP sobre el cliente REST (server.ts). Cada herramienta es un envoltorio de petición/respuesta bajo demanda. Punto de entrada: dist/index.js (claude mcp add oase -- node /path/to/dist/index.js).

Cómo funciona

• Identidad. Claude inicia sesión como usuario persistente de Promise (el proveedor de identidad que usa la aplicación Oase) mediante un inicio de sesión único en el navegador; consulta Iniciar sesión. El token de actualización de Oase de larga duración resultante se guarda en ~/.oase-mcp/config.json (modo 0600); los tokens de acceso de corta duración se mantienen en memoria y se renuevan automáticamente.

• Cifrado. Oase cifra el contenido de los mensajes con una clave simétrica AES-256-GCM por oase, depositada en custodia por el backend. Cualquier participante puede obtener la clave cruda del oase desde el KMS mediante una prueba firmada por el mainframe, por lo que cifrar/descifrar es sencillo — sin pares de claves de dispositivo ni inscripción. Producimos exactamente la forma de paquete cifrado que la aplicación espera.

• Ningún mensaje se envía en texto plano — el endpoint de envío exige un paquete cifrado.

Configuración

npm install
npm run build

Regístralo con Claude Code (usa la ruta absoluta a este checkout):

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

O añádelo manualmente a la configuración de tu cliente MCP:

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

Iniciar sesión

Claude inicia sesión como usuario persistente de Promise — una configuración única.

1. Llama a promise_login_start — devuelve una URL. Ábrela en un navegador (lo más seguro es una ventana de incógnito para que no se reutilice una sesión existente de Promise).

2. Inicia sesión en (o crea) la cuenta de Promise para Claude. La página dirá "Token capturado".

3. Llama a promise_login_finish — intercambia el token por una identidad persistente de Oase.

Internamente, el servidor aloja un callback OIDC en localhost y captura el id_token de un solo uso desde la redirección — sin necesidad de copiar y pegar. (Si ya tienes un id_token, login_with_promise lo acepta directamente).

El intercambio devuelve el token de actualización de larga duración propio de Oase (vinculado al person_id de Promise), por lo que nunca se vuelve a contactar con Promise — no se almacenan credenciales de Promise, solo el token de actualización de Oase resultante.

El inicio de sesión es obligatorio: todas las demás herramientas (unirse, enviar, leer, consultar) se niegan a funcionar hasta que se establezca una identidad de Promise.

Herramientas

Hilos y respuestas

Los hilos en Oase son de un solo nivel: cada respuesta a un mensaje vive bajo el id de recurso de ese mensaje (chat_id <oaseId>/m/<messageId>), y no puedes responder a una respuesta — un hilo anidado nunca se mostraría en la aplicación. El servidor lo aplica: un thread_id que apunta a una respuesta se resuelve automáticamente al mensaje raíz del hilo, de modo que nada acabe en un chat anidado invisible. Para responder a un mensaje, pasa su id como thread_id a send_message; usa read_messages para ponerte al día con el contexto y obtener los ids.

Adjuntos (imágenes, notas de voz, archivos)

Los mensajes con archivos adjuntos los muestran como etiquetas [attachment <n>: <mime> "<name>"] en cada resultado de lectura (un mensaje de voz es simplemente un archivo adjunto audio/*, normalmente audio/mp4). read_media descarga el blob y, en las subidas modernas, lo descifra: la app sube los medios como un contenedor .oase cifrado — [4-byte length][metadata JSON {alg, kid, oaseId, ivBase64}] [ciphertext][16-byte GCM tag] — cifrado con la misma clave oase en custodia del servidor que el texto, mientras que el nombre/MIME originales viajan como bundles cifrados en el elemento multimedia (los adjuntos heredados son blobs en texto plano tras URL de CDN firmadas y pasan sin cambios; los adjuntos de giphy se resuelven mediante su objeto giphy cifrado).

Lo que recibe el agente:

• Imágenes (jpeg/png/gif/webp de hasta 3 MB) se devuelven integradas como contenido de imagen MCP, para que el agente pueda mirarlas directamente y usar lo que ve en su respuesta. Las imágenes más grandes recurren al archivo guardado.

• Todo se escribe también en <tmpdir>/oase-mcp/media/<messageId>-<n>-<name> y se devuelve la ruta. Para el audio (Claude no puede escucharlo de forma nativa), se incita al agente a transcribir el archivo guardado con una herramienta local de voz a texto (p. ej. hear en macOS o whisper) y a trabajar a partir de la transcripción; los documentos pueden abrirse con las herramientas de archivo normales.

Las URL de descarga de los blobs están firmadas por el proveedor y caducan a los ~2 días; read_media actualiza la proyección del chat y reintenta una vez si una URL ha caducado. Los mensajes de voz / mensajes de solo medios tienen un cuerpo de texto vacío y read_messages los muestra como cualquier otro mensaje.

Flujo típico

1. Inicia sesión con Claude: promise_login_start → abre la URL → promise_login_finish.

2. En la app de Oase, abre tu oase → invitar → copia el enlace de invitación.

3. Pide a Claude: "Únete a esta oase: https://oase.app/oase/…/join/…" → join_oase.

4. Pide a Claude que "envíe un mensaje a la oase diciendo …" → send_message, que "publique una actualización en el feed" → send_post, o "¿qué hay de nuevo en la oase?" → read_messages / read_posts.

Configuración

Variables de entorno (todas opcionales):

• OASE_MCP_CONFIG_DIR — dónde almacenar config.json (por defecto ~/.oase-mcp).

• OASE_API_ROOT — raíz de la API de mainframe (por defecto https://api.oase.app), p. ej. para apuntar a staging.

• OASE_KMS_ROOT — raíz de KMS (por defecto https://kms.oase.app/, requiere la barra final).

Notas y limitaciones

• Funciona con el chat grupal de una oase (y los hilos de respuestas por mensaje) y sus publicaciones del feed (send_post/read_posts — solo texto al enviar; el título y el cuerpo de una publicación son bundles cifrados separados bajo la misma clave de la oase). Puede leer/descifrar archivos adjuntos de medios (read_media) pero no enviarlos; no gestiona chats privados 1:1 ni flujos de aprobación de unión a realms.

• Las respuestas no se pueden anidar — los hilos tienen un solo nivel de profundidad. Un thread_id que es a su vez una respuesta se resuelve silenciosamente al mensaje raíz del hilo (mejor esfuerzo: para un mensaje más antiguo que la última página del chat, el id se usa tal cual).

• Iniciar sesión con una cuenta de Promise distinta borra las oases a las que se ha unido, ya que las membresías son por persona — vuelve a invitar a Claude después.

• Eliminar ~/.oase-mcp/config.json olvida la identidad (Claude debe iniciar sesión y ser invitado de nuevo).

• Muchos procesos de servidor (uno por sesión de Claude) comparten la identidad en ~/.oase-mcp/config.json. El backend rota el token de refresco en cada oauth2/refresh y elimina la sesión si alguna vez ve uno obsoleto (antirrepetición) — por lo que el token de acceso se persiste para reutilizarlo, y los refrescos se serializan entre procesos mediante ~/.oase-mcp/auth.lock con una relectura bajo el bloqueo. No hagas peticiones a oauth2/refresh fuera de banda mientras los servidores estén en ejecución; si la sesión se revoca, las herramientas lo indicarán — inicia sesión de nuevo con promise_login_start.

Licencia

MIT — véase LICENSE.