canvas-agent 1.0.0

package/dist/tools/assignments.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { canvas, canvasAll, summarizeItem } from "../canvas-client.js";
+export function registerAssignmentTools(server) {
+    server.tool("list_assignments", "List assignments in a course. This includes regular assignments, graded discussions, and New Quizzes (which are all assignments internally). Returns summary info (id, name, dates, points). Use get_assignment for full details.", {
+        course_id: z.string().describe("Canvas course ID"),
+        search_term: z.string().optional().describe("Filter by name substring"),
+        assignment_group_id: z
+            .string()
+            .optional()
+            .describe("Filter to a specific assignment group"),
+        order_by: z
+            .enum(["due_at", "name", "position"])
+            .default("position")
+            .describe("Sort order"),
+    }, async ({ course_id, search_term, assignment_group_id, order_by }) => {
+        const params = { order_by };
+        if (search_term)
+            params.search_term = search_term;
+        if (assignment_group_id)
+            params.assignment_group_id = assignment_group_id;
+        const assignments = await canvasAll(`/courses/${course_id}/assignments`, params);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(assignments.map(summarizeItem), null, 2),
+                },
+            ],
+        };
+    });
+    server.tool("get_assignment", "Get full details of a single assignment, including its description/instructions.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+    }, async ({ course_id, assignment_id }) => {
+        const assignment = await canvas(`/courses/${course_id}/assignments/${assignment_id}`);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(assignment, null, 2) },
+            ],
+        };
+    });
+    server.tool("create_assignment", "Create a new regular assignment in a course. For graded discussions, use create_discussion with points_possible instead. For New Quizzes, use create_new_quiz instead.", {
+        course_id: z.string().describe("Canvas course ID"),
+        name: z.string().describe("Assignment name"),
+        description: z
+            .string()
+            .optional()
+            .describe("Instructions/description (HTML supported)"),
+        due_at: z.string().optional().describe("Due date (ISO 8601)"),
+        unlock_at: z
+            .string()
+            .optional()
+            .describe("Available from date (ISO 8601)"),
+        lock_at: z
+            .string()
+            .optional()
+            .describe("Available until date (ISO 8601)"),
+        points_possible: z.number().optional().describe("Point value"),
+        submission_types: z
+            .array(z.string())
+            .optional()
+            .describe("e.g. ['online_text_entry','online_upload','online_url','discussion_topic','external_tool']"),
+        assignment_group_id: z
+            .string()
+            .optional()
+            .describe("Assignment group ID to place it in"),
+        published: z.boolean().default(false).describe("Publish immediately"),
+        position: z.number().optional().describe("Position within the group"),
+    }, async ({ course_id, ...params }) => {
+        const result = await canvas(`/courses/${course_id}/assignments`, {
+            method: "POST",
+            body: JSON.stringify({ assignment: params }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Created assignment "${result.name}" (ID: ${result.id})\n${result.html_url}`,
+                },
+            ],
+        };
+    });
+    server.tool("update_assignment", "Update an existing assignment. Only include fields you want to change. Also works for graded discussions and New Quizzes (via their assignment_id). For date-only changes, prefer update_assignment_dates which is more focused.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+        name: z.string().optional(),
+        description: z.string().optional().describe("HTML instructions"),
+        due_at: z.string().optional().describe("ISO 8601 or empty string to clear"),
+        unlock_at: z.string().optional().describe("Available from (ISO 8601)"),
+        lock_at: z.string().optional().describe("Available until (ISO 8601)"),
+        points_possible: z.number().optional(),
+        submission_types: z.array(z.string()).optional().describe("e.g. ['online_text_entry','online_upload','online_url']"),
+        assignment_group_id: z.string().optional().describe("Group ID (use list_assignment_groups to find)"),
+        published: z.boolean().optional(),
+        position: z.number().optional(),
+    }, async ({ course_id, assignment_id, ...params }) => {
+        const result = await canvas(`/courses/${course_id}/assignments/${assignment_id}`, {
+            method: "PUT",
+            body: JSON.stringify({ assignment: params }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated "${result.name}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("delete_assignment", "Permanently delete an assignment. This cannot be undone.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+        confirm_name: z
+            .string()
+            .describe("Type the assignment name to confirm deletion (safety check)"),
+    }, async ({ course_id, assignment_id, confirm_name }) => {
+        // Verify the name matches before deleting
+        const assignment = await canvas(`/courses/${course_id}/assignments/${assignment_id}`);
+        if (assignment.name !== confirm_name) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Safety check failed: assignment name is "${assignment.name}" but you confirmed "${confirm_name}". Delete aborted.`,
+                    },
+                ],
+            };
+        }
+        await canvas(`/courses/${course_id}/assignments/${assignment_id}`, {
+            method: "DELETE",
+        });
+        return {
+            content: [
+                { type: "text", text: `Deleted assignment "${confirm_name}"` },
+            ],
+        };
+    });
+    server.tool("batch_update_assignments", "Update fields across multiple assignments at once. Does NOT support date fields — use batch_update_dates for date changes. Applies the same update to each assignment ID provided.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_ids: z
+            .array(z.string())
+            .describe("List of assignment IDs to update"),
+        updates: z
+            .object({
+            description: z.string().optional(),
+            points_possible: z.number().optional(),
+            submission_types: z.array(z.string()).optional(),
+            published: z.boolean().optional(),
+            assignment_group_id: z.string().optional(),
+        })
+            .describe("Fields to update on each assignment"),
+    }, async ({ course_id, assignment_ids, updates }) => {
+        const results = [];
+        for (const id of assignment_ids) {
+            try {
+                const result = await canvas(`/courses/${course_id}/assignments/${id}`, {
+                    method: "PUT",
+                    body: JSON.stringify({ assignment: updates }),
+                });
+                results.push(`  OK: "${result.name}" (${id})`);
+            }
+            catch (e) {
+                results.push(`  FAILED: ${id} — ${e.message}`);
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Batch update complete (${assignment_ids.length} assignments):\n${results.join("\n")}`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/calendar.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCalendarTools(server: McpServer): void;

package/dist/tools/calendar.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { canvas, canvasAll } from "../canvas-client.js";
+export function registerCalendarTools(server) {
+    server.tool("list_calendar_events", "List calendar events, optionally filtered by course, date range, or type.", {
+        course_id: z
+            .string()
+            .optional()
+            .describe("Filter to a specific course ID"),
+        start_date: z
+            .string()
+            .optional()
+            .describe("Start of date range (ISO 8601)"),
+        end_date: z
+            .string()
+            .optional()
+            .describe("End of date range (ISO 8601)"),
+        type: z
+            .enum(["event", "assignment"])
+            .optional()
+            .describe("Filter by event type"),
+    }, async ({ course_id, start_date, end_date, type }) => {
+        const params = {};
+        if (course_id)
+            params["context_codes[]"] = `course_${course_id}`;
+        if (start_date)
+            params.start_date = start_date;
+        if (end_date)
+            params.end_date = end_date;
+        if (type)
+            params.type = type;
+        const events = await canvasAll("/calendar_events", params);
+        const summary = events.map((e) => ({
+            id: e.id,
+            title: e.title,
+            start_at: e.start_at,
+            end_at: e.end_at,
+            description: e.description
+                ? e.description.substring(0, 200) +
+                    (e.description.length > 200 ? "..." : "")
+                : null,
+            location_name: e.location_name,
+            type: e.type,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("create_calendar_event", "Create a standalone calendar event (e.g. office hours, class sessions, review sessions). These are NOT assignments — to create graded items with due dates, use create_assignment.", {
+        course_id: z.string().describe("Canvas course ID"),
+        title: z.string().describe("Event title"),
+        start_at: z.string().describe("Start date/time (ISO 8601)"),
+        end_at: z.string().describe("End date/time (ISO 8601)"),
+        description: z
+            .string()
+            .optional()
+            .describe("Event description (HTML supported)"),
+        location_name: z.string().optional().describe("Location name"),
+        location_address: z.string().optional().describe("Location address"),
+    }, async ({ course_id, title, start_at, end_at, description, location_name, location_address }) => {
+        const result = await canvas("/calendar_events", {
+            method: "POST",
+            body: JSON.stringify({
+                calendar_event: {
+                    context_code: `course_${course_id}`,
+                    title,
+                    start_at,
+                    end_at,
+                    description,
+                    location_name,
+                    location_address,
+                },
+            }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Created calendar event "${result.title}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("update_calendar_event", "Update an existing calendar event. Only include fields you want to change.", {
+        event_id: z.string().describe("Calendar event ID"),
+        title: z.string().optional(),
+        start_at: z.string().optional().describe("ISO 8601"),
+        end_at: z.string().optional().describe("ISO 8601"),
+        description: z.string().optional().describe("HTML description"),
+        location_name: z.string().optional(),
+    }, async ({ event_id, ...params }) => {
+        const result = await canvas(`/calendar_events/${event_id}`, {
+            method: "PUT",
+            body: JSON.stringify({ calendar_event: params }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated calendar event "${result.title}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("delete_calendar_event", "Delete a calendar event.", {
+        event_id: z.string().describe("Calendar event ID"),
+    }, async ({ event_id }) => {
+        await canvas(`/calendar_events/${event_id}`, {
+            method: "DELETE",
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Deleted calendar event ${event_id}`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/courses.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCourseTools(server: McpServer): void;

package/dist/tools/courses.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { canvasAll } from "../canvas-client.js";
+export function registerCourseTools(server) {
+    server.tool("list_courses", "List Canvas courses you have access to. Returns course IDs needed by all other tools. Shows active courses by default.", {
+        enrollment_state: z
+            .enum(["active", "completed", "invited"])
+            .default("active")
+            .describe("Filter by enrollment state"),
+    }, async ({ enrollment_state }) => {
+        const courses = await canvasAll("/courses", {
+            enrollment_state,
+            include: "term",
+        });
+        const summary = courses.map((c) => ({
+            id: c.id,
+            name: c.name,
+            course_code: c.course_code,
+            term: c.term?.name,
+            workflow_state: c.workflow_state,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("list_assignment_groups", "List assignment groups (grading categories) in a course with their weights. The returned group IDs are used as assignment_group_id when creating or updating assignments.", { course_id: z.string().describe("Canvas course ID") }, async ({ course_id }) => {
+        const groups = await canvasAll(`/courses/${course_id}/assignment_groups`);
+        const summary = groups.map((g) => ({
+            id: g.id,
+            name: g.name,
+            position: g.position,
+            group_weight: g.group_weight,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("list_modules", "List modules in a course. For module management (create, update, delete, add items), see create_module, update_module, add_module_item, and related tools.", {
+        course_id: z.string().describe("Canvas course ID"),
+        include_items: z
+            .boolean()
+            .default(false)
+            .describe("Include module items in the response"),
+    }, async ({ course_id, include_items }) => {
+        const params = {};
+        if (include_items)
+            params.include = "items";
+        const modules = await canvasAll(`/courses/${course_id}/modules`, params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(modules, null, 2) }],
+        };
+    });
+}

package/dist/tools/discussions.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDiscussionTools(server: McpServer): void;

package/dist/tools/discussions.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { canvas, canvasAll } from "../canvas-client.js";
+export function registerDiscussionTools(server) {
+    server.tool("list_discussions", "List discussion topics in a course. Graded discussions also appear as assignments (with assignment_id in the response). To update dates or points of graded discussions, use update_assignment_dates or update_assignment with the assignment_id.", {
+        course_id: z.string().describe("Canvas course ID"),
+        search_term: z.string().optional().describe("Filter by title substring"),
+        only_announcements: z
+            .boolean()
+            .default(false)
+            .describe("Only return announcements"),
+    }, async ({ course_id, search_term, only_announcements }) => {
+        const params = {};
+        if (search_term)
+            params.search_term = search_term;
+        if (only_announcements)
+            params.only_announcements = "true";
+        const discussions = await canvasAll(`/courses/${course_id}/discussion_topics`, params);
+        const summary = discussions.map((d) => ({
+            id: d.id,
+            title: d.title,
+            due_at: d.assignment?.due_at ?? null,
+            unlock_at: d.assignment?.unlock_at ?? d.delayed_post_at,
+            lock_at: d.assignment?.lock_at ?? d.lock_at,
+            points_possible: d.assignment?.points_possible ?? null,
+            published: d.published,
+            discussion_type: d.discussion_type,
+            assignment_id: d.assignment_id,
+            html_url: d.html_url,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("get_discussion", "Get full details of a discussion topic, including its message/instructions.", {
+        course_id: z.string().describe("Canvas course ID"),
+        discussion_id: z.string().describe("Discussion topic ID"),
+    }, async ({ course_id, discussion_id }) => {
+        const discussion = await canvas(`/courses/${course_id}/discussion_topics/${discussion_id}`);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(discussion, null, 2) },
+            ],
+        };
+    });
+    server.tool("create_discussion", "Create a new graded or ungraded discussion topic.", {
+        course_id: z.string().describe("Canvas course ID"),
+        title: z.string().describe("Discussion title"),
+        message: z
+            .string()
+            .optional()
+            .describe("Discussion prompt/instructions (HTML)"),
+        discussion_type: z
+            .enum(["side_comment", "threaded"])
+            .default("threaded")
+            .describe("Comment style"),
+        published: z.boolean().default(false),
+        // Grading fields — if included, Canvas creates a linked assignment
+        points_possible: z
+            .number()
+            .optional()
+            .describe("If set, makes this a graded discussion"),
+        assignment_group_id: z.string().optional().describe("Group ID (use list_assignment_groups to find)"),
+        due_at: z.string().optional().describe("Due date (ISO 8601)"),
+        unlock_at: z.string().optional().describe("Available from (ISO 8601)"),
+        lock_at: z.string().optional().describe("Available until (ISO 8601)"),
+    }, async ({ course_id, points_possible, assignment_group_id, due_at, unlock_at, lock_at, ...params }) => {
+        const body = { ...params };
+        // If grading fields are provided, nest them under assignment
+        if (points_possible != null) {
+            body.assignment = {
+                points_possible,
+                assignment_group_id,
+                due_at,
+                unlock_at,
+                lock_at,
+                submission_types: ["discussion_topic"],
+            };
+        }
+        const result = await canvas(`/courses/${course_id}/discussion_topics`, { method: "POST", body: JSON.stringify(body) });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Created discussion "${result.title}" (ID: ${result.id})\n${result.html_url}`,
+                },
+            ],
+        };
+    });
+    server.tool("update_discussion", "Update a discussion topic's title, message, or published state. Cannot update dates or points — for those, use update_assignment or update_assignment_dates with the discussion's assignment_id (from list_discussions).", {
+        course_id: z.string().describe("Canvas course ID"),
+        discussion_id: z.string().describe("Discussion topic ID"),
+        title: z.string().optional(),
+        message: z.string().optional().describe("HTML prompt/instructions"),
+        published: z.boolean().optional(),
+    }, async ({ course_id, discussion_id, ...params }) => {
+        const result = await canvas(`/courses/${course_id}/discussion_topics/${discussion_id}`, { method: "PUT", body: JSON.stringify(params) });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated discussion "${result.title}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("batch_update_discussions", "Update title/message/published across multiple discussions. Cannot update dates or points — use batch_update_dates with assignment_ids for date changes on graded discussions.", {
+        course_id: z.string().describe("Canvas course ID"),
+        discussion_ids: z.array(z.string()).describe("Discussion topic IDs"),
+        updates: z.object({
+            message: z.string().optional().describe("HTML instructions"),
+            discussion_type: z.enum(["side_comment", "threaded"]).optional(),
+            published: z.boolean().optional(),
+        }),
+    }, async ({ course_id, discussion_ids, updates }) => {
+        const results = [];
+        for (const id of discussion_ids) {
+            try {
+                const result = await canvas(`/courses/${course_id}/discussion_topics/${id}`, { method: "PUT", body: JSON.stringify(updates) });
+                results.push(`  OK: "${result.title}" (${id})`);
+            }
+            catch (e) {
+                results.push(`  FAILED: ${id} — ${e.message}`);
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Batch update complete (${discussion_ids.length} discussions):\n${results.join("\n")}`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/enrollments.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEnrollmentTools(server: McpServer): void;

package/dist/tools/enrollments.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { canvas, canvasAll } from "../canvas-client.js";
+export function registerEnrollmentTools(server) {
+    server.tool("list_students", "List students enrolled in a course with enrollment-specific data (section, activity, last login). For a simpler user list with any role (teachers, TAs, etc.), use list_users_in_course instead.", {
+        course_id: z.string().describe("Canvas course ID"),
+        section_id: z
+            .string()
+            .optional()
+            .describe("Filter to a specific section"),
+        state: z
+            .array(z.enum(["active", "invited", "completed", "inactive"]))
+            .optional()
+            .describe("Filter by enrollment state(s)"),
+    }, async ({ course_id, section_id, state }) => {
+        const params = {
+            "type[]": "StudentEnrollment",
+        };
+        if (section_id)
+            params.section_id = section_id;
+        if (state)
+            params["state[]"] = state.join(",");
+        const enrollments = await canvasAll(`/courses/${course_id}/enrollments`, params);
+        const summary = enrollments.map((e) => ({
+            user_id: e.user_id,
+            name: e.user?.name ?? null,
+            sortable_name: e.user?.sortable_name ?? null,
+            email: e.user?.email ?? null,
+            section_id: e.course_section_id,
+            enrollment_state: e.enrollment_state,
+            last_activity_at: e.last_activity_at,
+            total_activity_time_seconds: e.total_activity_time,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("list_sections", "List sections in a course. Optionally include enrolled students.", {
+        course_id: z.string().describe("Canvas course ID"),
+        include_students: z
+            .boolean()
+            .optional()
+            .describe("Include student enrollments in each section"),
+    }, async ({ course_id, include_students }) => {
+        const params = {};
+        if (include_students)
+            params["include[]"] = "students";
+        const sections = await canvasAll(`/courses/${course_id}/sections`, params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(sections, null, 2) }],
+        };
+    });
+    server.tool("get_student_enrollments", "Get enrollment details for a specific student in a course, including grades if available.", {
+        course_id: z.string().describe("Canvas course ID"),
+        student_id: z.string().describe("Canvas user ID of the student"),
+    }, async ({ course_id, student_id }) => {
+        const enrollments = await canvasAll(`/courses/${course_id}/enrollments`, { user_id: student_id });
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(enrollments, null, 2) },
+            ],
+        };
+    });
+    server.tool("list_users_in_course", "List users in a course by role (teacher, student, ta, observer). Simpler output than list_students — use list_students when you need enrollment details like section, activity time, or state.", {
+        course_id: z.string().describe("Canvas course ID"),
+        enrollment_type: z
+            .enum(["teacher", "student", "ta", "observer", "designer"])
+            .optional()
+            .describe("Filter by enrollment role"),
+        search_term: z
+            .string()
+            .optional()
+            .describe("Filter by name or email substring"),
+        include_email: z
+            .boolean()
+            .optional()
+            .describe("Include email addresses in results"),
+    }, async ({ course_id, enrollment_type, search_term, include_email }) => {
+        const params = {};
+        if (enrollment_type)
+            params.enrollment_type = enrollment_type;
+        if (search_term)
+            params.search_term = search_term;
+        if (include_email)
+            params["include[]"] = "email";
+        const users = await canvasAll(`/courses/${course_id}/users`, params);
+        const summary = users.map((u) => ({
+            id: u.id,
+            name: u.name,
+            sortable_name: u.sortable_name,
+            email: u.email ?? null,
+            created_at: u.created_at,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("get_user_profile", "Get any user's profile information including name, email, and bio. Works for students, teachers, and any Canvas user.", {
+        user_id: z.string().describe("Canvas user ID"),
+    }, async ({ user_id }) => {
+        const profile = await canvas(`/users/${user_id}/profile`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(profile, null, 2) }],
+        };
+    });
+}

package/dist/tools/files.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFileTools(server: McpServer): void;