oase-mcp

一个可以让 Claude 在 Oase 内聊天的 MCP 服务器。只要给 Claude 一个邀请链接，它就能在那个 oase 的群聊中发消息、向 oase 的动态发布帖子（opslag）、阅读对话并作出反应——非常适合发布状态更新、“我完成了 X”之类的消息，或者在你日后会看到的地方留言。

它是一个 REST 客户端：每个工具都是一次普通的请求/响应 HTTP 调用。

📖 文档： https://dev.oase.app/mcp/

状态 / 免责声明

这是实验性项目，按现状提供。它基于 Oase 的内部 API 构建，这些 API 可能随时更改，恕不另行通知——因此它可能随时失效、变化或被弃用，而且无法保证它今天能用，也无法保证明天还能继续用。不承诺提供支持：欢迎提交 issue（参见 SUPPORT.md），但也可能无人回复。如果你需要受支持的集成路径，请改用身份与 SCIM 集成。

与 Oase 生产后端（api.oase.app）的通信方式与应用完全一致：登录 → 通过邀请链接加入 → 从 KMS 获取 oase 密钥 → AES-256-GCM 加密 → POST .../messaging/messages。消息在客户端使用该 oase 的对称 AES-256-GCM 密钥进行加密（密钥通过 mainframe 签名的证明从 KMS 获取），因此它们在应用中能正常渲染。

Related MCP server: WAHA WhatsApp MCP Server

架构

该代码库是一个被动的 REST 客户端，上层是一个 MCP 服务器：

• 被动 REST 客户端 — src/client/。 所有知道如何通过 HTTP 与 Oase 通信的部分：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 通过一次性浏览器登录，以持久化的 Promise 用户身份登录（这是 Oase 应用使用的身份提供商）——参见登录。由此产生的长效 Oase 刷新令牌存储在 ~/.oase-mcp/config.json（模式 0600）中；短效访问令牌保存在内存中并自动刷新。

• 加密。 Oase 使用由后端代管的、每个 oase 独立的对称 AES-256-GCM 密钥对消息内容进行加密。任何参与者都可以通过 mainframe 签名的证明从 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 身份之前，所有其他工具（加入、发送、读取、询问）都会拒绝执行。

工具

线程与回复

Oase 中的线程只有一个层级：每条对某条消息的回复都位于该消息的资源 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 则作为密文捆绑包随媒体项一起传输（旧版附件是签名 CDN URL 后面的明文 blob，会原样通过；giphy 附件则通过其加密的 giphy 对象解析）。

Agent 获得的内容：

• 图片（jpeg/png/gif/webp，最大 3 MB）会以 MCP 图片内容的形式内联返回，因此 Agent 可以直接查看它们，并在回复中利用所看到的内容。更大的图片则回退到已保存的文件。

• 所有内容还会写入 <tmpdir>/oase-mcp/media/<messageId>-<n>-<name> 并返回该路径。对于音频（Claude 本身无法收听），会提示 Agent 使用本地语音转文字工具（例如 macOS 上的 hear 或 whisper）转写已保存的文件，并基于转写结果来处理；文档则可以用常规文件工具打开。

Blob 下载 URL 由服务商签名，约 ~2 天后过期；如果 URL 已失效，read_media 会刷新聊天投影并重试一次。语音消息/仅含媒体的消息没有文本正文，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），例如指向 staging。

• OASE_KMS_ROOT — KMS 根地址（默认 https://kms.oase.app/，要求结尾带斜杠）。

注意事项与限制

• 适用于 oase 的群聊（以及单条消息的回复线程）和动态帖子（send_post/read_posts — 发送时仅支持文本；帖子的标题和正文是同一个 oase 密钥下的独立密文捆绑包）。它可以读取/解密媒体附件（read_media），但不能发送；它不处理私密 1:1 聊天或 realm 加入审批流程。

• 回复不能嵌套 — 线程只有一层。本身是回复的 thread_id 会被静默解析为该线程的根消息（尽力而为：对于早于最新聊天页的消息，该 id 会原样使用）。

• 以不同的 Promise 账户登录会清除已加入的 oase，因为成员身份是因人而异的 — 之后需要重新邀请 Claude。

• 删除 ~/.oase-mcp/config.json 会丢失身份（Claude 必须重新登录并被重新邀请）。

• 多个服务器进程（每个 Claude 会话一个）共享 ~/.oase-mcp/config.json 中的身份。后端在每次 oauth2/refresh 时轮换刷新令牌，并且一旦看到过期的令牌就会删除会话（防重放）— 因此访问令牌会被持久化以供复用，刷新操作则通过 ~/.oase-mcp/auth.lock 跨进程串行化，并在锁内重新读取。服务器运行期间，不要在带外调用 oauth2/refresh；如果会话确实被吊销，工具会给出相应提示 — 请使用 promise_login_start 重新登录。

许可证

MIT — 参见 LICENSE。