wicker-study-mcp 2.10.0 → 2.11.0

package/README.md

@@ -17,7 +17,7 @@ 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.10.0 configure
+WICKER_STUDY_URL='https://study.wicker.life' WICKER_STUDY_API_KEY='wsk_…' npx -y wicker-study-mcp@2.11.0 configure
 ```
 
 ```jsonc
@@ -77,7 +77,7 @@ they are how a key is obtained. Everything else needs one.
   `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
+- **Canvas** — `canvas_groups` (your course teams and global memberships; pass a group ID to read teammates), `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`,
@@ -100,7 +100,7 @@ authoritative list of endpoints and scopes.
 
 Direct context reads do not call the model. `tutor_ask` uses the student's AI allowance and can prepare attendance changes, assignment/catch-up trackers, group milestones, focused practice, diagnostics and rubric-based draft reviews. Reuse conversation IDs. Approve only the exact proposal the student reviewed; receipts prevent double application. No tool sends email or submits assignments to Canvas. Personal completion is separate from Canvas submission status.
 
-Update an installed client to `wicker-study-mcp@2.10.0` and restart its MCP connection to discover the new tools. The companion skill is served at [SKILL.md](https://study.wicker.life/skills/wicker-study/SKILL.md); re-download it to update an existing copy.
+Update an installed client to `wicker-study-mcp@2.11.0` and restart its MCP connection to discover the new tools. The companion skill is served at [SKILL.md](https://study.wicker.life/skills/wicker-study/SKILL.md); re-download it to update an existing copy.
 
 ## Licence
 
@@ -145,3 +145,25 @@ Use `feedback_prepare` to create an exact report preview, then show it and obtai
 Students can follow reports and withdraw evidence at `/app/feedback`; authorized staff review them at `/app/admin/feedback`. See [the operations guide](../docs/FEEDBACK.md) for data boundaries and retention.
 
 Contact sharing is optional per report: use `shareContactEmail:true` only when the student chooses it and show the returned address in the preview. `feedback_withdraw_contact` stops sharing it after fresh confirmation. Reports show receipt, investigation and completion updates with public comments; AI-assisted replies are labeled and reviewed by the team.
+
+### Updating Claude Code
+
+`claude mcp add` does not overwrite an existing registration. If it reports “MCP server wicker-study already exists in user config”, replace that registration:
+
+```sh
+claude mcp remove --scope user wicker-study
+claude mcp add --scope user wicker-study -- npx -y wicker-study-mcp@2.11.0
+```
+
+Restart Claude Code afterward. Removing the MCP registration does not remove Wicker’s saved credentials in `~/.config/wicker-study/config.json`; you do not need to run `configure` again. This updates Claude Code, not the separate Claude Desktop configuration.
+
+## Local study generation
+
+The 2.11.0 source adds `study_generation_contract`, `study_generation_sources`, `study_generation_start`, `study_generation_next`, `study_generation_submit`, `study_generation_refresh`, `study_generation_stop`, and `study_generation_add_notes`. Install this repository checkout until that package version is published.
+
+1. Read the current contract and list the course edition’s sources. If needed, download originals with `canvas_import_remote_course`; inspect graphics and preserve page numbers. Add supplementary extraction as explicitly labelled local notes.
+2. Start the student-requested private run with its exact source selection, or continue a version prepared in the web UI.
+3. Fetch `study_generation_next`. Use its exact evidence, prompt and response schema to compute one complete response locally. Use a fresh critique context for review steps and report real findings.
+4. Submit with its `requestId` and `contractId`. Retry network failures with the identical payload. Fetch next again until complete. Failed content can be corrected with `retry:true`; ready chapters remain saved.
+
+Prompts and schemas are fetched from the deployed platform every step. An implementation fingerprint rejects submissions after pipeline changes; fetch next again. No platform generation worker, model call or AI allowance is used. Your local provider/subscription costs still apply. Local semantic reviews are agent-supplied; platform schema, citations and deterministic quality checks are enforced. This is not independent editorial verification, and nothing is shared automatically.

package/package.json

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

@@ -66,7 +66,7 @@ async function apiResponse(path, { method = 'GET', body, query, timeoutMs } = {}
   const response = await fetch(url, {
     ...(timeoutMs ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
     method,
-    headers: { authorization: `Bearer ${requireKey()}`, accept: 'application/json', 'x-wicker-client': 'wicker-study-mcp 2.10.0', ...(toolRequestContext.getStore() ? { 'x-wicker-tool': toolRequestContext.getStore().tool, 'x-wicker-confirmed': String(toolRequestContext.getStore().confirmed) } : {}), ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+    headers: { authorization: `Bearer ${requireKey()}`, accept: 'application/json', 'x-wicker-client': 'wicker-study-mcp 2.11.0', ...(toolRequestContext.getStore() ? { 'x-wicker-tool': toolRequestContext.getStore().tool, 'x-wicker-confirmed': String(toolRequestContext.getStore().confirmed) } : {}), ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
     body: body !== undefined ? JSON.stringify(body) : undefined
   })
   if (!response.ok) {
@@ -93,7 +93,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.10.0' })
+const server = new McpServer({ name: 'wicker-study', version: '2.11.0' })
 installWriteConfirmation(server, z)
 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").')

package/study-tools.mjs

@@ -6,8 +6,21 @@ export function registerStudyTools(server, { z, run, api, defaultCanvasUrl }) {
   const canvasUrl = z.string().url().optional()
   const context = z.object({ courseId: code, courseCode: code, chapterId: code, sourcePath: z.string().max(500).optional(), attachmentIds: z.array(id).max(10).optional() }).optional()
   const tool = (name, description, schema, handler) => server.tool(name, description, schema, run(handler))
+  // The installed MCP is a transport. Prompts, schemas and validation always
+  // come from the deployed pipeline, never a bundled copy that can drift.
+  const courseIdentity = { courseCode: z.string().min(2).max(80), courseName: z.string().max(180).optional(), academicYear: z.string().regex(/^(20\d{2}-20\d{2}|undated)$/), period: z.string().max(80).optional() }
+  const selection = { sourceKeys: z.array(id).min(1).max(500), includeHistorical: z.boolean().optional() }
+  tool('study_generation_contract', 'Read the current deployed generation protocol and quality contract before local generation. The platform provides the exact prompt and JSON schema for every step; do not use a cached prompt pack. No platform model call.', {}, () => api('/api/study-versions/local/contract'))
+  tool('study_generation_sources', 'List authorised source keys for a course edition before starting local generation. To process original files locally, use canvas_import_remote_course; retain slide graphics, tables, notes and page numbers. Add your OCR/visual interpretations as explicit local notes, never mislabel them as original source text.', courseIdentity, args => api('/api/study-versions/sources', { query: args }))
+  tool('study_generation_start', 'Start a private local-generation run using the student’s chosen course and source keys. Use when the student requests local generation. Then repeatedly fetch next, compute its complete JSON response locally, and submit. No platform AI billing or hosted worker is started. The authorised run includes its generation and review steps; it does not publish or share the guide.', { ...courseIdentity, ...selection, title: z.string().max(180).optional(), confirmed: z.literal(true) }, body => api('/api/study-versions/local', { method: 'POST', body }))
+  tool('study_generation_next', 'Continue an already authorised local run. Fetch the latest exact prompt, source evidence, response schema and contractId. Compute the response with your local model and submit using the returned requestId. For quality review use a fresh critique context; report unsupported claims honestly. If request is null inspect status: complete/failed/stopped need no polling, active may need another next call. retry:true resumes failed/stopped work. Never regenerate a finished step or ask for approval on each continuation.', { versionId: id, retry: z.boolean().optional() }, ({versionId,...body}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/next`, { method: 'POST', body, timeoutMs: 120000 }))
+  tool('study_generation_submit', 'Submit the complete JSON result for exactly one pending local request. Reuse requestId and identical response on network retry; changed contract or stale inputs require fetching next again. Server applies the same schema, citation, teaching-quality, repair and activation checks as hosted generation. This continues the existing authorised run and never publishes the guide.', { versionId: id, requestId: id, contractId: id, response: z.union([z.string().max(600000), z.record(z.unknown())]) }, ({versionId,...body}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/submit`, { method: 'POST', body, timeoutMs: 120000 }))
+  tool('study_generation_refresh', 'Start a new local revision with a changed source selection after the student requests an update. Stop an active run first. Finished revisions remain readable. Then continue with study_generation_next.', { versionId: id, ...selection, confirmed: z.literal(true) }, ({versionId,...body}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/refresh`, { method: 'POST', body }))
+  tool('study_generation_stop', 'Pause the student’s local run. Completed steps and published-to-self revisions are preserved; an outstanding local result can no longer be submitted.', { versionId: id }, ({versionId}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/stop`, { method: 'POST', body: {} }))
+  tool('study_generation_add_notes', 'Save student-authorised local extraction or notes as a clearly labelled private source. Preserve original page numbers and identify source filenames in text. Describe relevant graphs, tables, diagrams and relationships accurately; distinguish inference from source facts. Does not alter the original Canvas document. Use its returned id in sourceKeys.', { ...courseIdentity, title: z.string().max(150), pages: z.array(z.object({page: z.number().int().positive().nullable(), text: z.string().max(300000)})).min(1).max(500), confirmed: z.literal(true) }, body => api('/api/study-versions/local/notes', { method: 'POST', body }))
   tool('read_course_source', 'Read 12 indexed passages from an authorised Canvas document returned by search_course. Follow nextOffset to read beyond the snippet, including later paper-list pages. Retains edition, path and page citations; never widens source access.', { assetId: id, courseCode: z.string().min(1).max(40), offset: z.number().int().min(0).max(100000).optional() }, args => api('/api/retrieve/source', { query: args }))
   tool('canvas_course_materials', 'List indexed originals and source editions for one course. Select an exact academic year for a retake; use read_course_source for extracted text.', { courseCode: z.string().min(1).max(40), academicYear: z.string().max(20).optional() }, args => api('/api/corpus/materials', { query: args }))
+  tool('canvas_groups', 'Read your Canvas group memberships across courses and global groups. Filter by courseCode and academicYear to keep retake teams separate. Pass a groupId from these memberships to read teammates; include its canvasUrl if several Canvas hosts are connected. A failed roster is unknown, not an empty team. Read-only: never joins or changes groups.', {canvasUrl,courseCode:code,academicYear:z.string().max(20).optional(),scope:z.enum(['all','course','global']).optional(),groupId:z.string().regex(/^\d{1,20}$/).optional(),refresh:z.boolean().optional()}, ({refresh,...args}) => api('/api/integrations/canvas/groups',{query:{...args,refresh:refresh?'1':undefined}}))
   tool('canvas_assignment_detail', 'Read the full assignment brief, due/unlock/lock dates, own submission status, grade, rubric and submission comments. Use Canvas numeric course and assignment IDs from canvas_updates. Direct the student to /app/updates?tab=assignments&assignment=COURSE_ID%3AASSIGNMENT_ID; Canvas remains a secondary link.', { canvasUrl, courseId: z.string().regex(/^\d+$/), assignmentId: z.string().regex(/^\d+$/), refresh: z.boolean().optional() }, ({ refresh, ...args }) => api('/api/integrations/canvas/assignment', { query: { ...args, canvasUrl: args.canvasUrl || defaultCanvasUrl, refresh: refresh ? '1' : undefined } }))
   tool('canvas_sync_logs', 'Inspect durable progress for one sync job, optionally filtered by stage or severity. before is the next cursor returned by an earlier page. Last progress and worker checkpoints are distinct; do not claim a task is advancing from its heartbeat alone.', { job: id, before: z.string().max(160).optional(), stage: z.string().max(40).optional(), level: z.enum(['info','warning','error']).optional() }, args => api('/api/account/integrations/canvas/corpus/logs', { query: args }))
   tool('canvas_sync_control', 'Stop or retry one owned course-edition sync, after the student requests that action. Retry resumes saved originals and unfinished stages; stop fences the running worker and pauses future material refreshes for that edition.', { jobId: id, action: z.enum(['stop','retry']) }, ({ jobId, action }) => api(`/api/integrations/canvas/corpus/jobs/${encodeURIComponent(jobId)}`, { method: 'POST', body: { action } }))

package/vendor/canvas-course-import.mjs

@@ -589,9 +589,19 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     try {
       const assignment = initial && Object.hasOwn(initial, 'description') ? initial : await api.getJson(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/assignments/${encodeURIComponent(id)}`)
       const title = assignment.name || source.title || 'Canvas assignment'
+      source = { ...source, assignmentId: id, assignmentTitle: title }
       const outputPath = pagePath(join(base, 'assignments'), position, title, `assignment-${id}`)
       await write(outputPath, htmlRecord({ title, url: assignment.html_url, body: assignment.description, details: [['Due', assignment.due_at], ['Unlocks', assignment.unlock_at], ['Available until', assignment.lock_at], ['Points possible', assignment.points_possible], ['Submission types', (assignment.submission_types || []).join(', ')], ['Grading type', assignment.grading_type]] }))
       const links = uniqueLinks(assignment.description, assignment.html_url || `${canvas.origin}/courses/${canvas.courseId}/assignments/${id}`, canvas.origin, canvas.courseId)
+      // Some courses expose attachments as structured file objects, in addition
+      // to links in the assignment HTML. Resolve through the course file API.
+      for (const attachment of Array.isArray(assignment.attachments) ? assignment.attachments : []) {
+        const fileId = String(attachment.id || '')
+        if (/^\d+$/.test(fileId)) {
+          linkedFilePosition++
+          await importFile(fileId, join(root, 'linked-files'), linkedFilePosition, { ...source, itemType: 'Assignment attachment', title: attachment.display_name || attachment.filename || title })
+        }
+      }
       records.push({ kind: 'assignment', id, source, path: outputPath.slice(root.length + 1), canvasUrl: assignment.html_url || null, links })
       await indexAndFollowLinks({ title, pageUrl: assignment.html_url || `${canvas.origin}/courses/${canvas.courseId}/assignments/${id}`, body: assignment.description, outputPath, source, id: `assignment-${id}`, links })
       return outputPath
@@ -665,7 +675,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
   async function importTextItem(item, moduleBase, module) {
     const kind = String(item.type || '').toLowerCase()
     const itemId = String(item.id || item.content_id || `${module?.id || 'course'}-${item.position || 0}`)
-    const source = { moduleId: module?.id || null, moduleName: module?.name || null, itemId, itemType: item.type || 'Unknown', title: text(item.title, 300) }
+    const source = { moduleId: module?.id || null, moduleName: module?.name || null, modulePosition: module?.position ?? null, itemPosition: item.position ?? null, itemId, itemType: item.type || 'Unknown', title: text(item.title, 300) }
     if (kind === 'file') return importFile(item.content_id || item.content_details?.content_id, moduleBase, item.position, source)
     if (kind === 'subheader') return null
     try {
@@ -704,7 +714,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
 
   for (const module of selectedModules.sort((left, right) => number(left.position) - number(right.position))) {
     const moduleBase = join(root, 'modules', `${prefix(module.position)} ${safeSegment(module.name)}--module-${safeSegment(module.id)}`)
-    if (durable) module.items = await api.getPaged(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/modules/${encodeURIComponent(module.id)}/items?per_page=100`)
+    if (durable || !Array.isArray(module.items) || Number(module.items_count) > module.items.length) module.items = await api.getPaged(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/modules/${encodeURIComponent(module.id)}/items?per_page=100`)
     const hierarchy = []
     for (const item of (Array.isArray(module.items) ? module.items : []).sort((left, right) => number(left.position) - number(right.position))) {
       const indent = Math.min(12, Math.max(0, number(item.indent)))