Hologres

English | 中文

Hologres MCP Server

Hologres MCP Server는 AI 에이전트와 Hologres 데이터베이스 간의 범용 인터페이스 역할을 합니다. AI 에이전트와 Hologres 간의 원활한 통신을 가능하게 하여, AI 에이전트가 Hologres 데이터베이스 메타데이터를 조회하고 SQL 작업을 실행할 수 있도록 지원합니다.

구성

모드 1: 로컬 파일 사용

다운로드

Github에서 다운로드

git clone https://github.com/aliyun/alibabacloud-hologres-mcp-server.git

MCP 통합

MCP 클라이언트 구성 파일에 다음 설정을 추가하세요:

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/alibabacloud-hologres-mcp-server",
                "run",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

모드 2: PIP 모드 사용

설치

다음 패키지를 사용하여 MCP Server를 설치하세요:

pip install hologres-mcp-server

MCP 통합

MCP 클라이언트 구성 파일에 다음 설정을 추가하세요:

uv 모드 사용

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "hologres-mcp-server",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

uvx 모드 사용

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uvx",
            "args": [
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

모드 3: Streamable HTTP 전송 사용

이 서버는 STDIO를 사용할 수 없는 원격 배포 시나리오를 위해 Streamable HTTP 전송을 지원합니다.

서버 시작

서버를 시작하기 전에 Hologres 연결 환경 변수를 설정하세요:

export HOLOGRES_HOST="your-hologres-instance.hologres.aliyuncs.com"
export HOLOGRES_PORT="80"
export HOLOGRES_USER="your_access_id"
export HOLOGRES_PASSWORD="your_access_key"
export HOLOGRES_DATABASE="your_database"

그런 다음 서버를 시작하세요:

# Using pip-installed package
hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

# Or using uvx
uvx hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

MCP 엔드포인트는 http://<host>:<port>/mcp에서 사용할 수 있습니다.

CLI 옵션

옵션	기본값	설명
--transport	stdio	전송 유형: stdio, streamable-http, 또는 sse
--host	127.0.0.1	바인딩할 호스트 (HTTP 전송만 해당)
--port	8000	수신 대기할 포트 (HTTP 전송만 해당)

MCP 통합

MCP 클라이언트 구성 파일에 다음 설정을 추가하세요:

{
    "mcpServers": {
        "hologres-mcp-server": {
            "url": "http://<host>:<port>/mcp"
        }
    }
}

Claude Code와 함께 사용하기

# Add to Claude Code
claude mcp add hologres-mcp-server \
  -e HOLOGRES_HOST=<your_host> \
  -e HOLOGRES_PORT=<your_port> \
  -e HOLOGRES_USER=<your_access_id> \
  -e HOLOGRES_PASSWORD=<your_access_key> \
  -e HOLOGRES_DATABASE=<your_database> \
  -- uvx hologres-mcp-server

구성 요소

도구

• execute_hg_select_sql: Hologres 데이터베이스에서 SELECT SQL 쿼리 실행
• execute_hg_select_sql_with_serverless: 서버리스 컴퓨팅으로 Hologres 데이터베이스에서 SELECT SQL 쿼리 실행
• execute_hg_dml_sql: Hologres 데이터베이스에서 DML (INSERT, UPDATE, DELETE) SQL 쿼리 실행
• execute_hg_ddl_sql: Hologres 데이터베이스에서 DDL (CREATE, ALTER, DROP, COMMENT ON) SQL 쿼리 실행
• gather_hg_table_statistics: Hologres 데이터베이스에서 테이블 통계 수집
  • 매개변수: schema_name (문자열), table (문자열)
• get_hg_query_plan: Hologres 데이터베이스에서 쿼리 계획 가져오기
• get_hg_execution_plan: Hologres 데이터베이스에서 실행 계획 가져오기
• call_hg_procedure: Hologres 데이터베이스에서 프로시저 호출
• create_hg_maxcompute_foreign_table: Hologres 데이터베이스에 MaxCompute 외부 테이블 생성.

일부 에이전트가 리소스 및 리소스 템플릿을 지원하지 않기 때문에, 스키마, 테이블, 뷰, 외부 테이블의 메타데이터를 얻기 위한 다음 도구들이 제공됩니다.

• list_hg_schemas: 시스템 스키마를 제외한 현재 Hologres 데이터베이스의 모든 스키마 나열.
• list_hg_tables_in_a_schema: 특정 스키마의 모든 테이블을 유형(테이블, 뷰, 외부 테이블, 파티션 테이블)과 함께 나열.
  • 매개변수: schema_name (문자열)
• show_hg_table_ddl: Hologres 데이터베이스의 테이블, 뷰 또는 외부 테이블의 DDL 스크립트 표시.
  • 매개변수: schema_name (문자열), table (문자열)
• query_and_plotly_chart: SELECT SQL 쿼리를 실행하고 차트(막대, 선, 산점도, 파이, 히스토그램, 영역)를 생성합니다. 쿼리 결과와 base64로 인코딩된 PNG 이미지를 반환합니다.
  • 매개변수: query (문자열), chart_type (문자열, 기본값 "bar"), x_column (문자열), y_column (문자열), title (문자열)
• analyze_hg_query_by_id: hg_query_log에서 query_id로 특정 쿼리의 성능 프로필을 분석합니다. 지속 시간, 메모리, CPU 시간, 읽기/쓰기 통계 등 상세 지표를 반환합니다.
  • 매개변수: query_id (문자열)
• get_hg_slow_queries: hg_query_log에서 지속 시간 기준으로 정렬된 느린 쿼리를 가져옵니다.
  • 매개변수: min_duration_ms (정수, 기본값 1000), limit (정수, 기본값 20)
• list_hg_dynamic_tables: 모든 동적 테이블을 상태, 최신성 설정, 마지막 새로 고침 정보와 함께 나열합니다.
  • 매개변수: schema_name (문자열, 선택 사항)
• get_hg_dynamic_table_refresh_history: 특정 동적 테이블의 새로 고침 기록을 지속 시간, 상태, 지연 시간과 함께 가져옵니다.
  • 매개변수: schema_name (문자열), table_name (문자열), limit (정수, 기본값 10)
• list_hg_recyclebin: Hologres 휴지통의 모든 테이블(복원 가능한 삭제된 테이블)을 나열합니다.
• restore_hg_table_from_recyclebin: Hologres 휴지통에서 삭제된 테이블을 복원합니다.
  • 매개변수: table_name (문자열), schema_name (문자열, 기본값 "public")
• list_hg_warehouses: 모든 컴퓨팅 그룹(웨어하우스)을 CPU, 메모리, 클러스터 수, 상태와 함께 나열합니다.
• switch_hg_warehouse: 현재 세션의 컴퓨팅 리소스를 지정된 웨어하우스로 전환합니다.
  • 매개변수: warehouse_name (문자열)
• get_hg_table_storage_size: 테이블의 저장소 크기 세부 정보를 총계, 데이터, 인덱스, 메타데이터 분석과 함께 가져옵니다.
  • 매개변수: schema_name (문자열), table (문자열)
• cancel_hg_query: 프로세스 ID로 실행 중인 쿼리를 취소하거나 종료합니다.
  • 매개변수: pid (정수), terminate (부울, 기본값 false)
• list_hg_active_queries: pg_stat_activity에서 현재 활성 쿼리 및 연결을 나열합니다.
  • 매개변수: state (문자열: "active", "idle", 또는 "all", 기본값 "active")
• list_hg_query_queues: 모든 쿼리 큐와 해당 분류기(동시성 제한, 라우팅 규칙)를 나열합니다. V3.0+ 필요.
• get_hg_table_properties: distribution_key, clustering_key, segment_key, bitmap_columns, binlog 설정 등 테이블 속성을 가져옵니다.
  • 매개변수: schema_name (문자열), table (문자열)
• get_hg_table_shard_info: 데이터 편향 진단을 위해 테이블의 테이블 그룹 및 샤드 수 정보를 가져옵니다.
  • 매개변수: schema_name (문자열), table (문자열)
• list_hg_external_databases: Lakehouse 가속을 위한 모든 외부 데이터베이스 및 외부 서버를 나열합니다. V3.0+ 필요.
• get_hg_lock_diagnostics: 차단 및 대기 중인 쿼리를 표시하여 잠금 경합을 진단합니다.
• get_hg_table_info_trend: hg_table_info에서 테이블 저장소 추세를 가져와 일일 저장소 크기, 파일 수, 행 수 변화를 표시합니다.
  • 매개변수: schema_name (문자열), table (문자열), days (정수, 기본값 7)
• manage_hg_query_queue: 쿼리 큐를 생성, 삭제 또는 비웁니다. V3.0+ 및 수퍼유저 권한 필요.
  • 매개변수: action (문자열: "create", "drop", "clear"), queue_name (문자열), max_concurrency (정수, 생성 시), max_queue_size (정수, 생성 시)
• manage_hg_classifier: 쿼리 큐에 대한 분류기를 생성하거나 삭제합니다. V3.0+ 필요.
  • 매개변수: action (문자열: "create", "drop"), queue_name (문자열), classifier_name (문자열), priority (정수, 생성 시)
• set_hg_query_queue_property: 쿼리 큐 또는 분류기에 속성을 설정하거나 제거합니다. V3.0+ 필요.
  • 매개변수: target (문자열: "queue", "classifier"), queue_name (문자열), property_key (문자열), property_value (문자열), classifier_name (문자열, 분류기용), action (문자열: "set", "remove")
• manage_hg_warehouse: 컴퓨팅 그룹 관리: 일시 중단, 재개, 재시작, 이름 변경 또는 크기 조정. 수퍼유저 필요.
  • 매개변수: action (문자열: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (문자열), cu (정수, 크기 조정 시), new_name (문자열, 이름 변경 시)
• get_hg_warehouse_status: 컴퓨팅 그룹의 상세 실행 상태 및 스케일링 진행 상황을 가져옵니다.
  • 매개변수: warehouse_name (문자열)
• rebalance_hg_warehouse: 데이터 편향을 제거하기 위해 컴퓨팅 그룹의 샤드 재조정을 트리거합니다.
  • 매개변수: warehouse_name (문자열)
• list_hg_data_masking_rules: hg_anon 확장을 통해 구성된 모든 데이터 마스킹 규칙(열 수준 및 사용자 수준)을 나열합니다.
• query_hg_external_files: 외부 테이블을 생성하지 않고 EXTERNAL_FILES 함수를 사용하여 OSS에서 직접 파일을 쿼리합니다. V4.1+ 필요.
  • 매개변수: path (문자열), format (문자열: "csv", "parquet", "orc"), columns (문자열, 선택 사항), oss_endpoint (문자열, 선택 사항), role_arn (문자열, 선택 사항)
• get_hg_guc_config: GUC (Grand Unified Configuration) 매개변수의 현재 값을 가져옵니다.
  • 매개변수: guc_name (문자열)

리소스

내장 리소스

• hologres:///schemas: Hologres 데이터베이스의 모든 스키마 가져오기

리소스 템플릿

• hologres:///{schema}/tables: Hologres 데이터베이스의 스키마에 있는 모든 테이블 나열

• hologres:///{schema}/{table}/partitions: Hologres 데이터베이스의 파티션 테이블의 모든 파티션 나열

• hologres:///{schema}/{table}/ddl: Hologres 데이터베이스에서 테이블 DDL 가져오기

• hologres:///{schema}/{table}/statistic: Hologres 데이터베이스에서 수집된 테이블 통계 표시

• system:///{+system_path}: 시스템 경로에는 다음이 포함됩니다:

  • hg_instance_version - hologres 인스턴스 버전을 표시합니다.
  • guc_value/<guc_name> - guc (Grand Unified Configuration) 값을 표시합니다.
  • missing_stats_tables - 통계가 누락된 테이블을 표시합니다.
  • stat_activity - 현재 실행 중인 쿼리 정보를 표시합니다.
  • query_log/latest/<row_limits> - 지정된 행 수로 최근 쿼리 로그 기록을 가져옵니다.
  • query_log/user/<user_name>/<row_limits> - 행 제한이 있는 특정 사용자의 쿼리 로그 기록을 가져옵니다.
  • query_log/application/<application_name>/<row_limits> - 행 제한이 있는 특정 애플리케이션의 쿼리 로그 기록을 가져옵니다.
  • query_log/failed/<interval>/<row_limits> - 간격 및 지정된 행 수로 실패한 쿼리 로그 기록을 가져옵니다.

프롬프트

• analyze_table_performance: Hologres에서 테이블 성능을 분석하기 위한 프롬프트 생성
• optimize_query: Hologres에서 SQL 쿼리를 최적화하기 위한 프롬프트 생성
• explore_schema: Hologres 데이터베이스의 스키마를 탐색하기 위한 프롬프트 생성

테스트

이 프로젝트에는 포괄적인 단위 테스트와 통합 테스트가 포함되어 있습니다.

단위 테스트

단위 테스트는 데이터베이스 연결이 필요하지 않으며 모의 의존성을 사용합니다. 테스트 스위트에는 다음을 다루는 326개의 테스트 케이스가 포함되어 있습니다:

• 도구 기능 및 SQL 유효성 검사
• 리소스 및 리소스 템플릿
• 프롬프트 생성
• 유틸리티 함수 및 오류 처리
• 동시성 시나리오
• SQL 인젝션 방지

# Run all unit tests
uv run pytest tests/unit/ -v

# Run specific test file
uv run pytest tests/unit/test_tools.py -v

# Run with coverage
uv run pytest tests/unit/ --cov=src/hologres_mcp_server --cov-report=html

통합 테스트

통합 테스트에는 실제 Hologres 데이터베이스 연결이 필요합니다. 테스트 스위트에는 12개의 테스트 클래스로 구성된 61개의 테스트 케이스가 포함되어 있습니다:

테스트 클래스	테스트 수	설명
TestMCPConnection	5	MCP 서버 연결 및 기본 기능
TestMCPResources	14	리소스 읽기 기능 (스키마, 테이블, DDL, 통계, 파티션, 쿼리 로그)
TestMCPTools	10	읽기 전용 작업을 위한 도구 호출
TestMCPProcedureTools	3	저장 프로시저 도구 호출
TestMCPMaxComputeTools	1	MaxCompute 외부 테이블 생성
TestMCPDDLTools	5	DDL 작업 (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	DML 작업 (INSERT, UPDATE, DELETE)
TestErrorHandling	3	오류 처리 및 엣지 케이스
TestMCPPrompts	4	프롬프트 생성 기능
TestMCPConcurrency	3	동시 MCP 작업
TestMCPBoundaryConditions	4	엣지 케이스 (유니코드, NULL, 빈 결과)
TestMCPPerformance	3	성능 시나리오 (대용량/넓은 결과 집합)

1. 예제에서 구성 파일을 생성합니다:

cp tests/integration/.test_mcp_client_env_example tests/integration/.test_mcp_client_env

2. Hologres 자격 증명으로 구성 파일을 편집합니다:

HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com
HOLOGRES_PORT=80
HOLOGRES_USER=your_username
HOLOGRES_PASSWORD=your_password
HOLOGRES_DATABASE=your_database

3. 통합 테스트를 실행합니다:

# Run all integration tests
uv run pytest tests/integration/ -v -m integration

# Run specific test class
uv run pytest tests/integration/test_mcp_integration.py::TestMCPTools -v

# Run all tests (unit + integration)
uv run pytest tests/ -v

참고: .test_mcp_client_env 파일이 없거나 불완전한 구성이 포함된 경우 통합 테스트를 건너뜁니다.

코드 품질

이 프로젝트는 코드 린팅 및 포맷팅에 ruff를 사용합니다.

# Install dev dependencies
uv sync --dev
uv pip install ruff

# Check code style
uv run ruff check .

# Check and auto-fix
uv run ruff check . --fix

# Format code
uv run ruff format .

# Format check only (no changes)
uv run ruff format . --check

빌드 및 게시

빌드

이 프로젝트는 빌드 백엔드로 hatchling을 사용합니다. 빌드 아티팩트는 dist/ 디렉터리에 생성됩니다.

# Using uv (recommended)
uv build

# Or using python build module
pip install build
python -m build

PyPI에 게시

# Install twine
pip install twine

# Upload to PyPI
twine upload dist/*

# Or upload to Test PyPI first for verification
twine upload --repository testpypi dist/*

릴리스 워크플로

# 1. Update version in pyproject.toml
# 2. Clean old build artifacts
rm -rf dist/

# 3. Build
uv build

# 4. Publish
twine upload dist/*

# 5. Tag the release
git tag -a v1.0.3 -m "Release v1.0.3"
git push origin v1.0.3

CLI 기능 업데이트

# Use FastMCP framework to generate CLI code and Skill
uv run fastmcp generate-cli hologres-mcp-server hologres_mcp_cli/hologres_mcp_cli.py -f