# utol-mcp

東京大学の学習管理システム **UTOL (UTokyo LMS)** を、MCP クライアント（Claude Desktop など）から
扱えるようにする個人用の **MCP サーバー**です。受講登録済みの講義・締切・お知らせ・教材・課題などを
自然言語で参照できます。

ローカル実行を前提とし、機能は読み取りが中心です。認証はユーザー本人が公式の UTokyo Account
ログイン画面で行い、ツールはパスワードや MFA コードを扱いません。

## できること

- 受講登録済みの講義（時間割）・お知らせ・教材リンクの一覧
- 全科目を横断した課題・テストの締切一覧、課題詳細の参照
- シラバス（UTAS）の参照、受講登録外コースの検索（公開カタログ情報のみ）
- 教材ファイルの個別ダウンロード
- 課題の「提出不要」切替、コースの受講登録・解除（確認付きの書き込み操作）

## セットアップ

### 1. インストールとログイン

> **配布状態について**
> 本パッケージは調査時点で npm に未公開です。以下の `npx -y utol-mcp ...` は npm 公開を想定した手順であり、
> 公開までは後述の「開発」節のローカルビルド手順（`node dist/index.js ...`）を利用してください。
> なお npm 公開時は、AGPL-3.0 依存（`mupdf`）に関する後述の注意（[ライセンス](#ライセンス)）を満たす必要があります。

npx で実行する場合は次のとおりです。

```bash
npx -y utol-mcp login
```

ブラウザが開くので、UTokyo Account でログインしてください。ログインが確認されると、以降の実行で
再認証が不要になります（セッションは `~/.utol-mcp/` に保存されます）。

> **状態確認・ログアウト**
> ```bash
> npx -y utol-mcp auth-status   # ログイン済みか確認
> npx -y utol-mcp logout        # セッションとキャッシュを削除
> ```

### 2. MCP クライアントに登録

Claude Desktop などの設定ファイルに次を追加します。

```json
{
  "mcpServers": {
    "utol": { "command": "npx", "args": ["-y", "utol-mcp", "serve"] }
  }
}
```

登録後、クライアントから「今週の課題の締切は？」「〇〇の講義のお知らせを見せて」のように
自然言語で問い合わせできます。

## 提供ツール

読み取り中心のツールです。

| ツール | 説明 | 主な引数 |
|---|---|---|
| `auth_status` | ログイン状態の確認 | — |
| `list_courses` | 受講登録している講義（時間割）一覧 | `refresh?` |
| `get_course` | 講義詳細（お知らせ・教材・課題） | `idnumber` |
| `list_assignments` | 全科目横断の課題・テスト一覧と締切 | `refresh?` |
| `get_assignment` | 課題詳細（読み取りのみ） | `idnumber`, `url` |
| `get_syllabus` | シラバス（UTAS 参照） | `idnumber`, `syllabusUrl?` |
| `search_courses` | コース検索（受講登録外可・公開カタログ情報のみ） | `keyword?`, `teacher?`, `year?` |
| `get_material` | 教材内容を読む（LLM コンテキストへ取り込む） | `idnumber`, `resourceId`, `mode?` |
| `download_material` | 教材ファイルをローカルへダウンロード | `idnumber`, `resourceId`, `destPath?` |
| `list_messages` | メッセージ一覧（メタのみ・本文なし） | `refresh?` |
| `refresh_cache` | 主要一覧の再取得 | — |

- `get_course` / `get_assignment` / `get_material` / `download_material` は、受講登録中のコースのみ対象です。
- `get_material` / `download_material` の対象は `get_course` が返す `materials[].resourceId` で指定します。
- `get_material` は内容を読む用途（`mode` は `text`＝テキスト抽出／`image`＝ページ画像化）。抽出非対応形式は `download_material` を使ってください。
- `download_material` はファイルとして残す用途です。stdio 接続ではサーバーローカルのディスクへ保存（`destPath` 省略時は `~/.utol-mcp/downloads/`）、HTTP 接続では取得用の一時 URL（短TTL・単回使用）を返し、`curl` で保存します。
- 受講登録外コースは `search_courses` が返す公開カタログ情報とシラバスのみを参照できます。

### 書き込み操作

状態を変更する操作です。`confirm:true` が無い場合は実行せずプレビューのみを返し、実行時は
`~/.utol-mcp/audit.log` に記録が残ります。特に `unregister_course` は受講登録・提出物に影響します。

| ツール | 説明 | 可逆性 |
|---|---|---|
| `set_task_no_submission` | 課題を「提出不要」⇔「未提出」に切替 | 可逆 |
| `register_course` | コースを受講登録 | 解除可能 |
| `unregister_course` | 受講登録を解除 | 要注意（データ喪失の可能性） |

## ポリシー

- 個人の学習支援を目的とし、大量アクセスや教材収集には用いません。
- UTokyo SSO・MFA・CAPTCHA・アクセス制御・レート制限を回避しません。
- 認証はユーザー本人が正規ログイン画面で行い、ツールは資格情報を収集・保存・入力しません。
- 受講登録外コースは公開カタログ情報とシラバスのみを取得し、保護された内部コンテンツは取得しません。
- セッション情報は機密情報として `~/.utol-mcp/`（ディレクトリ権限 700）に保存します。Git・ログ・クラウドには含めないでください。
- 利用者は大学の規則、UTOL の利用規程、関連法令を守る必要があります。**UTOL・大学の利用規程が自動アクセス（スクレイピング）・認証セッションの保存・教材の外部サービス送信・受講登録操作の自動化を許容するかは、利用者自身が原文で確認してください。** 禁止されている場合、本ツールの利用は学内処分・契約上の責任の対象となり得ます。
- 本ツールは無保証で提供されます。利用に伴う損害や不利益について、開発者は一切の責任を負いません。利用者自身の責任で使用してください。

### 秘密情報の取り扱い（HTTP モード）

- HTTP モードの**パスフレーズ・OAuth トークン**、およびローカルの UTOL セッションは、いずれも第三者に共有・エクスポートしないでください。これらが漏えいすると、保存済みの UTOL セッションを介してあなたのアカウントでの代理アクセスが可能になります。
- UTokyo Account の共有は大学の利用規則に抵触し得ます。本ツールは単一利用者（本人）による利用を前提とし、他人にアクセスさせる第三者向けサービス提供は想定していません。

### 教材内容の外部 LLM への送信について

- `get_material` は教材内容を MCP クライアント（クラウド LLM を含み得る）のコンテキストへ取り込みます。この送信が著作権法上の私的使用（30 条）や非享受利用（30 条の 4）で正当化されるかは**不確実**です。
- 教材に複製・アップロード禁止等の個別指示がある場合や、送信先 LLM 事業者の規約・学習利用設定によっては問題が生じ得ます。**授業ごとの指示・教材の利用条件・送信先の保存/学習利用設定を確認**し、送信は必要最小限にとどめてください。機微な教材については、ローカルモデルまたは学内で承認されたサービスの利用を優先してください。

詳細は [`docs/AUTHENTICATION_POLICY.md`](docs/AUTHENTICATION_POLICY.md) を参照してください。

## 認証の仕組み

UTOL のアプリセッションはブラウザ終了時に失われますが、`utol-mcp login` で確立した UTokyo Account
（Microsoft SSO）の永続セッションが端末に残るため、以降のツール実行時は資格情報・MFA なしの
リダイレクトのみでセッションが再確立されます。再認証の途中で資格情報・MFA・アカウント選択が
要求された場合は直ちに中止し、手動ログインを促します。詳細は
[`docs/AUTHENTICATION_POLICY.md`](docs/AUTHENTICATION_POLICY.md) を参照してください。

## 開発

TypeScript 製です。`npm install` 時の `prepare` スクリプトで `dist/` へ自動ビルドされるため、
npx でも動作します。ローカルで開発する場合は次のとおりです。

```bash
npm install        # 依存 + Chromium 取得 + 自動ビルド
npm run build      # 変更を反映する際に再ビルド
npm test           # パーサ・日時正規化の単体テスト
npm run typecheck

node dist/index.js login   # ローカルビルドでの実行例
```

MCP クライアントにローカルビルドを登録する場合は、`serve` を次のように指定します。

```json
{ "command": "node", "args": ["/absolute/path/to/utol-mcp/dist/index.js", "serve"] }
```

実 UTOL に対する主要フロー（ログイン・認証再確立・時間割/課題/講義/シラバス/検索/教材DL）は
実機で検証済みです。`test/fixtures/raw/`（`.gitignore` 済み）に実 HTML を保存してパーサの
セレクタを確定しています。UTOL 側の画面改修時は、同ディレクトリの HTML を更新して
パーサを再確認してください。

## ライセンス

本プロジェクトの自作ソースコードは **MIT** です。

ただし、依存パッケージのうち **`mupdf`（MuPDF, Artifex Software）は AGPL-3.0-or-later** です。本プロジェクトは PDF 処理のため `mupdf` を直接 import しているため、`mupdf` と結合した状態で配布・ネットワーク提供する場合、結合著作物全体に AGPL の条件（ソース提供義務、ネットワーク利用条項＝AGPL 第 13 条を含む）が及ぶと評価される可能性があります。MIT の許諾は自作コードにのみ及び、AGPL 依存の義務を打ち消すものではありません。

- **npm 等への実行可能パッケージの配布**、または **第三者へのネットワーク提供**を行う場合は、結合著作物としての AGPL 適合（通知・対応ソースの提供・第 13 条への対応）を個別に確認するか、`mupdf` を互換ライセンスのライブラリ（例: pdfjs-dist, Apache-2.0）へ置換するか、Artifex から別途商用ライセンスを取得してください。
- AGPL の条件は、個人利用・非商用利用であっても免除されません。

詳細は [`LICENSE`](LICENSE) の「Third-party licenses」節を参照してください。