oase-mcp

MCP-сервер, который позволяет Claude общаться внутри Oase. Дайте Claude ссылку-приглашение, и он сможет публиковать сообщения в групповом чате этого oase, публиковать посты (opslag) в ленту oase, читать переписку и реагировать — удобно для статусных обновлений, сообщений «Я закончил X» или заметок там, где вы их увидите.

Это REST-клиент: каждый инструмент — это обычный HTTP-вызов запроса/ответа.

📖 Документация: https://dev.oase.app/mcp/

Статус / отказ от ответственности

Это экспериментальный проект, предоставляемый как есть. Он основан на внутреннем API Oase, который может меняться без предупреждения, — поэтому проект может сломаться, измениться или быть прекращён в любой момент, и нет гарантии, что он работает сегодня или продолжит работать завтра. Поддержка не гарантируется: issue приветствуются (см. SUPPORT.md), но могут остаться без ответа. Если вам нужен поддерживаемый путь интеграции, используйте вместо этого интеграцию identity & SCIM.

Общается с продакшен-бэкендом Oase (api.oase.app) точно так же, как это делает приложение: вход → присоединение по ссылке-приглашению → получение ключа oase из KMS → шифрование AES-256-GCM → POST .../messaging/messages. Сообщения шифруются на стороне клиента симметричным ключом AES-256-GCM oase (полученным из KMS через подтверждение, подписанное mainframe), поэтому в приложении они отображаются нормально.

Related MCP server: WAHA WhatsApp MCP Server

Архитектура

Кодовая база — это пассивный REST-клиент с MCP-сервером поверх:

• Пассивный REST-клиент — src/client/. Всё, что знает, как общаться с Oase по HTTP: вход/аутентификация Promise (promiseLogin.ts), обновление токена и общий файл конфигурации (config.ts), а также полный REST-клиент (oaseClient.ts) — присоединение по ссылке-приглашению, получение ключа из KMS, шифрование/дешифрование AES-256-GCM, отправка и чтение сообщений и постов ленты, реакции и медиа. Никакого поведения агента, никакой зависимости от MCP: он что-то делает, только когда его вызывают. Его могут импортировать другие потребители через корень пакета или oase-mcp/client (import { OaseClient, loadConfig } from "oase-mcp"), без подключения MCP-слоя.

• MCP-сервер — src/mcp/. Слой MCP-инструментов поверх REST-клиента (server.ts). Каждый инструмент — это обёртка запроса/ответа по требованию. Точка входа: dist/index.js (claude mcp add oase -- node /path/to/dist/index.js).

Как это работает

• Идентичность. Claude входит как постоянный пользователь Promise (провайдера идентичности, который использует приложение Oase) через одноразовый вход в браузере — см. Вход в систему. Полученный долгоживущий refresh-токен Oase хранится в ~/.oase-mcp/config.json (режим 0600); кратковременные access-токены хранятся в памяти и обновляются автоматически.

• Шифрование. Oase шифрует содержимое сообщений симметричным ключом AES-256-GCM для каждого oase, который хранится в эскроу на бэкенде. Любой участник может получить исходный ключ oase из KMS через подтверждение, подписанное mainframe, так что шифрование/дешифрование не представляет сложности — никаких пар ключей устройства или регистрации. Мы создаём точно такую же форму cipher-bundle, которую ожидает приложение.

• Ни одно сообщение не отправляется открытым текстом — endpoint отправки требует cipher bundle.

Установка

npm install
npm run build

Зарегистрируйте его в Claude Code (укажите абсолютный путь к этому каталогу):

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

Или добавьте в конфигурацию MCP-клиента вручную:

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

Вход в систему

Claude входит как постоянный пользователь Promise — это одноразовая настройка:

1. Вызовите promise_login_start — он вернёт URL. Откройте его в браузере (лучше всего в режиме инкогнито, чтобы не использовалась существующая сессия Promise).

2. Войдите в (или создайте) учётную запись Promise для Claude. На странице будет написано «Token captured».

3. Вызовите promise_login_finish — он обменяет токен на постоянную идентичность Oase.

Под капотом сервер запускает OIDC-callback на localhost и перехватывает одноразовый id_token из редиректа — без копирования и вставки. (Если у вас уже есть id_token, login_with_promise принимает его напрямую.)

В результате обмена возвращается собственный долгоживущий refresh-токен Oase (привязанный к Promise person_id), поэтому Promise больше никогда не запрашивается — никакие учётные данные Promise не сохраняются, только полученный refresh-токен Oase.

Вход обязателен: все остальные инструменты (join, send, read, ask) отказываются работать, пока не установлена идентичность Promise.

Инструменты

Ветки и ответы

Ветки в Oase одноуровневые: каждый ответ на сообщение находится под resource id этого сообщения (chat_id <oaseId>/m/<messageId>), и нельзя ответить на ответ — вложенная ветка никогда бы не отображалась в приложении. Сервер обеспечивает это: thread_id, указывающий на ответ, автоматически преобразуется в корневое сообщение ветки, так что ничто никогда не попадает в невидимый вложенный чат. Чтобы ответить на сообщение, передайте его id как thread_id в send_message; используйте read_messages, чтобы ознакомиться с контекстом и получить нужные id.

Вложения (изображения, голосовые сообщения, файлы)

Сообщения с вложениями показывают их как теги [attachment <n>: <mime> "<name>"] в каждом результате чтения (голосовое сообщение — это просто вложение audio/*, обычно audio/mp4). read_media скачивает blob и для современных загрузок расшифровывает его: приложение загружает медиа как зашифрованный контейнер .oase — [4-byte length][metadata JSON {alg, kid, oaseId, ivBase64}] [ciphertext][16-byte GCM tag] — зашифрованный тем же oase-ключом, что и текст (сервер хранит его в эскроу), а исходные имя файла/mime передаются как cipher-пакеты в элементе медиа (legacy-вложения — это открытые blob'ы за подписанными CDN-URL, которые проходят без изменений; вложения giphy резолвятся через свой зашифрованный giphy-объект).

Что агент получает в ответ:

• Изображения (jpeg/png/gif/webp до 3 МБ) возвращаются инлайн как image-контент MCP, так что агент может смотреть на них напрямую и использовать увиденное в своём ответе. Более крупные изображения откатываются к сохранённому файлу.

• Всё также записывается в <tmpdir>/oase-mcp/media/<messageId>-<n>-<name>, и возвращается путь. Для аудио (Claude не умеет слушать нативно) агенту предлагается транскрибировать сохранённый файл локальным инструментом распознавания речи (например, hear на macOS или whisper) и работать с транскриптом; документы можно открывать обычными файловыми инструментами.

URL-адреса загрузки blob подписаны провайдером и истекают через ~2 дня; read_media обновляет проекцию чата и повторяет попытку один раз, если URL устарел. Голосовые сообщения / сообщения только с медиа имеют пустое текстовое тело и показываются через read_messages так же, как любое другое сообщение.

Типовой сценарий

1. Авторизуйте Claude: promise_login_start → откройте URL → promise_login_finish.

2. В приложении Oase откройте свою oase → invite → скопируйте ссылку для вступления.

3. Попросите Claude: "Вступите в эту oase: https://oase.app/oase/…/join/…" → join_oase.

4. Попросите Claude "отправить сообщение в oase с текстом …" → send_message, "опубликовать обновление в ленте" → send_post или "что нового в oase?" → read_messages / read_posts.

Конфигурация

Переменные окружения (все опциональны):

• OASE_MCP_CONFIG_DIR — где хранить config.json (по умолчанию ~/.oase-mcp).

• OASE_API_ROOT — корень API mainframe (по умолчанию https://api.oase.app), например, для указания на staging.

• OASE_KMS_ROOT — корень KMS (по умолчанию https://kms.oase.app/, завершающий слэш обязателен).

Примечания и ограничения

• Работает с групповым чатом oase (и с ветками ответов к отдельным сообщениям) и с записями в ленте oase (send_post/read_posts — только текст при отправке; заголовок и тело записи — это отдельные cipher-пакеты под тем же oase-ключом). Может читать/расшифровывать медиавложения (read_media), но не отправлять их; не обрабатывает приватные чаты 1:1 или процессы одобрения вступления в realm.

• Ответы не могут быть вложенными — ветки имеют глубину в один уровень. thread_id, который сам является ответом, молча резолвится в корневое сообщение ветки (best effort: для сообщения старше последней страницы чата id используется как есть).

• Вход под другой учётной записью Promise очищает список присоединённых oase, поскольку членства привязаны к человеку — после этого пригласите Claude заново.

• Удаление ~/.oase-mcp/config.json стирает личность (Claude должен войти и быть приглашённым заново).

• Многие серверные процессы (по одному на сессию Claude) используют общую личность из ~/.oase-mcp/config.json. Бэкенд ротирует refresh-токен при каждом oauth2/refresh и удаляет сессию, если когда-либо видит устаревший токен (анти-повтор) — поэтому access-токен сохраняется для повторного использования, а обновления сериализуются между процессами через ~/.oase-mcp/auth.lock с повторным чтением под локом. Не вызывайте oauth2/refresh out-of-band, пока серверы работают; если сессия всё же будет отозвана, инструменты сообщат об этом — войдите снова через promise_login_start.

Лицензия

MIT — см. LICENSE.