# lineworks-mcp

LINE WORKS の MCP サーバー（stdio トランスポート / ユーザー本人 OAuth）。
`uvx` で1コマンド起動できます。

## ツール

- `get_user_profile` — プロフィール取得
- `get_events_in_calendar` — カレンダー予定取得（繰り返し予定も展開）
- `create_event_to_calendar` — 予定作成（メモ欄・参加者の指定に対応）
- `search_users` — ユーザー（メンバー）一覧を検索（予定の参加者を探す用）
- `get_tasks` — ToDo タスク取得
- `create_task` — タスク作成
- `get_groups` — グループ一覧
- `get_group_note_posts` — グループノートの投稿一覧
- `get_group_note_post` — 投稿詳細
- `auth_status` — 認証状態の確認
- `reauthorize` — 再認証（ブラウザで再ログイン）

### 予定作成（メモ欄・参加者）

`create_event_to_calendar` は次の引数を取ります。

| 引数 | 必須 | 説明 |
|---|---|---|
| `summary` | ✅ | 予定のタイトル |
| `start_time` | ✅ | 開始時刻（ISO 8601 例: `2026-07-01T10:00:00`） |
| `end_time` | ✅ | 終了時刻（ISO 8601） |
| `description` | — | メモ欄（予定の本文・詳細）。最大 5000 文字 |
| `attendee_emails` | — | 参加者のメールアドレス一覧。`search_users` で検索して指定 |

参加者を付けた予定作成の流れ:

```text
1. search_users(keyword="田中")
   → [{userId, email, displayName}, ...] が返る

2. create_event_to_calendar(
     summary="定例MTG",
     start_time="2026-07-01T10:00:00",
     end_time="2026-07-01T11:00:00",
     description="議題：来期計画の確認",          # メモ欄
     attendee_emails=["tanaka@example.com"]      # 参加者
   )
```

`search_users` はキーワード（氏名・メール等）でメンバーを検索します。キーワードを
省略するとドメイン全メンバーを返します。続きがある場合は応答の `nextCursor` を
`cursor` 引数に渡してページングできます。

## 事前準備

1. [LINE WORKS Developer Console](https://dev.worksmobile.com/) でアプリを作成
2. **Client ID** と **Client Secret** を取得
3. **OAuth Scope** を設定（下記参照）
4. **Redirect URL** に `http://localhost:8000/redirect` を登録
   （`MCP_WORKS_REDIRECT_PORT` でポートを変えたら合わせる）

## Client ID / Client Secret の作成方法

`MCP_WORKS_CLIENT_ID` と `MCP_WORKS_CLIENT_SECRET` は、LINE WORKS の
[Developer Console](https://dev.worksmobile.com/) で「アプリ」を登録すると発行されます。

> ⚠️ Developer Console を利用するには、LINE WORKS 管理者から **Developers 権限** が
> 付与されている必要があります（LINE WORKS Admin → セキュリティ → 管理者権限）。
> 初回ログイン時は Developers 利用規約への同意が必要です。

### 手順

1. **Developer Console にログイン**
   [https://dev.worksmobile.com/](https://dev.worksmobile.com/) に LINE WORKS アカウントでログイン。

2. **アプリを新規作成**
   「API」→「アプリ」メニューから **「アプリの新規追加」** をクリックし、基本情報を入力して作成。

3. **Client ID / Client Secret を取得**
   作成したアプリの詳細画面に **Client ID** と **Client Secret** が表示されます。
   これがそれぞれ `MCP_WORKS_CLIENT_ID` / `MCP_WORKS_CLIENT_SECRET` になります。
   （Client Secret は再表示・再発行が可能です。漏洩した場合は再発行してください。）

4. **OAuth Scope を設定**
   アプリの **OAuth Scope** に、このサーバーが使う以下のスコープを追加します
   （`MCP_WORKS_SCOPE` のデフォルト値と一致させる）。

   ```text
   user.profile.read
   calendar
   task
   group.read
   group.note
   directory.read
   ```

   > 📌 `directory.read` は `search_users`（ユーザー検索）で必要です。この Scope を
   > 付与するには LINE WORKS 側で管理者の同意・権限が必要な場合があります。Console で
   > 選択肢に出ない場合は管理者に確認してください。

   > 💡 LINE WORKS では Authorization Code Flow を使うと **refresh_token が自動的に発行**
   > されます（有効期間 90 日）。`offline_access` のような追加スコープは不要です
   > （LINE WORKS には存在しません）。

5. **Redirect URL を登録**
   アプリの **Redirect URL** に、このサーバーがコールバックを受ける URL を登録します。

   ```text
   http://localhost:8000/redirect
   ```

   `MCP_WORKS_REDIRECT_PORT` でポートを変えた場合は、その番号に合わせて登録してください
   （例: ポート 9000 なら `http://localhost:9000/redirect`）。

6. **保存**
   設定を保存すると、Client ID / Client Secret / Scope / Redirect URL が確定します。

> 📌 認証方式はユーザー本人としての **OAuth 2.0 Authorization Code Flow** です。
> サーバー間で動かす Service Account (JWT) 方式とは別物なので、秘密鍵 (Private Key) の
> 発行は不要です。

## 環境変数

| 変数 | 必須 | 説明 |
|---|---|---|
| `MCP_WORKS_CLIENT_ID` | ✅ | クライアントID |
| `MCP_WORKS_CLIENT_SECRET` | ✅ | クライアントシークレット |
| `MCP_WORKS_SCOPE` | — | OAuth スコープ（デフォルト: `user.profile.read calendar task group.read group.note directory.read`） |
| `MCP_WORKS_REDIRECT_PORT` | — | 初回認可で使うローカルポート（デフォルト 8000） |

## uvx での起動

GitHub から直接:

```bash
MCP_WORKS_CLIENT_ID=xxxx MCP_WORKS_CLIENT_SECRET=[REDACTED_PASSWORD] \
  uvx --from git+https://github.com/tsukumonasu/lineworks-mcp lineworks-mcp
```

ローカルのソースから:

```bash
MCP_WORKS_CLIENT_ID=xxxx MCP_WORKS_CLIENT_SECRET=[REDACTED_PASSWORD] \
  uvx --from . lineworks-mcp
```

初回はブラウザが開き LINE WORKS のログイン画面が表示されます。認可後、
`~/.lineworks_mcp_token.json` にトークンが保存され、2回目以降は自動更新されます。

> 🔄 Scope を変更した場合（例: `directory.read` を追加した場合）は、保存済みトークンを
> 取り直す必要があります。`~/.lineworks_mcp_token.json` を削除してから再起動し、
> 再度ブラウザ認可してください。また `uvx` のビルドキャッシュをクリアすると確実です:
> `uv cache clean lineworks-mcp`

## トークン切れと再認証

このサーバーはトークンを自動管理します。基本的にユーザーが手動で再認証する必要はありません。

| トークン | 有効期限 | 切れたときの挙動 |
|---|---|---|
| Access Token | 1〜24時間 | **自動更新**（refresh_token を使用。操作不要） |
| Refresh Token | 90日 | `reauthorize` ツールでブラウザ再ログイン |

動作の流れ:

1. Access Token が有効ならそのまま使う。
2. 期限切れなら refresh_token で自動更新を試みる（ブラウザ不要）。
3. refresh も失敗（90日経過・失効など）した場合は、応答をブロックせず
   **「再認証が必要です。reauthorize ツールを実行してください。」** とエラーを返す。
   `reauthorize` を実行するとブラウザが開き、再ログインで新しいトークンが保存される。

### 再認証ツール

| ツール | 役割 |
|---|---|
| `auth_status` | 現在の認証状態を確認（`valid` / `expired` / `needs_reauth`） |
| `reauthorize` | ブラウザを自動で開いて再ログイン → トークンを取り直す |

`reauthorize` はブラウザ認可を**別スレッドで実行**するため、他のツール応答を
ブロックしません。Amazon Quick 上では、トークン失効でツールがエラーになると
エージェントが `reauthorize` を呼び、ブラウザが開いて再ログインする流れになります。

> 💡 確実にやり直したい場合は、ターミナルでトークンファイルを削除してから
> 手動起動しても構いません:
>
> ```bash
> rm ~/.lineworks_mcp_token.json
> uvx --from . lineworks-mcp        # ブラウザで再ログイン
> ```

## Amazon Quick への登録

**Settings → Capabilities → Connectors → Add MCP server → Local (stdio)**

```json
{
  "mcpServers": {
    "lineworks": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tsukumonasu/lineworks-mcp", "lineworks-mcp"],
      "env": {
        "MCP_WORKS_CLIENT_ID": "あなたのクライアントID",
        "MCP_WORKS_CLIENT_SECRET": "あなたのクライアントシークレット"
      }
    }
  }
}
```

ローカルソースを使う場合は `args` を `["--from", "/path/to/lineworks-mcp", "lineworks-mcp"]` に変更。

> 💡 初回はブラウザ認可が走るため、先に一度ターミナルで `uvx --from . lineworks-mcp` を
> 実行してログインを済ませ、トークンファイルを作っておくと、Amazon Quick からの起動が
> スムーズです。