StarRocks

공식

StarRocks와 상호작용

GitHub
183

Star Rocks MCP(으)로 무엇을 할 수 있나요?

  • 읽기 전용 SQL 쿼리 실행 — read_query를 통해 SELECT, SHOW 또는 DESCRIBE 문을 실행하고, 대용량 결과는 선택적으로 파일로 저장합니다.
  • DDL/DML 명령 실행 — write_query로 CREATE, INSERT, UPDATE 또는 DELETE 작업을 수행하고, 영향을 받은 행 수를 확인합니다.
  • 데이터베이스 스키마 탐색 — starrocks:// 리소스를 통해 데이터베이스, 테이블을 나열하고 SHOW CREATE TABLE 정의를 검색합니다.
  • 테이블 및 데이터베이스 개요 확인 — table_overview 또는 db_overview를 사용하여 열 정의, 행 수 및 샘플 행을 가져오며, 인메모리 캐싱을 지원합니다.
  • 쿼리 결과를 차트로 시각화 — SQL 쿼리와 Plotly 표현식을 query_and_plotly_chart에 제공하여 차트 이미지를 받습니다.
  • 클러스터 상태 및 핫스팟 검사 — top_hot_tables로 자주 액세스되는 테이블을, top_bad_tables로 상태가 낮은 테이블을 식별하고, proc:// 리소스를 통해 내부 시스템 메트릭에 접근합니다.

문서

MseeP.ai Security Assessment Badge

StarRocks 공식 MCP 서버

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

StarRocks Server MCP server

기능

  • 직접 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은 HTTP 서버 포트가 아닌 StarRocks MySQL 프로토콜 포트입니다):

$ 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"
    }
  }
}

설치된 패키지와 함께 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 엔드포인트를 가리켜야 합니다 (필요에 따라 호스트/포트 조정).
  • 이 구성을 사용하면 클라이언트는 HTTP POST 요청을 통해 표준 JSON으로 서버와 상호 작용할 수 있습니다. 특별한 SDK가 필요하지 않습니다.
  • 모든 도구 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_KEYCHAIN_SERVICE: (선택 사항, macOS 전용) 키체인에서 비밀번호를 읽을 때 사용할 일반 비밀번호 서비스 이름. STARROCKS_PASSWORD 또는 STARROCKS_URL을 통해 명시적인 비밀번호가 제공되지 않은 경우에만 사용됩니다.
  • STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (선택 사항, macOS 전용) 키체인에서 비밀번호를 읽을 때 사용할 일반 비밀번호 계정 이름. 기본값은 확인된 StarRocks 사용자입니다.
  • STARROCKS_DB: (선택 사항) 도구 인수 또는 리소스 URI에 지정되지 않은 경우 사용할 기본 데이터베이스. 설정하면 연결 시 이 데이터베이스로 USE을 시도합니다. table_overview 및 db_overview과 같은 도구는 인수에서 데이터베이스 부분이 생략된 경우 이를 사용합니다. 기본값은 비어 있습니다(기본 데이터베이스 없음).

옵션 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_KEYCHAIN_SERVICE이 구성된 경우, macOS 키체인에서 비밀번호를 읽습니다.

macOS 키체인 예시

비밀번호 저장:

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

추가 구성

  • 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: (선택 사항) format 인수가 생략된 경우 query_and_plotly_chart의 기본 출력 형식. 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

  • 설명: ResultSet을 반환하는 SELECT 쿼리 또는 기타 명령(예: 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

    • 설명: ResultSet을 반환하지 않는 DDL(CREATE, ALTER, DROP), DML(INSERT, UPDATE, DELETE) 또는 기타 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 - 비동기 작업(스키마 변경, 롤업 등)에 대한 정보.
      • /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이거나 캐시 미스인 경우 가져옴). db_overview에 대해 refresh이 true이면 해당 데이터베이스의 모든 테이블에 대해 새로 고침을 강제합니다.
  • STARROCKS_OVERVIEW_LIMIT 환경 변수는 캐시를 채울 때 테이블당 생성되는 개요 문자열의 최대 길이에 대한 _소프트 타겟_을 제공하여 메모리 사용량 관리에 도움을 줍니다.
  • 원래 가져오기 중에 발생한 오류 메시지를 포함한 캐시된 결과는 저장되며 후속 캐시 적중 시 반환됩니다.

디버그

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

npx @modelcontextprotocol/inspector

데모

MCP Demo Image