wicker-study-mcp 2.0.0 → 2.2.0

package/README.md

@@ -65,8 +65,11 @@ they are how a key is obtained. Everything else needs one.
   `set_course_visibility`, `join_programme`
 - **Documents and calendars** — `analyze_documents`, `apply_changes`, `preview_calendar`,
   `save_calendar_link`, `sync_calendar_link`, `remove_calendar_link`
-- **Canvas** — `canvas_connect`, `canvas_list_remote_courses`, `canvas_list_remote_course_modules`,
-  `canvas_import_remote_course`, `canvas_import_remote_course_set`
+- **Canvas** — `canvas_connect`, `canvas_updates` (announcements, assignments with
+  submission state, events, grades), `canvas_course_requirements` (syllabus and the
+  module item carrying the assessment rules), `canvas_list_remote_courses`,
+  `canvas_list_remote_course_modules`, `canvas_import_remote_course`,
+  `canvas_import_remote_course_set`
 - **Editorial (admin key)** — the `admin_*` family: course editions, source folders, rights review,
   extraction, mapping, generation, artifact review, and publication.
 

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "wicker-study-mcp",
-  "version": "2.0.0",
-  "description": "MCP server for Wicker Study: read course material and a student's academic record, study on their behalf, collect a private Canvas course snapshot, and — with an admin key — run the editorial workflow.",
-  "keywords": ["mcp", "model-context-protocol", "wicker-study", "canvas-lms", "study", "education"],
+  "version": "2.2.0",
+  "description": "MCP server for Wicker Study: read course material and a student's academic record, study on their behalf, collect a private Canvas course snapshot, and \u2014 with an admin key \u2014 run the editorial workflow.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "wicker-study",
+    "canvas-lms",
+    "study",
+    "education"
+  ],
   "license": "MIT",
   "author": "David Wicker",
   "homepage": "https://study.wicker.life",

package/server.mjs

@@ -71,7 +71,7 @@ const json = (value) => ({ content: [{ type: 'text', text: typeof value === 'str
 const failed = (error) => ({ isError: true, content: [{ type: 'text', text: error.message }] })
 const run = (fn) => async (args) => { try { return json(await fn(args)) } catch (error) { return failed(error) } }
 
-const server = new McpServer({ name: 'wicker-study', version: '2.0.0' })
+const server = new McpServer({ name: 'wicker-study', version: '2.2.0' })
 const courseId = z.string().describe('Course id (e.g. "sec"). Use list_courses to discover ids.')
 const chapterId = z.string().describe('Chapter id (e.g. "02").')
 
@@ -475,7 +475,7 @@ server.tool('list_mock_sessions', 'Completed mock sessions.', {}, run(() => api(
 server.tool('get_mock_session', 'One mock session with every answer and correction.', { sessionId: z.string() }, run(({ sessionId }) => api(`/api/mocks/${encodeURIComponent(sessionId)}`)))
 server.tool('get_academic_plan', 'Active academic programme: courses, attempts, exam dates, events, gates, summary.', {}, run(() => api('/api/academics')))
 server.tool('list_known_programmes', 'The catalogue of known bachelor programmes.', {}, run(() => api('/api/editorial-programmes')))
-server.tool('get_calendar', 'Unified calendar: exams, deadlines, registration windows, institution dates, and timetable feed events.', { from: z.string().optional().describe('ISO date; omit for everything'), to: z.string().optional() },
+server.tool('get_calendar', 'Unified calendar in one call: exam attempts, personal events, registration windows, the institution calendar, saved timetable feeds (lectures, tutorials, labs), and — when Canvas is connected — Canvas assignment deadlines and Canvas course events. This is the tool for "when is my next lecture", "where do I need to be", and "what is due this week". Events carry `category`, `courseCode`, and for Canvas items a `canvasStatus`; `problems` names any source that could not be read, which is how you tell an empty week from a missing timetable feed.', { from: z.string().optional().describe('ISO date; omit for everything'), to: z.string().optional() },
   run(async ({ from, to }) => { const data = await api('/api/calendar/events'); const events = data.events.filter((e) => (!from || String(e.start) >= from) && (!to || String(e.start) <= to)); return { ...data, events } }))
 server.tool('get_activity', 'Study activity series, streak, weekly totals, recent events.', { days: z.number().int().min(7).max(120).optional() }, run(({ days }) => api('/api/activity', { query: { days } })))
 server.tool('get_account_summary', 'What is stored for the account, per record family.', {}, run(() => api('/api/account/summary')))
@@ -507,10 +507,48 @@ server.tool('set_course_visibility', 'Archive/unarchive or reorder a course for
   run(({ courseId, archived, order }) => api(`/api/courses/${encodeURIComponent(courseId)}`, { method: 'PATCH', body: { archived, order } })))
 
 // ── Canvas through the account connection (no local PAT) ──────────────────
+server.tool('canvas_updates',
+  'What is happening in the student’s Canvas courses right now: announcements, assignments with their submission state, Canvas course events, and the grade Canvas shows. This is the tool for "what was announced", "what is due", "what have I not handed in", and "how am I doing". Answers are cached for ten minutes; pass refresh:true only when the student says something is missing. Never returns the Canvas token.',
+  {
+    scope: z.enum(['current', 'all']).optional().describe('"current" (default) is the courses being taught now, plus any the student starred on their Canvas dashboard and the standing faculty spaces. "all" includes concluded enrolments.'),
+    days: z.number().int().min(1).max(365).optional().describe('How far back to read announcements. Default 60.'),
+    courseIds: z.array(z.string()).optional().describe('Restrict to these Canvas course ids. Overrides scope.'),
+    parts: z.array(z.enum(['announcements', 'assignments', 'events', 'grades'])).optional().describe('Fetch only what is needed. Omitting this fetches all four.'),
+    refresh: z.boolean().optional()
+  },
+  run(({ scope, days, courseIds, parts, refresh }) => api('/api/integrations/canvas/hub', {
+    query: {
+      canvasUrl: DEFAULT_CANVAS_URL,
+      scope,
+      days,
+      courseIds: courseIds?.join(','),
+      parts: parts?.join(','),
+      refresh: refresh ? '1' : undefined
+    }
+  })))
+
+server.tool('canvas_course_requirements',
+  'The course syllabus and whichever module item carries the rules — assessment components and weights, minimum grades, attendance, deadlines, resit conditions. Use this for "what do I need to pass", "is attendance mandatory", "how is this graded". Canvas’s own syllabus field is usually only a filename or an unfilled placeholder, so when `syllabus.substantive` is false the answer is in `requirementItems`: fetch that File or Page and read it before answering. Never state a rule you have not read in a source — say it is not published yet instead.',
+  { courseUrl: z.string().describe('Canvas course URL, e.g. https://canvas.example.edu/courses/25806/modules. Use canvas_list_remote_courses to find it.') },
+  run(async ({ courseUrl }) => {
+    const result = await listRemoteCanvasCourseModules({ courseUrl })
+    return {
+      course: result.course,
+      syllabus: result.syllabus,
+      requirementItems: result.requirementItems,
+      next: result.syllabus?.substantive
+        ? 'The syllabus text below is the source. Cite it.'
+        : result.requirementItems?.length
+          ? 'Read these items before answering. canvas_import_remote_course with the containing module downloads them locally, where a File can be opened and a Page is saved as readable HTML.'
+          : 'Neither a syllabus nor a requirements document is published for this course yet. Say so; do not infer rules from convention or from another course.',
+      moduleCount: result.modules?.length ?? 0
+    }
+  }))
+
 server.tool('canvas_list_remote_courses', 'List current and concluded Canvas courses from the caller’s encrypted Wicker Study Canvas connection. Search title, course code, term, or title initials (for example “IUI”). The Canvas PAT is never returned to the agent.', {
   canvasUrl: z.string().url().default('https://canvas.maastrichtuniversity.nl'), query: z.string().max(240).optional()
 }, run(listRemoteCanvasCourses))
-server.tool('canvas_list_remote_course_modules', 'List modules for a Canvas course using the caller’s encrypted Wicker Study Canvas connection. Use this before importing a chosen subset.', {
+server.tool('canvas_list_remote_course_modules', 'List modules and their items for a Canvas course, plus its syllabus and any item that looks like the course manual. Use this before importing a chosen subset; for rules and assessment specifically, canvas_course_requirements returns the same data already narrowed down.', {
   courseUrl: z.string().url()
 }, run(listRemoteCanvasCourseModules))
 server.tool('canvas_import_remote_course', 'Download an entire Canvas course or selected modules into a private local folder through Wicker’s authenticated Canvas proxy. The destination is local to this MCP process, so Claude/Codex can analyse it using its own subscription; it never receives the Canvas PAT. Canvas pages are followed recursively within the course, linked files download when accessible, and URLs are compiled into link indexes.', {

package/vendor/canvas-course-import.mjs

@@ -36,6 +36,41 @@ function filename(value, fallback = 'material') {
   return raw || fallback
 }
 
+// The document that carries assessment rules, attendance requirements, and
+// deadlines. Two places hold it, and the course usually uses only one: the
+// Canvas Syllabus page — which typically contains a link to a PDF rather than
+// the rules themselves — or a module item.
+export const COURSE_REQUIREMENTS_PATTERN = /(syllabus|course\s*manual|coursemanual|course\s*outline|course\s*information|study\s*guide|handbook|assessment)/i
+
+// Maastricht ships every course a Syllabus page pre-filled with a link to a
+// how-to guide. A course still carrying it has published nothing, and treating
+// that link as the syllabus would be worse than reporting none.
+const SYLLABUS_PLACEHOLDER = /scribehow\.com|embed\s+(?:your\s+)?(?:the\s+)?course\s+syllabus/i
+
+// Pull the documents a Canvas Syllabus page links to. Stylesheets and the
+// institution's placeholder are not documents.
+export function syllabusDocuments(html, { origin = '', courseId = '' } = {}) {
+  const documents = []
+  for (const match of String(html || '').matchAll(/<a\b[^>]*href\s*=\s*"([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi)) {
+    const href = match[1]
+    const label = text(match[2].replace(/<[^>]*>/g, ' '), 200)
+    if (/\.css(\?|$)/i.test(href) || SYLLABUS_PLACEHOLDER.test(href) || SYLLABUS_PLACEHOLDER.test(label)) continue
+    const fileId = (href.match(/\/files\/(\d+)/) || [])[1] || null
+    const pageSlug = (href.match(new RegExp(`/courses/${courseId}/pages/([^/?#]+)`)) || [])[1] || null
+    documents.push({
+      title: label || 'Course syllabus',
+      type: fileId ? 'File' : pageSlug ? 'Page' : 'ExternalUrl',
+      contentId: fileId,
+      pageSlug: pageSlug ? decodeSegment(pageSlug) : null,
+      // A Canvas file link is fetchable through the account connection; an
+      // external one is recorded but never followed.
+      url: fileId && origin ? `${origin}/courses/${courseId}/files/${fileId}` : href,
+      source: 'syllabus-page'
+    })
+  }
+  return documents
+}
+
 function fileCategory(value) {
   const name = text(value, 240).toLowerCase()
   if (/(syllabus|course manual|course outline|study guide|course information)/.test(name)) return 'course-information'
@@ -289,15 +324,68 @@ export async function listCanvasCourseModules({ courseUrl, accessToken, fetchImp
     api.getJson(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}?include[]=syllabus_body`),
     api.getPaged(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/modules?include[]=items&per_page=100`)
   ])
+  const mapped = modules.sort((left, right) => number(left.position) - number(right.position)).map((module) => ({
+    id: String(module.id || ''),
+    name: text(module.name, 300) || 'Untitled module',
+    position: number(module.position),
+    items: Array.isArray(module.items) ? module.items.map((item) => ({
+      id: String(item.id || ''),
+      title: text(item.title, 300) || item.type || 'Untitled item',
+      type: text(item.type, 80) || 'Unknown',
+      indent: number(item.indent),
+      contentId: item.content_id ? String(item.content_id) : null,
+      pageSlug: item.page_url ? text(item.page_url, 200) : null,
+      url: item.html_url ? text(item.html_url, 500) : null
+    })) : []
+  })).filter((module) => module.id)
+
+  // The syllabus field was fetched above; hand it back rather than dropping it,
+  // and say plainly when it is only a pointer. A field this short is a filename
+  // or an unfilled placeholder, not the rules — the real document is the module
+  // item flagged below, and it still has to be read.
+  const rawSyllabus = String(course.syllabus_body || '')
+  const syllabusHtml = sanitizeCanvasHtml(rawSyllabus)
+  const syllabusText = text(String(syllabusHtml).replace(/<[^>]*>/g, ' '), 20_000)
+  const placeholder = SYLLABUS_PLACEHOLDER.test(rawSyllabus)
+  // Both places, in the order a reader should try them: the Syllabus page is
+  // where a course is supposed to put this, and a module item is where it ends
+  // up when the page was left as the institution's template.
+  const seenDocuments = new Set()
+  const requirementItems = [
+    ...syllabusDocuments(rawSyllabus, { origin: canvas.origin, courseId: canvas.courseId }),
+    ...mapped.flatMap((module) => module.items
+      .filter((item) => COURSE_REQUIREMENTS_PATTERN.test(item.title) && ['File', 'Page', 'Attachment'].includes(item.type))
+      .map((item) => ({ ...item, module: module.name, source: 'module' })))
+  ].filter((item) => {
+    // A course often carries the same document twice — linked from the Syllabus
+    // page and uploaded again as a module item, sometimes under different file
+    // ids. One entry is what a reader needs, and the Syllabus-page one comes
+    // first, so match on the filename as well as the id.
+    const name = String(item.title || '').trim().toLowerCase()
+    const keys = [item.contentId ? `file:${item.contentId}` : item.pageSlug ? `page:${item.pageSlug}` : `url:${item.url}`, name ? `name:${name}` : null].filter(Boolean)
+    if (keys.some((key) => seenDocuments.has(key))) return false
+    for (const key of keys) seenDocuments.add(key)
+    return true
+  })
+
   return {
     origin: canvas.origin,
     course: { id: String(course.id || canvas.courseId), name: text(course.name, 300) || `Canvas course ${canvas.courseId}`, courseCode: text(course.course_code, 160) || null, workflowState: text(course.workflow_state, 80) || null, courseUrl: canvas.courseUrl },
-    modules: modules.sort((left, right) => number(left.position) - number(right.position)).map((module) => ({
-      id: String(module.id || ''),
-      name: text(module.name, 300) || 'Untitled module',
-      position: number(module.position),
-      items: Array.isArray(module.items) ? module.items.map((item) => ({ id: String(item.id || ''), title: text(item.title, 300) || item.type || 'Untitled item', type: text(item.type, 80) || 'Unknown', indent: number(item.indent), contentId: item.content_id ? String(item.content_id) : null })) : []
-    })).filter((module) => module.id)
+    syllabus: {
+      html: syllabusHtml || null,
+      text: syllabusText || null,
+      // 200 characters of rich text is not a syllabus. Say so rather than
+      // letting a reader treat a filename as the course requirements.
+      substantive: syllabusText.length >= 200 && !placeholder,
+      placeholder,
+      note: syllabusText.length >= 200 && !placeholder ? null
+        : placeholder ? 'This course still has the institution’s empty syllabus template. Nothing has been published on the Syllabus page.'
+          : requirementItems.some((item) => item.source === 'syllabus-page') ? 'The Canvas Syllabus page links to the document rather than containing it. Read the item in requirementItems.'
+            : requirementItems.length ? 'This course has no Canvas syllabus text; the requirements document is a module item. Read the item in requirementItems.'
+              : 'This course has published no syllabus text and links to no document.'
+    },
+    requirementItems,
+    modules: mapped
   }
 }