MCP Tools Reference: cloudcli.googleapis.com

도구: run_bq_command

단일 BigQuery CLI (bq) 명령어를 실행합니다. 이 도구를 사용하면 GCP 리소스 (즉, 변경)를 만들거나 업데이트하거나 삭제하는 명령어를 포함하여 사용자의 프로젝트에서 모든 bq 명령어를 실행할 수 있습니다.

중요한 안전 경고 (잠재적으로 파괴적): 이 도구는 BigQuery 리소스 (bq rm, bq cancel, bq query 등)를 만들거나 업데이트하거나 삭제할 수 있습니다. 읽기 전용 명령어로 제한되지 않습니다. 매우 주의하세요.

금지된 명령어: 에이전트는 bq init, bq pyshell, bq shell bq 명령어를 실행해서는 안 됩니다.

엄격한 실행 규칙:

  1. 명령어 문자열에 --project_id 또는 --quota_project_id 중 하나 이상을 지정해야 합니다.
  2. 프로젝트 ID와 할당량 프로젝트: --project_id 플래그는 명령어가 작동하는 리소스 프로젝트를 지정합니다 (gcloud의 --project 플래그를 미러링함). --quota_project_id 플래그는 다운스트림 BigQuery API 호출의 결제/할당량에 대해 청구되는 프로젝트를 지정합니다 (gcloud의 --billing-project 플래그를 미러링함). 명령어에 --project_id가 지정되면 결제/할당량 프로젝트로 사용됩니다. --project_id가 지정되지 않거나 --quota_project_id가 추가로 지정된 경우 결제/할당량 프로젝트는 --quota_project_id 플래그에 설정된 프로젝트가 됩니다.
  3. 플래그 형식 지정: 모든 긴 옵션에 대해 항상 '=' 기호를 사용하여 플래그 키와 값을 구분해야 합니다. 올바른 예: '--project_id=my-project' 또는 '--location=us'. 잘못된 예: '--project_id my-project' 또는 '--location us'. 플래그와 값 사이에 공백을 사용하지 마세요.
  4. 구성 기본값 없음: bq 명령어는 상태 비저장 방식으로 실행됩니다. .bigqueryrc와 같은 로컬 구성 파일을 로드하지 않습니다. 따라서 모든 리전 작업 (예: 데이터 세트 만들기 또는 리전 데이터 세트 쿼리)의 경우 --location 플래그 (예: --location=us 또는 --location=EU)를 명시적으로 지정해야 합니다.
  5. 비동기 작업: 일부 명령어는 동기식 장기 실행 작업 (예: 쿼리 작업 실행)을 시작합니다. 에이전트 시간 초과를 방지하려면 이러한 명령어에 항상 --nosync 플래그를 전달해야 합니다.
  6. 명령어 제한: bq init, bq pyshell, bq shell bq 명령어를 사용해서는 안 됩니다. 명령어 파이핑 또는 체이닝은 지원되지 않습니다.
  7. 자가 수정: 명령어가 오류를 반환하면 stderr를 분석하고, 문법 또는 플래그를 수정하고, 다음 반복에서 다시 시도합니다.

변경 bq 명령어의 예로는 bq mk, bq rm, bq update, bq insert, bq query (--dry_run 없음) 등이 있습니다. 사용법: RunBq(command="bq query --project_id=PROJECT_ID 'SELECT 1'", project="projects/PROJECT_ID", input_files=[{"path": "PATH", "contents": "CONTENTS"}]) 'command' 매개변수에 전체 bq 명령어를 단일 문자열로 제공해야 합니다. 결제, API 사용 설정, 할당량 소비 확인을 위한 API 실행 프로젝트로 'project' 매개변수 (형식: projects/PROJECT_ID)를 제공해야 합니다.

bq 명령어/패턴 예:

  1. 쿼리 실행: bq query --use_legacy_sql=false --project_id=PROJECT_ID 'SELECT * FROMproject.dataset.tableLIMIT 10'
  2. 데이터 세트 만들기: bq mk --dataset --location=us --project_id=PROJECT_ID myDataset
  3. 테이블 만들기: bq mk --table --project_id=PROJECT_ID myDataset.myTable name:string,value:integer
  4. 데이터 세트 삭제: bq rm -f --dataset --project_id=PROJECT_ID myDataset
  5. 테이블 삭제: bq rm -f -t --project_id=PROJECT_ID myDataset.myTable
  6. 테이블 설명 업데이트: bq update --description="New description" --project_id=PROJECT_ID myDataset.myTable
  7. 프로젝트의 데이터 세트 나열: bq ls --datasets=true --project_id=PROJECT_ID

다음 코드 샘플은 curl을 사용하여 run_bq_command MCP 도구를 호출하는 방법을 보여줍니다.

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
}'

입력 스키마

RunBq의 요청 메시지입니다.

RunBqRequest

JSON 표현 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
필드
project

string

필수 항목입니다. CloudCli API의 API 사용 설정 및 할당량 소비를 위한 프로젝트입니다.

형식은 projects/ 또는 projects/
command

string

필수 항목입니다. 단일 문자열로 실행할 전체 bq 명령어 줄입니다. 예: 'bq ls my-dataset --location=us'

LLM은 시간 초과를 방지하기 위해 장기 실행 작업에 --nosync 플래그를 사용하도록 안내됩니다.
inputFiles[]

object (File)

선택사항입니다. 실행을 위해 bq 명령어에 제공할 파일입니다.

파일

JSON 표현 
{
  "path": string,
  "contents": string
}
필드
path

string

필수 항목입니다. 홈 디렉터리를 기준으로 하는 파일 경로입니다. 상위 디렉터리 탐색 (..) 또는 셸 확장을 포함해서는 안 됩니다.
contents

string

필수 항목입니다. 파일의 콘텐츠입니다.

출력 스키마

RunBq의 응답 메시지입니다.

RunBqResponse

JSON 표현 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
필드
response

object (CliExecutionResponse)

독립적인 stdout, stderr 스트림과 종료 코드를 포함하는 CLI 도구 실행의 응답입니다.
outputFiles[]

object (File)

실행에서 bq 명령어로 생성된 파일입니다.

CliExecutionResponse

JSON 표현 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
필드
stdout

string

CLI 도구 실행의 stdout 스트림입니다.
stderr

string

CLI 도구 실행의 stderr 스트림입니다.
exitCode

string (int64 format)

CLI 도구 실행의 종료 코드입니다.

파일

JSON 표현 
{
  "path": string,
  "contents": string
}
필드
path

string

필수 항목입니다. 홈 디렉터리를 기준으로 하는 파일 경로입니다. 상위 디렉터리 탐색 (..) 또는 셸 확장을 포함해서는 안 됩니다.
contents

string

필수 항목입니다. 파일의 콘텐츠입니다.

도구 주석

파괴적 힌트: ✅ | 멱등성 힌트: ❌ | 읽기 전용 힌트: ❌ | 개방형 세계 힌트: ❌