multi-workspace-for-notion 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 heoeunseo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,238 @@
+<h1 align="center">Multi-Workspace for Notion</h1>
+
+<p align="center"><em>Claude Code 하나로 모든 Notion 워크스페이스를. 공식 도구는 그대로.</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-111111?style=flat-square" alt="Version 0.1.0">
+  <img src="https://img.shields.io/badge/Claude%20Code-plugin-111111?style=flat-square" alt="Claude Code plugin">
+  <img src="https://img.shields.io/badge/platform-macOS-111111?style=flat-square" alt="macOS">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
+</p>
+
+<p align="center"><sub><a href="README.md">English</a> &middot; <a href="README.ko.md">한국어</a></sub></p>
+
+---
+
+Claude Code에서 여러 Notion 워크스페이스를 동시에 쓸 수 있게 해 줍니다. 공식 Notion MCP 서버의 도구를 하나도 빠짐없이 그대로 씁니다.
+
+> **상태: 개발 초기 (v0.1.0).** 워크스페이스 연결과 공식 도구 전달은 동작하며, 실제 워크스페이스 두 개를 Claude Code에 연결해 시험했습니다. 계획한 기능 중 아직 없는 것이 여럿 있습니다. [로드맵](#로드맵)과 [알려진 제약](#알려진-제약)을 참고하세요.
+>
+> 비공식 프로젝트입니다. Notion Labs, Inc.와 관계가 없고 Notion의 승인을 받지 않았습니다.
+
+## 왜 만들었나
+
+Notion 공식 MCP 커넥터는 연결 하나에 워크스페이스 하나만 붙습니다. 다른 워크스페이스를 쓰려면 연결을 끊고 다시 로그인해야 하고, 그동안 다른 대화에도 영향을 줍니다. claude.ai는 같은 URL(`https://mcp.notion.com/mcp`)로 커넥터를 하나 더 추가하는 것도 막습니다.
+
+Claude Code에서는 같은 URL을 이름만 다르게 두 번 등록할 수 있습니다. 하지만 이런 문제가 있습니다.
+
+- 연결마다 도구 전체(약 65개)가 복제됩니다. 워크스페이스가 2개면 약 130개, 3개면 약 195개가 됩니다.
+- Notion 로그인 화면에서 실제로 어느 워크스페이스를 골랐는지 아무도 확인하지 않습니다. 그래서 `notion-work`라고 이름 붙인 연결이 개인 워크스페이스를 가리키고 있어도 모르고 지나갈 수 있습니다.
+- 모든 워크스페이스를 한 번에 검색하는 것처럼 워크스페이스를 넘나드는 기능이 없습니다.
+
+다른 오픈소스 프로젝트들은 Notion REST API를 직접 호출하고, 직접 만든 도구 몇 개만 제공합니다. 이 프로젝트는 공식 호스팅 서버 앞에 서서 공식 도구를 그대로 넘겨주므로, Notion이 도구를 바꾸면 자동으로 따라갑니다.
+
+## 동작 방식
+
+```
+Claude Code
+    │  stdio (Claude가 서버를 자식 프로세스로 실행)
+    ▼
+Multi-Workspace for Notion  (로컬 Node 프로세스)
+    │  호출마다 workspace 값을 보고 보낼 곳을 고름
+    ├──▶ mcp.notion.com   [personal]
+    ├──▶ mcp.notion.com   [work]
+    └──▶ mcp.notion.com   [...]
+```
+
+- **워크스페이스마다 OAuth 클라이언트 하나.** 워크스페이스를 연결하면 서버가 Notion MCP 서버에 클라이언트로 등록하고(Dynamic Client Registration), PKCE로 로그인하고, 임시 `localhost` 포트로 인증 결과를 받습니다.
+- **고른 워크스페이스를 확인합니다.** 로그인 직후 `notion-get-self`를 호출해 실제 워크스페이스 이름과 ID를 기록합니다. 이미 연결된 워크스페이스를 또 고르면 거부합니다.
+- **공식 도구를 한 번만 노출합니다.** 도구마다 필수 파라미터 `workspace` 하나가 더 붙습니다. 이 파라미터에 넣을 수 있는 값은 그 도구가 있는 워크스페이스뿐이라, 요금제에 따라 없는 도구가 엉뚱한 워크스페이스로 가지 않습니다. 그 밖의 호출 내용과 결과는 손대지 않고 그대로 전달합니다.
+- **연결된 워크스페이스를 Claude에게 알려 줍니다.** 서버 안내문(instructions)에 각 워크스페이스의 별칭, 실제 이름, 설명을 넣습니다. 워크스페이스가 불분명하면 쓰기 전에 사용자에게 물으라는 내용도 넣고, 그 뒤에 Notion 공식 안내문을 붙입니다.
+
+Claude가 보내는 호출은 이런 모양입니다.
+
+```json
+{ "name": "notion-search", "arguments": { "workspace": "work", "query": "roadmap" } }
+```
+
+## 필요한 것
+
+- macOS (내장 `security` 명령으로 키체인에 토큰을 저장합니다)
+- Node.js 20 이상
+- Claude Code
+
+## Claude Code 플러그인으로 설치 (추천)
+
+이 저장소는 Claude Code 플러그인 마켓플레이스입니다. 플러그인에 MCP 서버가 파일 하나로 묶여 들어 있어서 따로 빌드할 필요가 없습니다.
+
+```bash
+claude plugin marketplace add heoeunseo08/multi-workspace-for-notion
+claude plugin install multi-workspace@multi-workspace-for-notion
+```
+
+지금은 저장소가 비공개라서, 저장소를 읽을 수 있는 계정에서만 설치됩니다.
+
+Claude Code 세션을 새로 연 뒤 워크스페이스마다 연결합니다.
+
+```
+/multi-workspace:workspace-add personal 개인 메모
+/multi-workspace:workspace-add work 회사 위키
+```
+
+브라우저에 Notion 로그인 화면이 열리면, 이 별칭으로 연결할 워크스페이스를 골라 승인하세요. 그러면 Claude가 실제로 연결된 워크스페이스를 알려 줍니다. 의도한 워크스페이스가 아니면 지우고 다시 추가하세요. 새로 연결한 워크스페이스의 도구는 다음 대화부터 보입니다.
+
+- 별칭은 영어 소문자나 숫자로 시작하고, 영어 소문자·숫자·`-`·`_`만 쓸 수 있습니다(최대 32자).
+- 설명은 넣지 않아도 됩니다. Claude가 이 설명을 보고 워크스페이스를 고르므로, 그 워크스페이스에 무엇이 있는지 몇 마디 적어 두면 도움이 됩니다.
+- 로그인은 최대 10분까지 기다립니다.
+
+claude.ai Notion 커넥터도 켜져 있으면 Claude에게 Notion 도구가 두 벌 보입니다. 이 플러그인을 쓰는 곳에서는 그 커넥터를 꺼서 Claude가 헷갈리지 않게 하세요.
+
+그다음에는 평소 말투로 요청하면 됩니다. 예를 들어 "회사 노션과 개인 노션에서 각각 '로드맵'을 검색해 줘"라고 하면, Claude가 별칭과 설명을 보고 `workspace` 값을 고릅니다.
+
+## 스킬
+
+| 스킬 | 하는 일 |
+| --- | --- |
+| `/multi-workspace:workspace-list` | 연결된 워크스페이스를 실제 이름, 설명, 상태와 함께 보여줍니다. |
+| `/multi-workspace:workspace-add <별칭> [설명]` | 브라우저로 워크스페이스를 연결하고, 실제로 어느 워크스페이스를 골랐는지 보여줍니다. |
+| `/multi-workspace:workspace-remove <별칭>` | 확인을 받은 뒤, 이 컴퓨터에서 그 워크스페이스의 토큰과 설정을 지우고 Notion 쪽 토큰도 해제합니다. |
+| `/multi-workspace:workspace-rename <별칭> [새 별칭] [새 설명]` | 다시 로그인하지 않고 별칭이나 설명을 바꿉니다. |
+| `/multi-workspace:workspace-check [별칭]` | 저장된 토큰으로 다시 로그인해서, 워크스페이스가 아직 동작하는지와 처음 연결한 그 워크스페이스가 맞는지 확인합니다. |
+| `/multi-workspace:workspace-help` | 스킬, 도구, 요청 예를 한 화면에 보여줍니다. |
+
+`workspace-add`와 `workspace-remove`는 직접 입력했을 때만 실행됩니다. Claude가 알아서 실행하지 않습니다.
+
+새 세션을 열 때마다 `Notion: personal(허 은서의 Notion), work(회사)`처럼 연결 상태가 한 줄로 표시되고, 확인이 필요한 워크스페이스가 있으면 `workspace-check`를 안내합니다.
+
+## Claude Desktop 확장(`.mcpb`, 아직 시험 전)
+
+```bash
+npm install
+npm run pack:mcpb    # multi-workspace-for-notion.mcpb 생성
+```
+
+이 파일을 Claude Desktop으로 열어 설치한 뒤, Claude에게 워크스페이스를 연결해 달라고 하면 됩니다(`workspace_connect`). Desktop에는 플러그인 스킬이 없으니 도구를 바로 씁니다. 아직 Claude Desktop에서 시험하지 않은 방법입니다.
+
+## 소스에서 설치
+
+코드를 고치거나 플러그인 없이 서버만 쓰고 싶을 때 이 방법을 씁니다.
+
+```bash
+git clone https://github.com/heoeunseo08/multi-workspace-for-notion.git
+cd multi-workspace-for-notion
+npm install
+npm run build
+node dist/index.js add personal "개인 메모"
+claude mcp add --scope user multi-workspace -- node /absolute/path/to/multi-workspace-for-notion/dist/index.js
+```
+
+그다음 `claude mcp list`에서 `multi-workspace`가 연결됐는지 확인하세요.
+
+## CLI 명령
+
+| 명령 | 하는 일 |
+| --- | --- |
+| `node dist/index.js` | MCP 서버를 stdio로 실행합니다. Claude가 실행하는 명령이라 직접 쓸 일은 없습니다. |
+| `node dist/index.js list` | 연결된 워크스페이스 목록을 보여줍니다: 별칭, 실제 워크스페이스 이름, 상태, 설명 |
+| `node dist/index.js add <별칭> [설명...]` | 브라우저 로그인으로 워크스페이스를 연결합니다. |
+| `node dist/index.js tools <별칭>` | 저장된 토큰으로 붙어서 워크스페이스를 확인하고 도구 목록을 보여줍니다. 연결이 아직 살아 있는지 확인할 때 씁니다. |
+| `node dist/index.js rename <별칭> <새 별칭>` | 다시 로그인하지 않고 별칭을 바꿉니다. |
+| `node dist/index.js remove <별칭>` | 이 컴퓨터에서 워크스페이스의 토큰과 설정을 지우고 Notion 쪽 토큰도 해제합니다. |
+
+## Claude에게 보이는 도구
+
+| 도구 | 설명 |
+| --- | --- |
+| 모든 공식 Notion 도구 | 이름, 설명, 옵션은 그대로이고 필수 파라미터 `workspace`가 하나 붙습니다. 읽기 도구가 그 워크스페이스에서 ID를 찾지 못하면 다른 워크스페이스에서 다시 시도하고, 어느 워크스페이스에서 찾았는지 알려 줍니다. 쓰기 도구는 고르지 않은 워크스페이스로 보내지 않습니다. |
+| `search_all_workspaces` | 모든 워크스페이스에서 `notion-search`를 동시에 실행하고 결과를 워크스페이스별로 묶어 보여줍니다. 워크스페이스가 둘 이상 연결돼 있을 때만 보입니다. |
+| `workspace_list` | 연결된 워크스페이스를 보여줍니다: 별칭, 설명, 실제 워크스페이스 이름과 ID, 상태, 연결을 마지막으로 확인한 시각 |
+| `workspace_connect` | 브라우저로 워크스페이스를 연결합니다(최대 10분 기다림). |
+| `workspace_disconnect` | 이 컴퓨터에서 워크스페이스의 토큰과 설정을 지우고 Notion 쪽 토큰도 해제합니다. 되돌릴 수 없는 작업으로 표시돼 있어 Claude가 먼저 확인을 받습니다. |
+| `workspace_rename` | 다시 로그인하지 않고 별칭이나 설명을 바꿉니다. 새 별칭은 새 대화부터 쓸 수 있습니다. |
+| `workspace_check` | 저장된 토큰으로 다시 로그인해서 워크스페이스를 확인하고 상태를 갱신합니다. |
+
+## 데이터 저장 위치
+
+| 무엇 | 어디 |
+| --- | --- |
+| OAuth 토큰과 클라이언트 등록 정보 | macOS 키체인. 서비스 `multi-workspace-for-notion`, 계정 `workspace:<별칭>` |
+| 별칭, 설명, 실제 워크스페이스 이름과 ID | `~/.config/multi-workspace-for-notion/config.json` |
+| 도구 목록과 안내문 캐시 | `~/.config/multi-workspace-for-notion/cache/` |
+| 토큰 저장용 잠금 파일 | `~/.config/multi-workspace-for-notion/locks/` |
+
+다른 폴더를 쓰려면 `MWN_CONFIG_DIR`을 설정하세요. 파일은 본인만 읽고 쓸 수 있는 권한으로 만들고, 토큰은 절대 들어가지 않습니다.
+
+## 보안
+
+- 서버는 Claude와 stdio로 통신하고, 평소에는 네트워크 포트를 열지 않습니다.
+- 로그인하는 동안에만 인증 결과를 받는 서버가 `127.0.0.1`과 `::1`에서 기다립니다. 응답 하나만 받고, OAuth `state`를 확인한 뒤 바로 닫습니다.
+- 토큰은 키체인에만 있습니다. `security` 명령의 표준 입력으로 넘기므로 프로세스 목록에도 보이지 않습니다.
+- `remove`는 이 컴퓨터의 토큰을 먼저 지운 뒤 Notion 쪽 토큰을 해제합니다(RFC 7009). 오프라인 등으로 해제에 실패하면 결과에 표시되니, 그때는 Notion 설정의 연결(Connections) 메뉴에서 직접 해제하세요.
+
+## 알려진 제약
+
+- **claude.ai 웹과 모바일에서는 쓸 수 없습니다.** 웹과 모바일의 커스텀 커넥터는 원격 URL만 받습니다.
+- **Claude Desktop은 아직 시험하지 않았습니다.**
+- **macOS만 지원합니다.** 키체인을 쓰기 때문입니다.
+- **새로 연결한 워크스페이스는 새 대화부터 보입니다.** Claude가 대화마다 도구 목록을 캐시합니다.
+- **다른 세션이 토큰을 갱신하는 도중에 별칭을 바꾸면** 새 별칭에 Notion이 이미 바꾼 refresh 토큰이 남을 수 있습니다. 인증 저장, 별칭 변경, 연결 해제는 같은 잠금을 쓰므로 갱신 요청 자체가 별칭 변경과 겹칠 때만 생깁니다. 생기면 `workspace-check`가 알려 주고, 그 워크스페이스를 다시 연결해야 합니다.
+- **MCP resources와 prompts는 넘겨주지 않습니다.** Notion의 `notion://docs/...` 문서는 `notion-fetch`로 읽을 수 있고, 서버가 Claude에게 그렇게 하라고 안내합니다.
+- **시작할 때 워크스페이스마다 도구 목록을 받습니다**(워크스페이스 2개 기준 약 1초). 15초 안에 받지 못한 워크스페이스는 마지막으로 캐시해 둔 목록을 씁니다.
+
+## 문제 해결
+
+| 문제 | 해결 방법 |
+| --- | --- |
+| 워크스페이스 추가가 시간 초과로 끝남 | 로그인 화면이 실제로 열렸는지 확인하세요. CLI로 추가할 때는 출력된 주소로 직접 들어가 10분 안에 승인할 수 있습니다. |
+| 다른 워크스페이스가 연결됨 | 지우고 다시 추가하면서 Notion 화면에서 맞는 워크스페이스를 고르세요. |
+| "이미 연결되어 있습니다" 오류 | 그 Notion 워크스페이스가 다른 별칭으로 이미 연결돼 있습니다. `/multi-workspace:workspace-list`로 확인하세요. |
+| 인증이 만료됐다는 오류로 호출이 실패함 | `/multi-workspace:workspace-check`로 확인한 뒤, 그 워크스페이스를 지우고 다시 추가하세요. |
+| Claude가 엉뚱한 Notion 도구를 씀 | 이 플러그인을 쓰는 곳에서 claude.ai Notion 커넥터를 끄세요. |
+
+## 로드맵
+
+- [x] 워크스페이스 연결 (DCR, PKCE, localhost 콜백, 키체인, 워크스페이스 확인)
+- [x] 공식 도구에 `workspace` 파라미터를 붙여 전달, 요금제에 따른 도구 차이 처리
+- [x] 워크스페이스 관리를 MCP 도구와 플러그인 스킬로: 연결, 해제, 확인
+- [x] `workspace_rename`: 다시 로그인하지 않고 별칭이나 설명 바꾸기
+- [x] `search_all_workspaces`: 모든 워크스페이스를 한 번에 검색하고 결과에 출처 표시
+- [x] 토큰 갱신에 파일 잠금을 걸어 여러 프로세스가 같은 워크스페이스를 안전하게 쓰기
+- [x] 페이지 ID로 하는 호출이 실패하면 그 페이지가 실제로 있는 워크스페이스로 다시 보내기
+- [x] 워크스페이스를 지울 때 Notion 쪽 접근 권한도 해제
+- [x] Claude Code 플러그인
+- [x] 패키징: npm 패키지는 의존성 없이 묶은 서버 하나만 담고, `npm run pack:mcpb`로 Claude Desktop 확장을 만든다
+- [ ] npm에 배포하고, Claude Desktop에서 확장 시험하기
+
+## 개발
+
+```bash
+npm install
+npm run typecheck
+npm test             # 단위 테스트
+npm run build        # dist/로 컴파일하고 plugin/server.mjs로 묶음
+npm run dev          # 소스에서 바로 MCP 서버(stdio) 실행
+npm run dev -- list  # 소스에서 바로 CLI 실행
+npm run pack:mcpb    # Claude Desktop 확장
+```
+
+| 파일 | 역할 |
+| --- | --- |
+| `src/index.ts` | 진입점. 인자가 없으면 MCP 서버, 있으면 CLI |
+| `src/server.ts` | MCP 서버, 도구 목록, 안내문 |
+| `src/management.ts` | 워크스페이스 관리 도구 |
+| `src/proxy.ts` | 워크스페이스별 도구 목록을 합치고 호출을 보낼 곳을 고름 |
+| `src/upstream.ts` | 워크스페이스별 업스트림 세션, 도구 목록 캐시 |
+| `src/connect.ts` | 워크스페이스 연결, 다시 붙기, 지우기 |
+| `src/lock.ts` | 인증 저장을 감싸는, 서버 프로세스끼리 공유하는 잠금 |
+| `src/oauth.ts` | 키체인을 쓰는 OAuth 클라이언트 |
+| `src/callback-server.ts` | 인증 결과를 받는 임시 서버 |
+| `src/keychain.ts` | `security` 명령으로 키체인에 저장 |
+| `src/notion.ts` | 공식 Notion MCP 서버에 붙는 클라이언트 세션 |
+| `src/config.ts` | 비밀이 아닌 설정 파일 |
+| `plugin/server.mjs` | 플러그인이 실행하는, 하나로 묶은 서버 파일. `src/`를 고치면 `npm run build`로 다시 만들어 함께 커밋합니다. |
+| `manifest.json`, `.mcpbignore` | Claude Desktop 확장 매니페스트와 거기서 뺄 파일 |
+| `.claude-plugin/`, `skills/` | 플러그인 정보, 마켓플레이스 항목, 스킬 |
+
+## 라이선스
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+<h1 align="center">Multi-Workspace for Notion</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><em>One Claude Code, every Notion workspace. The official tools, untouched.</em></p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.1.0-111111?style=flat-square" alt="Version 0.1.0">
+  <img src="https://img.shields.io/badge/Claude%20Code-plugin-111111?style=flat-square" alt="Claude Code plugin">
+  <img src="https://img.shields.io/badge/platform-macOS-111111?style=flat-square" alt="macOS">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
+</p>
+
+<p align="center"><sub><a href="README.md">English</a> &middot; <a href="README.ko.md">한국어</a></sub></p>
+
+---
+
+Use several Notion workspaces at the same time from Claude Code, with every tool the official Notion MCP server offers.
+
+> **Status: early development (v0.1.0).** Connecting workspaces and proxying the official tools work and have been tested with two real workspaces in Claude Code. Several planned pieces are still missing; see [Roadmap](#roadmap) and [Known limitations](#known-limitations).
+>
+> This is an unofficial project. It is not affiliated with or endorsed by Notion Labs, Inc.
+
+## Why
+
+Notion's official MCP connector links one workspace per connection. To switch, you disconnect and sign in again, which affects every other conversation too. claude.ai also refuses to add a second connector with the same URL (`https://mcp.notion.com/mcp`).
+
+Claude Code does let you register that URL twice under different names, but:
+
+- every connection copies the full tool set (about 65 tools), so two workspaces mean about 130 tools and three mean about 195;
+- nothing checks which workspace you actually picked on Notion's sign-in page, so `notion-work` can quietly end up pointing at your personal workspace;
+- nothing works across workspaces, such as searching all of them at once.
+
+Other open-source projects call the Notion REST API directly and expose a handful of hand-written tools. This project instead sits in front of the official hosted server, so you get the official tools as they are, and pick up Notion's changes to them automatically.
+
+## How it works
+
+```
+Claude Code
+    │  stdio (Claude starts the server as a child process)
+    ▼
+Multi-Workspace for Notion  (local Node process)
+    │  routes each call by its `workspace` argument
+    ├──▶ mcp.notion.com   [personal]
+    ├──▶ mcp.notion.com   [work]
+    └──▶ mcp.notion.com   [...]
+```
+
+- **One OAuth client per workspace.** When you connect a workspace, the server registers itself with Notion's MCP server (Dynamic Client Registration), signs in with PKCE, and receives the callback on a temporary `localhost` port.
+- **Checks the workspace you picked.** Right after sign-in it calls `notion-get-self` and records the real workspace name and ID. Picking a workspace that is already connected is refused.
+- **Exposes the official tools once.** Each tool gets one extra, required `workspace` parameter. Its allowed values are the workspaces that have that tool, so tools missing from some plans can't be sent to the wrong workspace. Everything else about the call and its result passes through unchanged.
+- **Tells Claude what is connected.** The server's instructions list each workspace's alias, real name and description, ask Claude to confirm the workspace before writing when it is unclear, and then include Notion's own instructions.
+
+What Claude sends looks like this:
+
+```json
+{ "name": "notion-search", "arguments": { "workspace": "work", "query": "roadmap" } }
+```
+
+## Requirements
+
+- macOS (tokens are stored in the Keychain through the built-in `security` command)
+- Node.js 20 or newer
+- Claude Code
+
+## Install as a Claude Code plugin (recommended)
+
+The repository is a Claude Code plugin marketplace. The plugin ships the MCP server as one bundled file, so there is nothing to build.
+
+```bash
+claude plugin marketplace add heoeunseo08/multi-workspace-for-notion
+claude plugin install multi-workspace@multi-workspace-for-notion
+```
+
+The repository is private for now, so this works only for accounts that can read it.
+
+Start a new Claude Code session, then connect each workspace:
+
+```
+/multi-workspace:workspace-add personal My personal notes
+/multi-workspace:workspace-add work Company wiki
+```
+
+Your browser opens Notion's sign-in page: choose the workspace you want for this alias and approve. Claude then shows which workspace was actually connected. If it is not the one you meant, remove it and add it again. Tools for a newly connected workspace appear in the next conversation.
+
+- An alias starts with a lowercase letter or digit and may contain lowercase letters, digits, `-` and `_` (up to 32 characters).
+- The description is optional. Claude sees it, so a few words about what lives in the workspace help it choose.
+- Sign-in waits up to 10 minutes.
+
+If the claude.ai Notion connector is also enabled, Claude sees two sets of Notion tools. Turn that connector off where you use this plugin so Claude doesn't mix them up.
+
+Then ask in plain language, for example "Search for 'roadmap' in both my work and personal Notion". Claude picks the `workspace` value from the aliases and descriptions.
+
+## Skills
+
+| Skill | What it does |
+| --- | --- |
+| `/multi-workspace:workspace-list` | Shows connected workspaces with their real names, descriptions and status. |
+| `/multi-workspace:workspace-add <alias> [description]` | Connects a workspace through the browser and shows which workspace you actually picked. |
+| `/multi-workspace:workspace-remove <alias>` | Asks for confirmation, then deletes the workspace's tokens and settings from this computer and revokes the tokens on Notion's side. |
+| `/multi-workspace:workspace-rename <alias> [new-alias] [description]` | Changes an alias or description without signing in again. |
+| `/multi-workspace:workspace-check [alias]` | Signs in again with the saved tokens and checks each workspace still works and is the one you connected. |
+| `/multi-workspace:workspace-help` | Shows the skills, tools and example requests on one screen. |
+
+`workspace-add` and `workspace-remove` run only when you type them; Claude doesn't start them on its own.
+
+Each new session also starts with a one-line status, such as `Notion: personal(My Notion), work(Acme)`, and points you to `workspace-check` when a workspace needs attention.
+
+## Claude Desktop extension (`.mcpb`, not tested yet)
+
+```bash
+npm install
+npm run pack:mcpb    # writes multi-workspace-for-notion.mcpb
+```
+
+Open the file with Claude Desktop to install it, then ask Claude to connect a workspace (`workspace_connect`). Desktop has no plugin skills, so use the tools directly. This path has not been tested in Claude Desktop yet.
+
+## Install from source
+
+Use this to work on the code, or to run the server without the plugin.
+
+```bash
+git clone https://github.com/heoeunseo08/multi-workspace-for-notion.git
+cd multi-workspace-for-notion
+npm install
+npm run build
+node dist/index.js add personal "My personal notes"
+claude mcp add --scope user multi-workspace -- node /absolute/path/to/multi-workspace-for-notion/dist/index.js
+```
+
+Then check that `multi-workspace` shows as connected in `claude mcp list`.
+
+## CLI reference
+
+| Command | What it does |
+| --- | --- |
+| `node dist/index.js` | Runs the MCP server over stdio. Claude runs this; you don't need to. |
+| `node dist/index.js list` | Lists connected workspaces: alias, real workspace name, status, description. |
+| `node dist/index.js add <alias> [description...]` | Connects a workspace through the browser. |
+| `node dist/index.js tools <alias>` | Signs in with the saved tokens, confirms the workspace, and lists its tools. Useful to check a connection still works. |
+| `node dist/index.js rename <alias> <new-alias>` | Changes an alias without signing in again. |
+| `node dist/index.js remove <alias>` | Deletes the workspace's tokens and settings from this computer and revokes the tokens on Notion's side. |
+
+CLI messages are currently in Korean.
+
+## Tools exposed to Claude
+
+| Tool | Description |
+| --- | --- |
+| Every official Notion tool | Same name, description and options, plus a required `workspace` parameter. If a read-only tool can't find an ID in that workspace, it is retried in the others and the result says which workspace has it. Write tools are never sent to a workspace you didn't pick. |
+| `search_all_workspaces` | Runs `notion-search` in every workspace at once and groups the results by workspace. Shown when two or more workspaces are connected. |
+| `workspace_list` | Shows the connected workspaces: alias, description, real workspace name and ID, status, and when the connection was last confirmed. |
+| `workspace_connect` | Connects a workspace through the browser (waits up to 10 minutes). |
+| `workspace_disconnect` | Deletes a workspace's tokens and settings from this computer and revokes the tokens on Notion's side. Marked destructive, so Claude asks first. |
+| `workspace_rename` | Changes an alias or description without signing in again. A new alias is usable from the next conversation. |
+| `workspace_check` | Signs in again with the saved tokens, confirms the workspace and updates its status. |
+
+## Where data is stored
+
+| What | Where |
+| --- | --- |
+| OAuth tokens and client registration | macOS Keychain, service `multi-workspace-for-notion`, account `workspace:<alias>` |
+| Aliases, descriptions, real workspace names and IDs | `~/.config/multi-workspace-for-notion/config.json` |
+| Cached tool lists and instructions | `~/.config/multi-workspace-for-notion/cache/` |
+| Lock files for saving tokens | `~/.config/multi-workspace-for-notion/locks/` |
+
+Set `MWN_CONFIG_DIR` to use a different directory. Files are written with owner-only permissions and never contain tokens.
+
+## Security
+
+- The server talks to Claude over stdio and opens no network port in normal use.
+- While you sign in, a callback server listens on `127.0.0.1` and `::1` only. It accepts one response, checks the OAuth `state`, then closes.
+- Tokens live only in the Keychain. They are written through `security`'s standard input, so they never appear in the process list.
+- `remove` deletes the tokens from this computer first, then revokes them on Notion's side (RFC 7009). If revoking fails, for example offline, the result says so; remove the connection in Notion's settings under Connections.
+
+## Known limitations
+
+- **claude.ai web and mobile are not supported.** Their custom connectors accept only remote URLs.
+- **Claude Desktop is not tested yet.**
+- **macOS only**, because of the Keychain.
+- **A newly connected workspace appears in new conversations.** Claude caches the tool list per conversation.
+- **Renaming a workspace while another session is refreshing its token** can leave the new alias with a refresh token Notion has already replaced. Credential saves, renames and disconnects share a lock, so this needs the refresh request itself to overlap the rename; if it happens, `workspace-check` reports it and the workspace has to be connected again.
+- **MCP resources and prompts are not proxied.** Notion's `notion://docs/...` documents can still be read with `notion-fetch`; the server tells Claude to do so.
+- **Startup fetches each workspace's tool list** (about a second for two workspaces). If a workspace can't be reached within 15 seconds, the last cached list is used.
+
+## Troubleshooting
+
+| Problem | What to do |
+| --- | --- |
+| Adding a workspace times out | Make sure the sign-in page actually opened. With the CLI, you can open the printed URL yourself and approve within 10 minutes. |
+| The wrong workspace was connected | Remove it, then add it again and choose the right workspace on Notion's page. |
+| "already connected" | That Notion workspace is already linked under another alias. Check with `/multi-workspace:workspace-list`. |
+| Calls fail with an expired-sign-in error | Run `/multi-workspace:workspace-check`, then remove and add the workspace again. |
+| Claude uses the wrong Notion tools | Turn off the claude.ai Notion connector where you use this plugin. |
+
+## Roadmap
+
+- [x] Connect workspaces (DCR, PKCE, localhost callback, Keychain, workspace check)
+- [x] Proxy the official tools with a `workspace` parameter and per-plan availability
+- [x] Workspace management as MCP tools and plugin skills: connect, disconnect, check
+- [x] `workspace_rename`: change an alias or description without signing in again
+- [x] `search_all_workspaces`: search every workspace at once, results labelled by workspace
+- [x] File lock around token refresh so several processes can share a workspace safely
+- [x] Retry calls that use a page ID in the workspace that actually owns the page
+- [x] Revoke access on Notion's side when removing a workspace
+- [x] Claude Code plugin
+- [x] Packaging: the npm package ships only the bundled server, with no dependencies; `npm run pack:mcpb` builds a Claude Desktop extension
+- [ ] Publish to npm, and test the extension in Claude Desktop
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test             # unit tests
+npm run build        # compiles to dist/ and bundles plugin/server.mjs
+npm run dev          # MCP server over stdio, from source
+npm run dev -- list  # CLI, from source
+npm run pack:mcpb    # Claude Desktop extension
+```
+
+| File | Role |
+| --- | --- |
+| `src/index.ts` | Entry point: MCP server without arguments, CLI otherwise |
+| `src/server.ts` | MCP server, tool list, instructions |
+| `src/management.ts` | Workspace management tools |
+| `src/proxy.ts` | Merges workspaces' tool lists and routes calls |
+| `src/upstream.ts` | Upstream session per workspace, tool list cache |
+| `src/connect.ts` | Connect, reopen and remove a workspace |
+| `src/lock.ts` | Lock shared by server processes, around credential saves |
+| `src/oauth.ts` | OAuth client provider backed by the Keychain |
+| `src/callback-server.ts` | Temporary OAuth callback server |
+| `src/keychain.ts` | Keychain storage through `security` |
+| `src/notion.ts` | Client session to the official Notion MCP server |
+| `src/config.ts` | Non-secret settings file |
+| `plugin/server.mjs` | Bundled server the plugin runs. Rebuild with `npm run build` and commit it whenever `src/` changes. |
+| `manifest.json`, `.mcpbignore` | Claude Desktop extension manifest and the files it leaves out |
+| `.claude-plugin/`, `skills/` | Plugin manifest, marketplace entry and skills |
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "multi-workspace-for-notion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json && npm run bundle",
+    "start": "node dist/index.js",
+    "test": "node --import tsx --test 'src/**/*.test.ts'",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --legal-comments=none --outfile=plugin/server.mjs --banner:js=\"import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);\"",
+    "pack:mcpb": "npm run build && npx -y @anthropic-ai/mcpb@2 pack . multi-workspace-for-notion.mcpb",
+    "prepublishOnly": "npm run build"
+  },
+  "type": "module",
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@types/node": "^26.6.5",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "zod": "^4.6.7"
+  },
+  "description": "Use several Notion workspaces at once from Claude Code and Claude Desktop, with the official Notion MCP tools",
+  "license": "MIT",
+  "author": "heoeunseo",
+  "bin": {
+    "multi-workspace-for-notion": "plugin/server.mjs"
+  },
+  "files": [
+    "plugin/server.mjs"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "notion",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heoeunseo08/multi-workspace-for-notion.git"
+  },
+  "os": [
+    "darwin"
+  ]
+}