canvas-parent-mcp 1.3.1 → 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.3.1"
+    "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.3.1",
+      "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.3.1",
+  "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

@@ -3314,8 +3314,8 @@ var require_utils = __commonJS({
     var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
     var HOST_DELIM_RE = /[@/?#:]/g;
     var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
-    function reescapeHostDelimiters(host, isIP) {
-      const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+    function reescapeHostDelimiters(host, isIP2) {
+      const re = isIP2 ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
       re.lastIndex = 0;
       return host.replace(re, (ch) => HOST_DELIMS[ch]);
     }
@@ -3804,7 +3804,7 @@ var require_fast_uri = __commonJS({
         fragment: void 0
       };
       let malformedAuthorityOrPort = false;
-      let isIP = false;
+      let isIP2 = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
           uri = options.scheme + ":" + uri;
@@ -3853,9 +3853,9 @@ var require_fast_uri = __commonJS({
           if (ipv4result === false) {
             const ipv6result = normalizeIPv6(parsed.host);
             parsed.host = ipv6result.host.toLowerCase();
-            isIP = ipv6result.isIPV6;
+            isIP2 = ipv6result.isIPV6;
           } else {
-            isIP = true;
+            isIP2 = true;
           }
         }
         if (parsed.scheme === void 0 && parsed.userinfo === void 0 && parsed.host === void 0 && parsed.port === void 0 && parsed.query === void 0 && !parsed.path) {
@@ -3872,7 +3872,7 @@ var require_fast_uri = __commonJS({
         }
         const schemeHandler = getSchemeHandler(options.scheme || parsed.scheme);
         if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport)) {
-          if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
+          if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP2 === false && nonSimpleDomain(parsed.host)) {
             try {
               parsed.host = new URL("http://" + parsed.host).hostname;
             } catch (e) {
@@ -3886,7 +3886,7 @@ var require_fast_uri = __commonJS({
               parsed.scheme = unescape(parsed.scheme);
             }
             if (parsed.host !== void 0) {
-              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
+              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP2);
             }
           }
           if (parsed.path) {
@@ -7199,7 +7199,7 @@ var require_permessage_deflate = __commonJS({
       acceptAsServer(offers) {
         const opts = this._options;
         const accepted = offers.find((params) => {
-          if (opts.serverNoContextTakeover === false && params.server_no_context_takeover || params.server_max_window_bits && (opts.serverMaxWindowBits === false || typeof opts.serverMaxWindowBits === "number" && opts.serverMaxWindowBits > params.server_max_window_bits) || typeof opts.clientMaxWindowBits === "number" && !params.client_max_window_bits) {
+          if (opts.serverNoContextTakeover === false && params.server_no_context_takeover || params.server_max_window_bits && (opts.serverMaxWindowBits === false || typeof opts.serverMaxWindowBits === "number" && opts.serverMaxWindowBits > params.server_max_window_bits) || typeof opts.clientMaxWindowBits === "number" && (typeof params.client_max_window_bits === "number" ? opts.clientMaxWindowBits > params.client_max_window_bits : !params.client_max_window_bits)) {
             return false;
           }
           return true;
@@ -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) {
@@ -37096,6 +37101,7 @@ function classifyBridgeError(err) {
 }
 
 // node_modules/@fetchproxy/server/dist/ws-server.js
+import { isIP } from "node:net";
 function envWsPort() {
   const raw = process.env.FETCHPROXY_WS_PORT;
   if (raw === void 0 || raw.trim() === "")
@@ -37107,6 +37113,15 @@ function envWsPort() {
     return void 0;
   return port;
 }
+function envWsHost() {
+  const raw = process.env.FETCHPROXY_WS_HOST;
+  if (raw === void 0)
+    return void 0;
+  const host = raw.trim();
+  if (host === "" || isIP(host) === 0)
+    return void 0;
+  return host;
+}
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
     super(message);
@@ -37355,7 +37370,7 @@ var FetchproxyServer = class {
     }
     this.opts = {
       port: opts.port ?? envWsPort() ?? 37149,
-      host: opts.host ?? "127.0.0.1",
+      host: opts.host ?? envWsHost() ?? "127.0.0.1",
       serverName: opts.serverName,
       version: opts.version,
       domains: [...opts.domains],
@@ -37641,6 +37656,7 @@ var FetchproxyServer = class {
     return {
       role: this.role,
       port: this.opts.port,
+      host: this.opts.host,
       serverVersion: this.opts.version,
       fetchTimeoutMs: this.opts.fetchTimeoutMs ?? 0,
       bridgeReviveDelayMs: this.opts.bridgeReviveDelayMs ?? 0,
@@ -39226,7 +39242,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "canvas-parent-mcp",
-  version: "1.3.1",
+  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>",
@@ -39273,9 +39289,9 @@ var package_default = {
     typecheck: "tsc -p tsconfig.json --noEmit"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.17.1",
-    "@fetchproxy/bootstrap": "^2.0.0",
-    "@fetchproxy/server": "^2.0.0",
+    "@chrischall/mcp-utils": "^0.19.2",
+    "@fetchproxy/bootstrap": "^2.2.0",
+    "@fetchproxy/server": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
@@ -39381,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";
 
@@ -40123,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 = {}) {
@@ -40491,9 +40647,12 @@ try {
 }
 await runMcp({
   name: "canvas",
-  version: "1.3.1",
+  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.3.1', // 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.3.1",
+  "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,9 +47,9 @@
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.17.1",
-    "@fetchproxy/bootstrap": "^2.0.0",
-    "@fetchproxy/server": "^2.0.0",
+    "@chrischall/mcp-utils": "^0.19.2",
+    "@fetchproxy/bootstrap": "^2.2.0",
+    "@fetchproxy/server": "^2.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/canvas-parent-mcp",
     "source": "github"
   },
-  "version": "1.3.1",
+  "version": "1.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "canvas-parent-mcp",
-      "version": "1.3.1",
+      "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