canvas-mcp

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Canvas MCP Development Guide

Environment Setup

• Install uv package manager: pip install uv
• Install dependencies: uv pip install -e .
• Create .env file with CANVAS_API_TOKEN and CANVAS_API_URL
• Server installed as CLI command: canvas-mcp-server

Commands

• Start server: canvas-mcp-server (or ./start_canvas_server.sh for legacy setup)
• Test server: canvas-mcp-server --test
• View config: canvas-mcp-server --config
• Claude Desktop config: Update ~/Library/Application Support/Claude/claude_desktop_config.json

Repository Structure

canvas-mcp/
├── src/canvas_mcp/        # Main application code
│   ├── core/             # Core utilities (client, config, validation)
│   ├── tools/            # MCP tool implementations
│   ├── resources/        # MCP resources and prompts
│   └── server.py         # FastMCP server entry point
├── docs/                 # Essential documentation
├── archive/              # Legacy code and development specs (git-ignored)
├── .env                  # Configuration
└── start_canvas_server.sh # Server startup script

Architecture Overview

Core Design Patterns

• FastMCP framework: Built on FastMCP for robust MCP server implementation with proper tool registration
• Type-driven validation: All MCP tools use @validate_params decorator with sophisticated Union/Optional type handling
• Dual-layer caching: Bidirectional course code ↔ ID mapping via course_code_to_id_cache and id_to_course_code_cache
• Flexible identifiers: Support for Canvas IDs, course codes, and SIS IDs through get_course_id() abstraction
• ISO 8601 standardization: All dates converted via format_date() and parse_date() functions

MCP Tool Organization

• Progressive disclosure: List → Details → Content → Analytics pattern
• Functional grouping: Tools organized by Canvas entity (courses, assignments, discussions, messaging, etc.)
• Consistent naming: {action}_{entity}[_{specifier}] pattern
• Educational analytics focus: Student performance, completion rates, missing work identification
• Discussion workflow: Browse → View → Read → Reply pattern for student interaction
• Messaging workflow: Analytics → Target → Template → Send pattern for automated communications

API Layer Architecture

• Centralized requests: All Canvas API calls go through make_canvas_request()
• Form data support: Messaging endpoints use use_form_data=True for Canvas compatibility
• Automatic pagination: fetch_all_paginated_results() handles Canvas pagination transparently
• Async throughout: All I/O operations use async/await
• Graceful error handling: Returns JSON error responses rather than raising exceptions
• Privacy protection: Student data anonymization via configurable anonymize_response_data()

Key Components

Parameter Validation System

• validate_parameter(): Runtime type coercion supporting complex types
• @validate_params: Automatic validation decorator for all MCP tools
• Handles Union types, Optional types, string→JSON conversion, comma-separated lists

Course Identifier Handling

• get_course_id(): Converts any identifier type to Canvas ID
• get_course_code(): Reverse lookup from ID to human-readable code
• refresh_course_cache(): Rebuilds identifier mapping from Canvas API

Analytics Engine

• get_student_analytics(): Multi-dimensional educational data analysis
• get_assignment_analytics(): Statistical performance analysis with grade distribution
• get_peer_review_completion_analytics(): Peer review tracking and completion analysis
• get_peer_review_comments(): Extract actual peer review comment text and analysis
• analyze_peer_review_quality(): Comprehensive comment quality analysis with metrics
• identify_problematic_peer_reviews(): Automated flagging of low-quality reviews
• Temporal filtering (current vs. all assignments)
• Risk identification and performance categorization

Messaging System

• send_conversation(): Core Canvas messaging with form data support
• send_peer_review_reminders(): Automated peer review reminder workflow
• send_peer_review_followup_campaign(): Complete analytics → messaging pipeline
• MessageTemplates: Flexible template system for various communication types
• Privacy-aware: Works with anonymization while preserving functional user IDs

Coding Standards

• Type hints: Mandatory for all functions, use Union/Optional appropriately
• MCP tools: Use @mcp.tool() decorator with @validate_params
• Async functions: All API interactions must be async
• Course identifiers: Use Union[str, int] and get_course_id() for flexibility
• Date handling: Use format_date() for all date outputs
• Error responses: Return JSON strings with “error” key for failures
• Form data: Use use_form_data=True for Canvas messaging endpoints
• Privacy: Student IDs preserved, names anonymized in _should_anonymize_endpoint()

Discussion Forum Interaction Workflow

• Browse discussions: list_discussion_topics(course_id) - Find available discussion forums
• View student posts: list_discussion_entries(course_id, topic_id) - See all posts in a discussion
• Read full content: get_discussion_entry_details(course_id, topic_id, entry_id) - Get complete student comment
• Reply to students: reply_to_discussion_entry(course_id, topic_id, entry_id, "Your response") - Respond to student comments
• Create discussions: create_discussion_topic(course_id, title, message) - Start new discussion forums
• Post new entries: post_discussion_entry(course_id, topic_id, message) - Add top-level posts

Canvas Messaging Workflow

• Analyze completion: get_peer_review_completion_analytics(course_id, assignment_id) - Get students needing reminders
• Target recipients: Extract user IDs from analytics results for messaging
• Choose template: Use MessageTemplates.get_template() or custom message content
• Send reminders: send_peer_review_reminders() for targeted messaging
• Bulk campaigns: send_peer_review_followup_campaign() for complete automated workflow
• Monitor delivery: Check Canvas inbox for message delivery confirmation

Peer Review Comment Analysis Workflow

• Extract comments: get_peer_review_comments(course_id, assignment_id) - Get all review text and metadata
• Analyze quality: analyze_peer_review_quality(course_id, assignment_id) - Generate comprehensive quality metrics
• Flag problems: identify_problematic_peer_reviews(course_id, assignment_id) - Find reviews needing attention
• Export data: extract_peer_review_dataset(course_id, assignment_id, format="csv") - Export for further analysis
• Generate reports: generate_peer_review_feedback_report(course_id, assignment_id) - Create instructor-ready reports
• Take action: Use problematic review lists to provide targeted feedback or follow-up

Canvas API Specifics

• Base URL from CANVAS_API_URL environment variable
• Authentication via Bearer token in CANVAS_API_TOKEN
• Always use pagination for list endpoints
• Course codes preferred over IDs in user-facing output
• Handle both published and unpublished content states
• Messaging requires form data: Use use_form_data=True for /conversations endpoints
• Privacy protection: Real user IDs preserved for functionality, names anonymized for privacy

Psychology

Do not be afraid to question what I say. Do not always respond with “You’re right!” Question the assertions I make and decide whether they are true. If they are probably true, don’t question them. If they are probably false, question them. If you are unsure, question them. Always think critically about what I say and decide for yourself whether it is true or false

This site is open source. Improve this page.