# BigQuery MCP

이 패키지는 Google BigQuery API를 사용하여 특정 쿼리를 실행하고, 그 결과를 반환하거나 CSV 파일로 저장하는 Model Context Protocol(MCP) 도구입니다.

## 기능

- **BigQuery 연동**: Google BigQuery 서비스와 안전하게 연동합니다.
- **쿼리 실행 및 결과 반환**:
  - `run_bigquery_query`: 지정된 SQL 쿼리를 BigQuery에서 실행하고 결과를 직접 반환합니다.
- **쿼리 결과 다운로드**:
  - `download_bigquery_query`: 지정된 SQL 쿼리를 실행하고, 그 결과를 CSV 파일로 지정된 또는 기본 경로에 저장합니다. 저장된 파일 경로를 반환합니다.
  - `download_bigquery_query_transpose`: `download_bigquery_query`와 유사하나, 결과를 CSV로 저장하기 전에 행과 열을 전치(transpose)합니다.
- **MCP 서버 기본 설정**: MCP 표준을 준수하는 서버 구조를 가집니다.
- **TypeScript 설정**: 타입 안정성을 위한 TypeScript 기반입니다.
- **서비스 및 도구 분리**: 로직을 서비스와 도구 레이어로 분리하여 관리 용이성을 높였습니다.
- **중앙화된 설정 관리**: `src/config/index.ts`를 통해 환경 변수 기반의 설정을 관리합니다.

## 인증 및 환경 변수

이 MCP 도구를 사용하기 위해서는 Google Cloud Platform (GCP) 인증 설정 및 프로젝트 ID 지정이 필요합니다.

1.  **필수 환경 변수**:

    - `BIGQUERY_PROJECT_ID`: 쿼리를 실행할 Google Cloud 프로젝트의 ID입니다.
      ```bash
      export BIGQUERY_PROJECT_ID="your-gcp-project-id"
      ```

2.  **Google Cloud 인증 방법 (다음 중 하나를 선택)**:

    - **방법 1: 서비스 계정 키 파일 사용 (권장)**
      - GCP 서비스 계정을 생성하고, 해당 서비스 계정에 BigQuery 관련 권한(예: BigQuery 데이터 뷰어, BigQuery 사용자 등)을 부여합니다.
      - 서비스 계정 키(JSON 파일)를 다운로드합니다.
      - 다운로드한 서비스 계정 키 파일의 경로를 `GOOGLE_APPLICATION_CREDENTIALS` 환경 변수에 설정합니다.
        ```bash
        export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
        ```
    - **방법 2: 서비스 계정 JSON 문자열 직접 사용**
      - 서비스 계정 키의 JSON 내용을 문자열 형태로 `BIGQUERY_CREDENTIALS_JSON` 환경 변수에 설정합니다. JSON 문자열 내의 특수 문자(예: 줄바꿈, 따옴표)는 올바르게 이스케이프되거나, 전체 문자열을 Base64로 인코딩하여 저장 후 애플리케이션에서 디코딩하는 방식을 고려할 수 있습니다. (현재 구현은 Raw JSON 문자열을 가정합니다.)
        ```bash
        # 예시: 실제 키 값은 매우 길고 복잡합니다.
        export BIGQUERY_CREDENTIALS_JSON='{"type": "service_account", "project_id": "...", ...}'
        ```
      - **참고**: 이 방법은 `GOOGLE_APPLICATION_CREDENTIALS`보다 우선적으로 사용됩니다. 둘 다 설정된 경우 경고가 표시됩니다.
    - **방법 3: Application Default Credentials (ADC)**
      - 위 두 환경 변수가 설정되지 않은 경우, Google Cloud SDK는 ADC를 사용하여 인증을 시도합니다. (예: `gcloud auth application-default login`으로 로컬 개발 환경 설정, 또는 Cloud Run, GKE 등에서 자동으로 주입되는 서비스 계정 사용)

3.  **다운로드 디렉토리 (선택 사항)**:
    - `download_bigquery_query` 및 `download_bigquery_query_transpose` 도구를 사용하여 파일을 저장할 때, 기본 저장 경로는 사용자 홈 디렉토리의 `Downloads` 폴더입니다.
    - 다른 디렉토리를 사용하고 싶다면 `BIGQUERY_DOWNLOAD_DIR` 환경 변수를 설정하여 원하는 경로를 지정할 수 있습니다.
      ```bash
      export BIGQUERY_DOWNLOAD_DIR="/custom/download/path"
      ```

## 프로젝트 구조

```
apps/bigquery-mcp/
├── src/
│   ├── config/
│   │   └── index.ts            # 환경 변수 로드 및 설정 객체 관리
│   ├── services/
│   │   └── BigQueryService.ts  # BigQuery 클라이언트 초기화 및 핵심 쿼리 실행 로직
│   ├── tools/
│   │   ├── runBigQueryQuery.ts             # 'run_bigquery_query' 도구 정의
│   │   ├── downloadBigQueryQuery.ts        # 'download_bigquery_query' 도구 정의
│   │   └── downloadBigQueryQueryTranspose.ts # 'download_bigquery_query_transpose' 도구 정의
│   └── index.ts                # 메인 진입점 (MCP 서버 초기화 및 도구 등록)
├── package.json
├── README.md
└── tsconfig.json
```

## 새 패키지 생성 시 참고사항 (원본 보일러플레이트 기준)

이 패키지를 새로운 MCP 도구의 시작점으로 사용하려면:

1.  디렉토리 이름을 변경하고 모든 파일의 `bigquery-mcp` 참조를 새 이름으로 변경 (현재 프로젝트는 이미 `bigquery-mcp`로 설정됨)
2.  `package.json`의 패키지 이름 업데이트
3.  `package.json`에서 `"private": true,` 부분 제거 (필요시)
4.  필요한 의존성 추가
5.  서비스 및 도구 디렉토리와 구현 파일 추가

## 라이선스

Channel 내부용