campus-cli AGENTS.md

campus-cli — Agent Guide

This CLI/MCP server gives agents direct access to a student's university campus systems. Today only Blackboard Learn (UPC Aula Virtual) is implemented — all its tools use the blackboard_ prefix. Use it to help students check their courses, assignments, grades, and download materials — all without opening a browser. (Future: canvas_*, moodle_* for other universities — not implemented yet.)

Setup

Before using any tool, the user must be authenticated:

campus login              # opens browser for Microsoft SSO
campus whoami              # verify session is active

If you get Not authenticated, ask the user to run campus login.

Primary workflow

1. blackboard_list_courses                           → find the relevant courseId
2. blackboard_list_assignments <courseId>            → see pending tasks + due dates
3. blackboard_get_grades <courseId>                  → check current grades
4. blackboard_list_contents <courseId>               → browse course materials
5. blackboard_list_contents <courseId> <parentId>    → navigate into a subfolder
6. blackboard_list_attachments <courseId> <contentId>→ find downloadable files

Feedback workflow

1. blackboard_get_assignment_feedback <courseId>    → scores + instructor comments + feedback files for all assignments
2. blackboard_download_feedback_file <ids>          → download an annotated file the professor attached to the grade

Agent behavior rules

• Always confirm before submitting (blackboard_submit_attempt). Show the user what will be submitted and ask for confirmation. The server also requires direct MCP elicitation and fails closed when the client cannot show it. blackboard_save_attempt_draft (saving progress without sending) does not need this confirmation — only the final submit does.
• Downloads are sandboxed — MCP downloads go under ~/Downloads/campus-cli (or the user-configured CAMPUS_DOWNLOAD_DIR). outputDir is a relative subdirectory, never an arbitrary path, and existing files are not overwritten.
• blackboard_save_attempt_draft/blackboard_submit_attempt only work on file/text/link-submission columns — not on quiz-style columns with interactive questions (both look identical from blackboard_list_assignments, since Ultra treats tests and assignments as the same resource/x-bb-asmt-test-link content type). If Blackboard returns 400 with a message like "Attempts cannot be created for assessments with non-presentation-only questions", that column is actually a quiz/test — tell the user, don't retry. A 403 bb-rest-attempt-past-due-exception is expected/normal once the due date has passed and late attempts aren't allowed — same as the web UI would show, not a bug.
• Show grades in context — when showing grades, also show the assignment name, max score, and due date if available.
• Navigate content recursively — if the user asks for materials, explore subfolders using blackboard_list_contents with parentId.
• Use blackboard_raw_api for anything not covered — it is restricted to /learn/api/public/. POST, PUT, PATCH, and DELETE require direct user confirmation through MCP elicitation.
• Session errors are recoverable — if you get a session error, tell the user to run campus login (not a fatal error).
• Respect rate limits — don't fan out more than 5 parallel API calls.