canvas-agent 1.0.0

package/dist/tools/files.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { canvas, canvasAll } from "../canvas-client.js";
+export function registerFileTools(server) {
+    server.tool("list_course_files", "List files in a course, optionally filtered by search term, content type, or sort order.", {
+        course_id: z.string().describe("Canvas course ID"),
+        search_term: z.string().optional().describe("Filter by filename substring"),
+        content_types: z
+            .array(z.string())
+            .optional()
+            .describe('Filter by MIME type (e.g. ["application/pdf"])'),
+        sort: z
+            .enum(["name", "size", "created_at", "updated_at"])
+            .optional()
+            .describe("Sort order"),
+    }, async ({ course_id, search_term, content_types, sort }) => {
+        const params = {};
+        if (search_term)
+            params.search_term = search_term;
+        if (sort)
+            params.sort = sort;
+        // Canvas expects content_types[] as repeated params; encode manually
+        let extraQs = "";
+        if (content_types && content_types.length > 0) {
+            extraQs = content_types
+                .map((ct) => `content_types[]=${encodeURIComponent(ct)}`)
+                .join("&");
+        }
+        const path = extraQs
+            ? `/courses/${course_id}/files?${extraQs}`
+            : `/courses/${course_id}/files`;
+        const files = await canvasAll(path, params);
+        const summary = files.map((f) => ({
+            id: f.id,
+            display_name: f.display_name,
+            filename: f.filename,
+            size: f.size,
+            content_type: f["content-type"],
+            url: f.url,
+            created_at: f.created_at,
+            updated_at: f.updated_at,
+            folder_id: f.folder_id,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("get_file", "Get full details of a single file, including its download URL.", {
+        file_id: z.string().describe("File ID"),
+    }, async ({ file_id }) => {
+        const file = await canvas(`/files/${file_id}`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(file, null, 2) }],
+        };
+    });
+    server.tool("list_folders", "List all folders in a course.", {
+        course_id: z.string().describe("Canvas course ID"),
+    }, async ({ course_id }) => {
+        const folders = await canvasAll(`/courses/${course_id}/folders`);
+        const summary = folders.map((f) => ({
+            id: f.id,
+            name: f.name,
+            full_name: f.full_name,
+            parent_folder_id: f.parent_folder_id,
+            files_count: f.files_count,
+            folders_count: f.folders_count,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("create_folder", "Create a new folder in a course.", {
+        course_id: z.string().describe("Canvas course ID"),
+        name: z.string().describe("Folder name"),
+        parent_folder_path: z
+            .string()
+            .optional()
+            .default("/")
+            .describe("Parent folder path (default: root)"),
+        hidden: z.boolean().optional().describe("Hide the folder from students"),
+        locked: z.boolean().optional().describe("Lock the folder"),
+    }, async ({ course_id, name, parent_folder_path, hidden, locked }) => {
+        const body = { name, parent_folder_path };
+        if (hidden !== undefined)
+            body.hidden = hidden;
+        if (locked !== undefined)
+            body.locked = locked;
+        const result = await canvas(`/courses/${course_id}/folders`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Created folder "${result.name}" (ID: ${result.id}) at ${result.full_name}`,
+                },
+            ],
+        };
+    });
+    server.tool("delete_file", "Permanently delete a file.", {
+        file_id: z.string().describe("File ID"),
+    }, async ({ file_id }) => {
+        await canvas(`/files/${file_id}`, { method: "DELETE" });
+        return {
+            content: [{ type: "text", text: `Deleted file ${file_id}` }],
+        };
+    });
+    server.tool("update_file", "Update file metadata. Only include fields you want to change.", {
+        file_id: z.string().describe("File ID"),
+        name: z.string().optional().describe("Rename the file"),
+        lock_at: z.string().optional().describe("Lock date (ISO 8601)"),
+        unlock_at: z.string().optional().describe("Unlock date (ISO 8601)"),
+        locked: z.boolean().optional().describe("Lock the file"),
+        hidden: z.boolean().optional().describe("Hide from students"),
+    }, async ({ file_id, ...params }) => {
+        const result = await canvas(`/files/${file_id}`, {
+            method: "PUT",
+            body: JSON.stringify(params),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated file "${result.display_name}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("get_file_quota", "Get the file storage quota and usage for a course.", {
+        course_id: z.string().describe("Canvas course ID"),
+    }, async ({ course_id }) => {
+        const quota = await canvas(`/courses/${course_id}/files/quota`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        quota: quota.quota,
+                        quota_used: quota.quota_used,
+                        quota_remaining: quota.quota - quota.quota_used,
+                        quota_human: `${(quota.quota / 1024 / 1024).toFixed(1)} MB`,
+                        used_human: `${(quota.quota_used / 1024 / 1024).toFixed(1)} MB`,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/tools/grading.d.ts

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

package/dist/tools/grading.js

@@ -0,0 +1,260 @@
+import { z } from "zod";
+import { canvas, canvasAll } from "../canvas-client.js";
+export function registerGradingTools(server) {
+    server.tool("grade_submission", "Grade a single student submission with a score and optional comment. For rubric-based grading, use grade_with_rubric instead. Works for regular assignments, graded discussions (use the assignment_id), and New Quizzes (use the assignment_id).", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID (also works for graded discussions and New Quizzes via their linked assignment_id)"),
+        student_id: z.string().describe("Student user ID (use list_students or list_gradeable_students to find IDs)"),
+        score: z.union([z.number(), z.string()]).optional().describe("Grade to assign: points (95), percentage ('85%'), letter grade ('A-'), 'pass'/'fail', or 'complete'/'incomplete'"),
+        excuse: z
+            .boolean()
+            .optional()
+            .describe("Excuse the student from the assignment"),
+        late_policy_status: z
+            .enum(["none", "missing", "late", "extended"])
+            .optional()
+            .describe("Override the late policy status"),
+        comment: z
+            .string()
+            .optional()
+            .describe("Text comment on the submission"),
+        comment_file_ids: z
+            .array(z.string())
+            .optional()
+            .describe("File IDs to attach to the comment"),
+    }, async ({ course_id, assignment_id, student_id, score, excuse, late_policy_status, comment, comment_file_ids, }) => {
+        const body = {};
+        const submission = {};
+        if (score !== undefined)
+            submission.posted_grade = score;
+        if (excuse !== undefined)
+            submission.excuse = excuse;
+        if (late_policy_status !== undefined)
+            submission.late_policy_status = late_policy_status;
+        if (Object.keys(submission).length > 0)
+            body.submission = submission;
+        const commentObj = {};
+        if (comment !== undefined)
+            commentObj.text_comment = comment;
+        if (comment_file_ids !== undefined)
+            commentObj.file_ids = comment_file_ids;
+        if (Object.keys(commentObj).length > 0)
+            body.comment = commentObj;
+        const result = await canvas(`/courses/${course_id}/assignments/${assignment_id}/submissions/${student_id}`, {
+            method: "PUT",
+            body: JSON.stringify(body),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Graded submission for user ${student_id}: score=${result.score}, grade="${result.grade}", workflow_state=${result.workflow_state}`,
+                },
+            ],
+        };
+    });
+    server.tool("bulk_grade", "Grade multiple students on one assignment at once. Returns a Progress object — the grading happens asynchronously.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+        grades: z
+            .array(z.object({
+            student_id: z.string().describe("Student (user) ID"),
+            score: z.union([z.number(), z.string()]).describe("Grade: points (95), percentage ('85%'), or letter ('A-')"),
+            comment: z
+                .string()
+                .optional()
+                .describe("Optional text comment"),
+        }))
+            .describe("Array of student grades to apply"),
+    }, async ({ course_id, assignment_id, grades }) => {
+        const grade_data = {};
+        for (const g of grades) {
+            const entry = { posted_grade: g.score };
+            if (g.comment !== undefined)
+                entry.text_comment = g.comment;
+            grade_data[g.student_id] = entry;
+        }
+        const result = await canvas(`/courses/${course_id}/assignments/${assignment_id}/submissions/update_grades`, {
+            method: "POST",
+            body: JSON.stringify({ grade_data }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Bulk grade started. Progress: id=${result.id}, workflow_state=${result.workflow_state}, url=${result.url ?? "N/A"}\n${JSON.stringify(result, null, 2)}`,
+                },
+            ],
+        };
+    });
+    server.tool("submission_summary", "Quick overview of submission status for an assignment — counts of graded, ungraded, and not submitted. For individual submission details, use list_submissions instead.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+    }, async ({ course_id, assignment_id }) => {
+        const summary = await canvas(`/courses/${course_id}/assignments/${assignment_id}/submission_summary`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("list_missing_submissions", "List all missing assignments for a specific student. Very useful for parent conferences and progress reports.", {
+        student_id: z.string().describe("Student (user) ID"),
+        course_id: z
+            .string()
+            .optional()
+            .describe("Filter to a specific course"),
+        include_planner_overrides: z
+            .boolean()
+            .optional()
+            .describe("Include planner override info"),
+    }, async ({ student_id, course_id, include_planner_overrides }) => {
+        const params = {};
+        if (course_id)
+            params.course_id = course_id;
+        if (include_planner_overrides)
+            params["include[]"] = "planner_overrides";
+        const submissions = await canvasAll(`/users/${student_id}/missing_submissions`, params);
+        const summary = submissions.map((s) => ({
+            id: s.id,
+            name: s.name,
+            course_id: s.course_id,
+            due_at: s.due_at,
+            points_possible: s.points_possible,
+            html_url: s.html_url,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("list_gradeable_students", "List students who can be graded for a specific assignment. Use the returned IDs as student_id in grade_submission or grade_with_rubric.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+    }, async ({ course_id, assignment_id }) => {
+        const students = await canvasAll(`/courses/${course_id}/assignments/${assignment_id}/gradeable_students`);
+        const summary = students.map((s) => ({
+            id: s.id,
+            display_name: s.display_name,
+            avatar_url: s.avatar_url,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("get_late_policy", "Get the late policy configuration for a course.", {
+        course_id: z.string().describe("Canvas course ID"),
+    }, async ({ course_id }) => {
+        const result = await canvas(`/courses/${course_id}/late_policy`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.tool("set_late_policy", "Create or update the late policy for a course. Only include fields you want to change.", {
+        course_id: z.string().describe("Canvas course ID"),
+        missing_submission_deduction_enabled: z
+            .boolean()
+            .optional()
+            .describe("Enable automatic deduction for missing submissions"),
+        missing_submission_deduction: z
+            .number()
+            .optional()
+            .describe("Percentage to deduct for missing submissions"),
+        late_submission_deduction_enabled: z
+            .boolean()
+            .optional()
+            .describe("Enable automatic deduction for late submissions"),
+        late_submission_deduction: z
+            .number()
+            .optional()
+            .describe("Percentage to deduct per period for late submissions"),
+        late_submission_interval: z
+            .enum(["day", "hour"])
+            .optional()
+            .describe("Interval for late deduction (day or hour)"),
+        late_submission_minimum_percent_enabled: z
+            .boolean()
+            .optional()
+            .describe("Enable a minimum grade for late submissions"),
+        late_submission_minimum_percent: z
+            .number()
+            .optional()
+            .describe("Minimum percentage a late submission can receive"),
+    }, async ({ course_id, ...policyFields }) => {
+        // Filter out undefined values
+        const late_policy = {};
+        for (const [key, value] of Object.entries(policyFields)) {
+            if (value !== undefined)
+                late_policy[key] = value;
+        }
+        const result = await canvas(`/courses/${course_id}/late_policy`, {
+            method: "PATCH",
+            body: JSON.stringify({ late_policy }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Late policy updated.\n${JSON.stringify(result, null, 2)}`,
+                },
+            ],
+        };
+    });
+    server.tool("post_grades", "Post (make visible) grades for an assignment so students can see them. Optionally post for specific students only.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+        only_student_ids: z
+            .array(z.string())
+            .optional()
+            .describe("Post grades only for these student IDs (omit to post all)"),
+    }, async ({ course_id, assignment_id, only_student_ids }) => {
+        const body = {};
+        if (only_student_ids !== undefined) {
+            body.student_ids = only_student_ids;
+        }
+        const result = await canvas(`/courses/${course_id}/assignments/${assignment_id}/post_grades`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Grades posted for assignment ${assignment_id}.\n${JSON.stringify(result, null, 2)}`,
+                },
+            ],
+        };
+    });
+    server.tool("hide_grades", "Hide grades from students for an assignment. Optionally hide for specific students only.", {
+        course_id: z.string().describe("Canvas course ID"),
+        assignment_id: z.string().describe("Assignment ID"),
+        only_student_ids: z
+            .array(z.string())
+            .optional()
+            .describe("Hide grades only for these student IDs (omit to hide all)"),
+    }, async ({ course_id, assignment_id, only_student_ids }) => {
+        const body = {};
+        if (only_student_ids !== undefined) {
+            body.student_ids = only_student_ids;
+        }
+        const result = await canvas(`/courses/${course_id}/assignments/${assignment_id}/hide_grades`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Grades hidden for assignment ${assignment_id}.\n${JSON.stringify(result, null, 2)}`,
+                },
+            ],
+        };
+    });
+    server.tool("get_grading_standards", "List grading scales/standards defined for a course (e.g. A/B/C letter grades with cutoffs).", {
+        course_id: z.string().describe("Canvas course ID"),
+    }, async ({ course_id }) => {
+        const standards = await canvasAll(`/courses/${course_id}/grading_standards`);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(standards, null, 2) },
+            ],
+        };
+    });
+}

package/dist/tools/modules.d.ts

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

package/dist/tools/modules.js

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import { canvas, canvasAll } from "../canvas-client.js";
+export function registerModuleTools(server) {
+    server.tool("create_module", "Create a new module in a course. Use list_modules to see existing modules first.", {
+        course_id: z.string().describe("Canvas course ID"),
+        name: z.string().describe("Module name"),
+        position: z.number().optional().describe("Position in the module list"),
+        unlock_at: z
+            .string()
+            .optional()
+            .describe("Date the module unlocks (ISO 8601)"),
+        require_sequential_progress: z
+            .boolean()
+            .optional()
+            .describe("Require students to complete items in order"),
+        prerequisite_module_ids: z
+            .array(z.string())
+            .optional()
+            .describe("IDs of modules that must be completed first"),
+    }, async ({ course_id, name, position, unlock_at, require_sequential_progress, prerequisite_module_ids }) => {
+        const moduleData = { name };
+        if (position !== undefined)
+            moduleData.position = position;
+        if (unlock_at !== undefined)
+            moduleData.unlock_at = unlock_at;
+        if (require_sequential_progress !== undefined)
+            moduleData.require_sequential_progress = require_sequential_progress;
+        if (prerequisite_module_ids !== undefined)
+            moduleData.prerequisite_module_ids = prerequisite_module_ids;
+        const result = await canvas(`/courses/${course_id}/modules`, {
+            method: "POST",
+            body: JSON.stringify({ module: moduleData }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Created module "${result.name}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("update_module", "Update an existing module. Only include fields you want to change.", {
+        course_id: z.string().describe("Canvas course ID"),
+        module_id: z.string().describe("Module ID"),
+        name: z.string().optional(),
+        position: z.number().optional(),
+        published: z.boolean().optional(),
+        unlock_at: z.string().optional().describe("ISO 8601"),
+    }, async ({ course_id, module_id, ...params }) => {
+        const result = await canvas(`/courses/${course_id}/modules/${module_id}`, {
+            method: "PUT",
+            body: JSON.stringify({ module: params }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated module "${result.name}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("delete_module", "Delete a module from a course.", {
+        course_id: z.string().describe("Canvas course ID"),
+        module_id: z.string().describe("Module ID"),
+    }, async ({ course_id, module_id }) => {
+        await canvas(`/courses/${course_id}/modules/${module_id}`, {
+            method: "DELETE",
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Deleted module ${module_id}`,
+                },
+            ],
+        };
+    });
+    server.tool("list_module_items", "List all items in a module.", {
+        course_id: z.string().describe("Canvas course ID"),
+        module_id: z.string().describe("Module ID"),
+    }, async ({ course_id, module_id }) => {
+        const items = await canvasAll(`/courses/${course_id}/modules/${module_id}/items`);
+        const summary = items.map((i) => ({
+            id: i.id,
+            title: i.title,
+            type: i.type,
+            position: i.position,
+            content_id: i.content_id,
+            html_url: i.html_url,
+            published: i.published,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
+        };
+    });
+    server.tool("add_module_item", "Add an item to a module. Required fields depend on type: Assignment/Discussion/File need content_id, Page needs page_url, SubHeader/ExternalUrl need title. For New Quizzes, use type='Assignment' with the New Quiz's assignment_id (not type='Quiz'). type='Quiz' is for Classic Quizzes only.", {
+        course_id: z.string().describe("Canvas course ID"),
+        module_id: z.string().describe("Module ID"),
+        type: z
+            .enum([
+            "Assignment",
+            "Quiz",
+            "Discussion",
+            "File",
+            "Page",
+            "SubHeader",
+            "ExternalUrl",
+            "ExternalTool",
+        ])
+            .describe("Type of item to add"),
+        content_id: z
+            .string()
+            .optional()
+            .describe("ID of the content (required for Assignment, Quiz, Discussion, File)"),
+        page_url: z
+            .string()
+            .optional()
+            .describe("URL slug of the page (required for Page type)"),
+        title: z
+            .string()
+            .optional()
+            .describe("Title (required for SubHeader and ExternalUrl)"),
+        external_url: z
+            .string()
+            .optional()
+            .describe("URL for ExternalUrl type"),
+        position: z.number().optional().describe("Position within the module"),
+        indent: z
+            .number()
+            .optional()
+            .describe("Indentation level (0-5)"),
+    }, async ({ course_id, module_id, type, content_id, page_url, title, external_url, position, indent }) => {
+        const moduleItem = { type };
+        if (content_id !== undefined)
+            moduleItem.content_id = content_id;
+        if (page_url !== undefined)
+            moduleItem.page_url = page_url;
+        if (title !== undefined)
+            moduleItem.title = title;
+        if (external_url !== undefined)
+            moduleItem.external_url = external_url;
+        if (position !== undefined)
+            moduleItem.position = position;
+        if (indent !== undefined)
+            moduleItem.indent = indent;
+        const result = await canvas(`/courses/${course_id}/modules/${module_id}/items`, {
+            method: "POST",
+            body: JSON.stringify({ module_item: moduleItem }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Added "${result.title}" (ID: ${result.id}, type: ${result.type}) to module`,
+                },
+            ],
+        };
+    });
+    server.tool("update_module_item", "Update a module item. Only include fields you want to change.", {
+        course_id: z.string().describe("Canvas course ID"),
+        module_id: z.string().describe("Module ID"),
+        item_id: z.string().describe("Module item ID"),
+        title: z.string().optional(),
+        position: z.number().optional(),
+        indent: z.number().optional().describe("Indentation level (0-5)"),
+        published: z.boolean().optional(),
+    }, async ({ course_id, module_id, item_id, ...params }) => {
+        const result = await canvas(`/courses/${course_id}/modules/${module_id}/items/${item_id}`, {
+            method: "PUT",
+            body: JSON.stringify({ module_item: params }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Updated module item "${result.title}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+    server.tool("delete_module_item", "Delete an item from a module.", {
+        course_id: z.string().describe("Canvas course ID"),
+        module_id: z.string().describe("Module ID"),
+        item_id: z.string().describe("Module item ID"),
+    }, async ({ course_id, module_id, item_id }) => {
+        await canvas(`/courses/${course_id}/modules/${module_id}/items/${item_id}`, { method: "DELETE" });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Deleted module item ${item_id}`,
+                },
+            ],
+        };
+    });
+    server.tool("publish_module", "Publish a module (makes it visible to students). Note: this publishes the module container only — individual items retain their own published state.", {
+        course_id: z.string().describe("Canvas course ID"),
+        module_id: z.string().describe("Module ID"),
+    }, async ({ course_id, module_id }) => {
+        const result = await canvas(`/courses/${course_id}/modules/${module_id}`, {
+            method: "PUT",
+            body: JSON.stringify({ module: { published: true } }),
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Published module "${result.name}" (ID: ${result.id})`,
+                },
+            ],
+        };
+    });
+}

package/dist/tools/new-quizzes.d.ts

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