canvas-agent 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# Canvas Agent
+
+MCP server that connects Claude AI to Instructure Canvas LMS. Manage courses, assignments, grades, and more through natural language.
+
+## Quick Setup
+
+Full setup guide: **[hughsibbele.github.io/Canvas-Agent](https://hughsibbele.github.io/Canvas-Agent)**
+
+If you already have Claude Code and Node.js installed:
+
+```bash
+npx -y canvas-agent setup
+```
+
+The wizard will walk you through connecting your Canvas account.
+
+## What It Does
+
+Canvas Agent gives Claude access to your Canvas LMS:
+
+- **Courses & Modules** — list, organize, and manage course structure
+- **Assignments** — create, update, set due dates and submission types
+- **Grading & Rubrics** — grade submissions, create rubrics, post grades
+- **Discussions & Quizzes** — create discussion boards and quizzes
+- **Student Management** — enrollments, submissions, analytics
+- **Pages, Files & Calendar** — create pages, upload files, manage events
+
+## Development
+
+```bash
+git clone https://github.com/hughsibbele/Canvas-Agent.git
+cd Canvas-Agent
+npm install
+cp .env.example .env     # add your Canvas URL and API token
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/canvas-client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thin wrapper around the Canvas REST API with automatic pagination.
+ */
+/** Single API call — returns parsed JSON. */
+export declare function canvas(path: string, options?: RequestInit): Promise<any>;
+/**
+ * Auto-paginated GET — follows Link: <...>; rel="next" headers
+ * and returns all results as a flat array.
+ * Canvas defaults to 10 items per page; we request 100.
+ */
+export declare function canvasAll(path: string, params?: Record<string, string>): Promise<any[]>;
+/** Summarize an assignment/discussion/quiz to reduce token usage. */
+export declare function summarizeItem(item: any): {
+    id: any;
+    name: any;
+    due_at: any;
+    unlock_at: any;
+    lock_at: any;
+    points_possible: any;
+    submission_types: any;
+    published: any;
+    assignment_group_id: any;
+    html_url: any;
+};

package/dist/canvas-client.js

@@ -0,0 +1,90 @@
+/**
+ * Thin wrapper around the Canvas REST API with automatic pagination.
+ */
+const BASE_URL = process.env.CANVAS_API_URL;
+const TOKEN = process.env.CANVAS_API_TOKEN;
+if (!BASE_URL || !TOKEN) {
+    throw new Error("Missing CANVAS_API_URL or CANVAS_API_TOKEN environment variables.\n" +
+        "Copy .env.example to .env and fill in your values.");
+}
+function authHeaders(extra) {
+    return {
+        Authorization: `Bearer ${TOKEN}`,
+        "Content-Type": "application/json",
+        ...extra,
+    };
+}
+/** Parse Canvas Link header to find the "next" page URL. */
+function getNextUrl(linkHeader) {
+    if (!linkHeader)
+        return null;
+    const match = linkHeader.match(/<([^>]+)>;\s*rel="next"/);
+    return match ? match[1] : null;
+}
+/** Retry a fetch after a delay (for rate-limit backoff). */
+async function fetchWithRetry(url, init, retries = 3) {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        const res = await fetch(url, init);
+        if (res.status === 429 && attempt < retries) {
+            const retryAfter = res.headers.get("retry-after");
+            const delay = retryAfter ? Number(retryAfter) * 1000 : 1000 * (attempt + 1);
+            await new Promise((r) => setTimeout(r, delay));
+            continue;
+        }
+        return res;
+    }
+    throw new Error("Unreachable");
+}
+/** Single API call — returns parsed JSON. */
+export async function canvas(path, options) {
+    const url = path.startsWith("http") ? path : `${BASE_URL}${path}`;
+    const res = await fetchWithRetry(url, {
+        ...options,
+        headers: authHeaders(options?.headers),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Canvas API ${res.status} ${res.statusText}: ${body}`);
+    }
+    // Some endpoints (DELETE) return 204 with no body
+    if (res.status === 204)
+        return { success: true };
+    return res.json();
+}
+/**
+ * Auto-paginated GET — follows Link: <...>; rel="next" headers
+ * and returns all results as a flat array.
+ * Canvas defaults to 10 items per page; we request 100.
+ */
+export async function canvasAll(path, params) {
+    const sep = path.includes("?") ? "&" : "?";
+    const qs = new URLSearchParams({ per_page: "100", ...params }).toString();
+    let url = `${BASE_URL}${path}${sep}${qs}`;
+    const results = [];
+    while (url) {
+        const res = await fetchWithRetry(url, { headers: authHeaders() });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Canvas API ${res.status}: ${body}`);
+        }
+        const data = await res.json();
+        results.push(...(Array.isArray(data) ? data : [data]));
+        url = getNextUrl(res.headers.get("link"));
+    }
+    return results;
+}
+/** Summarize an assignment/discussion/quiz to reduce token usage. */
+export function summarizeItem(item) {
+    return {
+        id: item.id,
+        name: item.name ?? item.title,
+        due_at: item.due_at,
+        unlock_at: item.unlock_at,
+        lock_at: item.lock_at,
+        points_possible: item.points_possible,
+        submission_types: item.submission_types,
+        published: item.published,
+        assignment_group_id: item.assignment_group_id,
+        html_url: item.html_url,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+const command = process.argv[2];
+if (command === "setup") {
+    const { runSetup } = await import("./setup.js");
+    await runSetup();
+}
+else {
+    await import("./index.js");
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,41 @@
+import "dotenv/config";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerCourseTools } from "./tools/courses.js";
+import { registerAssignmentTools } from "./tools/assignments.js";
+import { registerDiscussionTools } from "./tools/discussions.js";
+import { registerQuizTools } from "./tools/quizzes.js";
+import { registerSchedulingTools } from "./tools/scheduling.js";
+import { registerSubmissionTools } from "./tools/submissions.js";
+import { registerRubricTools } from "./tools/rubrics.js";
+import { registerNewQuizTools } from "./tools/new-quizzes.js";
+import { registerGradingTools } from "./tools/grading.js";
+import { registerPageTools } from "./tools/pages.js";
+import { registerEnrollmentTools } from "./tools/enrollments.js";
+import { registerAnalyticsTools } from "./tools/analytics.js";
+import { registerCalendarTools } from "./tools/calendar.js";
+import { registerFileTools } from "./tools/files.js";
+import { registerModuleTools } from "./tools/modules.js";
+const server = new McpServer({
+    name: "canvas-agent",
+    version: "1.0.0",
+});
+// Register all tool groups
+registerCourseTools(server);
+registerAssignmentTools(server);
+registerDiscussionTools(server);
+registerQuizTools(server);
+registerSchedulingTools(server);
+registerSubmissionTools(server);
+registerRubricTools(server);
+registerNewQuizTools(server);
+registerGradingTools(server);
+registerPageTools(server);
+registerEnrollmentTools(server);
+registerAnalyticsTools(server);
+registerCalendarTools(server);
+registerFileTools(server);
+registerModuleTools(server);
+// Connect via stdio (Claude Code launches this as a subprocess)
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/setup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Interactive setup wizard for Canvas Agent.
+ * Guides non-technical users through connecting Canvas to Claude.
+ * Uses only Node.js built-ins — no external dependencies.
+ */
+export declare function runSetup(): Promise<void>;

package/dist/setup.js

@@ -0,0 +1,287 @@
+/**
+ * Interactive setup wizard for Canvas Agent.
+ * Guides non-technical users through connecting Canvas to Claude.
+ * Uses only Node.js built-ins — no external dependencies.
+ */
+import { createInterface } from "readline/promises";
+import { execSync } from "child_process";
+import { stdin, stdout, platform } from "process";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+// ANSI color helpers
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+function banner() {
+    console.log();
+    console.log(cyan("  ╔══════════════════════════════════════╗"));
+    console.log(cyan("  ║") + bold("     Canvas Agent — Setup Wizard      ") + cyan("║"));
+    console.log(cyan("  ╚══════════════════════════════════════╝"));
+    console.log();
+    console.log("  This will connect Claude to your Canvas courses.");
+    console.log("  You'll need about 3 minutes and access to your");
+    console.log("  Canvas account.\n");
+}
+function isClaudeInstalled() {
+    try {
+        execSync("claude --version", { stdio: "pipe" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function openBrowser(url) {
+    try {
+        const cmd = platform === "darwin"
+            ? "open"
+            : platform === "win32"
+                ? "start"
+                : "xdg-open";
+        execSync(`${cmd} "${url}"`, { stdio: "ignore" });
+    }
+    catch {
+        // Silently fail — we print the URL as fallback
+    }
+}
+function normalizeCanvasUrl(raw) {
+    let hostname = raw.trim();
+    // Strip protocol
+    hostname = hostname.replace(/^https?:\/\//, "");
+    // Strip paths
+    hostname = hostname.replace(/\/.*$/, "");
+    // Strip port for validation but keep it
+    const apiUrl = `https://${hostname}/api/v1`;
+    return { hostname, apiUrl };
+}
+async function validateCredentials(apiUrl, token) {
+    try {
+        const res = await fetch(`${apiUrl}/users/self`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (res.ok) {
+            const user = (await res.json());
+            return { valid: true, name: user.name };
+        }
+        if (res.status === 401) {
+            return { valid: false, error: "Invalid token — double-check that you copied the full token." };
+        }
+        return { valid: false, error: `Canvas returned an error (${res.status} ${res.statusText}).` };
+    }
+    catch (e) {
+        if (e.cause?.code === "ENOTFOUND") {
+            return { valid: false, error: `Could not reach "${apiUrl}" — check your Canvas address.` };
+        }
+        return { valid: false, error: e.message };
+    }
+}
+function registerWithClaudeCode(apiUrl, token) {
+    try {
+        execSync(`claude mcp add -s user -e "CANVAS_API_URL=${apiUrl}" -e "CANVAS_API_TOKEN=${token}" canvas-agent -- npx -y canvas-agent`, { stdio: "inherit" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getDesktopConfigPath() {
+    if (platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32" && process.env.APPDATA) {
+        return join(process.env.APPDATA, "Claude", "claude_desktop_config.json");
+    }
+    return null;
+}
+function registerWithDesktop(apiUrl, token) {
+    const configPath = getDesktopConfigPath();
+    if (!configPath)
+        return false;
+    try {
+        // Read existing config or start fresh
+        let config = {};
+        if (existsSync(configPath)) {
+            config = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        else {
+            // Ensure parent directory exists
+            const dir = join(configPath, "..");
+            mkdirSync(dir, { recursive: true });
+        }
+        // Merge in our MCP server entry
+        if (!config.mcpServers)
+            config.mcpServers = {};
+        config.mcpServers["canvas-agent"] = {
+            command: "npx",
+            args: ["-y", "canvas-agent"],
+            env: {
+                CANVAS_API_URL: apiUrl,
+                CANVAS_API_TOKEN: token,
+            },
+        };
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function printManualConfig(apiUrl, token) {
+    console.log(yellow("\n  Add this to your Claude MCP configuration:\n"));
+    const config = {
+        "canvas-agent": {
+            command: "npx",
+            args: ["-y", "canvas-agent"],
+            env: {
+                CANVAS_API_URL: apiUrl,
+                CANVAS_API_TOKEN: token,
+            },
+        },
+    };
+    console.log("  " + JSON.stringify(config, null, 2).replace(/\n/g, "\n  "));
+    console.log();
+}
+export async function runSetup() {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        banner();
+        // ── Step 1: Check for Claude Code ──
+        const hasClaude = isClaudeInstalled();
+        let useDesktop = false;
+        if (hasClaude) {
+            console.log(green("  ✓") + " Claude Code is installed.\n");
+        }
+        else {
+            console.log(yellow("  ⚠") + " Claude Code not found.\n");
+            console.log("  Canvas Agent works best with Claude Code.");
+            console.log("  To install it, run:\n");
+            console.log(bold("    npm install -g @anthropic-ai/claude-code\n"));
+            console.log("  Then run this setup again.\n");
+            const answer = await rl.question("  Continue with Claude Desktop setup instead? (y/n): ");
+            if (answer.trim().toLowerCase() !== "y") {
+                console.log("\n  No problem! Install Claude Code and run this again:");
+                console.log(bold("    npx -y canvas-agent setup\n"));
+                return;
+            }
+            useDesktop = true;
+            console.log();
+        }
+        // ── Step 2: Get Canvas URL ──
+        console.log(bold("  Step 1: Your School's Canvas\n"));
+        let hostname = "";
+        let apiUrl = "";
+        while (true) {
+            const rawUrl = await rl.question("  Your Canvas address (e.g., myschool.instructure.com): ");
+            if (!rawUrl.trim())
+                continue;
+            const normalized = normalizeCanvasUrl(rawUrl);
+            hostname = normalized.hostname;
+            apiUrl = normalized.apiUrl;
+            if (!hostname.includes(".")) {
+                console.log(red("  ✗") + ` That doesn't look like a web address. Try again.\n`);
+                continue;
+            }
+            console.log(dim(`    → ${apiUrl}`));
+            break;
+        }
+        // ── Step 3: Get Canvas API Token ──
+        console.log(bold("\n  Step 2: Canvas API Token\n"));
+        console.log("  We need an access token from Canvas. Here's how:\n");
+        console.log(`  1. Log in to Canvas at ${cyan(`https://${hostname}`)}`);
+        console.log("  2. Click your profile picture (top left) → " + bold("Settings"));
+        console.log("  3. Scroll down to " + bold('"Approved Integrations"'));
+        console.log("  4. Click " + bold('"+ New Access Token"'));
+        console.log("  5. For Purpose, type: " + dim("Canvas Agent"));
+        console.log("  6. Click " + bold('"Generate Token"') + " and copy the token shown\n");
+        const settingsUrl = `https://${hostname}/profile/settings`;
+        console.log(`  Opening ${cyan(settingsUrl)} in your browser...`);
+        openBrowser(settingsUrl);
+        console.log();
+        let token = "";
+        while (true) {
+            token = (await rl.question("  Paste your token here: ")).trim();
+            if (!token)
+                continue;
+            // ── Step 4: Validate ──
+            console.log(dim("    Checking..."));
+            const result = await validateCredentials(apiUrl, token);
+            if (result.valid) {
+                console.log(green("  ✓") + ` Connected! Welcome, ${bold(result.name || "there")}.\n`);
+                break;
+            }
+            else {
+                console.log(red("  ✗") + ` ${result.error}\n`);
+                const retry = await rl.question("  Try again? (y/n): ");
+                if (retry.trim().toLowerCase() !== "y") {
+                    console.log("\n  No worries — run this wizard again when you're ready:");
+                    console.log(bold("    npx -y canvas-agent setup\n"));
+                    return;
+                }
+                // Let them fix the URL too
+                const fixUrl = await rl.question("  Change Canvas address too? (y/n): ");
+                if (fixUrl.trim().toLowerCase() === "y") {
+                    const rawUrl = await rl.question("  Canvas address: ");
+                    const normalized = normalizeCanvasUrl(rawUrl);
+                    hostname = normalized.hostname;
+                    apiUrl = normalized.apiUrl;
+                    console.log(dim(`    → ${apiUrl}\n`));
+                }
+                console.log();
+            }
+        }
+        // ── Step 5: Register MCP server ──
+        console.log(bold("  Step 3: Connecting to Claude\n"));
+        let registered = false;
+        if (!useDesktop) {
+            // Try Claude Code first
+            console.log("  Registering Canvas Agent with Claude Code...\n");
+            registered = registerWithClaudeCode(apiUrl, token);
+            if (registered) {
+                console.log(green("\n  ✓") + " Registered with Claude Code!\n");
+            }
+            else {
+                console.log(yellow("\n  ⚠") + " Could not register automatically.\n");
+                // Fall through to Desktop or manual
+                useDesktop = true;
+            }
+        }
+        if (useDesktop && !registered) {
+            console.log("  Setting up Claude Desktop...");
+            registered = registerWithDesktop(apiUrl, token);
+            if (registered) {
+                console.log(green("  ✓") + " Configured Claude Desktop!\n");
+                console.log(dim("    Restart Claude Desktop for changes to take effect.\n"));
+            }
+        }
+        if (!registered) {
+            printManualConfig(apiUrl, token);
+            console.log("  Copy the JSON above and add it to your Claude configuration.");
+            console.log("  For help, visit: " + cyan("https://hughsibbele.github.io/Canvas-Agent") + "\n");
+        }
+        // ── Done ──
+        console.log(cyan("  ╔══════════════════════════════════════╗"));
+        console.log(cyan("  ║") + green("          Setup Complete!              ") + cyan("║"));
+        console.log(cyan("  ╚══════════════════════════════════════╝"));
+        console.log();
+        if (!useDesktop) {
+            console.log("  To start using Canvas Agent:");
+            console.log("  1. Open a terminal and type: " + bold("claude"));
+            console.log('  2. Try asking: ' + dim('"List my Canvas courses"'));
+        }
+        else {
+            console.log("  To start using Canvas Agent:");
+            console.log("  1. Restart Claude Desktop");
+            console.log('  2. Try asking: ' + dim('"List my Canvas courses"'));
+        }
+        console.log();
+        console.log("  For help: " + cyan("https://hughsibbele.github.io/Canvas-Agent"));
+        console.log();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/tools/analytics.d.ts

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

package/dist/tools/analytics.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { canvas, canvasAll } from "../canvas-client.js";
+export function registerAnalyticsTools(server) {
+    server.tool("get_course_activity", "Get daily page views and participation analytics for a course. This returns engagement metrics, not assignment data — use list_assignments for assignment info.", {
+        course_id: z.string().describe("Canvas course ID"),
+    }, async ({ course_id }) => {
+        const activity = await canvas(`/courses/${course_id}/analytics/activity`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(activity, null, 2) }],
+        };
+    });
+    server.tool("get_course_assignment_analytics", "Get aggregate statistical analytics per assignment: min/max/median scores, submission counts (on_time, late, missing). This returns statistics, not the assignments themselves — use list_assignments for that.", {
+        course_id: z.string().describe("Canvas course ID"),
+    }, async ({ course_id }) => {
+        const analytics = await canvas(`/courses/${course_id}/analytics/assignments`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(analytics, null, 2) }],
+        };
+    });
+    server.tool("get_student_summaries", "Get per-student engagement analytics for a course: page views, participations, and tardiness breakdown. For enrollment/roster data, use list_students instead.", {
+        course_id: z.string().describe("Canvas course ID"),
+        sort_column: z
+            .enum([
+            "name",
+            "name_descending",
+            "score",
+            "score_descending",
+            "participations",
+            "page_views",
+        ])
+            .optional()
+            .describe("Column to sort by"),
+    }, async ({ course_id, sort_column }) => {
+        const params = {};
+        if (sort_column)
+            params.sort_column = sort_column;
+        const summaries = await canvasAll(`/courses/${course_id}/analytics/student_summaries`, params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(summaries, null, 2) }],
+        };
+    });
+    server.tool("get_student_activity", "Get hourly page view breakdown for a specific student in a course.", {
+        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 activity = await canvas(`/courses/${course_id}/analytics/users/${student_id}/activity`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(activity, null, 2) }],
+        };
+    });
+    server.tool("get_student_assignment_data", "Get per-assignment scores, submission status, and timestamps for a specific student. This is analytics data — for actual submission details, use list_submissions.", {
+        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 data = await canvas(`/courses/${course_id}/analytics/users/${student_id}/assignments`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    server.tool("get_student_messaging_data", "Get message counts between instructor and a specific student in a course.", {
+        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 data = await canvas(`/courses/${course_id}/analytics/users/${student_id}/communication`);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/dist/tools/assignments.d.ts

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