infinitecampus-mcp 2.3.5 → 2.4.0

package/dist/tools/foodservice.js

@@ -1,5 +1,6 @@
+import { textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { textContent, is404, featureDisabled, findStudent, studentNotFound, checkFeatureDisabled } from './_shared.js';
+import { is404, featureDisabled, findStudent, studentNotFound, checkFeatureDisabled } from './_shared.js';
 const argsSchema = z.object({
     district: z.string(),
     studentId: z.string(),
@@ -27,7 +28,7 @@ export function registerFoodServiceTools(server, client) {
             params.set('endDate', args.until);
         try {
             const data = await client.request(args.district, `/campus/resources/portal/foodService?${params}`);
-            return textContent(data);
+            return textResult(data);
         }
         catch (e) {
             if (is404(e))

package/dist/tools/grades.js

@@ -1,5 +1,5 @@
+import { textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { textContent } from './_shared.js';
 const argsSchema = z.object({
     district: z.string(),
     studentId: z.string(),
@@ -16,6 +16,6 @@ export function registerGradeTools(server, client) {
         if (args.termId)
             params.set('termID', args.termId);
         const data = await client.request(args.district, `/campus/resources/portal/grades?${params}`);
-        return textContent(data);
+        return textResult(data);
     });
 }

package/dist/tools/messages.js

@@ -1,6 +1,7 @@
+import { textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
 import { extractPlainTextFromHtml } from '@chrischall/mcp-utils/html';
-import { textContent, toArray } from './_shared.js';
+import { toArray } from './_shared.js';
 const listArgs = z.object({
     district: z.string(),
     limit: z.number().int().positive().describe('Number of prism notifications to retrieve (default 20). Does not affect inbox or announcements.').optional(),
@@ -95,7 +96,7 @@ export function registerMessageTools(server, client) {
             return { count: 0, items: [], error: e instanceof Error ? e.message : String(e) };
         });
         const [notifications, inbox, announcements] = await Promise.all([prismPromise, inboxPromise, noticePromise]);
-        return textContent({ notifications, inbox, announcements });
+        return textResult({ notifications, inbox, announcements });
     });
     server.registerTool('ic_get_message', {
         description: "Fetch the HTML body of an inbox message and return it parsed into { subject, date, body, url }. Takes a `messageUrl` which is the `url` field from an item returned by ic_list_messages' inbox section (e.g. 'portal/messageView.xsl?x=messenger.MessengerEngine-getMessageRecipientView&messageID=...'). Relative and /campus/-prefixed URLs are both accepted. Note: fetching the HTML body may mark the message as read on some district configurations; probe against an empty inbox could not confirm the side effect.",
@@ -106,6 +107,6 @@ export function registerMessageTools(server, client) {
         const path = normalizeMessageUrl(args.messageUrl);
         const html = await client.request(args.district, path, { responseType: 'text' });
         const parsed = parseMessageHtml(html ?? '', path);
-        return textContent(parsed);
+        return textResult(parsed);
     });
 }

package/dist/tools/recent_grades.js

@@ -1,5 +1,5 @@
+import { textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { textContent } from './_shared.js';
 const argsSchema = z.object({
     district: z.string(),
     studentId: z.string(),
@@ -34,6 +34,6 @@ export function registerRecentGradesTools(server, client) {
             }
             return out;
         });
-        return textContent(trimmed);
+        return textResult(trimmed);
     });
 }

package/dist/tools/schedule.js

@@ -1,5 +1,5 @@
+import { textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { textContent } from './_shared.js';
 const argsSchema = z.object({
     district: z.string().describe('District name from ic_list_districts'),
     studentId: z.string().describe('Student personID from ic_list_students'),
@@ -15,6 +15,6 @@ export function registerScheduleTools(server, client) {
         const args = argsSchema.parse(rawArgs);
         const params = new URLSearchParams({ personID: args.studentId });
         const data = await client.request(args.district, `/campus/resources/portal/roster?${params}`);
-        return textContent(data);
+        return textResult(data);
     });
 }

package/dist/tools/students.js

@@ -1,5 +1,5 @@
+import { textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { textContent } from './_shared.js';
 const argsSchema = z.object({
     district: z.string().describe('District name from ic_list_districts'),
 });
@@ -11,6 +11,6 @@ export function registerStudentTools(server, client) {
     }, async (rawArgs) => {
         const args = argsSchema.parse(rawArgs);
         const data = await client.request(args.district, '/campus/api/portal/students');
-        return textContent(data);
+        return textResult(data);
     });
 }

package/dist/tools/teachers.js

@@ -1,5 +1,6 @@
+import { textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
-import { textContent, is404, toArray } from './_shared.js';
+import { is404, toArray } from './_shared.js';
 const argsSchema = z.object({
     district: z.string(),
     studentId: z.string(),
@@ -41,6 +42,6 @@ export function registerTeacherTools(server, client) {
         const [teachersRaw, counselorsRaw] = await Promise.all([teachersPromise, counselorsPromise]);
         const teachers = toArray(teachersRaw).map((t) => trimRecord(t));
         const counselors = toArray(counselorsRaw).map((c) => trimRecord(c));
-        return textContent({ counselors, teachers });
+        return textResult({ counselors, teachers });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.3.5",
+  "version": "2.4.0",
   "mcpName": "io.github.chrischall/infinitecampus-mcp",
   "description": "Infinite Campus (Campus Parent) MCP server — multi-district read + message/document write",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -42,19 +42,19 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.10.3",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
-    "node-html-parser": "^8.0.2",
+    "node-html-parser": "^9.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.7"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/infinitecampus-mcp",
     "source": "github"
   },
-  "version": "2.3.5",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "infinitecampus-mcp",
-      "version": "2.3.5",
+      "version": "2.4.0",
       "transport": {
         "type": "stdio"
       },

package/skills/infinitecampus-api/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: infinitecampus-api
+description: >-
+  Query an Infinite Campus (Campus Parent portal) district directly with curl
+  instead of running the infinitecampus-mcp server — log in with a real
+  username/password, capture the session cookie + XSRF token, and curl grades,
+  attendance, assignments, schedule, messages, documents, and fees. Use when
+  you want IC data without the MCP, in a script, or on a machine where the MCP
+  isn't installed. Infinite Campus is per-district: the base URL and district
+  app name are configurable, not hardcoded.
+---
+
+# Infinite Campus via curl (no MCP)
+
+Infinite Campus's Campus Parent portal is a classic server-rendered site
+(no public API, no bot wall). A plain form POST to `verify.jsp` logs a
+parent in and hands back a session cookie — no browser bridge needed. This
+is the same login `infinitecampus-mcp`'s `src/client.ts`/`src/auth.ts` do;
+this skill reproduces it with `curl` + a cookie jar.
+
+**Infinite Campus is per-district.** Every parent's portal lives at their
+own district's host (`https://campus.<district>.k12.example.us` or similar)
+under an `appName` path segment. There is no shared IC endpoint — carry the
+base URL and district from the same config the MCP uses:
+
+```sh
+: "${IC_BASE_URL:?set to your district's portal URL, e.g. https://campus.yourdistrict.org}"
+: "${IC_DISTRICT:?set to the appName path segment, e.g. yourdistrict}"
+: "${IC_USERNAME:?parent portal username}"
+: "${IC_PASSWORD:?parent portal password}"
+```
+
+(Same 4 env vars the MCP reads — reuse the repo's `.env` or the host's
+secret store; don't hardcode a district.)
+
+## One-time setup
+
+None — `curl` and `jq` are the only tools needed (`brew install jq` if
+missing). No profile/pairing step, no extension.
+
+## Login (capture cookies + XSRF token)
+
+`verify.jsp` accepts a urlencoded form POST and returns 200 with an
+`<AUTHENTICATION>state</AUTHENTICATION>` marker in the body — **not**
+via HTTP status — plus ~20 `Set-Cookie` headers. Use a cookie jar so curl
+does the Set-Cookie parsing/deduping for you:
+
+```sh
+JAR=$(mktemp)
+BODY=$(curl -sS -c "$JAR" \
+  "$IC_BASE_URL/campus/verify.jsp?nonBrowser=true" \
+  --data-urlencode "username=$IC_USERNAME" \
+  --data-urlencode "password=$IC_PASSWORD" \
+  --data-urlencode "appName=$IC_DISTRICT" \
+  --data-urlencode "portalLoginPage=parents")
+
+echo "$BODY" | grep -o '<AUTHENTICATION>[^<]*' # AUTHENTICATIONsuccess = good
+```
+
+`password-error` / `account-locked` / any non-`success` state means the
+login failed — check that string before doing anything else. Credentials
+go in the form body (never the query string — it lands in access logs).
+
+Pull the XSRF token out of the jar (IC's JS reads it back and echoes it on
+every request as `X-XSRF-TOKEN`; `JSESSIONID` alone is not enough):
+
+```sh
+XSRF=$(awk -F'\t' '$6=="XSRF-TOKEN"{print $7}' "$JAR")
+```
+
+## Core call pattern
+
+Every subsequent request rides the jar + the XSRF header:
+
+```sh
+ic_get() { # ic_get <path-with-query>
+  curl -sS -b "$JAR" -H "X-XSRF-TOKEN: $XSRF" -H 'Accept: application/json' \
+    "$IC_BASE_URL$1"
+}
+
+ic_get '/campus/api/portal/students' | jq .
+```
+
+A **401** means the session expired (IC sessions last ~5-6h) — re-run the
+Login step to get a fresh `$JAR`/`$XSRF` and retry once. There is no retry
+budget beyond that in this shell version (the MCP's `CookieSessionManager`
+does this automatically; here just redo the login block).
+
+## The one rule: resolve student + enrollment first
+
+Almost every read is scoped to a `personID` (student), and several need the
+student's **enrollment** (`enrollmentID` / `calendarID` / `structureID`).
+Always start with:
+
+```sh
+ic_get '/campus/api/portal/students' | jq '.[] | {personID, firstName, lastName, enrollments}'
+```
+
+Take `personID` for `studentId`/`personID` params, and the first (or
+relevant) `enrollments[]` entry's `enrollmentID`/`calendarID`/`structureID`
+for the endpoints that need them (attendance, school days, assessments,
+features). There is no name→id search — `ic_list_students` (i.e. this call)
+*is* the resolve step.
+
+## Endpoints
+
+All 17 read endpoints (grades, attendance, assignments, schedule, messages,
+documents, fees, teachers, assessments, feature flags) with ready-to-run
+`curl`+`jq` recipes are in `references/endpoints.md`. Two (`behavior`,
+`food_service`) have real paths that were never confirmed live against a
+district with that module enabled — try them, expect a 404 if the module
+is off or the district's shape differs.
+
+## Downloads
+
+`ic_download_document`'s `url` field (from the documents list) may be a
+relative `/campus/...` path or an absolute URL. Same jar + header pattern,
+just write to a file instead of piping to `jq`:
+
+```sh
+curl -sS -b "$JAR" -H "X-XSRF-TOKEN: $XSRF" -o report-card.pdf "$IC_BASE_URL$DOC_URL"
+```
+
+## FeatureDisabled districts
+
+Some districts turn whole modules off (behavior, food service, assessments,
+documents, attendance). The MCP checks `displayOptions` first and falls
+back to treating a 404 as "disabled." Doing the same by hand: fetch
+`/campus/api/portal/displayOptions/{structureID}?personID=X` (see
+references) and check the flag before assuming a 404 is a bug.
+
+## Notes
+
+- Read-only in practice: every recipe here is a GET. `ic_get_message`
+  fetching a message body *may* mark it read on some district configs — the
+  MCP's own probe couldn't confirm the side effect either way.
+- No CUPS linked-district switching in this skill (a parent with kids in
+  2+ IC instances under shared SSO) — that's a multi-step token-exchange
+  flow (`src/client.ts`'s `discoverLinkedDistricts`); out of scope here.
+  Run the login flow again against the linked district's own
+  `IC_BASE_URL`/`IC_DISTRICT` if you need it.
+- This project is developed and maintained by AI (Claude).

package/skills/infinitecampus-api/references/endpoints.md

@@ -0,0 +1,225 @@
+# Infinite Campus endpoints for curl
+
+Assumes the Login block from `../SKILL.md` has already run (`$JAR`, `$XSRF`,
+`$IC_BASE_URL` set) and the `ic_get` helper is defined:
+
+```sh
+ic_get() { curl -sS -b "$JAR" -H "X-XSRF-TOKEN: $XSRF" -H 'Accept: application/json' "$IC_BASE_URL$1"; }
+```
+
+All paths are transcribed from `infinitecampus-mcp`'s `src/tools/*.ts` and
+`docs/endpoints.md` — the same requests the `ic_*` MCP tools make. `$PID` =
+a student's `personID` from the resolve-first step.
+
+Some IC/prism responses serialize a 1-item collection as a bare object
+instead of a 1-element array — pipe through `jq 'if type=="array" then . else [.] end'`
+if a recipe below assumes an array and you get an object back.
+
+---
+
+## Students (resolve-first — always start here)
+
+```sh
+ic_get '/campus/api/portal/students' \
+  | jq '.[] | {personID, firstName, lastName, enrollments}'
+```
+
+Each `enrollments[]` entry carries `enrollmentID`, `calendarID`,
+`structureID`, `schoolName`, `endDate` — needed by several endpoints below.
+
+## Schedule
+
+```sh
+ic_get "/campus/resources/portal/roster?personID=$PID" | jq .
+```
+
+(Only `personID` is honored server-side — no working date/term filter, even
+though the MCP tool's schema accepts `date`/`termFilter` args.)
+
+## Assignments
+
+```sh
+# all assignments (full term history, ~hundreds of rows)
+ic_get "/campus/api/portal/assignment/listView?personID=$PID" | jq .
+
+# scoped to one course (sectionID from the schedule call above)
+ic_get "/campus/api/portal/assignment/listView?personID=$PID&sectionID=$SECTION_ID" | jq .
+
+# client-side filters (server ignores date/missing params entirely):
+ic_get "/campus/api/portal/assignment/listView?personID=$PID" \
+  | jq --arg since 2026-01-01 '[.[] | select(.dueDate >= $since)]'
+```
+
+## Recent (recently-graded) assignments
+
+Server-side filtered by `modifiedDate` (defaults to 14 days ago in the MCP;
+reproduce with `date -u -v-14d '+%Y-%m-%dT00:00:00'` on macOS):
+
+```sh
+SINCE=$(date -u -v-14d '+%Y-%m-%dT00:00:00')
+ic_get "/campus/api/portal/assignment/recentlyScored?modifiedDate=$SINCE&personID=$PID" | jq .
+```
+
+## Grades
+
+```sh
+ic_get "/campus/resources/portal/grades?personID=$PID" | jq .
+# scoped to one term:
+ic_get "/campus/resources/portal/grades?personID=$PID&termID=$TERM_ID" | jq .
+```
+
+## Attendance (per-course summary, loop over each enrollment)
+
+```sh
+ic_get "/campus/resources/portal/attendance/$ENROLLMENT_ID?courseSummary=true&personID=$PID" \
+  | jq '.terms[]?.courses[]? | {absentList, tardyList, presentList, earlyReleaseList}'
+```
+
+Feature-gated: check `displayOptions.attendance` first (see Feature flags,
+below) — a 404 here on a district with attendance disabled is expected, not
+a bug.
+
+## Attendance events (individual absences/tardies, loop over each enrollment)
+
+```sh
+ic_get "/campus/resources/portal/attendance/events?enrollmentID=$ENROLLMENT_ID&personID=$PID" \
+  | jq '.events[]? | {date: .localDate, code, description, excuse, comments}'
+
+# excused-only, since a date (client-side filter):
+ic_get "/campus/resources/portal/attendance/events?enrollmentID=$ENROLLMENT_ID&personID=$PID" \
+  | jq --arg since 2026-01-01 '[.events[]? | select((.localDate[0:10] >= $since) and (.excuse == "E"))]'
+```
+
+## School days / calendar (loop over each enrollment)
+
+Two calls per enrollment, then join term windows to days client-side:
+
+```sh
+ic_get "/campus/resources/term?structureID=$STRUCTURE_ID" | jq .          # term boundaries
+ic_get "/campus/resources/calendar/instructionalDay?calendarID=$CALENDAR_ID" | jq .  # day list
+
+# days within term N's [startDate,endDate]:
+jq --slurpfile terms terms.json --arg t "$TERM_ID" \
+  '[.[] | select(.date >= $terms[0][0].startDate and .date <= $terms[0][0].endDate)]' days.json
+```
+
+## Assessments (standardized tests, loop over each enrollment)
+
+```sh
+ic_get "/campus/resources/prism/portal/assessments?personID=$PID&calendarID=$CALENDAR_ID" \
+  | jq '{stateTests, nationalTests, districtTests}'
+```
+
+Feature-gated on `displayOptions.assessment`; test-item shape varies by
+district/test type — pass through unchanged, don't assume field names
+beyond `stateTests`/`nationalTests`/`districtTests`.
+
+## Behavior *(path unconfirmed — never verified live against a district with the module on)*
+
+```sh
+ic_get "/campus/resources/portal/behavior?personID=$PID" | jq .
+# with a date range:
+ic_get "/campus/resources/portal/behavior?personID=$PID&startDate=2026-01-01&endDate=2026-06-01" | jq .
+```
+
+Feature-gated on `displayOptions.behavior` — a 404 is the expected result
+on most districts (few enable this module for parent portal).
+
+## Food service *(path unconfirmed — same caveat as behavior)*
+
+```sh
+ic_get "/campus/resources/portal/foodService?personID=$PID" | jq .
+ic_get "/campus/resources/portal/foodService?personID=$PID&startDate=2026-01-01&endDate=2026-06-01" | jq .
+```
+
+Feature-gated on `displayOptions.foodService`.
+
+## Documents + download
+
+```sh
+ic_get "/campus/resources/portal/report/all?personID=$PID" \
+  | jq '.[] | {name, type, url, moduleLabel, endYear}'
+
+# download (url may be relative /campus/... or an absolute URL — handle both):
+DOC_URL='/campus/resources/portal/report/...'   # from the .url field above
+curl -sS -b "$JAR" -H "X-XSRF-TOKEN: $XSRF" -o report-card.pdf \
+  "$( [[ "$DOC_URL" == http* ]] && echo "$DOC_URL" || echo "$IC_BASE_URL$DOC_URL" )"
+```
+
+Feature-gated on `displayOptions.documents`.
+
+## Teachers + counselors
+
+```sh
+ic_get "/campus/resources/portal/section/contacts?personID=$PID" | jq .
+ic_get "/campus/resources/portal/studentCounselor/byUser?personID=$PID" | jq .
+```
+
+Either endpoint 404ing is treated as "no results" (not FeatureDisabled) by
+the MCP — do the same.
+
+## Messages (three independent sources — combine client-side)
+
+```sh
+# 1. prism notifications (assignment/grade/attendance alerts)
+ic_get '/campus/prism?x=notifications.Notification-retrieve&limitCount=20' \
+  | jq '.data.NotificationList.Notification'
+
+# 2. Messenger 2.0 inbox (teacher messages, district announcements)
+ic_get '/campus/api/portal/process-message' | jq .
+
+# 3. portal userNotice announcements
+ic_get '/campus/resources/portal/userNotice' | jq .
+```
+
+Each inbox item's `url` field feeds `ic_get_message` below (normalize a bare
+or `portal/...`-relative URL to `/campus/portal/...` first).
+
+## Get one message body (HTML → text)
+
+```sh
+# normalize: bare "portal/..." → "/campus/portal/..."; already-absolute /campus/... stays as-is
+MSG_PATH='/campus/portal/messageView.xsl?x=messenger.MessengerEngine-getMessageRecipientView&messageID=...&messageRecipientID=...'
+curl -sS -b "$JAR" -H "X-XSRF-TOKEN: $XSRF" -H 'Accept: text/html' "$IC_BASE_URL$MSG_PATH"
+# then strip tags/entities yourself, or eyeball the rendered HTML — this is
+# an HTML fragment, not JSON, so `jq` doesn't apply.
+```
+
+Fetching a message body *may* mark it read on some district configs
+(unconfirmed either way).
+
+## Fees (two endpoints in parallel; either can 404 independently)
+
+```sh
+ic_get "/campus/api/portal/fees/feeAssignments?personID=$PID" | jq .
+ic_get "/campus/api/portal/fees/feeTransactionDetail/totalSurplus/-1?personID=$PID" | jq .
+```
+
+Both 404 → module is off for this district. One 404 → report the other
+side plus a note that the failing endpoint may be disabled.
+
+## Feature flags (displayOptions — check before assuming a 404 is a bug)
+
+```sh
+ic_get "/campus/api/portal/displayOptions/$STRUCTURE_ID?personID=$PID" \
+  | jq '{attendance, behavior, assessment, documents, foodService, grades, schedule}'
+```
+
+`false` = district has that module turned off for this enrollment; `true`
+or absent = available. ~90 flags total; the MCP caches this per
+`(district, structureID)` for the session lifetime since it rarely changes
+mid-session — worth doing the same if you're calling it more than once.
+
+---
+
+## Not covered here (out of scope for this skill)
+
+- **CUPS linked-district discovery/switching** — a parent with kids at 2+
+  IC-hosted districts under shared SSO. Multi-step: fetch
+  `cups/linkedAccounts`, `userAccountSwitch/originalDistrict`,
+  `districts/current`, then per linked account a `cups/loginToken` POST
+  followed by a second `verify.jsp`-style POST at the *linked* district's
+  own host with the CUPS token. Fully discoverable in `src/client.ts`
+  (`discoverLinkedDistricts`) but a lot of shell for a one-shot skill —
+  just re-run the Login block against the linked district's own
+  `IC_BASE_URL`/`IC_DISTRICT` instead.