MCP Reference: cloudcli.googleapis.com

Il server MCP di Cloud CLI fornisce strumenti per eseguire i comandi di 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 collegano le applicazioni AI a sistemi esterni come database e servizi web, traducendo le loro risposte in un formato che l'applicazione AI può comprendere.

Configurazione del server

Prima dell'uso, devi abilitare i server MCP e configurare l'autenticazione. Per saperne di più 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 (in genere 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 MCP di Google 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 ha i seguenti strumenti:

Strumenti MCP
run_gcloud_command

Esegue un singolo comando gcloud CLI all'interno del progetto Google Cloud dell'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. Utilizza la massima 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") (viene utilizzato per il controllo dell'abilitazione dell'API Cloud CLI Execution, la fatturazione, la quota e così via). NON è lo stesso del 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. Non corretto: --zone us-central1-a o --project my-project.
  3. Progetto di fatturazione: non puoi presupporre alcuna impostazione di progetto o di fatturazione preconfigurata 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 limitati al progetto, PUOI anche specificare --billing-project=PROJECT per sostituire il progetto di quota, che avrà effetto per le API Google Cloud che non supportano la sostituzione del progetto di risorsa.
  4. Ambito del progetto: DEVI SEMPRE passare il flag --project=PROJECT_ID per i comandi limitati al progetto. Non utilizzarlo per i comandi a livello di organizzazione o cartella. Se non fornisci un flag --project per un comando limitato al progetto, il progetto di risorsa utilizzerà per impostazione predefinita il 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. Nella stringa di comando DEVE essere specificato almeno uno tra --project o --billing-project.
  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 dei log: quando utilizzi gcloud logging read, DEVI SEMPRE includere un flag --limit (ad es. --limit=100) per evitare timeout di credenziali e connessioni.
  9. Autocorrezione: 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". Il valore "contents" deve essere testo normale che rappresenta il contenuto del file. Questo è 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 GCE 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 Compute: gcloud compute instances list --project=PROJECT_ID
  7. Recupera il policy IAM per un progetto: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

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

Esegue un singolo comando BigQuery CLI (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. Utilizza la massima cautela. COMANDI VIETATI: un agente NON DEVE eseguire i seguenti comandi bq: bq init, bq load, bq pyshell, bq shell. REGOLE DI ESECUZIONE RIGIDE:

  1. Nella stringa di comando DEVE essere specificato almeno uno tra --project_id o --quota_project_id.
  2. ID progetto rispetto a progetto di quota: il flag --project_id specifica il progetto di risorsa su cui opera il comando (rispecchia il flag --project di gcloud). Il flag --quota_project_id specifica il progetto a cui vengono addebitati i costi di 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 --quota_project_id è specificato in aggiunta, 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'. Non corretto: '--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 senza stato; non carica i 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 es. l'esecuzione di job di query). Per questi comandi, DEVI SEMPRE passare il flag --nosync per evitare timeout dell'agente.
  6. Restrizioni dei comandi: NON DEVI utilizzare i seguenti comandi bq: bq init, bq pyshell, bq shell. L'incanalamento o l'incatenamento dei comandi NON è supportato.
  7. Autocorrezione: 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 di quota.

Esempi di comandi/pattern bq:

  1. Esegui una query: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROM project.dataset.table LIMIT 10'
  2. Crea un set di dati: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Crea una tabella: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Rimuovi un set di dati: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Rimuovi 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

Recupera le specifiche degli strumenti MCP

Per recuperare le specifiche degli strumenti 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
}'