@charlie.act7/canvas-mcp-server 1.1.0

package/dist/tools/file-tools.js

@@ -0,0 +1,229 @@
+import { resolveCourseId } from "../common/helpers.js";
+import { z } from "zod";
+export const fileTools = [
+    {
+        name: "canvas_upload_file",
+        tool: {
+            name: "canvas_upload_file",
+            description: "Upload a local file to a Canvas course and optionally add it to a module",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The ID or name of the course"
+                    },
+                    file_path: { type: "string", description: "The local path to the file to upload" },
+                    file_name: { type: "string", description: "The name to give the file in Canvas" },
+                    content_type: { type: "string", description: "The MIME type of the file (e.g., application/pdf)" },
+                    parent_folder_id: { type: "number", description: "Optional folder ID in Canvas to upload to" },
+                    module_id: { type: "number", description: "Optional: Add the uploaded file to this module" },
+                    position: { type: "number", description: "Optional position in the module" },
+                    indent: { type: "number", description: "Optional level of indentation (0-3)" }
+                },
+                required: ["course_id", "file_path", "file_name", "content_type"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                course_id: z.union([z.number(), z.string()]),
+                file_path: z.string(),
+                file_name: z.string(),
+                content_type: z.string(),
+                parent_folder_id: z.number().optional(),
+                module_id: z.number().optional(),
+                position: z.number().optional(),
+                indent: z.number().optional()
+            }).parse(args);
+            const courseId = await resolveCourseId(client, input.course_id);
+            // 1. Upload the file
+            const file = await client.uploadFile(courseId, input.file_path, input.file_name, input.content_type, input.parent_folder_id);
+            let resultText = `File uploaded successfully: ${file.display_name} (ID: ${file.id})`;
+            // 2. Optionally add to module
+            if (input.module_id && file.id) {
+                const moduleItem = await client.createModuleItem(courseId, input.module_id, {
+                    type: 'File',
+                    content_id: file.id,
+                    position: input.position,
+                    indent: input.indent
+                });
+                resultText += `\nAnd added to module ${input.module_id} as item ${moduleItem.id}`;
+            }
+            return {
+                content: [{ type: "text", text: resultText }],
+            };
+        }
+    },
+    {
+        name: "canvas_list_folders",
+        tool: {
+            name: "canvas_list_folders",
+            description: "List folders in a Canvas course",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The ID or name of the course"
+                    }
+                },
+                required: ["course_id"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                course_id: z.union([z.number(), z.string()])
+            }).parse(args);
+            const courseId = await resolveCourseId(client, input.course_id);
+            const folders = await client.getFolders(courseId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(folders, null, 2) }],
+            };
+        }
+    },
+    {
+        name: "canvas_create_folder",
+        tool: {
+            name: "canvas_create_folder",
+            description: "Create a new folder in a Canvas course",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The ID or name of the course"
+                    },
+                    name: { type: "string", description: "The name of the new folder" },
+                    parent_folder_id: { type: "number", description: "Optional parent folder ID" }
+                },
+                required: ["course_id", "name"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                course_id: z.union([z.number(), z.string()]),
+                name: z.string(),
+                parent_folder_id: z.number().optional()
+            }).parse(args);
+            const courseId = await resolveCourseId(client, input.course_id);
+            const folder = await client.createFolder(courseId, input.name, input.parent_folder_id);
+            return {
+                content: [{ type: "text", text: `Folder created successfully: ${folder.name} (ID: ${folder.id})` }],
+            };
+        }
+    },
+    {
+        name: "canvas_update_folder",
+        tool: {
+            name: "canvas_update_folder",
+            description: "Update a folder's name or location",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    folder_id: { type: "number", description: "The ID of the folder to update" },
+                    name: { type: "string", description: "The new name for the folder" },
+                    parent_folder_id: { type: "number", description: "The ID of the new parent folder" }
+                },
+                required: ["folder_id"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                folder_id: z.number(),
+                name: z.string().optional(),
+                parent_folder_id: z.number().optional()
+            }).parse(args);
+            const folder = await client.updateFolder(input.folder_id, {
+                name: input.name,
+                parent_folder_id: input.parent_folder_id
+            });
+            return {
+                content: [{ type: "text", text: `Folder updated successfully: ${folder.name} (ID: ${folder.id})` }],
+            };
+        }
+    },
+    {
+        name: "canvas_delete_folder",
+        tool: {
+            name: "canvas_delete_folder",
+            description: "Delete a folder from Canvas",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    folder_id: { type: "number", description: "The ID of the folder to delete" },
+                    force: { type: "boolean", description: "Set to true to delete even if folder is not empty" }
+                },
+                required: ["folder_id"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                folder_id: z.number(),
+                force: z.boolean().optional().default(false)
+            }).parse(args);
+            await client.deleteFolder(input.folder_id, input.force);
+            return {
+                content: [{ type: "text", text: `Folder ${input.folder_id} deleted successfully.` }],
+            };
+        }
+    },
+    {
+        name: "canvas_update_file",
+        tool: {
+            name: "canvas_update_file",
+            description: "Update a file's metadata (name, folder, visibility)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file_id: { type: "number", description: "The ID of the file to update" },
+                    name: { type: "string", description: "The new name for the file" },
+                    parent_folder_id: { type: "number", description: "The ID of the new parent folder" },
+                    locked: { type: "boolean", description: "Whether the file is locked" },
+                    hidden: { type: "boolean", description: "Whether the file is hidden" }
+                },
+                required: ["file_id"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                file_id: z.number(),
+                name: z.string().optional(),
+                parent_folder_id: z.number().optional(),
+                locked: z.boolean().optional(),
+                hidden: z.boolean().optional()
+            }).parse(args);
+            const file = await client.updateFile(input.file_id, {
+                name: input.name,
+                parent_folder_id: input.parent_folder_id,
+                locked: input.locked,
+                hidden: input.hidden
+            });
+            return {
+                content: [{ type: "text", text: `File updated successfully: ${file.display_name} (ID: ${file.id})` }],
+            };
+        }
+    },
+    {
+        name: "canvas_delete_file",
+        tool: {
+            name: "canvas_delete_file",
+            description: "Delete a file from Canvas",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    file_id: { type: "number", description: "The ID of the file to delete" }
+                },
+                required: ["file_id"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                file_id: z.number()
+            }).parse(args);
+            await client.deleteFile(input.file_id);
+            return {
+                content: [{ type: "text", text: `File ${input.file_id} deleted successfully.` }],
+            };
+        }
+    }
+];

package/dist/tools/grading-tools.js

@@ -0,0 +1,187 @@
+import { z } from "zod";
+export const gradingTools = [
+    {
+        name: "canvas_grade_submission",
+        tool: {
+            name: "canvas_grade_submission",
+            description: "Grade a submission for a specific student",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: { type: "number", description: "The ID of the course" },
+                    assignment_id: { type: "number", description: "The ID of the assignment" },
+                    student_id: { type: "number", description: "The ID of the student" },
+                    grade: { type: "number", description: "The numeric grade to assign" },
+                    comment: { type: "string", description: "Optional comment" },
+                    rubric_assessment: {
+                        type: "object",
+                        description: "Rubric assessment data. Map of criterion ID to rating/points.",
+                        additionalProperties: {
+                            type: "object",
+                            properties: {
+                                points: { type: "number" },
+                                rating_id: { type: "string" },
+                                comments: { type: "string" }
+                            }
+                        }
+                    }
+                },
+                required: ["course_id", "assignment_id", "student_id", "grade"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                course_id: z.coerce.number(),
+                assignment_id: z.coerce.number(),
+                student_id: z.coerce.number(),
+                grade: z.union([z.number(), z.string()]),
+                comment: z.string().optional(),
+                rubric_assessment: z.record(z.string(), z.object({
+                    rating_id: z.string().optional(),
+                    points: z.number(),
+                    comments: z.string().optional()
+                })).optional()
+            }).parse(args);
+            const result = await client.gradeSubmission(input.course_id, input.assignment_id, input.student_id, input.grade, input.comment, input.rubric_assessment);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+    },
+    {
+        name: "canvas_grade_multiple_submissions",
+        tool: {
+            name: "canvas_grade_multiple_submissions",
+            description: "Grade multiple submissions at once, either by providing student_ids or filtering by status (e.g. unsubmitted)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: { type: "number", description: "The ID of the course" },
+                    assignment_id: { type: "number", description: "The ID of the assignment" },
+                    grade: { type: "number", description: "The grade to assign" },
+                    comment: { type: "string", description: "Optional comment" },
+                    student_ids: {
+                        type: "array",
+                        items: { type: "number" },
+                        description: "List of student IDs to grade"
+                    },
+                    filter_status: {
+                        type: "string",
+                        enum: ["unsubmitted", "missing", "late"],
+                        description: "Filter student submissions by status"
+                    },
+                    rubric_assessment: {
+                        type: "object",
+                        description: "Rubric assessment data. Map of criterion ID to rating/points.",
+                        additionalProperties: {
+                            type: "object",
+                            properties: {
+                                points: { type: "number" },
+                                rating_id: { type: "string" },
+                                comments: { type: "string" }
+                            }
+                        }
+                    }
+                },
+                required: ["course_id", "assignment_id", "grade"]
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                course_id: z.number(),
+                assignment_id: z.number(),
+                grade: z.union([z.number(), z.string()]),
+                comment: z.string().optional(),
+                student_ids: z.array(z.number()).optional(),
+                filter_status: z.enum(['unsubmitted', 'missing', 'late']).optional(),
+                rubric_assessment: z.record(z.string(), z.object({
+                    rating_id: z.string().optional(),
+                    points: z.number(),
+                    comments: z.string().optional()
+                })).optional()
+            }).parse(args);
+            if (!input.student_ids && !input.filter_status) {
+                throw new Error("You must provide either student_ids or a filter_status (e.g. 'unsubmitted')");
+            }
+            const cid = input.course_id;
+            const aid = input.assignment_id;
+            let studentsToGrade = [];
+            if (input.student_ids) {
+                studentsToGrade = input.student_ids;
+            }
+            else if (input.filter_status) {
+                const submissions = await client.getSubmissions(cid, aid);
+                const status = input.filter_status;
+                studentsToGrade = submissions
+                    .filter(s => {
+                    if (status === 'unsubmitted')
+                        return s.workflow_state === 'unsubmitted' || !s.submitted_at;
+                    if (status === 'missing')
+                        return s.missing;
+                    if (status === 'late')
+                        return s.late;
+                    return false;
+                })
+                    .map(s => s.user_id);
+            }
+            if (studentsToGrade.length === 0) {
+                return { content: [{ type: "text", text: "No students found matching the criteria." }] };
+            }
+            const results = [];
+            for (const userId of studentsToGrade) {
+                try {
+                    await client.gradeSubmission(cid, aid, userId, input.grade, input.comment, input.rubric_assessment);
+                    results.push({ student_id: userId, status: 'graded', grade: input.grade });
+                }
+                catch (err) {
+                    results.push({ student_id: userId, status: 'error', error: err.message });
+                }
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+            };
+        }
+    },
+    {
+        name: "canvas_audit_course",
+        tool: {
+            name: "canvas_audit_course",
+            description: "Audit a course for future assignments and missing submissions",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: { type: "number", description: "The ID of the course" },
+                },
+                required: ["course_id"],
+            },
+        },
+        handler: async (client, args) => {
+            const input = z.object({ course_id: z.coerce.number() }).parse(args);
+            const cid = input.course_id;
+            const assignments = await client.getAssignments(cid);
+            const now = new Date();
+            const future = assignments.filter(a => a.due_at && new Date(a.due_at) > now);
+            if (future.length === 0) {
+                return { content: [{ type: "text", text: "No future assignments found." }] };
+            }
+            let report = `Audit for Course ${cid}:\n`;
+            for (const a of future) {
+                if (!a.id)
+                    continue;
+                const subs = await client.getSubmissions(cid, a.id);
+                const missing = subs.filter(s => s.workflow_state === 'unsubmitted' || !s.submitted_at);
+                if (missing.length > 0) {
+                    report += `\nAssignment: ${a.name} (Due: ${a.due_at})\n`;
+                    report += `  ${missing.length} missing submissions:\n`;
+                    missing.forEach(m => {
+                        const name = m.user?.name || `User ${m.user_id}`;
+                        report += `    - ${name} (ID: ${m.user_id})\n`;
+                    });
+                }
+            }
+            return {
+                content: [{ type: "text", text: report }],
+            };
+        }
+    }
+];

package/dist/tools/group-tools.js

@@ -0,0 +1,192 @@
+import { resolveCourseId, resolveStudentId } from "../common/helpers.js";
+import { z } from "zod";
+export const groupTools = [
+    {
+        name: "canvas_list_group_categories",
+        tool: {
+            name: "canvas_list_group_categories",
+            description: "List group categories (Group Sets) in a course",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The ID or name of the course"
+                    }
+                },
+                required: ["course_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({ course_id: z.union([z.number(), z.string()]) }).parse(args);
+            const courseId = await resolveCourseId(client, input.course_id);
+            const categories = await client.getGroupCategories(courseId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(categories, null, 2) }]
+            };
+        }
+    },
+    {
+        name: "canvas_create_group_category",
+        tool: {
+            name: "canvas_create_group_category",
+            description: "Create a new group category (Group Set) in a course",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The ID or name of the course"
+                    },
+                    name: { type: "string", description: "Name of the group category" },
+                    self_signup: { type: "string", enum: ["enabled", "restricted"], description: "Allow students to sign up themselves" },
+                    auto_leader: { type: "string", enum: ["first", "random"], description: "Auto-assign a leader" },
+                    group_limit: { type: "number", description: "Maximum number of users in each group (requires self_signup)" },
+                    create_group_count: { type: "number", description: "Automatically create this number of groups" },
+                    split_group_count: { type: "number", description: "Create this many groups and randomly assign students" }
+                },
+                required: ["course_id", "name"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                course_id: z.union([z.number(), z.string()]),
+                name: z.string(),
+                self_signup: z.enum(["enabled", "restricted"]).optional(),
+                auto_leader: z.enum(["first", "random"]).optional(),
+                group_limit: z.number().optional(),
+                create_group_count: z.number().optional(),
+                split_group_count: z.number().optional()
+            }).parse(args);
+            const courseId = await resolveCourseId(client, input.course_id);
+            const category = await client.createGroupCategory(courseId, {
+                name: input.name,
+                self_signup: input.self_signup,
+                auto_leader: input.auto_leader,
+                group_limit: input.group_limit,
+                create_group_count: input.create_group_count,
+                split_group_count: input.split_group_count
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(category, null, 2) }]
+            };
+        }
+    },
+    {
+        name: "canvas_create_group",
+        tool: {
+            name: "canvas_create_group",
+            description: "Create a new group within a group category",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    group_category_id: { type: "number", description: "The ID of the group category" },
+                    name: { type: "string", description: "Name of the group" },
+                    description: { type: "string", description: "Description of the group" },
+                    join_level: { type: "string", enum: ["parent_context_auto_join", "parent_context_request", "invitation_only"], description: "How people can join" },
+                    is_public: { type: "boolean", description: "Whether the group is public" }
+                },
+                required: ["group_category_id", "name"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                group_category_id: z.number(),
+                name: z.string(),
+                description: z.string().optional(),
+                join_level: z.enum(["parent_context_auto_join", "parent_context_request", "invitation_only"]).optional(),
+                is_public: z.boolean().optional()
+            }).parse(args);
+            const group = await client.createGroup(input.group_category_id, {
+                name: input.name,
+                description: input.description,
+                join_level: input.join_level,
+                is_public: input.is_public
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(group, null, 2) }]
+            };
+        }
+    },
+    {
+        name: "canvas_list_groups_in_category",
+        tool: {
+            name: "canvas_list_groups_in_category",
+            description: "List groups inside a group category",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    group_category_id: { type: "number", description: "The ID of the group category" }
+                },
+                required: ["group_category_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({ group_category_id: z.number() }).parse(args);
+            const groups = await client.getGroupsInCategory(input.group_category_id);
+            return {
+                content: [{ type: "text", text: JSON.stringify(groups, null, 2) }]
+            };
+        }
+    },
+    {
+        name: "canvas_assign_unassigned_members",
+        tool: {
+            name: "canvas_assign_unassigned_members",
+            description: "Randomly assign unassigned students to existing groups in a category",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    group_category_id: { type: "number", description: "The ID of the group category" },
+                    sync: { type: "boolean", description: "Run assignment synchronously" }
+                },
+                required: ["group_category_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                group_category_id: z.number(),
+                sync: z.boolean().optional().default(false)
+            }).parse(args);
+            const result = await client.assignUnassignedMembers(input.group_category_id, input.sync);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+            };
+        }
+    },
+    {
+        name: "canvas_add_group_member",
+        tool: {
+            name: "canvas_add_group_member",
+            description: "Add a student to a group",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    course_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The ID or name of the course"
+                    },
+                    group_id: { type: "number", description: "The ID of the group" },
+                    student_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The ID or name of the student"
+                    }
+                },
+                required: ["course_id", "group_id", "student_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                course_id: z.union([z.number(), z.string()]),
+                group_id: z.number(),
+                student_id: z.union([z.number(), z.string()])
+            }).parse(args);
+            const courseId = await resolveCourseId(client, input.course_id);
+            const studentId = await resolveStudentId(client, courseId, input.student_id);
+            const membership = await client.addGroupMember(input.group_id, studentId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(membership, null, 2) }]
+            };
+        }
+    }
+];