infinitecampus-mcp 2.6.0 → 2.7.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Infinite Campus (Campus Parent) — grades, attendance, assignments, messages, documents",
-    "version": "2.6.0"
+    "version": "2.7.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Infinite Campus",
       "source": "./",
       "description": "Infinite Campus (Campus Parent) MCP server for Claude — grades, attendance, assignments, messages, and documents via natural language",
-      "version": "2.6.0",
+      "version": "2.7.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "infinitecampus-mcp",
   "displayName": "Infinite Campus",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Infinite Campus (Campus Parent) MCP server for Claude — grades, attendance, assignments, messages, and documents",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -8,7 +8,7 @@ MCP server for Infinite Campus (Campus Parent portal). Single-account config —
 
 ## Tools
 
-19 tools across academics, daily life, documents, messaging, and feature discovery.
+20 tools across academics, daily life, documents, messaging, feature discovery, and a credential/district healthcheck.
 
 | Domain | Tools |
 |---|---|

package/dist/bundle.js

@@ -34682,6 +34682,7 @@ var StdioServerTransport = class {
 };
 
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
+var DEFAULT_ERROR_MESSAGE_MAX = 500;
 var McpToolError = class extends Error {
   /** Actionable remediation text, when one applies. */
   hint;
@@ -34720,6 +34721,18 @@ var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*('
 function redactSecrets(text) {
   return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
 }
+function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
+  const str = text === null || text === void 0 ? "" : String(text);
+  const redacted = redactSecrets(str);
+  if (redacted.length <= max)
+    return redacted;
+  return `${redacted.slice(0, max)}\u2026 [truncated]`;
+}
+function messageOf(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
@@ -39015,6 +39028,118 @@ var BootstrapDisabledError = class extends Error {
   }
 };
 
+// node_modules/@chrischall/mcp-utils/dist/healthcheck/index.js
+function statusOf(err) {
+  if (typeof err !== "object" || err === null)
+    return void 0;
+  const s = err.status ?? err.statusCode;
+  return typeof s === "number" ? s : void 0;
+}
+function credentialHint(arm, prefix, hostLabel, source2) {
+  switch (arm) {
+    case "ok":
+      return `Credential from '${source2}' works: ${hostLabel} accepted an authenticated request. If a real tool still fails, the problem is that tool, not auth.`;
+    case "no_credential":
+      return `No credential resolved. Nothing was available to authenticate with \u2014 sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
+    case "credential_rejected":
+      return `${hostLabel} rejected the credential from '${source2}'. It is present but no longer valid \u2014 most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
+    case "timeout":
+      return `The credential from '${source2}' resolved, but ${hostLabel} did not answer in time. Usually transient \u2014 retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
+    case "http":
+      return `${hostLabel} answered with an error status that is not an auth rejection. That is USUALLY a ${hostLabel}-side problem rather than an auth one \u2014 but a 404 here more often means the probe path is wrong than that ${hostLabel} is broken, so check error.message and probe.url before concluding anything about the credential.`;
+    case "transport":
+      return `Could not reach ${hostLabel} at all. Check network egress; the credential itself was never judged.`;
+    default:
+      return `Unexpected failure \u2014 see error.message.`;
+  }
+}
+function registerCredentialHealthcheckTool(args) {
+  const { server, prefix, hostLabel, probePath, resolveCredential, probeFn, classifyThrown, hints } = args;
+  const probeUrl = probePath ? `https://${hostLabel}${probePath}` : void 0;
+  server.registerTool(`${prefix}_healthcheck`, {
+    title: "Verify credentials and upstream reachability",
+    description: `Resolves the credential the way real tools do, then makes one authenticated request to ${hostLabel}. Reports which source supplied the credential, whether ${hostLabel} accepted it, the round-trip time, and a plain-English hint distinguishing 'no credential' from 'credential rejected' from 'a ${hostLabel}-side problem'. Call this when a real tool fails and you want to know which hop broke. Read-only; never returns the credential itself.`,
+    annotations: {
+      title: "Verify credentials and upstream reachability",
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: true
+    },
+    inputSchema: {}
+  }, async () => {
+    let probeStarted = 0;
+    let state;
+    try {
+      state = await resolveCredential();
+    } catch (e) {
+      const result2 = {
+        ok: false,
+        credential: { source: null, resolved: false },
+        // No `url`: nothing was probed, and naming one implies it was tried.
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: truncateErrorMessage(messageOf(e)) },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    const credential = {
+      source: state.source,
+      resolved: state.source !== null,
+      ...state.detail !== void 0 ? { detail: state.detail } : {}
+    };
+    if (!credential.resolved) {
+      const result2 = {
+        ok: false,
+        credential,
+        probe: { elapsed_ms: 0 },
+        error: { kind: "no_credential", message: "no credential source resolved" },
+        hint: hints?.no_credential ?? credentialHint("no_credential", prefix, hostLabel, null)
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
+    }
+    let arm = "ok";
+    let error51;
+    let status;
+    let customHint;
+    probeStarted = Date.now();
+    try {
+      await probeFn();
+    } catch (e) {
+      status = statusOf(e);
+      const aborted2 = e instanceof Error && e.name === "AbortError";
+      arm = status === 401 || status === 403 ? "credential_rejected" : status !== void 0 ? "http" : aborted2 || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e)) ? "timeout" : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e)) ? "transport" : "unknown";
+      let kind = arm;
+      let detail;
+      const custom2 = classifyThrown?.(e);
+      if (custom2) {
+        kind = custom2.kind;
+        customHint = custom2.hint;
+        detail = custom2.detail;
+      }
+      error51 = {
+        kind,
+        // Redacted AND bounded before it reaches the result: an upstream
+        // failure routinely quotes what it was sent, and a healthcheck is
+        // the tool people paste into a chat when something is broken.
+        message: truncateErrorMessage(messageOf(e)),
+        ...detail !== void 0 ? { detail } : {}
+      };
+    }
+    const result = {
+      ok: error51 === void 0,
+      credential,
+      probe: {
+        ...probeUrl ? { url: probeUrl } : {},
+        elapsed_ms: Date.now() - probeStarted,
+        ...status !== void 0 ? { status } : {}
+      },
+      ...error51 ? { error: error51 } : {},
+      hint: customHint ?? hints?.[arm] ?? credentialHint(arm, prefix, hostLabel, state.source)
+    };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  });
+}
+
 // src/config.ts
 function readVar(env, key) {
   return readEnvVar(key, { env });
@@ -39056,7 +39181,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "infinitecampus-mcp",
-  version: "2.6.0",
+  version: "2.7.0",
   mcpName: "io.github.chrischall/infinitecampus-mcp",
   description: "Infinite Campus (Campus Parent) MCP server \u2014 multi-district read + message/document write",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -39101,7 +39226,7 @@ var package_default = {
     typecheck: "tsc -p tsconfig.json --noEmit"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.18.0",
+    "@chrischall/mcp-utils": "^0.19.2",
     "@fetchproxy/bootstrap": "^2.2.0",
     "@fetchproxy/server": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -40125,6 +40250,50 @@ function registerDistrictTools(server, client) {
   });
 }
 
+// src/tools/healthcheck.ts
+function registerHealthcheckTools(server, state) {
+  registerCredentialHealthcheckTool({
+    server,
+    prefix: "ic",
+    hostLabel: "your Infinite Campus portal",
+    resolveCredential: async () => {
+      if (!state.account || !state.client) {
+        throw state.configError ?? new Error("Infinite Campus is not configured.");
+      }
+      const detail = {
+        base_url: state.account.baseUrl,
+        configured_district: state.account.district,
+        auth_source: state.source ?? "unknown"
+      };
+      try {
+        await state.client.ensureDiscovery();
+        const districts = state.client.listDistricts();
+        detail.districts = districts.map((d) => ({ name: d.name, linked: d.linked }));
+        const linked = districts.filter((d) => d.linked).map((d) => d.name);
+        detail.configured_district_is_linked = districts.some(
+          (d) => d.name === state.account.district && d.linked
+        );
+        if (linked.length > 0) detail.linked_districts = linked;
+      } catch {
+        detail.districts = "unavailable (discovery needs a live session)";
+      }
+      return { source: state.source ?? "env", detail };
+    },
+    // Probe the district the account is actually LINKED to when that differs
+    // from the configured one — probing a district you are not enrolled in
+    // fails for a reason that has nothing to do with your credentials.
+    probeFn: () => {
+      const districts = state.client.listDistricts();
+      const linked = districts.find((d) => d.linked);
+      const district = linked?.name ?? state.account.district;
+      return state.client.request(district, "/campus/api/portal/students");
+    },
+    hints: {
+      credential_rejected: "Infinite Campus rejected the credentials. Check IC_USERNAME/IC_PASSWORD, or sign into your IC portal in the browser so the fetchproxy fallback can lift a session."
+    }
+  });
+}
+
 // src/tools/students.ts
 var argsSchema = external_exports.object({
   district: external_exports.string().describe("District name from ic_list_districts")
@@ -41018,12 +41187,15 @@ try {
 }
 var COMMON = {
   name: "infinitecampus",
-  version: "2.6.0"
+  version: "2.7.0"
   // x-release-please-version
 };
+var healthState = { account, source, configError, client: null };
 if (account) {
   const client = new ICClient(account, { refreshSession });
+  healthState.client = client;
   const tools = [
+    (server) => registerHealthcheckTools(server, healthState),
     registerDistrictTools,
     registerStudentTools,
     registerScheduleTools,
@@ -41049,6 +41221,10 @@ ${AI_NOTICE}` });
 } else {
   const notConfigured = `[infinitecampus-mcp] Not configured: ${configError?.message ?? "unknown error"}
 [infinitecampus-mcp] Server is running with no tools registered. Set the required env vars and reinstall.`;
-  await runMcp({ ...COMMON, tools: [], banner: `${notConfigured}
-${AI_NOTICE}` });
+  await runMcp({
+    ...COMMON,
+    tools: [(server) => registerHealthcheckTools(server, healthState)],
+    banner: `${notConfigured}
+${AI_NOTICE}`
+  });
 }

package/dist/index.js

@@ -14,6 +14,7 @@ await loadDotenvSafely({
 import { resolveAuth } from './auth.js';
 import { ICClient } from './client.js';
 import { registerDistrictTools } from './tools/districts.js';
+import { registerHealthcheckTools } from './tools/healthcheck.js';
 import { registerStudentTools } from './tools/students.js';
 import { registerScheduleTools } from './tools/schedule.js';
 import { registerAssignmentTools } from './tools/assignments.js';
@@ -57,11 +58,16 @@ catch (e) {
 // actionable stderr message (banner) instead of a crash loop.
 const COMMON = {
     name: 'infinitecampus',
-    version: '2.6.0', // x-release-please-version
+    version: '2.7.0', // x-release-please-version
 };
+// Shared with the healthcheck so it can report the SAME state the tools see,
+// including on the unconfigured path where there are no tools at all.
+const healthState = { account, source, configError, client: null };
 if (account) {
     const client = new ICClient(account, { refreshSession });
+    healthState.client = client;
     const tools = [
+        (server) => registerHealthcheckTools(server, healthState),
         registerDistrictTools,
         registerStudentTools,
         registerScheduleTools,
@@ -87,5 +93,13 @@ if (account) {
 else {
     const notConfigured = `[infinitecampus-mcp] Not configured: ${configError?.message ?? 'unknown error'}\n` +
         '[infinitecampus-mcp] Server is running with no tools registered. Set the required env vars and reinstall.';
-    await runMcp({ ...COMMON, tools: [], banner: `${notConfigured}\n${AI_NOTICE}` });
+    // NOT `tools: []` any more. A server that registers nothing explains itself
+    // only on stderr, which a hosted connector never sees — so a misconfigured
+    // server was indistinguishable from a broken one. The healthcheck is the one
+    // tool that must survive this path, because this is the path that needs it.
+    await runMcp({
+        ...COMMON,
+        tools: [(server) => registerHealthcheckTools(server, healthState)],
+        banner: `${notConfigured}\n${AI_NOTICE}`,
+    });
 }

package/dist/tools/healthcheck.js

@@ -0,0 +1,62 @@
+import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
+/**
+ * Register `ic_healthcheck` — reports which auth path resolved and which
+ * districts the account is actually LINKED to, then makes one authenticated
+ * call.
+ *
+ * REGISTERED UNCONDITIONALLY. When `IC_BASE_URL`/`IC_DISTRICT` are missing,
+ * `index.ts` registers zero tools and reports the reason on stderr only —
+ * invisible to a hosted connector, so a misconfigured server looks like a
+ * broken one.
+ *
+ * The district detail is the specific thing that cost real debugging time
+ * here: a configured `IC_DISTRICT` the account is NOT linked to fails every
+ * tool with an unrelated-looking error, while `ic_list_districts` quietly
+ * shows `linked: false` next to a different district that works. Surfacing
+ * "configured X, linked to Y" turns that into one glance.
+ */
+export function registerHealthcheckTools(server, state) {
+    registerCredentialHealthcheckTool({
+        server,
+        prefix: 'ic',
+        hostLabel: 'your Infinite Campus portal',
+        resolveCredential: async () => {
+            if (!state.account || !state.client) {
+                throw state.configError ?? new Error('Infinite Campus is not configured.');
+            }
+            const detail = {
+                base_url: state.account.baseUrl,
+                configured_district: state.account.district,
+                auth_source: state.source ?? 'unknown',
+            };
+            try {
+                // Discovery is what knows about LINKED districts, and it needs a live
+                // session — so a failure here is not a credential answer. Report what
+                // is known and let the probe below decide.
+                await state.client.ensureDiscovery();
+                const districts = state.client.listDistricts();
+                detail.districts = districts.map((d) => ({ name: d.name, linked: d.linked }));
+                const linked = districts.filter((d) => d.linked).map((d) => d.name);
+                detail.configured_district_is_linked = districts.some((d) => d.name === state.account.district && d.linked);
+                if (linked.length > 0)
+                    detail.linked_districts = linked;
+            }
+            catch {
+                detail.districts = 'unavailable (discovery needs a live session)';
+            }
+            return { source: state.source ?? 'env', detail };
+        },
+        // Probe the district the account is actually LINKED to when that differs
+        // from the configured one — probing a district you are not enrolled in
+        // fails for a reason that has nothing to do with your credentials.
+        probeFn: () => {
+            const districts = state.client.listDistricts();
+            const linked = districts.find((d) => d.linked);
+            const district = linked?.name ?? state.account.district;
+            return state.client.request(district, '/campus/api/portal/students');
+        },
+        hints: {
+            credential_rejected: 'Infinite Campus rejected the credentials. Check IC_USERNAME/IC_PASSWORD, or sign into your IC portal in the browser so the fetchproxy fallback can lift a session.',
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.6.0",
+  "version": "2.7.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>",
@@ -45,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.18.0",
+    "@chrischall/mcp-utils": "^0.19.2",
     "@fetchproxy/bootstrap": "^2.2.0",
     "@fetchproxy/server": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/server.json

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

package/skills/ic/SKILL.md

@@ -5,7 +5,7 @@ description: This skill should be used when the user asks about Infinite Campus
 
 # infinitecampus-mcp
 
-MCP server for Infinite Campus (Campus Parent portal) — 19 tools covering schedule, grades (current + recently-scored), assignments, attendance (summary + per-event), behavior, food service, documents, messages (3 sources), teachers, assessments, and fees. Linked districts are auto-discovered via CUPS SSO after primary login.
+MCP server for Infinite Campus (Campus Parent portal) — 20 tools covering schedule, grades (current + recently-scored), assignments, attendance (summary + per-event), behavior, food service, documents, messages (3 sources), teachers, assessments, and fees. Linked districts are auto-discovered via CUPS SSO after primary login.
 
 - **Source:** [github.com/chrischall/infinitecampus-mcp](https://github.com/chrischall/infinitecampus-mcp)
 - **npm:** [npmjs.com/package/infinitecampus-mcp](https://www.npmjs.com/package/infinitecampus-mcp)
@@ -89,7 +89,14 @@ mcporter call ic.<tool_name> [key=value ...] --config ~/.mcporter/mcporter.json
 
 Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter.json` exists.
 
-Every tool except `ic_list_districts` takes `district` as its first arg (the district name from `ic_list_districts`). Most student-scoped tools also take `studentId` (the personID from `ic_list_students`).
+Every tool except `ic_list_districts` takes `district` as its first arg (the district name from `ic_list_districts`).
+
+`ic_healthcheck` takes no args and is the exception worth knowing: it is
+registered even when the server is unconfigured (every other tool is not), and
+it reports whether the configured `IC_DISTRICT` is one the account is actually
+LINKED to. A district you are not linked to fails every other tool for a reason
+that looks nothing like "wrong district", so run this first when things fail
+inexplicably. Most student-scoped tools also take `studentId` (the personID from `ic_list_students`).
 
 ## Tools