MCP Tools Reference: cloudcli.googleapis.com

Strumento: run_gcloud_command

Esegue un singolo comando della gcloud CLI nel 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. Utilizzalo con 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") (viene utilizzato per il controllo dell'attivazione 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 che siano presenti progetti o impostazioni di fatturazione preconfigurati 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 risorse.
  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 --project flag per un comando limitato al progetto, il progetto di risorse 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 campo "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
    • Nota 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
    • Nota 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. Ottieni il criterio 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.

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

Richiesta curl 
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "run_gcloud_command",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schema di input

Messaggio di richiesta per RunGcloud.

RunGcloudRequest

Rappresentazione JSON 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Campi
project

string

Obbligatorio. Progetto per l'attivazione dell'API e il consumo di quota per l'API Cloud CLI Execution.

Il formato deve essere projects/ o projects/
command

string

Obbligatorio. La riga di comando gcloud completa da eseguire come singola stringa. Esempio: "gcloud compute instances create my-vm --zone=us-central1-a"

I LLM sono istruiti a utilizzare il flag --async per le operazioni a lunga esecuzione per evitare timeout.
inputFiles[]

object (File)

Facoltativo. File da rendere disponibili al comando gcloud per la sua esecuzione.

File

Rappresentazione JSON 
{
  "path": string,
  "contents": string
}
Campi
path

string

Obbligatorio. Percorso del file relativo alla home directory. Non deve contenere attraversamenti della directory principale (..) o espansioni della shell.
contents

string

Obbligatorio. Contenuti del file.

Schema di output

Messaggio di risposta per RunGCloud.

RunGcloudResponse

Rappresentazione JSON 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Campi
response

object (CliExecutionResponse)

La risposta dall'esecuzione dello strumento CLI, contenente stream stdout, stderr indipendenti e un codice di uscita.
outputFiles[]

object (File)

File generati dal comando gcloud durante l'esecuzione.

CliExecutionResponse

Rappresentazione JSON 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Campi
stdout

string

Lo stream stdout dall'esecuzione dello strumento CLI.
stderr

string

Lo stream stderr dall'esecuzione dello strumento CLI.
exitCode

string (int64 format)

Il codice di uscita dell'esecuzione dello strumento CLI.

File

Rappresentazione JSON 
{
  "path": string,
  "contents": string
}
Campi
path

string

Obbligatorio. Percorso del file relativo alla home directory. Non deve contenere attraversamenti della directory principale (..) o espansioni della shell.
contents

string

Obbligatorio. Contenuti del file.

Annotazioni dello strumento

Suggerimento distruttivo: ✅ | Suggerimento idempotente: ❌ | Suggerimento di sola lettura: ❌ | Suggerimento Open World: ❌