Skip to content

NTULearn: Announcements, calendar and grades MCP tools

Service overview · CLI reference · All MCP tools · Data types

Announcements, calendar and grades

Inputs are required only where marked. A required output field may still be null if its type allows it. See data types for nested objects.

ntulearn_get_announcements

Read published announcements for one enrolled course. An empty list is distinct from denied access.

Inputs: course_id; common pagination and refresh parameters.

Returns: published announcement IDs, titles, body text, and created/modified timestamps. A successful empty list is distinct from an access-denied error.

Inputs

Field Type Required Details
course_id string Yes NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$
limit integer No minimum: 1; maximum: 100; default: 50
offset integer No minimum: 0; default: 0
refresh boolean No default: false

Output

Field Type Required Details
retrieved_at string Yes format: date-time
from_cache boolean Yes —
cache_age_seconds integer Yes —
course_id string Yes —
announcements array of Announcement Yes —
offset integer Yes —
next_offset integer or null Yes —

ntulearn_get_calendar

Read calendar entries and published deadlines, across your courses or for one course. Defaults to the next 14 days. Supply timezone-aware timestamps and a window no longer than 112 days.

Inputs: optional since, until, course_id, pagination, and refresh. Defaults to the next 14 days. Explicit timestamps must include a timezone, with a positive window no longer than 112 days.

Returns: one page of calendar items with course attribution when provided, event type, dates, description, location, and cache metadata. Published deadlines can appear as type GradebookColumn.

Inputs

Field Type Required Details
since string or null No default: null; format: date-time
until string or null No default: null; format: date-time
course_id string or null No default: null; NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$
limit integer No minimum: 1; maximum: 100; default: 50
offset integer No minimum: 0; default: 0
refresh boolean No default: false

Output

Field Type Required Details
retrieved_at string Yes format: date-time
from_cache boolean Yes —
cache_age_seconds integer Yes —
since string Yes format: date-time
until string Yes format: date-time
items array of CalendarItem Yes —
offset integer Yes —
next_offset integer or null Yes —

ntulearn_get_gradebook

Read visible gradebook columns and your own scores/status. Missing scores remain null. Columns and grades paginate independently with offset and grades_offset.

Inputs: course_id; limit, offset, refresh; and grades_offset, default 0.

Returns: visible gradebook columns and your own grades. Columns include names, possible scores, due dates, availability, and content IDs when published. Grades include score/text, status, exemption, feedback, and modified time when published. Missing scores remain null; zero remains zero.

Columns and grades paginate independently. Follow next_offset for columns and grades_next_offset for grades, supplying offset and grades_offset respectively.

Inputs

Field Type Required Details
course_id string Yes NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$
limit integer No minimum: 1; maximum: 100; default: 50
offset integer No minimum: 0; default: 0
grades_offset integer No minimum: 0; default: 0
refresh boolean No default: false

Output

Field Type Required Details
retrieved_at string Yes format: date-time
from_cache boolean Yes —
cache_age_seconds integer Yes —
course_id string Yes —
columns array of GradeColumn Yes —
grades array of Grade Yes —
offset integer Yes —
next_offset integer or null Yes —
grades_next_offset integer or null Yes —
grades_offset integer Yes —

ntulearn_get_upcoming

Collect all calendar pages across your enrolled courses. Defaults to the next 14 days. Optionally select courses or item_type such as GradebookColumn. Partial failures are reported in issues.

Inputs: optional since, until, course_ids, item_type, max_requests, and refresh. Uses the same calendar window rules and default as ntulearn_get_calendar.

Returns: collected calendar pages sorted by start time. Use course_ids to select sites and item_type: "GradebookColumn" for assignment due-date entries. Unlike the paginated calendar tool, this tool collects pages within a single request budget and reports partial coverage.

Inputs

Field Type Required Details
since string or null No default: null; format: date-time
until string or null No default: null; format: date-time
course_ids array of string or null No default: null; minimum items: 1; maximum items: 100
item_type string or null No default: null
max_requests integer No minimum: 1; maximum: 200; default: 100
refresh boolean No default: false

Output

Field Type Required Details
retrieved_at string Yes format: date-time
from_cache boolean Yes —
cache_age_seconds integer Yes —
complete boolean Yes —
requests_used integer Yes —
issues array of Issue Yes —
since string Yes format: date-time
until string Yes format: date-time
items array of CalendarItem Yes —

ntulearn_whats_new

Digest of recent announcements, upcoming calendar items and your gradebook across courses. Defaults to announcements from the last 7 days and events in the next 14 days. NTU often omits grade-change timestamps: those grades are labeled snapshots with changed_since=null. No persistent last-seen tracker. Check issues for partial coverage.

Inputs: optional timezone-aware since, default seven days ago; until, default 14 days ahead; course_ids; max_items of 1–500 with default 200; request budget; and refresh. since must be in the past, and until must be in the future within 112 days.

Returns: recent announcements, upcoming calendar entries, your gradebook snapshots, and collection issues. Change timestamps filter announcements/grades when available. Grades without a published change timestamp have changed_since: null and are explicitly current snapshots. max_items bounds each result category. No persistent last-seen tracker is stored.

Inputs

Field Type Required Details
since string or null No default: null; format: date-time
until string or null No default: null; format: date-time
course_ids array of string or null No default: null; minimum items: 1; maximum items: 100
max_items integer No minimum: 1; maximum: 500; default: 200
max_requests integer No minimum: 1; maximum: 200; default: 100
refresh boolean No default: false

Output

Field Type Required Details
retrieved_at string Yes format: date-time
from_cache boolean Yes —
cache_age_seconds integer Yes —
complete boolean Yes —
requests_used integer Yes —
issues array of Issue Yes —
since string Yes format: date-time
until string Yes format: date-time
announcements array of RecentAnnouncement Yes —
upcoming array of CalendarItem Yes —
grades array of RecentGrade Yes —
grade_change_note string No default: "Grades without a published change timestamp are current snapshots; changed_since is null."