MCP Tools Reference: classroommcp.googleapis.com

Strumento: list_courses

Elenca i corsi dell'utente con i relativi dettagli (sezione, aula, materia, livelli scolastici, descrizione, obiettivi di apprendimento, stato e ruolo dell'utente). Utilizzalo come punto di accesso principale per scoprire i corsi e recuperare i relativi ID. I corsi spesso condividono un titolo, quindi utilizza la sezione per distinguerli. Restituisce solo i corsi ATTIVI, a meno che non sia impostato courseState (ad es. ARCHIVED).

Per collegare l'utente a un corso nell'app web Classroom, utilizza https://classroom.google.com/c/{course_id} (stream) o https://classroom.google.com/w/{course_id}/t/all (pagina Lavori del corso). Utilizza gli ID esattamente come vengono restituiti; non indovinarli o modificarli.

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP list_courses.

Richiesta 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
}'

Schema di input

Richiesta di elencare i corsi.

ListCoursesRequest

Rappresentazione JSON
{
  "courseState": enum (State),
  "createdDateRange": {
    object (DateRange)
  },
  "timeZone": string,
  "titleContains": string,
  "pageSize": integer,
  "pageToken": string
}
Campi
courseState

enum (State)

Facoltativo. Filtra per stato del corso. Il valore predefinito è ACTIVE.

createdDateRange

object (DateRange)

Facoltativo. Filtra in base all'intervallo di date di creazione.

timeZone

string

Obbligatorio. Il fuso orario IANA dell'utente (ad es. "America/Los_Angeles"). Le date di questa richiesta vengono interpretate in questo fuso orario e le date della risposta vengono formattate in questo fuso orario, in modo da corrispondere a ciò che l'utente vede in Classroom.

titleContains

string

Facoltativo. Filtra il titolo in base alla sottostringa senza distinzione tra maiuscole e minuscole.

pageSize

integer

Facoltativo. Controlla le dimensioni della pagina. Il valore predefinito è 10; il valore massimo è 50.

pageToken

string

Facoltativo. Token per l'impaginazione.

DateRange

Rappresentazione JSON
{
  "startDate": string,
  "endDate": string
}
Campi
startDate

string

Inizio dell'intervallo (formato: AAAA-MM-GG).

endDate

string

Fine inclusiva dell'intervallo (formato: AAAA-MM-GG).

Stato

Stati di un corso.

Enum
STATE_UNSPECIFIED Stato non specificato.
ACTIVE Stato attivo.
ARCHIVED Stato archiviato.
PROVISIONED Stato di provisioning.

Schema di output

Risposta per elencare i corsi.

ListCoursesResponse

Rappresentazione JSON
{
  "courses": [
    {
      object (Course)
    }
  ],
  "nextPageToken": string
}
Campi
courses[]

object (Course)

L'elenco dei corsi.

nextPageToken

string

Il token di pagina successiva.

Corso

Rappresentazione 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)
    }
  ]
}
Campi
id

string

Identificatore. Identificatore di questo corso.

title

string

Il titolo del corso.

role

enum (Role)

Ruolo dell'utente in questo corso.

creationDate

string

Data di creazione del corso (formato: AAAA-MM-GG). Vuoto se la data di creazione non è nota.

state

enum (State)

Solo output. Stato del corso.

section

string

Facoltativo. in questa sezione del corso.

room

string

Facoltativo. Aula del corso.

subject

string

Facoltativo. Oggetto del corso.

gradeLevels

string

Facoltativo. Livelli scolastici del corso.

description

string

Facoltativo. Descrizione del corso.

learningGoals[]

object (LearningGoal)

Solo output. Obiettivi di apprendimento collegati a questo corso.

LearningGoal

Rappresentazione JSON
{
  "id": string,
  "type": enum (Type),
  "standardCode": string,
  "title": string,
  "documentTitle": string
}
Campi
id

string

Solo output. ID dell'obiettivo di apprendimento. Per allegare uno standard, utilizza un id di search_course_standards (non standardCode).

type

enum (Type)

Solo output. Il tipo di obiettivo di apprendimento.

standardCode

string

Solo output. Codice standard (ad es. "NY-2.NBT.4"). Compilato solo per gli standard.

title

string

Solo output. Descrizione dell'istruzione per gli standard o titolo leggibile per le competenze.

documentTitle

string

Solo output. Nome del documento del programma. Compilato solo per gli standard.

Ruolo

Ruoli di un utente in un corso.

Enum
ROLE_UNSPECIFIED Ruolo non specificato.
TEACHER Ruolo Insegnante.
COTEACHER Ruolo Co-insegnante.
STUDENT Ruolo Studente.
INVITED_OR_INACTIVE Ruolo invitato o inattivo.

Stato

Stati di un corso.

Enum
STATE_UNSPECIFIED Stato non specificato.
ACTIVE Stato attivo.
ARCHIVED Stato archiviato.
PROVISIONED Stato di provisioning.

Tipo

Il tipo di obiettivo di apprendimento.

Enum
TYPE_UNSPECIFIED Tipo di obiettivo di apprendimento non specificato.
STANDARD Uno standard di apprendimento di un programma accademico.
SKILL Una competenza che rappresenta un concetto o una competenza didattica. Solo un insegnante può aggiungere o rimuovere competenze in Classroom.

Annotazioni dello strumento

Le annotazioni degli strumenti vengono inviate ai client MCP per descrivere il rischio di base di un determinato strumento. La maggior parte dei client considera questi suggerimenti come non attendibili, ma possono essere utilizzati per decidere quando inviare una richiesta di conferma a un utente.

Oltre alla stringa del titolo, i seguenti suggerimenti booleani sono definiti come segue:

  • readOnlyHint: se true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se true, lo strumento può eseguire azioni distruttive. Se false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se true, la chiamata ripetuta dello strumento con gli stessi argomenti non avrà alcun effetto aggiuntivo sul suo ambiente. Valore predefinito: false.
  • openWorldHint: se true, lo strumento può interagire con un "open world" di entità esterne. Se è impostato su false, lo strumento può interagire solo con entità interne. Ad esempio, uno strumento di ricerca web sarebbe open world, mentre uno strumento di memoria non lo sarebbe.

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ✅ | Suggerimento di sola lettura: ✅ | Suggerimento open world: ❌

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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