MCP Tools Reference: classroommcp.googleapis.com

Araç: list_courses

Kullanıcının derslerini ayrıntılarıyla (bölüm, oda, konu, sınıf düzeyleri, açıklama, öğrenme hedefleri, durum ve kullanıcının rolü) listeler. Kursları keşfetmek ve kimliklerini almak için bunu birincil giriş noktası olarak kullanın. Dersler genellikle aynı başlığa sahip olduğundan bunları ayırt etmek için bölümü kullanın. courseState ayarlanmadığı sürece (ör. ARCHIVED) yalnızca ACTIVE kursları döndürür.

Kullanıcıyı Classroom web uygulamasındaki bir kursa bağlamak için https://classroom.google.com/c/{course_id} (akış) veya https://classroom.google.com/w/{course_id}/t/all (Sınıf Çalışmaları sayfası) bağlantısını kullanın. Kimlikleri tam olarak döndürüldüğü şekilde kullanın. Kimlikleri asla tahmin etmeyin veya değiştirmeyin.

Aşağıdaki kod örneğinde, list_courses MCP aracını çağırmak için curl öğesinin nasıl kullanılacağı gösterilmektedir.

Curl İsteği
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
}'

Giriş şeması

Kursları listeleme isteği.

ListCoursesRequest

JSON gösterimi
{
  "courseState": enum (State),
  "createdDateRange": {
    object (DateRange)
  },
  "timeZone": string,
  "titleContains": string,
  "pageSize": integer,
  "pageToken": string
}
Alanlar
courseState

enum (State)

İsteğe bağlıdır. Ders durumuna göre filtreleme Varsayılan değer ACTIVE'dir.

createdDateRange

object (DateRange)

İsteğe bağlıdır. Oluşturma tarihlerinin aralığına göre filtreleyin.

timeZone

string

Zorunlu. Kullanıcının IANA saat dilimi (ör. "America/Los_Angeles"). Bu istekteki tarihler bu saat dilimine göre yorumlanır ve yanıttaki tarihler bu saat dilimine göre biçimlendirilir. Bu sayede, kullanıcının Classroom'da gördüğü tarihlerle eşleşir.

titleContains

string

İsteğe bağlıdır. Başlığı büyük/küçük harfe duyarlı olmayan alt dizeye göre filtreleyin.

pageSize

integer

İsteğe bağlıdır. Sayfa boyutunu kontrol eder. Varsayılan değer 10, maksimum değer 50'dir.

pageToken

string

İsteğe bağlıdır. Sayfalara ayırma jetonu.

DateRange

JSON gösterimi
{
  "startDate": string,
  "endDate": string
}
Alanlar
startDate

string

Aralığın başlangıç zamanı dahildir (biçim: YYYY-AA-GG).

endDate

string

Aralığın dahil edilen bitiş tarihi (biçim: YYYY-AA-GG).

Eyalet

Kursun durumları.

Sıralamalar
STATE_UNSPECIFIED Belirtilmemiş durum.
ACTIVE Etkin durumda.
ARCHIVED Arşivlenmiş durum.
PROVISIONED Temel hazırlığı yapılmış durum.

Çıkış şeması

Kursları listeleme isteğinin yanıtı.

ListCoursesResponse

JSON gösterimi
{
  "courses": [
    {
      object (Course)
    }
  ],
  "nextPageToken": string
}
Alanlar
courses[]

object (Course)

Kursların listesi.

nextPageToken

string

Sonraki sayfa jetonu.

Kurs

JSON gösterimi
{
  "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)
    }
  ]
}
Alanlar
id

string

Tanımlayıcı. Bu dersin tanımlayıcısı.

title

string

Kursun başlığı.

role

enum (Role)

Kullanıcının bu dersteki rolü.

creationDate

string

Kursun oluşturulma tarihi (biçim: YYYY-AA-GG). Oluşturma tarihi bilinmiyorsa boş bırakılır.

state

enum (State)

Yalnızca çıkış. Kursun durumu.

section

string

İsteğe bağlıdır. Kursun bölümü.

room

string

İsteğe bağlıdır. Kursun odası.

subject

string

İsteğe bağlıdır. Kursun konusu.

gradeLevels

string

İsteğe bağlıdır. Kursun sınıf düzeyleri.

description

string

İsteğe bağlıdır. Kursun açıklaması.

learningGoals[]

object (LearningGoal)

Yalnızca çıkış. Bu kursa eklenen öğrenme hedefleri.

LearningGoal

JSON gösterimi
{
  "id": string,
  "type": enum (Type),
  "standardCode": string,
  "title": string,
  "documentTitle": string
}
Alanlar
id

string

Yalnızca çıkış. Öğrenme hedefinin kimliği. Standart eklemek için search_course_standards'dan bir id kullanın (standardCode değil).

type

enum (Type)

Yalnızca çıkış. Öğrenme hedefinin türü.

standardCode

string

Yalnızca çıkış. Standart kod (ör. "NY-2.NBT.4"). Yalnızca standartlar için doldurulur.

title

string

Yalnızca çıkış. Standartlar için ifade açıklaması veya beceriler için kullanıcılar tarafından okunabilir başlık.

documentTitle

string

Yalnızca çıkış. Müfredat dokümanı adı. Yalnızca standartlar için doldurulur.

Rol

Kullanıcının bir dersteki rolleri.

Sıralamalar
ROLE_UNSPECIFIED Belirtilmemiş rol.
TEACHER Öğretmen rolü.
COTEACHER Yardımcı öğretmen rolü.
STUDENT Öğrenci rolü
INVITED_OR_INACTIVE Davet edilen veya etkin olmayan rol.

Eyalet

Kursun durumları.

Sıralamalar
STATE_UNSPECIFIED Belirtilmemiş durum.
ACTIVE Etkin durumda.
ARCHIVED Arşivlenmiş durum.
PROVISIONED Temel hazırlığı yapılmış durum.

Tür

Öğrenme hedefinin türü.

Sıralamalar
TYPE_UNSPECIFIED Öğrenme hedefi türü belirtilmemiş.
STANDARD Akademik müfredattaki bir öğrenme standardı.
SKILL Eğitimle ilgili bir kavramı veya yeterliliği temsil eden beceri. Classroom'da yalnızca öğretmenler beceri ekleyebilir veya kaldırabilir.

Araç Notları

Araç ek açıklamaları, belirli bir aracın temel riskini açıklamak için MCP istemcilerine gönderilir. Çoğu istemci bu ipuçlarını güvenilir olarak değerlendirmez ancak kullanıcıya ne zaman onay istemi gönderileceğine karar vermek için kullanılabilir.

Başlık dizesiyle birlikte aşağıdaki boole ipuçları şu şekilde tanımlanır:

  • readOnlyHint: Doğru ise araç, ortamını değiştirmez. Varsayılan: false.
  • destructiveHint: Doğru ise araç, yıkıcı işlemler gerçekleştirebilir. "False" ise araç yalnızca ekleme işlemleri gerçekleştirebilir. Varsayılan: true.
  • idempotentHint: Doğru ise aracın aynı bağımsız değişkenlerle tekrar tekrar çağrılması, ortamı üzerinde ek bir etki yaratmaz. Varsayılan: false.
  • openWorldHint: Doğru ise araç, harici varlıkların "açık dünyası" ile etkileşime girebilir. Yanlış ise araç yalnızca dahili varlıklarla etkileşim kurabilir. Örneğin, web arama aracı açık dünya iken bellek aracı açık dünya değildir.

Yıkıcı İpucu: ❌ | Aynı Sonucu Veren İpucu: ✅ | Salt Okunur İpucu: ✅ | Açık Dünya İpucu: ❌

Yetkilendirme Kapsamları

Aşağıdaki OAuth kapsamlarından birini gerektirir:

  • https://www.googleapis.com/auth/classroom.courses.readonly
  • https://www.googleapis.com/auth/classroom.rosters.readonly