wicker-study-mcp 2.6.0 → 2.8.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.8.0 configure
+```
+
 ```jsonc
 // Claude Desktop / Claude Code / Cursor MCP config
 {
@@ -56,13 +67,14 @@ agent receives proxied course data and nothing else.
 `wicker_status`, `wicker_authorize`, `wicker_sign_out`, and `canvas_connect` work without a key —
 they are how a key is obtained. Everything else needs one.
 
-- **Reading** — `list_courses`, `get_course`, `get_chapter`, `get_course_outline`, `search_course`,
+- **Reading** — `list_courses`, `get_course`, `get_chapter`, `get_course_outline`, `search_course`, `list_regulation_sources`, `search_regulations`,
   `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.6.0",
+  "version": "2.8.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.6.0' })
+const server = new McpServer({ name: 'wicker-study', version: '2.8.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?tab=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?tab=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) {
@@ -470,6 +488,15 @@ server.tool('search_course', 'Hybrid full-text and embedding retrieval across pu
   query: z.string(),
   limit: z.number().int().min(1).max(20).optional()
 }, run((args) => api('/api/retrieve', { method: 'POST', body: args })))
+server.tool('search_regulations', 'Focused retrieval from official regulations for the active programme. Use for the Education and Examination Regulations, Board of Examiners, exam and resit procedures, registration, inspections, appeals, exemptions, hardship, fraud, projects, internships and curriculum transition rules. Results include the governing document, academic year and exact page; programme-restricted originals are not exposed.', {
+  query: z.string(),
+  academicYear: z.string().optional().describe('Exact academic year such as 2026-2027. Defaults to the active programme year.'),
+  documentKind: z.enum(['education-examination-regulations', 'rules-regulations', 'board-of-examiners', 'exam-procedure', 'programme-policy', 'other']).optional(),
+  limit: z.number().int().min(1).max(20).optional()
+}, run((args) => api('/api/programme-policies/retrieve', { method: 'POST', body: args })))
+server.tool('list_regulation_sources', 'List the official regulation sources indexed for the active programme and academic year. Returns reviewed metadata and coverage counts, never a programme-restricted original.', {
+  academicYear: z.string().optional().describe('Exact academic year such as 2026-2027. Defaults to the active programme year.')
+}, run(({ academicYear }) => api('/api/programme-policies', { query: { academicYear } })))
 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 } })))
@@ -489,6 +516,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 } }))
@@ -518,6 +546,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 } })))