StarRocks

Máy chủ MCP chính thức của StarRocks

Máy chủ MCP StarRocks hoạt động như một cầu nối giữa các trợ lý AI và cơ sở dữ liệu StarRocks. Nó cho phép thực thi SQL trực tiếp, khám phá cơ sở dữ liệu, trực quan hóa dữ liệu qua biểu đồ và truy xuất thông tin tổng quan chi tiết về lược đồ/dữ liệu mà không cần thiết lập phức tạp ở phía máy khách.

Tính năng

• Thực thi SQL trực tiếp: Chạy các truy vấn SELECT (read_query) và các lệnh DDL/DML (write_query).
• Khám phá cơ sở dữ liệu: Liệt kê các cơ sở dữ liệu và bảng, truy xuất lược đồ bảng (tài nguyên starrocks://).
• Thông tin hệ thống: Truy cập các số liệu và trạng thái nội bộ của StarRocks qua đường dẫn tài nguyên proc://.
• Tổng quan chi tiết: Nhận tóm tắt toàn diện về các bảng (table_overview) hoặc toàn bộ cơ sở dữ liệu (db_overview), bao gồm định nghĩa cột, số hàng và dữ liệu mẫu.
• Trực quan hóa dữ liệu: Thực thi một truy vấn và tạo biểu đồ Plotly trực tiếp từ kết quả (query_and_plotly_chart).
• Bộ nhớ đệm thông minh: Tổng quan về bảng và cơ sở dữ liệu được lưu trong bộ nhớ để tăng tốc các yêu cầu lặp lại. Có thể bỏ qua bộ nhớ đệm khi cần.
• Cấu hình linh hoạt: Đặt chi tiết kết nối và hành vi qua các biến môi trường.

Điều kiện tiên quyết

• Python 3.11 trở lên.
• Một cụm StarRocks có thể truy cập được (dịch vụ FE). Theo mặc định, máy chủ kết nối đến localhost:9030 qua giao thức MySQL.
• uv — một trình quản lý gói và dự án Python nhanh (thay thế hiện đại cho pip + virtualenv) từ Astral. Dự án này sử dụng uv để giải quyết các phụ thuộc, tạo môi trường ảo và khởi chạy máy chủ. Các lệnh uv run trong toàn bộ README này tự động tạo một môi trường cô lập và cài đặt các phụ thuộc cần thiết khi sử dụng lần đầu, vì vậy không cần bước pip install thủ công.

Cài đặt 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

Xem hướng dẫn cài đặt uv chính thức để biết các tùy chọn khác. Sau khi cài đặt, hãy xác minh nó nằm trong PATH của bạn:

uv --version

Cài đặt

Bạn thường không cần cài đặt gói theo cách thủ công — máy chủ MCP khởi chạy nó cho bạn qua uv (xem Cấu hình bên dưới). uv tìm nạp gói và các phụ thuộc của nó theo yêu cầu.

Để chạy trực tiếp cho mục đích kiểm thử hoặc phát triển:

# 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

Cấu hình

Máy chủ MCP thường được chạy qua một máy chủ MCP. Cấu hình được truyền cho máy chủ, chỉ định cách khởi chạy tiến trình máy chủ MCP StarRocks.

Sử dụng Streamable HTTP (khuyến nghị):

Để khởi động máy chủ ở chế độ Streamable HTTP:

Trước tiên, kiểm tra kết nối đến StarRocks hoạt động tốt (9030 là cổng giao thức MySQL của StarRocks, không phải cổng máy chủ HTTP):

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

Khởi động máy chủ:

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

Sau đó cấu hình MCP như sau:

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

Sử dụng Docker:

Xây dựng hình ảnh:

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

Xây dựng và đẩy hình ảnh có phiên bản:

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

Khởi động máy chủ ở chế độ 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

Sau đó cấu hình máy khách MCP với:

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

Sử dụng uv với gói đã cài đặt (các biến môi trường riêng lẻ):

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

Sử dụng uv với gói đã cài đặt (URL kết nối):

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

Sử dụng uv với thư mục cục bộ (dành cho phát triển):

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

Sử dụng uv với thư mục cục bộ và URL kết nối:

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

Đối số dòng lệnh:

Máy chủ hỗ trợ các đối số dòng lệnh sau:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: Chế độ truyền tải (mặc định: stdio hoặc biến môi trường MCP_TRANSPORT_MODE)
• --host HOST: Máy chủ cho các chế độ HTTP (mặc định: localhost)
• --port PORT: Cổng máy chủ cho các chế độ HTTP
• --test: Chạy ở chế độ kiểm thử để xác minh chức năng

Ví dụ:

# 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

• Trường url phải trỏ đến điểm cuối Streamable HTTP của máy chủ MCP của bạn (điều chỉnh máy chủ/cổng khi cần).
• Với cấu hình này, máy khách có thể tương tác với máy chủ bằng JSON tiêu chuẩn qua các yêu cầu HTTP POST. Không cần SDK đặc biệt.
• Tất cả các API công cụ chấp nhận và trả về JSON tiêu chuẩn như mô tả ở trên.

Lưu ý: Chế độ sse (Server-Sent Events) đã không còn được dùng và không còn được bảo trì. Vui lòng sử dụng chế độ Streamable HTTP cho tất cả các tích hợp mới.

Biến môi trường:

Cấu hình kết nối

Bạn có thể cấu hình kết nối StarRocks bằng các biến môi trường riêng lẻ hoặc một URL kết nối duy nhất:

Tùy chọn 1: Các biến môi trường riêng lẻ

• STARROCKS_HOST: (Tùy chọn) Tên máy chủ hoặc địa chỉ IP của dịch vụ FE StarRocks. Mặc định là localhost.
• STARROCKS_PORT: (Tùy chọn) Cổng giao thức MySQL của dịch vụ FE StarRocks. Mặc định là 9030.
• STARROCKS_USER: (Tùy chọn) Tên người dùng StarRocks. Mặc định là root.
• STARROCKS_PASSWORD: (Tùy chọn) Mật khẩu StarRocks. Mặc định là chuỗi rỗng.
• STARROCKS_PASSWORD_FILE: (Tùy chọn) Đường dẫn đến tệp văn bản UTF-8 chứa mật khẩu. Điều này hữu ích với việc tiêm bí mật dựa trên tệp như thông tin xác thực systemd. Một ký tự xuống dòng ở cuối sẽ bị bỏ qua. Chỉ được sử dụng khi không có mật khẩu rõ ràng nào được cung cấp qua STARROCKS_PASSWORD hoặc STARROCKS_URL.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Tùy chọn, chỉ dành cho macOS) Tên dịch vụ mật khẩu chung để sử dụng khi đọc mật khẩu từ Keychain. Chỉ được sử dụng khi không có mật khẩu rõ ràng hoặc STARROCKS_PASSWORD_FILE được cấu hình.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Tùy chọn, chỉ dành cho macOS) Tên tài khoản mật khẩu chung để sử dụng khi đọc mật khẩu từ Keychain. Mặc định là người dùng StarRocks đã được phân giải.
• STARROCKS_DB: (Tùy chọn) Cơ sở dữ liệu mặc định để sử dụng nếu không được chỉ định trong đối số công cụ hoặc URI tài nguyên. Nếu được đặt, kết nối sẽ cố gắng USE cơ sở dữ liệu này. Các công cụ như table_overview và db_overview sẽ sử dụng điều này nếu phần cơ sở dữ liệu bị bỏ qua trong đối số của chúng. Mặc định là trống (không có cơ sở dữ liệu mặc định).
• STARROCKS_QUERY_TIMEOUT: (Tùy chọn) Số giây để chờ kết quả truy vấn trước khi từ bỏ, dưới dạng số nguyên. Không được đặt theo mặc định, nghĩa là chờ vô thời hạn, phù hợp với hành vi trước đó. Đặt giá trị này nếu một truy vấn bị kẹt hoặc chạy lâu nên thất bại thay vì chặn một lệnh gọi công cụ mãi mãi.

Tùy chọn 2: URL kết nối (ưu tiên hơn các biến riêng lẻ)

• STARROCKS_URL: (Tùy chọn) Một chuỗi URL kết nối chứa tất cả các tham số kết nối trong một biến duy nhất. Định dạng: [<schema>://]user:password@host:port/database. Phần lược đồ là tùy chọn. Khi biến này được đặt, nó được ưu tiên hơn các biến STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD và STARROCKS_DB riêng lẻ.

  Ví dụ:

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

Thứ tự ưu tiên mật khẩu:

• Mật khẩu nhúng trong STARROCKS_URL được ưu tiên, bao gồm cả mật khẩu trống rõ ràng như user:@host:9030/db.
• Nếu STARROCKS_URL bỏ qua mật khẩu, STARROCKS_PASSWORD sẽ được sử dụng khi được đặt.
• Nếu không có nguồn mật khẩu rõ ràng nào được đặt và STARROCKS_PASSWORD_FILE được cấu hình, mật khẩu sẽ được đọc từ tệp đó.
• Nếu không có mật khẩu rõ ràng hoặc tệp mật khẩu được cấu hình và STARROCKS_PASSWORD_KEYCHAIN_SERVICE được đặt, mật khẩu sẽ được đọc từ macOS Keychain.

Ví dụ về macOS Keychain

Lưu trữ mật khẩu:

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

Xác minh mật khẩu đã lưu trữ:

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

Sử dụng nó với máy chủ này:

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

Thông tin xác thực được mã hóa systemd ví dụ (systemd 250 trở lên)

Máy chủ không tự gọi systemd-creds. Tại thời điểm triển khai, quản trị viên mã hóa mật khẩu; khi khởi động dịch vụ, systemd giải mã nó vào thư mục thông tin xác thực của dịch vụ và chỉ hiển thị đường dẫn tệp cho máy chủ này.

Tạo thông tin xác thực được mã hóa gắn với máy chủ mà không đưa mật khẩu vào lịch sử shell:

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

Thêm thông tin xác thực vào đơn vị dịch vụ. Bộ xác định %d mở rộng đến thư mục thông tin xác thực cụ thể của dịch vụ:

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

Giữ STARROCKS_PASSWORD không được đặt và bỏ qua mật khẩu từ STARROCKS_URL, sau đó tải lại đơn vị và khởi động lại dịch vụ. Thông tin xác thực được mã hóa thường được gắn với máy chủ cục bộ (và với thiết bị TPM2 của nó khi có sẵn); nó chỉ được giải mã trong khi dịch vụ đang được kích hoạt. Tiến trình dịch vụ và quản trị viên có quyền root vẫn có thể truy cập mật khẩu văn bản thuần túy tại thời điểm chạy. Không sử dụng systemd-creds encrypt --with-key=null, vì nó không cung cấp tính bảo mật.

Cấu hình bổ sung

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Tùy chọn) Cổng Arrow Flight SQL của dịch vụ FE StarRocks. Khi được đặt, máy chủ kết nối bằng giao thức Arrow Flight SQL hiệu suất cao (qua trình điều khiển ADBC) thay vì giao thức MySQL tiêu chuẩn. Để trống để sử dụng kết nối MySQL mặc định. Máy chủ, người dùng và mật khẩu được lấy từ cùng cài đặt kết nối được mô tả ở trên.

• STARROCKS_OVERVIEW_LIMIT: (Tùy chọn) Giới hạn ký tự xấp xỉ cho tổng văn bản được tạo bởi các công cụ tổng quan (table_overview, db_overview) khi tìm nạp dữ liệu để điền vào bộ nhớ đệm. Điều này giúp ngăn chặn việc sử dụng bộ nhớ quá mức cho các lược đồ rất lớn hoặc nhiều bảng. Mặc định là 20000.

• STARROCKS_MCP_OUTPUT_DIR: (Tùy chọn) Thư mục được sử dụng bởi read_query khi đối số output_file của nó là một đường dẫn tương đối. Mặc định là ~/.mcp-server-starrocks/output/. Thư mục được tạo theo yêu cầu. Các đường dẫn tuyệt đối được truyền cho output_file (bao gồm cả các đường dẫn có tiền tố ~) bỏ qua cài đặt này. Lưu ý: các tệp được ghi trên máy nơi máy chủ MCP chạy. Đối với Claude Code / Claude Desktop, máy chủ chạy cục bộ, vì vậy các tệp nằm trên máy tính xách tay của bạn. Đối với các triển khai từ xa/http, tệp nằm trên máy chủ, không phải máy khách.

• STARROCKS_CHART_OUTPUT_DIR: (Tùy chọn) Thư mục nơi query_and_plotly_chart ghi các biểu đồ HTML tương tác (khi format="html"). Mặc định là thư mục tạm thời của hệ thống. Thư mục được tạo theo yêu cầu. Lưu ý: giống như các tệp đầu ra khác, biểu đồ được ghi trên máy nơi máy chủ MCP chạy.

• STARROCKS_CHART_INCLUDE_PLOTLYJS: (Tùy chọn) Kiểm soát cách plotly.js được đóng gói vào các biểu đồ HTML. cdn (mặc định) giữ cho các tệp nhỏ nhưng cần truy cập mạng khi xem; inline/true nhúng toàn bộ thư viện để sử dụng ngoại tuyến; directory và false cũng được chấp nhận (chuyển qua cho write_html của Plotly).

• STARROCKS_CHART_DEFAULT_FORMAT: (Tùy chọn) Định dạng đầu ra mặc định cho query_and_plotly_chart khi đối số format bị bỏ qua. Một trong các giá trị json, png, jpeg (mặc định) hoặc html. Đặt thành html để luôn ghi tệp biểu đồ tương tác vào STARROCKS_CHART_OUTPUT_DIR (với bản xem trước PNG nội tuyến) mà không cần truyền format trong mỗi lần gọi. Các giá trị không hợp lệ sẽ quay lại jpeg với cảnh báo.

• STARROCKS_MYSQL_AUTH_PLUGIN: (Tùy chọn) Chỉ định plugin xác thực để sử dụng khi kết nối với dịch vụ FE StarRocks. Ví dụ: đặt thành mysql_clear_password nếu triển khai StarRocks của bạn yêu cầu xác thực mật khẩu văn bản thuần túy (chẳng hạn như khi sử dụng một số thiết lập LDAP hoặc xác thực bên ngoài). Chỉ đặt điều này nếu môi trường của bạn cụ thể yêu cầu; nếu không, auth_plugin mặc định sẽ được sử dụng.

Cấu hình TLS / SSL

Các biến này kiểm soát TLS cho kết nối. Khi không có biến nào trong số chúng được đặt, mysql.connector bên dưới giữ hành vi mặc định của nó (ssl-mode=PREFERRED): kết nối được mã hóa nếu máy chủ hỗ trợ TLS, nhưng chứng chỉ máy chủ không được xác minh. Để bảo mật thực sự, hãy cung cấp chứng chỉ CA và bật xác minh.

• STARROCKS_SSL_DISABLED: (Tùy chọn) Đặt thành true để buộc tắt TLS. Ghi đè mọi cài đặt SSL khác. Mặc định là false.
• STARROCKS_SSL_CA: (Tùy chọn) Đường dẫn đến chứng chỉ CA (PEM) dùng để xác minh chứng chỉ máy chủ StarRocks.
• STARROCKS_SSL_CERT: (Tùy chọn) Đường dẫn đến chứng chỉ máy khách (PEM) cho TLS tương hỗ (mTLS).
• STARROCKS_SSL_KEY: (Tùy chọn) Đường dẫn đến khóa riêng máy khách (PEM) cho TLS tương hỗ (mTLS).
• STARROCKS_SSL_VERIFY_CERT: (Tùy chọn) Đặt thành true để xác minh chứng chỉ máy chủ với CA. Mặc định là false.
• STARROCKS_SSL_VERIFY_IDENTITY: (Tùy chọn) Đặt thành true để cũng xác minh rằng tên máy chủ khớp với chứng chỉ. Mặc định là false.
• STARROCKS_TLS_VERSIONS: (Tùy chọn) Danh sách các phiên bản TLS được phép, phân tách bằng dấu phẩy, ví dụ: TLSv1.2,TLSv1.3.

Ví dụ (xác minh máy chủ bằng chứng chỉ 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"
}

Đối với kết nối Arrow Flight SQL hiệu suất cao (được bật qua STARROCKS_FE_ARROW_FLIGHT_SQL_PORT), TLS được kiểm soát riêng:

• STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS: (Tùy chọn) Đặt thành true để sử dụng grpc+tls:// thay vì grpc:// dạng văn bản thuần. Khi được bật, STARROCKS_SSL_CA được dùng làm chứng chỉ gốc TLS và STARROCKS_SSL_VERIFY_CERT=false (mặc định) bỏ qua việc xác minh chứng chỉ máy chủ.

Lưu ý bảo mật: tránh lưu mật khẩu dạng văn bản thuần trực tiếp trong mcp.json. Ưu tiên tiêm STARROCKS_PASSWORD (và đường dẫn chứng chỉ) từ trình quản lý bí mật hoặc biến môi trường, và không bao giờ cam kết thông tin xác thực vào hệ thống kiểm soát phiên bản.

• MCP_TRANSPORT_MODE: (Tùy chọn) Chế độ giao tiếp xác định cách MCP Server hiển thị các dịch vụ của mình. Các tùy chọn có sẵn:
  • stdio (mặc định): Giao tiếp qua đầu vào/đầu ra chuẩn, phù hợp cho việc lưu trữ MCP Host.
  • streamable-http (Streamable HTTP): Khởi động dưới dạng Streamable HTTP Server, hỗ trợ các lệnh gọi RESTful API.
  • sse: (Không dùng nữa, không khuyến nghị) Khởi động ở chế độ phát trực tuyến Server-Sent Events (SSE), phù hợp cho các tình huống yêu cầu phản hồi trực tuyến. Lưu ý: chế độ SSE không còn được duy trì, khuyến nghị sử dụng thống nhất chế độ Streamable HTTP.

Thành phần

Công cụ

• read_query

  • Mô tả: Thực thi truy vấn SELECT hoặc các lệnh khác trả về ResultSet (ví dụ: SHOW, DESCRIBE). Tùy chọn ghi toàn bộ kết quả vào tệp cục bộ thay vì trả về trực tiếp — hữu ích cho kết quả quá lớn không vừa với ngữ cảnh mô hình.
  • Đầu vào:

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

  • Đầu ra: Không có output_file, nội dung văn bản chứa kết quả truy vấn ở định dạng giống CSV với hàng tiêu đề và tóm tắt số hàng. Với output_file, một tóm tắt ngắn bao gồm đường dẫn tuyệt đối đã giải quyết, số byte và số hàng, cùng bản xem trước nhỏ. Trả về thông báo lỗi khi thất bại.

• write_query

  • Mô tả: Thực thi DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) hoặc lệnh StarRocks khác không trả về ResultSet.
  • Đầu vào:

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

  • Đầu ra: Nội dung văn bản xác nhận thành công (ví dụ: "Query OK, X rows affected") hoặc báo lỗi. Các thay đổi được cam kết tự động khi thành công.

• analyze_query

  • Mô tả: Phân tích truy vấn và nhận kết quả phân tích bằng query profile hoặc explain analyze.
  • Đầu vào:

    {
      "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)"
    }
    

  • Đầu ra: Nội dung văn bản chứa kết quả phân tích truy vấn. Sử dụng ANALYZE PROFILE FROM nếu uuid được cung cấp, nếu không sử dụng EXPLAIN ANALYZE nếu sql được cung cấp.

• top_hot_tables

  • Mô tả: Lấy các bảng nóng hàng đầu theo số lượt truy cập nhật ký kiểm toán. Nó nối information_schema.tables với starrocks_audit_db__.starrocks_audit_tbl__, loại trừ các câu lệnh root và SHOW, khớp văn bản SQL kiểm toán với tên bảng và sắp xếp theo visit_count giảm dần.
  • Đầu vào:

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

  • Đầu ra: Tóm tắt văn bản cộng với nội dung có cấu trúc chứa các hàng được xếp hạng với db, table và visit_count.

• top_bad_tables

  • Mô tả: Lấy các bảng kém hàng đầu theo điểm sức khỏe bảng, tuân theo logic top-bad-tables của Star Management Studio. Nó tái sử dụng phép tính sức khỏe bảng dựa trên information_schema.be_tablets và information_schema.partitions_meta, lọc ra các lược đồ hệ thống, sắp xếp theo table_health_score tăng dần và trả về các bảng có điểm thấp nhất.
  • Đầu vào:

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

  • Đầu ra: Tóm tắt văn bản cộng với nội dung có cấu trúc chứa các hàng được xếp hạng với các trường sức khỏe bảng như db, table, tablet_num, replica_score, tablet_score và table_health_score.

• query_and_plotly_chart

  • Mô tả: Thực thi truy vấn SQL, tải kết quả vào Pandas DataFrame và tạo biểu đồ Plotly bằng biểu thức Python được cung cấp. Được thiết kế để trực quan hóa trong các UI hỗ trợ.
  • Đầu vào:

    {
      "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)"
    }
    

  • Đầu ra: Danh sách chứa:
    1. TextContent: Biểu diễn văn bản của DataFrame và ghi chú rằng biểu đồ dành cho hiển thị UI.
    2. ImageContent: Biểu đồ Plotly được tạo mã hóa dưới dạng hình ảnh PNG base64 (image/png). Trả về thông báo lỗi văn bản khi thất bại hoặc nếu truy vấn không trả về dữ liệu.

• table_overview

  • Mô tả: Lấy tổng quan về một bảng cụ thể: các cột (từ DESCRIBE), tổng số hàng và các hàng mẫu (LIMIT 3). Sử dụng bộ nhớ đệm trong bộ nhớ trừ khi refresh là true.
  • Đầu vào:

    {
      "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.
    }
    

  • Đầu ra: Nội dung văn bản chứa tổng quan đã định dạng (các cột, số hàng, dữ liệu mẫu) hoặc thông báo lỗi. Kết quả được lưu trong bộ nhớ đệm bao gồm cả lỗi trước đó nếu có.

• db_overview

  • Mô tả: Lấy tổng quan (các cột, số hàng, các hàng mẫu) cho tất cả các bảng trong một cơ sở dữ liệu được chỉ định. Sử dụng bộ nhớ đệm cấp bảng cho từng bảng trừ khi refresh là true.
  • Đầu vào:

    {
      "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.
    }
    

  • Đầu ra: Nội dung văn bản chứa các tổng quan được nối cho tất cả các bảng tìm thấy trong cơ sở dữ liệu, được phân tách bằng tiêu đề. Trả về thông báo lỗi nếu không thể truy cập cơ sở dữ liệu hoặc không chứa bảng nào.

Tài nguyên

Tài nguyên trực tiếp

• starrocks:///databases
  • Mô tả: Liệt kê tất cả các cơ sở dữ liệu mà người dùng đã cấu hình có thể truy cập.
  • Truy vấn tương đương: SHOW DATABASES
  • Loại MIME: text/plain

Mẫu tài nguyên

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

  • Mô tả: Lấy định nghĩa lược đồ của một bảng cụ thể.
  • Truy vấn tương đương: SHOW CREATE TABLE {db}.{table}
  • Loại MIME: text/plain

• starrocks:///{db}/tables

  • Mô tả: Liệt kê tất cả các bảng trong một cơ sở dữ liệu cụ thể.
  • Truy vấn tương đương: SHOW TABLES FROM {db}
  • Loại MIME: text/plain

• proc:///{+path}

  • Mô tả: Truy cập thông tin hệ thống nội bộ của StarRocks, tương tự như /proc của Linux. Tham số path chỉ định nút thông tin mong muốn.
  • Truy vấn tương đương: SHOW PROC '/{path}'
  • Loại MIME: text/plain
  • Các đường dẫn phổ biến:
    • /frontends - Thông tin về các nút FE.
    • /backends - Thông tin về các nút BE (đối với triển khai không phải cloud native).
    • /compute_nodes - Thông tin về các nút CN (đối với triển khai cloud native).
    • /dbs - Thông tin về các cơ sở dữ liệu.
    • /dbs/<DB_ID> - Thông tin về một cơ sở dữ liệu cụ thể theo ID.
    • /dbs/<DB_ID>/<TABLE_ID> - Thông tin về một bảng cụ thể theo ID.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - Thông tin phân vùng cho một bảng.
    • /transactions - Thông tin giao dịch được nhóm theo cơ sở dữ liệu.
    • /transactions/<DB_ID> - Thông tin giao dịch cho một ID cơ sở dữ liệu cụ thể.
    • /transactions/<DB_ID>/running - Các giao dịch đang chạy cho một ID cơ sở dữ liệu.
    • /transactions/<DB_ID>/finished - Các giao dịch đã hoàn thành cho một ID cơ sở dữ liệu.
    • /jobs - Thông tin về các công việc không đồng bộ (Schema Change, Rollup, v.v.).
    • /statistic - Thống kê cho từng cơ sở dữ liệu.
    • /tasks - Thông tin về các tác vụ đại lý.
    • /cluster_balance - Thông tin trạng thái cân bằng tải.
    • /routine_loads - Thông tin về các công việc Routine Load.
    • /colocation_group - Thông tin về các nhóm Colocation Join.
    • /catalog - Thông tin về các danh mục đã cấu hình (ví dụ: Hive, Iceberg).

Lời nhắc

Không có lời nhắc nào được xác định bởi máy chủ này.

Hành vi bộ nhớ đệm

• Các công cụ table_overview và db_overview sử dụng bộ nhớ đệm trong bộ nhớ để lưu trữ văn bản tổng quan đã tạo.
• Khóa bộ nhớ đệm là một bộ dữ liệu của (database_name, table_name).
• Khi table_overview được gọi, nó kiểm tra bộ nhớ đệm trước. Nếu kết quả tồn tại và tham số refresh là false (mặc định), kết quả được lưu trong bộ nhớ đệm sẽ được trả về ngay lập tức. Nếu không, nó tìm nạp dữ liệu từ StarRocks, lưu trữ trong bộ nhớ đệm và sau đó trả về.
• Khi db_overview được gọi, nó liệt kê tất cả các bảng trong cơ sở dữ liệu và sau đó cố gắng truy xuất tổng quan cho từng bảng bằng cùng logic bộ nhớ đệm như table_overview (kiểm tra bộ nhớ đệm trước, tìm nạp nếu cần và refresh là false hoặc bộ nhớ đệm bị thiếu). Nếu refresh là true cho db_overview, nó buộc làm mới cho tất cả các bảng trong cơ sở dữ liệu đó.
• Biến môi trường STARROCKS_OVERVIEW_LIMIT cung cấp mục tiêu mềm cho độ dài tối đa của chuỗi tổng quan được tạo cho mỗi bảng khi điền bộ nhớ đệm, giúp quản lý việc sử dụng bộ nhớ.
• Kết quả được lưu trong bộ nhớ đệm, bao gồm mọi thông báo lỗi gặp phải trong quá trình tìm nạp ban đầu, được lưu trữ và trả về khi truy cập bộ nhớ đệm sau đó.

Gỡ lỗi

Sau khi khởi động máy chủ mcp, bạn có thể sử dụng inspector để gỡ lỗi:

npx @modelcontextprotocol/inspector

Demo