MCP Tools Reference: classroommcp.googleapis.com

כלי: list_courses

רשימה של הקורסים של המשתמש עם הפרטים שלהם (חלק, חדר, נושא, כיתות, תיאור, יעדי למידה, סטטוס ותפקיד המשתמש). אפשר להשתמש בזה כנקודת הכניסה הראשית כדי למצוא קורסים ולאחזר את המזהים שלהם. להרבה קורסים יש שם זהה, לכן כדאי להשתמש בשדה "מדור" כדי להבדיל ביניהם. הפונקציה מחזירה רק קורסים במצב ACTIVE, אלא אם מוגדר courseState (למשל ARCHIVED).

כדי לקשר את המשתמש לקורס באפליקציית האינטרנט של Classroom, משתמשים בכתובת https://classroom.google.com/c/{course_id} (עדכונים) או בכתובת https://classroom.google.com/w/{course_id}/t/all (הדף "סביבת הלמידה"). השתמשו במזהים בדיוק כפי שהם מוחזרים. אל תנחשו או תשנו אותם.

בדוגמת הקוד הבאה מוסבר איך להשתמש ב-curl כדי להפעיל את כלי ה-MCP‏ list_courses.

בקשת 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 (State),
  "createdDateRange": {
    object (DateRange)
  },
  "timeZone": string,
  "titleContains": string,
  "pageSize": integer,
  "pageToken": string
}
שדות
courseState

enum (State)

אופציונלי. סינון לפי מצב הקורס. ברירת המחדל היא ACTIVE.

createdDateRange

object (DateRange)

אופציונלי. סינון לפי טווח של תאריכי יצירה.

timeZone

string

חובה. אזור הזמן של המשתמש לפי IANA (למשל "America/Los_Angeles"). התאריכים בבקשה הזו מפורשים לפיו והתאריכים בתגובה מעוצבים לפיו, בהתאם למה שהמשתמש רואה ב-Classroom.

titleContains

string

אופציונלי. סינון הכותרת לפי מחרוזת משנה ללא תלות ברישיות.

pageSize

integer

אופציונלי. שולט בגודל הדף. ברירת המחדל היא 10, והמקסימום הוא 50.

pageToken

string

אופציונלי. טוקן לעימוד.

DateRange

ייצוג ב-JSON
{
  "startDate": string,
  "endDate": string
}
שדות
startDate

string

תאריך ההתחלה של הטווח (כולל, בפורמט: YYYY-MM-DD).

endDate

string

סוף הטווח, כולל (פורמט: YYYY-MM-DD).

מדינה (State)

מצבים של קורס.

טיפוסים בני מנייה (enum)
STATE_UNSPECIFIED מצב לא מוגדר.
ACTIVE מצב פעיל.
ARCHIVED מצב ארכיון.
PROVISIONED מצב הקצאה.

סכימת הפלט

תגובה לרשימת קורסים.

ListCoursesResponse

ייצוג ב-JSON
{
  "courses": [
    {
      object (Course)
    }
  ],
  "nextPageToken": string
}
שדות
courses[]

object (Course)

רשימת הקורסים.

nextPageToken

string

האסימון של הדף הבא.

קורס

ייצוג ב-JSON
{
  "id": string,
  "title": string,
  "role": enum (Role),
  "creationDate": string,
  "state": enum (State),
  "section": string,
  "room": string,
  "subject": string,
  "gradeLevels": string,
  "description": string,
  "learningGoals": [
    {
      object (LearningGoal)
    }
  ]
}
שדות
id

string

מזהה. המזהה של הקורס הזה.

title

string

שם הקורס.

role

enum (Role)

התפקיד של המשתמש בקורס הזה.

creationDate

string

תאריך היצירה של הקורס (פורמט: YYYY-MM-DD). השדה ריק אם תאריך היצירה לא ידוע.

state

enum (State)

פלט בלבד. מצב הקורס.

section

string

אופציונלי. החלק של הקורס.

room

string

אופציונלי. החדר של הקורס.

subject

string

אופציונלי. נושא הקורס.

gradeLevels

string

אופציונלי. רמות הכיתה של הקורס.

description

string

אופציונלי. תיאור הקורס.

learningGoals[]

object (LearningGoal)

פלט בלבד. יעדי הלמידה שמצורפים לקורס הזה.

LearningGoal

ייצוג ב-JSON
{
  "id": string,
  "type": enum (Type),
  "standardCode": string,
  "title": string,
  "documentTitle": string
}
שדות
id

string

פלט בלבד. המזהה של יעד הלמידה. כדי לצרף סטנדרט, צריך להשתמש ב-id מ-search_course_standards (ולא ב-standardCode).

type

enum (Type)

פלט בלבד. סוג יעד הלמידה.

standardCode

string

פלט בלבד. קוד סטנדרטי (למשל, "NY-2.NBT.4"). מאוכלס רק עבור תקנים.

title

string

פלט בלבד. תיאור ההצהרה של הסטנדרטים, או כותרת קריאה לאנשים של המיומנויות.

documentTitle

string

פלט בלבד. שם מסמך תוכנית הלימודים. מאוכלס רק עבור תקנים.

תפקיד

התפקידים של המשתמש בקורס.

טיפוסים בני מנייה (enum)
ROLE_UNSPECIFIED תפקיד לא מוגדר.
TEACHER תפקיד המורה.
COTEACHER תפקיד של מורה עמית/ה.
STUDENT תפקיד התלמיד/ה.
INVITED_OR_INACTIVE תפקיד מוזמן או לא פעיל.

מדינה (State)

מצבים של קורס.

טיפוסים בני מנייה (enum)
STATE_UNSPECIFIED מצב לא מוגדר.
ACTIVE מצב פעיל.
ARCHIVED מצב ארכיון.
PROVISIONED מצב הקצאה.

סוג

סוג יעד הלמידה.

טיפוסים בני מנייה (enum)
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.readonly
  • https://www.googleapis.com/auth/classroom.rosters.readonly