@mtgibbs/canvas-lms-mcp 0.2.2 → 0.2.8

package/esm/src/api/courses.d.ts

@@ -17,6 +17,7 @@ export declare function listCourseEnrollments(courseId: number, options?: {
     type?: string[];
     state?: string[];
     userId?: number | string;
+    include?: string[];
 }): Promise<Enrollment[]>;
 /**
  * Get enrollment with grades for a specific user in a course
@@ -25,6 +26,9 @@ export declare function getUserEnrollment(courseId: number, userId: number | str
 /**
  * List courses with grades for a user (observer or self)
  * Enriches course data with enrollment/grade information
+ *
+ * For observer accounts querying a specific student, this fetches
+ * the student's enrollment separately to get their actual grades.
  */
 export declare function listCoursesWithGrades(userId?: string | number): Promise<(Course & {
     enrollment?: Enrollment;

package/esm/src/api/courses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"courses.d.ts","sourceRoot":"","sources":["../../../src/src/api/courses.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjF;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmB3E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B,GACA,OAAO,CAAC,UAAU,EAAE,CAAC,CAgBvB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAO5B;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,GAAE,MAAM,GAAG,MAAe,GAC/B,OAAO,CAAC,CAAC,MAAM,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,EAAE,CAAC,CAyBnD"}
+{"version":3,"file":"courses.d.ts","sourceRoot":"","sources":["../../../src/src/api/courses.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEjF;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmB3E;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB,GACA,OAAO,CAAC,UAAU,EAAE,CAAC,CAmBvB;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GAAG,MAAM,GACtB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAO5B;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,GAAE,MAAM,GAAG,MAAe,GAC/B,OAAO,CAAC,CAAC,MAAM,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC,EAAE,CAAC,CAmDnD"}

package/esm/src/api/courses.js

@@ -34,7 +34,10 @@ export function getCourse(courseId) {
  */
 export function listCourseEnrollments(courseId, options) {
     const client = getClient();
-    const params = {};
+    const params = {
+        // Always include grades when fetching enrollments
+        include: options?.include || ["grades"],
+    };
     if (options?.type) {
         params.type = options.type;
     }
@@ -59,6 +62,9 @@ export async function getUserEnrollment(courseId, userId) {
 /**
  * List courses with grades for a user (observer or self)
  * Enriches course data with enrollment/grade information
+ *
+ * For observer accounts querying a specific student, this fetches
+ * the student's enrollment separately to get their actual grades.
  */
 export async function listCoursesWithGrades(userId = "self") {
     // Get all active courses with enrollments included
@@ -67,14 +73,35 @@ export async function listCoursesWithGrades(userId = "self") {
         include: ["enrollments", "term"],
         state: ["available"],
     });
-    // Filter and enrich with the specific user's enrollment data
+    // If querying for a specific student (not "self"), we need to fetch
+    // the student's enrollment separately since the courses endpoint
+    // only returns the observer's enrollment for parent accounts
+    const isObserverQuery = userId !== "self" && !isNaN(Number(userId));
+    if (isObserverQuery) {
+        // Fetch student enrollments with grades in parallel
+        const enrollmentPromises = courses.map(async (course) => {
+            try {
+                const enrollments = await listCourseEnrollments(course.id, {
+                    userId: Number(userId),
+                    type: ["StudentEnrollment"],
+                });
+                return { courseId: course.id, enrollment: enrollments[0] || null };
+            }
+            catch {
+                return { courseId: course.id, enrollment: null };
+            }
+        });
+        const enrollmentResults = await Promise.all(enrollmentPromises);
+        const enrollmentMap = new Map(enrollmentResults.map((r) => [r.courseId, r.enrollment]));
+        return courses.map((course) => ({
+            ...course,
+            enrollment: enrollmentMap.get(course.id) || undefined,
+        }));
+    }
+    // For "self" queries, use the enrollment from the courses response
     const coursesWithGrades = courses.map((course) => {
-        // Find the enrollment for this user (or observed user)
         const enrollment = course.enrollments?.find((e) => {
-            if (userId === "self") {
-                return e.type === "StudentEnrollment" || e.type === "ObserverEnrollment";
-            }
-            return e.user_id === Number(userId) || e.observed_user?.id === Number(userId);
+            return e.type === "StudentEnrollment" || e.type === "ObserverEnrollment";
         });
         return {
             ...course,

package/esm/src/mcp/tools/get-courses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-courses.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/get-courses.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;CAElB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,OAAO,MAAM,CASxD,CAAC"}
+{"version":3,"file":"get-courses.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/get-courses.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;CAKlB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,OAAO,MAAM,CAWxD,CAAC"}

package/esm/src/mcp/tools/get-courses.js

@@ -4,17 +4,22 @@
  */
 import { z } from "zod";
 import { getCourses } from "../../services/index.js";
+import { getEffectiveStudentId } from "../../api/users.js";
 import { jsonResponse } from "../types.js";
 export const schema = {
-    student_id: z.string().optional().describe("Student ID (default: 'self')"),
+    student_id: z
+        .string()
+        .optional()
+        .describe("Student ID (uses configured CANVAS_STUDENT_ID if not provided)"),
 };
 export const getCoursesTool = {
     name: "get_courses",
-    description: "List all active courses and current grades for the student",
+    description: "List all active courses with current cumulative grades (score percentages). Use this to get an overview of the student's course load and overall academic standing. For observer/parent accounts, this fetches the observed student's grades, not the observer's. Returns course name, code, and current score percentage.",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ student_id }) => {
-        const courses = await getCourses({ studentId: student_id || "self" });
+        const effectiveStudentId = await getEffectiveStudentId(student_id);
+        const courses = await getCourses({ studentId: String(effectiveStudentId) });
         return jsonResponse(courses);
     },
 };

package/esm/src/mcp/tools/get-due-this-week.js

@@ -24,7 +24,7 @@ export const schema = {
 };
 export const getDueThisWeekTool = {
     name: "get_due_this_week",
-    description: "Get all assignments due in the next N days across ALL courses for a student, with submission status",
+    description: "Get all assignments due in the next N days across ALL courses at once. This is the recommended tool for questions like 'what's due this week?' or 'what homework do I have?'. Returns assignment name, course, due date, points, and whether it's been submitted. By default hides already-graded items to focus on pending work.",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ student_id, days, hide_graded }) => {

package/esm/src/mcp/tools/get-missing-assignments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-missing-assignments.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/get-missing-assignments.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;;CAGlB,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,cAAc,CAAC,OAAO,MAAM,CAanE,CAAC"}
+{"version":3,"file":"get-missing-assignments.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/get-missing-assignments.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;;CAMlB,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,cAAc,CAAC,OAAO,MAAM,CAenE,CAAC"}

package/esm/src/mcp/tools/get-missing-assignments.js

@@ -4,19 +4,24 @@
  */
 import { z } from "zod";
 import { getMissingAssignments } from "../../services/index.js";
+import { getEffectiveStudentId } from "../../api/users.js";
 import { jsonResponse } from "../types.js";
 export const schema = {
-    student_id: z.string().optional().describe("Student ID (default: 'self')"),
+    student_id: z
+        .string()
+        .optional()
+        .describe("Student ID (uses configured CANVAS_STUDENT_ID if not provided)"),
     course_id: z.number().optional().describe("Filter by specific course ID"),
 };
 export const getMissingAssignmentsTool = {
     name: "get_missing_assignments",
-    description: "Get missing assignments for a student (Canvas-flagged as missing)",
+    description: "Get assignments that Canvas has officially flagged as 'missing'. These are past-due assignments where the teacher has marked them missing. NOTE: This may not catch all unsubmitted work - use get_unsubmitted_past_due for assignments that are past due but not yet flagged by the teacher. Use both tools together for a complete picture of outstanding work.",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ student_id, course_id }) => {
+        const effectiveStudentId = await getEffectiveStudentId(student_id);
         const missing = await getMissingAssignments({
-            studentId: student_id || "self",
+            studentId: String(effectiveStudentId),
             courseId: course_id,
         });
         return jsonResponse(missing);

package/esm/src/mcp/tools/get-recent-grades.js

@@ -27,7 +27,7 @@ export const schema = {
 };
 export const getRecentGradesTool = {
     name: "get_recent_grades",
-    description: "Get recently graded assignments with scores. Can filter by date range and minimum grade threshold.",
+    description: "Get recently graded assignments with scores from the last N days (default 14). Shows assignment name, course, score, points possible, and percentage. Use below_percentage to filter for low grades (e.g., below_percentage=70 to find grades under 70%). Useful for questions like 'how did I do on recent tests?' or 'any bad grades lately?'",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ student_id, days, below_percentage, course_id }) => {

package/esm/src/mcp/tools/get-stats.js

@@ -19,7 +19,7 @@ export const schema = {
 };
 export const getStatsTool = {
     name: "get_stats",
-    description: "Get late and missing assignment statistics by course, showing percentages to identify problem areas",
+    description: "Get late and missing assignment statistics aggregated by course. Shows total assignments, late count, missing count, and percentages for each course. Use this to identify problem courses or answer questions like 'which class has the most missing work?' or 'how many late assignments do I have?'",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ student_id, hide_empty }) => {

package/esm/src/mcp/tools/get-todo.js

@@ -20,7 +20,7 @@ export const schema = {
 };
 export const getTodoTool = {
     name: "get_todo",
-    description: "Get the student's to-do list (planner items) showing upcoming assignments, quizzes, and tasks",
+    description: "Get the student's Canvas planner/to-do list showing upcoming assignments, quizzes, discussions, and tasks. This is what the student sees in their Canvas planner. Shows item type, due date, points, and submission status. Use hide_submitted=true to focus on incomplete items only.",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ student_id, days, hide_submitted }) => {

package/esm/src/mcp/tools/get-unsubmitted-past-due.js

@@ -18,7 +18,7 @@ export const schema = {
 };
 export const getUnsubmittedPastDueTool = {
     name: "get_unsubmitted_past_due",
-    description: "Get assignments that are past due but not submitted (catches items Canvas hasn't flagged as missing yet)",
+    description: "Get assignments that are past due but have no submission. This catches work that Canvas hasn't officially flagged as 'missing' yet (teachers may not have updated the status). Use this alongside get_missing_assignments for a complete picture of all outstanding/late work. Returns assignment name, course, due date, and points.",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ student_id, course_id }) => {

package/esm/src/mcp/tools/get-upcoming-assignments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-upcoming-assignments.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/get-upcoming-assignments.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;;CAGlB,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,cAAc,CAAC,OAAO,MAAM,CAapE,CAAC"}
+{"version":3,"file":"get-upcoming-assignments.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/get-upcoming-assignments.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;;CAGlB,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,cAAc,CAAC,OAAO,MAAM,CAcpE,CAAC"}

package/esm/src/mcp/tools/get-upcoming-assignments.js

@@ -11,7 +11,7 @@ export const schema = {
 };
 export const getUpcomingAssignmentsTool = {
     name: "get_upcoming_assignments",
-    description: "Get assignments due in the next N days for a single course",
+    description: "Get assignments due in the next N days for a SINGLE course. Requires course_id. Use this when asking about upcoming work in a specific class. For upcoming assignments across ALL courses at once, use get_due_this_week instead - it's more efficient for broad queries.",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ course_id, days }) => {

package/esm/src/mcp/tools/list-assignments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-assignments.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/list-assignments.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;;;CAOlB,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC,OAAO,MAAM,CAc7D,CAAC"}
+{"version":3,"file":"list-assignments.d.ts","sourceRoot":"","sources":["../../../../src/src/mcp/tools/list-assignments.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,eAAO,MAAM,MAAM;;;;CAOlB,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cAAc,CAAC,OAAO,MAAM,CAe7D,CAAC"}

package/esm/src/mcp/tools/list-assignments.js

@@ -15,7 +15,7 @@ export const schema = {
 };
 export const listAssignmentsTool = {
     name: "list_assignments",
-    description: "List assignments for a course with optional filtering",
+    description: "List assignments for a specific course with optional filtering by bucket (past, overdue, undated, ungraded, unsubmitted, upcoming, future). Use this for detailed assignment queries within a single course, like 'show me all overdue assignments in Math' or 'what assignments are ungraded in Science'. For simpler upcoming/due queries, prefer get_due_this_week.",
     schema,
     annotations: { readOnlyHint: true, openWorldHint: true },
     handler: async ({ course_id, bucket, search_term }) => {

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "canvas-lms-mcp",
   "display_name": "Canvas LMS",
-  "version": "0.2.2",
+  "version": "0.2.8",
   "description": "Connect Claude to your Canvas LMS account to query grades, assignments, missing work, and more.",
   "long_description": "An MCP server that connects AI assistants like Claude to your Canvas LMS account. Perfect for parents monitoring their child's academic progress, students tracking their own work, or anyone who wants to interact with Canvas data through natural language.\n\nAsk Claude things like:\n- What assignments are due this week?\n- Show me missing assignments across all classes\n- What's my grade in Biology?\n- Are there any late assignments I should know about?",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtgibbs/canvas-lms-mcp",
-  "version": "0.2.2",
+  "version": "0.2.8",
   "description": "Canvas LMS MCP (Model Context Protocol) server for AI assistants. Query student grades, assignments, and academic data through Claude or other MCP-compatible AI tools.",
   "keywords": [
     "mcp",