MCP Tools Reference: cloudcli.googleapis.com

Tool: run_bq_command

Führt einen einzelnen BigQuery-Befehlszeilenbefehl (bq) aus. Mit diesem Tool können Sie jeden bq-Befehl im Projekt des Nutzers ausführen, einschließlich Befehlen, mit denen GCP-Ressourcen erstellt, aktualisiert oder gelöscht werden (d.h. Mutationen).

WICHTIGER SICHERHEITSHINWEIS (POTENZIELL DESTRUKTIV): Mit diesem Tool können BigQuery-Ressourcen erstellt, aktualisiert oder gelöscht werden (z.B. bq rm, bq cancel, bq query). Es ist NICHT auf schreibgeschützte Befehle beschränkt. Seien Sie äußerst vorsichtig.

VERBOTENE BEFEHLE: Ein Agent darf die folgenden bq-Befehle NICHT ausführen: bq init, bq pyshell, bq shell.

STRENGE AUSFÜHRUNGSREGELN:

  1. Im Befehlsstring muss mindestens --project_id oder --quota_project_id angegeben werden.
  2. Projekt-ID im Vergleich zu Kontingentprojekt: Mit dem Flag `--project_id` wird das Ressourcenprojekt angegeben, für das der Befehl ausgeführt wird (entspricht dem Flag `--project` von gcloud). Mit dem Flag `--quota_project_id` wird das Projekt angegeben, das für die Abrechnung/das Kontingent des nachgelagerten BigQuery API-Aufrufs in Rechnung gestellt wird (entspricht dem Flag --billing-project von gcloud). Wenn --project_id im Befehl angegeben ist, wird es als Abrechnungs-/Kontingentprojekt verwendet. Wenn --project_id nicht angegeben ist ODER --quota_project_id zusätzlich angegeben ist, ist das Abrechnungs-/Kontingentprojekt das Projekt, das im Flag --quota_project_id festgelegt ist.
  3. Flag-Formatierung: Sie MÜSSEN immer ein Gleichheitszeichen verwenden, um Flag-Schlüssel von ihren Werten zu trennen. Korrekt: '--project_id=my-project' oder '--location=us'. Falsch: '--project_id my-project' oder '--location us'. Verwenden Sie keine Leerzeichen zwischen Flags und ihren Werten.
  4. Keine Standardkonfigurationen: Der bq-Befehl wird zustandslos ausgeführt. Es werden keine lokalen Konfigurationsdateien wie .bigqueryrc geladen. Daher MÜSSEN Sie für alle regionalen Vorgänge (z.B. das Erstellen eines Datasets oder das Abfragen eines regionalen Datasets) das Flag --location explizit angeben (z.B. --location=us oder --location=EU).
  5. Asynchrone Vorgänge: Einige Befehle starten synchrone, lang andauernde Vorgänge (z.B. das Ausführen von Abfragejobs). Sie SOLLTEN für diese Befehle IMMER das Flag --nosync übergeben, um Agent-Time-outs zu vermeiden.
  6. Befehlsbeschränkungen: Sie DÜRFEN die folgenden bq-Befehle NICHT verwenden: bq init, bq pyshell, bq shell. Befehlspiping oder -verkettung wird NICHT unterstützt.
  7. Selbstkorrektur: Wenn ein Befehl einen Fehler zurückgibt, analysieren Sie die Standardfehlerausgabe, korrigieren Sie die Syntax oder Flags und versuchen Sie es in der nächsten Iteration noch einmal.

Beispiele für mutierende bq-Befehle sind: bq mk, bq rm, bq update, bq insert, bq query (ohne --dry_run) usw. Verwendung: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) Sie MÜSSEN den vollständigen bq-Befehl als einzelnen String im Parameter „command“ angeben. Sie MÜSSEN den Parameter „project“ (Format: projects/PROJECT_ID) als API-Ausführungsprojekt für Abrechnungs-, API-Aktivierungs- und Kontingentnutzungsprüfungen angeben.

Beispiele für bq-Befehle/Muster:

  1. Abfrage ausführen: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. Dataset erstellen: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Tabelle erstellen: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Dataset entfernen: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Tabelle entfernen: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Tabellenbeschreibung aktualisieren: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Datasets in einem Projekt auflisten: bq ls --datasets=true --project_id=PROJECT_ID

Das folgende Codebeispiel zeigt, wie Sie curl verwenden, um das MCP-Tool run_bq_command aufzurufen.

Curl-Anfrage 
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_bq_command",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Eingabeschema

Anfragenachricht für RunBq.

RunBqRequest

JSON-Darstellung 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Felder
project

string

Erforderlich. Projekt für die API-Aktivierung und den Kontingentverbrauch für die CloudCli API.

Das Format muss „projects/ “ oder „projects/“ sein.
command

string

Erforderlich. Die vollständige bq-Befehlszeile, die als einzelner String ausgeführt werden soll. Beispiel: „bq ls my-dataset --location=us“

LLMs werden angewiesen, das Flag --nosync für lang andauernde Vorgänge zu verwenden, um Time-outs zu vermeiden.
inputFiles[]

object (File)

Optional. Dateien, die dem bq-Befehl für die Ausführung zur Verfügung gestellt werden sollen.

Datei

JSON-Darstellung 
{
  "path": string,
  "contents": string
}
Felder
path

string

Erforderlich. Dateipfad relativ zum Basisverzeichnis. Darf keine übergeordneten Verzeichnisse (..) oder Shell-Erweiterungen enthalten.
contents

string

Erforderlich. Inhalt der Datei.

Ausgabeschema

Antwortnachricht für RunBq.

RunBqResponse

JSON-Darstellung 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Felder
response

object (CliExecutionResponse)

Die Antwort von der Ausführung des Befehlszeilentools, die unabhängige Streams für die Standardausgabe und die Standardfehlerausgabe sowie einen Exit-Code enthält.
outputFiles[]

object (File)

Dateien, die vom bq-Befehl bei der Ausführung generiert wurden.

CliExecutionResponse

JSON-Darstellung 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Felder
stdout

string

Der Stream der Standardausgabe von der Ausführung des Befehlszeilentools.
stderr

string

Der Stream der Standardfehlerausgabe von der Ausführung des Befehlszeilentools.
exitCode

string (int64 format)

Der Exit-Code der Ausführung des Befehlszeilentools.

Datei

JSON-Darstellung 
{
  "path": string,
  "contents": string
}
Felder
path

string

Erforderlich. Dateipfad relativ zum Basisverzeichnis. Darf keine übergeordneten Verzeichnisse (..) oder Shell-Erweiterungen enthalten.
contents

string

Erforderlich. Inhalt der Datei.

Tool-Anmerkungen

Destruktiver Hinweis: ✅ | Hinweis auf Idempotenz: ❌ | Hinweis auf schreibgeschützt: ❌ | Hinweis auf offene Welt: ❌