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.ja.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.md) | [🇰🇷 한국어](README.ko.md) | 🇯🇵 日本語
11
-
12
- <p align="center">
13
- <img src="assets/demo.gif" width="600" alt="nworks demo">
14
- </p>
15
-
16
- LINE WORKS (NAVER WORKS) 初のMCPサーバー。
17
- メッセージ、カレンダー、ドライブ、メール、タスク、掲示板 — 26ツール対応のCLI + MCPサーバーです。
18
-
19
- ## クイックスタート
20
-
21
- ```bash
22
- npm install -g nworks
23
- nworks login --user
24
- nworks calendar list
25
- ```
26
-
27
- ### AIエージェントの使用例
28
-
29
- ```
30
- ユーザー: 今日の予定を教えて
31
-
32
- Claude → nworks_calendar_list
33
- → 3件: スタンドアップ(10:00)、ランチミーティング(12:00)、コードレビュー(15:00)
34
-
35
- ユーザー: チームチャンネルにデプロイ完了メッセージを送って
36
-
37
- Claude → nworks_message_send
38
- { "channel": "C001", "text": "v1.2.0 デプロイ完了" }
39
- → メッセージが送信されました
40
-
41
- ユーザー: 未読メールを確認して要約して
42
-
43
- Claude → nworks_mail_list (unread)
44
- → 未読メール3件
45
- Claude → nworks_mail_read (各)
46
- → "3件: 1) CTOからのデプロイ承認, 2) 金曜日のミーティング招待, 3) 週次レポートリマインダー"
47
- ```
48
-
49
- ## インストール
50
-
51
- ```bash
52
- npx nworks # 直接実行
53
- npm install -g nworks # グローバルインストール
54
- ```
55
-
56
- ## ログイン
57
-
58
- ```bash
59
- # User OAuth（カレンダー、ドライブ、メール、タスク、掲示板）
60
- nworks login --user --scope "calendar calendar.read file file.read mail mail.read task task.read board board.read user.read"
61
-
62
- # ボットメッセージ送信が必要な場合（Service Account）
63
- nworks login
64
-
65
- # 認証状態の確認
66
- nworks whoami
67
-
68
- # ログアウト
69
- nworks logout
70
- ```
71
-
72
- > `nworks login --user` にはCLIENT_IDとCLIENT_SECRETのみ必要です。環境変数や既存の設定に値がある場合は再入力を求めません。
73
-
74
- > **Developer Console設定**: User OAuthを使用するには、[Developer Console](https://dev.worksmobile.com/jp/)でRedirect URLに `http://localhost:9876/callback` を登録してください。
75
-
76
- ---
77
-
78
- ## AIエージェント連携（MCPサーバー）
79
-
80
- Claude Desktop、Cursorなど、MCP対応クライアントから利用できます。
81
-
82
- ### セットアップ
83
-
84
- まずログインします：
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
- 次にMCP設定に追加します（`~/.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
- 一度のログインで26ツールすべて利用可能。追加のenv設定は不要です。
104
-
105
- > CLIログインなしでも、AIエージェントが `nworks_setup` → `nworks_login_user` を呼び出せばブラウザから直接認証できます。Client SecretとPrivate Keyのパスは、MCP設定の `env` フィールドまたはシステム環境変数で事前に設定してください。
106
-
107
- ### MCPツール一覧（26個）
108
-
109
- | ツール | 説明 | 必要な認証 |
110
- |--------|------|-----------|
111
- | **設定/認証** | | |
112
- | `nworks_setup` | API認証情報の設定（Client IDなど）。Client Secretは環境変数で設定 | — |
113
- | `nworks_login_user` | User OAuthブラウザログイン（全scope自動含む） | — |
114
- | `nworks_logout` | 認証情報とトークンの削除 | — |
115
- | `nworks_whoami` | 認証状態の確認 | — |
116
- | `nworks_doctor` | 接続診断（認証、トークン、APIヘルスチェック） | — |
117
- | **メッセージ** | | |
118
- | `nworks_message_send` | ユーザー/チャンネルにメッセージ送信 | Service Account |
119
- | `nworks_message_members` | チャンネルメンバー一覧 | Service Account |
120
- | `nworks_directory_members` | 組織メンバー一覧 | Service Account |
121
- | **カレンダー** | | |
122
- | `nworks_calendar_list` | カレンダー予定の一覧 | User OAuth (calendar.read) |
123
- | `nworks_calendar_create` | カレンダー予定の作成 | User OAuth (calendar + calendar.read) |
124
- | `nworks_calendar_update` | カレンダー予定の更新 | User OAuth (calendar + calendar.read) |
125
- | `nworks_calendar_delete` | カレンダー予定の削除 | User OAuth (calendar + calendar.read) |
126
- | **ドライブ** | | |
127
- | `nworks_drive_list` | ドライブのファイル/フォルダ一覧 | User OAuth (file.read) |
128
- | `nworks_drive_upload` | ドライブにファイルアップロード | User OAuth (file) |
129
- | `nworks_drive_download` | ドライブからファイルダウンロード（5MB超はローカル保存） | User OAuth (file.read) |
130
- | **メール** | | |
131
- | `nworks_mail_send` | メール送信 | User OAuth (mail) |
132
- | `nworks_mail_list` | メールボックス一覧 | User OAuth (mail.read) |
133
- | `nworks_mail_read` | メール詳細表示 | User OAuth (mail.read) |
134
- | **タスク** | | |
135
- | `nworks_task_list` | タスク一覧 | User OAuth (task.read) |
136
- | `nworks_task_create` | タスク作成 | User OAuth (task + user.read) |
137
- | `nworks_task_update` | タスク更新/完了 | User OAuth (task + user.read) |
138
- | `nworks_task_delete` | タスク削除 | User OAuth (task + user.read) |
139
- | **掲示板** | | |
140
- | `nworks_board_list` | 掲示板一覧 | User OAuth (board.read) |
141
- | `nworks_board_posts` | 掲示板の投稿一覧 | User OAuth (board.read) |
142
- | `nworks_board_read` | 掲示板の投稿詳細 | User OAuth (board.read) |
143
- | `nworks_board_create` | 掲示板に投稿作成 | User OAuth (board) |
144
-
145
- ### AIエージェント使用例
146
-
147
- ```
148
- ユーザー: 明日14時にミーティングを入れて、チームチャンネルに知らせて
149
-
150
- Claude → nworks_calendar_create
151
- { "summary": "ミーティング", "start": "2026-03-15T14:00:00", "end": "2026-03-15T15:00:00" }
152
- → 予定が作成されました
153
-
154
- Claude → nworks_message_send
155
- { "channel": "C001", "text": "明日14:00にミーティングが設定されました" }
156
- → メッセージが送信されました
157
-
158
- ユーザー: 未読メールを確認して要約して
159
-
160
- Claude → nworks_mail_list (unread)
161
- → 未読メール3件
162
- Claude → nworks_mail_read (各)
163
- → "3件: 1) CTOからのデプロイ承認, 2) 金曜日のミーティング招待, 3) 週次レポートリマインダー"
164
- ```
165
-
166
- ---
167
-
168
- ## CLIの使い方
169
-
170
- > すべてのコマンドで `--json` に対応（パイプ、スクリプト、エージェント解析に便利）。`message send`、`mail send`、`drive upload` は `--dry-run` で実際の送信なしにテスト可能。
171
-
172
- ### メッセージ（Bot API）
173
-
174
- ```bash
175
- # ユーザーにテキストメッセージ
176
- nworks message send --to <userId> --text "メッセージ"
177
-
178
- # チャンネルにテキストメッセージ
179
- nworks message send --channel <channelId> --text "お知らせ"
180
-
181
- # ボタンメッセージ
182
- nworks message send --to <userId> --type button --text "PRレビュー依頼" \
183
- --actions '[{"type":"message","label":"承認","postback":"approve"}]'
184
-
185
- # リストメッセージ
186
- nworks message send --to <userId> --type list --text "今日のタスク" \
187
- --elements '[{"title":"コードレビュー","subtitle":"PR #382"}]'
188
-
189
- # チャンネルメンバー一覧
190
- nworks message members --channel <channelId>
191
- ```
192
-
193
- ### 組織（Directory API）
194
-
195
- ```bash
196
- nworks directory members # 組織メンバー一覧
197
- ```
198
-
199
- ### カレンダー（User OAuth）
200
-
201
- ```bash
202
- # 今日の予定一覧
203
- nworks calendar list
204
-
205
- # 期間指定
206
- nworks calendar list --from "2026-03-14T00:00:00+09:00" --until "2026-03-14T23:59:59+09:00"
207
-
208
- # 予定の作成
209
- nworks calendar create --title "ミーティング" --start "2026-03-14T14:00+09:00" --end "2026-03-14T15:00+09:00"
210
-
211
- # 場所/説明付き
212
- nworks calendar create --title "ランチ" --start "2026-03-14T12:00+09:00" --end "2026-03-14T13:00+09:00" \
213
- --location "会議室" --description "四半期レビュー"
214
-
215
- # 参加者指定 + 通知
216
- nworks calendar create --title "チームミーティング" --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
- # 予定の更新
220
- nworks calendar update --id <eventId> --title "変更後のタイトル"
221
-
222
- # 予定の削除
223
- nworks calendar delete --id <eventId>
224
- ```
225
-
226
- ### ドライブ（User OAuth）
227
-
228
- ```bash
229
- # ファイル/フォルダ一覧
230
- nworks drive list
231
-
232
- # ファイルアップロード
233
- nworks drive upload --file ./report.pdf
234
-
235
- # 特定フォルダにアップロード
236
- nworks drive upload --file ./report.pdf --folder <folderId>
237
-
238
- # ファイルダウンロード
239
- nworks drive download --file-id <fileId>
240
-
241
- # 出力先/ファイル名指定
242
- nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
243
- ```
244
-
245
- ### メール（User OAuth）
246
-
247
- ```bash
248
- # メール送信
249
- nworks mail send --to "user@example.com" --subject "件名" --body "本文"
250
-
251
- # CC/BCC付き
252
- nworks mail send --to "user@example.com" --cc "cc@example.com" --subject "件名" --body "本文"
253
-
254
- # 受信トレイ一覧
255
- nworks mail list
256
-
257
- # 未読のみ
258
- nworks mail list --unread
259
-
260
- # メール詳細表示
261
- nworks mail read --id <mailId>
262
- ```
263
-
264
- ### タスク（User OAuth）
265
-
266
- ```bash
267
- # タスク一覧
268
- nworks task list
269
-
270
- # 未完了のみ
271
- nworks task list --status TODO
272
-
273
- # タスク作成
274
- nworks task create --title "コードレビュー" --body "PR #382 レビュー"
275
-
276
- # 期限付き
277
- nworks task create --title "デプロイ" --due 2026-03-20
278
-
279
- # 完了にする
280
- nworks task update --id <taskId> --status done
281
-
282
- # タスク削除
283
- nworks task delete --id <taskId>
284
- ```
285
-
286
- ### 掲示板（User OAuth）
287
-
288
- ```bash
289
- # 掲示板一覧
290
- nworks board list
291
-
292
- # 投稿一覧
293
- nworks board posts --board <boardId>
294
-
295
- # 投稿詳細
296
- nworks board read --board <boardId> --post <postId>
297
-
298
- # 投稿作成
299
- nworks board create --board <boardId> --title "お知らせ" --body "内容"
300
-
301
- # 通知付き + コメント無効化
302
- nworks board create --board <boardId> --title "通知" --body "内容" --notify --no-comment
303
- ```
304
-
305
- ### CI/CDデプロイ通知
306
-
307
- ```bash
308
- # GitHub Actionsでデプロイ完了後、チームチャンネルに通知
309
- nworks message send --channel $CHANNEL_ID --text "v${VERSION} デプロイ完了"
310
- ```
311
-
312
- ### チーム自動化スクリプト
313
-
314
- ```bash
315
- # 毎朝チームメンバーにリマインダー送信
316
- for userId in $(nworks directory members --json | jq -r '.users[].userId'); do
317
- nworks message send --to "$userId" --text "本日のスタンドアップは10時です"
318
- done
319
- ```
320
-
321
- ---
322
-
323
- ## OAuth Scope設定
324
-
325
- [LINE WORKS Developer Console](https://dev.worksmobile.com/jp/)でアプリのOAuth Scopeを追加してください。
326
-
327
- | Scope | 用途 | 認証方式 | 必要なコマンド |
328
- |-------|------|---------|---------------|
329
- | `bot` | Botメッセージ送信 | Service Account | `message send` |
330
- | `bot.read` | Botチャンネル/メンバー取得 | Service Account | `message members` |
331
- | `calendar` | カレンダー書き込み | User OAuth | `calendar create/update/delete`（calendar.readも必要） |
332
- | `calendar.read` | カレンダー読み取り | User OAuth | `calendar list`、カレンダー書き込みの依存関係 |
333
- | `file` | ドライブ読み書き | User OAuth | `drive list/upload/download` |
334
- | `file.read` | ドライブ読み取り専用 | User OAuth | `drive list/download` |
335
- | `mail` | メール読み書き | User OAuth | `mail send/list/read` |
336
- | `mail.read` | メール読み取り専用 | User OAuth | `mail list/read` |
337
- | `task` | タスク読み書き | User OAuth | `task create/update/delete`（user.readも必要） |
338
- | `task.read` | タスク読み取り専用 | User OAuth | `task list` |
339
- | `user.read` | ユーザー情報取得 | Service Account / User OAuth | `directory members`、タスク書き込みの依存関係 |
340
- | `board` | 掲示板読み書き | User OAuth | `board list/posts/read/create` |
341
- | `board.read` | 掲示板読み取り専用 | User OAuth | `board list/posts/read` |
342
-
343
- > **ヒント**: scopeを変更した後はトークンを再発行してください。
344
- > ```bash
345
- > nworks logout && nworks login --user --scope "..."
346
- > ```
347
-
348
- ---
349
-
350
- ## 環境変数
351
-
352
- 環境変数で認証情報を設定すると、`nworks login` なしで利用できます（CI/エージェント向け）。
353
-
354
- ```bash
355
- # 必須
356
- NWORKS_CLIENT_ID=
357
- NWORKS_CLIENT_SECRET=
358
-
359
- # ボットメッセージ送信時のみ必要（User OAuthのみなら不要）
360
- NWORKS_SERVICE_ACCOUNT=
361
- NWORKS_PRIVATE_KEY_PATH=
362
- NWORKS_BOT_ID=
363
-
364
- # オプション
365
- NWORKS_DOMAIN_ID=
366
- NWORKS_SCOPE= # デフォルト: bot bot.read user.read
367
- NWORKS_VERBOSE=1 # デバッグログ
368
- ```
369
-
370
- ### MCPサーバーに環境変数を直接設定
371
-
372
- 機密情報（Client Secret、Private Keyパス）はMCP設定の `env` フィールドで設定します。Client IDなどの非機密情報は、AIエージェントが `nworks_setup` ツールで直接設定できます。
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ファイルの絶対パス（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.md) | [🇰🇷 한국어](README.ko.md) | 🇯🇵 日本語
11
+
12
+ <p align="center">
13
+ <img src="assets/demo.gif" width="600" alt="nworks demo">
14
+ </p>
15
+
16
+ LINE WORKS (NAVER WORKS) 初のMCPサーバー。
17
+ メッセージ、カレンダー、ドライブ、メール、タスク、掲示板 — 36ツール対応のCLI + MCPサーバーです。
18
+
19
+ nworksは、**外部**のAIエージェント（Claude、Cursor）やターミナルからLINE WORKSを*操作*するためのレイヤーです。LINE WORKS自身の社内向けAI（AiStudio、WORKS AI）とは競合せず、補完関係にあります。非公式・コミュニティ運営であり、LINE WORKS / NAVER WORKSとの提携関係はありません。
20
+
21
+ ## クイックスタート
22
+
23
+ ```bash
24
+ npm install -g nworks
25
+ nworks login --user
26
+ nworks calendar list
27
+ ```
28
+
29
+ > **初めての方へ:** まずDeveloper Consoleアプリ（Client ID/Secret）、redirect URLの登録、そしてボットメッセージの場合は管理者の承認が必要です。[オンボーディング & 管理者セットアップガイド](ONBOARDING.md)を参照してください。
30
+
31
+ ### AIエージェントの使用例
32
+
33
+ ```
34
+ ユーザー: 今日の予定を教えて
35
+
36
+ Claude → nworks_calendar_list
37
+ → 3件: スタンドアップ(10:00)、ランチミーティング(12:00)、コードレビュー(15:00)
38
+
39
+ ユーザー: チームチャンネルにデプロイ完了メッセージを送って
40
+
41
+ Claude → nworks_message_send
42
+ { "channel": "C001", "text": "v1.2.0 デプロイ完了" }
43
+ → メッセージが送信されました
44
+
45
+ ユーザー: 未読メールを確認して要約して
46
+
47
+ Claude → nworks_mail_list (unread)
48
+ → 未読メール3件
49
+ Claude → nworks_mail_read (各)
50
+ → "3件: 1) CTOからのデプロイ承認, 2) 金曜日のミーティング招待, 3) 週次レポートリマインダー"
51
+ ```
52
+
53
+ ## インストール
54
+
55
+ ```bash
56
+ npx nworks # 直接実行
57
+ npm install -g nworks # グローバルインストール
58
+ ```
59
+
60
+ ## ログイン
61
+
62
+ ```bash
63
+ # User OAuth（カレンダー、ドライブ、メール、タスク、掲示板）
64
+ nworks login --user --scope "calendar calendar.read file file.read mail mail.read task task.read board board.read user.read"
65
+
66
+ # ボットメッセージ送信が必要な場合（Service Account）
67
+ nworks login
68
+
69
+ # 認証状態の確認
70
+ nworks whoami
71
+
72
+ # ログアウト
73
+ nworks logout
74
+ ```
75
+
76
+ > `nworks login --user` にはCLIENT_IDとCLIENT_SECRETのみ必要です。環境変数や既存の設定に値がある場合は再入力を求めません。
77
+
78
+ > **Developer Console設定**: User OAuthを使用するには、[Developer Console](https://dev.worksmobile.com/jp/)でRedirect URLに `http://localhost:9876/callback` を登録してください。
79
+
80
+ ---
81
+
82
+ ## AIエージェント連携（MCPサーバー）
83
+
84
+ Claude Desktop、Cursorなど、MCP対応クライアントから利用できます。
85
+
86
+ ### セットアップ
87
+
88
+ まずログインします：
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
+ 次にMCP設定に追加します（`~/.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
+ 一度のログインで36ツールすべて利用可能。追加のenv設定は不要です。
108
+
109
+ > CLIログインなしでも、AIエージェントが `nworks_setup` → `nworks_login_user` を呼び出せばブラウザから直接認証できます。Client SecretとPrivate Keyのパスは、MCP設定の `env` フィールドまたはシステム環境変数で事前に設定してください。
110
+
111
+ ### MCPツール一覧（32個）
112
+
113
+ | ツール | 説明 | 必要な認証 |
114
+ |--------|------|-----------|
115
+ | **設定/認証** | | |
116
+ | `nworks_setup` | API認証情報の設定（Client IDなど）。Client Secretは環境変数で設定 | — |
117
+ | `nworks_login_user` | User OAuthブラウザログイン（全scope自動含む） | — |
118
+ | `nworks_logout` | 認証情報とトークンの削除 | — |
119
+ | `nworks_whoami` | 認証状態の確認 | — |
120
+ | `nworks_doctor` | 接続診断（認証、トークン、APIヘルスチェック） | — |
121
+ | **メッセージ** | | |
122
+ | `nworks_message_send` | ユーザー/チャンネルにメッセージ送信 | Service Account |
123
+ | `nworks_message_members` | チャンネルメンバー一覧 | Service Account |
124
+ | `nworks_directory_members` | 組織メンバー一覧 | Service Account |
125
+ | **カレンダー** | | |
126
+ | `nworks_calendar_list` | カレンダー予定の一覧 | User OAuth (calendar.read) |
127
+ | `nworks_calendar_create` | カレンダー予定の作成 | User OAuth (calendar + calendar.read) |
128
+ | `nworks_calendar_update` | カレンダー予定の更新 | User OAuth (calendar + calendar.read) |
129
+ | `nworks_calendar_delete` | カレンダー予定の削除 | User OAuth (calendar + calendar.read) |
130
+ | **ドライブ** | | |
131
+ | `nworks_drive_list` | ドライブのファイル/フォルダ一覧 | User OAuth (file.read) |
132
+ | `nworks_drive_upload` | ドライブにファイルアップロード | User OAuth (file) |
133
+ | `nworks_drive_download` | ドライブからファイルダウンロード（5MB超はローカル保存） | User OAuth (file.read) |
134
+ | `nworks_sharedrive_list` | 共有ドライブ一覧 | User OAuth (file.read) |
135
+ | `nworks_sharedrive_files` | 共有ドライブのファイル/フォルダ一覧 | User OAuth (file.read) |
136
+ | `nworks_sharedrive_download` | 共有ドライブのファイルをダウンロード (5MB超はローカル保存) | User OAuth (file.read) |
137
+ | **メール** | | |
138
+ | `nworks_mail_send` | メール送信 | User OAuth (mail) |
139
+ | `nworks_mail_list` | メールボックス一覧 | User OAuth (mail.read) |
140
+ | `nworks_mail_read` | メール詳細表示 | User OAuth (mail.read) |
141
+ | `nworks_mail_download_attachment` | メール添付ファイルのダウンロード (5MB超はローカル保存) | User OAuth (mail.read) |
142
+ | **タスク** | | |
143
+ | `nworks_task_list` | タスク一覧 | User OAuth (task.read) |
144
+ | `nworks_task_create` | タスク作成 | User OAuth (task + user.read) |
145
+ | `nworks_task_update` | タスク更新/完了 | User OAuth (task + user.read) |
146
+ | `nworks_task_delete` | タスク削除 | User OAuth (task + user.read) |
147
+ | **掲示板** | | |
148
+ | `nworks_board_list` | 掲示板一覧 | User OAuth (board.read) |
149
+ | `nworks_board_posts` | 掲示板の投稿一覧 | User OAuth (board.read) |
150
+ | `nworks_board_read` | 掲示板の投稿詳細 | User OAuth (board.read) |
151
+ | `nworks_board_create` | 掲示板に投稿作成 | User OAuth (board) |
152
+ | **連絡先** | | |
153
+ | `nworks_contact_list` | 連絡先一覧 | User OAuth (contact.read) |
154
+ | `nworks_contact_get` | 連絡先の詳細 | User OAuth (contact.read) |
155
+ | `nworks_contact_create` | 連絡先の作成 | User OAuth (contact) |
156
+ | `nworks_contact_update` | 連絡先の更新 | User OAuth (contact) |
157
+ | `nworks_contact_delete` | 連絡先の削除 | User OAuth (contact) |
158
+ | `nworks_contact_list_tags` | 連絡先タグ一覧 | User OAuth (contact.read) |
159
+
160
+ ### AIエージェント使用例
161
+
162
+ ```
163
+ ユーザー: 明日14時にミーティングを入れて、チームチャンネルに知らせて
164
+
165
+ Claude → nworks_calendar_create
166
+ { "summary": "ミーティング", "start": "2026-03-15T14:00:00", "end": "2026-03-15T15:00:00" }
167
+ → 予定が作成されました
168
+
169
+ Claude → nworks_message_send
170
+ { "channel": "C001", "text": "明日14:00にミーティングが設定されました" }
171
+ → メッセージが送信されました
172
+
173
+ ユーザー: 未読メールを確認して要約して
174
+
175
+ Claude → nworks_mail_list (unread)
176
+ → 未読メール3件
177
+ Claude → nworks_mail_read (各)
178
+ → "3件: 1) CTOからのデプロイ承認, 2) 金曜日のミーティング招待, 3) 週次レポートリマインダー"
179
+ ```
180
+
181
+ ---
182
+
183
+ ## CLIの使い方
184
+
185
+ > すべてのコマンドで `--json` に対応（パイプ、スクリプト、エージェント解析に便利）。`message send`、`mail send`、`drive upload` は `--dry-run` で実際の送信なしにテスト可能。
186
+
187
+ ### メッセージ（Bot API）
188
+
189
+ ```bash
190
+ # ユーザーにテキストメッセージ
191
+ nworks message send --to <userId> --text "メッセージ"
192
+
193
+ # チャンネルにテキストメッセージ
194
+ nworks message send --channel <channelId> --text "お知らせ"
195
+
196
+ # ボタンメッセージ
197
+ nworks message send --to <userId> --type button --text "PRレビュー依頼" \
198
+ --actions '[{"type":"message","label":"承認","postback":"approve"}]'
199
+
200
+ # リストメッセージ
201
+ nworks message send --to <userId> --type list --text "今日のタスク" \
202
+ --elements '[{"title":"コードレビュー","subtitle":"PR #382"}]'
203
+
204
+ # チャンネルメンバー一覧
205
+ nworks message members --channel <channelId>
206
+ ```
207
+
208
+ ### 組織（Directory API）
209
+
210
+ ```bash
211
+ nworks directory members # 組織メンバー一覧
212
+ ```
213
+
214
+ ### カレンダー（User OAuth）
215
+
216
+ ```bash
217
+ # 今日の予定一覧
218
+ nworks calendar list
219
+
220
+ # 期間指定
221
+ nworks calendar list --from "2026-03-14T00:00:00+09:00" --until "2026-03-14T23:59:59+09:00"
222
+
223
+ # 予定の作成
224
+ nworks calendar create --title "ミーティング" --start "2026-03-14T14:00+09:00" --end "2026-03-14T15:00+09:00"
225
+
226
+ # 場所/説明付き
227
+ nworks calendar create --title "ランチ" --start "2026-03-14T12:00+09:00" --end "2026-03-14T13:00+09:00" \
228
+ --location "会議室" --description "四半期レビュー"
229
+
230
+ # 参加者指定 + 通知
231
+ nworks calendar create --title "チームミーティング" --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
+ # 予定の更新
235
+ nworks calendar update --id <eventId> --title "変更後のタイトル"
236
+
237
+ # 予定の削除
238
+ nworks calendar delete --id <eventId>
239
+ ```
240
+
241
+ ### ドライブ（User OAuth）
242
+
243
+ ```bash
244
+ # ファイル/フォルダ一覧
245
+ nworks drive list
246
+
247
+ # ファイルアップロード
248
+ nworks drive upload --file ./report.pdf
249
+
250
+ # 特定フォルダにアップロード
251
+ nworks drive upload --file ./report.pdf --folder <folderId>
252
+
253
+ # ファイルダウンロード
254
+ nworks drive download --file-id <fileId>
255
+
256
+ # 出力先/ファイル名指定
257
+ nworks drive download --file-id <fileId> --out ./downloads --name report.pdf
258
+
259
+ # 共有ドライブ一覧
260
+ nworks drive sharedrive-list
261
+
262
+ # 共有ドライブのファイル一覧 (ルート)
263
+ nworks drive sharedrive-files --sharedrive <sharedriveId>
264
+
265
+ # 共有ドライブのフォルダ内ファイル一覧
266
+ nworks drive sharedrive-files --sharedrive <sharedriveId> --folder <fileId>
267
+
268
+ # 共有ドライブのファイルをダウンロード
269
+ nworks drive sharedrive-download --sharedrive <sharedriveId> --file-id <fileId>
270
+ ```
271
+
272
+ ### メール（User OAuth）
273
+
274
+ ```bash
275
+ # メール送信
276
+ nworks mail send --to "user@example.com" --subject "件名" --body "本文"
277
+
278
+ # CC/BCC付き
279
+ nworks mail send --to "user@example.com" --cc "cc@example.com" --subject "件名" --body "本文"
280
+
281
+ # 受信トレイ一覧
282
+ nworks mail list
283
+
284
+ # 未読のみ
285
+ nworks mail list --unread
286
+
287
+ # メール詳細表示
288
+ nworks mail read --id <mailId>
289
+
290
+ # メール添付ファイルのダウンロード
291
+ nworks mail download-attachment --id <mailId> --attachment-id <attachmentId>
292
+
293
+ # 保存先/ファイル名を指定
294
+ nworks mail download-attachment --id <mailId> --attachment-id <attachmentId> --out ./downloads --name invoice.pdf
295
+ ```
296
+
297
+ ### タスク（User OAuth）
298
+
299
+ ```bash
300
+ # タスク一覧
301
+ nworks task list
302
+
303
+ # 未完了のみ
304
+ nworks task list --status TODO
305
+
306
+ # タスク作成
307
+ nworks task create --title "コードレビュー" --body "PR #382 レビュー"
308
+
309
+ # 期限付き
310
+ nworks task create --title "デプロイ" --due 2026-03-20
311
+
312
+ # 完了にする
313
+ nworks task update --id <taskId> --status done
314
+
315
+ # タスク削除
316
+ nworks task delete --id <taskId>
317
+ ```
318
+
319
+ ### 掲示板（User OAuth）
320
+
321
+ ```bash
322
+ # 掲示板一覧
323
+ nworks board list
324
+
325
+ # 投稿一覧
326
+ nworks board posts --board <boardId>
327
+
328
+ # 投稿詳細
329
+ nworks board read --board <boardId> --post <postId>
330
+
331
+ # 投稿作成
332
+ nworks board create --board <boardId> --title "お知らせ" --body "内容"
333
+
334
+ # 通知付き + コメント無効化
335
+ nworks board create --board <boardId> --title "通知" --body "内容" --notify --no-comment
336
+ ```
337
+
338
+ ### 連絡先 (User OAuth)
339
+
340
+ ```bash
341
+ # 連絡先一覧
342
+ nworks contact list
343
+
344
+ # タグで絞り込み
345
+ nworks contact list --tag <contactTagId>
346
+
347
+ # 連絡先の詳細
348
+ nworks contact get --id <contactId>
349
+
350
+ # 連絡先の作成
351
+ nworks contact create --payload '{"contactName":{"lastName":"金","firstName":"哲秀"},"emails":[{"email":"chulsoo@example.com","primary":true}],"permission":{"accessibleRange":"MEMBER","isCoEditing":false,"accessibleMembers":[{"id":"<自分のuserId>","type":"USER"}]}}'
352
+
353
+ # 連絡先の更新
354
+ nworks contact update --id <contactId> --payload '{"telephones":[{"type":"CELLPHONE","telephone":"010-1234-5678","primary":true}]}'
355
+
356
+ # 連絡先の削除
357
+ nworks contact delete --id <contactId>
358
+
359
+ # 連絡先タグ一覧
360
+ nworks contact list-tags
361
+ ```
362
+
363
+ > `contact create` は `contactName` と `permission` が必須で、`permission.accessibleMembers` に最低1名(通常は自分)が必要です。自分のuserIdは `nworks whoami` で確認できます。
364
+
365
+
366
+ ### CI/CDデプロイ通知
367
+
368
+ ```bash
369
+ # GitHub Actionsでデプロイ完了後、チームチャンネルに通知
370
+ nworks message send --channel $CHANNEL_ID --text "v${VERSION} デプロイ完了"
371
+ ```
372
+
373
+ ### チーム自動化スクリプト
374
+
375
+ ```bash
376
+ # 毎朝チームメンバーにリマインダー送信
377
+ for userId in $(nworks directory members --json | jq -r '.users[].userId'); do
378
+ nworks message send --to "$userId" --text "本日のスタンドアップは10時です"
379
+ done
380
+ ```
381
+
382
+ ---
383
+
384
+ ## OAuth Scope設定
385
+
386
+ [LINE WORKS Developer Console](https://dev.worksmobile.com/jp/)でアプリのOAuth Scopeを追加してください。
387
+
388
+ | Scope | 用途 | 認証方式 | 必要なコマンド |
389
+ |-------|------|---------|---------------|
390
+ | `bot` | Botメッセージ送信 | Service Account | `message send` |
391
+ | `bot.read` | Botチャンネル/メンバー取得 | Service Account | `message members` |
392
+ | `calendar` | カレンダー書き込み | User OAuth | `calendar create/update/delete`（calendar.readも必要） |
393
+ | `calendar.read` | カレンダー読み取り | User OAuth | `calendar list`、カレンダー書き込みの依存関係 |
394
+ | `file` | ドライブ読み書き | User OAuth | `drive list/upload/download` |
395
+ | `file.read` | ドライブ読み取り専用 | User OAuth | `drive list/download` |
396
+ | `mail` | メール読み書き | User OAuth | `mail send/list/read` |
397
+ | `mail.read` | メール読み取り専用 | User OAuth | `mail list/read` |
398
+ | `task` | タスク読み書き | User OAuth | `task create/update/delete`（user.readも必要） |
399
+ | `task.read` | タスク読み取り専用 | User OAuth | `task list` |
400
+ | `user.read` | ユーザー情報取得 | Service Account / User OAuth | `directory members`、タスク書き込みの依存関係 |
401
+ | `board` | 掲示板読み書き | User OAuth | `board list/posts/read/create` |
402
+ | `board.read` | 掲示板読み取り専用 | User OAuth | `board list/posts/read` |
403
+ | `contact` | 連絡先の読み書き | User OAuth | `contact create/update/delete` (contact.read が必要) |
404
+ | `contact.read` | 連絡先の読み取り専用 | User OAuth | `contact list/get/list-tags` |
405
+
406
+ > **プリセット**を使うとscopeを個別に列挙するより簡単です:
407
+ > ```bash
408
+ > nworks login --user --preset all # デフォルト: 一度のログインで全機能
409
+ > nworks login --user --preset readonly # 読み取り専用scope
410
+ > ```
411
+ > `default`は`all`のエイリアスです。メッセージ送信はService Account（ボット）を使うため、プリセットに関係なく動作します。
412
+ > 再ログインしても権限は狭まりません — 新たに要求したscopeが既存トークンとマージされるため、プリセットの切り替えは権限を追加するだけです。個別に選ぶ場合は`--scope "calendar calendar.read"`を指定してください。
413
+
414
+ ---
415
+
416
+ ## 環境変数
417
+
418
+ 環境変数で認証情報を設定すると、`nworks login` なしで利用できます（CI/エージェント向け）。
419
+
420
+ ```bash
421
+ # 必須
422
+ NWORKS_CLIENT_ID=
423
+ NWORKS_CLIENT_SECRET=
424
+
425
+ # ボットメッセージ送信時のみ必要（User OAuthのみなら不要）
426
+ NWORKS_SERVICE_ACCOUNT=
427
+ NWORKS_PRIVATE_KEY_PATH=
428
+ NWORKS_BOT_ID=
429
+
430
+ # オプション
431
+ NWORKS_DOMAIN_ID=
432
+ NWORKS_SCOPE= # デフォルト: bot bot.read user.read
433
+ NWORKS_VERBOSE=1 # デバッグログ
434
+ ```
435
+
436
+ ### MCPサーバーに環境変数を直接設定
437
+
438
+ 機密情報（Client Secret、Private Keyパス）はMCP設定の `env` フィールドで設定します。Client IDなどの非機密情報は、AIエージェントが `nworks_setup` ツールで直接設定できます。
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ファイルの絶対パス（Service Account使用時）>"
449
+ }
450
+ }
451
+ }
452
+ }
453
+ ```
454
+
455
+ ---
456
+
457
+ ## License
458
+
459
+ Apache-2.0