nworks 1.2.2 β†’ 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/LICENSE +190 -190
  2. package/README.ja.md +459 -393
  3. package/README.ko.md +459 -393
  4. package/README.md +459 -393
  5. package/dist/index.js +1442 -508
  6. package/dist/index.js.map +1 -1
  7. package/dist/mcp.js +1948 -1218
  8. package/dist/mcp.js.map +1 -1
  9. package/package.json +61 -58
package/README.md CHANGED
@@ -1,393 +1,459 @@
1
- # nworks
2
-
3
- [![npm version](https://img.shields.io/npm/v/nworks.svg)](https://www.npmjs.com/package/nworks)
4
- [![license](https://img.shields.io/npm/l/nworks.svg)](LICENSE)
5
- [![npm downloads](https://img.shields.io/npm/dm/nworks.svg)](https://www.npmjs.com/package/nworks)
6
- [![nworks MCP server](https://glama.ai/mcp/servers/yjcho9317/nworks/badges/score.svg)](https://glama.ai/mcp/servers/yjcho9317/nworks)
7
-
8
- Featured in [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
9
-
10
- πŸ‡ΊπŸ‡Έ English | [πŸ‡°πŸ‡· ν•œκ΅­μ–΄](README.ko.md) | [πŸ‡―πŸ‡΅ ζ—₯本θͺž](README.ja.md)
11
-
12
- <p align="center">
13
- <img src="assets/demo.gif" width="600" alt="nworks demo">
14
- </p>
15
-
16
- Full-featured MCP server for LINE WORKS (NAVER WORKS).
17
- CLI + MCP server β€” 26 tools covering messages, calendar, drive, mail, tasks, and boards.
18
-
19
- ## Quickstart
20
-
21
- ```bash
22
- npm install -g nworks
23
- nworks login --user
24
- nworks calendar list
25
- ```
26
-
27
- ### AI Agents Actually Use It Like This
28
-
29
- ```
30
- User: Show me today's schedule
31
-
32
- Claude β†’ nworks_calendar_list
33
- β†’ 3 events: Standup (10:00), Lunch meeting (12:00), Code review (15:00)
34
-
35
- User: Send a deploy complete message to the team channel
36
-
37
- Claude β†’ nworks_message_send
38
- { "channel": "C001", "text": "v1.2.0 deploy complete" }
39
- β†’ Message sent
40
-
41
- User: Check my unread emails and summarize them
42
-
43
- Claude β†’ nworks_mail_list (unread)
44
- β†’ 3 unread emails
45
- Claude β†’ nworks_mail_read (each)
46
- β†’ "3 unread: 1) Deploy approval from CTO, 2) Meeting invite for Friday, 3) Weekly report reminder"
47
- ```
48
-
49
- ## Install
50
-
51
- ```bash
52
- npx nworks # Run directly
53
- npm install -g nworks # Global install
54
- ```
55
-
56
- ## Login
57
-
58
- ```bash
59
- # User OAuth (calendar, drive, mail, tasks, boards)
60
- nworks login --user --scope "calendar calendar.read file file.read mail mail.read task task.read board board.read user.read"
61
-
62
- # Bot messaging (Service Account)
63
- nworks login
64
-
65
- # Check auth status
66
- nworks whoami
67
-
68
- # Logout
69
- nworks logout
70
- ```
71
-
72
- > `nworks login --user` only requires CLIENT_ID + CLIENT_SECRET. Values already set via environment variables or existing config won't be asked again.
73
-
74
- > **Developer Console**: To use User OAuth, register `http://localhost:9876/callback` as a Redirect URL in the [Developer Console](https://dev.worksmobile.com/en/).
75
-
76
- ---
77
-
78
- ## AI Agent Integration (MCP Server)
79
-
80
- Works with Claude Desktop, Cursor, and other MCP-compatible clients.
81
-
82
- ### Setup
83
-
84
- Login first:
85
-
86
- ```bash
87
- nworks login --user --scope "calendar calendar.read file file.read mail mail.read task task.read board board.read user.read"
88
- ```
89
-
90
- Then add to your MCP config (`~/.config/claude/claude_desktop_config.json`):
91
-
92
- ```json
93
- {
94
- "mcpServers": {
95
- "nworks": {
96
- "command": "nworks",
97
- "args": ["mcp"]
98
- }
99
- }
100
- }
101
- ```
102
-
103
- One login enables all 26 tools. No extra env setup needed.
104
-
105
- > 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.
106
-
107
- ### MCP Tools (26)
108
-
109
- | Tool | Description | Auth |
110
- |------|-------------|------|
111
- | **Setup / Auth** | | |
112
- | `nworks_setup` | Configure API credentials (Client ID, etc.). Client Secret is set via env | β€” |
113
- | `nworks_login_user` | User OAuth browser login (all scopes included) | β€” |
114
- | `nworks_logout` | Delete credentials and tokens | β€” |
115
- | `nworks_whoami` | Check auth status | β€” |
116
- | `nworks_doctor` | Diagnose connection (auth, tokens, API health) | β€” |
117
- | **Messages** | | |
118
- | `nworks_message_send` | Send message to user/channel | Service Account |
119
- | `nworks_message_members` | List channel members | Service Account |
120
- | `nworks_directory_members` | List organization members | Service Account |
121
- | **Calendar** | | |
122
- | `nworks_calendar_list` | List calendar events | User OAuth (calendar.read) |
123
- | `nworks_calendar_create` | Create calendar event | User OAuth (calendar + calendar.read) |
124
- | `nworks_calendar_update` | Update calendar event | User OAuth (calendar + calendar.read) |
125
- | `nworks_calendar_delete` | Delete calendar event | User OAuth (calendar + calendar.read) |
126
- | **Drive** | | |
127
- | `nworks_drive_list` | List drive files/folders | User OAuth (file.read) |
128
- | `nworks_drive_upload` | Upload file to drive | User OAuth (file) |
129
- | `nworks_drive_download` | Download file (saves locally if >5MB) | User OAuth (file.read) |
130
- | **Mail** | | |
131
- | `nworks_mail_send` | Send mail | User OAuth (mail) |
132
- | `nworks_mail_list` | List mailbox | User OAuth (mail.read) |
133
- | `nworks_mail_read` | Read mail detail | User OAuth (mail.read) |
134
- | **Tasks** | | |
135
- | `nworks_task_list` | List tasks | User OAuth (task.read) |
136
- | `nworks_task_create` | Create task | User OAuth (task + user.read) |
137
- | `nworks_task_update` | Update/complete task | User OAuth (task + user.read) |
138
- | `nworks_task_delete` | Delete task | User OAuth (task + user.read) |
139
- | **Boards** | | |
140
- | `nworks_board_list` | List boards | User OAuth (board.read) |
141
- | `nworks_board_posts` | List board posts | User OAuth (board.read) |
142
- | `nworks_board_read` | Read board post detail | User OAuth (board.read) |
143
- | `nworks_board_create` | Create board post | User OAuth (board) |
144
-
145
- ### AI Agent Usage Example
146
-
147
- ```
148
- User: Schedule a meeting tomorrow at 2pm and notify the team channel
149
-
150
- Claude β†’ nworks_calendar_create
151
- { "summary": "Meeting", "start": "2026-03-15T14:00:00", "end": "2026-03-15T15:00:00" }
152
- β†’ Event created
153
-
154
- Claude β†’ nworks_message_send
155
- { "channel": "C001", "text": "Meeting scheduled tomorrow at 14:00" }
156
- β†’ Message sent
157
-
158
- User: Check my unread emails and summarize them
159
-
160
- Claude β†’ nworks_mail_list (unread)
161
- β†’ 3 unread emails
162
- Claude β†’ nworks_mail_read (each)
163
- β†’ "3 unread: 1) Deploy approval from CTO, 2) Meeting invite for Friday, 3) Weekly report reminder"
164
- ```
165
-
166
- ---
167
-
168
- ## CLI Usage
169
-
170
- > All commands support `--json` for pipe/script/agent parsing. `message send`, `mail send`, and `drive upload` support `--dry-run` for testing without sending.
171
-
172
- ### Messages (Bot API)
173
-
174
- ```bash
175
- # Send text to user
176
- nworks message send --to <userId> --text "Hello"
177
-
178
- # Send text to channel
179
- nworks message send --channel <channelId> --text "Announcement"
180
-
181
- # Button message
182
- nworks message send --to <userId> --type button --text "PR review request" \
183
- --actions '[{"type":"message","label":"Approve","postback":"approve"}]'
184
-
185
- # List message
186
- nworks message send --to <userId> --type list --text "Today's tasks" \
187
- --elements '[{"title":"Code review","subtitle":"PR #382"}]'
188
-
189
- # List channel members
190
- nworks message members --channel <channelId>
191
- ```
192
-
193
- ### Directory
194
-
195
- ```bash
196
- nworks directory members # List organization members
197
- ```
198
-
199
- ### Calendar (User OAuth)
200
-
201
- ```bash
202
- # List today's events
203
- nworks calendar list
204
-
205
- # Specify date range
206
- nworks calendar list --from "2026-03-14T00:00:00+09:00" --until "2026-03-14T23:59:59+09:00"
207
-
208
- # Create event
209
- nworks calendar create --title "Meeting" --start "2026-03-14T14:00+09:00" --end "2026-03-14T15:00+09:00"
210
-
211
- # With location/description
212
- nworks calendar create --title "Lunch" --start "2026-03-14T12:00+09:00" --end "2026-03-14T13:00+09:00" \
213
- --location "Conference Room" --description "Quarterly review"
214
-
215
- # With attendees + notification
216
- nworks calendar create --title "Team meeting" --start "2026-03-14T10:00+09:00" --end "2026-03-14T11:00+09:00" \
217
- --attendees "user1@example.com,user2@example.com" --notify
218
-
219
- # Update event
220
- nworks calendar update --id <eventId> --title "Updated title"
221
-
222
- # Delete event
223
- nworks calendar delete --id <eventId>
224
- ```
225
-
226
- ### Drive (User OAuth)
227
-
228
- ```bash
229
- # List files/folders
230
- nworks drive list
231
-
232
- # Upload file
233
- nworks drive upload --file ./report.pdf
234
-
235
- # Upload to specific folder
236
- nworks drive upload --file ./report.pdf --folder <folderId>
237
-
238
- # Download file
239
- nworks drive download --file-id <fileId>
240
-
241
- # Specify output path/name
242
- nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
243
- ```
244
-
245
- ### Mail (User OAuth)
246
-
247
- ```bash
248
- # Send mail
249
- nworks mail send --to "user@example.com" --subject "Subject" --body "Body"
250
-
251
- # With CC/BCC
252
- nworks mail send --to "user@example.com" --cc "cc@example.com" --subject "Subject" --body "Body"
253
-
254
- # List inbox
255
- nworks mail list
256
-
257
- # Unread only
258
- nworks mail list --unread
259
-
260
- # Read mail detail
261
- nworks mail read --id <mailId>
262
- ```
263
-
264
- ### Tasks (User OAuth)
265
-
266
- ```bash
267
- # List tasks
268
- nworks task list
269
-
270
- # Incomplete only
271
- nworks task list --status TODO
272
-
273
- # Create task
274
- nworks task create --title "Code review" --body "Review PR #382"
275
-
276
- # With due date
277
- nworks task create --title "Deploy" --due 2026-03-20
278
-
279
- # Mark as done
280
- nworks task update --id <taskId> --status done
281
-
282
- # Delete task
283
- nworks task delete --id <taskId>
284
- ```
285
-
286
- ### Boards (User OAuth)
287
-
288
- ```bash
289
- # List boards
290
- nworks board list
291
-
292
- # List posts
293
- nworks board posts --board <boardId>
294
-
295
- # Read post detail
296
- nworks board read --board <boardId> --post <postId>
297
-
298
- # Create post
299
- nworks board create --board <boardId> --title "Announcement" --body "Content"
300
-
301
- # With notification + disable comments
302
- nworks board create --board <boardId> --title "Notice" --body "Content" --notify --no-comment
303
- ```
304
-
305
- ### CI/CD Deploy Notification
306
-
307
- ```bash
308
- # Notify team channel after deployment in GitHub Actions
309
- nworks message send --channel $CHANNEL_ID --text "v${VERSION} deployed"
310
- ```
311
-
312
- ### Team Automation Script
313
-
314
- ```bash
315
- # Send daily standup reminder to all members
316
- for userId in $(nworks directory members --json | jq -r '.users[].userId'); do
317
- nworks message send --to "$userId" --text "Standup at 10:00 today"
318
- done
319
- ```
320
-
321
- ---
322
-
323
- ## OAuth Scopes
324
-
325
- Add the required scopes in the [LINE WORKS Developer Console](https://dev.worksmobile.com/en/).
326
-
327
- | Scope | Purpose | Auth | Required For |
328
- |-------|---------|------|-------------|
329
- | `bot` | Bot messaging | Service Account | `message send` |
330
- | `bot.read` | Bot channel/member read | Service Account | `message members` |
331
- | `calendar` | Calendar write | User OAuth | `calendar create/update/delete` (requires calendar.read) |
332
- | `calendar.read` | Calendar read | User OAuth | `calendar list`, also needed for calendar write |
333
- | `file` | Drive read/write | User OAuth | `drive list/upload/download` |
334
- | `file.read` | Drive read-only | User OAuth | `drive list/download` |
335
- | `mail` | Mail read/write | User OAuth | `mail send/list/read` |
336
- | `mail.read` | Mail read-only | User OAuth | `mail list/read` |
337
- | `task` | Tasks read/write | User OAuth | `task create/update/delete` (requires user.read) |
338
- | `task.read` | Tasks read-only | User OAuth | `task list` |
339
- | `user.read` | User info read | Service Account / User OAuth | `directory members`, also needed for task write |
340
- | `board` | Boards read/write | User OAuth | `board list/posts/read/create` |
341
- | `board.read` | Boards read-only | User OAuth | `board list/posts/read` |
342
-
343
- > **Tip**: After changing scopes, reissue your token:
344
- > ```bash
345
- > nworks logout && nworks login --user --scope "..."
346
- > ```
347
-
348
- ---
349
-
350
- ## Environment Variables
351
-
352
- Set environment variables to use nworks without `nworks login` (useful for CI/agents).
353
-
354
- ```bash
355
- # Required
356
- NWORKS_CLIENT_ID=
357
- NWORKS_CLIENT_SECRET=
358
-
359
- # Bot messaging only (not needed for User OAuth)
360
- NWORKS_SERVICE_ACCOUNT=
361
- NWORKS_PRIVATE_KEY_PATH=
362
- NWORKS_BOT_ID=
363
-
364
- # Optional
365
- NWORKS_DOMAIN_ID=
366
- NWORKS_SCOPE= # default: bot bot.read user.read
367
- NWORKS_VERBOSE=1 # debug logging
368
- ```
369
-
370
- ### MCP Server with Environment Variables
371
-
372
- Sensitive values (Client Secret, Private Key path) must be set via MCP config `env` field. Non-sensitive values like Client ID can be configured by the AI agent through the `nworks_setup` tool.
373
-
374
- ```json
375
- {
376
- "mcpServers": {
377
- "nworks": {
378
- "command": "npx",
379
- "args": ["-y", "nworks", "mcp"],
380
- "env": {
381
- "NWORKS_CLIENT_SECRET": "<Client Secret>",
382
- "NWORKS_PRIVATE_KEY_PATH": "<Private Key file absolute path (for Service Account)>"
383
- }
384
- }
385
- }
386
- }
387
- ```
388
-
389
- ---
390
-
391
- ## License
392
-
393
- Apache-2.0
1
+ # nworks
2
+
3
+ [![npm version](https://img.shields.io/npm/v/nworks.svg)](https://www.npmjs.com/package/nworks)
4
+ [![license](https://img.shields.io/npm/l/nworks.svg)](LICENSE)
5
+ [![npm downloads](https://img.shields.io/npm/dm/nworks.svg)](https://www.npmjs.com/package/nworks)
6
+ [![nworks MCP server](https://glama.ai/mcp/servers/yjcho9317/nworks/badges/score.svg)](https://glama.ai/mcp/servers/yjcho9317/nworks)
7
+
8
+ Featured in [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
9
+
10
+ πŸ‡ΊπŸ‡Έ English | [πŸ‡°πŸ‡· ν•œκ΅­μ–΄](README.ko.md) | [πŸ‡―πŸ‡΅ ζ—₯本θͺž](README.ja.md)
11
+
12
+ <p align="center">
13
+ <img src="assets/demo.gif" width="600" alt="nworks demo">
14
+ </p>
15
+
16
+ Full-featured MCP server for LINE WORKS (NAVER WORKS).
17
+ CLI + MCP server β€” 36 tools covering messages, calendar, drive, mail, tasks, and boards.
18
+
19
+ 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.
20
+
21
+ ## Quickstart
22
+
23
+ ```bash
24
+ npm install -g nworks
25
+ nworks login --user
26
+ nworks calendar list
27
+ ```
28
+
29
+ > **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).
30
+
31
+ ### AI Agents Actually Use It Like This
32
+
33
+ ```
34
+ User: Show me today's schedule
35
+
36
+ Claude β†’ nworks_calendar_list
37
+ β†’ 3 events: Standup (10:00), Lunch meeting (12:00), Code review (15:00)
38
+
39
+ User: Send a deploy complete message to the team channel
40
+
41
+ Claude β†’ nworks_message_send
42
+ { "channel": "C001", "text": "v1.2.0 deploy complete" }
43
+ β†’ Message sent
44
+
45
+ User: Check my unread emails and summarize them
46
+
47
+ Claude β†’ nworks_mail_list (unread)
48
+ β†’ 3 unread emails
49
+ Claude β†’ nworks_mail_read (each)
50
+ β†’ "3 unread: 1) Deploy approval from CTO, 2) Meeting invite for Friday, 3) Weekly report reminder"
51
+ ```
52
+
53
+ ## Install
54
+
55
+ ```bash
56
+ npx nworks # Run directly
57
+ npm install -g nworks # Global install
58
+ ```
59
+
60
+ ## Login
61
+
62
+ ```bash
63
+ # User OAuth (calendar, drive, mail, tasks, boards)
64
+ nworks login --user --scope "calendar calendar.read file file.read mail mail.read task task.read board board.read user.read"
65
+
66
+ # Bot messaging (Service Account)
67
+ nworks login
68
+
69
+ # Check auth status
70
+ nworks whoami
71
+
72
+ # Logout
73
+ nworks logout
74
+ ```
75
+
76
+ > `nworks login --user` only requires CLIENT_ID + CLIENT_SECRET. Values already set via environment variables or existing config won't be asked again.
77
+
78
+ > **Developer Console**: To use User OAuth, register `http://localhost:9876/callback` as a Redirect URL in the [Developer Console](https://dev.worksmobile.com/en/).
79
+
80
+ ---
81
+
82
+ ## AI Agent Integration (MCP Server)
83
+
84
+ Works with Claude Desktop, Cursor, and other MCP-compatible clients.
85
+
86
+ ### Setup
87
+
88
+ Login first:
89
+
90
+ ```bash
91
+ nworks login --user --scope "calendar calendar.read file file.read mail mail.read task task.read board board.read user.read"
92
+ ```
93
+
94
+ Then add to your MCP config (`~/.config/claude/claude_desktop_config.json`):
95
+
96
+ ```json
97
+ {
98
+ "mcpServers": {
99
+ "nworks": {
100
+ "command": "nworks",
101
+ "args": ["mcp"]
102
+ }
103
+ }
104
+ }
105
+ ```
106
+
107
+ One login enables all 36 tools. No extra env setup needed.
108
+
109
+ > 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.
110
+
111
+ ### MCP Tools (32)
112
+
113
+ | Tool | Description | Auth |
114
+ |------|-------------|------|
115
+ | **Setup / Auth** | | |
116
+ | `nworks_setup` | Configure API credentials (Client ID, etc.). Client Secret is set via env | β€” |
117
+ | `nworks_login_user` | User OAuth browser login (all scopes included) | β€” |
118
+ | `nworks_logout` | Delete credentials and tokens | β€” |
119
+ | `nworks_whoami` | Check auth status | β€” |
120
+ | `nworks_doctor` | Diagnose connection (auth, tokens, API health) | β€” |
121
+ | **Messages** | | |
122
+ | `nworks_message_send` | Send message to user/channel | Service Account |
123
+ | `nworks_message_members` | List channel members | Service Account |
124
+ | `nworks_directory_members` | List organization members | Service Account |
125
+ | **Calendar** | | |
126
+ | `nworks_calendar_list` | List calendar events | User OAuth (calendar.read) |
127
+ | `nworks_calendar_create` | Create calendar event | User OAuth (calendar + calendar.read) |
128
+ | `nworks_calendar_update` | Update calendar event | User OAuth (calendar + calendar.read) |
129
+ | `nworks_calendar_delete` | Delete calendar event | User OAuth (calendar + calendar.read) |
130
+ | **Drive** | | |
131
+ | `nworks_drive_list` | List drive files/folders | User OAuth (file.read) |
132
+ | `nworks_drive_upload` | Upload file to drive | User OAuth (file) |
133
+ | `nworks_drive_download` | Download file (saves locally if >5MB) | User OAuth (file.read) |
134
+ | `nworks_sharedrive_list` | List shared drives | User OAuth (file.read) |
135
+ | `nworks_sharedrive_files` | List files/folders in a shared drive | User OAuth (file.read) |
136
+ | `nworks_sharedrive_download` | Download a shared drive file (saves locally if >5MB) | User OAuth (file.read) |
137
+ | **Mail** | | |
138
+ | `nworks_mail_send` | Send mail | User OAuth (mail) |
139
+ | `nworks_mail_list` | List mailbox | User OAuth (mail.read) |
140
+ | `nworks_mail_read` | Read mail detail | User OAuth (mail.read) |
141
+ | `nworks_mail_download_attachment` | Download a mail attachment (saves locally if >5MB) | User OAuth (mail.read) |
142
+ | **Tasks** | | |
143
+ | `nworks_task_list` | List tasks | User OAuth (task.read) |
144
+ | `nworks_task_create` | Create task | User OAuth (task + user.read) |
145
+ | `nworks_task_update` | Update/complete task | User OAuth (task + user.read) |
146
+ | `nworks_task_delete` | Delete task | User OAuth (task + user.read) |
147
+ | **Boards** | | |
148
+ | `nworks_board_list` | List boards | User OAuth (board.read) |
149
+ | `nworks_board_posts` | List board posts | User OAuth (board.read) |
150
+ | `nworks_board_read` | Read board post detail | User OAuth (board.read) |
151
+ | `nworks_board_create` | Create board post | User OAuth (board) |
152
+ | **Contacts** | | |
153
+ | `nworks_contact_list` | List contacts | User OAuth (contact.read) |
154
+ | `nworks_contact_get` | Get contact detail | User OAuth (contact.read) |
155
+ | `nworks_contact_create` | Create contact | User OAuth (contact) |
156
+ | `nworks_contact_update` | Update contact | User OAuth (contact) |
157
+ | `nworks_contact_delete` | Delete contact | User OAuth (contact) |
158
+ | `nworks_contact_list_tags` | List contact tags | User OAuth (contact.read) |
159
+
160
+ ### AI Agent Usage Example
161
+
162
+ ```
163
+ User: Schedule a meeting tomorrow at 2pm and notify the team channel
164
+
165
+ Claude β†’ nworks_calendar_create
166
+ { "summary": "Meeting", "start": "2026-03-15T14:00:00", "end": "2026-03-15T15:00:00" }
167
+ β†’ Event created
168
+
169
+ Claude β†’ nworks_message_send
170
+ { "channel": "C001", "text": "Meeting scheduled tomorrow at 14:00" }
171
+ β†’ Message sent
172
+
173
+ User: Check my unread emails and summarize them
174
+
175
+ Claude β†’ nworks_mail_list (unread)
176
+ β†’ 3 unread emails
177
+ Claude β†’ nworks_mail_read (each)
178
+ β†’ "3 unread: 1) Deploy approval from CTO, 2) Meeting invite for Friday, 3) Weekly report reminder"
179
+ ```
180
+
181
+ ---
182
+
183
+ ## CLI Usage
184
+
185
+ > All commands support `--json` for pipe/script/agent parsing. `message send`, `mail send`, and `drive upload` support `--dry-run` for testing without sending.
186
+
187
+ ### Messages (Bot API)
188
+
189
+ ```bash
190
+ # Send text to user
191
+ nworks message send --to <userId> --text "Hello"
192
+
193
+ # Send text to channel
194
+ nworks message send --channel <channelId> --text "Announcement"
195
+
196
+ # Button message
197
+ nworks message send --to <userId> --type button --text "PR review request" \
198
+ --actions '[{"type":"message","label":"Approve","postback":"approve"}]'
199
+
200
+ # List message
201
+ nworks message send --to <userId> --type list --text "Today's tasks" \
202
+ --elements '[{"title":"Code review","subtitle":"PR #382"}]'
203
+
204
+ # List channel members
205
+ nworks message members --channel <channelId>
206
+ ```
207
+
208
+ ### Directory
209
+
210
+ ```bash
211
+ nworks directory members # List organization members
212
+ ```
213
+
214
+ ### Calendar (User OAuth)
215
+
216
+ ```bash
217
+ # List today's events
218
+ nworks calendar list
219
+
220
+ # Specify date range
221
+ nworks calendar list --from "2026-03-14T00:00:00+09:00" --until "2026-03-14T23:59:59+09:00"
222
+
223
+ # Create event
224
+ nworks calendar create --title "Meeting" --start "2026-03-14T14:00+09:00" --end "2026-03-14T15:00+09:00"
225
+
226
+ # With location/description
227
+ nworks calendar create --title "Lunch" --start "2026-03-14T12:00+09:00" --end "2026-03-14T13:00+09:00" \
228
+ --location "Conference Room" --description "Quarterly review"
229
+
230
+ # With attendees + notification
231
+ nworks calendar create --title "Team meeting" --start "2026-03-14T10:00+09:00" --end "2026-03-14T11:00+09:00" \
232
+ --attendees "user1@example.com,user2@example.com" --notify
233
+
234
+ # Update event
235
+ nworks calendar update --id <eventId> --title "Updated title"
236
+
237
+ # Delete event
238
+ nworks calendar delete --id <eventId>
239
+ ```
240
+
241
+ ### Drive (User OAuth)
242
+
243
+ ```bash
244
+ # List files/folders
245
+ nworks drive list
246
+
247
+ # Upload file
248
+ nworks drive upload --file ./report.pdf
249
+
250
+ # Upload to specific folder
251
+ nworks drive upload --file ./report.pdf --folder <folderId>
252
+
253
+ # Download file
254
+ nworks drive download --file-id <fileId>
255
+
256
+ # Specify output path/name
257
+ nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
258
+
259
+ # List shared drives
260
+ nworks drive sharedrive-list
261
+
262
+ # List files in a shared drive (root)
263
+ nworks drive sharedrive-files --sharedrive <sharedriveId>
264
+
265
+ # List files in a shared drive folder
266
+ nworks drive sharedrive-files --sharedrive <sharedriveId> --folder <fileId>
267
+
268
+ # Download a shared drive file
269
+ nworks drive sharedrive-download --sharedrive <sharedriveId> --file-id <fileId>
270
+ ```
271
+
272
+ ### Mail (User OAuth)
273
+
274
+ ```bash
275
+ # Send mail
276
+ nworks mail send --to "user@example.com" --subject "Subject" --body "Body"
277
+
278
+ # With CC/BCC
279
+ nworks mail send --to "user@example.com" --cc "cc@example.com" --subject "Subject" --body "Body"
280
+
281
+ # List inbox
282
+ nworks mail list
283
+
284
+ # Unread only
285
+ nworks mail list --unread
286
+
287
+ # Read mail detail
288
+ nworks mail read --id <mailId>
289
+
290
+ # Download a mail attachment
291
+ nworks mail download-attachment --id <mailId> --attachment-id <attachmentId>
292
+
293
+ # Specify output path/name
294
+ nworks mail download-attachment --id <mailId> --attachment-id <attachmentId> --out ./downloads --name invoice.pdf
295
+ ```
296
+
297
+ ### Tasks (User OAuth)
298
+
299
+ ```bash
300
+ # List tasks
301
+ nworks task list
302
+
303
+ # Incomplete only
304
+ nworks task list --status TODO
305
+
306
+ # Create task
307
+ nworks task create --title "Code review" --body "Review PR #382"
308
+
309
+ # With due date
310
+ nworks task create --title "Deploy" --due 2026-03-20
311
+
312
+ # Mark as done
313
+ nworks task update --id <taskId> --status done
314
+
315
+ # Delete task
316
+ nworks task delete --id <taskId>
317
+ ```
318
+
319
+ ### Boards (User OAuth)
320
+
321
+ ```bash
322
+ # List boards
323
+ nworks board list
324
+
325
+ # List posts
326
+ nworks board posts --board <boardId>
327
+
328
+ # Read post detail
329
+ nworks board read --board <boardId> --post <postId>
330
+
331
+ # Create post
332
+ nworks board create --board <boardId> --title "Announcement" --body "Content"
333
+
334
+ # With notification + disable comments
335
+ nworks board create --board <boardId> --title "Notice" --body "Content" --notify --no-comment
336
+ ```
337
+
338
+ ### Contacts (User OAuth)
339
+
340
+ ```bash
341
+ # List contacts
342
+ nworks contact list
343
+
344
+ # Filter by tag
345
+ nworks contact list --tag <contactTagId>
346
+
347
+ # Get contact detail
348
+ nworks contact get --id <contactId>
349
+
350
+ # Create contact
351
+ 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"}]}}'
352
+
353
+ # Update contact
354
+ nworks contact update --id <contactId> --payload '{"telephones":[{"type":"CELLPHONE","telephone":"010-1234-5678","primary":true}]}'
355
+
356
+ # Delete contact
357
+ nworks contact delete --id <contactId>
358
+
359
+ # List contact tags
360
+ nworks contact list-tags
361
+ ```
362
+
363
+ > `contact create` requires `contactName` and `permission`; `permission.accessibleMembers` must list at least one member (usually yourself). Get your own user ID from `nworks whoami`.
364
+
365
+
366
+ ### CI/CD Deploy Notification
367
+
368
+ ```bash
369
+ # Notify team channel after deployment in GitHub Actions
370
+ nworks message send --channel $CHANNEL_ID --text "v${VERSION} deployed"
371
+ ```
372
+
373
+ ### Team Automation Script
374
+
375
+ ```bash
376
+ # Send daily standup reminder to all members
377
+ for userId in $(nworks directory members --json | jq -r '.users[].userId'); do
378
+ nworks message send --to "$userId" --text "Standup at 10:00 today"
379
+ done
380
+ ```
381
+
382
+ ---
383
+
384
+ ## OAuth Scopes
385
+
386
+ Add the required scopes in the [LINE WORKS Developer Console](https://dev.worksmobile.com/en/).
387
+
388
+ | Scope | Purpose | Auth | Required For |
389
+ |-------|---------|------|-------------|
390
+ | `bot` | Bot messaging | Service Account | `message send` |
391
+ | `bot.read` | Bot channel/member read | Service Account | `message members` |
392
+ | `calendar` | Calendar write | User OAuth | `calendar create/update/delete` (requires calendar.read) |
393
+ | `calendar.read` | Calendar read | User OAuth | `calendar list`, also needed for calendar write |
394
+ | `file` | Drive read/write | User OAuth | `drive list/upload/download` |
395
+ | `file.read` | Drive read-only | User OAuth | `drive list/download` |
396
+ | `mail` | Mail read/write | User OAuth | `mail send/list/read` |
397
+ | `mail.read` | Mail read-only | User OAuth | `mail list/read` |
398
+ | `task` | Tasks read/write | User OAuth | `task create/update/delete` (requires user.read) |
399
+ | `task.read` | Tasks read-only | User OAuth | `task list` |
400
+ | `user.read` | User info read | Service Account / User OAuth | `directory members`, also needed for task write |
401
+ | `board` | Boards read/write | User OAuth | `board list/posts/read/create` |
402
+ | `board.read` | Boards read-only | User OAuth | `board list/posts/read` |
403
+ | `contact` | Contacts read/write | User OAuth | `contact create/update/delete` (requires contact.read) |
404
+ | `contact.read` | Contacts read-only | User OAuth | `contact list/get/list-tags` |
405
+
406
+ > **Presets** are simpler than listing scopes:
407
+ > ```bash
408
+ > nworks login --user --preset all # default: full functionality in one login
409
+ > nworks login --user --preset readonly # read-only scopes
410
+ > ```
411
+ > `default` is an alias of `all`. Message sending uses the Service Account (bot), so it works regardless of preset.
412
+ > 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"`.
413
+
414
+ ---
415
+
416
+ ## Environment Variables
417
+
418
+ Set environment variables to use nworks without `nworks login` (useful for CI/agents).
419
+
420
+ ```bash
421
+ # Required
422
+ NWORKS_CLIENT_ID=
423
+ NWORKS_CLIENT_SECRET=
424
+
425
+ # Bot messaging only (not needed for User OAuth)
426
+ NWORKS_SERVICE_ACCOUNT=
427
+ NWORKS_PRIVATE_KEY_PATH=
428
+ NWORKS_BOT_ID=
429
+
430
+ # Optional
431
+ NWORKS_DOMAIN_ID=
432
+ NWORKS_SCOPE= # default: bot bot.read user.read
433
+ NWORKS_VERBOSE=1 # debug logging
434
+ ```
435
+
436
+ ### MCP Server with Environment Variables
437
+
438
+ Sensitive values (Client Secret, Private Key path) must be set via MCP config `env` field. Non-sensitive values like Client ID can be configured by the AI agent through the `nworks_setup` tool.
439
+
440
+ ```json
441
+ {
442
+ "mcpServers": {
443
+ "nworks": {
444
+ "command": "npx",
445
+ "args": ["-y", "nworks", "mcp"],
446
+ "env": {
447
+ "NWORKS_CLIENT_SECRET": "<Client Secret>",
448
+ "NWORKS_PRIVATE_KEY_PATH": "<Private Key file absolute path (for Service Account)>"
449
+ }
450
+ }
451
+ }
452
+ }
453
+ ```
454
+
455
+ ---
456
+
457
+ ## License
458
+
459
+ Apache-2.0