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.

NOTES_DIR/
  Deutsch/
    2026-09-15 Erörterung.md
    2026-09-22 Sprachanalyse.md
  LF07/
    2026-09-16 Subnetting.md
  Allgemein/
    2026-09-18 Elternabend.md

Why files

Three properties, in this order:

• They have to be writable from a classroom. Whatever you take notes in on a phone or a laptop, it can produce text files; nothing can produce rows in the Pi's Postgres.
• They have to be readable when the index is down. list_notes and get_note read the disk, so they answer before the first crawl and while Postgres is unreachable — the index is a view of the notes, never the notes themselves. That is the same split as extracted file text and the mirror.
• They have to survive this project. A directory of dated Markdown is greppable, diffable, syncable and still yours if the server is thrown away.

What a note looks like

Frontmatter, then the note. Every field is optional, and a plain .md file with no frontmatter at all is a perfectly good note.

---
title: Erörterung — Aufbau
date: 2026-09-15
subject: Deutsch
tags: [klausur, aufsatz]
---

Dreischritt: These, Argument mit Beleg, Fazit.

Frau Meier betont: das **Gegenargument** darf nicht fehlen, sonst gibt es
Abzug — kam letztes Jahr in der Arbeit dran.

What the server reads out of it:

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 (Deutsch/…)
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:. Anything else in the block is kept but not interpreted.

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.

Reading them

Tool	Answers
list_notes	"what did I write down in Deutsch before the test" — filter by subject or date
get_note	one note in full, by the path everything else prints
search	notes by their contents, next to board text and the inside of PDFs
what_changed	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.

Writing them

Four ways in, all landing in the same files:

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

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

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

# by syncing a folder you already write in — see below

add_note and schulcloud note add take append, which adds to the note already written for that subject and day instead of starting a second one. That is the right choice while a lesson is running: notes accumulate in one file the way they do on paper.

This is the only thing in this server that writes anything. It writes into the notes directory and nowhere else: every path component goes through safeComponent and the result through resolveWithin, the same two functions that stop a hostile filename escaping the file mirror, so a note titled ../../.ssh/authorized_keys becomes a filename. Schulcloud and WebUntis stay strictly read-only — see the invariants in CLAUDE.md. Set NOTES_READONLY=1 to refuse writes entirely, which is right when the notes are synced in from somewhere else and should have exactly one writer.

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 convert and import. Look at it first:

schulcloud note import notes.ndjson --dry-run

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

and then for real, either straight into the server:

schulcloud note import notes.ndjson

or into a local directory, to read through before anything is sent anywhere:

schulcloud note import notes.ndjson --out ~/Notizen

What the import 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.

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.

Writing them from a phone, afterwards

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 on one side and your phone on the other. New files are picked up by the next crawl; nothing has to be told about them.

Without any of that, schulcloud note add and add_note still work — they go over the same authenticated /api as everything else the CLI does.

What the crawl does with them

A full crawl reads the directory and indexes every note: title, subject, tags and body, under the kind note, with its path as its id. A per-course refresh leaves them alone — notes belong to the account, not to a course — 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.