MCP Tools Reference: cloudcli.googleapis.com

Strumento: run_gcloud_command

Esegue un singolo comando dell'interfaccia a riga di 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. 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 è 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. Errato: --zone us-central1-a o --project my-project.
  3. Progetto di fatturazione: non puoi presupporre impostazioni di fatturazione o di progetto preconfigurate 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 eseguire l'override del progetto di quota, che avrà effetto per le API GCP 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 flag --project 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. Nella stringa di comando deve essere specificato almeno uno dei parametri --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 di logging: 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. Questo è utile per i comandi che leggono dai file (ad es. gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID).

Comandi/pattern gcloud di esempio:

  1. Leggi i log dell'istanza 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. Descrivere 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 il criterio 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.

Il seguente esempio mostra come utilizzare curl per richiamare 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'abilitazione dell'API e il consumo di quote per l'API Cloud CLI Execution.

Il formato deve essere projects/ o projects/
command

string

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

Gli 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 attraversamento 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 all'esecuzione dello strumento CLI, contenente stdout, flusso stderr indipendenti e un codice di uscita.
outputFiles[]

object (File)

File generati dall'esecuzione del comando gcloud.

CliExecutionResponse

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

string

Lo stream stdout dall'esecuzione dello strumento CLI.
stderr

string

Il flusso stderr dall'esecuzione dello strumento dell'interfaccia a riga di comando.
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 attraversamento 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: ❌