infinitecampus-mcp: Instructions file for Claude Code

infinitecampus-mcp

MCP server for Infinite Campus (Campus Parent portal). Single-account config; linked districts are auto-discovered via CUPS SSO after primary login. Stdio transport, 20 tools across academics, daily life, documents, messaging, and a credential/district healthcheck.

Commands

npm run build        # tsc → dist/ + esbuild bundle → dist/bundle.js
npm run bundle       # esbuild only (skip tsc)
npm run dev          # node --env-file=.env dist/index.js (requires built dist/)
npm test             # tsc typecheck + vitest run (all tests)
npm run test:watch   # vitest in watch mode

dist/ is gitignored; CI rebuilds it and npm publish ships it via the files array in package.json. Rebuild locally before publishing or verifying end-to-end.

Tool naming

All tools are prefixed ic_ (e.g. ic_list_grades, ic_get_schedule). Every per-student tool takes district as its first arg; use ic_list_districts to get valid names.

Response shape (view)

src/view.ts holds this server's rung vocabulary (compact | full, defaulting to compact) over viewParam/resolveView/stripMediaUrls/minifiedResult from @chrischall/mcp-utils. All 18 read tools (readOnlyHint: true) take view and answer through viewResponse; ic_download_document does not — it is a write (destructiveHint) whose response is a receipt with nothing to strip. It delivers by route: local + no inline → the confined disk write (client.download, unchanged); hosted (isHostedEnv) or inline: true → client.fetchDocument (same origin fence, timeout and 50 MB cap, no disk) and deliverFile from @chrischall/mcp-utils/export with NO disk route, so a hosted runner never writes a file nobody can open: a signed blob link (documents/<uuid>/<name>), else inline ≤ 10 MiB, else too_large. ic_list_assignments alone also honours brief (its own enum, not IC_VIEWS): one line per assignment, <assignmentName> — due <dueDate> | no date — <missing|ok>, built only from fields this repo already reads, cut to ≤ 120 chars title-first (briefLine in src/view.ts). Names are teacher-written, so the lines ride in the untrusted-data envelope as data: string[] (untrustedBriefResponse). A line starting with -- is a note, not an item: nothing matched is exactly ["-- none"], an unreadable payload is -- error: …, and a name that itself starts with -- or \ gets one leading \.