fabi/Schulcloud-MCP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Close the gaps an audit of courses, tasks, files and grades turned up

Browse Source 
Every area — courses, rooms, boards, topics, tasks, files, quizzes, teams,
groups, submissions, grades — was checked for data the instance has and the
tools did not show.

Grades and feedback. A teacher's /homework page is a different page from a
student's: grade and comment live in the grading form, one block per
submission, so a teacher account reported every graded submission as having
neither. parseTeacherGrading reads the form, and list_submissions can now
include the written feedback and who handed the work in.

Names. /api/v1 is partly served: courses, users and classes survive in the
deployment's ingress table, and users/{id} is the only route from an id to a
name. Submitters, file creators and course teachers resolve through it, and
degrade to "not visible to this account" where a student may not read them.

Courses, rooms and classes. get_course adds the description, teachers,
member count and weekly timetable from /api/v1/courses. list_classes is new.
get_room reports what the account may do — allowedOperations is an object of
booleans, not the list it was typed as — and applicants and invitation links
where it may manage them.

Board and topic content. Link descriptions, image alt text, drawing and
video-conference titles, the ids behind external tools and H5P content (the
only thing resembling a quiz), and what a deleted element used to be. Topic
Etherpad pads are read like board pads, and htmlToText keeps table columns
apart and drops template indentation.

Files. A scan with no text layer falls back to the preview endpoint, whose
width and outputFormat are undocumented enums, so Claude gets a picture of
the page; list_files reports counts and sizes. Teams stay documented as
unreadable at any API version; their files come later.

What the crawl missed. Tasks attached to topics (18 of 60 on the live
account), each course's own file area, and — behind INDEX_PERSONAL_FILES —
personal files and submissions with their grade comments, so search and
what_changed cover grading. A submission hit points at get_task.

The local instance's preview profile gets an ImageMagick policy that allows
the coders its 7.1.2 build needs; the image's own denies them all.

110 tests.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
2026-09-16 20:19:16 +02:00
parent a3b17a680c
commit 5ae2210459
25 changed files with 1462 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
src/mcp/tools/files.ts
View File

@@ -30,11 +30,22 @@ export function registerFileTools(server: McpServer, context: ServerContext): vo
async ({ parentType, parentId }) => {
try {
const schoolId = await context.schoolId();
const page = await context.client.listFiles({ storageLocationId: schoolId, parentType, parentId });
const [page, stats] = await Promise.all([
context.client.listFiles({ storageLocationId: schoolId, parentType, parentId }),
// Cheap, and it is the only way to see that a parent holds files
// the listing paged past.
context.client.getParentFileStats(parentType, parentId).catch(() => undefined),
]);
if (page.data.length === 0) return text(`No files attached to ${parentType} ${parentId}.`);
const total =
stats && stats.fileCount > page.data.length
? ` — ${stats.fileCount} in total, ${formatBytes(stats.totalSizeInBytes)}`
: stats
? ` — ${formatBytes(stats.totalSizeInBytes)} in total`
: '';
return text(
joinSections([
heading(2, `Files on ${parentType} ${parentId} (${page.data.length})`),
heading(2, `Files on ${parentType} ${parentId} (${page.data.length})${total}`),
page.data.map((file) => `- ${formatFileLine(file)} — uploaded ${formatDate(file.createdAt)}`).join('\n'),
'Read one with download_file.',
]),
@@ -80,7 +91,12 @@ export function registerFileTools(server: McpServer, context: ServerContext): vo
`"${record.name}" was blocked by the instance's virus scanner and will not be downloaded.`,
);
}
const file = await context.client.downloadFile(record);
const [file, uploader] = await Promise.all([
context.client.downloadFile(record),
// Who put the file there is often the quickest way to tell a
// teacher's material apart from a classmate's upload.
record.creatorId ? context.userName(record.creatorId) : Promise.resolve(undefined),
]);
const header = [
heading(2, record.name),
[
@@ -88,7 +104,7 @@ export function registerFileTools(server: McpServer, context: ServerContext): vo
`- Type: ${record.mimeType}`,
`- Size: ${formatBytes(record.size)}`,
`- Attached to: ${record.parentType} \`${record.parentId}\``,
`- Uploaded: ${formatDate(record.createdAt)}`,
`- Uploaded: ${formatDate(record.createdAt)}${uploader ? ` by ${uploader}` : ''}`,
record.securityCheckStatus !== 'verified'
? `- Virus scan: ${record.securityCheckStatus}`
: undefined,
@@ -140,6 +156,32 @@ export function registerFileTools(server: McpServer, context: ServerContext): vo
);
}
// Nothing extractable — but files-storage may still be able to render
// the file as a picture. That is the whole answer for an image-only
// PDF: its pages *are* pictures, so a rasterised preview is readable
// where the bytes are not, and it needs no OCR on our side.
if (record.previewStatus === 'preview_possible') {
const preview = await context.client.getFilePreview(record, 500).catch(() => undefined);
if (preview && preview.mimeType.startsWith('image/')) {
const result: CallToolResult = {
content: [
{
type: 'text',
text: joinSections([
header,
// The note ends by suggesting raw bytes, which is no longer the
// best answer once a readable rendering is attached.
extraction.note.replace(' Use download_file with raw=true to get the bytes.', ''),
"Showing the instance's own rendered preview below, which is readable as a picture.",
]),
},
{ type: 'image', data: preview.bytes.toString('base64'), mimeType: preview.mimeType },
],
};
return result;
}
}
return text(joinSections([header, extraction.note]));
} catch (error) {
return toToolError(error, `download file ${fileId}`);