@charlie.act7/canvas-mcp-server 1.1.0 → 1.1.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "canvas-lms",
+  "description": "Canvas LMS integration for teachers. Manage courses, assignments, grades, quizzes, students, modules, and more — directly from Claude Code.",
+  "version": "1.1.0",
+  "author": {
+    "name": "CharlieCardenasToledo"
+  },
+  "homepage": "https://github.com/CharlieCardenasToledo/canvas-mcp-server",
+  "repository": "https://github.com/CharlieCardenasToledo/canvas-mcp-server",
+  "license": "MIT"
+}

package/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "canvas": {
+    "command": "npx",
+    "args": ["-y", "@charlie.act7/canvas-mcp-server"],
+    "env": {
+      "CANVAS_API_TOKEN": "${CANVAS_API_TOKEN}",
+      "CANVAS_API_DOMAIN": "${CANVAS_API_DOMAIN}"
+    }
+  }
+}

package/README.es.md

@@ -0,0 +1,173 @@
+# 🎓 Canvas LMS 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)
+
+**¡Lleva tu aula virtual de Canvas al siguiente nivel con Inteligencia Artificial!** 🚀
+
+Este proyecto es un servidor de **Model Context Protocol (MCP)** para **Canvas LMS**. En palabras sencillas, funciona como un "traductor" o puente que permite a asistentes de Inteligencia Artificial (como Claude Desktop, Claude Code, Cursor, etc.) comprender y realizar acciones en tus cursos de Canvas mediante instrucciones en lenguaje natural.
+
+---
+
+## 🔍 ¿Cómo funciona?
+
+Cuando utilizas este servidor, la comunicación fluye de la siguiente manera:
+
+```mermaid
+graph LR
+    User([Usuario]) -->|Instrucción en Lenguaje Natural| AI["Asistente de IA (Claude)"]
+    AI -->|Petición MCP| MCP["Canvas MCP Server"]
+    MCP -->|API REST (HTTPS)| Canvas["Canvas LMS"]
+    Canvas -->|Respuesta| MCP
+    MCP -->|Datos procesados| AI
+    AI -->|Respuesta amigable| User
+```
+
+1. **Tú le pides algo a Claude** (por ejemplo: *"Crea una tarea para el próximo viernes"*).
+2. **Claude detecta la intención** y se comunica con el **Canvas MCP Server** enviándole los parámetros necesarios.
+3. **El servidor realiza la llamada segura** a la API de Canvas.
+4. **Canvas procesa la acción** y devuelve el resultado.
+5. **Claude te confirma el éxito de la operación** en lenguaje natural.
+
+---
+
+## 💡 ¿Qué puedes pedirle a tu Asistente?
+
+¡Cualquier tarea administrativa o de consulta que harías manualmente en Canvas! Aquí tienes algunos ejemplos de lo que puedes pedirle:
+
+### 📖 Para Consultar Información
+* 💬 *"¿Qué cursos tengo activos este semestre?"*
+* 💬 *"Muéstrame las entregas pendientes de calificar para la Tarea 2 en Biología."*
+* 💬 *"¿Cuáles son los estudiantes del Grupo B de Química?"*
+* 💬 *"¿Qué cuestionarios o exámenes tenemos programados para esta semana?"*
+
+### ✍️ Para Administrar y Crear Contenido
+* 💬 *"Crea una nueva tarea llamada 'Ensayo final de Historia' con fecha de entrega para el próximo viernes."*
+* 💬 *"Publica un anuncio en el curso de Matemáticas avisando que la clase de mañana será virtual."*
+* 💬 *"Crea un nuevo módulo llamado 'Semana 5: Introducción a React' en mi curso."*
+
+### 💯 Para Calificar y Dar Retroalimentación
+* 💬 *"Califica el ensayo de María con un 90/100 y agrégale un comentario que diga: 'Excelente análisis crítico, continúa así'."*
+* 💬 *"Genera un reporte de las notas actuales de los alumnos del curso de Física."*
+
+---
+
+## 🛠️ Guía de Instalación Paso a Paso
+
+Para conectar tu asistente de IA a Canvas, necesitas configurar **dos cosas**: tus credenciales de Canvas y el cliente de IA (como Claude).
+
+### Paso 1: Obtener tus credenciales de Canvas LMS
+Para que el servidor pueda actuar en tu nombre, necesita permiso:
+1. Inicia sesión en tu cuenta de **Canvas LMS**.
+2. Dirígete a **Cuenta (Account)** ➡️ **Configuración (Settings)** en el menú lateral.
+3. Baja hasta la sección **Integraciones Aprobadas (Approved Integrations)** y haz clic en el botón **+ Nuevo token de acceso (+ New Access Token)**.
+4. Escribe un propósito (ej. "Asistente Claude") y haz clic en **Generar token**.
+5. **Copia el token generado inmediatamente** y guárdalo en un lugar seguro (no podrás volver a verlo después de cerrar la pantalla).
+
+> [!IMPORTANT]
+> También necesitarás el dominio de tu Canvas. Es la dirección web de tu escuela/universidad, por ejemplo: `miuniversidad.instructure.com`.
+
+---
+
+### Paso 2: Configurar tu Cliente de IA
+
+#### Opción A: Claude Desktop (Aplicación de Escritorio)
+1. Abre tu archivo de configuración de Claude Desktop. En Windows se encuentra en:
+   `%APPDATA%\Claude\claude_desktop_config.json`
+   *(En macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`)*
+2. Agrega la configuración del servidor Canvas bajo `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "npx",
+      "args": ["-y", "@charlie.act7/canvas-mcp-server"],
+      "env": {
+        "CANVAS_API_TOKEN": "TU_TOKEN_DE_ACCESO_AQUÍ",
+        "CANVAS_API_DOMAIN": "miuniversidad.instructure.com"
+      }
+    }
+  }
+}
+```
+3. Guarda el archivo y reinicia Claude Desktop. Verás un icono de enchufe indicando que el servidor está conectado.
+
+#### Opción B: Claude Code (Terminal)
+Si utilizas la herramienta de línea de comandos Claude Code, simplemente instala el plugin ejecutando:
+```bash
+/plugin install canvas-lms@claude-community
+```
+Luego, configura tus credenciales de forma interactiva:
+```bash
+/canvas-lms:config
+```
+
+---
+
+## 💻 Configuración Interactiva por Consola (CLI)
+Si prefieres configurar las credenciales de manera local e interactiva en tu terminal para desarrollo, puedes ejecutar:
+```bash
+npx @charlie.act7/canvas-mcp-server config
+```
+Esto te pedirá el dominio y tu API token paso a paso, guardándolos de forma segura en un archivo de configuración local.
+
+---
+
+<details>
+<summary>🛠️ <b>Ver Lista Detallada de Herramientas Soportadas (Técnico)</b></summary>
+
+El servidor expone internamente las siguientes herramientas organizadas por categorías:
+
+| Categoría | Herramientas Incluidas |
+|---|---|
+| **Cursos (Courses)** | Listar cursos, detalles del curso, configuración básica |
+| **Módulos (Modules)** | Listar y gestionar módulos del curso |
+| **Páginas (Pages)** | Listar páginas de contenido, leer el HTML de una página |
+| **Archivos (Files)** | Listar archivos cargados en el curso |
+| **Anuncios (Announcements)** | Listar y crear anuncios para el curso |
+| **Tareas (Assignments)** | Listar, crear, actualizar tareas y modificar fechas de entrega masivamente |
+| **Entregas (Submissions)** | Ver entregas y archivos adjuntos de alumnos |
+| **Calificaciones (Grading)** | Calificar entregas de tareas, auditar notas del curso |
+| **Exámenes (Quizzes)** | Listar quizzes, gestionar preguntas y modificar fechas límite |
+| **Estudiantes (Students)** | Roster de alumnos, progreso de aprendizaje y detalles |
+| **Grupos (Groups)** | Listar y gestionar grupos de estudiantes |
+| **Calendario (Calendar)** | Listar y crear eventos o recordatorios en la agenda |
+| **Rúbricas (Rubrics)** | Crear y gestionar rúbricas de evaluación |
+| **Comunicación (Communication)** | Enviar mensajes directos, gestionar foros y discusiones |
+
+### Recursos MCP Soportados
+Para clientes compatibles con recursos directos:
+* `canvas://courses/{id}/readme` — Resumen general formateado de un curso.
+* `canvas://courses/{id}/pages/{slug}` — Contenido HTML directo de páginas de Canvas.
+</details>
+
+---
+
+## 🛠️ Desarrollo Local (Para Programadores)
+
+Si deseas clonar este repositorio y hacer modificaciones:
+
+1. **Instalar Dependencias:**
+   ```bash
+   npm install
+   ```
+2. **Compilar el Proyecto (TypeScript a JavaScript):**
+   ```bash
+   npm run build
+   ```
+3. **Ejecutar Servidor en Modo Stdio (MCP):**
+   ```bash
+   npm start
+   ```
+4. **Ejecutar Servidor HTTP con Documentación Swagger:**
+   Si deseas utilizarlo como una acción de GPTs de OpenAI, levanta el servidor web con:
+   ```bash
+   npm run start:http
+   ```
+   Si deseas ver la interfaz interactiva de Swagger, visita `http://localhost:3000`.
+
+---
+
+## 📄 Licencia
+Este proyecto está bajo la licencia MIT. Creado por [Charlie Cárdenas Toledo](https://github.com/charlie-act7).

package/README.md

@@ -1,15 +1,81 @@
-# Canvas MCP Server
+# 🎓 Canvas LMS 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.
+**Bring AI to your Canvas Virtual Classroom!** 🚀
 
-## Quick Start (Claude Desktop / Claude Code)
+This project is a **Model Context Protocol (MCP)** server for **Canvas LMS**. In simple terms, it acts as a "translator" or bridge that allows AI assistants (like Claude Desktop, Claude Code, Cursor, etc.) to understand and perform actions in your Canvas courses using natural language.
 
-### Option 1: npx (recommended — no install needed)
+---
 
-Add this to your `claude_desktop_config.json`:
+## 🔍 How It Works
+
+When you interact with the server, communication flows as follows:
+
+```mermaid
+graph LR
+    User([User]) -->|Natural Language Instruction| AI["AI Assistant (e.g., Claude)"]
+    AI -->|MCP Request| MCP["Canvas MCP Server"]
+    MCP -->|REST API (HTTPS)| Canvas["Canvas LMS"]
+    Canvas -->|Response| MCP
+    MCP -->|Processed Data| AI
+    AI -->|Friendly Answer| User
+```
+
+1. **You ask Claude for something** (e.g., *"Create an assignment due next Friday"*).
+2. **Claude detects your intent** and communicates with the **Canvas MCP Server**, sending the required parameters.
+3. **The server makes a secure call** to the official Canvas API.
+4. **Canvas processes the action** and returns the result.
+5. **Claude confirms the success of the action** back to you in plain, natural language.
+
+---
+
+## 💡 What Can You Ask Your Assistant?
+
+Anything you would normally do manually in Canvas! Here are some everyday examples:
+
+### 📖 Querying Information
+* 💬 *"What active courses do I have this semester?"*
+* 💬 *"Show me the ungraded submissions for Assignment 2 in Biology."*
+* 💬 *"Who is in Group B of my Chemistry class?"*
+* 💬 *"What quizzes or exams are scheduled for this week?"*
+
+### ✍️ Creating and Managing Content
+* 💬 *"Create a new assignment named 'History Term Paper' due next Friday."*
+* 💬 *"Post an announcement in my Math course letting everyone know tomorrow's lecture is online."*
+* 💬 *"Create a new module named 'Week 5: Introduction to React' in my course."*
+
+### 💯 Grading & Giving Feedback
+* 💬 *"Grade Maria's essay with a 90/100 and add a comment saying: 'Excellent critical analysis, keep it up!'"*
+* 💬 *"Give me a summary of current student grades in the Physics course."*
+
+---
+
+## 🛠️ Step-by-Step Setup Guide
+
+To connect your AI assistant to Canvas, you need to configure **two things**: your Canvas credentials and your AI client (like Claude).
+
+### Step 1: Obtain your Canvas credentials
+To let the server act on your behalf, it needs permission:
+1. Log in to your **Canvas LMS** account.
+2. Go to **Account** ➡️ **Settings** in the sidebar menu.
+3. Scroll down to the **Approved Integrations** section and click **+ New Access Token**.
+4. Enter a purpose (e.g., "Claude Assistant") and click **Generate Token**.
+5. **Copy the generated token immediately** and store it somewhere safe (you won't be able to see it again after closing the page).
+
+> [!IMPORTANT]
+> You will also need your Canvas Domain. This is the web address of your school/university, for example: `myschool.instructure.com`.
+
+---
+
+### Step 2: Connect to your AI Client
+
+#### Option A: Claude Desktop (Desktop Application)
+1. Open your Claude Desktop configuration file. On Windows, it is located at:
+   `%APPDATA%\Claude\claude_desktop_config.json`
+   *(On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`)*
+2. Add the Canvas server configuration under `mcpServers`:
 
 ```json
 {
@@ -18,100 +84,90 @@ Add this to your `claude_desktop_config.json`:
       "command": "npx",
       "args": ["-y", "@charlie.act7/canvas-mcp-server"],
       "env": {
-        "CANVAS_API_TOKEN": "your_token_here",
-        "CANVAS_API_DOMAIN": "your_school.instructure.com"
+        "CANVAS_API_TOKEN": "YOUR_ACCESS_TOKEN_HERE",
+        "CANVAS_API_DOMAIN": "myschool.instructure.com"
       }
     }
   }
 }
 ```
+3. Save the file and restart Claude Desktop. You will see a socket/plug icon indicating the server is successfully connected.
 
-### 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"
-      ]
-    }
-  }
-}
+#### Option B: Claude Code (Terminal CLI)
+If you are using the Claude Code terminal tool, install the plugin by running:
+```bash
+/plugin install canvas-lms@claude-community
 ```
-
-> **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
-
+Then, configure your credentials interactively:
 ```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
+/canvas-lms:config
 ```
 
-The HTTP server runs on `http://localhost:3000`:
-- Swagger UI: `http://localhost:3000/docs`
-- OpenAPI JSON: `http://localhost:3000/openapi.json`
+---
 
-## Deploy on Render
+## 💻 Interactive Console Configuration (CLI)
+If you prefer to configure your credentials locally for development, run:
+```bash
+npx @charlie.act7/canvas-mcp-server config
+```
+This will guide you step-by-step to input your domain and API token, storing them securely in a local configuration file.
 
-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`)
+<details>
+<summary>🛠️ <b>View Detailed List of Supported Tools (Technical)</b></summary>
 
-## License
+The server exposes the following tools organized by category:
 
-MIT © Charlie Cárdenas Toledo
+| Category | Included Tools |
+|---|---|
+| **Courses** | List courses, get course details, set basic configuration |
+| **Modules** | List and manage course modules |
+| **Pages** | List pages, read page content HTML |
+| **Files** | List files uploaded to a course |
+| **Announcements** | List and create announcements |
+| **Assignments** | List, create, and update assignments; bulk update due dates |
+| **Submissions** | View student submissions and attachments |
+| **Grading** | Grade submissions, audit course grades |
+| **Quizzes** | List quizzes, manage questions, update quiz dates |
+| **Students** | Course roster, progress tracking, and student details |
+| **Groups** | List and manage student groups |
+| **Calendar** | List and create calendar events/reminders |
+| **Rubrics** | Create and manage grading rubrics |
+| **Communication** | Send direct messages, manage discussions and threads |
+
+### Supported MCP Resources
+For clients supporting direct resources:
+* `canvas://courses/{id}/readme` — Formatted course summary.
+* `canvas://courses/{id}/pages/{slug}` — Direct HTML content of Canvas pages.
+</details>
+
+---
+
+## 🛠️ Local Development (For Developers)
+
+To clone this repository and modify the code:
+
+1. **Install Dependencies:**
+   ```bash
+   npm install
+   ```
+2. **Build the Project (TypeScript to JavaScript):**
+   ```bash
+   npm run build
+   ```
+3. **Start Server in Stdio Mode (MCP):**
+   ```bash
+   npm start
+   ```
+4. **Start HTTP Server with Swagger Documentation:**
+   If you want to use this as an OpenAI GPT Custom Action, spin up the web server with:
+   ```bash
+   npm run start:http
+   ```
+   Then visit `http://localhost:3000` to view the interactive Swagger interface.
+
+---
+
+## 📄 License
+This project is licensed under the MIT License. Created by [Charlie Cárdenas Toledo](https://github.com/charlie-act7).

package/llms-install.md

@@ -0,0 +1,46 @@
+# Canvas LMS MCP Server — Installation Guide for AI Agents
+
+This server requires two environment variables to function.
+
+## Required Environment Variables
+
+| Variable | Description | Example |
+|---|---|---|
+| `CANVAS_API_TOKEN` | Canvas LMS personal access token | `1234~abcXYZ...` |
+| `CANVAS_API_DOMAIN` | Hostname of the Canvas instance (no `https://`) | `myschool.instructure.com` |
+
+## How to Get a Canvas API Token
+
+1. Log in to Canvas at your institution's URL
+2. Click your profile picture → **Settings**
+3. Scroll to **Approved Integrations**
+4. Click **+ New Access Token**
+5. Give it a name and click **Generate Token**
+6. Copy the token immediately — it will not be shown again
+
+## MCP Configuration
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "npx",
+      "args": ["-y", "@charlie.act7/canvas-mcp-server"],
+      "env": {
+        "CANVAS_API_TOKEN": "<paste token here>",
+        "CANVAS_API_DOMAIN": "<your school>.instructure.com"
+      }
+    }
+  }
+}
+```
+
+## Verification
+
+After installation, ask the AI: *"List my Canvas courses"*. If credentials are correct, it will return your active courses.
+
+## Troubleshooting
+
+- **401 Unauthorized**: Token is invalid or expired — generate a new one in Canvas Settings
+- **404 Not Found**: Check that `CANVAS_API_DOMAIN` does not include `https://` — use the hostname only
+- **No courses returned**: Ensure you are enrolled in at least one active course as a Teacher or Admin

package/package.json

@@ -3,7 +3,7 @@
     "publishConfig": {
         "access": "public"
     },
-    "version": "1.1.0",
+    "version": "1.1.2",
     "description": "MCP Server for Canvas LMS - Use AI to interact with your courses, assignments, and grades.",
     "main": "dist/index.js",
     "bin": {
@@ -18,7 +18,10 @@
         "dist/resources",
         "dist/services",
         "dist/tools",
-        "README.md"
+        "README.md",
+        "llms-install.md",
+        ".claude-plugin",
+        ".mcp.json"
     ],
     "scripts": {
         "build": "tsc",