<div align="center">

# UG Sakai for Claude

**Your University of Ghana Sakai account, inside Claude.**

Ask what is due, read assignment briefs, follow announcements, revise from your lecture slides,
and get help planning and reviewing your own work, all without opening Sakai.

[![CI](https://github.com/Joeboy77/ug-sakai-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Joeboy77/ug-sakai-mcp/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)
![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
![Read-only](https://img.shields.io/badge/Sakai%20access-read--only-success)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

[Install](#install) · [What you can do](#what-you-can-do) · [Privacy](#privacy-and-safety) ·
[Troubleshooting](#troubleshooting) · [Contributing](CONTRIBUTING.md)

</div>

---

> **Not an official University of Ghana product.** This is an independent, open-source student
> project. It uses your own login to read what you can already see on
> [sakai.ug.edu.gh](https://sakai.ug.edu.gh), and nothing more.

## Why

Sakai keeps everything you need, but spread across dozens of course sites, tools and PDFs.
This project is an [MCP](https://modelcontextprotocol.io) server: it gives Claude a small set of
safe, read-only tools for your Sakai account, so you can simply ask:

> *"What's due in the next two weeks, and which of those haven't I submitted?"*
>
> *"Explain the DCIT 418 project brief in plain language and list the deliverables."*
>
> *"Show me slide 14 of the MATH 359 graphs lecture. I don't follow the diagram."*
>
> *"Help me revise for the MATH 359 exam and quiz me on my weak topics."*

## What you can do

### Stay on top of your courses

| Ask Claude… | Tool |
|---|---|
| "What's due soon?" (assignments **and** quiz/exam dates) | `get_upcoming_deadlines` |
| "Anything new on Sakai since yesterday?" | `whats_new` |
| "Which courses am I taking this semester?" | `list_my_courses` |
| "Any announcements from DCIT 302?" | `get_announcements` |
| "What's on my calendar this week?" | `get_calendar` |

### Assignments, feedback and grades

| Ask Claude… | Tool |
|---|---|
| "List the assignments in DCIT 418" | `list_assignments` |
| "Show me the full brief for assignment 2" | `get_assignment_details` |
| "Read the PDF attached to that assignment" | `download_assignment_attachment` |
| "What feedback did my lecturer give me?" | `get_assignment_feedback` |
| "What grades have been released in DCIT 302?" | `get_my_grades` |

### Lecture material

| Ask Claude… | Tool |
|---|---|
| "List the slides in MATH 359" | `list_course_resources` |
| "Summarise Lecture 3" (PDF, PowerPoint, Word, text) | `get_resource` |
| "Show me page 12 as a picture" (equations, diagrams, handwriting) | `view_slide` |
| "Does this course use Lessons?" | `list_lessons` |

### Study with built-in prompts

In Claude Desktop, click **+** and choose **UG Sakai** to start one of these:

| Prompt | What Claude does |
|---|---|
| **Break down an assignment** | Explains what is really being asked, the deliverables, criteria and deadline. |
| **Plan an assignment** | Builds a step-by-step plan with mini-deadlines, fitted around your other deadlines. |
| **Tutor me for an assignment** | Teaches the concepts from your course's own lecture files and checks your understanding. |
| **Review my draft** | Gives specific feedback on your draft against the brief, including Turnitin risks. |
| **Help me draft it myself** | Guides you part by part while **you** write. |
| **Revise for an exam** | Builds a revision plan up to the exam date, finds past papers and quizzes you one question at a time. |

### Optional: submission checker

UG Sakai does not let tools submit work, and this project never will. If you switch on the
checker, Claude can confirm a file **you** chose is ready (right type and size, assignment still
open, resubmission allowed), then gives you the link and the steps to submit it yourself.

## Install

You need [Claude Desktop](https://claude.ai/download).

### Option 1: one file (recommended, about 3 minutes)

1. Download **`ug-sakai.mcpb`** from the [latest release](https://github.com/Joeboy77/ug-sakai-mcp/releases/latest).
2. Double-click it. Claude Desktop opens an install screen.
3. Enter your **Student ID** and **Sakai password**, and switch on the submission checker if you
   want it. Click **Install**.
4. Open a new chat and ask: *"Which courses am I taking this semester?"*

The first start takes up to a minute while Claude Desktop sets things up. To change your
password later, go to **Settings → Extensions → UG Sakai**.

### Option 2: from source

<details>
<summary>Manual install with uv (about 10 minutes)</summary>

1. **Install [uv](https://docs.astral.sh/uv/)**. It also installs the right Python.

   macOS or Linux:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```
   Windows (PowerShell):
   ```powershell
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   ```

2. **Get the code**
   ```bash
   git clone https://github.com/Joeboy77/ug-sakai-mcp.git
   cd ug-sakai-mcp
   uv sync
   ```

3. **Save your Sakai login** in your system keychain. Type it in the terminal, never in a chat.
   ```bash
   uv run ug-sakai-mcp login
   uv run ug-sakai-mcp check
   ```

4. **Connect Claude Desktop**
   ```bash
   uv run ug-sakai-mcp desktop-config
   ```
   Paste the printed `ug-sakai` block into **Settings → Developer → Edit Config** under
   `mcpServers`, save, then quit Claude Desktop completely and reopen it. Add
   `--enable-submission` to switch on the submission checker.

</details>

## Privacy and safety

| | |
|---|---|
| **Read-only by design** | Every Sakai address the server may call is on a fixed allowlist of read endpoints. Anything else is refused before a request is made, including Sakai actions that change data. |
| **Your password stays with you** | Stored in your system keychain (macOS Keychain, Windows Credential Manager). It is only ever sent to `sakai.ug.edu.gh`. |
| **No lockouts** | If Sakai rejects your password, the server stops and never retries, so your account is not locked. |
| **Nothing leaves your computer** | No servers, accounts or analytics. Files Claude reads are saved to `~/SakaiMCP/downloads`. |
| **Prompt-injection guard** | Text from announcements, briefs and files is marked as untrusted, and Claude is told never to follow instructions inside it. |
| **Safe downloads** | Course files only, from Sakai only, with cleaned filenames and a 50 MB limit. |

What is stored where:

| What | Where |
|---|---|
| Your login | System keychain |
| Files Claude reads | `~/SakaiMCP/downloads/<course>/…` |
| What `whats_new` has already shown you | `~/SakaiMCP/state.json` |
| Submission checks | `~/SakaiMCP/logs/submissions.jsonl` |
| Debug log (only with `DEBUG=true`) | `~/SakaiMCP/logs/server.log` (passwords and sessions masked) |

To remove everything, uninstall the extension (or run `uv run ug-sakai-mcp forget`), then delete
the `~/SakaiMCP` folder.

## Academic integrity

You are responsible for everything you submit, and UG checks submissions with Turnitin. The
built-in prompts tell Claude to help you **understand and produce the work yourself**, to explain
so you can defend every part, and to warn you first when a brief limits or bans AI tools. The
server cannot take quizzes, read quiz questions or submit anything, and the revision prompt
refuses to answer questions from a quiz that is open right now. Always follow your lecturer's
rules.

## How it works

```mermaid
flowchart LR
    You([You]) --> Claude[Claude Desktop]
    Claude <-->|MCP over stdio| Server[UG Sakai MCP server<br/>on your computer]
    Server -->|login from keychain| Keychain[(System keychain)]
    Server -->|read-only allowlist| Sakai[(sakai.ug.edu.gh<br/>/direct REST API)]
    Server -->|text and page images| Files[(~/SakaiMCP/downloads)]
```

The server logs in to Sakai's `/direct` REST API with your session, reads only allowlisted
endpoints, turns the results into compact, structured answers with dates in Ghana time, and
extracts text and page images from lecture files. [`DISCOVERY.md`](DISCOVERY.md) records what UG
Sakai supports and why each design decision was made.

## Limitations

- **No quiz or exam scores.** UG Sakai only shares assignment grades with tools.
- **No submitting, posting or messaging.** By design.
- **Lessons pages:** page titles only for now.
- **Old `.ppt` and `.doc` files and images** cannot be read as text. `view_slide` shows PDF pages,
  and the pictures inside PowerPoint slides.
- **Scanned PDFs** have no text layer. Use `view_slide` to let Claude look at the page instead.

## Troubleshooting

| You see | Do this |
|---|---|
| "Sakai rejected the Student ID or password" | Update your login in **Settings → Extensions → UG Sakai** (or `uv run ug-sakai-mcp login`) and restart Claude Desktop. |
| "Login is paused…" | Same as above. The server pauses after one rejection to protect your account. |
| "Sakai is not responding" | Check your internet connection, or try again later. Sakai may be down. |
| "No Sakai Student ID and password are set yet" | Add them in the extension settings, or run `uv run ug-sakai-mcp login`. |
| "This computer has no usable keychain" | Copy `.env.example` to `.env` and set `SAKAI_USERNAME` and `SAKAI_PASSWORD`. Never share that file. |
| The tools don't appear in Claude | Quit Claude Desktop completely (Cmd+Q on a Mac) and reopen it. For a manual install, rerun `uv run ug-sakai-mcp desktop-config` and check the paths. |
| "matches more than one course" | You took the course in more than one year. Use the `site_id` from `list_my_courses`. |

## FAQ

**Does it work with other universities' Sakai?** It is built and tested for UG Sakai. Other Sakai
sites may work by setting `SAKAI_BASE_URL`, but their enabled endpoints differ. Run
`uv run ug-sakai-discover` first.

**Can it see other students' work or grades?** No. It uses your login, so it only sees what you
can already see on Sakai.

**Does it work with Claude Code or other MCP clients?** Yes. Any client that can start a stdio MCP
server can run `uv run ug-sakai-mcp`.

## Contributing

Contributions are welcome, from bug reports to new tools. Start with
[CONTRIBUTING.md](CONTRIBUTING.md). To report a security problem, see [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE)