oase-mcp

Claude가 Oase 안에서 채팅할 수 있게 해주는 MCP 서버입니다. Claude에게 초대 링크를 주면 해당 oase의 그룹 채팅에 게시하고, oase 피드에 포스트(opslag)를 발행하고, 대화를 읽고, 반응할 수 있습니다. 상태 업데이트, "I finished X", 또는 나중에 볼 메모를 남기기에 유용합니다.

REST 클라이언트입니다. 모든 도구는 단순한 요청/응답 HTTP 호출입니다.

📖 문서: https://dev.oase.app/mcp/

상태 / 면책 조항

이 프로젝트는 실험적이며 있는 그대로 제공됩니다. Oase의 내부 API를 기반으로 하며, 이 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/. 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 앱이 사용하는 ID 공급자)로 로그인합니다 — 로그인 참조. 그 결과로 생성된 수명이 긴 Oase 갱신 토큰은 ~/.oase-mcp/config.json(모드 0600)에 저장됩니다. 수명이 짧은 액세스 토큰은 메모리에 보관되었다가 자동으로 갱신됩니다.

• 암호화. Oase는 백엔드가 에스크로(escrow)로 보관하는 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의 스레드는 한 단계뿐입니다. 메시지에 대한 모든 답글은 해당 메시지의 리소스 id(chat_id <oaseId>/m/<messageId>) 아래에 있으며, 답글에 답글을 달 수 없습니다 — 중첩 스레드는 앱에 표시되지 않습니다. 서버는 이를 강제합니다. 답글을 가리키는 thread_id는 자동으로 스레드의 루트 메시지로 확인되므로 어떤 메시지도 보이지 않는 중첩 채팅에 들어가지 않습니다. 메시지에 답글을 달려면 해당 id를 send_message의 thread_id로 전달하세요. 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 객체를 통해 확인됩니다).

에이전트가 돌려받는 것:

• 이미지(jpeg/png/gif/webp 최대 3MB)는 MCP 이미지 콘텐츠로 인라인 반환되므로, 에이전트가 직접 보고 응답에 사용할 수 있습니다. 더 큰 이미지는 저장된 파일로 대체됩니다.

• 모든 것은 또한 <tmpdir>/oase-mcp/media/<messageId>-<n>-<name>에 기록되고 경로가 반환됩니다. 오디오의 경우(Claude는 기본적으로 들을 수 없음) 에이전트는 로컬 음성-텍스트 도구(예: macOS의 hear 또는 whisper)로 저장된 파일을 전사하고 그 전사본을 사용하도록 안내됩니다; 문서는 일반 파일 도구로 열 수 있습니다.

Blob 다운로드 URL은 공급자(provider)가 서명하며 약 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 — mainframe API 루트(기본값 https://api.oase.app), 예: 스테이징을 가리킬 때.

• 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를 참조하세요.