nworks 1.2.1 → 1.3.0

package/README.ja.md

@@ -14,7 +14,9 @@ Featured in [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-server
 </p>
 
 LINE WORKS (NAVER WORKS) 初のMCPサーバー。
-メッセージ、カレンダー、ドライブ、メール、タスク、掲示板 — 26ツール対応のCLI + MCPサーバーです。
+メッセージ、カレンダー、ドライブ、メール、タスク、掲示板 — 36ツール対応のCLI + MCPサーバーです。
+
+nworksは、**外部**のAIエージェント（Claude、Cursor）やターミナルからLINE WORKSを*操作*するためのレイヤーです。LINE WORKS自身の社内向けAI（AiStudio、WORKS AI）とは競合せず、補完関係にあります。非公式・コミュニティ運営であり、LINE WORKS / NAVER WORKSとの提携関係はありません。
 
 ## クイックスタート
 
@@ -24,6 +26,8 @@ nworks login --user
 nworks calendar list
 ```
 
+> **初めての方へ:** まずDeveloper Consoleアプリ（Client ID/Secret）、redirect URLの登録、そしてボットメッセージの場合は管理者の承認が必要です。[オンボーディング & 管理者セットアップガイド](ONBOARDING.md)を参照してください。
+
 ### AIエージェントの使用例
 
 ```
@@ -100,11 +104,11 @@ nworks login --user --scope "calendar calendar.read file file.read mail mail.rea
 }
 ```
 
-一度のログインで26ツールすべて利用可能。追加のenv設定は不要です。
+一度のログインで36ツールすべて利用可能。追加のenv設定は不要です。
 
 > CLIログインなしでも、AIエージェントが `nworks_setup` → `nworks_login_user` を呼び出せばブラウザから直接認証できます。Client SecretとPrivate Keyのパスは、MCP設定の `env` フィールドまたはシステム環境変数で事前に設定してください。
 
-### MCPツール一覧（26個）
+### MCPツール一覧（32個）
 
 | ツール | 説明 | 必要な認証 |
 |--------|------|-----------|
@@ -127,10 +131,14 @@ nworks login --user --scope "calendar calendar.read file file.read mail mail.rea
 | `nworks_drive_list` | ドライブのファイル/フォルダ一覧 | User OAuth (file.read) |
 | `nworks_drive_upload` | ドライブにファイルアップロード | User OAuth (file) |
 | `nworks_drive_download` | ドライブからファイルダウンロード（5MB超はローカル保存） | User OAuth (file.read) |
+| `nworks_sharedrive_list` | 共有ドライブ一覧 | User OAuth (file.read) |
+| `nworks_sharedrive_files` | 共有ドライブのファイル/フォルダ一覧 | User OAuth (file.read) |
+| `nworks_sharedrive_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_mail_download_attachment` | メール添付ファイルのダウンロード (5MB超はローカル保存) | User OAuth (mail.read) |
 | **タスク** | | |
 | `nworks_task_list` | タスク一覧 | User OAuth (task.read) |
 | `nworks_task_create` | タスク作成 | User OAuth (task + user.read) |
@@ -141,6 +149,13 @@ nworks login --user --scope "calendar calendar.read file file.read mail mail.rea
 | `nworks_board_posts` | 掲示板の投稿一覧 | User OAuth (board.read) |
 | `nworks_board_read` | 掲示板の投稿詳細 | User OAuth (board.read) |
 | `nworks_board_create` | 掲示板に投稿作成 | User OAuth (board) |
+| **連絡先** | | |
+| `nworks_contact_list` | 連絡先一覧 | User OAuth (contact.read) |
+| `nworks_contact_get` | 連絡先の詳細 | User OAuth (contact.read) |
+| `nworks_contact_create` | 連絡先の作成 | User OAuth (contact) |
+| `nworks_contact_update` | 連絡先の更新 | User OAuth (contact) |
+| `nworks_contact_delete` | 連絡先の削除 | User OAuth (contact) |
+| `nworks_contact_list_tags` | 連絡先タグ一覧 | User OAuth (contact.read) |
 
 ### AIエージェント使用例
 
@@ -240,6 +255,18 @@ nworks drive download --file-id <fileId>
 
 # 出力先/ファイル名指定
 nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
+
+# 共有ドライブ一覧
+nworks drive sharedrive-list
+
+# 共有ドライブのファイル一覧 (ルート)
+nworks drive sharedrive-files --sharedrive <sharedriveId>
+
+# 共有ドライブのフォルダ内ファイル一覧
+nworks drive sharedrive-files --sharedrive <sharedriveId> --folder <fileId>
+
+# 共有ドライブのファイルをダウンロード
+nworks drive sharedrive-download --sharedrive <sharedriveId> --file-id <fileId>
 ```
 
 ### メール（User OAuth）
@@ -259,6 +286,12 @@ nworks mail list --unread
 
 # メール詳細表示
 nworks mail read --id <mailId>
+
+# メール添付ファイルのダウンロード
+nworks mail download-attachment --id <mailId> --attachment-id <attachmentId>
+
+# 保存先/ファイル名を指定
+nworks mail download-attachment --id <mailId> --attachment-id <attachmentId> --out ./downloads --name invoice.pdf
 ```
 
 ### タスク（User OAuth）
@@ -302,6 +335,34 @@ nworks board create --board <boardId> --title "お知らせ" --body "内容"
 nworks board create --board <boardId> --title "通知" --body "内容" --notify --no-comment
 ```
 
+### 連絡先 (User OAuth)
+
+```bash
+# 連絡先一覧
+nworks contact list
+
+# タグで絞り込み
+nworks contact list --tag <contactTagId>
+
+# 連絡先の詳細
+nworks contact get --id <contactId>
+
+# 連絡先の作成
+nworks contact create --payload '{"contactName":{"lastName":"金","firstName":"哲秀"},"emails":[{"email":"chulsoo@example.com","primary":true}],"permission":{"accessibleRange":"MEMBER","isCoEditing":false,"accessibleMembers":[{"id":"<自分のuserId>","type":"USER"}]}}'
+
+# 連絡先の更新
+nworks contact update --id <contactId> --payload '{"telephones":[{"type":"CELLPHONE","telephone":"010-1234-5678","primary":true}]}'
+
+# 連絡先の削除
+nworks contact delete --id <contactId>
+
+# 連絡先タグ一覧
+nworks contact list-tags
+```
+
+> `contact create` は `contactName` と `permission` が必須で、`permission.accessibleMembers` に最低1名(通常は自分)が必要です。自分のuserIdは `nworks whoami` で確認できます。
+
+
 ### CI/CDデプロイ通知
 
 ```bash
@@ -339,11 +400,16 @@ done
 | `user.read` | ユーザー情報取得 | Service Account / User OAuth | `directory members`、タスク書き込みの依存関係 |
 | `board` | 掲示板読み書き | User OAuth | `board list/posts/read/create` |
 | `board.read` | 掲示板読み取り専用 | User OAuth | `board list/posts/read` |
+| `contact` | 連絡先の読み書き | User OAuth | `contact create/update/delete` (contact.read が必要) |
+| `contact.read` | 連絡先の読み取り専用 | User OAuth | `contact list/get/list-tags` |
 
-> **ヒント**: scopeを変更した後はトークンを再発行してください。
+> **プリセット**を使うとscopeを個別に列挙するより簡単です:
 > ```bash
-> nworks logout && nworks login --user --scope "..."
+> nworks login --user --preset all       # デフォルト: 一度のログインで全機能
+> nworks login --user --preset readonly  # 読み取り専用scope
 > ```
+> `default`は`all`のエイリアスです。メッセージ送信はService Account（ボット）を使うため、プリセットに関係なく動作します。
+> 再ログインしても権限は狭まりません — 新たに要求したscopeが既存トークンとマージされるため、プリセットの切り替えは権限を追加するだけです。個別に選ぶ場合は`--scope "calendar calendar.read"`を指定してください。
 
 ---
 

package/README.ko.md

@@ -14,7 +14,9 @@ Featured in [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-server
 </p>
 
 NAVER WORKS (LINE WORKS) 최초의 MCP 서버.
-메시지, 캘린더, 드라이브, 메일, 할 일, 게시판 — 26개 도구를 CLI와 AI 에이전트에서 쓸 수 있습니다.
+메시지, 캘린더, 드라이브, 메일, 할 일, 게시판 — 36개 도구를 CLI와 AI 에이전트에서 쓸 수 있습니다.
+
+nworks는 **외부** AI 에이전트(Claude, Cursor)와 터미널에서 LINE WORKS를 *다루기* 위한 도구입니다. LINE WORKS 자체의 사내용 AI(AiStudio, WORKS AI)와 겹치지 않고 상호 보완합니다. 비공식·커뮤니티 프로젝트이며 LINE WORKS / NAVER WORKS와 제휴 관계가 없습니다.
 
 ## Quickstart
 
@@ -24,6 +26,8 @@ nworks login --user
 nworks calendar list
 ```
 
+> **처음이신가요?** 먼저 Developer Console 앱(Client ID/Secret), redirect URL 등록, 그리고 봇 메시지의 경우 관리자 승인이 필요합니다. [온보딩 & 관리자 설정 가이드](ONBOARDING.md)를 참고하세요.
+
 ### AI 에이전트가 실제로 이렇게 씁니다
 
 ```
@@ -100,11 +104,11 @@ nworks login --user --scope "calendar calendar.read file file.read mail mail.rea
 }
 ```
 
-로그인 한 번이면 26개 도구 모두 사용 가능. 별도 env 설정 불필요.
+로그인 한 번이면 36개 도구 모두 사용 가능. 별도 env 설정 불필요.
 
 > **MCP에서 AI 에이전트가 직접 설정하기**: CLI 로그인 없이도 AI 에이전트가 `nworks_setup` → `nworks_login_user` 순서로 호출하면 브라우저 로그인만으로 전체 기능을 사용할 수 있습니다. Client Secret과 Private Key 경로는 MCP 설정의 `env` 필드 또는 시스템 환경변수로 미리 설정해야 합니다.
 
-### MCP 도구 목록 (26개)
+### MCP 도구 목록 (32개)
 
 | 도구 | 설명 | 필요 인증 |
 |------|------|----------|
@@ -127,10 +131,14 @@ nworks login --user --scope "calendar calendar.read file file.read mail mail.rea
 | `nworks_drive_list` | 드라이브 파일/폴더 목록 | User OAuth (file.read) |
 | `nworks_drive_upload` | 드라이브 파일 업로드 | User OAuth (file) |
 | `nworks_drive_download` | 드라이브 파일 다운로드 (5MB 초과 시 로컬 저장) | User OAuth (file.read) |
+| `nworks_sharedrive_list` | 공유 드라이브 목록 조회 | User OAuth (file.read) |
+| `nworks_sharedrive_files` | 공유 드라이브 파일/폴더 목록 조회 | User OAuth (file.read) |
+| `nworks_sharedrive_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_mail_download_attachment` | 메일 첨부파일 다운로드 (5MB 초과 시 로컬 저장) | User OAuth (mail.read) |
 | **할 일** | | |
 | `nworks_task_list` | 할 일 목록 조회 | User OAuth (task.read) |
 | `nworks_task_create` | 할 일 생성 | User OAuth (task + user.read) |
@@ -141,6 +149,13 @@ nworks login --user --scope "calendar calendar.read file file.read mail mail.rea
 | `nworks_board_posts` | 게시판 글 목록 조회 | User OAuth (board.read) |
 | `nworks_board_read` | 게시판 글 상세 조회 | User OAuth (board.read) |
 | `nworks_board_create` | 게시판 글 작성 | User OAuth (board) |
+| **연락처** | | |
+| `nworks_contact_list` | 연락처 목록 조회 | User OAuth (contact.read) |
+| `nworks_contact_get` | 연락처 상세 조회 | User OAuth (contact.read) |
+| `nworks_contact_create` | 연락처 생성 | User OAuth (contact) |
+| `nworks_contact_update` | 연락처 수정 | User OAuth (contact) |
+| `nworks_contact_delete` | 연락처 삭제 | User OAuth (contact) |
+| `nworks_contact_list_tags` | 연락처 태그 목록 조회 | User OAuth (contact.read) |
 
 ### AI 에이전트 사용 예시
 
@@ -240,6 +255,18 @@ nworks drive download --file-id <fileId>
 
 # 다운로드 경로/파일명 지정
 nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
+
+# 공유 드라이브 목록
+nworks drive sharedrive-list
+
+# 공유 드라이브 파일 목록 (루트)
+nworks drive sharedrive-files --sharedrive <sharedriveId>
+
+# 공유 드라이브 폴더 내 파일 목록
+nworks drive sharedrive-files --sharedrive <sharedriveId> --folder <fileId>
+
+# 공유 드라이브 파일 다운로드
+nworks drive sharedrive-download --sharedrive <sharedriveId> --file-id <fileId>
 ```
 
 ### 메일 (User OAuth)
@@ -259,6 +286,12 @@ nworks mail list --unread
 
 # 메일 상세 조회
 nworks mail read --id <mailId>
+
+# 메일 첨부파일 다운로드
+nworks mail download-attachment --id <mailId> --attachment-id <attachmentId>
+
+# 저장 경로/파일명 지정
+nworks mail download-attachment --id <mailId> --attachment-id <attachmentId> --out ./downloads --name invoice.pdf
 ```
 
 ### 할 일 (User OAuth)
@@ -302,6 +335,34 @@ nworks board create --board <boardId> --title "공지사항" --body "내용"
 nworks board create --board <boardId> --title "공지" --body "내용" --notify --no-comment
 ```
 
+### 연락처 (User OAuth)
+
+```bash
+# 연락처 목록
+nworks contact list
+
+# 태그로 필터링
+nworks contact list --tag <contactTagId>
+
+# 연락처 상세 조회
+nworks contact get --id <contactId>
+
+# 연락처 생성
+nworks contact create --payload '{"contactName":{"lastName":"김","firstName":"철수"},"emails":[{"email":"chulsoo@example.com","primary":true}],"permission":{"accessibleRange":"MEMBER","isCoEditing":false,"accessibleMembers":[{"id":"<내 userId>","type":"USER"}]}}'
+
+# 연락처 수정
+nworks contact update --id <contactId> --payload '{"telephones":[{"type":"CELLPHONE","telephone":"010-1234-5678","primary":true}]}'
+
+# 연락처 삭제
+nworks contact delete --id <contactId>
+
+# 연락처 태그 목록
+nworks contact list-tags
+```
+
+> `contact create`는 `contactName`과 `permission`이 필수이며, `permission.accessibleMembers`에 최소 1명(보통 본인)이 있어야 합니다. 본인 userId는 `nworks whoami`로 확인합니다.
+
+
 ### CI/CD 배포 알림
 
 ```bash
@@ -339,11 +400,16 @@ done
 | `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` |
+| `contact` | 연락처 읽기/쓰기 | User OAuth | `contact create/update/delete` (contact.read 필요) |
+| `contact.read` | 연락처 읽기 전용 | User OAuth | `contact list/get/list-tags` |
 
-> **Tip**: scope를 변경한 후에는 토큰을 재발급해야 합니다.
+> **프리셋**이 scope를 일일이 나열하는 것보다 간단합니다:
 > ```bash
-> nworks logout && nworks login --user --scope "..."
+> nworks login --user --preset all       # 기본값: 한 번 로그인으로 전체 기능
+> nworks login --user --preset readonly  # 읽기 전용 scope
 > ```
+> `default`는 `all`의 별칭입니다. 메시지 전송은 Service Account(봇)를 쓰므로 프리셋과 무관하게 동작합니다.
+> 재로그인해도 권한은 줄지 않습니다. 새로 요청한 scope가 기존 토큰과 합쳐지므로, 프리셋을 바꿔도 권한이 추가되기만 합니다. 직접 고른 조합은 `--scope "calendar calendar.read"`로 지정하세요.
 
 ---
 

package/README.md

@@ -14,7 +14,9 @@ Featured in [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-server
 </p>
 
 Full-featured MCP server for LINE WORKS (NAVER WORKS).
-CLI + MCP server — 26 tools covering messages, calendar, drive, mail, tasks, and boards.
+CLI + MCP server — 36 tools covering messages, calendar, drive, mail, tasks, and boards.
+
+nworks lets **external** AI agents (Claude, Cursor) and your terminal *operate* LINE WORKS from the outside — complementary to LINE WORKS' own in-product AI (AiStudio, WORKS AI), not a replacement. Unofficial and community-maintained; not affiliated with LINE WORKS / NAVER WORKS.
 
 ## Quickstart
 
@@ -24,6 +26,8 @@ nworks login --user
 nworks calendar list
 ```
 
+> **First time?** You first need a Developer Console app (Client ID/Secret), a registered redirect URL, and — for bot messaging — admin approval. See the [Onboarding & Admin Setup guide](ONBOARDING.md).
+
 ### AI Agents Actually Use It Like This
 
 ```
@@ -100,11 +104,11 @@ Then add to your MCP config (`~/.config/claude/claude_desktop_config.json`):
 }
 ```
 
-One login enables all 26 tools. No extra env setup needed.
+One login enables all 36 tools. No extra env setup needed.
 
 > Without CLI login, an AI agent can call `nworks_setup` → `nworks_login_user` to authenticate via browser directly. Client Secret and Private Key path must be pre-configured via MCP config `env` field or system environment variables.
 
-### MCP Tools (26)
+### MCP Tools (32)
 
 | Tool | Description | Auth |
 |------|-------------|------|
@@ -127,10 +131,14 @@ One login enables all 26 tools. No extra env setup needed.
 | `nworks_drive_list` | List drive files/folders | User OAuth (file.read) |
 | `nworks_drive_upload` | Upload file to drive | User OAuth (file) |
 | `nworks_drive_download` | Download file (saves locally if >5MB) | User OAuth (file.read) |
+| `nworks_sharedrive_list` | List shared drives | User OAuth (file.read) |
+| `nworks_sharedrive_files` | List files/folders in a shared drive | User OAuth (file.read) |
+| `nworks_sharedrive_download` | Download a shared drive file (saves locally if >5MB) | User OAuth (file.read) |
 | **Mail** | | |
 | `nworks_mail_send` | Send mail | User OAuth (mail) |
 | `nworks_mail_list` | List mailbox | User OAuth (mail.read) |
 | `nworks_mail_read` | Read mail detail | User OAuth (mail.read) |
+| `nworks_mail_download_attachment` | Download a mail attachment (saves locally if >5MB) | User OAuth (mail.read) |
 | **Tasks** | | |
 | `nworks_task_list` | List tasks | User OAuth (task.read) |
 | `nworks_task_create` | Create task | User OAuth (task + user.read) |
@@ -141,6 +149,13 @@ One login enables all 26 tools. No extra env setup needed.
 | `nworks_board_posts` | List board posts | User OAuth (board.read) |
 | `nworks_board_read` | Read board post detail | User OAuth (board.read) |
 | `nworks_board_create` | Create board post | User OAuth (board) |
+| **Contacts** | | |
+| `nworks_contact_list` | List contacts | User OAuth (contact.read) |
+| `nworks_contact_get` | Get contact detail | User OAuth (contact.read) |
+| `nworks_contact_create` | Create contact | User OAuth (contact) |
+| `nworks_contact_update` | Update contact | User OAuth (contact) |
+| `nworks_contact_delete` | Delete contact | User OAuth (contact) |
+| `nworks_contact_list_tags` | List contact tags | User OAuth (contact.read) |
 
 ### AI Agent Usage Example
 
@@ -240,6 +255,18 @@ nworks drive download --file-id <fileId>
 
 # Specify output path/name
 nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
+
+# List shared drives
+nworks drive sharedrive-list
+
+# List files in a shared drive (root)
+nworks drive sharedrive-files --sharedrive <sharedriveId>
+
+# List files in a shared drive folder
+nworks drive sharedrive-files --sharedrive <sharedriveId> --folder <fileId>
+
+# Download a shared drive file
+nworks drive sharedrive-download --sharedrive <sharedriveId> --file-id <fileId>
 ```
 
 ### Mail (User OAuth)
@@ -259,6 +286,12 @@ nworks mail list --unread
 
 # Read mail detail
 nworks mail read --id <mailId>
+
+# Download a mail attachment
+nworks mail download-attachment --id <mailId> --attachment-id <attachmentId>
+
+# Specify output path/name
+nworks mail download-attachment --id <mailId> --attachment-id <attachmentId> --out ./downloads --name invoice.pdf
 ```
 
 ### Tasks (User OAuth)
@@ -302,6 +335,34 @@ nworks board create --board <boardId> --title "Announcement" --body "Content"
 nworks board create --board <boardId> --title "Notice" --body "Content" --notify --no-comment
 ```
 
+### Contacts (User OAuth)
+
+```bash
+# List contacts
+nworks contact list
+
+# Filter by tag
+nworks contact list --tag <contactTagId>
+
+# Get contact detail
+nworks contact get --id <contactId>
+
+# Create contact
+nworks contact create --payload '{"contactName":{"lastName":"Kim","firstName":"Chulsoo"},"emails":[{"email":"chulsoo@example.com","primary":true}],"permission":{"accessibleRange":"MEMBER","isCoEditing":false,"accessibleMembers":[{"id":"<yourUserId>","type":"USER"}]}}'
+
+# Update contact
+nworks contact update --id <contactId> --payload '{"telephones":[{"type":"CELLPHONE","telephone":"010-1234-5678","primary":true}]}'
+
+# Delete contact
+nworks contact delete --id <contactId>
+
+# List contact tags
+nworks contact list-tags
+```
+
+> `contact create` requires `contactName` and `permission`; `permission.accessibleMembers` must list at least one member (usually yourself). Get your own user ID from `nworks whoami`.
+
+
 ### CI/CD Deploy Notification
 
 ```bash
@@ -339,11 +400,16 @@ Add the required scopes in the [LINE WORKS Developer Console](https://dev.worksm
 | `user.read` | User info read | Service Account / User OAuth | `directory members`, also needed for task write |
 | `board` | Boards read/write | User OAuth | `board list/posts/read/create` |
 | `board.read` | Boards read-only | User OAuth | `board list/posts/read` |
+| `contact` | Contacts read/write | User OAuth | `contact create/update/delete` (requires contact.read) |
+| `contact.read` | Contacts read-only | User OAuth | `contact list/get/list-tags` |
 
-> **Tip**: After changing scopes, reissue your token:
+> **Presets** are simpler than listing scopes:
 > ```bash
-> nworks logout && nworks login --user --scope "..."
+> nworks login --user --preset all       # default: full functionality in one login
+> nworks login --user --preset readonly  # read-only scopes
 > ```
+> `default` is an alias of `all`. Message sending uses the Service Account (bot), so it works regardless of preset.
+> Re-login never narrows access — newly requested scopes are merged with the existing token, so switching presets only adds capability. For a hand-picked set use `--scope "calendar calendar.read"`.
 
 ---