nworks 0.7.0 → 1.1.0

package/README.md

@@ -1,85 +1,158 @@
 # nworks
 
-NAVER WORKS CLI — built for humans and AI agents.
+[![npm version](https://img.shields.io/npm/v/nworks.svg)](https://www.npmjs.com/package/nworks)
+[![license](https://img.shields.io/npm/l/nworks.svg)](LICENSE)
+[![npm downloads](https://img.shields.io/npm/dm/nworks.svg)](https://www.npmjs.com/package/nworks)
 
-## Install
+<p align="center">
+  <img src="assets/demo.gif" width="600" alt="nworks demo">
+</p>
+
+First full MCP server for NAVER WORKS.
+NAVER WORKS API를 스크립트나 AI 에이전트에서 쓰기 쉽게 만든 CLI + MCP 서버입니다.
+
+**Automate messages, calendar, drive, mail, tasks, and boards — from CLI or AI agents.**
+
+## Quickstart
 
 ```bash
-npx nworks
+npm install -g nworks
+nworks login --user
+nworks calendar list
+```
+
+### AI 에이전트가 실제로 이렇게 씁니다
+
 ```
+User: 오늘 일정 알려줘
+
+Claude → nworks_calendar_list
+  → 3건: 스탠드업(10:00), 점심미팅(12:00), 코드리뷰(15:00)
+
+User: 팀 채널에 배포 완료 메시지 보내줘
 
-Or install globally:
+Claude → nworks_message_send
+  { "channel": "C001", "text": "v1.2.0 배포 완료" }
+  → 메시지가 전송되었습니다
+```
+
+## Install
 
 ```bash
-npm install -g nworks
+npx nworks          # 바로 실행
+npm install -g nworks  # 글로벌 설치
 ```
 
-## Quick Start
+## 로그인
 
 ```bash
-# 서비스 계정 로그인
-nworks login \
-  --client-id <CLIENT_ID> \
-  --client-secret <CLIENT_SECRET> \
-  --service-account <SERVICE_ACCOUNT> \
-  --private-key <PATH_TO_KEY> \
-  --bot-id <BOT_ID>
+# User OAuth (캘린더, 드라이브, 메일, 할 일, 게시판)
+nworks login --user --scope "calendar,calendar.read,file,file.read,mail,mail.read,task,task.read,board,board.read,user.read"
 
-# User OAuth 로그인 (캘린더, 드라이브 등 사용자 API용)
-nworks login --user --scope "calendar,calendar.read,file,mail,task,board,user.read"
+# 봇 메시지 전송이 필요한 경우 (Service Account)
+nworks login
 
 # 인증 확인
 nworks whoami
 
-# 메시지 전송
-nworks message send --to <userId> --text "배포 완료했습니다"
+# 로그아웃
+nworks logout
+```
 
-# 조직 구성원 조회
-nworks directory members
+> `nworks login --user`는 CLIENT_ID + CLIENT_SECRET만 있으면 됩니다. 환경변수나 기존 설정에 이미 있는 값은 다시 물어보지 않습니다.
 
-# 오늘 일정 조회
-nworks calendar list
+> **Developer Console 설정**: User OAuth를 사용하려면 [Developer Console](https://dev.worksmobile.com)에서 Redirect URL에 `http://localhost:9876/callback`을 등록해야 합니다.
 
-# 일정 생성
-nworks calendar create --title "회의" --start "2026-03-14T14:00+09:00" --end "2026-03-14T15:00+09:00"
+---
 
-# 드라이브 파일 목록
-nworks drive list
+## MCP 서버 (AI 에이전트 연동)
 
-# 파일 업로드
-nworks drive upload --file ./report.pdf
+Claude Desktop, Cursor 등에서 MCP server로 NAVER WORKS 26개 도구를 사용할 수 있습니다.
+메시지 전송, 일정 관리, 파일 업로드, 메일, 할 일, 게시판까지 — AI 에이전트가 NAVER WORKS 워크플로우를 자동화합니다.
 
-# 메일 전송
-nworks mail send --to "user@example.com" --subject "제목" --body "내용"
+### 설정
 
-# 받은편지함 조회
-nworks mail list
+먼저 로그인합니다:
 
-# 할 일 목록
-nworks task list
-
-# 할 일 생성
-nworks task create --title "코드 리뷰" --body "PR #382 리뷰"
+```bash
+nworks login --user --scope "calendar,calendar.read,file,file.read,mail,mail.read,task,task.read,board,board.read,user.read"
+```
 
-# 게시판 목록
-nworks board list
+그리고 MCP 설정에 추가합니다 (`~/.config/claude/claude_desktop_config.json`):
 
-# 게시판 글 작성
-nworks board create --board <boardId> --title "공지사항" --body "내용"
+```json
+{
+  "mcpServers": {
+    "nworks": {
+      "command": "nworks",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
-## CLI Commands
+끝입니다. 인증 한 번으로 26개 도구 모두 사용 가능 — 별도 env 설정이 필요 없습니다.
+
+> **MCP에서 AI 에이전트가 직접 설정하기**: CLI 로그인 없이도 AI 에이전트가 `nworks_setup` → `nworks_login_user` 순서로 호출하면 브라우저 로그인만으로 전체 기능을 사용할 수 있습니다.
+
+### MCP 도구 목록 (26개)
+
+| 도구 | 설명 | 필요 인증 |
+|------|------|----------|
+| **설정/인증** | | |
+| `nworks_setup` | API 인증 정보 설정 (Client ID/Secret 등) | — |
+| `nworks_login_user` | User OAuth 브라우저 로그인 (전체 scope 자동 포함) | — |
+| `nworks_logout` | 인증 정보 및 토큰 삭제 | — |
+| `nworks_whoami` | 인증 상태 확인 | — |
+| `nworks_doctor` | 연결 상태 진단 (인증, 토큰, API 점검) | — |
+| **메시지** | | |
+| `nworks_message_send` | 사용자/채널에 메시지 전송 | Service Account |
+| `nworks_message_members` | 채널 구성원 조회 | Service Account |
+| `nworks_directory_members` | 조직 구성원 조회 | Service Account |
+| **캘린더** | | |
+| `nworks_calendar_list` | 캘린더 일정 조회 | User OAuth (calendar.read) |
+| `nworks_calendar_create` | 캘린더 일정 생성 | User OAuth (calendar + calendar.read) |
+| `nworks_calendar_update` | 캘린더 일정 수정 | User OAuth (calendar + calendar.read) |
+| `nworks_calendar_delete` | 캘린더 일정 삭제 | User OAuth (calendar + calendar.read) |
+| **드라이브** | | |
+| `nworks_drive_list` | 드라이브 파일/폴더 목록 | User OAuth (file.read) |
+| `nworks_drive_upload` | 드라이브 파일 업로드 | User OAuth (file) |
+| `nworks_drive_download` | 드라이브 파일 다운로드 (5MB 초과 시 로컬 저장) | User OAuth (file.read) |
+| **메일** | | |
+| `nworks_mail_send` | 메일 전송 | User OAuth (mail) |
+| `nworks_mail_list` | 메일 목록 조회 | User OAuth (mail.read) |
+| `nworks_mail_read` | 메일 상세 조회 | User OAuth (mail.read) |
+| **할 일** | | |
+| `nworks_task_list` | 할 일 목록 조회 | User OAuth (task.read) |
+| `nworks_task_create` | 할 일 생성 | User OAuth (task + user.read) |
+| `nworks_task_update` | 할 일 수정/완료 | User OAuth (task + user.read) |
+| `nworks_task_delete` | 할 일 삭제 | User OAuth (task + user.read) |
+| **게시판** | | |
+| `nworks_board_list` | 게시판 목록 조회 | User OAuth (board.read) |
+| `nworks_board_posts` | 게시판 글 목록 조회 | User OAuth (board.read) |
+| `nworks_board_read` | 게시판 글 상세 조회 | User OAuth (board.read) |
+| `nworks_board_create` | 게시판 글 작성 | User OAuth (board) |
+
+### AI 에이전트 사용 예시
+
+```
+User: 내일 오후 2시에 회의 잡고, 팀 채널에 알려줘
 
-### 인증
+Claude → nworks_calendar_create
+  { "summary": "회의", "start": "2026-03-15T14:00:00", "end": "2026-03-15T15:00:00" }
+  → 일정이 생성되었습니다
 
-```bash
-nworks login [options]        # 서비스 계정 로그인 (대화형 또는 플래그)
-nworks login --user           # User OAuth 로그인 (브라우저)
-nworks login --user --scope calendar.read  # scope 지정
-nworks whoami                 # 인증 상태 확인
-nworks logout                 # 로그아웃
+Claude → nworks_message_send
+  { "channel": "C001", "text": "내일 14:00 회의가 잡혔습니다" }
+  → 메시지가 전송되었습니다
 ```
 
+---
+
+## CLI 사용법
+
+> 모든 명령어에 `--json` 지원 (파이프, 스크립트, 에이전트 파싱 용이). `message send`, `mail send`, `drive upload`는 `--dry-run`으로 실제 전송 없이 테스트 가능.
+
 ### 메시지 (Bot API)
 
 ```bash
@@ -107,22 +180,16 @@ nworks message members --channel <channelId>
 nworks directory members   # 조직 구성원 목록
 ```
 
-### 캘린더 (User OAuth 필요)
+### 캘린더 (User OAuth)
 
 ```bash
 # 오늘 일정 조회
 nworks calendar list
 
-# 기간 지정 (타임존 필수)
+# 기간 지정
 nworks calendar list --from "2026-03-14T00:00:00+09:00" --until "2026-03-14T23:59:59+09:00"
 
-# 특정 사용자의 일정
-nworks calendar list --user <userId>
-
 # 일정 생성
-nworks calendar create --title "회의" --start "2026-03-14T14:00:00+09:00" --end "2026-03-14T15:00:00+09:00"
-
-# 초 생략 가능
 nworks calendar create --title "회의" --start "2026-03-14T14:00+09:00" --end "2026-03-14T15:00+09:00"
 
 # 장소/설명 포함
@@ -136,36 +203,22 @@ nworks calendar create --title "팀 회의" --start "2026-03-14T10:00+09:00" --e
 # 일정 수정
 nworks calendar update --id <eventId> --title "변경된 제목"
 
-# 시간 변경
-nworks calendar update --id <eventId> --start "2026-03-14T15:00+09:00" --end "2026-03-14T16:00+09:00"
-
 # 일정 삭제
 nworks calendar delete --id <eventId>
 ```
 
-> **Note**: 캘린더 API는 User OAuth가 필요합니다. 먼저 `nworks login --user --scope "calendar calendar.read"`를 실행하세요.
-
-### 드라이브 (User OAuth 필요)
+### 드라이브 (User OAuth)
 
 ```bash
-# 루트 파일/폴더 목록
+# 파일/폴더 목록
 nworks drive list
 
-# 특정 폴더 내 파일 목록
-nworks drive list --folder <folderId>
-
-# 페이지네이션
-nworks drive list --count 50 --cursor <nextCursor>
-
-# 파일 업로드 (루트)
+# 파일 업로드
 nworks drive upload --file ./report.pdf
 
 # 특정 폴더에 업로드
 nworks drive upload --file ./report.pdf --folder <folderId>
 
-# 동일 파일명 덮어쓰기
-nworks drive upload --file ./report.pdf --overwrite
-
 # 파일 다운로드
 nworks drive download --file-id <fileId>
 
@@ -173,9 +226,7 @@ nworks drive download --file-id <fileId>
 nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
 ```
 
-> **Note**: 드라이브 API는 User OAuth가 필요합니다. 먼저 `nworks login --user --scope file`을 실행하세요. 읽기만 필요하면 `file.read` scope로 충분합니다.
-
-### 메일 (User OAuth 필요)
+### 메일 (User OAuth)
 
 ```bash
 # 메일 전송
@@ -194,12 +245,10 @@ nworks mail list --unread
 nworks mail read --id <mailId>
 ```
 
-> **Note**: 메일 API는 User OAuth가 필요합니다. 먼저 `nworks login --user --scope mail`을 실행하세요. 읽기만 필요하면 `mail.read` scope로 충분합니다.
-
-### 할 일 (User OAuth 필요)
+### 할 일 (User OAuth)
 
 ```bash
-# 할 일 목록 (기본 카테고리)
+# 할 일 목록
 nworks task list
 
 # 미완료만 조회
@@ -214,16 +263,11 @@ nworks task create --title "배포" --due 2026-03-20
 # 할 일 완료 처리
 nworks task update --id <taskId> --status done
 
-# 할 일 미완료로 되돌리기
-nworks task update --id <taskId> --status todo
-
 # 할 일 삭제
 nworks task delete --id <taskId>
 ```
 
-> **Note**: 할 일 API는 User OAuth가 필요합니다. 먼저 `nworks login --user --scope "task user.read"`를 실행하세요. (`user.read`는 사용자 ID 조회에 필요) 읽기만 필요하면 `nworks login --user --scope "task.read user.read"`로 충분합니다.
-
-### 게시판 (User OAuth 필요)
+### 게시판 (User OAuth)
 
 ```bash
 # 게시판 목록
@@ -242,36 +286,7 @@ nworks board create --board <boardId> --title "공지사항" --body "내용"
 nworks board create --board <boardId> --title "공지" --body "내용" --notify --no-comment
 ```
 
-> **Note**: 게시판 API는 User OAuth가 필요합니다. 먼저 `nworks login --user --scope board`를 실행하세요. 읽기만 필요하면 `board.read` scope로 충분합니다.
-
-### MCP 서버
-
-```bash
-nworks mcp              # stdio MCP 서버 시작
-nworks mcp --list-tools # 등록된 tool 목록
-```
-
-## MCP 서버 연동 (Claude Desktop)
-
-`~/.config/claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "nworks": {
-      "command": "npx",
-      "args": ["-y", "nworks", "mcp"],
-      "env": {
-        "NWORKS_CLIENT_ID": "<Client ID>",
-        "NWORKS_CLIENT_SECRET": "<Client Secret>",
-        "NWORKS_SERVICE_ACCOUNT": "<Service Account>",
-        "NWORKS_PRIVATE_KEY_PATH": "<Private Key 경로>",
-        "NWORKS_BOT_ID": "<Bot ID>"
-      }
-    }
-  }
-}
-```
+---
 
 ## OAuth Scope 설정
 
@@ -281,39 +296,30 @@ nworks mcp --list-tools # 등록된 tool 목록
 |-------|------|----------|--------------|
 | `bot` | Bot 메시지 전송 | Service Account | `message send` |
 | `bot.read` | Bot 채널/구성원 조회 | Service Account | `message members` |
-| `user.read` | 조직 구성원 조회 | Service Account | `directory members` |
-| `calendar` | 캘린더 쓰기 | User OAuth | `calendar create/update/delete` (+ `calendar.read` 필요) |
-| `calendar.read` | 캘린더 읽기 | User OAuth | `calendar list` |
+| `calendar` | 캘린더 쓰기 | User OAuth | `calendar create/update/delete` (calendar.read도 함께 필요) |
+| `calendar.read` | 캘린더 읽기 | User OAuth | `calendar list`, `calendar create/update/delete`의 의존성 |
 | `file` | 드라이브 읽기/쓰기 | User OAuth | `drive list/upload/download` |
 | `file.read` | 드라이브 읽기 전용 | User OAuth | `drive list/download` |
 | `mail` | 메일 읽기/쓰기 | User OAuth | `mail send/list/read` |
 | `mail.read` | 메일 읽기 전용 | User OAuth | `mail list/read` |
-| `task` | 할 일 읽기/쓰기 | User OAuth | `task list/create/update/delete` (+ `user.read` 필요) |
-| `task.read` | 할 일 읽기 전용 | User OAuth | `task list` (+ `user.read` 필요) |
+| `task` | 할 일 읽기/쓰기 | User OAuth | `task create/update/delete` (user.read도 함께 필요) |
+| `task.read` | 할 일 읽기 전용 | User OAuth | `task list` |
+| `user.read` | 사용자 정보 조회 | Service Account / User OAuth | `directory members`, `task create/update/delete`의 의존성 |
 | `board` | 게시판 읽기/쓰기 | User OAuth | `board list/posts/read/create` |
 | `board.read` | 게시판 읽기 전용 | User OAuth | `board list/posts/read` |
 
 > **Tip**: scope를 변경한 후에는 토큰을 재발급해야 합니다.
 > ```bash
-> nworks logout && nworks login ...
+> nworks logout && nworks login --user --scope "..."
 > ```
 
-> **Developer Console 설정**: User OAuth를 사용하려면 Developer Console에서 Redirect URL에 `http://localhost:9876/callback`을 등록해야 합니다.
-
 ## 사용 시나리오
 
 ### CI/CD 배포 알림
 
 ```bash
 # GitHub Actions에서 배포 완료 후 팀 채널에 알림
-nworks message send --channel $CHANNEL_ID --text "✅ v${VERSION} 배포 완료"
-```
-
-### AI 에이전트 메시지
-
-```bash
-# Claude Desktop / Cursor에서 MCP tool로 직접 메시지 전송
-# nworks mcp 서버가 nworks_message_send tool을 제공
+nworks message send --channel $CHANNEL_ID --text "v${VERSION} 배포 완료"
 ```
 
 ### 팀 자동화 스크립트
@@ -321,34 +327,67 @@ nworks message send --channel $CHANNEL_ID --text "✅ v${VERSION} 배포 완료"
 ```bash
 # 매일 아침 팀원에게 리마인더 전송
 for userId in $(nworks directory members --json | jq -r '.users[].userId'); do
-  nworks message send --to "$userId" --text "📋 오늘의 스탠드업 10시입니다"
+  nworks message send --to "$userId" --text "오늘의 스탠드업 10시입니다"
 done
 ```
 
-## 환경 변수
+---
+
+## Advanced Configuration
+
+### 환경 변수
+
+환경변수로 인증 정보를 설정하면 `nworks login` 없이 바로 사용할 수 있습니다.
 
 ```bash
+# 공통 (필수)
 NWORKS_CLIENT_ID=          # 필수
 NWORKS_CLIENT_SECRET=      # 필수
-NWORKS_SERVICE_ACCOUNT=    # 필수
-NWORKS_PRIVATE_KEY_PATH=   # 필수
-NWORKS_BOT_ID=             # 필수
+
+# 봇 메시지 전송 시에만 필요 (User OAuth만 쓰면 불필요)
+NWORKS_SERVICE_ACCOUNT=    # 봇 전용
+NWORKS_PRIVATE_KEY_PATH=   # 봇 전용
+NWORKS_BOT_ID=             # 봇 전용
+
+# 선택
 NWORKS_DOMAIN_ID=          # optional
 NWORKS_SCOPE=              # optional (기본: bot bot.read user.read)
 NWORKS_VERBOSE=1           # optional, 디버그 로깅
 ```
 
-환경변수가 설정되면 `nworks login` 없이 바로 사용 가능합니다.
+### MCP 서버에 환경 변수 직접 설정
+
+`nworks login` 대신 환경 변수로 직접 설정할 수도 있습니다:
+
+```json
+{
+  "mcpServers": {
+    "nworks": {
+      "command": "npx",
+      "args": ["-y", "nworks", "mcp"],
+      "env": {
+        "NWORKS_CLIENT_ID": "<Client ID>",
+        "NWORKS_CLIENT_SECRET": "<Client Secret>"
+      }
+    }
+  }
+}
+```
+
+봇 메시지도 사용하려면 `NWORKS_SERVICE_ACCOUNT`, `NWORKS_PRIVATE_KEY_PATH`, `NWORKS_BOT_ID`도 추가합니다.
+
+---
 
 ## Roadmap
 
 - ~~**v0.1** — 메시지, 조직 구성원, MCP 서버~~
 - ~~**v0.2** — 캘린더 일정 조회 + User OAuth~~
-- ~~**v0.3** — 드라이브 파일 조회/업로드/다운로드 (`nworks drive`)~~
-- ~~**v0.4** — 메일 (`nworks mail send/list/read`)~~
-- ~~**v0.5** — 할 일 (`nworks task list/create/update/delete`)~~
-- ~~**v0.6** — 캘린더 쓰기 (`nworks calendar create/update/delete`)~~
-- ~~**v0.7** — 게시판 (`nworks board list/posts/read/create`)~~
+- ~~**v0.3** — 드라이브 파일 조회/업로드/다운로드~~
+- ~~**v0.4** — 메일 (`mail send/list/read`)~~
+- ~~**v0.5** — 할 일 (`task list/create/update/delete`)~~
+- ~~**v0.6** — 캘린더 쓰기 (`calendar create/update/delete`)~~
+- ~~**v0.7** — 게시판 (`board list/posts/read/create`)~~
+- ~~**v1.0** — User OAuth 단독 로그인, MCP/CLI 인증 UX 개선, AI 에이전트 전용 설정 flow (nworks_setup → nworks_login_user), scope 자동 확장, 한국어 에러 안내, nworks doctor~~
 
 ## License