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 tổng quan chi tiết về lược đồ/dữ liệu mà không yêu cầu thiết lập phía máy khách phức tạp.

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ơ 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 chỉ số 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 các bản tóm tắt toàn diện về 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ố lượng hàng và dữ liệu mẫu.
• Trực quan hóa Dữ liệu: Thực thi 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 vào bộ nhớ đệm để 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: Thiết lập 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 công cụ quản lý gói và dự án Python nhanh (sự 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 biệt lập và cài đặt các phụ thuộc cần thiết trong lần sử dụng đầu tiên, do đó 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ó có trong PATH của bạn:

uv --version

Cài đặt

Bạn thường không cần cài đặt gói thủ công — máy chủ MCP sẽ khởi chạy nó cho bạn qua uv (xem Cấu hình bên dưới). uv tải 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 thông 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 HTTP có thể Truyền phát (khuyến nghị):

Để khởi động máy chủ ở chế độ HTTP có thể Truyền phát:

Trước tiên, hãy kiểm tra kết nối đến StarRocks ổn định (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 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ộ (để 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"
      }
    }
  }
}

Tham số Dòng lệnh:

Máy chủ hỗ trợ các tham 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ủ lưu trữ 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 nên trỏ đến điểm cuối HTTP có thể Truyền phát của máy chủ MCP của bạn (điều chỉnh máy chủ/cổng nếu cần).
• Với cấu hình này, các máy khách có thể tương tác với máy chủ bằng các yêu cầu HTTP POST JSON tiêu chuẩn. Không yêu cầu 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) đã bị phản đối và không còn được bảo trì. Vui lòng sử dụng chế độ HTTP có thể Truyền phát 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ách sử dụ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: 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ụ StarRocks FE. Mặc định là localhost.
• STARROCKS_PORT: (Tùy chọn) Cổng giao thức MySQL của dịch vụ StarRocks FE. 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 trống.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Tùy chọn, chỉ 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 nào được cung cấp qua STARROCKS_PASSWORD hoặc STARROCKS_URL.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Tùy chọn, chỉ 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 các tham 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 nó nếu phần cơ sở dữ liệu bị bỏ qua trong các tham số của chúng. Mặc định là trống (không có cơ sở dữ liệu mặc định).

Tùy chọn 2: URL Kết nối (được ư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

Ưu tiên mật khẩu:

• Mật khẩu được 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 đượ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_KEYCHAIN_SERVICE được cấu hình, mật khẩu sẽ được đọc từ Keychain macOS.

Ví dụ về Keychain macOS

Lưu 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:

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

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ụ StarRocks FE. Khi được đặt, máy chủ kết nối bằng giao thức Arrow Flight SQL hiệu suất cao (thông 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ác cài đặt kết nối tương tự đượ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 tham 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 đườ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 sẽ 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 biểu đồ HTML. cdn (mặc định) giữ cho 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 (được truyền qua 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 tham 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 một 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 về jpeg với một 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 đến dịch vụ StarRocks FE. 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 rõ ràng (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 yêu cầu cụ thể; 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 cơ bản 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. Để có 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 đè tất cả các 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) được sử 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 song phương (mTLS).
• STARROCKS_SSL_KEY: (Tùy chọn) Đường dẫn đến khóa riêng tư của máy khách (PEM) cho TLS song phương (mTLS).
• STARROCKS_SSL_VERIFY_CERT: (Tùy chọn) Đặt thành true để xác minh chứng chỉ máy chủ dựa trên 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ủ dựa trên 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 biệt:

• STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS: (Tùy chọn) Đặt thành true để sử dụng grpc+tls:// thay vì văn bản thuần túy grpc://. Khi được bật, STARROCKS_SSL_CA được sử 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 trữ mật khẩu văn bản thuần túy trực tiếp trong mcp.json. Ưu tiên đưa STARROCKS_PASSWORD (và các đường dẫn chứng chỉ) từ trình quản lý bí mật hoặc môi trường, và không bao giờ commit thông tin xác thực vào kiểm soát phiên bản.

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

Thành phần

Công cụ

• read_query

• Mô tả: Thực thi câu lệnh SELECT hoặc các lệnh khác trả về ResultSet (ví dụ: SHOW, DESCRIBE). Có thể 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 các 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: Nếu 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. Nếu có output_file, một tóm tắt ngắn bao gồm đường dẫn tuyệt đối đã phân giải, số byte, số hàng, cùng một bản xem trước nhỏ. Trả về thông báo lỗi nếu thất bại.

• write_query

  • Mô tả: Thực thi lệnh DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE), hoặc cá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 hồ sơ truy vấn 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, ngược lại 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 từ nhật ký kiểm toán. Công cụ này kết hợp 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 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 chất lượng hàng đầu theo điểm sức khỏe bảng, tuân theo logic top-bad-tables của Star Management Studio. Công cụ này tái sử dụng tính toán sức khỏe bảng dựa trên information_schema.be_tablets và information_schema.partitions_meta, lọc bỏ 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 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 giao diện người dùng 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: Một 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ị giao diện người dùng.
    2. ImageContent: Biểu đồ Plotly đã tạo được mã hóa dưới dạng ảnh PNG base64 (image/png). Trả về thông báo lỗi văn bản nếu thất bại hoặc nếu truy vấn không có 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á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 mỗi 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 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 cá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 cơ sở dữ liệu 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 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 (cho triển khai không phải cloud native).
    • /compute_nodes - Thông tin về các nút CN (cho 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 bất đồ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ụ agent.
    • /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 catalog đã cấu hình (ví dụ: Hive, Iceberg).

Lời nhắc

Không có lời nhắc nào được định nghĩa 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ộ gồm (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ả đã lưu trong bộ nhớ đệm được trả về ngay lập tức. Nếu không, nó lấy dữ liệu từ StarRocks, lưu vào bộ nhớ đệm, rồi 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 lấy 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, lấy dữ liệu nếu cần và refresh là false hoặc không có trong bộ nhớ đệm). 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ột 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 vào bộ nhớ đệm, giúp quản lý việc sử dụng bộ nhớ.
• Kết quả đã lưu trong bộ nhớ đệm, bao gồm mọi thông báo lỗi gặp phải trong lần lấy dữ liệu ban đầu, được lưu trữ và trả về trong các lần truy cập bộ nhớ đệm tiếp theo.

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