MCP Tools Reference: cloudcli.googleapis.com

Herramienta: run_bq_command

Ejecuta un solo comando de la CLI de BigQuery (bq). Esta herramienta te permite ejecutar cualquier comando bq en el proyecto del usuario, incluidos los comandos que crean, actualizan o borran recursos de GCP (es decir, mutaciones).

ADVERTENCIA DE SEGURIDAD CRÍTICA (POTENCIALMENTE DESTRUCTIVA): Esta herramienta puede crear, actualizar o borrar recursos de BigQuery (p.ej., bq rm, bq cancel, bq query). NO se limita a los comandos de solo lectura. Úsala con extrema precaución.

COMANDOS PROHIBIDOS: Un agente NO DEBE ejecutar los siguientes comandos bq: bq init, bq pyshell, bq shell.

REGLAS DE EJECUCIÓN ESTRICTAS:

  1. Se DEBE especificar al menos uno de --project_id o --quota_project_id en la cadena de comandos.
  2. ID del proyecto en comparación con el proyecto de cuota: La marca --project_id especifica el proyecto de recursos en el que opera el comando (refleja la marca --project de gcloud). La marca --quota_project_id especifica el proyecto que se cobra por la facturación o la cuota de la llamada a la API de BigQuery descendente (refleja la marca --billing-project de gcloud). Si se especifica --project_id en el comando, se usará como el proyecto de facturación o cuota. Si no se especifica --project_id O se especifica --quota_project_id de forma adicional, el proyecto de facturación o cuota será el proyecto establecido en la marca --quota_project_id.
  3. Formato de marcas: SIEMPRE debes usar un signo "=" para separar las claves de marca de sus valores para todas las opciones largas. Correcto: '--project_id=my-project' o '--location=us'. Incorrecto: '--project_id my-project' o '--location us'. No uses espacios entre las marcas y sus valores.
  4. Sin valores predeterminados de configuración: El comando bq se ejecuta sin estado; no carga archivos de configuración locales como .bigqueryrc. Por lo tanto, para todas las operaciones regionales (p.ej., crear un conjunto de datos o consultar un conjunto de datos regional), DEBES especificar de forma explícita la marca --location (p.ej., --location=us o --location=EU).
  5. Operaciones asíncronas: Algunos comandos inician operaciones síncronas de larga duración (p.ej., ejecutar trabajos de consulta). SIEMPRE debes pasar la marca --nosync para que estos comandos eviten los tiempos de espera del agente.
  6. Restricciones de comandos: NO DEBES usar los siguientes comandos bq: bq init, bq pyshell, bq shell. NO se admite la canalización ni el encadenamiento de comandos.
  7. Autocorrección: Si un comando muestra un error, analiza stderr, corrige la sintaxis o las marcas y vuelve a intentarlo en la siguiente iteración.

Entre los ejemplos de comandos bq mutantes, se incluyen los siguientes: bq mk, bq rm, bq update, bq insert, bq query (sin --dry_run), etc. Uso: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) DEBES proporcionar el comando bq completo como una sola cadena en el parámetro "command". DEBES proporcionar el parámetro "project" (formato: projects/PROJECT_ID) como el proyecto de ejecución de la API para la facturación, la habilitación de la API y las verificaciones de consumo de cuota.

Ejemplos de comandos o patrones de bq:

  1. Ejecuta una consulta: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. Crea un conjunto de datos: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Crea una tabla: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Quita un conjunto de datos: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Quita una tabla: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Actualiza la descripción de la tabla: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Enumera los conjuntos de datos de un proyecto: bq ls --datasets=true --project_id=PROJECT_ID

En la siguiente muestra de código, se muestra cómo usar curl para llamar a la herramienta MCP run_bq_command.

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

Esquema de entrada

Mensaje de solicitud para RunBq.

RunBqRequest

Representación JSON 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Campos
project

string

Obligatorio. Proyecto para la habilitación de la API y el consumo de cuota de la API de CloudCli.

El formato debe ser projects/ o projects/
command

string

Obligatorio. La línea de comandos bq completa para ejecutar como una sola cadena. Ejemplo: "bq ls my-dataset --location=us"

Se les indica a los LLM que usen la marca --nosync para las operaciones de larga duración para evitar los tiempos de espera.
inputFiles[]

object (File)

Es opcional. Archivos que se pondrán a disposición del comando bq para su ejecución.

Archivo

Representación JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obligatorio. Ruta de acceso al archivo relativa al directorio principal. No debe contener el recorrido del directorio superior (..) ni las expansiones de shell.
contents

string

Obligatorio. Contenido del archivo.

Esquema de salida

Mensaje de respuesta para RunBq.

RunBqResponse

Representación JSON 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Campos
response

object (CliExecutionResponse)

La respuesta de la ejecución de la herramienta de CLI, que contiene stdout, stderr y un código de salida independientes.
outputFiles[]

object (File)

Archivos generados por el comando bq a partir de su ejecución.

CliExecutionResponse

Representación JSON 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Campos
stdout

string

El flujo stdout de la ejecución de la herramienta de CLI.
stderr

string

El flujo stderr de la ejecución de la herramienta de CLI.
exitCode

string (int64 format)

El código de salida de la ejecución de la herramienta de CLI.

Archivo

Representación JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obligatorio. Ruta de acceso al archivo relativa al directorio principal. No debe contener el recorrido del directorio superior (..) ni las expansiones de shell.
contents

string

Obligatorio. Contenido del archivo.

Anotaciones de herramientas

Sugerencia destructiva: ✅ | Sugerencia idempotente: ❌ | Sugerencia de solo lectura: ❌ | Sugerencia de mundo abierto: ❌