canvas-parent-mcp 1.4.0 → 1.5.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Canvas LMS (Instructure) — courses, grades, assignments, announcements, planner, conversations, files",
-    "version": "1.4.0"
+    "version": "1.5.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Canvas LMS",
       "source": "./",
       "description": "Canvas LMS (Instructure) MCP server for Claude — student/observer access via natural language",
-      "version": "1.4.0",
+      "version": "1.5.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canvas-parent-mcp",
   "displayName": "Canvas LMS",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Canvas LMS (Instructure) MCP server for Claude — courses, grades, assignments, announcements, planner, conversations, files",
   "author": {
     "name": "Chris Hall",

package/dist/bundle.js

@@ -34731,6 +34731,11 @@ function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_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) {
@@ -39237,7 +39242,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "canvas-parent-mcp",
-  version: "1.4.0",
+  version: "1.5.0",
   mcpName: "io.github.chrischall/canvas-parent-mcp",
   description: "Canvas LMS (Instructure) MCP server \u2014 student/observer read access with optional file download",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -39284,7 +39289,7 @@ var package_default = {
     typecheck: "tsc -p tsconfig.json --noEmit"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.17.1",
+    "@chrischall/mcp-utils": "^0.19.2",
     "@fetchproxy/bootstrap": "^2.2.0",
     "@fetchproxy/server": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -39392,6 +39397,118 @@ async function liftBrowserCookie(declaredDomain, baseHost) {
   }
 }
 
+// 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, source) {
+  switch (arm) {
+    case "ok":
+      return `Credential from '${source}' 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 '${source}'. 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 '${source}' 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/client.ts
 import { writeFile as writeFile3, stat } from "fs/promises";
 
@@ -40134,6 +40251,34 @@ var FileExistsError = class extends Error {
   path;
 };
 
+// src/tools/healthcheck.ts
+function registerHealthcheckTools(server, state) {
+  registerCredentialHealthcheckTool({
+    server,
+    prefix: "canvas",
+    hostLabel: "canvas",
+    probePath: "/api/v1/users/self/profile",
+    resolveCredential: async () => {
+      if (!state.resolved) {
+        throw state.configError ?? new Error("Canvas auth is not configured.");
+      }
+      return {
+        source: state.resolved.source,
+        detail: {
+          base_url: state.resolved.account.baseUrl,
+          mode: state.resolved.account.mode
+        }
+      };
+    },
+    probeFn: async () => {
+      const client = new CanvasClient(state.resolved.account, {
+        refreshSession: state.resolved.refresh
+      });
+      return client.request("/api/v1/users/self/profile");
+    }
+  });
+}
+
 // src/tools/_shared.ts
 var textContent = textResult;
 function buildPath(base, params = {}) {
@@ -40502,9 +40647,12 @@ try {
 }
 await runMcp({
   name: "canvas",
-  version: "1.4.0",
+  version: "1.5.0",
   // x-release-please-version
   tools: [
+    // Outside the `if (resolved)` on purpose: an unconfigured server must
+    // still expose something that can say WHY (see the tool's docblock).
+    (server) => registerHealthcheckTools(server, { resolved, configError }),
     (server) => {
       if (resolved) {
         const client = new CanvasClient(resolved.account, {

package/dist/index.js

@@ -8,6 +8,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // (bundled mcpb runtime) degrades to a silent no-op.
 await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
 import { resolveAuth } from './auth.js';
+import { registerHealthcheckTools } from './tools/healthcheck.js';
 import { CanvasClient } from './client.js';
 import { registerProfileTools } from './tools/profile.js';
 import { registerObserveeTools } from './tools/observees.js';
@@ -46,8 +47,11 @@ catch (e) {
 // host's install-time `tools/list` succeeds.
 await runMcp({
     name: 'canvas',
-    version: '1.4.0', // x-release-please-version
+    version: '1.5.0', // x-release-please-version
     tools: [
+        // Outside the `if (resolved)` on purpose: an unconfigured server must
+        // still expose something that can say WHY (see the tool's docblock).
+        (server) => registerHealthcheckTools(server, { resolved, configError }),
         (server) => {
             if (resolved) {
                 const client = new CanvasClient(resolved.account, {

package/dist/tools/healthcheck.js

@@ -0,0 +1,47 @@
+import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthcheck';
+import { CanvasClient } from '../client.js';
+/**
+ * Register `canvas_healthcheck` — reports which auth path resolved, then makes
+ * one authenticated call to `/api/v1/users/self/profile`.
+ *
+ * REGISTERED UNCONDITIONALLY, unlike every other tool here. The
+ * deferred-config-error pattern registers nothing when auth fails, so an
+ * unconfigured server exposes zero tools and explains itself only on stderr —
+ * which a hosted connector never sees. That makes "the connector has no tools"
+ * indistinguishable from "the connector is broken". This one tool always
+ * exists, so there is always something that can answer why.
+ *
+ * `/api/v1/users/self/profile` is the probe because it is the cheapest
+ * endpoint requiring valid auth — its own tool description calls it the
+ * "useful first call to confirm credentials".
+ */
+export function registerHealthcheckTools(server, state) {
+    registerCredentialHealthcheckTool({
+        server,
+        prefix: 'canvas',
+        hostLabel: 'canvas',
+        probePath: '/api/v1/users/self/profile',
+        resolveCredential: async () => {
+            if (!state.resolved) {
+                // The stored error names every accepted auth path, which is exactly
+                // the question being asked; surface it rather than a generic message.
+                throw state.configError ?? new Error('Canvas auth is not configured.');
+            }
+            return {
+                source: state.resolved.source,
+                detail: {
+                    base_url: state.resolved.account.baseUrl,
+                    mode: state.resolved.account.mode,
+                },
+            };
+        },
+        probeFn: async () => {
+            // Built here rather than passed in: with no credential the probe is
+            // skipped entirely, so there is nothing to construct on that path.
+            const client = new CanvasClient(state.resolved.account, {
+                refreshSession: state.resolved.refresh,
+            });
+            return client.request('/api/v1/users/self/profile');
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-parent-mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "mcpName": "io.github.chrischall/canvas-parent-mcp",
   "description": "Canvas LMS (Instructure) MCP server — student/observer read access with optional file download",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -47,7 +47,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.17.1",
+    "@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/canvas-parent-mcp",
     "source": "github"
   },
-  "version": "1.4.0",
+  "version": "1.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "canvas-parent-mcp",
-      "version": "1.4.0",
+      "version": "1.5.0",
       "transport": {
         "type": "stdio"
       },

package/skills/canvas-parent/SKILL.md

@@ -56,6 +56,7 @@ Precedence when multiple are set: `CANVAS_TOKEN` > username/password > OAuth > f
 
 ### Profile & observees
 - `canvas_get_profile` — your Canvas profile
+- `canvas_healthcheck` — which auth path resolved and whether Canvas accepts it; registered even when auth is unconfigured, so it can say why
 - `canvas_list_observees` — students linked to your observer account
 
 ### Courses