oase-mcp

Claude が Oase 内でチャットできるようにする MCP サーバーです。Claude に招待リンクを与えると、その oase のグループチャットに投稿したり、oase のフィードに投稿（opslag）を公開したり、会話を読んだり、リアクションしたりできます。ステータス更新、「X を完了しました」、または後で見る場所にメモを残すのに便利です。

これは REST クライアントです。すべてのツールは単純な要求/応答の HTTP 呼び出しです。

📖 ドキュメント: https://dev.oase.app/mcp/

ステータス / 免責事項

これは実験的であり、現状のまま提供されます。Oase の内部 API に基づいており、予告なく変更される可能性があります。そのため、いつでも壊れたり、変更されたり、廃止されたりする可能性があり、今日動作することも、明日も動作し続けることも保証されません。サポートの約束はありません: 問題報告（SUPPORT.md を参照）は歓迎しますが、回答されない場合があります。サポートされている統合パスが必要な場合は、identity & SCIM 統合 を使用してください。

アプリと同じように、本番 Oase バックエンド（api.oase.app）と通信します: サインイン → 招待リンクで参加 → KMS から oase キーを取得 → AES-256-GCM で暗号化 → POST .../messaging/messages。メッセージは oase の対称 AES-256-GCM キー（メインフレーム署名付きプルーフを介して KMS から取得）でクライアント側で暗号化されるため、アプリでは通常どおり表示されます。

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/。 REST クライアント上に MCP ツールサーフェスを提供します (server.ts)。すべてのツールはオンデマンドのリクエスト/レスポンスラッパーです。エントリーポイント: dist/index.js (claude mcp add oase -- node /path/to/dist/index.js)。

仕組み

• アイデンティティ。 Claude は、Oase アプリが使用するアイデンティティプロバイダーである Promise ユーザーとして、一度きりのブラウザログインでサインインします — ログイン を参照してください。結果として得られる長期有効な Oase リフレッシュトークンは ~/.oase-mcp/config.json（モード 0600）に保存されます。短期有効なアクセストークンはメモリに保持され、自動的に更新されます。

• 暗号化。 Oase は、バックエンドがエスクローする oase ごとの対称 AES-256-GCM キーでメッセージ内容を暗号化します。参加者は誰でも、メインフレーム署名付きプルーフを介して KMS から生の oase キーを取得できるため、暗号化/復号は簡単です — デバイスのキーペアや登録は不要です。アプリが期待するものと正確に同じ暗号バンドル形式を生成します。

• メッセージが平文で送信されることはありません — 送信エンドポイントは暗号バンドルを要求します。

セットアップ

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. Claude 用の Promise アカウントにサインインするか、作成します。ページに "Token captured" と表示されます。

3. promise_login_finish を呼び出します — トークンを永続的な Oase アイデンティティと交換します。

内部的には、サーバーは localhost の OIDC コールバックをホストし、リダイレクトから使い捨ての id_token を取得します — コピー＆ペーストは不要です。（すでに id_token を持っている場合は、login_with_promise が直接受け取ります。）

この交換により、Oase 独自の長期有効なリフレッシュトークン（Promise の person_id に関連付けられます）が返されるため、Promise に再度問い合わせることはありません — Promise の資格情報は保存されず、結果として得られる Oase リフレッシュトークンだけが保存されます。

ログインが必要です: Promise アイデンティティが確立されるまで、他のすべてのツール（join、send、read、ask）は拒否されます。

ツール

スレッドと返信

Oase のスレッドは 1 階層です: メッセージへのすべての返信は、そのメッセージのリソース ID（chat_id <oaseId>/m/<messageId>）の下に置かれ、返信への返信はできません — ネストされたスレッドはアプリに表示されないからです。サーバーはこれを強制します: 返信を指す thread_id は自動的にスレッドのルートメッセージに解決されるため、見えないネストされたチャットに迷い込むことはありません。メッセージに返信するには、その ID を thread_id として send_message に渡します。コンテキストを把握して ID を取得するには read_messages を使用します。

添付ファイル（画像、ボイスメッセージ、ファイル）

添付ファイル付きのメッセージは、すべての読み取り結果で [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 はメディア項目上の暗号バンドルとして送信されます（レガシー添付ファイルは署名付き CDN URL の背後にある平文 blob で、そのまま変更されずに通過します。giphy 添付ファイルは暗号化された giphy オブジェクトを介して解決されます）。

エージェントが受け取るもの：

• 画像（jpeg/png/gif/webp、最大 3 MB）は MCP 画像コンテンツとしてインラインで返されるため、エージェントは直接画像を確認し、応答で見た内容を利用できます。より大きな画像は保存されたファイルにフォールバックします。

• すべて は <tmpdir>/oase-mcp/media/<messageId>-<n>-<name> にも書き込まれ、そのパスが返されます。音声の場合（Claude はネイティブに音声を聞くことができません）、エージェントはローカルの音声テキスト変換ツール（macOS の hear や whisper など）で保存されたファイルを文字起こしし、その文字起こし結果を基に作業するよう促されます。ドキュメントは通常のファイルツールで開くことができます。

Blob ダウンロード URL はプロバイダーによって署名されており、約2日で期限切れになります。read_media はチャットプロジェクションを更新し、URL が失効している場合は1回再試行します。音声メッセージ / メディアのみのメッセージはテキスト本文が空で、read_messages では他のメッセージと同様に表示されます。

一般的なフロー

1. Claude をログインさせる：promise_login_start → URL を開く → promise_login_finish。

2. Oase アプリで、自分の oase を開く → 招待 → 参加リンクをコピー。

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 — mainframe API ルート（デフォルトは https://api.oase.app）。例：ステージングを指定。

• OASE_KMS_ROOT — KMS ルート（デフォルトは https://kms.oase.app/、末尾のスラッシュが必要）。

注意事項と制限事項

• oase の グループチャット（およびメッセージごとの返信スレッド）とその フィード投稿（send_post/read_posts — 送信時はテキストのみ。投稿のタイトルと本文は同じ oase キーの下にある別々の暗号バンドルです）で動作します。メディア添付ファイルの読み取り/復号（read_media）はできますが、送信はできません。プライベートな 1:1 チャットやレルムの参加承認フローには対応していません。

• 返信は入れ子にできません — スレッドの深さは1レベルまでです。それ自体が返信である thread_id は、スレッドのルートメッセージに暗黙的に解決されます（ベストエフォート：最新のチャットページより古いメッセージの場合は、その ID がそのまま使用されます）。

• 別の Promise アカウントでサインインすると、参加済みの oase がクリアされます。メンバーシップは個人単位であるため、その後 Claude を再招待してください。

• ~/.oase-mcp/config.json を削除すると、ID が忘れられます（Claude はログインして再招待される必要があります）。

• 多くのサーバープロセス（Claude セッションごとに1つ）が ~/.oase-mcp/config.json の ID を共有します。バックエンドは oauth2/refresh のたびにリフレッシュトークンをローテーションし、古いリフレッシュトークンを検出した場合はセッションを削除します（リプレイ防止）— そのため、アクセストークンは再利用のために永続化され、リフレッシュは ~/.oase-mcp/auth.lock を介してプロセス間で直列化され、ロック下で再読み取りが行われます。サーバーの実行中に oauth2/refresh を帯域外で呼び出さないでください。セッションが失効した場合は、ツールがその旨を通知します — promise_login_start で再ログインしてください。

ライセンス

MIT — LICENSE を参照。