NTULearn: Attachments and downloads MCP tools
Service overview · CLI reference · All MCP tools · Data types
Attachments and downloads
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_content_attachments
List files attached to a course content item. Use a leaf content ID rather than a folder. Some external/LTI content has no downloadable Blackboard attachment.
Inputs: course_id, content_id; common pagination and refresh parameters. Use a leaf content item rather than a folder.
Returns: attachment IDs, filenames, and MIME types when provided. Some external/LTI items do not expose Blackboard attachment files.
Inputs
| Field | Type | Required | Details |
|---|---|---|---|
course_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
content_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 | — |
content_id |
string |
Yes | — |
attachments |
array of Attachment |
Yes | — |
offset |
integer |
Yes | — |
next_offset |
integer or null |
Yes | — |
ntulearn_read_file_content
Read an attachment inline as text: PDF, DOCX, PPTX, XLSX and UTF text/code. Get attachment_id from ntulearn_get_content_attachments. Reports truncation; no OCR, image interpretation or external LTI downloads. Temporary files are removed.
Inputs: course_id, content_id, attachment_id; optional max_chars of 1–100000 with default 20000 and max_pages of 1–50 with default 20.
Returns: the filename, extracted text, truncated, retrieval time, and PDF page counts when applicable. Supports PDF, DOCX, PPTX including text notes, XLSX, and supported UTF-8/UTF-16 text/code files. PDFs are read from the beginning up to the page/character limit. Extraction is text-only: scanned images and diagrams are not interpreted, and OCR is not performed. Temporary files are removed after extraction.
Unsupported, encrypted, malformed, or oversized documents produce an actionable error; download them for local viewing instead. Extraction has a 30-second worker timeout. Attachments remain subject to the 20 MB download limit.
{"course_id":"_100_1","content_id":"_200_1","attachment_id":"_300_1","max_pages":5,"max_chars":10000}
Inputs
| Field | Type | Required | Details |
|---|---|---|---|
course_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
content_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
attachment_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
max_chars |
integer |
No | minimum: 1; maximum: 100000; default: 20000 |
max_pages |
integer |
No | minimum: 1; maximum: 50; default: 20 |
Output
| Field | Type | Required | Details |
|---|---|---|---|
course_id |
string |
Yes | — |
content_id |
string |
Yes | — |
attachment_id |
string |
Yes | — |
file_name |
string |
Yes | — |
text |
string |
Yes | — |
truncated |
boolean |
Yes | — |
pages_read |
integer or null |
No | default: null |
total_pages |
integer or null |
No | default: null |
retrieved_at |
string |
Yes | format: date-time |
ntulearn_download_file
Download a Blackboard attachment to an explicit local file path, up to 20 MB. Never overwrites an existing file. Does not modify NTULearn or forward university cookies to file-delivery hosts.
Inputs: course_id, content_id, attachment_id, and an explicit local destination file path. Its parent directory must already exist.
Returns: saved path, bytes written, and download time. Saves at most 20 MB and never overwrites an existing file. It writes locally and does not modify NTULearn. Supported redirects stay on NTU or Blackboard delivery hosts; university cookies are not forwarded to delivery hosts. HTML/JSON attachments are unsupported.
MCP host confirmation is required before this action.
Inputs
| Field | Type | Required | Details |
|---|---|---|---|
course_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
content_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
attachment_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
destination |
string |
Yes | — |
max_bytes |
integer |
No | minimum: 1; maximum: 20000000; default: 20000000 |
Output
| Field | Type | Required | Details |
|---|---|---|---|
path |
string |
Yes | — |
bytes_written |
integer |
Yes | minimum: 0 |
downloaded_at |
string |
Yes | format: date-time |
ntulearn_download_video
Download a Kaltura video embedded in an NTULearn content item to a new local file. Uses your normal course access and a short-lived viewer session; max_mb is 1–2000, existing files are never overwritten, and NTULearn is not modified.
Inputs: course_id, content_id, an explicit local destination file path, and optional max_mb from 1–2000 (default 1000). The parent directory must already exist.
Returns: saved path, bytes written, and download time. Supports Kaltura players embedded in NTULearn content. It obtains the player’s short-lived viewer session in a temporary Chromium context, then streams the Kaltura download to disk. NTU cookies are used only for the NTULearn WebDAV wrapper and are never sent to Blackboard or Kaltura. Existing files and symbolic-link directories are rejected; failed partial downloads are removed. The item must be visible to your account and Kaltura must provide a downloadable source. This tool requires the optional personal dependencies and installed Chromium.
{"course_id":"_100_1","content_id":"_200_1","destination":"/path/to/lecture.mp4","max_mb":1000}
MCP host confirmation is required before this action.
Inputs
| Field | Type | Required | Details |
|---|---|---|---|
course_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
content_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
destination |
string |
Yes | — |
max_mb |
integer |
No | minimum: 1; maximum: 2000; default: 1000 |
Output
| Field | Type | Required | Details |
|---|---|---|---|
path |
string |
Yes | — |
bytes_written |
integer |
Yes | minimum: 0 |
downloaded_at |
string |
Yes | format: date-time |
ntulearn_download_course
Recursively save readable Blackboard attachments under destination/course_id with content folder names and stable file IDs. Creates local directories, skips existing regular files, rejects symlinks and never overwrites. Per-file limit 20 MB; batch limits and denied/external content are reported in issues. NTULearn is never modified.
Inputs: course_id, destination directory; optional traversal limits and refresh; max_files of 1–500 with default 100, max_total_mb of 1–500 with default 200, and max_requests with default 200.
Returns: destination, file statuses of downloaded, skipped_existing, or failed, bytes written, and coverage/issues. Files are saved beneath destination/course_id using content-folder names and stable IDs. Downloads run as the tree is traversed. Existing regular files are skipped, symbolic-link directories are rejected, and files are never overwritten. Each file is limited to 20 MB in addition to the total batch budget. External/LTI material may not be downloadable through these APIs.
MCP host confirmation is required before this action.
Inputs
| Field | Type | Required | Details |
|---|---|---|---|
course_id |
string |
Yes | NTULearn ID returned by another tool; pattern: ^[A-Za-z0-9_-]{1,80}$ |
destination |
string |
Yes | — |
max_depth |
integer |
No | minimum: 1; maximum: 10; default: 5 |
max_nodes |
integer |
No | minimum: 1; maximum: 5000; default: 1000 |
max_files |
integer |
No | minimum: 1; maximum: 500; default: 100 |
max_total_mb |
integer |
No | minimum: 1; maximum: 500; default: 200 |
max_requests |
integer |
No | minimum: 1; maximum: 200; default: 200 |
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 | — |
course_id |
string |
Yes | — |
destination |
string |
Yes | — |
files |
array of CourseDownloadFile |
Yes | — |
bytes_written |
integer |
Yes | — |
See the MCP data types for nested object fields.