wicker-study-mcp 2.0.0

package/README.md

@@ -0,0 +1,78 @@
+# wicker-study-mcp
+
+MCP server for [Wicker Study](https://study.wicker.life) — a private, source-grounded academic
+workspace. It gives an agent read access to course material and a student's academic record, the
+ability to study on their behalf, a Canvas course importer that never sees the Canvas token, and —
+with an admin key — the whole editorial content workflow.
+
+Runs from anywhere. Nothing here needs a checkout of the application.
+
+## Use it
+
+```jsonc
+// Claude Desktop / Claude Code / Cursor MCP config
+{
+  "mcpServers": {
+    "wicker-study": {
+      "command": "npx",
+      "args": ["-y", "wicker-study-mcp"]
+    }
+  }
+}
+```
+
+Then ask the agent to connect. It calls `wicker_status`, finds no key, calls `wicker_authorize`,
+and gives you a URL to approve in your browser. The key comes straight back to your machine over
+loopback and is saved for every future session.
+
+No environment variable is required. Two are honoured when set:
+
+| Variable | Meaning |
+| --- | --- |
+| `WICKER_STUDY_URL` | Which server to use. Default `https://study.wicker.life`. Use `http://localhost:4177` for a local development server; plain http is refused for anything else. |
+| `WICKER_STUDY_API_KEY` | Use this key instead of the saved one. Always wins, so a one-off run and CI never pick up a developer's saved key. |
+
+## Where the key lives
+
+`~/.config/wicker-study/config.json`, mode `0600` in a `0700` directory, keyed by server URL so a
+local and a production key never overwrite each other. `wicker_sign_out` removes it. Revoke the key
+itself under **Account → API access** in the web app.
+
+The key is never printed, never a tool argument, and never sent to a host other than the one it was
+minted for. Wicker Study will only deliver it to a loopback address, so a link that asks for
+anything else is refused by the approval page.
+
+## Canvas
+
+Canvas material is reached through the account's own encrypted connection, not through the agent.
+Call `canvas_connect` first: it reports whether the account has a Canvas connection and, if not,
+returns the page where the student pastes their Canvas Personal Access Token — in their browser.
+
+**Never ask a user for a Canvas token, password, MFA code, cookie, or session export in chat.** The
+agent receives proxied course data and nothing else.
+
+## Tools
+
+`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`,
+  `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`
+- **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`
+- **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`
+- **Editorial (admin key)** — the `admin_*` family: course editions, source folders, rights review,
+  extraction, mapping, generation, artifact review, and publication.
+
+`GET /api/agent/manifest` (also exposed as the `wicker-study://manifest` resource) is the
+authoritative list of endpoints and scopes.
+
+## Licence
+
+MIT.

package/authorize.mjs

@@ -0,0 +1,132 @@
+// Getting a key without putting one in a chat transcript.
+//
+// The agent opens a listener bound to loopback, sends the user to /connect with
+// a verifier challenge and that listener's address, and waits. The browser
+// approves; Wicker Study redirects back to loopback with a single-use code; the
+// agent exchanges code + verifier for a key and stores it globally.
+//
+// The key therefore travels browser → loopback → disk. It is never printed,
+// never passed as a tool argument, and never leaves the machine that asked for
+// it — Wicker Study refuses any callback that is not loopback.
+
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+import { createServer } from 'node:http'
+import { saveApiKey } from './config.mjs'
+
+export const AUTHORIZE_TIMEOUT_MS = 5 * 60_000
+
+function base64url(bytes) { return bytes.toString('base64url') }
+
+function sameSecret(left, right) {
+  const a = Buffer.from(String(left || ''))
+  const b = Buffer.from(String(right || ''))
+  return a.length === b.length && a.length > 0 && timingSafeEqual(a, b)
+}
+
+function page(title, body) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title><style>
+    body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#f7f7f4;color:#20263a;
+      font:400 15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+    main{max-width:420px;padding:32px;background:#fff;border:1px solid #dfe2ea;border-radius:12px;text-align:center}
+    h1{margin:0 0 8px;font-size:19px;letter-spacing:-.02em}p{margin:0;color:#59627b;font-size:13.5px}
+  </style></head><body><main><h1>${title}</h1><p>${body}</p></main></body></html>`
+}
+
+// Bound to 127.0.0.1 explicitly so nothing on the network can reach it. The
+// caller needs the address straight away and the code much later, so the two
+// are handed back as separate promises.
+export function startCallbackListener({ timeoutMs = AUTHORIZE_TIMEOUT_MS } = {}) {
+  const state = base64url(randomBytes(24))
+  let resolveCode
+  let rejectCode
+  const code = new Promise((resolve, reject) => { resolveCode = resolve; rejectCode = reject })
+  let settled = false
+
+  const server = createServer((req, res) => {
+    const url = new URL(req.url || '/', 'http://127.0.0.1')
+    if (url.pathname !== '/callback') { res.writeHead(404).end(); return }
+    if (!sameSecret(url.searchParams.get('state') || '', state)) {
+      res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' })
+      res.end(page('That did not match', 'This response did not come from the authorization this agent started. Nothing has been saved.'))
+      return
+    }
+    const failure = url.searchParams.get('error')
+    const value = url.searchParams.get('code')
+    res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+    res.end(failure || !value
+      ? page('Authorization cancelled', 'Nothing was granted. You can close this tab and try again from your agent.')
+      : page('Wicker Study is connected', 'You can close this tab and go back to your agent.'))
+    settle(failure ? new Error('The authorization was cancelled in the browser.') : null, value)
+  })
+
+  function settle(error, value) {
+    if (settled) return
+    settled = true
+    clearTimeout(timer)
+    setTimeout(() => server.close(), 250).unref?.()
+    if (error) rejectCode(error); else resolveCode(value)
+  }
+
+  const timer = setTimeout(() => settle(new Error(`No response within ${Math.round(timeoutMs / 60_000)} minutes. Start the authorization again.`)), timeoutMs)
+  timer.unref?.()
+  server.once('error', (error) => settle(error))
+
+  const address = new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address()
+      resolve({ port, redirectUri: `http://127.0.0.1:${port}/callback`, state })
+    })
+  })
+
+  return { address, code, state, cancel: () => settle(new Error('The authorization was cancelled.')) }
+}
+
+export function authorizationUrl(serverUrl, { name, scopes, challenge, state, redirectUri }) {
+  const url = new URL('/connect', serverUrl)
+  url.searchParams.set('name', name)
+  url.searchParams.set('scopes', scopes.join(','))
+  url.searchParams.set('challenge', challenge)
+  url.searchParams.set('state', state)
+  url.searchParams.set('redirect_uri', redirectUri)
+  return url.toString()
+}
+
+export function makeVerifier() {
+  const verifier = base64url(randomBytes(32))
+  return { verifier, challenge: createHash('sha256').update(verifier).digest('base64url') }
+}
+
+export async function exchange(serverUrl, { code, verifier }) {
+  const response = await fetch(new URL('/api/agent/authorize/exchange', serverUrl), {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({ code, verifier })
+  })
+  const body = await response.json().catch(() => null)
+  if (!response.ok) throw new Error(body?.error || `The authorization could not be completed (HTTP ${response.status}).`)
+  if (!body?.apiKey) throw new Error('Wicker Study returned no API key.')
+  return body
+}
+
+// The whole flow. Returns the loopback URL to show the user immediately, and a
+// promise that settles when they have finished in the browser.
+export function beginAuthorization(serverUrl, { name = 'Agent (MCP)', scopes = ['read', 'write'], timeoutMs = AUTHORIZE_TIMEOUT_MS } = {}) {
+  const { verifier, challenge } = makeVerifier()
+  const listener = startCallbackListener({ timeoutMs })
+  const ready = listener.address.then((address) => ({
+    url: authorizationUrl(serverUrl, { name, scopes, challenge, state: address.state, redirectUri: address.redirectUri }),
+    redirectUri: address.redirectUri
+  }))
+  const completed = (async () => {
+    await ready
+    const granted = await exchange(serverUrl, { code: await listener.code, verifier })
+    const saved = await saveApiKey(serverUrl, granted.apiKey, granted)
+    return { ...saved, name: granted.name, scopes: granted.scopes, expiresAt: granted.expiresAt }
+  })()
+  // The caller may only await this much later, or never (the user walked away).
+  // Keep an unobserved rejection from taking the process down; the rejection is
+  // still delivered to whoever does await it.
+  completed.catch(() => {})
+  return { ready, completed, cancel: listener.cancel }
+}

package/config.mjs

@@ -0,0 +1,109 @@
+// Where an authorised key lives once the agent has one.
+//
+// Keys are stored per server URL, so a developer pointing at localhost and the
+// same person pointing at study.wicker.life do not overwrite each other, and so
+// a key is never sent to a host it was not minted for. The file is written
+// 0600 and its directory 0700; the key never appears in a shell history, a
+// project directory, or a chat transcript.
+
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+export function configDirectory(env = process.env) {
+  const explicit = String(env.WICKER_STUDY_CONFIG_DIR || '').trim()
+  if (explicit) return explicit
+  const xdg = String(env.XDG_CONFIG_HOME || '').trim()
+  return join(xdg || join(homedir(), '.config'), 'wicker-study')
+}
+
+export function configPath(env = process.env) {
+  return join(configDirectory(env), 'config.json')
+}
+
+export function normaliseServerUrl(value) {
+  const raw = String(value || '').trim()
+  if (!raw) throw new Error('A Wicker Study URL is required.')
+  let url
+  try { url = new URL(raw) } catch { throw new Error(`"${raw}" is not a valid Wicker Study URL.`) }
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('A Wicker Study URL must be http or https.')
+  // http is only sensible against a local development server; anything else
+  // would put a bearer key on the wire in clear text.
+  if (url.protocol === 'http:' && !['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)) {
+    throw new Error(`Refusing to use http for ${url.hostname}. Use https, or point at a local development server.`)
+  }
+  return url.origin
+}
+
+async function readConfig(env = process.env) {
+  try {
+    const parsed = JSON.parse(await readFile(configPath(env), 'utf8'))
+    return parsed && typeof parsed === 'object' && parsed.servers && typeof parsed.servers === 'object' ? parsed : { servers: {} }
+  } catch {
+    return { servers: {} }
+  }
+}
+
+async function writeConfig(config, env = process.env) {
+  const path = configPath(env)
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 })
+  await chmod(dirname(path), 0o700).catch(() => {})
+  // Write-then-rename so an interrupted save cannot leave a truncated file, and
+  // set the mode before the content is in place at its final name.
+  const temporary = `${path}.${process.pid}.tmp`
+  await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  await chmod(temporary, 0o600).catch(() => {})
+  await rename(temporary, path)
+}
+
+export async function savedApiKey(serverUrl, env = process.env) {
+  const config = await readConfig(env)
+  const entry = config.servers[normaliseServerUrl(serverUrl)]
+  return entry && typeof entry.apiKey === 'string' && entry.apiKey ? entry.apiKey : null
+}
+
+export async function saveApiKey(serverUrl, apiKey, details = {}, env = process.env) {
+  const origin = normaliseServerUrl(serverUrl)
+  const key = String(apiKey || '').trim()
+  if (!key.startsWith('wsk_')) throw new Error('That does not look like a Wicker Study API key (they start with wsk_).')
+  const config = await readConfig(env)
+  config.servers[origin] = {
+    apiKey: key,
+    name: details.name || null,
+    scopes: Array.isArray(details.scopes) ? details.scopes : null,
+    expiresAt: details.expiresAt || null,
+    savedAt: new Date().toISOString()
+  }
+  await writeConfig(config, env)
+  return { server: origin, path: configPath(env) }
+}
+
+export async function forgetApiKey(serverUrl, env = process.env) {
+  const origin = normaliseServerUrl(serverUrl)
+  const config = await readConfig(env)
+  if (!config.servers[origin]) return false
+  delete config.servers[origin]
+  await writeConfig(config, env)
+  return true
+}
+
+export async function listSavedServers(env = process.env) {
+  const config = await readConfig(env)
+  // Never return the key itself — only that one exists and what it can do.
+  return Object.entries(config.servers).map(([server, entry]) => ({
+    server,
+    name: entry?.name || null,
+    scopes: entry?.scopes || null,
+    savedAt: entry?.savedAt || null,
+    expiresAt: entry?.expiresAt || null
+  }))
+}
+
+// The environment always wins, so a one-off `WICKER_STUDY_API_KEY=… npx …`
+// still works and CI never picks up a developer's saved key by accident.
+export async function resolveApiKey(serverUrl, env = process.env) {
+  const fromEnv = String(env.WICKER_STUDY_API_KEY || '').trim()
+  if (fromEnv) return { apiKey: fromEnv, source: 'environment' }
+  const stored = await savedApiKey(serverUrl, env)
+  return stored ? { apiKey: stored, source: configPath(env) } : { apiKey: null, source: null }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "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"],
+  "license": "MIT",
+  "author": "David Wicker",
+  "homepage": "https://study.wicker.life",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/davidwickerhf/exam-study-platform.git",
+    "directory": "mcp"
+  },
+  "bugs": "https://github.com/davidwickerhf/exam-study-platform/issues",
+  "type": "module",
+  "bin": {
+    "wicker-study-mcp": "./server.mjs"
+  },
+  "main": "./server.mjs",
+  "engines": {
+    "node": ">=20.11"
+  },
+  "files": [
+    "server.mjs",
+    "config.mjs",
+    "authorize.mjs",
+    "vendor/",
+    "scripts/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.76"
+  }
+}

package/scripts/macos-keychain.swift

@@ -0,0 +1,79 @@
+import Foundation
+import Security
+
+struct KeychainRequest: Decodable {
+  let operation: String
+  let service: String
+  let account: String
+  let value: String?
+}
+
+struct KeychainResponse: Encodable {
+  let found: Bool
+  let value: String?
+}
+
+func write(_ response: KeychainResponse) {
+  guard let data = try? JSONEncoder().encode(response) else { exit(1) }
+  FileHandle.standardOutput.write(data)
+}
+
+func fail(_ status: OSStatus) -> Never {
+  let text = SecCopyErrorMessageString(status, nil) as String? ?? "Keychain error \(status)"
+  FileHandle.standardError.write(Data(text.utf8))
+  exit(1)
+}
+
+let input = FileHandle.standardInput.readDataToEndOfFile()
+guard let request = try? JSONDecoder().decode(KeychainRequest.self, from: input),
+      !request.service.isEmpty,
+      !request.account.isEmpty else {
+  FileHandle.standardError.write(Data("Invalid Keychain request".utf8))
+  exit(1)
+}
+
+func baseQuery() -> [String: Any] {
+  [
+    kSecClass as String: kSecClassGenericPassword,
+    kSecAttrService as String: request.service,
+    kSecAttrAccount as String: request.account
+  ]
+}
+
+switch request.operation {
+case "get":
+  var query = baseQuery()
+  query[kSecReturnData as String] = true
+  query[kSecMatchLimit as String] = kSecMatchLimitOne
+  var result: CFTypeRef?
+  let status = SecItemCopyMatching(query as CFDictionary, &result)
+  if status == errSecItemNotFound {
+    write(KeychainResponse(found: false, value: nil))
+  } else if status == errSecSuccess, let data = result as? Data {
+    write(KeychainResponse(found: true, value: String(data: data, encoding: .utf8)))
+  } else {
+    fail(status)
+  }
+case "set":
+  guard let value = request.value, !value.isEmpty else {
+    FileHandle.standardError.write(Data("A Keychain value is required".utf8))
+    exit(1)
+  }
+  let deleteStatus = SecItemDelete(baseQuery() as CFDictionary)
+  if deleteStatus != errSecSuccess && deleteStatus != errSecItemNotFound { fail(deleteStatus) }
+  var query = baseQuery()
+  query[kSecValueData as String] = Data(value.utf8)
+  query[kSecAttrLabel as String] = "Wicker Study Canvas token (\(request.account))"
+  query[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
+  let status = SecItemAdd(query as CFDictionary, nil)
+  if status == errSecSuccess { write(KeychainResponse(found: true, value: nil)) }
+  else { fail(status) }
+case "delete":
+  let status = SecItemDelete(baseQuery() as CFDictionary)
+  if status == errSecSuccess { write(KeychainResponse(found: true, value: nil)) }
+  else if status == errSecItemNotFound { write(KeychainResponse(found: false, value: nil)) }
+  else { fail(status) }
+default:
+  FileHandle.standardError.write(Data("Unknown Keychain operation".utf8))
+  exit(1)
+}