wicker-study-mcp 2.5.0 → 2.7.0

package/README.md

@@ -9,6 +9,17 @@ Runs from anywhere. Nothing here needs a checkout of the application.
 
 ## Use it
 
+The authenticated **Docs** page in Wicker Study can mint a scoped key and place it directly inside
+one copy-ready Codex or Claude Code installation block. There is no separate credential field to
+copy. The first line stores the embedded key with owner-only permissions and the second registers
+the MCP server.
+
+For a manually supplied key, the same secure bootstrap is available as:
+
+```sh
+WICKER_STUDY_URL='https://study.wicker.life' WICKER_STUDY_API_KEY='wsk_…' npx -y wicker-study-mcp@2.7.0 configure
+```
+
 ```jsonc
 // Claude Desktop / Claude Code / Cursor MCP config
 {
@@ -59,10 +70,11 @@ they are how a key is obtained. Everything else needs one.
 - **Reading** — `list_courses`, `get_course`, `get_chapter`, `get_course_outline`, `search_course`,
   `list_materials`, `list_questions`, `get_practice_queue`, `get_progress`, `list_flashcards`,
   `list_due_cards`, `list_mistakes`, `list_mock_sessions`, `get_mock_session`, `get_academic_plan`,
-  `list_known_programmes`, `get_calendar`, `get_activity`, `get_account_summary`, `whoami`
+  `get_planning_context`, `list_known_programmes`, `get_calendar`, `get_activity`,
+  `get_account_summary`, `whoami`
 - **Studying** — `submit_answer`, `set_mastery`, `review_card`, `add_to_deck`, `create_flashcard`,
   `review_flashcard`, `resolve_mistake`, `record_chapter_read`, `save_academic_plan`,
-  `set_course_visibility`, `join_programme`
+  `update_planning_objective`, `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_updates` (announcements, assignments with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicker-study-mcp",
-  "version": "2.5.0",
+  "version": "2.7.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",

package/server.mjs

@@ -25,6 +25,24 @@ import { getSavedCanvasAccessToken, promptForLocalCanvasImport, saveCanvasAccess
 import { beginAuthorization } from './authorize.mjs'
 import { configPath, forgetApiKey, listSavedServers, normaliseServerUrl, resolveApiKey, saveApiKey } from './config.mjs'
 
+// A copy-ready installation block can provision the credential before an MCP
+// client launches the stdio server. Persist it through the same hardened
+// config writer as browser authorization (0700 directory, 0600 file), then
+// discard the environment value with this short-lived process.
+if (process.argv[2] === 'configure') {
+  try {
+    const serverUrl = normaliseServerUrl(process.env.WICKER_STUDY_URL || 'https://study.wicker.life')
+    const apiKey = String(process.env.WICKER_STUDY_API_KEY || '').trim()
+    if (!apiKey) throw new Error('WICKER_STUDY_API_KEY is required for configuration.')
+    const saved = await saveApiKey(serverUrl, apiKey, { name: 'Terminal installation', scopes: ['read', 'write'] })
+    process.stdout.write(`Wicker Study access saved securely for ${saved.server} at ${saved.path}.\n`)
+    process.exit(0)
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : 'Wicker Study could not be configured.'}\n`)
+    process.exit(1)
+  }
+}
+
 const baseUrl = normaliseServerUrl(process.env.WICKER_STUDY_URL || 'https://study.wicker.life')
 const DEFAULT_CANVAS_URL = process.env.WICKER_CANVAS_URL || 'https://canvas.maastrichtuniversity.nl'
 
@@ -71,7 +89,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.5.0' })
+const server = new McpServer({ name: 'wicker-study', version: '2.7.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").')
 
@@ -417,7 +435,7 @@ server.tool('wicker_sign_out',
       stillConnected: Boolean(credential.apiKey),
       note: credential.apiKey
         ? 'WICKER_STUDY_API_KEY is set in this process’s environment and still applies; unset it to disconnect fully.'
-        : `Revoke the key itself at ${baseUrl}/app#/account/api if it should stop working everywhere.`
+        : `Revoke the key itself at ${baseUrl}/app/settings?tab=api if it should stop working everywhere.`
     }
   }))
 
@@ -426,7 +444,7 @@ server.tool('canvas_connect',
   { canvasUrl: z.string().optional().describe(`Canvas origin. Default ${DEFAULT_CANVAS_URL}.`) },
   run(async ({ canvasUrl }) => {
     const origin = new URL(canvasUrl || DEFAULT_CANVAS_URL).origin
-    const settings = `${baseUrl}/app#/account/connections`
+    const settings = `${baseUrl}/app/settings?tab=connections`
     const connections = (await api('/api/account/integrations/canvas')).connections || []
     const match = connections.find((connection) => connection.origin === origin) || null
     if (match) {
@@ -460,8 +478,23 @@ server.tool('get_chapter', 'Chapter markdown content. relPath opens a linked fil
   run(({ courseId, chapterId, relPath }) => api(`/api/chapter/${encodeURIComponent(courseId)}/${encodeURIComponent(chapterId)}${relPath ? '/' + relPath.split('/').map(encodeURIComponent).join('/') : ''}`)))
 server.tool('get_course_outline', 'Heading outline of every chapter in a course.', { courseId }, run(({ courseId }) => api(`/api/course-toc/${encodeURIComponent(courseId)}`)))
 server.tool('list_materials', 'Files in a course knowledge base (markdown, PDFs, images, code).', { courseId }, run(({ courseId }) => api('/api/materials', { query: { courseId } })))
-server.tool('search_course', 'Full-text retrieval over course material (hosted deployments).', { courseId, query: z.string(), limit: z.number().int().min(1).max(20).optional() },
-  run(({ courseId, query, limit }) => api('/api/retrieve', { method: 'POST', body: { courseId, query, limit } })))
+server.tool('search_course', 'Hybrid full-text and embedding retrieval across published material and authorised Canvas snapshots. Results identify the exact academic-year edition and source path. Specify academicYear for a strict edition query; otherwise current and historical editions may be searched, with newer editions preferred.', {
+  courseId: courseId.optional(),
+  courseCode: z.string().optional().describe('Stable course code, for example BCS1540. Use this when querying Canvas editions.'),
+  canonicalCourseId: z.string().optional().describe('Stable corpus course identity returned by an earlier search.'),
+  academicYear: z.string().optional().describe('Exact edition such as 2025-2026.'),
+  sourceType: z.enum(['syllabus', 'requirements', 'slides', 'pages', 'assessments', 'activities', 'readings', 'materials']).optional(),
+  includeHistorical: z.boolean().optional().describe('Search older editions when no exact year is requested; defaults to true.'),
+  query: z.string(),
+  limit: z.number().int().min(1).max(20).optional()
+}, run((args) => api('/api/retrieve', { method: 'POST', body: args })))
+server.tool('canvas_corpus_status', 'Material collection consent, background sync jobs, versioned course editions, source counts, and last/next scrape times for the connected account.', {
+  canvasUrl: z.string().url().optional()
+}, run(({ canvasUrl }) => api('/api/account/integrations/canvas/corpus', { query: { canvasUrl: canvasUrl || DEFAULT_CANVAS_URL } })))
+server.tool('canvas_corpus_sync', 'Queue a server-side refresh of authorised Canvas material. Collection must first be enabled by the user in the signed-in Wicker Study browser; an MCP key cannot grant or expand consent.', {
+  canvasUrl: z.string().url().optional(),
+  force: z.boolean().optional()
+}, run(({ canvasUrl, force }) => api('/api/integrations/canvas/corpus/sync', { method: 'POST', body: { canvasUrl: canvasUrl || DEFAULT_CANVAS_URL, force } })))
 server.tool('list_questions', 'Published questions for a chapter plus the student’s personal extra exercises.', { courseId, chapterId },
   run(({ courseId, chapterId }) => api(`/api/questions/${encodeURIComponent(courseId)}/${encodeURIComponent(chapterId)}`)))
 server.tool('get_practice_queue', 'Every published question across active courses (optionally one course).', { courseId: courseId.optional(), limit: z.number().int().min(1).max(500).optional() },
@@ -474,6 +507,7 @@ server.tool('list_mistakes', 'Mistake bank.', { open: z.boolean().optional().des
 server.tool('list_mock_sessions', 'Completed mock sessions.', {}, run(() => api('/api/mocks')))
 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('get_planning_context', 'Read the student’s saved exam scenario as a compact planning model. Recorded attempts and grades are explicitly separated from private choices such as a resit, following-year deferral, expected grade, or what-if outcome. Actual academic-calendar records are grouped into dated examination windows, so one window can contain a period’s primary exams and another period’s resits. Each course includes allowed session ids and course-specific roles derived from its teaching period, calendar, transcript fallback, and verified resit rules. Returns stable session ids and a revision; call this before suggesting or changing the plan.', {}, run(() => api('/api/planning/context')))
 server.tool('list_known_programmes', 'The catalogue of known bachelor programmes.', {}, run(() => api('/api/editorial-programmes')))
 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 } }))
@@ -503,6 +537,14 @@ server.tool('record_chapter_read', 'Record that the student read a chapter.', {
   run(({ courseId, chapterId, label }) => api('/api/activity', { method: 'POST', body: { type: 'read', courseId, chapterId, label } })))
 server.tool('save_academic_plan', 'Save the active academic programme workspace. Pass the revision you read to avoid overwriting concurrent edits.', { workspace: z.record(z.any()), expectedRevision: z.number().int() },
   run(({ workspace, expectedRevision }) => api('/api/academics', { method: 'PUT', body: { workspace, expectedRevision } })))
+server.tool('update_planning_objective', 'Update one course in the student’s private exam scenario without replacing the rest of the academic record. Call get_planning_context first, use a session id from that course’s planningRules.allowedSessionIds, inspect allowedDestinations for whether the shared window is a primary or resit route for that course, explain the exact change to the student, and pass the revision you read. Invalid sittings and stale revisions are rejected.', {
+  courseId: z.string(),
+  expectedRevision: z.number().int(),
+  mode: z.enum(['current', 'resit', 'none']).optional(),
+  targetSession: z.string().max(140).nullable().optional(),
+  expectedGrade: z.number().min(0).max(100).nullable().optional(),
+  outcome: z.enum(['actual', 'pass', 'fail']).optional()
+}, run(({ courseId: id, expectedRevision, ...objective }) => api(`/api/planning/objectives/${encodeURIComponent(id)}`, { method: 'PATCH', body: { objective, expectedRevision } })))
 server.tool('set_course_visibility', 'Archive/unarchive or reorder a course for the student.', { courseId, archived: z.boolean().optional(), order: z.number().int().optional() },
   run(({ courseId, archived, order }) => api(`/api/courses/${encodeURIComponent(courseId)}`, { method: 'PATCH', body: { archived, order } })))
 

package/vendor/canvas-course-import.mjs

@@ -715,10 +715,11 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     }
   }
 
-  const [courseAssignments, courseQuizzes, courseDiscussions] = await Promise.all([
+  const [courseAssignments, courseQuizzes, courseDiscussions, coursePages] = await Promise.all([
     optionalCourseCollection('Course-wide assignments listing', `/api/v1/courses/${encodeURIComponent(canvas.courseId)}/assignments?per_page=100`),
     optionalCourseCollection('Course-wide quizzes listing', `/api/v1/courses/${encodeURIComponent(canvas.courseId)}/quizzes?per_page=100`),
-    optionalCourseCollection('Course-wide discussions listing', `/api/v1/courses/${encodeURIComponent(canvas.courseId)}/discussion_topics?per_page=100`)
+    optionalCourseCollection('Course-wide discussions listing', `/api/v1/courses/${encodeURIComponent(canvas.courseId)}/discussion_topics?per_page=100`),
+    requestedModuleIds ? Promise.resolve([]) : optionalCourseCollection('Course-wide Pages listing', `/api/v1/courses/${encodeURIComponent(canvas.courseId)}/pages?per_page=100`)
   ])
   for (const [index, assignment] of courseAssignments.entries()) {
     const id = String(assignment.id || '')
@@ -736,6 +737,21 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     await importDiscussion({ discussionId: id, base: join(root, 'course-communications'), position: index + 1, source: { moduleId: null, moduleName: null, itemId: id, itemType: 'Course discussion', title: text(discussion.title, 300) }, initial: discussion })
   }
 
+  // Lecturers often publish wiki pages through the Pages navigation without
+  // adding them to a module. Enumerate that collection during a full archive;
+  // importPage deduplicates anything already reached through modules or links.
+  for (const [index, page] of coursePages.entries()) {
+    const pageSlug = text(page.url || page.page_url, 300)
+    if (!pageSlug || importedPageSlugs.has(pageSlug)) continue
+    await importPage({
+      slug: pageSlug,
+      base: join(root, 'course-pages'),
+      position: index + 1,
+      title: page.title || pageSlug,
+      source: { moduleId: null, moduleName: null, itemId: pageSlug, itemType: 'Course page', title: text(page.title, 300) }
+    })
+  }
+
   for (const [index, file] of courseFiles.entries()) {
     if (downloadedFileIds.has(String(file.id))) continue
     await importFile(file.id, join(root, 'unassigned-files'), index + 1, { moduleId: null, moduleName: null, itemId: String(file.id), itemType: 'File', title: file.display_name || file.filename })
@@ -757,7 +773,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     limits: { maxResources, maxFileBytes }
   }
   await writeFile(manifestPath, `${JSON.stringify(summary, null, 2)}\n`, 'utf8')
-  await writeFile(join(root, 'README.md'), `# ${courseName}\n\nImported privately from Canvas on ${summary.importedAt.slice(0, 10)}.\n\n- Canvas course: ${canvas.courseUrl}\n- Modules included: ${selectedModules.length}${requestedModuleIds ? ' (chosen subset)' : ''}\n- Resources written: ${records.length}\n- Resources skipped: ${skipped.length}\n- Previous imported paths no longer found: ${staleLocalResources.length}\n\nThe snapshot includes the Canvas rich-text syllabus when the account can read it, plus separately uploaded course files (including syllabus/course-manual files), module material, accessible course-wide assignments, quizzes, discussions, and question banks where Canvas permits question access. Canvas pages are followed recursively when they link to another page in this same course. File links in rich-text records are downloaded when accessible; every HTTP(S) reference is compiled into a nearby \`link-index\` file and the hidden manifest. External sites are recorded, never crawled.\n\nThis folder is a source snapshot. Keep it local until the administrator confirms they are authorised to submit the materials for editorial review. The hidden \`.wicker-canvas-import.json\` file records exactly what was found. Re-run the importer into this same folder to refresh changed or newly published Canvas material. Paths no longer returned by Canvas are listed in that manifest for review; they are never deleted automatically.\n`, 'utf8')
+  await writeFile(join(root, 'README.md'), `# ${courseName}\n\nImported privately from Canvas on ${summary.importedAt.slice(0, 10)}.\n\n- Canvas course: ${canvas.courseUrl}\n- Modules included: ${selectedModules.length}${requestedModuleIds ? ' (chosen subset)' : ''}\n- Resources written: ${records.length}\n- Resources skipped: ${skipped.length}\n- Previous imported paths no longer found: ${staleLocalResources.length}\n\nThe snapshot includes the Canvas rich-text syllabus when the account can read it, plus separately uploaded course files (including syllabus/course-manual files), module material, standalone course Pages, accessible course-wide assignments, quizzes, discussions, and question banks where Canvas permits question access. Canvas pages are followed recursively when they link to another page in this same course. File links in rich-text records are downloaded when accessible; every HTTP(S) reference is compiled into a nearby \`link-index\` file and the hidden manifest. External sites are recorded, never crawled.\n\nThis folder is a source snapshot. Keep it local until the administrator confirms they are authorised to submit the materials for editorial review. The hidden \`.wicker-canvas-import.json\` file records exactly what was found. Re-run the importer into this same folder to refresh changed or newly published Canvas material. Paths no longer returned by Canvas are listed in that manifest for review; they are never deleted automatically.\n`, 'utf8')
 
   return {
     root,