Canvas Assignment Assistant

# Canvas MCP Server - Developer Documentation This document provides comprehensive information about the Canvas MCP Server codebase for AI assistants and developers. ## Project Overview **Canvas MCP Server** is a Model Context Protocol (MCP) server that integrates with Canvas LMS (Learning Management System by Instructure). It enables users to interact with Canvas courses and assignments directly from MCP clients like Claude Desktop or Cursor IDE. ### Key Features - List courses (active, completed, or all) - Search assignments across courses with advanced filtering - Retrieve detailed assignment information with formatting options - Access assignment content via MCP resources ## Architecture & File Structure The codebase follows standard Node.js/TypeScript project organization: ``` src/ ├── index.ts # Main entry point - orchestrates all components ├── config/ │ └── environment.ts # Environment variable validation & setup ├── types/ │ └── canvas.ts # TypeScript interfaces for Canvas API ├── api/ │ └── canvas-client.ts # Canvas API request handler & credentials ├── utils/ │ ├── html.ts # HTML parsing & conversion utilities │ └── date.ts # Date formatting & validation ├── tools/ │ ├── list-courses.ts # list_courses tool implementation │ ├── list-active-courses.ts # canvas_list_active_courses tool │ ├── search-assignments.ts # search_assignments tool │ └── get-assignment.ts # get_assignment tool └── resources/ └── assignment-content.ts # assignment_content resource ``` ## Core Components ### 1. Entry Point (`src/index.ts`) - Creates and configures the MCP server - Registers all tools and resources - Manages server lifecycle (startup/shutdown) - **Pattern**: Orchestrator that imports and wires up all components ### 2. Configuration (`src/config/environment.ts`) - Validates required environment variables (`CANVAS_API_TOKEN`, `CANVAS_DOMAIN`) - Authenticates with Canvas API on startup - Provides helpful error messages for misconfiguration - **Export**: `validateSetup()` async function ### 3. Type Definitions (`src/types/canvas.ts`) All Canvas API response interfaces: - `CanvasUser`: User profile and authentication - `CanvasCourse`: Course information with term details - `CanvasAssignment`: Comprehensive assignment metadata (50+ fields) - `CourseWithAssignments`: Extended type for search operations - `AssignmentWithCourse`: Assignment with course context ### 4. API Client (`src/api/canvas-client.ts`) - **Base URL**: `https://{CANVAS_DOMAIN}/api/v1` - **Authentication**: Bearer token via `CANVAS_API_TOKEN` - **Main Function**: `canvasApiRequest<T>(path, method?, body?)` - Typed HTTP requests - **Exports**: - `canvasApiRequest<T>()` - Generic API request handler - `getBaseUrl()` - Returns Canvas API base URL - `getCanvasApiToken()` - Returns API token (for validation) - `getCanvasDomain()` - Returns domain (for validation) ### 5. Utilities #### HTML Processing (`src/utils/html.ts`) - `htmlToPlainText(html)`: Extracts plain text from HTML - `convertHtmlToMarkdown(html)`: Converts HTML to Markdown format - Supports headers (h1-h3), bold, italic, lists, links - Preserves dollar signs (important for math notation) - `extractLinks(html)`: Extracts all hyperlinks with text and href #### Date Handling (`src/utils/date.ts`) - `formatDate(dateStr, format)`: Formats dates for display - Supports 'full' (with time) and 'date-only' formats - Handles invalid dates gracefully - `parseDate(dateStr)`: Parses ISO and YYYY-MM-DD formats - Treats YYYY-MM-DD as local timezone - `isDateInRange(date, before?, after?)`: Validates date ranges - Handles edge cases (null dates, parsing failures) - Sets proper time boundaries (start/end of day) ### 6. Tools (MCP Interface) All tools follow this registration pattern: ```typescript export function register[ToolName]Tool(server: McpServer) { server.tool(name, description, schema, handler); } ``` #### `list_courses` (`src/tools/list-courses.ts`) - **Purpose**: Lists courses with state filtering - **Parameters**: `state` (active|completed|all, default: active) - **Returns**: Course list with IDs, names, and terms #### `canvas_list_active_courses` (`src/tools/list-active-courses.ts`) - **Purpose**: Fast active course listing via dashboard API - **Parameters**: None - **Optimization**: Uses `/dashboard/dashboard_cards` endpoint - **Returns**: Course list with short names #### `search_assignments` (`src/tools/search-assignments.ts`) - **Purpose**: Search assignments across all courses - **Parameters**: - `query`: Search term (optional) - `dueBefore`: Date filter (YYYY-MM-DD) - `dueAfter`: Date filter (YYYY-MM-DD) - `includeCompleted`: Include completed courses (boolean) - `courseId`: Limit to specific course (optional) - **Features**: - Full-text search in titles and descriptions - Date range filtering with Canvas API bucket parameter - HTML-to-text conversion for description searching - Results sorted by due date - Error recovery (continues if one course fails) #### `get_assignment` (`src/tools/get-assignment.ts`) - **Purpose**: Retrieve detailed assignment information - **Parameters**: - `courseId`: Target course ID - `assignmentId`: Target assignment ID - `formatType`: Output format (full|plain|markdown, default: markdown) - **Returns**: Comprehensive assignment details including: - Submission requirements and file restrictions - Grading information and rubrics - Time restrictions (lock/unlock dates) - Special features (peer reviews, group assignments) - Plagiarism detection settings - Extracted links from description ### 7. Resources (`src/resources/assignment-content.ts`) - **URI Template**: `canvas://courses/{courseId}/assignments/{assignmentId}` - **Purpose**: Provides read-only access to assignment content - **Returns**: Markdown-formatted assignment with metadata ## Canvas API Integration ### Authentication - Uses Canvas REST API v1 - Requires personal access token (generate in Canvas account settings) - Token passed via `Authorization: Bearer {token}` header ### Error Handling - API errors include HTTP status and response body - Tools return `isError: true` for error responses - Search continues even if individual courses fail - Graceful degradation for missing/invalid data ### API Endpoints Used - `/users/self` - User authentication - `/courses` - Course listing - `/dashboard/dashboard_cards` - Active courses (optimized) - `/courses/{id}/assignments` - Assignment listing - `/courses/{id}/assignments/{id}` - Assignment details ## Build & Deployment ### Development Workflow ```bash npm install # Install dependencies npm run build # Compile TypeScript to dist/ npm start # Run the server npm run package # Create .mcpb distribution file ``` ### TypeScript Configuration - Target: ES2022 - Module: Node16 - Strict mode enabled - Output: `dist/` directory ### Distribution - **DXT/MCPB**: Packaged format for Claude Desktop/MCP clients - **Manifest**: `manifest.json` defines server metadata - **Entry Point**: `dist/index.js` ## Adding New Features ### Adding a New Tool 1. Create file in `src/tools/[tool-name].ts` 2. Export `register[ToolName]Tool(server: McpServer)` function 3. Import and call registration in `src/index.ts` 4. Add tool definition to `manifest.json` 5. Run `npm run build` ### Adding a New Utility 1. Create file in `src/utils/[utility-name].ts` 2. Export functions with clear type signatures 3. Import where needed in tools or other utilities ### Modifying Canvas API Types - Update interfaces in `src/types/canvas.ts` - Ensure type safety across all tool implementations - Consider backward compatibility with existing tools ## Best Practices ### Code Organization - Keep tools focused and single-purpose - Extract common logic into utilities - Use TypeScript types for all Canvas API responses - Follow existing naming conventions ### Error Handling - Always catch and handle API errors gracefully - Provide helpful error messages to users - Log debug information to stderr (not visible to MCP clients) - Continue processing when individual operations fail (e.g., course iteration) ### Performance - Use Canvas API pagination (`per_page=100`) - Leverage Canvas API filters (bucket, date ranges) before local filtering - Cache-friendly: stateless operations - Dashboard API preferred for active courses (faster) ### Security - Never log or expose API tokens - Mark sensitive fields in manifest.json (`sensitive: true`) - Validate all user input before API calls - Use environment variables for credentials ## Common Tasks ### Testing Locally ```bash # Set environment variables export CANVAS_API_TOKEN="your_token" export CANVAS_DOMAIN="canvas.youruniversity.edu" # Run the server npm start ``` ### Debugging - Check stderr output for authentication status - Look for "Successfully authenticated as..." message - Review API request URLs logged to stderr (in search_assignments) - Use TypeScript compiler for type checking before runtime ### Updating Dependencies ```bash npm update npm audit fix # Security updates npm run build # Verify build still works ``` ## Known Limitations - No support for submitting assignments (read-only) - Pagination limited to 100 items per course - Requires manual Canvas API token generation - No support for Canvas modules or pages - HTML conversion may not handle all edge cases ## Future Enhancement Ideas - Assignment submission support - Course module navigation - Quiz/test retrieval - Announcement fetching - Grade viewing - File download support - Caching layer for frequently accessed data - Batch operations for multiple assignments ## Troubleshooting ### "Canvas API token not set" - Ensure `CANVAS_API_TOKEN` environment variable is set - Check token validity in Canvas account settings ### "Canvas domain not set" - Ensure `CANVAS_DOMAIN` environment variable is set - Format: `canvas.youruniversity.edu` (no https://) ### "Authentication failed" - Verify token is still valid - Check domain is correct - Ensure token has necessary permissions ### Build Errors - Run `npm install` to ensure all dependencies are present - Check TypeScript version compatibility - Verify all imports use `.js` extensions (ES module requirement) ## Resources - Canvas API Documentation: https://canvas.instructure.com/doc/api/ - Model Context Protocol: https://modelcontextprotocol.io - TypeScript Documentation: https://www.typescriptlang.org/docs/