Schulcloud-MCP/docs/NOTES.md

Your own lesson notes

Schulcloud holds the material and WebUntis holds the schedule. Neither holds what was actually said in the room — which teacher stressed what, the example that finally made it click, the aside that turns up in the test. That is in whatever you write down during the lesson, and until now it lived somewhere no agent could read.

This is the third source: a directory of Markdown files the server reads, indexes and searches alongside everything else, and a small web app to write them in.

One note per school day

NOTES_DIR/
  2026/
    2026-09-18.md        ← Freitag, one heading per lesson
    2026-09-21.md
  Deutsch/
    2026-09-15 Erörterung.md   ← a single-subject note, e.g. from the import

A day note looks like this, and the shape is load-bearing:

---
title: Freitag, 18.09.2026
date: 2026-09-18
source: notes-page
---

## 1. Deutsch — 08:00–08:45 · MEI · R 204

Dreischritt: These, Argument mit Beleg, Fazit.

### Aufbau

- Gegenargument nicht vergessen — kam letztes Jahr in der Arbeit dran

## 2. LF07 — 08:50–09:35 · Sb · R 108

| Präfix | Nutzbare Adressen |
|---|---|
| /24 | 254 |

Each ## is indexed as its own lesson. A search for Gegenargument answers "my own note, Deutsch, 18.09.2026", not "my own note, Friday"; list_notes subject=Deutsch finds this day even though the note's frontmatter names no subject; and what_changed reports the lesson that changed rather than the whole day. Prose, lists, tables and ### subheadings all live inside their lesson.

Nothing forces the shape. A note with no ## headings — an imported Apple Note, a page of revision — is indexed whole, as one piece of prose.

The app

/app is a small web app: a login, the day's notes, and a settings page. It is served only when WEB_PASSWORD is set.

https://mcp.example.org/app/

On a phone it is worth adding to the home screen — it has a manifest and opens standalone, which is the difference between "a page I have to find" and "the thing I open in a free period".

Notizen is one screen: the day, ‹ › to move between days, and the editor.

• Opening a day with no note yet fills in that day's lessons from WebUntis — numbered, with times, teacher and room, cancellations left out and substitutions marked. That is the whole reason the app is day-shaped: the one thing WebUntis knows and you should not have to retype.
• Stunden ergänzen appears when the timetable has a lesson your note does not — a day you started writing before it ended, or a timetable that changed after you started. It appends what is missing and never touches what you wrote.
• It saves as you type (a couple of seconds after you stop), when the app goes to the background, and when the phone locks.
• Every keystroke also goes to the browser's local storage. If the connection drops mid-lesson you keep writing, and the next time the app loads that day it offers the version this device has. A note taken in a lesson cannot be retaken, which is the reasoning behind all of this.
• If the note changed elsewhere since you opened it — the laptop, a sync tool, add_note — the save is refused and you are asked which version wins. It never silently overwrites.

Einstellungen holds the Schulcloud token: how long it has left, and the box to paste a fresh jwt cookie into when it expires (the same thing schulcloud token set and the older /token page do). It also shows the index's state and the notes directory, and has the logout button.

The login

WEB_PASSWORD is the app's password — at least 12 characters, and a passphrase of three or four words is the right shape. It is hashed with scrypt at startup; the plain value is never stored, compared or logged.

Logging in sets an HttpOnly, SameSite=Strict session cookie that lasts 30 days, so a lesson never starts with a login screen. The cookie opens /api — it is the user — but not /mcp, which no browser needs. Changing WEB_PASSWORD invalidates every session, because the signing key is derived from it. Failed logins are rate-limited per address; a password is guessable in a way a 32-character token is not, and this endpoint is on the internet.

If WEB_PASSWORD is unset the app is not served at all — the same rule the untis_* and note tools follow. A login screen that no password can open is worse than no page, because it looks like a way in.

The other four ways to write a note

The app is not privileged; it writes the same files as everything else.

# the command line, text piped in
pbpaste | schulcloud note add --title "Subnetting" --subject LF07

# an editor, or anything else that writes files
$EDITOR "$NOTES_DIR/2026/2026-09-18.md"

# Claude, during or after the lesson
#   "halt fest: Gegenargument nicht vergessen, kam letztes Jahr dran"
#   → add_note, subject Deutsch, today's date

# a folder you already sync — see below

add_note and schulcloud note add take append, which adds to the note already written for that subject and that day rather than starting a second one — so "note this down too" mid-lesson lands in the note that is already open, whatever its title.

What may write, and where

The notes directory is the only thing this server writes to. Not Schulcloud, not WebUntis — those stay read-only, strictly, and that has not changed.

Every path component goes through safeComponent and the result through resolveWithin, the same two functions that stop a hostile Schulcloud filename escaping the file mirror, so a note titled ../../.ssh/authorized_keys becomes a filename. NOTES_READONLY=1 refuses writes entirely — right when the notes are synced in from somewhere else and should have exactly one writer. The app then still reads them, and says so rather than failing on save.

Migrating out of Apple Notes

Notes.app has no export. Its database is a Core Data store whose bodies are compressed protobuf and whose iCloud copy is encrypted, so scripting the app is not the clumsy route to your notes — it is the only one.

On the Mac, from a checkout of this repo:

osascript -l JavaScript scripts/export-apple-notes.js > notes.ndjson

The first run raises a macOS permission dialog ("Terminal wants access to Notes"); without it every note comes back empty. --folder Deutsch exports one Notes folder.

Then look at what it would do, and do it:

schulcloud note import notes.ndjson --dry-run
schulcloud note import notes.ndjson              # into the server
schulcloud note import notes.ndjson --out ~/Notizen   # or to a local folder first

would import: 2026-09-15 · Deutsch · Erörterung
Would import 84 of 91 note(s), skipped 5 with no text, 2 unreadable in Notes.

What it does with each note:

• The Notes folder becomes the subject — its last segment, so Schule/Deutsch is Deutsch. Notes' own default folders (Notizen, Recently Deleted) are ignored rather than becoming a subject. --subject LF07 overrides all of it.
• The creation date becomes the note's date, because that is the day of the lesson. The modification date is whenever you last tidied it up, which is not a school day at all.
• The HTML becomes Markdown — headings, lists, checklists, bold, italics and links survive; anything else keeps its words and loses its tag.
• Attachments do not come across. A note that was a photo of the board imports as a line saying an attachment was there. Better than importing empty: you can see which notes still need the picture.
• Locked notes cannot be read at all and are listed by name at the end. Unlock them in Notes and export again.

Imported notes arrive as single-subject notes, not day notes, which is the shape they were written in. Both kinds coexist.

Re-running the import creates second copies rather than overwriting, since the importer cannot tell an edited note from a new one with the same title. Import once, then keep writing in the new place.

Reading them

Tool	Answers
list_notes	"what did I write down in Deutsch before the test" — by subject or date, lesson headings included
get_note	one note in full, by the path everything else prints
search	notes by their contents, per lesson, next to board text and the inside of PDFs
what_changed	lessons and notes that appeared or were edited since a date

The pruefungsvorbereitung, zusammenfassung and tagesvorbereitung prompts consult them on their own, and are told to say when a note disagrees with the uploaded material rather than quietly preferring one.

Keeping them somewhere you already sync

The notes are files, so any sync tool will do and the server does not need to know which. Bind-mount the folder instead of using the volume:

# docker-compose.yml, under schulcloud-mcp:
    volumes:
      - /home/pi/Notizen:/data/notes

Then point Syncthing, Nextcloud, an Obsidian vault or git at /home/pi/Notizen. New files are picked up by the next crawl; nothing has to be told about them, and the app edits the same files.

Frontmatter is a small YAML subset — scalars and lists, in either the inline [a, b] or the indented - item form editors write — so an Obsidian vault round-trips. Unknown keys are kept and ignored.

What the server reads out of a note:

Field	Falls back to
title	the first # heading, else the filename without its date
date	a YYYY-MM-DD the filename starts with, else nothing
subject	the first folder name — except a year, which is a filing scheme
tags	none
courseId	none — set it to tie a note to a Schulcloud course in search

date also accepts 15.09.2026, and fach: works as a German spelling of subject:.

The file's modification time is never used as the date. An import writes every note today; dating a year of lessons "today" would make the whole store useless for revision, which is most of what it is for.

What the crawl does with them

A full crawl reads the directory and indexes every note — one entry per lesson for a day note, one for the whole note otherwise, under the kind note. A per-course refresh leaves them alone, and the store carries the previous generation's rows forward, so a per-course crawl never looks like the notes were deleted.

Notes are diffed by content, not by modification time, so a sync tool that rewrites a file byte-for-byte does not show up in what_changed as an edit.