@charlie.act7/canvas-mcp-server 1.1.0

package/README.md

@@ -0,0 +1,117 @@
+# Canvas MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@charlie.act7/canvas-mcp-server)](https://www.npmjs.com/package/@charlie.act7/canvas-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for **Canvas LMS**. Lets AI agents (Claude, etc.) interact with your courses, assignments, grades, quizzes, modules, files, and more — all through natural language.
+
+## Quick Start (Claude Desktop / Claude Code)
+
+### Option 1: npx (recommended — no install needed)
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "npx",
+      "args": ["-y", "@charlie.act7/canvas-mcp-server"],
+      "env": {
+        "CANVAS_API_TOKEN": "your_token_here",
+        "CANVAS_API_DOMAIN": "your_school.instructure.com"
+      }
+    }
+  }
+}
+```
+
+### Option 2: Docker
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-e", "CANVAS_API_TOKEN=your_token_here",
+        "-e", "CANVAS_API_DOMAIN=your_school.instructure.com",
+        "charliecardenas/canvas-mcp"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** Build the image first: `docker build -t charliecardenas/canvas-mcp .`
+
+## Getting Your Canvas Credentials
+
+1. Log in to Canvas
+2. Go to **Account → Settings**
+3. Scroll to **Approved Integrations** → click **New Access Token**
+4. Copy the token — you won't see it again
+
+Your domain is the hostname of your Canvas instance (e.g. `uide.instructure.com`).
+
+## Available Tools
+
+| Category | Tools |
+|---|---|
+| **Courses** | `canvas_list_courses`, `set_canvas_config` |
+| **Modules** | `canvas_list_modules` |
+| **Pages** | `canvas_list_pages`, `canvas_get_page_content` |
+| **Files** | `canvas_list_files` |
+| **Announcements** | `canvas_list_announcements` |
+| **Assignments** | `canvas_get_assignments`, `canvas_get_submissions` |
+| **Grading** | `canvas_grade_submission`, `canvas_audit_course` |
+| **Quizzes** | Quiz listing and question management |
+| **Students** | Student roster and progress |
+| **Groups** | Group management |
+| **Calendar** | Calendar events |
+| **Rubrics** | Rubric creation and management |
+| **Create** | Create assignments, pages, announcements |
+| **Communication** | Messaging and discussions |
+
+## Resources
+
+MCP clients that support resources can access Canvas content directly:
+
+- `canvas://courses/{id}/readme` — Course summary
+- `canvas://courses/{id}/pages/{slug}` — Page HTML content
+
+## Local Development
+
+```bash
+# Install dependencies
+npm install
+
+# Configure credentials interactively
+npx canvas-mcp config
+
+# Build
+npm run build
+
+# Start MCP server (stdio)
+npm start
+
+# Start HTTP API (for GPT Builder / OpenAPI)
+npm run start:http
+```
+
+The HTTP server runs on `http://localhost:3000`:
+- Swagger UI: `http://localhost:3000/docs`
+- OpenAPI JSON: `http://localhost:3000/openapi.json`
+
+## Deploy on Render
+
+This repo includes `render.yaml` for one-click deploy as a Web Service.
+
+Required environment variables:
+- `CANVAS_API_TOKEN`
+- `CANVAS_API_DOMAIN` (e.g. `your-school.instructure.com`)
+
+## License
+
+MIT © Charlie Cárdenas Toledo

package/dist/common/config-manager.js

@@ -0,0 +1,28 @@
+import Conf from 'conf';
+export class ConfigManager {
+    conf;
+    constructor() {
+        this.conf = new Conf({
+            projectName: 'canvas-mcp-server',
+            projectSuffix: ''
+        });
+    }
+    set(key, value) {
+        this.conf.set(key, value);
+    }
+    get(key) {
+        return this.conf.get(key);
+    }
+    getAll() {
+        return this.conf.store;
+    }
+    clear() {
+        this.conf.clear();
+    }
+    hasConfig() {
+        return this.conf.has('CANVAS_API_TOKEN') && this.conf.has('CANVAS_API_DOMAIN');
+    }
+    get path() {
+        return this.conf.path;
+    }
+}

package/dist/common/helpers.js

@@ -0,0 +1,46 @@
+export async function resolveCourseId(client, courseIdentifier) {
+    // If it's already a number or a string that looks like a number, return it as number
+    if (typeof courseIdentifier === 'number') {
+        return courseIdentifier;
+    }
+    if (!isNaN(Number(courseIdentifier))) {
+        return Number(courseIdentifier);
+    }
+    // It's a string (name), so we need to search for it
+    const courses = await client.getCourses();
+    const searchTerm = courseIdentifier.toLowerCase();
+    const matchedCourse = courses.find(course => {
+        const name = (course.name || "").toLowerCase();
+        const originalName = (course.original_name || "").toLowerCase(); // Cast to string as it might be missing in type def but present in API
+        const code = (course.course_code || "").toLowerCase();
+        return name.includes(searchTerm) || originalName.includes(searchTerm) || code.includes(searchTerm);
+    });
+    if (matchedCourse) {
+        return matchedCourse.id;
+    }
+    throw new Error(`Course not found matching: "${courseIdentifier}". Please provide a valid Course ID or a more specific name.`);
+}
+export async function resolveStudentId(client, courseId, studentIdentifier) {
+    if (typeof studentIdentifier === "number") {
+        return studentIdentifier;
+    }
+    if (!isNaN(Number(studentIdentifier))) {
+        return Number(studentIdentifier);
+    }
+    const students = await client.getEnrollments(courseId);
+    const searchTerm = studentIdentifier.toLowerCase();
+    const matchedStudent = students.find((student) => {
+        const name = (student.name || "").toLowerCase();
+        const sortableName = (student.sortable_name || "").toLowerCase();
+        const email = (student.email || "").toLowerCase();
+        const login = (student.login_id || "").toLowerCase();
+        return (name.includes(searchTerm) ||
+            sortableName.includes(searchTerm) ||
+            email.includes(searchTerm) ||
+            login.includes(searchTerm));
+    });
+    if (matchedStudent) {
+        return matchedStudent.id;
+    }
+    throw new Error(`Student not found matching: "${studentIdentifier}". Please provide a valid student ID or a more specific name.`);
+}

package/dist/common/tool-model.js

@@ -0,0 +1 @@
+export {};

package/dist/common/types.js

@@ -0,0 +1 @@
+export {};