Fabian Hamm
35125b7683
Read-only MCP server exposing a Schulcloud account to Claude: courses,
column boards, lessons, tasks, and file downloads with text extraction.
The API surface was verified against the live instance rather than
inferred from upstream source, which changed several design decisions:
- The `jwt` cookie works verbatim as `Authorization: Bearer` and lasts 30
days, so there is no cookie jar and no refresh-session timer.
- Course contents live at /api/v3/course-rooms/{courseId}/board; there is
no GET /api/v3/courses/{id}.
- Files are a separate service (/api/v3/file/*) with its own OpenAPI doc.
- Board file elements carry no file id; attachments are resolved by
listing files-storage with parentType=boardnodes and the element id.
Read-only by construction: every client method is a GET, including the
api_get escape hatch. The endpoint is internet-facing by necessity, so a
leaked token being unable to act as the user is the key safety property.
Deploys as a container behind the Pi's existing Caddy, guarded by a
constant-time bearer check. Stateless — no database.
Verified: 28 unit tests, plus a 30-check end-to-end run driving a real
MCP client over Streamable HTTP against the live account.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
74 lines
2.5 KiB
TypeScript
74 lines
2.5 KiB
TypeScript
import assert from 'node:assert/strict';
|
|
import { describe, it } from 'node:test';
|
|
import { daysUntil, formatDate, htmlToText, joinSections, normalizeObjectId } from '../src/render.ts';
|
|
|
|
describe('htmlToText', () => {
|
|
it('unwraps the CKEditor markup Schulcloud stores', () => {
|
|
assert.equal(htmlToText('<p>Hallo <strong>Welt</strong></p>'), 'Hallo Welt');
|
|
});
|
|
|
|
it('keeps the href when the link text differs from it', () => {
|
|
assert.equal(
|
|
htmlToText('<p><a href="https://example.org/x">Beispiel</a></p>'),
|
|
'Beispiel (https://example.org/x)',
|
|
);
|
|
});
|
|
|
|
it('does not duplicate a bare URL used as its own label', () => {
|
|
assert.equal(htmlToText('<a href="https://example.org">https://example.org</a>'), 'https://example.org');
|
|
});
|
|
|
|
it('renders list items as bullets and collapses blank runs', () => {
|
|
assert.equal(htmlToText('<ul><li>eins</li><li>zwei</li></ul>'), '- eins\n- zwei');
|
|
});
|
|
|
|
it('decodes entities, ampersand last so &lt; stays literal', () => {
|
|
assert.equal(htmlToText('<p>a &lt; b < c d</p>'), 'a < b < c d');
|
|
});
|
|
|
|
it('returns an empty string for missing input', () => {
|
|
assert.equal(htmlToText(undefined), '');
|
|
assert.equal(htmlToText(null), '');
|
|
});
|
|
});
|
|
|
|
describe('formatDate', () => {
|
|
it('renders ISO timestamps as minute-precision UTC', () => {
|
|
assert.equal(formatDate('2026-08-17T08:00:00.000Z'), '2026-08-17 08:00');
|
|
});
|
|
|
|
it('passes through unparseable values rather than printing Invalid Date', () => {
|
|
assert.equal(formatDate('not a date'), 'not a date');
|
|
});
|
|
|
|
it('marks absent dates', () => {
|
|
assert.equal(formatDate(null), '—');
|
|
});
|
|
});
|
|
|
|
describe('daysUntil', () => {
|
|
it('is negative for past dates and undefined when unset', () => {
|
|
const yesterday = new Date(Date.now() - 86_400_000).toISOString();
|
|
assert.ok((daysUntil(yesterday) ?? 0) < 0);
|
|
assert.equal(daysUntil(undefined), undefined);
|
|
});
|
|
});
|
|
|
|
describe('joinSections', () => {
|
|
it('drops empty and falsy parts', () => {
|
|
assert.equal(joinSections(['a', '', undefined, false, ' ', 'b']), 'a\n\nb');
|
|
});
|
|
});
|
|
|
|
describe('normalizeObjectId', () => {
|
|
it('converts the buffer shape the legacy lesson API returns', () => {
|
|
const id = { buffer: { type: 'Buffer', data: [106, 130, 219, 101, 127, 25, 207, 115, 254, 60, 242, 13] } };
|
|
assert.equal(normalizeObjectId(id), '6a82db657f19cf73fe3cf20d');
|
|
});
|
|
|
|
it('passes plain strings through and gives up on anything else', () => {
|
|
assert.equal(normalizeObjectId('abc'), 'abc');
|
|
assert.equal(normalizeObjectId({}), undefined);
|
|
});
|
|
});
|