StarRocks MCP Server

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 )。
• **インテリジェントキャッシュ：**テーブルとデータベースの概要はメモリにキャッシュされ、繰り返しのリクエストを高速化します。必要に応じてキャッシュをバイパスできます。
• **柔軟な構成:**環境変数を使用して接続の詳細と動作を設定します。

構成

MCPサーバーは通常、MCPホストを介して実行されます。StarRocks MCPサーバープロセスの起動方法を指定する設定がホストに渡されます。

インストールされたパッケージでuvを使用する:

ローカルディレクトリでuvを使用する (開発用):

環境変数:

• STARROCKS_HOST : (オプション) StarRocks FEサービスのホスト名またはIPアドレス。デフォルトはlocalhostです。
• STARROCKS_PORT : (オプション) StarRocks FEサービスのMySQLプロトコルポート。デフォルトは9030です。
• STARROCKS_USER : (オプション) StarRocks のユーザー名。デフォルトはrootです。
• STARROCKS_PASSWORD : (オプション) StarRocksパスワード。デフォルトは空の文字列です。
• STARROCKS_DB : (オプション) ツール引数またはリソースURIで指定されていない場合に使用するデフォルトのデータベース。設定されている場合、接続はこのデータベースUSEしようとします。table_overviewやdb_overviewなどのツールはtable_overview引数でデータベース部分が省略されている場合にこのデータベースを使用します。デフォルトは空（デフォルトデータベースなし）です。
• STARROCKS_OVERVIEW_LIMIT : (オプション) キャッシュにデータを格納するためにデータを取得する際に、概要ツール ( table_overview 、 db_overview ) によって生成されるテキストの合計文字数のおおよその制限。これは、非常に大きなスキーマや多数のテーブルによる過剰なメモリ使用を防ぐのに役立ちます。デフォルトは20000です。

コンポーネント

ツール

• read_query
  • 説明: SELECT クエリまたは ResultSet を返すその他のコマンド (例: SHOW 、 DESCRIBE ) を実行します。
  • 入力: { "query": "SQL query string" }
  • **出力:**クエリ結果をCSV形式のテキストコンテンツで出力します。ヘッダー行と行数の概要が含まれます。失敗した場合はエラーメッセージが返されます。
• write_query
  • 説明: DDL ( CREATE 、 ALTER 、 DROP )、DML ( INSERT 、 UPDATE 、 DELETE )、または ResultSet を返さないその他の StarRocks コマンドを実行します。
  • 入力: { "query": "SQL command string" }
  • **出力:**成功を示すテキストコンテンツ（例:「クエリは成功しました。X行が影響を受けました」）またはエラーを報告するテキストコンテンツ。成功した場合、変更は自動的にコミットされます。
• 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\")'" }
  • **出力:**次の内容を含むリスト:
    1. TextContent : DataFrame のテキスト表現と、チャートが UI 表示用であることを示す注記。
    2. ImageContent : 生成されたPlotlyチャートはbase64 PNG画像（ image/png ）としてエンコードされます。クエリが失敗した場合、またはクエリでデータが返されなかった場合は、テキストエラーメッセージを返します。
• table_overview
  • **説明:**特定のテーブルの概要を取得します。列数（ DESCRIBEから取得）、行数の合計、サンプル行数（ LIMIT 3 ）。refresh 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 refresh true でない限り、各テーブルに対してテーブルレベルのキャッシュを使用します。
  • 入力：
    { "db": "database_name", // Optional if STARROCKS_DB env var 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 - ルーチン ロード ジョブに関する情報。
    • /colocation_group - コロケーション参加グループに関する情報。
    • /catalog - 構成されたカタログ (例: Hive、Iceberg) に関する情報。

プロンプト

このサーバーでは定義されていません。

キャッシュ動作

• table_overviewおよびdb_overviewツールは、生成された概要テキストを保存するためにメモリ内キャッシュを利用します。
• キャッシュ キーは(database_name, table_name)のタプルです。
• table_overviewが呼び出されると、まずキャッシュをチェックします。結果が存在し、 refreshパラメータがfalse （デフォルト）の場合、キャッシュされた結果が直ちに返されます。そうでない場合は、StarRocks からデータを取得し、キャッシュに保存してから返します。
• db_overviewが呼び出されると、データベース内のすべてのテーブルが一覧表示され、 table_overviewと同じキャッシュロジック（最初にキャッシュをチェックし、必要に応じてフェッチし、 refreshがfalseまたはキャッシュミスの場合）を使用して各テーブルの概要を取得しようとします。db_overview db_overview``refreshがtrueの場合、そのデータベース内のすべてのテーブルが強制的にリフレッシュされます。
• STARROCKS_OVERVIEW_LIMIT環境変数は、キャッシュを作成するときにテーブルごとに生成される概要文字列の最大長のソフト ターゲットを提供し、メモリ使用量の管理に役立ちます。
• 元のフェッチ中に発生したエラー メッセージを含むキャッシュされた結果は保存され、後続のキャッシュ ヒット時に返されます。

デモ