MCP Tools Reference: cloudcli.googleapis.com

Ferramenta: run_bq_command

Executa um único comando da CLI do BigQuery (bq). Essa ferramenta permite executar qualquer comando bq no projeto do usuário, incluindo comandos que criam, atualizam ou excluem recursos do GCP (ou seja, mutações).

AVISO DE SEGURANÇA CRÍTICO (POTENCIALMENTE DESTRUTIVO): essa ferramenta pode criar, atualizar ou excluir recursos do BigQuery (por exemplo, bq rm, bq cancel, bq query). Ela NÃO é restrita a comandos somente leitura. Use com extrema cautela.

COMANDOS PROIBIDOS: um agente NÃO PODE executar os seguintes comandos bq: bq init, bq pyshell, bq shell.

REGRAS DE EXECUÇÃO ESTRITAS:

  1. Pelo menos um de --project_id ou --quota_project_id PRECISA ser especificado na string de comando.
  2. ID do projeto x projeto de cota: a flag --project_id especifica o projeto de recurso em que o comando opera (reflete a flag --project do gcloud). A flag --quota_project_id especifica o projeto cobrado pelo faturamento/cota da chamada da API BigQuery downstream (reflete a flag --billing-project do gcloud). Se --project_id for especificado no comando, ele será usado como o projeto de faturamento/cota. Se --project_id não for especificado OU --quota_project_id também for especificado, o projeto de faturamento/cota será o projeto definido na flag --quota_project_id.
  3. Formatação de flag: você PRECISA sempre usar um sinal "=" para separar as chaves de flag dos valores de todas as opções longas. Correto: '--project_id=my-project' ou '--location=us'. Incorreto: '--project_id my-project' ou '--location us'. Não use espaços entre as flags e os valores delas.
  4. Sem padrões de configuração: o comando bq é executado de maneira sem estado. Ele não carrega arquivos de configuração locais, como .bigqueryrc. Portanto, para todas as operações regionais (por exemplo, criar um conjunto de dados ou consultar um conjunto de dados regional), você PRECISA especificar explicitamente a --location flag (por exemplo, --location=us ou --location=EU).
  5. Operações assíncronas: alguns comandos iniciam operações síncronas de longa duração (por exemplo, executar jobs de consulta). Você SEMPRE PRECISA transmitir a flag --nosync para esses comandos para evitar tempos limite do agente.
  6. Restrições de comando: você NÃO PODE usar os seguintes comandos bq: bq init, bq pyshell, bq shell. O encadeamento ou o pipeline de comandos NÃO são aceitos.
  7. Autocorreção: se um comando retornar um erro, analise o stderr, corrija a sintaxe ou as flags e tente novamente na próxima iteração.

Exemplos de comandos bq de mutação incluem: bq mk, bq rm, bq update, bq insert, bq query (sem --dry_run) etc. Uso: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) Você PRECISA fornecer o comando bq completo como uma única string no parâmetro "command". Você PRECISA fornecer o parâmetro "project" (formato: projects/PROJECT_ID) como o projeto de execução da API para faturamento, ativação da API e verificações de consumo de cota.

Exemplos de comandos/padrões bq:

  1. Executar uma consulta: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. Criar um conjunto de dados: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. Criar uma tabela: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. Remover um conjunto de dados: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. Remover uma tabela: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. Atualizar a descrição da tabela: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. Listar conjuntos de dados em um projeto: bq ls --datasets=true --project_id=PROJECT_ID

O exemplo de código a seguir mostra como usar curl para chamar a ferramenta MCP run_bq_command.

Solicitação 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

Mensagem de solicitação para RunBq.

RunBqRequest

Representação JSON 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
Campos
project

string

Obrigatório. Projeto para ativação da API e consumo de cota da API CloudCli.

O formato precisa ser projects/ ou projects/
command

string

Obrigatório. A linha de comando bq completa a ser executada como uma única string. Exemplo: "bq ls my-dataset --location=us"

Os LLMs são instruídos a usar a flag --nosync para operações de longa duração para evitar tempos limite.
inputFiles[]

object (File)

Opcional. Arquivos a serem disponibilizados para o comando bq para execução.

Arquivo

Representação JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obrigatório. Caminho do arquivo relativo ao diretório principal. Não pode conter travessia de diretório pai (..) ou expansões de shell.
contents

string

Obrigatório. Conteúdo do arquivo.

Esquema de saída

Mensagem de resposta para RunBq.

RunBqResponse

Representação JSON 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
Campos
response

object (CliExecutionResponse)

A resposta da execução da ferramenta de CLI, contendo stdout independente, fluxo stderr e um código de saída.
outputFiles[]

object (File)

Arquivos gerados pelo comando bq da execução.

CliExecutionResponse

Representação JSON 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
Campos
stdout

string

O fluxo stdout da execução da ferramenta de CLI.
stderr

string

O fluxo stderr da execução da ferramenta de CLI.
exitCode

string (int64 format)

O código de saída da execução da ferramenta de CLI.

Arquivo

Representação JSON 
{
  "path": string,
  "contents": string
}
Campos
path

string

Obrigatório. Caminho do arquivo relativo ao diretório principal. Não pode conter travessia de diretório pai (..) ou expansões de shell.
contents

string

Obrigatório. Conteúdo do arquivo.

Anotações de ferramentas

Dica destrutiva: ✅ | Dica idempotente: ❌ | Dica somente leitura: ❌ | Dica de mundo aberto: ❌