Content
# Science Tokyo LMS MCP
This is an MCP (Model Context Protocol) server for operating the LMS (Learning Management System) of Science Tokyo. It allows you to call tools such as downloading lecture materials and checking assignment deadlines from an MCP client (e.g., Claude).
> [!NOTE]
> For those who want to introduce and start using it (for laboratory members), please refer to [`docs/USAGE.md`](docs/USAGE.md). This README mainly summarizes the policy, internal configuration, and development procedures.
> [!WARNING]
> This tool is intended for **individual academic use**. Automatic access to the university system may violate the terms of use. Please check the Science Tokyo terms and conditions before use and operate with moderation (e.g., caching, low-frequency access).
## Target and Platform
- **Target LMS:** Science Tokyo LMS (`https://lms.s.isct.ac.jp/<year>/`)
- **Platform:** **Moodle** (confirmed). The path changes every year (e.g., `/2025/`).
- **Method:** Moodle **Web Services REST API** + mobile token authentication. Official API is used for stability and speed.
## Authentication Policy (MFA Required)
Science Tokyo is protected by SAML2 SSO (`isct.ex-tic.com` / MFA required). Therefore, token issuance using a password is not possible. Instead, the same launch flow as the Moodle mobile app is used.
```bash
# Initial run only: Open a browser to complete SSO login (including MFA)
# → Obtain a mobile token and save it to keyring
uv run science-tokyo-lms-login
```
The obtained token is saved to keyring (or `.auth/wstoken` if not available, both are .gitignore'd). Subsequent Web Services API calls can be made without a browser. If the token expires, run the command again.
## Setup
```bash
uv sync # Synchronize dependencies
uv run playwright install chromium # Obtain the browser to use (chromium / firefox / webkit)
cp .env.example .env # Edit as necessary (year, browser, etc.)
```
## Configuration (`.env`)
Main configuration items (environment variables `STLMS_*`, specified in `.env`).
| Variable | Default | Description |
|---|---|---|
| `STLMS_LMS_BASE_URL` | `.../2025/` | Moodle base URL (path changes every year) |
| `STLMS_BROWSER` | `chromium` | Browser used for token acquisition (`chromium` / `firefox` / `webkit`) |
| `STLMS_TOKEN_BACKEND` | `auto` | Token storage method (`auto` / `keyring` / `file`) |
| `STLMS_WSTOKEN` | (none) | Directly specify token (highest priority) |
> If keyring (password store) is not available, specify `STLMS_TOKEN_BACKEND=file` to save the token to `.auth/wstoken` (.gitignore'd, permission 0600).
## Launch
```bash
uv run science-tokyo-lms-mcp # Start MCP server with stdio
```
Register with an MCP client (e.g., Claude Desktop / Claude Code) as follows:
```json
{
"mcpServers": {
"science-tokyo-lms": {
"command": "uv",
"args": ["run", "--directory", "/path/to/ScienceTokyoLMS-mcp", "science-tokyo-lms-mcp"]
}
}
}
```
## Provided Tools
| Tool | Description |
|---|---|
| `list_courses` | List of enrolled courses |
| `list_materials(course_id)` | List of lecture materials |
| `download_material(course_id, material_id, dest_dir?)` | Download lecture materials |
| `list_assignments(course_id?)` | List of assignments and deadlines |
| `get_upcoming_deadlines(days=7)` | Get upcoming deadlines in order |
| `list_announcements(course_id?)` | List of announcements and cancellations |
> Currently, `submitted` is always `false` due to the need for a separate API (planned to be implemented with `mod_assign_get_submission_status`).
## Main Moodle Web Services Functions
| Tool | Web Services Function |
|---|---|
| `list_courses` | `core_webservice_get_site_info` + `core_enrol_get_users_courses` |
| `list_materials` | `core_course_get_contents` |
| `list_assignments` | `mod_assign_get_assignments` |
| `list_announcements` | `mod_forum_get_forums_by_courses` + `mod_forum_get_forum_discussions` |
## Directory Structure
```
src/science_tokyo_lms_mcp/
├── server.py # FastMCP server (entry point)
├── login.py # Initial token acquisition CLI
├── config.py # Configuration (environment variables STLMS_*)
├── models.py # Data models
├── auth/
│ ├── session.py # Playwright persistent session management
│ └── token.py # Mobile token acquisition and storage (keyring)
├── client/
│ ├── base.py # LMSClient protocol
│ ├── moodle_client.py # Moodle Web Services implementation (default)
│ └── playwright_client.py # Scraping fallback
└── tools/ # MCP tools (courses / materials / deadlines / announcements)
```
## Development
```bash
uv run ruff format . # Format
uv run ruff check . # Lint
uv run ty check # Type check
uv run pytest # Test
```
## Security
- **Do not commit** authentication information, cookies, tokens, or downloaded materials (`.gitignore`d).
- Passwords are not stored in code or configuration; SSO is handled by a persistent profile, and tokens are stored in keyring.
- It is recommended to operate the repository **privately**.
