MCP Tools Reference: classroommcp.googleapis.com

工具:create_announcement

在課程訊息串中建立新公告。必須具備課程中的老師角色。公告一律會建立為學生無法查看的草稿;如果設定了 scheduleDate,公告就會在該日期自動發布。否則,請告知使用者在 Classroom 中發布,因為這項工具無法發布公告。

Classroom 沒有單一草稿公告的網頁連結。如要將使用者連結至新公告,請使用課程「訊息串」頁面 https://classroom.google.com/c/{course_id},老師可以在「草稿」部分找到公告,以便查看或發布。請務必使用系統傳回的 ID,切勿猜測或修改。

以下程式碼範例說明如何使用 curl 呼叫 create_announcement 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": "create_announcement",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

要求建立公告。

CreateAnnouncementRequest

JSON 表示法
{
  "courseId": string,
  "text": string,
  "materials": [
    {
      object (MaterialInput)
    }
  ],
  "assigneeIds": [
    string
  ],
  "scheduleDate": string,
  "timeZone": string
}
欄位
courseId

string

必填。課程 ID。

text

string

必填。公告文字。

materials[]

object (MaterialInput)

(選用步驟) 要附加的教材。最多 20 個。

assigneeIds[]

string

(選用步驟) 可查看公告的學生 ID,來自 get_course_roster。留空代表所有學生。

scheduleDate

string

(選用步驟) 自動發布公告的日期 (YYYY-MM-DD)。時間預設為使用者時區的上午 8 點,可在使用者介面中編輯。

timeZone

string

必填。使用者的 IANA 時區 (例如 "America/Los_Angeles")。這項要求中的日期會以此時區解讀,回應中的日期也會以此時區格式化,與使用者在 Classroom 中看到的內容一致。

MaterialInput

JSON 表示法
{
  "driveFile": {
    object (DriveFileInput)
  },
  "youtubeVideoId": string,
  "linkUrl": string,
  "formUrl": string,
  "notebook": {
    object (GeminiNotebook)
  }
}
欄位
聯集欄位 content。附件內容。content 只能是下列其中一項:
driveFile

object (DriveFileInput)

要附加的 Google 雲端硬碟檔案。

youtubeVideoId

string

要附加的 YouTube 影片 ID (例如 "dQw4w9WgXcQ")。

linkUrl

string

要附加的網頁網址。

formUrl

string

要附加的 Google 表單網址。

notebook

object (GeminiNotebook)

要附加的 Gemini Notebook。

DriveFileInput

JSON 表示法
{
  "id": string,
  "shareMode": enum (ShareMode)
}
欄位
id

string

必填。雲端硬碟檔案的 ID。

shareMode

enum (ShareMode)

必填。學生取得檔案的方式:查看 (唯讀)、編輯 (所有人編輯同一個檔案) 或複製 (每位學生取得自己的副本)。

GeminiNotebook

JSON 表示法
{
  "id": string,
  "title": string
}
欄位
id

string

必填。Notebook 的 ID。

title

string

Notebook 的標題。

ShareMode

雲端硬碟檔案的共用設定。

列舉
SHARE_MODE_UNSPECIFIED 未指定共用模式。
VIEW 學生可以查看共用檔案。
EDIT 學生可以編輯共用檔案。
COPY 學生會收到共用檔案的個人副本。

輸出內容的結構定義

公告事項的詳細中繼資料。

公告

JSON 表示法
{
  "id": string,
  "materials": [
    {
      object (Material)
    }
  ],
  "assigneeIds": [
    string
  ],
  "publishDate": string,
  "state": enum (State),
  "text": string,
  "scheduleDate": string
}
欄位
id

string

僅供輸出。ID。公告 ID。

materials[]

object (Material)

這則公告附加的教材。

assigneeIds[]

string

可查看這則公告的學生 ID 清單 (未設定代表所有學生)。

publishDate

string

僅供輸出。公告發布日期 (YYYY-MM-DD)。

state

enum (State)

僅供輸出。公告狀態。

text

string

公告文字。

scheduleDate

string

公告預定發布日期 (YYYY-MM-DD)。時間預設為使用者時區的上午 8 點,可在使用者介面中編輯。

材質

JSON 表示法
{
  "id": string,

  "sharedDriveFile": {
    object (SharedDriveFile)
  },
  "youtubeVideo": {
    object (YouTubeVideo)
  },
  "link": {
    object (Link)
  },
  "form": {
    object (Form)
  },
  "notebook": {
    object (GeminiNotebook)
  }
}
欄位
id

string

僅供輸出。教材 ID。使用 UpdateCourseWorkRequest.removeMaterialIds 移除材質。

聯集欄位 content。附件內容。content 只能是下列其中一項:
sharedDriveFile

object (SharedDriveFile)

Google 雲端硬碟檔案附件。

youtubeVideo

object (YouTubeVideo)

YouTube 影片附件。

link

object (Link)

網址連結附件。

form

object (Form)

Google 表單附件。

notebook

object (GeminiNotebook)

Gemini Notebook 附件。

SharedDriveFile

JSON 表示法
{
  "file": {
    object (DriveFile)
  },
  "shareMode": enum (ShareMode)
}
欄位
file

object (DriveFile)

雲端硬碟檔案詳細資料。

shareMode

enum (ShareMode)

必填。學生取得檔案的方式:查看 (唯讀)、編輯 (所有人編輯同一個檔案) 或複製 (每位學生取得自己的副本)。

DriveFile

JSON 表示法
{
  "id": string,
  "title": string,
  "url": string
}
欄位
id

string

必填。雲端硬碟檔案的 ID。

title

string

僅供輸出。雲端硬碟檔案的標題。

url

string

僅供輸出。雲端硬碟檔案的網址。

YouTubeVideo

JSON 表示法
{
  "id": string,
  "title": string
}
欄位
id

string

必填。YouTube 影片 ID。

title

string

僅供輸出。YouTube 影片的標題。

JSON 表示法
{
  "url": string,
  "title": string
}
欄位
url

string

必填。連結的網址。

title

string

僅供輸出。連結標題。

表單

JSON 表示法
{
  "formUrl": string,
  "title": string,
  "responseUrl": string
}
欄位
formUrl

string

必填。表單網址。

title

string

僅供輸出。表單標題。

responseUrl

string

僅供輸出。表單回覆的網址。只有在已記錄回覆,且要求的使用者是表單編輯者時,才會設定。

GeminiNotebook

JSON 表示法
{
  "id": string,
  "title": string
}
欄位
id

string

必填。Notebook 的 ID。

title

string

Notebook 的標題。

ShareMode

雲端硬碟檔案的共用設定。

列舉
SHARE_MODE_UNSPECIFIED 未指定共用模式。
VIEW 學生可以查看共用檔案。
EDIT 學生可以編輯共用檔案。
COPY 學生會收到共用檔案的個人副本。

州

公告狀態。

列舉
STATE_UNSPECIFIED 未指定狀態。
PUBLISHED 公告已發布,學生可以查看。
DRAFT 公告為草稿。

工具註解

工具註解會傳送至 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.announcements