MCP Reference: cloudcli.googleapis.com

Il server Google Cloud CLI MCP fornisce strumenti per eseguire i comandi Google Cloud CLI in un ambiente sandbox remoto.

Un server Model Context Protocol (MCP) funge da proxy tra un servizio esterno che fornisce contesto, dati o funzionalità a un modello linguistico di grandi dimensioni (LLM) o a un'applicazione AI. I server MCP connettono le applicazioni di AI a sistemi esterni come database e servizi web, traducendo le loro risposte in un formato che l'applicazione di AI può comprendere.

Configurazione del server

Prima dell'uso, devi abilitare i server MCP e configurare l'autenticazione. Per ulteriori informazioni sull'utilizzo dei server MCP remoti di Google e Google Cloud, consulta la panoramica dei server MCP di Google Cloud.

Endpoint server

Un endpoint di servizio MCP è l'indirizzo di rete e l'interfaccia di comunicazione (di solito un URL) del server MCP che un'applicazione AI (l'host per il client MCP) utilizza per stabilire una connessione sicura e standardizzata. È il punto di contatto per l'LLM per richiedere il contesto, chiamare uno strumento o accedere a una risorsa. Gli endpoint Google MCP possono essere globali o regionali.

Il server MCP dell'API Cloud CLI Execution ha il seguente endpoint MCP globale:

  • https://cloudcli.googleapis.com/mcp

Strumenti MCP

Uno strumento MCP è una funzione o una funzionalità eseguibile che un server MCP espone a un LLM o a un'applicazione AI per eseguire un'azione nel mondo reale.

Strumenti

Il server MCP cloudcli.googleapis.com dispone dei seguenti strumenti:

Strumenti MCP
run_gcloud_command

Esegue un singolo comando gcloud CLI all'interno del progetto Google Cloud'utente.

AVVISO DI SICUREZZA CRITICO (POTENZIALMENTE DISTRUTTIVO): questo strumento può creare, aggiornare o eliminare risorse Google Cloud (ad es. gcloud compute instances delete). NON è limitato ai comandi di sola lettura. Usa estrema cautela.

COMANDI VIETATI: un agente NON DEVE eseguire i seguenti comandi gcloud (incluse le varianti alpha/beta): app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey.

REGOLE DI ESECUZIONE RIGIDE:

  1. Quando utilizzi questo strumento, DEVI fornire il parametro "project" (ad es. project="projects/PROJECT_ID"), che viene utilizzato per il controllo dell'attivazione dell'API Cloud CLI Execution, la fatturazione, la quota e così via. Questo NON è uguale al flag --project nei comandi gcloud utilizzati per specificare il progetto su cui opera gcloud.
  2. Formattazione dei flag: devi sempre utilizzare il segno "=" per separare le chiavi dei flag dai relativi valori per tutte le opzioni lunghe. Corretto: --zone=us-central1-a o --project=my-project. Errato: --zone us-central1-a o --project my-project.
  3. Progetto di fatturazione: non puoi presupporre alcun progetto preconfigurato o impostazioni di fatturazione nell'ambiente di esecuzione. Per i comandi non limitati al progetto (ad es. a livello di cartella o organizzazione) o per scenari specifici come Cloud Storage Requester Pays, DEVI passare il flag --billing-project=PROJECT. Per i comandi con ambito progetto, PUOI specificare anche --billing-project=PROJECT per ignorare il progetto di quota, che avrà effetto per le API Google Cloud che non supportano l'override del progetto di risorse.
  4. Ambito del progetto: DEVI SEMPRE passare il flag --project=PROJECT_ID per i comandi con ambito del progetto. Non utilizzarlo per i comandi a livello di organizzazione o cartella. Se non fornisci un --project flag per un comando con ambito progetto, il progetto risorsa verrà impostato per impostazione predefinita sul progetto impostato nel flag --billing-project.
  5. Se specifichi il flag --billing-project nel comando gcloud, assicurati che il valore sia un ID progetto o un numero di progetto. Il valore NON DEVE essere un valore speciale (ad es. LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK).
  6. È necessario specificare almeno un valore per --project o --billing-project nella stringa di comando.
  7. Operazioni asincrone: per le operazioni sincrone a lunga esecuzione (ad es. la creazione di una VM o di un database), DEVI SEMPRE passare il flag --async per evitare timeout dell'agente.
  8. Limitazione della frequenza di log: quando utilizzi gcloud logging read, DEVI SEMPRE includere un flag --limit (ad es. --limit=100) per evitare timeout di connessione e delle credenziali.
  9. Correzione automatica: se un comando restituisce un errore, analizza stderr, correggi la sintassi o i flag e riprova nell'iterazione successiva.
  10. input_files: (facoltativo) un elenco di file da creare nell'ambiente prima di eseguire il comando. Ogni file deve avere un "path" (relativo alla directory corrente) e "contents". I "contenuti" devono essere testo normale che rappresenta i contenuti del file. Questa opzione è utile per i comandi che leggono dai file (ad es. gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Esempi di comandi/pattern gcloud:

  1. Leggi i log delle istanze Compute Engine con gravità>=ERROR: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • Tieni presente l'utilizzo delle virgolette per l'espressione di filtro.
  2. Elenca tutti gli endpoint PSC: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. Descrivi un endpoint PSC: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • Tieni presente l'utilizzo di "=" per il flag --region.
  4. Elenca tutti i cluster: gcloud container clusters list --project=PROJECT_ID
  5. Descrivi un cluster: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Elenca le istanze di Compute: gcloud compute instances list --project=PROJECT_ID
  7. Recupera la policy IAM per un progetto: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

Le stringhe di risposta sono formattate per l'output del terminale per impostazione predefinita (stdout o stderr). Utilizza il flag --format per modificare il formato.
run_bq_command

Esegue un singolo comando dell'interfaccia a riga di comando BigQuery (bq). Questo strumento ti consente di eseguire qualsiasi comando bq nel progetto dell'utente, inclusi i comandi che creano, aggiornano o eliminano risorse Google Cloud (ovvero le mutazioni).

AVVISO DI SICUREZZA CRITICO (POTENZIALMENTE DISTRUTTIVO): questo strumento può creare, aggiornare o eliminare risorse BigQuery (ad es. bq rm, bq cancel, bq query). NON è limitato ai comandi di sola lettura. Usa estrema cautela.

COMANDI VIETATI: un agente NON DEVE eseguire i seguenti comandi bq: bq init, bq pyshell, bq shell.

REGOLE DI ESECUZIONE RIGIDE:

  1. È necessario specificare almeno un valore per --project_id o --quota_project_id nella stringa di comando.
  2. ID progetto e progetto quota: il flag --project_id specifica il progetto risorsa su cui opera il comando (rispecchia il flag --project di gcloud). Il flag --quota_project_id specifica il progetto a cui viene addebitata la fatturazione/quota della chiamata API BigQuery downstream (rispecchia il flag --billing-project di gcloud). Se --project_id è specificato nel comando, verrà utilizzato come progetto di fatturazione/quota. Se --project_id non è specificato OPPURE se è specificato anche --quota_project_id, il progetto di fatturazione/quota sarà il progetto impostato nel flag --quota_project_id.
  3. Formattazione dei flag: devi sempre utilizzare il segno "=" per separare le chiavi dei flag dai relativi valori per tutte le opzioni lunghe. Corretto: '--project_id=my-project' o '--location=us'. Errato: '--project_id my-project' o '--location us'. Non utilizzare spazi tra i flag e i relativi valori.
  4. Nessun valore predefinito di configurazione: il comando bq viene eseguito in modo stateless, ovvero non carica file di configurazione locali come .bigqueryrc. Pertanto, per tutte le operazioni regionali (ad es. la creazione di un set di dati o l'esecuzione di query su un set di dati regionale), DEVI specificare esplicitamente il flag --location (ad es. --location=us o --location=EU).
  5. Operazioni asincrone: alcuni comandi avviano operazioni sincrone a lunga esecuzione (ad esempio, l'esecuzione di job di query). Devi SEMPRE passare il flag --nosync per questi comandi per evitare timeout dell'agente.
  6. Limitazioni dei comandi: NON DEVI utilizzare i seguenti comandi bq: bq init, bq pyshell, bq shell. Il piping o l'incatenamento dei comandi NON è supportato.
  7. Correzione automatica: se un comando restituisce un errore, analizza stderr, correggi la sintassi o i flag e riprova nell'iterazione successiva.

Esempi di comandi bq di mutazione includono: bq mk, bq rm, bq update, bq insert, bq query (senza --dry_run) e così via. Utilizzo: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) DEVI fornire il comando bq completo come singola stringa nel parametro "command". Devi fornire il parametro "project" (formato: projects/PROJECT_ID) come progetto di esecuzione dell'API per i controlli di fatturazione, abilitazione dell'API e consumo della quota.

Esempi di comandi/pattern bq:

  1. Esegui una query: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. Crea un set di dati: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Creare una tabella: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Rimuovere un set di dati: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Rimuovere una tabella: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Aggiorna la descrizione della tabella: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Elenca i set di dati in un progetto: bq ls --datasets=true --project_id=PROJECT_ID

Ottenere le specifiche dello strumento MCP

Per ottenere le specifiche dello strumento MCP per tutti gli strumenti in un server MCP, utilizza il metodo tools/list. L'esempio seguente mostra come utilizzare curl per elencare tutti gli strumenti e le relative specifiche attualmente disponibili nel server MCP.

Richiesta curl 
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
    "method": "tools/list",
    "jsonrpc": "2.0",
    "id": 1
}'