StarRocks

StarRocks 공식 MCP 서버

StarRocks MCP 서버는 AI 어시스턴트와 StarRocks 데이터베이스 사이의 브리지 역할을 합니다. 복잡한 클라이언트 측 설정 없이 직접 SQL 실행, 데이터베이스 탐색, 차트를 통한 데이터 시각화, 상세 스키마/데이터 개요 검색을 지원합니다.

기능

• 직접 SQL 실행: SELECT 쿼리(read_query) 및 DDL/DML 명령(write_query) 실행.
• 데이터베이스 탐색: 데이터베이스 및 테이블 목록 조회, 테이블 스키마 검색(starrocks:// 리소스).
• 시스템 정보: proc:// 리소스 경로를 통해 내부 StarRocks 메트릭 및 상태에 접근.
• 상세 개요: 테이블(table_overview) 또는 전체 데이터베이스(db_overview)에 대한 포괄적인 요약 제공 — 열 정의, 행 수, 샘플 데이터 포함.
• 데이터 시각화: 쿼리를 실행하고 결과에서 직접 Plotly 차트 생성(query_and_plotly_chart).
• 지능형 캐싱: 테이블 및 데이터베이스 개요는 반복 요청 속도를 높이기 위해 메모리에 캐시됩니다. 필요 시 캐시를 우회할 수 있습니다.
• 유연한 구성: 환경 변수를 통해 연결 세부 정보 및 동작을 설정합니다.

사전 요구 사항

• Python 3.11 이상.
• 연결 가능한 StarRocks 클러스터(FE 서비스). 기본적으로 서버는 MySQL 프로토콜을 통해 localhost:9030에 연결합니다.
• uv — Astral의 빠른 Python 패키지 및 프로젝트 관리자(pip + virtualenv의 현대적 대체). 이 프로젝트는 uv를 사용하여 종속성을 해결하고, 가상 환경을 생성하며, 서버를 시작합니다. 이 README 전체의 uv run 명령은 첫 사용 시 격리된 환경을 자동으로 생성하고 필요한 종속성을 설치하므로 수동 pip install 단계가 필요 없습니다.

uv 설치

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew / pipx / pip
brew install uv
# pipx install uv
# pip install uv

다른 옵션은 공식 uv 설치 가이드를 참조하세요. 설치 후 PATH에 있는지 확인합니다:

uv --version

설치

일반적으로 패키지를 수동으로 설치할 필요는 없습니다 — MCP 호스트가 uv를 통해 자동으로 실행합니다(아래 구성 참조). uv는 패키지와 해당 종속성을 요청 시 가져옵니다.

테스트나 개발을 위해 직접 실행하려면:

# Run the published package in a throwaway environment
uv run --with mcp-server-starrocks mcp-server-starrocks --help

# Or, from a local checkout of this repository
git clone https://github.com/starrocks/mcp-server-starrocks.git
cd mcp-server-starrocks
uv sync                      # create the virtual environment and install dependencies
uv run mcp-server-starrocks --help

구성

MCP 서버는 일반적으로 MCP 호스트를 통해 실행됩니다. 구성은 호스트에 전달되며, StarRocks MCP 서버 프로세스를 시작하는 방법을 지정합니다.

Streamable HTTP 사용(권장):

Streamable HTTP 모드에서 서버를 시작하려면:

먼저 StarRocks 연결이 정상인지 테스트합니다(9030는 StarRocks MySQL 프로토콜 포트이며, HTTP 서버 포트가 아님):

$ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --test

서버 시작:

uv run mcp-server-starrocks --mode streamable-http --port 8000

그런 다음 MCP를 다음과 같이 구성합니다:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Docker 사용:

이미지 빌드:

docker build -t mcp-server-starrocks:local .

버전 이미지 빌드 및 푸시:

docker build -t <registry>/<namespace>/mcp-starrocks:0.4.0 .
docker push <registry>/<namespace>/mcp-starrocks:0.4.0

Streamable HTTP 모드에서 서버 시작:

docker run --rm -p 8000:8000 \
  -e STARROCKS_HOST=host.docker.internal \
  -e STARROCKS_PORT=9030 \
  -e STARROCKS_USER=root \
  -e STARROCKS_PASSWORD='' \
  mcp-server-starrocks:local

그런 다음 MCP 클라이언트를 다음과 같이 구성합니다:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

설치된 패키지와 함께 uv 사용(개별 환경 변수):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

설치된 패키지와 함께 uv 사용(연결 URL):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

로컬 디렉터리와 함께 uv 사용(개발용):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

로컬 디렉터리 및 연결 URL과 함께 uv 사용:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

명령줄 인수:

서버는 다음 명령줄 인수를 지원합니다:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: 전송 모드(기본값: stdio 또는 MCP_TRANSPORT_MODE 환경 변수)
• --host HOST: HTTP 모드용 서버 호스트(기본값: localhost)
• --port PORT: HTTP 모드용 서버 포트
• --test: 기능 확인을 위한 테스트 모드 실행

예시:

# Start in streamable HTTP mode on custom host/port
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080

# Start in stdio mode (default)
uv run mcp-server-starrocks --mode stdio

# Run test mode
uv run mcp-server-starrocks --test

• url 필드는 MCP 서버의 Streamable HTTP 엔드포인트를 가리켜야 합니다(필요에 따라 호스트/포트 조정).
• 이 구성을 사용하면 클라이언트는 특별한 SDK 없이 HTTP POST 요청을 통해 표준 JSON으로 서버와 상호 작용할 수 있습니다.
• 모든 도구 API는 위에서 설명한 대로 표준 JSON을 수락하고 반환합니다.

참고: sse(Server-Sent Events) 모드는 더 이상 사용되지 않으며 유지 관리되지 않습니다. 모든 새 통합에는 Streamable HTTP 모드를 사용하세요.

환경 변수:

연결 구성

개별 환경 변수 또는 단일 연결 URL을 사용하여 StarRocks 연결을 구성할 수 있습니다:

옵션 1: 개별 환경 변수

• STARROCKS_HOST: (선택 사항) StarRocks FE 서비스의 호스트 이름 또는 IP 주소. 기본값은 localhost.
• STARROCKS_PORT: (선택 사항) StarRocks FE 서비스의 MySQL 프로토콜 포트. 기본값은 9030.
• STARROCKS_USER: (선택 사항) StarRocks 사용자 이름. 기본값은 root.
• STARROCKS_PASSWORD: (선택 사항) StarRocks 비밀번호. 기본값은 빈 문자열.
• STARROCKS_PASSWORD_FILE: (선택 사항) 비밀번호가 포함된 UTF-8 텍스트 파일 경로. systemd 자격 증명과 같은 파일 기반 비밀 주입에 유용합니다. 끝의 줄 바꿈 하나는 무시됩니다. STARROCKS_PASSWORD 또는 STARROCKS_URL를 통해 명시적 비밀번호가 제공되지 않은 경우에만 사용됩니다.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (선택 사항, macOS 전용) Keychain에서 비밀번호를 읽을 때 사용할 일반 비밀번호 서비스 이름. 명시적 비밀번호 또는 STARROCKS_PASSWORD_FILE가 구성되지 않은 경우에만 사용됩니다.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (선택 사항, macOS 전용) Keychain에서 비밀번호를 읽을 때 사용할 일반 비밀번호 계정 이름. 기본값은 확인된 StarRocks 사용자.
• STARROCKS_DB: (선택 사항) 도구 인수 또는 리소스 URI에 지정되지 않은 경우 사용할 기본 데이터베이스. 설정된 경우 연결은 이 데이터베이스에 USE를 시도합니다. table_overview 및 db_overview와 같은 도구는 인수에서 데이터베이스 부분이 생략된 경우 이를 사용합니다. 기본값은 비어 있음(기본 데이터베이스 없음).
• STARROCKS_QUERY_TIMEOUT: (선택 사항) 쿼리 결과를 기다릴 시간(초)을 정수로 지정. 기본적으로 설정되지 않으며, 이전 동작과 일치하게 무기한 대기합니다. 중단되거나 오래 실행되는 쿼리가 도구 호출을 영원히 차단하는 대신 실패해야 하는 경우 설정하세요.

옵션 2: 연결 URL(개별 변수보다 우선)

• STARROCKS_URL: (선택 사항) 모든 연결 매개변수를 단일 변수에 포함하는 연결 URL 문자열. 형식: [<schema>://]user:password@host:port/database. 스키마 부분은 선택 사항입니다. 이 변수가 설정되면 개별 STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD 및 STARROCKS_DB 변수보다 우선합니다.

  예시:

  • root:mypass@localhost:9030/test_db
  • mysql://admin:secret@db.example.com:9030/production
  • starrocks://user:pass@192.168.1.100:9030/analytics

비밀번호 우선 순위:

• STARROCKS_URL에 포함된 비밀번호가 우선하며, user:@host:9030/db와 같은 명시적 빈 비밀번호도 포함됩니다.
• STARROCKS_URL에 비밀번호가 없는 경우 설정된 STARROCKS_PASSWORD가 사용됩니다.
• 명시적 비밀번호 소스가 모두 설정되지 않고 STARROCKS_PASSWORD_FILE가 구성된 경우 해당 파일에서 비밀번호를 읽습니다.
• 명시적 비밀번호 또는 비밀번호 파일이 구성되지 않고 STARROCKS_PASSWORD_KEYCHAIN_SERVICE가 설정된 경우 macOS Keychain에서 비밀번호를 읽습니다.

macOS Keychain 예시

비밀번호 저장:

security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'

저장된 비밀번호 확인:

security find-generic-password -a root -s mcp-server-starrocks -w

이 서버에서 사용:

export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root

systemd 암호화 자격 증명 예시(systemd 250 이상)

서버는 systemd-creds를 직접 호출하지 않습니다. 배포 시 관리자가 비밀번호를 암호화하고, 서비스 시작 시 systemd가 이를 서비스의 자격 증명 디렉터리로 해독하여 이 서버에 파일 경로만 노출합니다.

셸 기록에 비밀번호를 남기지 않고 호스트 바인딩 암호화 자격 증명 생성:

sudo -v
sudo install -d -m 0700 /etc/credstore.encrypted
sudo systemd-ask-password -n "StarRocks password:" \
  | sudo systemd-creds encrypt \
      --name=starrocks-password \
      - /etc/credstore.encrypted/starrocks-password.cred

서비스 유닛에 자격 증명을 추가합니다. %d 지정자는 서비스별 자격 증명 디렉터리로 확장됩니다:

[Service]
LoadCredentialEncrypted=starrocks-password:/etc/credstore.encrypted/starrocks-password.cred
Environment=STARROCKS_PASSWORD_FILE=%d/starrocks-password
PrivateMounts=yes

STARROCKS_PASSWORD를 설정하지 않고 STARROCKS_URL에서 비밀번호를 생략한 다음 유닛을 다시 로드하고 서비스를 다시 시작합니다. 암호화된 자격 증명은 일반적으로 로컬 호스트(가능한 경우 TPM2 장치)에 바인딩됩니다. 서비스 활성화 중에만 해독됩니다. 서비스 프로세스와 루트 권한이 있는 관리자는 런타임에 일반 텍스트 비밀번호에 계속 접근할 수 있습니다. 기밀성을 제공하지 않는 systemd-creds encrypt --with-key=null를 사용하지 마세요.

추가 구성

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (선택 사항) StarRocks FE 서비스의 Arrow Flight SQL 포트. 설정된 경우 서버는 표준 MySQL 프로토콜 대신 고성능 Arrow Flight SQL 프로토콜(ADBC 드라이버를 통해)로 연결합니다. 기본 MySQL 연결을 사용하려면 설정하지 않은 상태로 두세요. 호스트, 사용자 및 비밀번호는 위에서 설명한 동일한 연결 설정에서 가져옵니다.

• STARROCKS_OVERVIEW_LIMIT: (선택 사항) 캐시를 채우기 위해 데이터를 가져올 때 개요 도구(table_overview, db_overview)가 생성하는 전체 텍스트에 대한 대략적인 문자 제한. 매우 큰 스키마나 많은 테이블에 대한 과도한 메모리 사용을 방지하는 데 도움이 됩니다. 기본값은 20000.

• STARROCKS_MCP_OUTPUT_DIR: (선택 사항) read_query의 output_file 인수가 상대 경로일 때 사용하는 디렉터리. 기본값은 ~/.mcp-server-starrocks/output/. 디렉터리는 요청 시 생성됩니다. output_file에 전달된 절대 경로(~ 접두사 경로 포함)는 이 설정을 우회합니다. 참고: 파일은 MCP 서버가 실행되는 머신에 기록됩니다. Claude Code / Claude Desktop의 경우 서버가 로컬에서 실행되므로 파일이 노트북에 저장됩니다. 원격/HTTP 배포의 경우 파일은 클라이언트가 아닌 서버에 저장됩니다.

• STARROCKS_CHART_OUTPUT_DIR: (선택 사항) query_and_plotly_chart가 대화형 HTML 차트를 작성하는 디렉터리(format="html"일 때). 기본값은 시스템 임시 디렉터리. 디렉터리는 요청 시 생성됩니다. 참고: 다른 출력 파일과 마찬가지로 차트는 MCP 서버가 실행되는 머신에 기록됩니다.

• STARROCKS_CHART_INCLUDE_PLOTLYJS: (선택 사항) plotly.js가 HTML 차트에 번들되는 방식을 제어합니다. cdn(기본값)는 파일을 작게 유지하지만 볼 때 네트워크 접근이 필요합니다. inline/true는 오프라인 사용을 위해 전체 라이브러리를 포함합니다. directory 및 false도 허용됩니다(Plotly의 write_html에 전달됨).

• STARROCKS_CHART_DEFAULT_FORMAT: (선택 사항) query_and_plotly_chart의 format 인수가 생략된 경우 기본 출력 형식. json, png, jpeg(기본값) 또는 html 중 하나. html로 설정하면 매 호출마다 format를 전달하지 않고 항상 대화형 차트 파일을 STARROCKS_CHART_OUTPUT_DIR에 작성합니다(인라인 PNG 미리 보기 포함). 잘못된 값은 경고와 함께 jpeg로 대체됩니다.

• STARROCKS_MYSQL_AUTH_PLUGIN: (선택 사항) StarRocks FE 서비스에 연결할 때 사용할 인증 플러그인을 지정합니다. 예를 들어 StarRocks 배포에 일반 텍스트 비밀번호 인증이 필요한 경우(특정 LDAP 또는 외부 인증 설정 사용 시) mysql_clear_password로 설정합니다. 환경에서 특별히 요구하는 경우에만 설정하세요. 그렇지 않으면 기본 auth_plugin이 사용됩니다.

TLS / SSL 구성

이 변수들은 연결의 TLS를 제어합니다. 이 중 아무것도 설정되지 않은 경우 기본 mysql.connector는 기본 동작(ssl-mode=PREFERRED)을 유지합니다: 서버가 TLS를 지원하면 연결이 암호화되지만 서버 인증서는 검증되지 않습니다. 실제 보안을 위해 CA 인증서를 제공하고 검증을 활성화하세요.

• STARROCKS_SSL_DISABLED: (선택 사항) TLS를 강제로 비활성화하려면 true로 설정합니다. 다른 모든 SSL 설정을 재정의합니다. 기본값은 false입니다.
• STARROCKS_SSL_CA: (선택 사항) StarRocks 서버 인증서를 검증하는 데 사용되는 CA 인증서(PEM)의 경로입니다.
• STARROCKS_SSL_CERT: (선택 사항) 상호 TLS(mTLS)용 클라이언트 인증서(PEM)의 경로입니다.
• STARROCKS_SSL_KEY: (선택 사항) 상호 TLS(mTLS)용 클라이언트 개인 키(PEM)의 경로입니다.
• STARROCKS_SSL_VERIFY_CERT: (선택 사항) CA에 대해 서버 인증서를 검증하려면 true로 설정합니다. 기본값은 false입니다.
• STARROCKS_SSL_VERIFY_IDENTITY: (선택 사항) 서버 호스트 이름이 인증서와 일치하는지도 검증하려면 true로 설정합니다. 기본값은 false입니다.
• STARROCKS_TLS_VERSIONS: (선택 사항) 허용된 TLS 버전의 쉼표로 구분된 목록입니다(예: TLSv1.2,TLSv1.3).

예시(CA 인증서에 대해 서버 검증):

"env": {
  "STARROCKS_HOST": "your-fe-host",
  "STARROCKS_PORT": "9030",
  "STARROCKS_USER": "root",
  "STARROCKS_PASSWORD": "your-password",
  "STARROCKS_SSL_CA": "/path/to/ca.pem",
  "STARROCKS_SSL_VERIFY_CERT": "true",
  "STARROCKS_SSL_VERIFY_IDENTITY": "true"
}

고성능 Arrow Flight SQL 연결(STARROCKS_FE_ARROW_FLIGHT_SQL_PORT를 통해 활성화)의 경우 TLS는 별도로 제어됩니다:

• STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS: (선택 사항) 일반 텍스트 grpc:// 대신 grpc+tls://를 사용하려면 true로 설정합니다. 활성화되면 STARROCKS_SSL_CA가 TLS 루트 인증서로 사용되고 STARROCKS_SSL_VERIFY_CERT=false(기본값)는 서버 인증서 검증을 건너뜁니다.

보안 참고: mcp.json에 일반 텍스트 비밀번호를 직접 저장하지 마십시오. 시크릿 관리자 또는 환경에서 STARROCKS_PASSWORD(및 인증서 경로)을 주입하는 것을 선호하고, 자격 증명을 버전 관리에 커밋하지 마십시오.

• MCP_TRANSPORT_MODE: (선택 사항) MCP 서버가 서비스를 노출하는 방식을 지정하는 통신 모드입니다. 사용 가능한 옵션:
  • stdio(기본값): 표준 입력/출력을 통해 통신하며, MCP 호스트 호스팅에 적합합니다.
  • streamable-http(Streamable HTTP): Streamable HTTP 서버로 시작하여 RESTful API 호출을 지원합니다.
  • sse: (더 이상 사용되지 않음, 권장하지 않음) Server-Sent Events(SSE) 스트리밍 모드로 시작하며, 스트리밍 응답이 필요한 시나리오에 적합합니다. 참고: SSE 모드는 더 이상 유지 관리되지 않으므로 Streamable HTTP 모드를 통일적으로 사용하는 것이 좋습니다.

구성 요소

도구

• read_query

  • 설명: SELECT 쿼리 또는 ResultSet을 반환하는 기타 명령(예: SHOW, DESCRIBE)을 실행합니다. 선택적으로 전체 결과를 인라인으로 반환하는 대신 로컬 파일에 쓸 수 있습니다. 모델 컨텍스트에 비해 너무 큰 결과에 유용합니다.
  • 입력:

    {
      "query": "SQL query string",
      "db": "database name (optional, uses default database if not specified)",
      "output_file": "optional path; if set, writes the full result to disk and returns only a summary + small preview. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/); absolute paths and ~ are used as-is",
      "output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
    }
    

  • 출력: output_file 없이 헤더 행과 행 수 요약이 포함된 CSV 형식의 쿼리 결과를 포함하는 텍스트 콘텐츠입니다. output_file 사용 시 확인된 절대 경로, 바이트 수, 행 수 및 작은 미리 보기를 포함한 짧은 요약입니다. 실패 시 오류 메시지를 반환합니다.

• write_query

  • 설명: DDL(CREATE, ALTER, DROP), DML(INSERT, UPDATE, DELETE) 또는 ResultSet을 반환하지 않는 기타 StarRocks 명령을 실행합니다.
  • 입력:

    {
      "query": "SQL command string",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • 출력: 성공을 확인하는 텍스트 콘텐츠(예: "Query OK, X rows affected") 또는 오류를 보고합니다. 변경 사항은 성공 시 자동으로 커밋됩니다.

• analyze_query

  • 설명: 쿼리를 분석하고 쿼리 프로필 또는 explain analyze를 사용하여 분석 결과를 얻습니다.
  • 입력:

    {
      "uuid": "Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12",
      "sql": "Query SQL to analyze",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • 출력: 쿼리 분석 결과를 포함하는 텍스트 콘텐츠입니다. uuid가 제공되면 ANALYZE PROFILE FROM를 사용하고, sql이 제공되면 EXPLAIN ANALYZE를 사용합니다.

• top_hot_tables

  • 설명: 감사 로그 방문 횟수로 상위 핫 테이블을 가져옵니다. information_schema.tables와 starrocks_audit_db__.starrocks_audit_tbl__를 조인하고, root 및 SHOW 문을 제외하고, 감사 SQL 텍스트를 테이블 이름과 일치시키고, visit_count 내림차순으로 정렬합니다.
  • 입력:

    {
      "db": "optional database/schema filter",
      "table": "optional table name substring filter",
      "min_start_time_ms": 1704067200000,
      "max_start_time_ms": 1704153600000,
      "top_n": 20
    }
    

  • 출력: db, table 및 visit_count가 포함된 순위 행이 포함된 텍스트 요약 및 구조화된 콘텐츠입니다.

• top_bad_tables

  • 설명: Star Management Studio의 top-bad-tables 로직에 따라 테이블 건강 점수로 상위 불량 테이블을 가져옵니다. information_schema.be_tablets 및 information_schema.partitions_meta를 기반으로 테이블 건강 계산을 재사용하고, 시스템 스키마를 필터링하고, table_health_score 오름차순으로 정렬하고, 가장 낮은 점수의 테이블을 반환합니다.
  • 입력:

    {
      "db": "optional database/schema filter",
      "table": "optional table name substring filter",
      "top_n": 20
    }
    

  • 출력: db, table, tablet_num, replica_score, tablet_score 및 table_health_score과 같은 테이블 건강 필드가 포함된 순위 행이 포함된 텍스트 요약 및 구조화된 콘텐츠입니다.

• query_and_plotly_chart

  • 설명: SQL 쿼리를 실행하고, 결과를 Pandas DataFrame에 로드하고, 제공된 Python 표현식을 사용하여 Plotly 차트를 생성합니다. 지원 UI에서 시각화하도록 설계되었습니다.
  • 입력:

    {
      "query": "SQL query to fetch data",
      "plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • 출력: 다음을 포함하는 목록:
    1. TextContent: DataFrame의 텍스트 표현 및 차트가 UI 표시용임을 알리는 메모.
    2. ImageContent: base64 PNG 이미지(image/png)로 인코딩된 생성된 Plotly 차트. 실패하거나 쿼리 결과가 없으면 텍스트 오류 메시지를 반환합니다.

• table_overview

  • 설명: 특정 테이블의 개요를 가져옵니다: 열(DESCRIBE에서), 총 행 수 및 샘플 행(LIMIT 3). refresh가 true가 아니면 인메모리 캐시를 사용합니다.
  • 입력:

    {
      "table": "Table name, optionally prefixed with database name (e.g., 'db_name.table_name' or 'table_name'). If database is omitted, uses STARROCKS_DB environment variable if set.",
      "refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
    }
    

  • 출력: 형식화된 개요(열, 행 수, 샘플 데이터)를 포함하는 텍스트 콘텐츠 또는 오류 메시지입니다. 캐시된 결과에는 해당하는 경우 이전 오류가 포함됩니다.

• db_overview

  • 설명: 지정된 데이터베이스 내의 모든 테이블에 대한 개요(열, 행 수, 샘플 행)를 가져옵니다. refresh가 true가 아니면 각 테이블에 대한 테이블 수준 캐시를 사용합니다.
  • 입력:

    {
      "db": "database_name", // Optional if default database is set.
      "refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
    }
    

  • 출력: 데이터베이스에서 찾은 모든 테이블에 대한 개요를 헤더로 구분하여 연결한 텍스트 콘텐츠입니다. 데이터베이스에 액세스할 수 없거나 테이블이 없으면 오류 메시지를 반환합니다.

리소스

직접 리소스

• starrocks:///databases
  • 설명: 구성된 사용자가 액세스할 수 있는 모든 데이터베이스를 나열합니다.
  • 동등 쿼리: SHOW DATABASES
  • MIME 유형: text/plain

리소스 템플릿

• starrocks:///{db}/{table}/schema

  • 설명: 특정 테이블의 스키마 정의를 가져옵니다.
  • 동등 쿼리: SHOW CREATE TABLE {db}.{table}
  • MIME 유형: text/plain

• starrocks:///{db}/tables

  • 설명: 특정 데이터베이스 내의 모든 테이블을 나열합니다.
  • 동등 쿼리: SHOW TABLES FROM {db}
  • MIME 유형: text/plain

• proc:///{+path}

  • 설명: Linux /proc와 유사하게 StarRocks 내부 시스템 정보에 액세스합니다. path 매개변수는 원하는 정보 노드를 지정합니다.
  • 동등 쿼리: SHOW PROC '/{path}'
  • MIME 유형: text/plain
  • 일반 경로:
    • /frontends - FE 노드에 대한 정보.
    • /backends - BE 노드에 대한 정보(비클라우드 네이티브 배포용).
    • /compute_nodes - CN 노드에 대한 정보(클라우드 네이티브 배포용).
    • /dbs - 데이터베이스에 대한 정보.
    • /dbs/<DB_ID> - ID로 특정 데이터베이스에 대한 정보.
    • /dbs/<DB_ID>/<TABLE_ID> - ID로 특정 테이블에 대한 정보.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - 테이블의 파티션 정보.
    • /transactions - 데이터베이스별로 그룹화된 트랜잭션 정보.
    • /transactions/<DB_ID> - 특정 데이터베이스 ID에 대한 트랜잭션 정보.
    • /transactions/<DB_ID>/running - 데이터베이스 ID에 대한 실행 중인 트랜잭션.
    • /transactions/<DB_ID>/finished - 데이터베이스 ID에 대한 완료된 트랜잭션.
    • /jobs - 비동기 작업(Schema Change, Rollup 등)에 대한 정보.
    • /statistic - 각 데이터베이스에 대한 통계.
    • /tasks - 에이전트 작업에 대한 정보.
    • /cluster_balance - 로드 밸런스 상태 정보.
    • /routine_loads - Routine Load 작업에 대한 정보.
    • /colocation_group - Colocation Join 그룹에 대한 정보.
    • /catalog - 구성된 카탈로그(예: Hive, Iceberg)에 대한 정보.

프롬프트

이 서버에서 정의된 프롬프트가 없습니다.

캐싱 동작

• table_overview 및 db_overview 도구는 생성된 개요 텍스트를 저장하기 위해 인메모리 캐시를 활용합니다.
• 캐시 키는 (database_name, table_name)의 튜플입니다.
• table_overview가 호출되면 먼저 캐시를 확인합니다. 결과가 있고 refresh 매개변수가 false(기본값)이면 캐시된 결과가 즉시 반환됩니다. 그렇지 않으면 StarRocks에서 데이터를 가져와 캐시에 저장한 다음 반환합니다.
• db_overview가 호출되면 데이터베이스의 모든 테이블을 나열한 다음 table_overview와 동일한 캐싱 로직을 사용하여 _각 테이블_에 대한 개요를 검색하려고 시도합니다(먼저 캐시 확인, 필요하고 refresh가 false이거나 캐시 미스인 경우 가져오기). refresh가 db_overview에 대해 true이면 해당 데이터베이스의 모든 테이블에 대한 새로 고침을 강제합니다.
• STARROCKS_OVERVIEW_LIMIT 환경 변수는 캐시를 채울 때 테이블당 생성되는 개요 문자열의 최대 길이에 대한 _소프트 목표_를 제공하여 메모리 사용량을 관리하는 데 도움이 됩니다.
• 캐시된 결과(원래 가져오기 중 발생한 오류 메시지 포함)는 저장되며 후속 캐시 적중 시 반환됩니다.

디버그

mcp 서버를 시작한 후 inspector를 사용하여 디버그할 수 있습니다:

npx @modelcontextprotocol/inspector

데모