Skip to content

STARS: Indexes and timetables MCP tools

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

Indexes and timetables

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.

stars_get_course_indexes

List a page of indexes with timetable details and matching-term vacancies/waitlists. Follow next_offset to see the rest. Sessions inherit course_code and index from their enclosing result; null raw_day/raw_time are omitted.

Inputs: course_code, academic_year, semester.

Returns: one page of indexes, their associated sessions, schedule completeness, vacancies, waitlist length, and vacancy metadata. index_count is the total; follow next_offset until it is null. Shared lectures remain attached to each applicable index. Sessions include lesson type, group, day, times, venue, teaching weeks, and remarks.

Inputs

Field Type Required Details
course_code string Yes —
academic_year integer Yes —
semester 1, 2, "S" Yes —
limit integer No minimum: 1; maximum: 50; default: 10
offset integer No minimum: 0; default: 0

Output

Field Type Required Details
course_code string Yes —
academic_year integer or null Yes —
semester string or null Yes —
index_count integer Yes —
offset integer Yes —
next_offset integer or null Yes —
vacancy_metadata VacancyMetadata Yes —
indexes array of CourseIndex Yes —

stars_get_index

Get one index's complete schedule, vacancies, and waitlist where matching-term counts are published.

Inputs: course_code, index, academic_year, semester.

Returns: one index's sessions and matching-term vacancy snapshot. Use an index returned by stars_get_course_indexes; an unknown index produces an error rather than an empty timetable.

{"course_code":"ZZ0001","index":"00001","academic_year":2030,"semester":1}

Inputs

Field Type Required Details
course_code string Yes —
index string Yes —
academic_year integer Yes —
semester 1, 2, "S" Yes —

Output

Field Type Required Details
course_code string Yes —
academic_year integer or null Yes —
semester string or null Yes —
vacancy_status "available", "not_listed", "closed", "term_mismatch", "unavailable" Yes —
vacancies_available integer or null Yes —
waitlist_length integer or null Yes —
index string Yes —
vacancy_metadata VacancyMetadata Yes —
schedule_complete boolean Yes —
sessions array of CompactSession Yes —

stars_compare_indexes

Compare shared and index-specific sessions; optionally check clashes with supplied time slots.

Inputs: course_code, academic_year, semester, at least two unique indexes; optional against_sessions.

Returns: common_sessions, unique_sessions_by_index, and an optional clash_check. Common sessions apply to every entry in indexes_compared. Clash checks distinguish definite overlaps from comparisons with unknown week/day/time information.

{"course_code":"ZZ0001","academic_year":2030,"semester":1,"indexes":["00001","00002"],"against_sessions":[{"day":"TUE","start_time":"14:00","end_time":"16:00","teaching_weeks":[2,4,6]}]}

Inputs

Field Type Required Details
course_code string Yes —
indexes array of string Yes —
academic_year integer Yes —
semester 1, 2, "S" Yes —
against_sessions array of TimeSlot or null No default: null

Output

Field Type Required Details
course_code string Yes —
academic_year integer or null Yes —
semester string or null Yes —
retrieved_at string or null Yes —
official_source string or null Yes —
indexes_compared array of string Yes —
common_sessions array of CompactSession Yes —
unique_sessions_by_index object of array of CompactSession Yes —
clash_check ClashCheck or null Yes —

stars_find_matching_indexes

Find indexes matching day/time/lesson/week rules and avoiding supplied timetable clashes.

Inputs: course_code, academic_year, semester; optional constraints and against_sessions.

Supported constraints:

Field Meaning
avoid_days Reject sessions on the listed days
earliest_start Every session must start at or after this time
latest_end Every session must end by this time
avoid_windows Reject overlaps with listed day/start/end windows
require_sessions Each rule must match a session by lesson type, day, or start-time bounds
teaching_weeks Evaluate sessions in the specified weeks, from 1–20

Required-session rules accept lesson_type, day, starts_at_or_after, and starts_at_or_before. Supply at least one condition per rule. Use lesson types as returned by NTU.

Returns: matching indexes with schedules, status of confirmed or uncertain, and reasons for uncertainty. Against-schedule slots accept day, start_time, end_time, and optional teaching_weeks. Use slots from the same academic year and semester. Overlaps in disjoint known teaching weeks do not clash.

{"course_code":"ZZ0001","academic_year":2030,"semester":1,"constraints":{"avoid_days":["FRI"],"latest_end":"17:00","require_sessions":[{"lesson_type":"TUT","day":"TUE","starts_at_or_after":"13:00"}]}}

Inputs

Field Type Required Details
course_code string Yes —
academic_year integer Yes —
semester 1, 2, "S" Yes —
constraints SearchConstraints or null No default: null
against_sessions array of TimeSlot or null No default: null

Output

Field Type Required Details
course_code string Yes —
academic_year integer or null Yes —
semester string or null Yes —
retrieved_at string or null Yes —
official_source string or null Yes —
constraints ConstraintsResult Yes —
against_session_count integer Yes —
match_count integer Yes —
matches array of MatchingIndex Yes —