awesome-monash-tools 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jackdsjk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,297 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Awesome Monash Tools
+
+**Agent-native MCP servers for Monash University — Ed, Moodle, Gmail and OnTrack, exposed as 22 read-only tools your agent can call.**
+
+[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)
+[![CI](https://github.com/jackdsjk/awesome-monash-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jackdsjk/awesome-monash-tools/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/awesome-monash-tools.svg)](https://www.npmjs.com/package/awesome-monash-tools)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-stdio-6B4FBB)](https://modelcontextprotocol.io)
+[![Tools](https://img.shields.io/badge/tools-22-blue)](#-tool-catalogue)
+[![Agent-first](https://img.shields.io/badge/built%20for-agents-0A66C2)](#-built-for-agents-not-for-humans)
+
+**English** · [中文](README.zh-CN.md)
+
+</div>
+
+> Monash students work across four systems that never talk to each other: **Ed** for discussion, **Moodle** for deadlines and materials, **Gmail** for official mail, **OnTrack** for FIT task feedback. None of them offers a student-facing API. This repository turns all four into small, typed, read-only MCP tools so an agent can answer *"what is due, what did my tutor say, and what did I miss?"* with real data instead of guesses.
+
+> **Unofficial.** Not affiliated with Monash University, Ed, Moodle, Google or Doubtfire. Use your own account, at your own risk, and respect each service's terms.
+
+---
+
+## 🤖 Built for agents, not for humans
+
+This repository ships **no app, no dashboard and no chat UI**. The only interface is a set of MCP tools. Every design choice targets the model on the other side of the protocol:
+
+| Decision | Why it exists |
+|---|---|
+| **Tools, not pages** | An agent cannot "browse" Moodle. It can call `moodle_deadlines` and get JSON. |
+| **Descriptions written for models** | Each tool states when to use it, what it returns, and what the next step is. |
+| **Errors are instructions** | A dead session returns *"Moodle rejected the saved session. Run `awesome-monash login moodle`"* — not a stack trace. |
+| **Deterministic output** | Stable field names, ISO timestamps, nearest-first sorting. Nothing the model has to re-derive. |
+| **Read-only by construction** | No write path exists in the codebase. Every tool is annotated `readOnlyHint`. |
+| **One credential, many calls** | Login is a CLI step; the agent never sees or asks for a password. |
+| **Local stdio only** | No server, no telemetry, no account to create. The host spawns a process. |
+
+Works with any MCP host: **Claude Code**, **Claude Desktop**, **Cursor**, **Codex**, **DeepSeek Harness**, or your own agent loop.
+
+## 📋 Table of Contents
+
+- [Why this exists](#-why-this-exists)
+- [What's inside](#-whats-inside)
+- [What agents can do](#-what-agents-can-do)
+- [Quick start](#-quick-start)
+- [MCP configuration](#-mcp-configuration)
+- [Tool catalogue](#-tool-catalogue)
+- [Design principles](#-design-principles)
+- [Security and privacy](#-security-and-privacy)
+- [Repository layout](#-repository-layout)
+- [Development](#-development)
+- [Contributing](#-contributing)
+- [Related projects](#-related-projects)
+- [License](#-license)
+
+---
+
+## 💡 Why this exists
+
+Ask a Monash student a simple question — *"what's due this week?"* — and the real answer requires four logins, four UIs and a mental join. The information exists, but it is optimized for humans clicking around, not for an agent answering.
+
+Existing tools stop halfway:
+
+- `moodle-cli`, `edstem-cli` and `ontrack-cli` are excellent **terminal** tools. They print tables for a person and assume a person runs them.
+- Scraping libraries return HTML. A model then burns context re-reading a Moodle theme.
+- Each service authenticates differently (API token, SSO cookie, OAuth, refresh cookie). Doing that per question is impossible.
+
+This project does the boring part once — **authentication, normalization, and error recovery** — and exposes the result as 22 MCP tools with consistent shapes. The agent does the thinking; the repository does the plumbing.
+
+**What this is not:** not a Monash client, not a notification app, not a scraper you point at arbitrary URLs, and not a way to automate submissions. There is deliberately no write access.
+
+## 📦 What's inside
+
+| Component | What you get |
+|---|---|
+| **4 MCP servers** | `ed`, `moodle`, `gmail`, `ontrack` — each independently runnable |
+| **1 combined server** | `all` — all 22 tools in one process |
+| **1 CLI** | `awesome-monash login / logout / status / serve` |
+| **22 tools** | typed inputs, JSON output, actionable errors |
+| **Docs** | [Auth guide](docs/auth.md) · [Tool reference](docs/tools.md) · [llms.txt](llms.txt) |
+
+| Server | Bin | Tools | Auth captured by `awesome-monash login` |
+|---|---|---:|---|
+| Ed | `awesome-monash-ed` | 7 | API token from <https://edstem.org/settings/api-tokens> |
+| Moodle | `awesome-monash-moodle` | 5 | Monash SSO cookie jar (Chrome, one login) |
+| Gmail | `awesome-monash-gmail` | 5 | Google OAuth, `gmail.readonly` only |
+| OnTrack | `awesome-monash-ontrack` | 5 | Monash SSO refresh cookie |
+| All | `awesome-monash-all` | 22 | whichever sources you connected |
+
+## 🎯 What agents can do
+
+Real questions, and the tools that answer them:
+
+| Ask your agent | Tools it calls |
+|---|---|
+| "What is due in the next 14 days, and which ones have I already submitted?" | `moodle_deadlines` with `checkSubmitted: true` |
+| "Summarize this week's Ed threads in FIT1045; skip anything already answered." | `ed_list_threads` → `ed_get_thread` |
+| "Did my tutor leave feedback on P1? Quote the part about the data model." | `ontrack_list_projects` → `ontrack_list_tasks` → `ontrack_task_comments` |
+| "Find the enrolment email from Monash and tell me the payment deadline." | `gmail_search_messages` → `gmail_get_message` |
+| "What's in week 8 of FIT1047, and is there a lab sheet?" | `moodle_list_courses` → `moodle_course_content` |
+| "Build my week: deadlines first, then unread Ed threads, then tutor feedback." | all four servers |
+
+Because everything is scoped to **your own account**, the answers are yours: your submissions, your feedback, your inbox. Nothing is shared or cached remotely.
+
+## 🚀 Quick start
+
+Requires **Node.js 20.11+** and **Google Chrome** (only for the two SSO logins).
+
+```bash
+# Nothing to install: npx pulls the published package.
+npx -y awesome-monash-tools@latest login ed
+npx -y awesome-monash-tools@latest login moodle
+npx -y awesome-monash-tools@latest login ontrack
+npx -y awesome-monash-tools@latest login gmail --client-id <id> --client-secret <secret>
+
+npx -y awesome-monash-tools@latest status
+npx -y awesome-monash-tools@latest serve all
+```
+
+Prefer a short command? Install it once and drop the `npx ...` prefix:
+
+```bash
+npm install -g awesome-monash-tools
+
+awesome-monash login ed
+awesome-monash status
+awesome-monash serve all
+```
+
+`login moodle` and `login ontrack` open a Chrome window: finish the normal Monash SSO login, wait for the dashboard, and the session is saved automatically. Nothing is typed into this tool.
+
+> Working on the code instead? `git clone` the repo, then `npm install && npm run build && npm link`.
+
+## 🔌 MCP configuration
+
+**Claude Code**
+
+```bash
+claude mcp add monash -- npx -y awesome-monash-tools@latest serve all
+```
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "monash": {
+      "command": "npx",
+      "args": ["-y", "awesome-monash-tools@latest", "serve", "all"]
+    }
+  }
+}
+```
+
+Prefer one server per source (smaller tool list, clearer permissions):
+
+```json
+{
+  "mcpServers": {
+    "ed":       { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "ed"] },
+    "moodle":   { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "moodle"] },
+    "gmail":    { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "gmail"] },
+    "ontrack":  { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "ontrack"] }
+  }
+}
+```
+
+**Cursor** uses the same JSON in `.cursor/mcp.json`.
+
+**Codex** (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.monash]
+command = "npx"
+args = ["-y", "awesome-monash-tools@latest", "serve", "all"]
+```
+
+## 🧰 Tool catalogue
+
+Full parameters and return shapes: [docs/tools.md](docs/tools.md).
+
+### Ed — discussion threads and lessons
+
+| Tool | Description |
+|---|---|
+| `ed_whoami` | Account and courses behind the token |
+| `ed_list_courses` | Course ids and codes |
+| `ed_list_threads` | Threads of one course, newest/top/unanswered |
+| `ed_search_threads` | Search titles and bodies across courses |
+| `ed_get_thread` | Full thread with nested replies and staff answers |
+| `ed_list_lessons` | Weekly lesson modules |
+| `ed_get_lesson` | Every slide as text/Markdown, files and video URLs |
+
+### Moodle — deadlines and materials
+
+| Tool | Description |
+|---|---|
+| `moodle_whoami` | Session health check |
+| `moodle_list_courses` | Enrolled courses |
+| `moodle_deadlines` | Due dates nearest first, optional submission check |
+| `moodle_course_content` | Sections, activities, label text, file links |
+| `moodle_submission_status` | submitted / graded / none for one activity |
+
+### Gmail — the official inbox
+
+| Tool | Description |
+|---|---|
+| `gmail_profile` | Address and counts |
+| `gmail_list_labels` | Labels and ids |
+| `gmail_search_messages` | Gmail query syntax, metadata results |
+| `gmail_get_message` | Plain-text body, recipients, attachments |
+| `gmail_get_thread` | Every message in a thread |
+
+### OnTrack — FIT task feedback
+
+| Tool | Description |
+|---|---|
+| `ontrack_whoami` | Account behind the refresh cookie |
+| `ontrack_list_projects` | Units and project ids |
+| `ontrack_list_tasks` | Status, weighting, due dates |
+| `ontrack_task_comments` | Tutor comments and grade rationale |
+| `ontrack_download` | Save a task sheet or submission PDF locally |
+
+## 🧱 Design principles
+
+1. **Normalize at the edge.** Moodle is scraped internally and returned as structured sections — the model never sees HTML.
+2. **One job per tool.** `moodle_deadlines` does deadlines; `moodle_submission_status` checks one submission. No mega-tools.
+3. **Verb + noun names, prefixed by source.** `ed_get_thread` is unambiguous in a 22-tool list.
+4. **Fail with the fix.** Every `AmtError` carries a `hint`; the tool result includes the exact command to run.
+5. **Read-only by construction.** No write code path exists. `ontrack_download` writes a local file and is the only non-read-only annotation.
+6. **Stable shapes.** Field names, ISO timestamps, deterministic ordering — agents can rely on them between calls.
+7. **Local and quiet.** stdio transport, no server component, no analytics, no remote cache.
+
+## 🔒 Security and privacy
+
+- Credentials live in `~/.config/awesome-monash-tools/credentials.json`, mode `0600`; `AMT_CONFIG_DIR` relocates them.
+- No password is ever entered into this tool. Moodle and OnTrack logins happen in a real Chrome window.
+- Gmail requests only `gmail.readonly`; revoke at <https://myaccount.google.com/permissions>.
+- No telemetry, no remote logging, no third-party service in the middle.
+- Output is sensitive by definition (grades, feedback, email). Treat transcripts accordingly.
+- Environment overrides exist for advanced users: `ED_API_TOKEN`, `MOODLE_COOKIE`, `ONTRACK_REFRESH_TOKEN`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`.
+
+## 🗂 Repository layout
+
+```
+src/core/       config, credential store, HTTP retries, MCP helpers
+src/ed/         Ed client, tools, server bin
+src/moodle/     Moodle client (AJAX + scraping), tools, server bin
+src/gmail/      Gmail client + OAuth loopback, tools, server bin
+src/ontrack/    OnTrack client (refresh-cookie auth), tools, server bin
+src/all.ts      combined server
+src/cli.ts      login / logout / status / serve
+docs/           auth guide and tool reference (EN + 中文)
+scripts/        protocol-level smoke test
+```
+
+## 🛠 Development
+
+```bash
+npm install
+npm run check     # tsc --noEmit + vitest
+npm run build     # emit dist/
+npm run smoke     # start every server over stdio and call one tool
+npm run dev -- status
+```
+
+The test suite uses a fake `fetch`; no real account is required to develop. See [AGENTS.md](AGENTS.md) for conventions.
+
+## 🤝 Contributing
+
+- **New tools:** keep them read-only, add a zod schema, annotate with `readOnlyHint`, and make the error hint actionable.
+- **New sources:** follow `src/ed/` (client → tools → server) and add a credential section in [docs/auth.md](docs/auth.md).
+- **Docs:** update both `README.md` and `README.zh-CN.md`, and both language versions of `docs/`.
+- Run `npm run check && npm run smoke` before opening a PR.
+
+## 🌏 Related projects
+
+Other community work in the Monash × agents space. Some of it taught this project how the APIs behave; none of it is bundled here.
+
+| Project | What it does | License |
+|---|---|---|
+| [bunizao/edstem-cli](https://github.com/bunizao/edstem-cli) | Ed CLI + MCP server, the closest prior art | MIT |
+| [bunizao/moodle-cli](https://github.com/bunizao/moodle-cli) | Moodle CLI covering deadlines, grades and forums | MIT |
+| [bunizao/ontrack-cli](https://github.com/bunizao/ontrack-cli) | OnTrack tasks and submissions from the terminal | MIT |
+| [MarkChu-git/Always-Ontrack](https://github.com/MarkChu-git/Always-Ontrack) | OnTrack watcher with real-time feedback | Apache-2.0 |
+| [TuuHub/unicorn](https://github.com/TuuHub/unicorn) | Self-hosted campus memory layer (Cove) | Apache-2.0 |
+
+Built something else for Monash students? Open a PR and add it to the table.
+
+## 📄 License
+
+[MIT](LICENSE) © 2026 jackdsjk
+
+---
+
+*Built for agents that need to know what is due.*

package/README.zh-CN.md

@@ -0,0 +1,297 @@
+<div align="center">
+
+# Awesome Monash Tools
+
+**为 Monash 学生做的 Agent 原生 MCP 工具集：把 Ed、Moodle、Gmail、OnTrack 变成 22 个只读工具，交给你的 Agent 调用。**
+
+[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)
+[![CI](https://github.com/jackdsjk/awesome-monash-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/jackdsjk/awesome-monash-tools/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/awesome-monash-tools.svg)](https://www.npmjs.com/package/awesome-monash-tools)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-stdio-6B4FBB)](https://modelcontextprotocol.io)
+[![Tools](https://img.shields.io/badge/tools-22-blue)](#-工具目录)
+[![Agent-first](https://img.shields.io/badge/built%20for-agents-0A66C2)](#-这是给-agent-用的不是给人用的)
+
+[English](README.md) · **中文**
+
+</div>
+
+> Monash 学生的日常横跨四个互不相通的系统：**Ed** 讨论区、**Moodle** 截止日期与课件、**Gmail** 官方邮件、**OnTrack** FIT 任务反馈。这四个系统都没有面向学生的 API。本仓库把它们统一成一组小而明确的只读 MCP 工具，让 Agent 能基于真实数据回答「这周要交什么、tutor 说了什么、我漏了什么」。
+
+> **非官方项目。** 与 Monash University、Ed、Moodle、Google、Doubtfire 均无隶属关系。请使用自己的账号，自担风险，并遵守各服务条款。
+
+---
+
+## 🤖 这是给 Agent 用的，不是给人用的
+
+本仓库**没有 App、没有仪表盘、没有聊天界面**。唯一的接口就是一组 MCP 工具。每个设计决定都服务于协议另一端的那个模型：
+
+| 设计 | 为什么 |
+|---|---|
+| **给工具，不给页面** | Agent 没法「浏览」Moodle；它能调用 `moodle_deadlines` 拿到 JSON。 |
+| **工具描述按模型来写** | 每个工具都说明：什么时候用、返回什么、下一步做什么。 |
+| **报错即指令** | 会话过期时返回的是「Moodle 会话已失效，请运行 `awesome-monash login moodle`」，不是堆栈。 |
+| **输出确定** | 字段名稳定、时间统一 ISO、默认按时间排序，模型不需要二次推导。 |
+| **结构上只读** | 代码里不存在写入路径；每个工具都标注 `readOnlyHint`。 |
+| **一次登录，多次调用** | 登录是 CLI 的一步；Agent 永远看不到、也不需要密码。 |
+| **纯本地 stdio** | 没有服务端、没有埋点、不用注册账号；宿主拉起一个进程即可。 |
+
+兼容任何 MCP 宿主：**Claude Code**、**Claude Desktop**、**Cursor**、**Codex**、**DeepSeek Harness**，或你自己的 agent loop。
+
+## 📋 目录
+
+- [为什么做这个](#-为什么做这个)
+- [里面有什么](#-里面有什么)
+- [Agent 能做什么](#-agent-能做什么)
+- [快速开始](#-快速开始)
+- [MCP 配置](#-mcp-配置)
+- [工具目录](#-工具目录)
+- [设计原则](#-设计原则)
+- [安全与隐私](#-安全与隐私)
+- [仓库结构](#-仓库结构)
+- [开发](#-开发)
+- [参与贡献](#-参与贡献)
+- [相关项目](#-相关项目)
+- [许可证](#-许可证)
+
+---
+
+## 💡 为什么做这个
+
+问一个 Monash 学生「这周要交什么」，真实答案需要四次登录、四个界面，再在脑子里做一次 join。信息一直存在，但它优化的是「人点着看」，不是「Agent 直接回答」。
+
+现有工具只解决了一半：
+
+- `moodle-cli`、`edstem-cli`、`ontrack-cli` 都是优秀的**终端**工具，但它们默认使用者是人：输出表格、命令行交互、一次一问。
+- 网页抓取库返回的是 HTML，模型得花大量上下文重新理解 Moodle 的主题结构。
+- 四个系统的认证方式完全不同：API token、SSO cookie、OAuth、refresh cookie。每问一个问题都重新认证一次，不可行。
+
+这个项目把最枯燥的部分一次做完——**认证、归一化、错误恢复**——然后把结果暴露成 22 个形状一致的 MCP 工具。思考交给 Agent，管道交给仓库。
+
+**它不是什么：** 不是 Monash 客户端，不是通知应用，不是可以随便指向任意 URL 的爬虫，也不是自动交作业的捷径。**这里刻意没有写权限。**
+
+## 📦 里面有什么
+
+| 组成 | 内容 |
+|---|---|
+| **4 个 MCP server** | `ed`、`moodle`、`gmail`、`ontrack`，各自独立运行 |
+| **1 个聚合 server** | `all`，22 个工具在同一个进程里 |
+| **1 个 CLI** | `awesome-monash login / logout / status / serve` |
+| **22 个工具** | 类型化入参、JSON 输出、可执行的报错 |
+| **文档** | [认证指南](docs/auth.zh-CN.md) · [工具参考](docs/tools.zh-CN.md) · [llms.txt](llms.txt) |
+
+| Server | 可执行名 | 工具数 | `awesome-monash login` 抓取的凭据 |
+|---|---|---:|---|
+| Ed | `awesome-monash-ed` | 7 | <https://edstem.org/settings/api-tokens> 生成的 API token |
+| Moodle | `awesome-monash-moodle` | 5 | Monash SSO cookie（Chrome 里登录一次） |
+| Gmail | `awesome-monash-gmail` | 5 | Google OAuth，仅 `gmail.readonly` |
+| OnTrack | `awesome-monash-ontrack` | 5 | Monash SSO refresh cookie |
+| All | `awesome-monash-all` | 22 | 你已连接的所有来源 |
+
+## 🎯 Agent 能做什么
+
+真实问题，以及回答它们要调用的工具：
+
+| 你可以这样问 Agent | 它会调用 |
+|---|---|
+| 「未来 14 天有什么要交？哪些我已经交了？」 | `moodle_deadlines`（`checkSubmitted: true`） |
+| 「总结 FIT1045 这周的 Ed 帖子，已经被回答的跳过。」 | `ed_list_threads` → `ed_get_thread` |
+| 「Tutor 对 P1 留反馈了吗？把讲数据模型的那段原话给我。」 | `ontrack_list_projects` → `ontrack_list_tasks` → `ontrack_task_comments` |
+| 「找出 Monash 发的选课邮件，告诉我缴费截止日。」 | `gmail_search_messages` → `gmail_get_message` |
+| 「FIT1047 第 8 周有什么？有 lab sheet 吗？」 | `moodle_list_courses` → `moodle_course_content` |
+| 「帮我排这周：先截止日期，再未读 Ed 帖，最后 tutor 反馈。」 | 四个 server 全用上 |
+
+因为一切都限定在**你自己的账号**内，答案也是你自己的：你的提交、你的反馈、你的收件箱。不会共享，也不会在远端缓存。
+
+## 🚀 快速开始
+
+需要 **Node.js 20.11+** 和 **Google Chrome**（只有两个 SSO 登录会用到）。
+
+```bash
+# 不用安装：npx 直接从 npm 拉取
+npx -y awesome-monash-tools@latest login ed
+npx -y awesome-monash-tools@latest login moodle
+npx -y awesome-monash-tools@latest login ontrack
+npx -y awesome-monash-tools@latest login gmail --client-id <id> --client-secret <secret>
+
+npx -y awesome-monash-tools@latest status
+npx -y awesome-monash-tools@latest serve all
+```
+
+嫌命令长？装一次，之后就能用短命令：
+
+```bash
+npm install -g awesome-monash-tools
+
+awesome-monash login ed
+awesome-monash status
+awesome-monash serve all
+```
+
+`login moodle` / `login ontrack` 会打开 Chrome 窗口：正常完成 Monash SSO 登录、等仪表盘加载出来，会话就自动保存了。**这个工具不会让你输入密码。**
+
+> 想改代码？`git clone` 仓库后 `npm install && npm run build && npm link`。
+
+## 🔌 MCP 配置
+
+**Claude Code**
+
+```bash
+claude mcp add monash -- npx -y awesome-monash-tools@latest serve all
+```
+
+**Claude Desktop**（`~/Library/Application Support/Claude/claude_desktop_config.json`）
+
+```json
+{
+  "mcpServers": {
+    "monash": {
+      "command": "npx",
+      "args": ["-y", "awesome-monash-tools@latest", "serve", "all"]
+    }
+  }
+}
+```
+
+也可以按来源拆开（工具列表更小、权限更清晰）：
+
+```json
+{
+  "mcpServers": {
+    "ed":       { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "ed"] },
+    "moodle":   { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "moodle"] },
+    "gmail":    { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "gmail"] },
+    "ontrack":  { "command": "npx", "args": ["-y", "awesome-monash-tools@latest", "serve", "ontrack"] }
+  }
+}
+```
+
+**Cursor** 在 `.cursor/mcp.json` 用同样的 JSON。
+
+**Codex**（`~/.codex/config.toml`）：
+
+```toml
+[mcp_servers.monash]
+command = "npx"
+args = ["-y", "awesome-monash-tools@latest", "serve", "all"]
+```
+
+## 🧰 工具目录
+
+完整参数与返回结构见 [docs/tools.zh-CN.md](docs/tools.zh-CN.md)。
+
+### Ed — 讨论帖与课件
+
+| 工具 | 作用 |
+|---|---|
+| `ed_whoami` | token 背后的账号与课程 |
+| `ed_list_courses` | 课程 id 与课程代码 |
+| `ed_list_threads` | 某门课的帖子，可按最新/最热/未回答 |
+| `ed_search_threads` | 跨课程搜索标题与正文 |
+| `ed_get_thread` | 完整帖子，含嵌套回复与 staff 回答 |
+| `ed_list_lessons` | 按周的 lesson 模块 |
+| `ed_get_lesson` | 每页 slide 的文本/Markdown、附件与视频地址 |
+
+### Moodle — 截止日期与课件
+
+| 工具 | 作用 |
+|---|---|
+| `moodle_whoami` | 会话健康检查 |
+| `moodle_list_courses` | 已选课程 |
+| `moodle_deadlines` | 按到期时间排序，可选检查是否已提交 |
+| `moodle_course_content` | 章节、活动、label 文本、文件链接 |
+| `moodle_submission_status` | 单个作业的 submitted / graded / none |
+
+### Gmail — 官方邮箱
+
+| 工具 | 作用 |
+|---|---|
+| `gmail_profile` | 邮箱地址与邮件计数 |
+| `gmail_list_labels` | 标签与 id |
+| `gmail_search_messages` | Gmail 查询语法，返回元数据 |
+| `gmail_get_message` | 纯文本正文、收件人、附件列表 |
+| `gmail_get_thread` | 整个会话的所有邮件 |
+
+### OnTrack — FIT 任务反馈
+
+| 工具 | 作用 |
+|---|---|
+| `ontrack_whoami` | refresh cookie 背后的账号 |
+| `ontrack_list_projects` | 单元与项目 id |
+| `ontrack_list_tasks` | 状态、权重、截止日期 |
+| `ontrack_task_comments` | tutor 评论与评分理由 |
+| `ontrack_download` | 把任务书或提交 PDF 存到本地 |
+
+## 🧱 设计原则
+
+1. **在边缘做归一化。** Moodle 在内部被解析，对外只返回结构化章节——模型永远看不到 HTML。
+2. **一个工具只做一件事。** `moodle_deadlines` 只管截止日期，查单个提交状态用 `moodle_submission_status`。不做大杂烩。
+3. **动词 + 名词，带来源前缀。** 在 22 个工具里，`ed_get_thread` 没有歧义。
+4. **报错要给解法。** 每个 `AmtError` 都带 `hint`，工具结果里直接给出该跑的命令。
+5. **结构上只读。** 代码里没有写入路径；`ontrack_download` 只写本地文件，是唯一非只读标注。
+6. **形状稳定。** 字段名、ISO 时间、确定的排序——Agent 可以在多次调用之间依赖它们。
+7. **本地、安静。** stdio 传输，没有服务端组件、没有分析、没有远端缓存。
+
+## 🔒 安全与隐私
+
+- 凭据存放在 `~/.config/awesome-monash-tools/credentials.json`，权限 `0600`；可用 `AMT_CONFIG_DIR` 改位置。
+- 本工具从不要求输入密码。Moodle 与 OnTrack 的登录发生在真实的 Chrome 窗口里。
+- Gmail 只申请 `gmail.readonly`；可随时在 <https://myaccount.google.com/permissions> 撤销。
+- 没有埋点、没有远端日志、中间没有第三方服务。
+- 输出本身就是敏感信息（成绩、反馈、邮件），转述时请自行判断。
+- 高级用户可用环境变量覆盖：`ED_API_TOKEN`、`MOODLE_COOKIE`、`ONTRACK_REFRESH_TOKEN`、`GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`。
+
+## 🗂 仓库结构
+
+```
+src/core/      配置、凭据存储、HTTP 重试、MCP 辅助
+src/ed/        Ed 客户端、工具、server 入口
+src/moodle/    Moodle 客户端（AJAX + 抓取）、工具、入口
+src/gmail/     Gmail 客户端 + OAuth 回环、工具、入口
+src/ontrack/   OnTrack 客户端（refresh cookie）、工具、入口
+src/all.ts     聚合 server
+src/cli.ts     login / logout / status / serve
+docs/          认证指南与工具参考（中英双语）
+scripts/       协议级 smoke 测试
+```
+
+## 🛠 开发
+
+```bash
+npm install
+npm run check     # tsc --noEmit + vitest
+npm run build     # 产出 dist/
+npm run smoke     # 真的拉起每个 server 并通过 stdio 调用一个工具
+npm run dev -- status
+```
+
+测试使用假的 `fetch`，开发不需要真实账号。代码约定见 [AGENTS.md](AGENTS.md)。
+
+## 🤝 参与贡献
+
+- **加工具：** 保持只读、补 zod schema、标注 `readOnlyHint`、报错必须给下一步。
+- **加数据源：** 照 `src/ed/` 的结构（client → tools → server），并在 [docs/auth.md](docs/auth.md) 与中文版里补认证说明。
+- **改文档：** `README.md` 与 `README.zh-CN.md`、`docs/` 的中英两版要同步。
+- 提交 PR 前先跑 `npm run check && npm run smoke`。
+
+## 🌏 相关项目
+
+Monash × Agent 生态里的其他社区工作。其中一些帮本项目摸清了这些 API 的行为；没有一个被打包进这里。
+
+| 项目 | 作用 | 许可 |
+|---|---|---|
+| [bunizao/edstem-cli](https://github.com/bunizao/edstem-cli) | Ed CLI + MCP server，最接近的先行实现 | MIT |
+| [bunizao/moodle-cli](https://github.com/bunizao/moodle-cli) | Moodle CLI，覆盖截止日期、成绩、论坛 | MIT |
+| [bunizao/ontrack-cli](https://github.com/bunizao/ontrack-cli) | 终端里的 OnTrack 任务与提交 | MIT |
+| [MarkChu-git/Always-Ontrack](https://github.com/MarkChu-git/Always-Ontrack) | OnTrack 实时反馈监听 | Apache-2.0 |
+| [TuuHub/unicorn](https://github.com/TuuHub/unicorn) | 自托管的校园记忆层（Cove） | Apache-2.0 |
+
+如果你也为 Monash 学生做了东西，欢迎提 PR 加进这张表。
+
+## 📄 许可证
+
+[MIT](LICENSE) © 2026 jackdsjk
+
+---
+
+*为那些需要知道「这周要交什么」的 Agent 而建。*

package/dist/all.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/all.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { createServer, serve } from "./core/mcp.js";
+import { registerEdTools } from "./ed/tools.js";
+import { registerGmailTools } from "./gmail/tools.js";
+import { registerMoodleTools } from "./moodle/tools.js";
+import { registerOnTrackTools } from "./ontrack/tools.js";
+const server = createServer("awesome-monash-all", "One MCP server for Ed, Moodle, Gmail and OnTrack. Tool prefixes name the source (ed_, moodle_, gmail_, ontrack_); use `awesome-monash login <source>` for any that report a missing session.");
+registerEdTools(server);
+registerMoodleTools(server);
+registerGmailTools(server);
+registerOnTrackTools(server);
+await serve(server, "all");
+//# sourceMappingURL=all.js.map

package/dist/all.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"all.js","sourceRoot":"","sources":["../src/all.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,MAAM,GAAG,YAAY,CACzB,oBAAoB,EACpB,8LAA8L,CAC/L,CAAC;AAEF,eAAe,CAAC,MAAM,CAAC,CAAC;AACxB,mBAAmB,CAAC,MAAM,CAAC,CAAC;AAC5B,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAC3B,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAE7B,MAAM,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};