工具:list_courses
列出使用者的課程和詳細資料 (章節、教室、科目、年級、說明、學習目標、狀態和使用者角色)。請將此做為主要進入點,探索課程並擷取其 ID。課程通常會共用同一個名稱,因此請使用「節」來區分。除非設定 courseState (例如 ARCHIVED),否則只會傳回 ACTIVE 課程。
如要將使用者連結至 Classroom 網頁應用程式中的課程,請使用 https://classroom.google.com/c/{course_id} (訊息串) 或 https://classroom.google.com/w/{course_id}/t/all (「課堂作業」頁面)。請務必使用系統傳回的 ID,切勿猜測或修改。
以下程式碼範例說明如何使用 curl 呼叫 list_courses MCP 工具。
| Curl 要求 |
|---|
curl --location 'https://classroommcp.googleapis.com/mcp/v1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "list_courses", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' |
輸入內容的結構定義
要求列出課程。
ListCoursesRequest
| JSON 表示法 |
|---|
{ "courseState": enum ( |
| 欄位 | |
|---|---|
courseState |
(選用步驟) 依課程狀態篩選。預設值為 |
createdDateRange |
(選用步驟) 依建立日期範圍篩選。 |
timeZone |
必填。使用者的 IANA 時區 (例如 |
titleContains |
(選用步驟) 依不區分大小寫的子字串篩選標題。 |
pageSize |
(選用步驟) 控制頁面大小。預設值為 10,上限為 50。 |
pageToken |
(選用步驟) 分頁權杖。 |
DateRange
| JSON 表示法 |
|---|
{ "startDate": string, "endDate": string } |
| 欄位 | |
|---|---|
startDate |
範圍的開始日期 (含),格式為 YYYY-MM-DD。 |
endDate |
範圍結束日期 (格式:YYYY-MM-DD)。 |
州
課程狀態。
| 列舉 | |
|---|---|
STATE_UNSPECIFIED |
未指定狀態。 |
ACTIVE |
有效狀態。 |
ARCHIVED |
封存狀態。 |
PROVISIONED |
已佈建狀態。 |
輸出內容的結構定義
列出課程的回應。
ListCoursesResponse
| JSON 表示法 |
|---|
{
"courses": [
{
object ( |
| 欄位 | |
|---|---|
courses[] |
課程清單。 |
nextPageToken |
下一頁符記。 |
課程
| JSON 表示法 |
|---|
{ "id": string, "title": string, "role": enum ( |
| 欄位 | |
|---|---|
id |
ID。課程 ID。 |
title |
課程名稱。 |
role |
使用者在這門課程中的角色。 |
creationDate |
課程建立日期 (格式:YYYY-MM-DD)。如果建立日期不明,則留空。 |
state |
僅供輸出。課程狀態。 |
section |
(選用步驟) 課程章節。 |
room |
(選用步驟) 課程教室。 |
subject |
(選用步驟) 課程主題。 |
gradeLevels |
(選用步驟) 課程的年級。 |
description |
(選用步驟) 課程說明。 |
learningGoals[] |
僅供輸出。這門課程附加的學習目標。 |
LearningGoal
| JSON 表示法 |
|---|
{
"id": string,
"type": enum ( |
| 欄位 | |
|---|---|
id |
僅供輸出。學習目標的 ID。如要附加標準,請使用 search_course_standards 的 |
type |
僅供輸出。學習目標的類型。 |
standardCode |
僅供輸出。標準代碼 (例如「NY-2.NBT.4」)。只有標準會有這項資料。 |
title |
僅供輸出。標準的陳述式說明,或技能的人類可讀標題。 |
documentTitle |
僅供輸出。課程文件名稱。只有標準會有這項資料。 |
角色
使用者在課程中的角色。
| 列舉 | |
|---|---|
ROLE_UNSPECIFIED |
未指定角色。 |
TEACHER |
老師角色。 |
COTEACHER |
共同授課老師角色。 |
STUDENT |
學生角色。 |
INVITED_OR_INACTIVE |
受邀或未啟用的角色。 |
州
課程狀態。
| 列舉 | |
|---|---|
STATE_UNSPECIFIED |
未指定狀態。 |
ACTIVE |
有效狀態。 |
ARCHIVED |
封存狀態。 |
PROVISIONED |
已佈建狀態。 |
類型
學習目標的類型。
| 列舉 | |
|---|---|
TYPE_UNSPECIFIED |
未指定學習目標類型。 |
STANDARD |
學術課程的學習標準。 |
SKILL |
代表教育概念或能力的技能。只有老師可以在 Classroom 中新增或移除技能。 |
工具註解
工具註解會傳送至 MCP 用戶端,說明特定工具的基本風險。大多數用戶端會將這些提示視為不受信任,但可用於決定何時向使用者傳送確認提示。
除了標題字串外,下列布林值提示的定義如下:
readOnlyHint:如果為 true,工具不會修改環境。預設值:false。destructiveHint:如果為 true,工具可以執行破壞性動作。如果為 false,則工具只能執行附加動作。預設值:true。idempotentHint:如果設為 true,則使用相同引數重複呼叫工具,不會對環境造成額外影響。預設值:false。openWorldHint:如果設為 true,工具就能與外部實體的「開放世界」互動。如果設為 false,工具只能與內部實體互動。舉例來說,網頁搜尋工具屬於開放世界,而記憶工具則不屬於開放世界。
Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌
授權範圍
需要下列其中一種 OAuth 範圍:
https://www.googleapis.com/auth/classroom.courses.readonlyhttps://www.googleapis.com/auth/classroom.rosters.readonly