@charlie.act7/canvas-mcp-server 1.2.0 → 1.2.2

package/dist/services/canvas-client.js

@@ -4,11 +4,22 @@ export class CanvasClient {
     quizClient;
     token;
     domain;
-    constructor(token, domain) {
+    autoRenewToken;
+    renewThresholdMs;
+    onTokenRenewed;
+    tokenMetaCacheMs = 15 * 60 * 1000;
+    tokenMeta = null;
+    tokenMetaCheckedAt = 0;
+    isCheckingToken = false;
+    constructor(token, domain, options = {}) {
         this.token = token;
         this.domain = domain;
+        this.autoRenewToken = options.autoRenewToken ?? true;
+        this.renewThresholdMs = (options.renewThresholdHours ?? 24) * 60 * 60 * 1000;
+        this.onTokenRenewed = options.onTokenRenewed;
         this.client = this.createAxiosInstance(token, domain);
         this.quizClient = this.createAxiosInstance(token, domain, 'api/quiz/v1');
+        this.attachAutoRenewInterceptor();
     }
     createAxiosInstance(token, domain, apiPath = 'api/v1') {
         const baseURL = `https://${domain}/${apiPath}`;
@@ -25,6 +36,71 @@ export class CanvasClient {
         this.domain = domain;
         this.client = this.createAxiosInstance(token, domain);
         this.quizClient = this.createAxiosInstance(token, domain, 'api/quiz/v1');
+        this.tokenMeta = null;
+        this.tokenMetaCheckedAt = 0;
+        this.attachAutoRenewInterceptor();
+    }
+    attachAutoRenewInterceptor() {
+        this.client.interceptors.request.use(async (config) => {
+            if (this.autoRenewToken && !this.isCheckingToken) {
+                await this.maybeRenewToken();
+            }
+            return config;
+        });
+    }
+    applyNewToken(newToken) {
+        this.token = newToken;
+        this.client.defaults.headers['Authorization'] = `Bearer ${newToken}`;
+        this.quizClient.defaults.headers['Authorization'] = `Bearer ${newToken}`;
+    }
+    // Canvas only returns the full token value on creation/regeneration, never on list/get.
+    // To identify which listed token corresponds to the one currently authenticating this
+    // client, we match its (short) token_hint as a substring of the known full token value.
+    async refreshTokenMeta() {
+        this.isCheckingToken = true;
+        try {
+            const tokens = await this.getAllPages('users/self/user_generated_tokens', { per_page: 100 });
+            const match = tokens.find(t => t.token_hint && this.token.includes(t.token_hint));
+            this.tokenMeta = match
+                ? { id: match.id, expiresAtMs: match.expires_at ? new Date(match.expires_at).getTime() : null }
+                : null;
+        }
+        catch {
+            // Don't block requests if we can't determine token metadata (e.g. insufficient permissions).
+            this.tokenMeta = null;
+        }
+        finally {
+            this.tokenMetaCheckedAt = Date.now();
+            this.isCheckingToken = false;
+        }
+    }
+    async maybeRenewToken() {
+        const now = Date.now();
+        if (now - this.tokenMetaCheckedAt >= this.tokenMetaCacheMs) {
+            await this.refreshTokenMeta();
+        }
+        if (!this.tokenMeta || this.tokenMeta.expiresAtMs === null)
+            return;
+        if (this.tokenMeta.expiresAtMs - now > this.renewThresholdMs)
+            return;
+        this.isCheckingToken = true;
+        try {
+            const response = await this.client.put(`users/self/tokens/${this.tokenMeta.id}`, {
+                token: { regenerate: true }
+            });
+            if (response.data.token) {
+                this.applyNewToken(response.data.token);
+                this.onTokenRenewed?.(response.data.token);
+            }
+            this.tokenMeta = {
+                id: this.tokenMeta.id,
+                expiresAtMs: response.data.expires_at ? new Date(response.data.expires_at).getTime() : null
+            };
+            this.tokenMetaCheckedAt = Date.now();
+        }
+        finally {
+            this.isCheckingToken = false;
+        }
     }
     parseLinkHeader(header) {
         if (!header)
@@ -273,9 +349,38 @@ export class CanvasClient {
         return response.data;
     }
     async updateModule(courseId, moduleId, data) {
-        const response = await this.client.put(`courses/${courseId}/modules/${moduleId}`, {
-            module: data
-        });
+        // Canvas only accepts arrays (prerequisite_module_ids, completion_requirements)
+        // via form-encoding, not JSON.
+        const hasArrays = data.prerequisite_module_ids !== undefined || data.completion_requirements !== undefined;
+        if (hasArrays) {
+            const params = new URLSearchParams();
+            if (data.name !== undefined)
+                params.set('module[name]', data.name);
+            if (data.published !== undefined)
+                params.set('module[published]', String(data.published));
+            if (data.position !== undefined)
+                params.set('module[position]', String(data.position));
+            if (data.require_sequential_progress !== undefined) {
+                params.set('module[require_sequential_progress]', String(data.require_sequential_progress));
+            }
+            if (data.prerequisite_module_ids) {
+                for (const id of data.prerequisite_module_ids) {
+                    params.append('module[prerequisite_module_ids][]', String(id));
+                }
+            }
+            if (data.completion_requirements) {
+                for (const req of data.completion_requirements) {
+                    params.append('module[completion_requirements][][id]', String(req.id));
+                    params.append('module[completion_requirements][][type]', req.type);
+                    if (req.min_score !== undefined) {
+                        params.append('module[completion_requirements][][min_score]', String(req.min_score));
+                    }
+                }
+            }
+            const response = await this.client.put(`courses/${courseId}/modules/${moduleId}`, params, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
+            return response.data;
+        }
+        const response = await this.client.put(`courses/${courseId}/modules/${moduleId}`, { module: data });
         return response.data;
     }
     async deleteModule(courseId, moduleId) {
@@ -290,9 +395,20 @@ export class CanvasClient {
         return response.data;
     }
     async updateModuleItem(courseId, moduleId, itemId, data) {
-        const response = await this.client.put(`courses/${courseId}/modules/${moduleId}/items/${itemId}`, {
-            module_item: data
-        });
+        // Canvas only accepts completion_requirement via form-encoding, not JSON.
+        // Use URLSearchParams when completion_requirement is present.
+        if (data.completion_requirement) {
+            const params = new URLSearchParams();
+            params.set('module_item[completion_requirement][type]', data.completion_requirement.type);
+            const { completion_requirement, ...rest } = data;
+            for (const [key, value] of Object.entries(rest)) {
+                if (value !== undefined)
+                    params.set(`module_item[${key}]`, String(value));
+            }
+            const response = await this.client.put(`courses/${courseId}/modules/${moduleId}/items/${itemId}`, params, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
+            return response.data;
+        }
+        const response = await this.client.put(`courses/${courseId}/modules/${moduleId}/items/${itemId}`, { module_item: data });
         return response.data;
     }
     async deleteModuleItem(courseId, moduleId, itemId) {
@@ -333,6 +449,39 @@ export class CanvasClient {
         }
         return uploadResponse.data;
     }
+    async getQuizSubmissions(courseId, quizId) {
+        const response = await this.client.get(`courses/${courseId}/quizzes/${quizId}/submissions`, {
+            params: { include: ['user'], per_page: 100 }
+        });
+        return response.data.quiz_submissions ?? [];
+    }
+    async deleteQuiz(courseId, quizId) {
+        await this.client.delete(`courses/${courseId}/quizzes/${quizId}`);
+        return { deleted: true };
+    }
+    async checkQuizPending(courseId, quizId) {
+        const [students, submissionsResp] = await Promise.all([
+            this.getEnrollments(courseId),
+            this.client.get(`courses/${courseId}/quizzes/${quizId}/submissions`, {
+                params: { per_page: 100 }
+            })
+        ]);
+        const realStudents = students.filter(u => u.name !== 'Estudiante de prueba' && u.sis_user_id !== null);
+        const submittedIds = new Set((submissionsResp.data.quiz_submissions ?? []).map((s) => s.user_id));
+        const pending = realStudents
+            .filter(u => !submittedIds.has(u.id))
+            .map(u => ({
+            id: u.id,
+            name: u.name ?? 'Desconocido',
+            email: u.login_id ?? ''
+        }));
+        return {
+            quiz_id: quizId,
+            total_students: realStudents.length,
+            submitted: submittedIds.size,
+            pending
+        };
+    }
     async createQuiz(courseId, quiz) {
         const response = await this.client.post(`courses/${courseId}/quizzes`, {
             quiz: quiz
@@ -699,4 +848,41 @@ export class CanvasClient {
         await this.quizClient.delete(`courses/${courseId}/quizzes/${quizId}/items/${itemId}`);
         return { deleted: true };
     }
+    // --- Access Tokens ---
+    async listAccessTokens(userId = 'self') {
+        return this.getAllPages(`users/${userId}/user_generated_tokens`, { per_page: 100 });
+    }
+    async getAccessToken(userId = 'self', tokenId) {
+        const response = await this.client.get(`users/${userId}/tokens/${tokenId}`);
+        return response.data;
+    }
+    async createAccessToken(userId = 'self', data) {
+        const response = await this.client.post(`users/${userId}/tokens`, { token: data });
+        return response.data;
+    }
+    async updateAccessToken(userId = 'self', tokenId, data) {
+        const response = await this.client.put(`users/${userId}/tokens/${tokenId}`, { token: data });
+        return response.data;
+    }
+    async deleteAccessToken(userId = 'self', tokenId) {
+        await this.client.delete(`users/${userId}/tokens/${tokenId}`);
+        return { deleted: true };
+    }
+    // Convenience wrapper around updateAccessToken({ regenerate: true }) that, when the
+    // regenerated token is the one currently authenticating this client, also hot-swaps
+    // and persists it so the MCP server keeps working without a manual reconfiguration.
+    async regenerateAccessToken(userId = 'self', tokenId) {
+        const result = await this.updateAccessToken(userId, tokenId, { regenerate: true });
+        const isActiveToken = userId === 'self' && this.tokenMeta?.id === Number(tokenId);
+        if (isActiveToken && result.token) {
+            this.applyNewToken(result.token);
+            this.onTokenRenewed?.(result.token);
+            this.tokenMeta = {
+                id: this.tokenMeta.id,
+                expiresAtMs: result.expires_at ? new Date(result.expires_at).getTime() : null
+            };
+            this.tokenMetaCheckedAt = Date.now();
+        }
+        return result;
+    }
 }

package/dist/tools/access-token-tools.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+const userIdSchema = z.union([z.number(), z.string()]).optional();
+export const accessTokenTools = [
+    {
+        name: "canvas_list_access_tokens",
+        tool: {
+            name: "canvas_list_access_tokens",
+            description: "List manually-generated Canvas API access tokens for a user (defaults to the authenticated user)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    user_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "User ID, or 'self' for the authenticated user (default)"
+                    }
+                }
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({ user_id: userIdSchema }).parse(args ?? {});
+            const result = await client.listAccessTokens(input.user_id ?? 'self');
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    },
+    {
+        name: "canvas_get_access_token",
+        tool: {
+            name: "canvas_get_access_token",
+            description: "Get details of a specific Canvas access token by its database ID or token_hint",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    user_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "User ID, or 'self' for the authenticated user (default)"
+                    },
+                    token_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The token's database ID or its token_hint"
+                    }
+                },
+                required: ["token_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                user_id: userIdSchema,
+                token_id: z.union([z.number(), z.string()])
+            }).parse(args);
+            const result = await client.getAccessToken(input.user_id ?? 'self', input.token_id);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    },
+    {
+        name: "canvas_create_access_token",
+        tool: {
+            name: "canvas_create_access_token",
+            description: "Create a new Canvas API access token. The full token value is returned only in this response — save it, it cannot be retrieved again later.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    user_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "User ID, or 'self' for the authenticated user (default)"
+                    },
+                    purpose: { type: "string", description: "Description of what the token is for" },
+                    expires_at: { type: "string", description: "ISO 8601 datetime when the token should expire (omit for no expiration)" },
+                    scopes: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "API scopes to restrict the token to (ignored unless the account has scoped tokens enabled)"
+                    }
+                },
+                required: ["purpose"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                user_id: userIdSchema,
+                purpose: z.string(),
+                expires_at: z.string().optional(),
+                scopes: z.array(z.string()).optional()
+            }).parse(args);
+            const { user_id, ...data } = input;
+            const result = await client.createAccessToken(user_id ?? 'self', data);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    },
+    {
+        name: "canvas_update_access_token",
+        tool: {
+            name: "canvas_update_access_token",
+            description: "Update a Canvas access token's purpose, expiration, or scopes",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    user_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "User ID, or 'self' for the authenticated user (default)"
+                    },
+                    token_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The token's database ID or its token_hint"
+                    },
+                    purpose: { type: "string", description: "New description of what the token is for" },
+                    expires_at: { type: "string", description: "New ISO 8601 expiration datetime, or null to remove expiration" },
+                    scopes: { type: "array", items: { type: "string" }, description: "New API scopes for the token" }
+                },
+                required: ["token_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                user_id: userIdSchema,
+                token_id: z.union([z.number(), z.string()]),
+                purpose: z.string().optional(),
+                expires_at: z.string().nullable().optional(),
+                scopes: z.array(z.string()).optional()
+            }).parse(args);
+            const { user_id, token_id, ...data } = input;
+            const result = await client.updateAccessToken(user_id ?? 'self', token_id, data);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    },
+    {
+        name: "canvas_regenerate_access_token",
+        tool: {
+            name: "canvas_regenerate_access_token",
+            description: "Regenerate a Canvas access token, issuing a new token value while keeping its purpose/scopes. If the regenerated token is the one currently authenticating this MCP server, it is automatically applied and persisted so the server keeps working without reconfiguration.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    user_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "User ID, or 'self' for the authenticated user (default)"
+                    },
+                    token_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The token's database ID or its token_hint"
+                    }
+                },
+                required: ["token_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                user_id: userIdSchema,
+                token_id: z.union([z.number(), z.string()])
+            }).parse(args);
+            const result = await client.regenerateAccessToken(input.user_id ?? 'self', input.token_id);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    },
+    {
+        name: "canvas_delete_access_token",
+        tool: {
+            name: "canvas_delete_access_token",
+            description: "Permanently delete a Canvas access token",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    user_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "User ID, or 'self' for the authenticated user (default)"
+                    },
+                    token_id: {
+                        anyOf: [{ type: "number" }, { type: "string" }],
+                        description: "The token's database ID or its token_hint"
+                    }
+                },
+                required: ["token_id"]
+            }
+        },
+        handler: async (client, args) => {
+            const input = z.object({
+                user_id: userIdSchema,
+                token_id: z.union([z.number(), z.string()])
+            }).parse(args);
+            const result = await client.deleteAccessToken(input.user_id ?? 'self', input.token_id);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+    }
+];

package/dist/tools/module-tools.js

@@ -63,7 +63,7 @@ export const moduleTools = [
         name: "canvas_update_module",
         tool: {
             name: "canvas_update_module",
-            description: "Update an existing module",
+            description: "Update an existing module (name, published, position, prerequisites, completion requirements)",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -74,7 +74,32 @@ export const moduleTools = [
                     module_id: { type: "number", description: "The ID of the module" },
                     name: { type: "string", description: "The new name of the module" },
                     published: { type: "boolean", description: "Whether the module is published" },
-                    position: { type: "number", description: "The new position of the module" }
+                    position: { type: "number", description: "The new position of the module" },
+                    prerequisite_module_ids: {
+                        type: "array",
+                        items: { type: "number" },
+                        description: "IDs of modules that must be completed before this one unlocks"
+                    },
+                    require_sequential_progress: {
+                        type: "boolean",
+                        description: "Whether items in the module must be completed in order"
+                    },
+                    completion_requirements: {
+                        type: "array",
+                        description: "Completion requirements for module items. Replaces ALL existing requirements — include every item that needs one.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                id: { type: "number", description: "The module item ID" },
+                                type: {
+                                    type: "string",
+                                    description: "must_view, must_submit, must_contribute, min_score, must_mark_done"
+                                },
+                                min_score: { type: "number", description: "Required when type is min_score" }
+                            },
+                            required: ["id", "type"]
+                        }
+                    }
                 },
                 required: ["course_id", "module_id"],
             },
@@ -85,13 +110,23 @@ export const moduleTools = [
                 module_id: z.number(),
                 name: z.string().optional(),
                 published: z.boolean().optional(),
-                position: z.number().optional()
+                position: z.number().optional(),
+                prerequisite_module_ids: z.array(z.number()).optional(),
+                require_sequential_progress: z.boolean().optional(),
+                completion_requirements: z.array(z.object({
+                    id: z.number(),
+                    type: z.string(),
+                    min_score: z.number().optional()
+                })).optional()
             }).parse(args);
             const courseId = await resolveCourseId(client, input.course_id);
             const module = await client.updateModule(courseId, input.module_id, {
                 name: input.name,
                 published: input.published,
-                position: input.position
+                position: input.position,
+                prerequisite_module_ids: input.prerequisite_module_ids,
+                require_sequential_progress: input.require_sequential_progress,
+                completion_requirements: input.completion_requirements
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(module, null, 2) }],
@@ -206,7 +241,11 @@ export const moduleTools = [
                     position: { type: "number", description: "The new position of the item" },
                     indent: { type: "number", description: "The new level of indentation (0-3)" },
                     published: { type: "boolean", description: "Whether the item is published" },
-                    new_module_id: { type: "number", description: "Move the item to a new module" }
+                    new_module_id: { type: "number", description: "Move the item to a new module" },
+                    completion_requirement_type: {
+                        type: "string",
+                        description: "Completion requirement type: must_view, must_submit, must_contribute, min_score, must_mark_done"
+                    }
                 },
                 required: ["course_id", "module_id", "item_id"],
             },
@@ -220,7 +259,8 @@ export const moduleTools = [
                 position: z.number().optional(),
                 indent: z.number().optional(),
                 published: z.boolean().optional(),
-                new_module_id: z.number().optional()
+                new_module_id: z.number().optional(),
+                completion_requirement_type: z.string().optional()
             }).parse(args);
             const courseId = await resolveCourseId(client, input.course_id);
             const result = await client.updateModuleItem(courseId, input.module_id, input.item_id, {
@@ -228,7 +268,10 @@ export const moduleTools = [
                 position: input.position,
                 indent: input.indent,
                 published: input.published,
-                module_id: input.new_module_id
+                module_id: input.new_module_id,
+                ...(input.completion_requirement_type && {
+                    completion_requirement: { type: input.completion_requirement_type }
+                })
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],