wicker-study-mcp 2.11.0 → 2.12.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.11.0 configure
+WICKER_STUDY_URL='https://study.wicker.life' WICKER_STUDY_API_KEY='wsk_…' npx -y wicker-study-mcp@2.12.0 configure
 ```
 
 ```jsonc
@@ -100,7 +100,13 @@ 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.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.
+Update an installed client to `wicker-study-mcp@2.12.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.
+
+### Complete original downloads and remembered context
+
+Use `canvas_course_materials` to choose an exact asset/course/year, then call `download_course_original({assetId, courseCode, academicYear, outputFolder})`. The MCP streams the full stored original to a new private local subfolder and returns its path, size and SHA-256 only after verifying the complete file. PDFs, slide decks, images, spreadsheets and archives retain their original bytes. Existing files are never overwritten. Failed or incomplete downloads are removed. The maximum is 1 GB per file; larger files remain available through the authenticated web download. A remote MCP's filesystem may not be accessible to its client. This tool uses read scope and never scrapes Canvas or sends file bytes into the chat.
+
+The companion skill now proactively notices lasting preferences, project decisions, constraints and availability during normal discussions. It reads `tutor_sources` to avoid duplicates, prepares the exact new context, and asks for confirmation before saving with `tutor_confirm_update`. The agent reports a successful receipt instead of treating a draft or an ordinary chat reply as saved memory. Transient remarks and speculation are not stored, and tasks/attendance continue using their dedicated workflows.
 
 ## Licence
 
@@ -146,20 +152,39 @@ Students can follow reports and withdraw evidence at `/app/feedback`; authorized
 
 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
+## Updating an existing installation
+
+The in-app guide at [Docs → Update your MCP](https://study.wicker.life/app/docs#update) has copyable commands for both clients. For the standard installation, reuse your saved credentials; do not generate a new API key or run `configure` again.
 
-`claude mcp add` does not overwrite an existing registration. If it reports “MCP server wicker-study already exists in user config”, replace that registration:
+### Codex
+
+```sh
+codex mcp remove wicker-study
+codex mcp add wicker-study -- npx -y wicker-study-mcp@2.12.0
+```
+
+Quit and reopen the Codex app, restart the CLI session, or reload the IDE extension window so the local MCP process restarts.
+
+### Claude Code
 
 ```sh
 claude mcp remove --scope user wicker-study
-claude mcp add --scope user wicker-study -- npx -y wicker-study-mcp@2.11.0
+claude mcp add --scope user wicker-study -- npx -y wicker-study-mcp@2.12.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.
+Exit and restart Claude Code, then check `/mcp`. `claude mcp add` does not overwrite an existing registration. If you originally installed with `project` or `local` scope, use that same scope in both commands.
+
+### Claude Desktop and custom configurations
+
+In Claude Desktop, use Settings → Developer → Edit Config. Change only the package argument in the existing `wicker-study` entry to `wicker-study-mcp@2.12.0`, preserve its other settings, then fully quit and reopen Claude Desktop. For custom Codex/Claude Code configurations with environment variables or a server URL, update the package argument in place instead of replacing the registration. Check project overrides if an older version still loads.
+
+The standard helper credentials stay in `~/.config/wicker-study/config.json`. These registration commands do not delete that file. After restarting, ask the agent to call `wicker_status` and `study_generation_contract` to verify connectivity and availability of the new tools. Replace any installed [companion skill](https://study.wicker.life/skills/wicker-study/SKILL.md) in its existing location too.
+
+Official client references: [Codex MCP configuration](https://developers.openai.com/codex/mcp), [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp).
 
 ## 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.
+The 2.12.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 `wicker-study-mcp@2.12.0` using the update instructions above.
 
 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.

package/original-download.mjs

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto'
+import { mkdir, mkdtemp, open, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+// Stream to a private, unique directory. Never replace an existing user file or
+// expose a partial download as a successful original.
+export async function downloadCourseOriginal({ assetId, courseCode, academicYear, outputFolder }, { api, apiResponse }) {
+  const inventory = await api('/api/corpus/materials', { query: { courseCode, academicYear } })
+  const material = inventory.materials?.find(item => item.assetId === assetId)
+  if (!material) throw new Error('This original is not available in the selected course edition. Read canvas_course_materials again.')
+  const size = Number(material.byteSize)
+  if (!Number.isSafeInteger(size) || size < 0 || !/^[a-f0-9]{64}$/i.test(material.sha256 || '')) throw new Error('The original has no verifiable size or checksum. Refresh its material record before downloading.')
+  if (size > 1024 ** 3) throw new Error('This original exceeds the 1 GB local download limit. Use its authenticated web download instead.')
+  const response = await apiResponse(`/api/corpus/assets/${encodeURIComponent(assetId)}`, { query: { download: '1' }, timeoutMs: 300000, redirect: 'error' })
+  if (response.status !== 200 || !response.body) {
+    await response.body?.cancel()
+    throw new Error('The server did not return a complete original file. Retry the download.')
+  }
+  const root = resolve(outputFolder)
+  await mkdir(root, { recursive: true, mode: 0o700 })
+  const folder = await mkdtemp(join(root, 'wicker-original-'))
+  const filename = String(material.filename || assetId).split(/[\\/]/).pop().replace(/[\x00-\x1f\x7f]/g, '_').slice(0, 200)
+  const path = join(folder, !filename || /^\.+$/.test(filename) ? 'original' : filename)
+  let file
+  try {
+    file = await open(path, 'wx', 0o600)
+    const hash = createHash('sha256')
+    let byteSize = 0
+    for await (const chunk of response.body) {
+      byteSize += chunk.byteLength
+      if (byteSize > size) throw new Error('The downloaded original does not match its recorded size.')
+      hash.update(chunk)
+      // FileHandle.write may make a partial write; retain every byte.
+      let offset = 0
+      while (offset < chunk.byteLength) {
+        const { bytesWritten } = await file.write(chunk, offset, chunk.byteLength - offset)
+        if (!bytesWritten) throw new Error('The original could not be written completely.')
+        offset += bytesWritten
+      }
+    }
+    const sha256 = hash.digest('hex')
+    if (byteSize !== size || sha256 !== material.sha256.toLowerCase()) throw new Error('The downloaded original failed its size or checksum check. Retry; no partial file was retained.')
+    await file.close(); file = null
+    return { path, filename: material.filename, assetId, courseCode: material.courseCode, academicYear: material.academicYear, mediaType: material.mediaType, byteSize, sha256, complete: true, location: 'Local filesystem of this MCP server. The complete original bytes are saved; this is not extracted text.' }
+  } catch (error) {
+    await file?.close().catch(() => {})
+    await rm(folder, { recursive: true, force: true })
+    throw error
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicker-study-mcp",
-  "version": "2.11.0",
+  "version": "2.12.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",
@@ -30,6 +30,7 @@
   "files": [
     "server.mjs",
     "study-tools.mjs",
+    "original-download.mjs",
     "feedback-tools.mjs",
     "write-confirmation.mjs",
     "config.mjs",

package/server.mjs

@@ -2,6 +2,7 @@
 import { registerFeedbackTools } from './feedback-tools.mjs'
 import { installWriteConfirmation, toolRequestContext } from './write-confirmation.mjs'
 import { registerStudyTools } from './study-tools.mjs'
+import { downloadCourseOriginal } from './original-download.mjs'
 // Wicker Study MCP server — a thin stdio wrapper over the HTTP API so agents
 // (Claude Desktop, Claude Code, Codex, Cursor, …) can read course material and
 // a student's record, record study activity, collect a private Canvas course
@@ -60,13 +61,14 @@ function requireKey() {
   return credential.apiKey
 }
 
-async function apiResponse(path, { method = 'GET', body, query, timeoutMs } = {}) {
+async function apiResponse(path, { method = 'GET', body, query, timeoutMs, redirect } = {}) {
   const url = new URL(baseUrl + path)
   for (const [key, value] of Object.entries(query || {})) if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value))
   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.11.0', ...(toolRequestContext.getStore() ? { 'x-wicker-tool': toolRequestContext.getStore().tool, 'x-wicker-confirmed': String(toolRequestContext.getStore().confirmed) } : {}), ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+    ...(redirect ? { redirect } : {}),
+    headers: { authorization: `Bearer ${requireKey()}`, accept: 'application/json', 'x-wicker-client': 'wicker-study-mcp 2.12.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,12 +95,15 @@ 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.11.0' })
+const server = new McpServer({ name: 'wicker-study', version: '2.12.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").')
 registerFeedbackTools(server, { z, run, api })
 registerStudyTools(server, { z, run, api, defaultCanvasUrl: DEFAULT_CANVAS_URL })
+server.tool('download_course_original', 'Download one complete original material file to the local filesystem of this MCP server, with size and SHA-256 verification. First use canvas_course_materials to choose its exact assetId and course/year. Use for PDFs, slide graphics, tables, datasets or any full-file analysis beyond indexed passages. Saves unchanged bytes in a new private subfolder of outputFolder; never overwrites files, executes content, or exposes credentials. This is a read of the platform, not a scrape or context update.', {
+  assetId: z.string().min(1).max(160), courseCode: z.string().min(1).max(40), academicYear: z.string().max(20).optional(), outputFolder: z.string().min(1).max(2000)
+}, run(args => downloadCourseOriginal(args, { api, apiResponse })))
 
 const COURSE_SOURCE_EXTENSIONS = new Set(['.pdf', '.ppt', '.pptx', '.doc', '.docx', '.txt', '.md', '.csv', '.tex', '.m', '.py', '.r', '.html', '.htm', '.png', '.jpg', '.jpeg', '.webp'])
 const SOURCE_MIME = { '.pdf': 'application/pdf', '.ppt': 'application/vnd.ms-powerpoint', '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation', '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.tex': 'text/x-tex', '.m': 'text/x-matlab', '.py': 'text/x-python', '.r': 'text/x-r', '.html': 'text/html', '.htm': 'text/html', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' }

package/study-tools.mjs

@@ -19,14 +19,14 @@ export function registerStudyTools(server, { z, run, api, defaultCanvasUrl }) {
   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_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 or download_course_original for the complete unchanged file.', { 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 } }))
   tool('canvas_sync_course', 'Queue a specific accessible Canvas course edition. Current-period latest editions refresh automatically; use this for a missing or historical edition or an explicit refresh. Existing material consent is required; this cannot grant consent. force:false reuses verified unchanged resources.', { canvasUrl, canvasCourseId: z.string().regex(/^\d+$/), force: z.boolean().default(false) }, args => api('/api/integrations/canvas/corpus/course', { method: 'POST', body: { ...args, canvasUrl: args.canvasUrl || defaultCanvasUrl } }))
   tool('tutor_prepare_attendance_update', 'Prepare an exact attendance change without applying it or calling a model. First read get_attendance, then use its exact session IDs and the student’s explicit report. Show the returned proposal detail and ask for confirmation before tutor_confirm_update.', { courseCode: code, from: date, to: date, eventIds: z.array(id).min(1).max(20), status: z.enum(['attended','missed','unknown']), note: z.string().max(500).optional() }, body => api('/api/tutor/updates/prepare', { method: 'POST', body: { ...body, kind: 'attendance' } }))
-  tool('tutor_prepare_context', 'Prepare personal context for future Tutor answers without adding it to memory yet or calling a model. Examples: preferred explanation style, project role, or work every Tuesday/Friday. Store exact student-provided wording; optional dates bound temporary context. Availability is advice context, not proof of absence. Show the returned wording, dates and weekdays before requesting confirmation.', { kind: z.enum(['preference','availability','context']), text: z.string().min(1).max(400), weekdays: z.array(z.enum(['monday','tuesday','wednesday','thursday','friday','saturday','sunday'])).max(7).optional(), startDate: date, endDate: date }, body => api('/api/tutor/updates/prepare', { method: 'POST', body }))
+  tool('tutor_prepare_context', 'Proactively prepare lasting student preferences, project decisions/roles, constraints or availability learned during a conversation; do not wait for a reminder to save context. Read tutor_sources first to avoid duplicates or detect corrections. This prepares a draft, not saved memory, and calls no model. Preserve student-provided facts; dates bound temporary context. Availability is not proof of absence. Show exact wording/dates/weekdays and obtain confirmation before tutor_confirm_update.', { kind: z.enum(['preference','availability','context']), text: z.string().min(1).max(400), weekdays: z.array(z.enum(['monday','tuesday','wednesday','thursday','friday','saturday','sunday'])).max(7).optional(), startDate: date, endDate: date }, body => api('/api/tutor/updates/prepare', { method: 'POST', body }))
   tool('tutor_confirm_update', 'Apply the exact prepared attendance/context update only after the student explicitly confirms this individual write. Cannot edit the prepared payload. Review expires after 30 minutes; retries return the same receipt. Context becomes visible to future Tutor conversations in this account/programme.', { updateId: id, confirmed: z.literal(true) }, body => api('/api/tutor/updates/confirm', { method: 'POST', body }))
   tool('tutor_forget_context', 'Remove one remembered fact/preference/availability item after explicit confirmation. Read tutor_sources first to identify its exact memory ID.', { memoryId: id, confirmed: z.literal(true) }, ({ memoryId }) => api(`/api/tutor/memory/${encodeURIComponent(memoryId)}`, { method: 'DELETE' }))
   tool('tutor_history', 'List saved Tutor conversations without loading every transcript. Reuse the relevant conversation for follow-ups.', {}, () => api('/api/tutor', { query: { view: 'history' } }))

package/vendor/canvas-course-import.mjs

@@ -93,7 +93,7 @@ export function sanitizeCanvasHtml(value) {
     .replace(/\s+(href|src)\s*=\s*(?:"\s*javascript:[^"]*"|'\s*javascript:[^']*'|javascript:[^\s>]+)/gi, '')
 }
 
-function htmlRecord({ title, url, body, details = [] }) {
+export function htmlRecord({ title, url, body, details = [] }) {
   const rows = details.filter(([label, value]) => text(value)).map(([label, value]) => `<dt>${escapeHtml(label)}</dt><dd>${escapeHtml(value)}</dd>`).join('')
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head><body>
@@ -622,7 +622,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       const discussion = initial && Object.hasOwn(initial, 'message') ? initial : await api.getJson(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/discussion_topics/${encodeURIComponent(id)}`)
       const title = discussion.title || source.title || 'Canvas discussion'
       const outputPath = pagePath(join(base, 'discussions'), position, title, `discussion-${id}`)
-      await write(outputPath, htmlRecord({ title, url: discussion.html_url, body: discussion.message, details: [['Posted', discussion.posted_at], ['Discussion type', discussion.discussion_type], ['Due', discussion.delayed_post_at]] }))
+      await write(outputPath, htmlRecord({ title, url: discussion.html_url, body: discussion.message, details: [['Posted', discussion.posted_at], ['Discussion type', discussion.discussion_type], ['Scheduled publication', discussion.delayed_post_at]] }))
       const links = uniqueLinks(discussion.message, discussion.html_url || `${canvas.origin}/courses/${canvas.courseId}/discussion_topics/${id}`, canvas.origin, canvas.courseId)
       records.push({ kind: 'discussion', id, source, path: outputPath.slice(root.length + 1), canvasUrl: discussion.html_url || null, links })
       await indexAndFollowLinks({ title, pageUrl: discussion.html_url || `${canvas.origin}/courses/${canvas.courseId}/discussion_topics/${id}`, body: discussion.message, outputPath, source, id: `discussion-${id}`, links })