analyticbase

analyticbase

analyticbase を使うと、エージェントや、ターミナルを使うあなた自身が ClickHouse データベースの中を調べ、データを変更することなく質問できます。サーバー上のデータベースを一覧表示し、1 つのデータベース内のテーブルを、それぞれのエンジン、コメント、行数、列数とともに一覧表示できます。また、読み取り専用の SELECT クエリを 1 つ実行できます。すべて ClickHouse のプレーンな HTTP インターフェース経由で行われるため、クライアントライブラリは同梱されず、トンネルするネイティブポートもありません。

ClickHouse が利用できない場合、analyticbase はそのことを通知します。MCP サーバーは、接続先のサーバーがまったくなくても起動してツールを一覧表示します。リクエストが送信されるのは実際の操作時だけであり、接続拒否やサーバーエラーは、サーバー自身のテキストを含むエラーとして返されます。存在しない行が作られることはありません。

インストール

npx @reneturcios/analyticbase list-databases

または、コンテナーイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/analyticbase

コンテナーは、デフォルトで MCP サーバーを起動します（下記参照）。CLI として使用するには、CLI 引数を渡してください。

CLI

# Which databases does this server hold?
analyticbase list-databases

# What tables live in one database? (name filters are LIKE patterns)
analyticbase list-tables analytics
analyticbase list-tables analytics --like "events_%" --not-like "%_tmp"

# Run one read-only query; rows print as JSON
analyticbase query "SELECT count() AS n FROM analytics.events"

# Start the MCP server
analyticbase mcp

analyticbase --version

終了コード：成功時は 0、クエリ、ガード、または接続に失敗した場合は 1（どれに失敗したかはエラーに記載されます）、使い方に誤りがある場合は 2 です。

エンドポイントは、次の環境変数で設定します。

変数	意味	デフォルト
CLICKHOUSE_URL	HTTP インターフェースのベース URL 全体。ホストとポートより優先されます	—
CLICKHOUSE_HOST	ホスト名、または完全な http(s):// URL	localhost
CLICKHOUSE_PORT	HTTP インターフェースのポート	8123
CLICKHOUSE_USER	ユーザー名	default
CLICKHOUSE_PASSWORD	パスワード	(空)

クエリの仕組み

各操作は、SQL をリクエスト本文として HTTP インターフェースに POST し、認証情報は URL パラメーターとして渡します。これはインターフェース独自の規約です。一覧表示操作では FORMAT JSONEachRow を追加し、行ごとに 1 つの JSON オブジェクトを解析します。list_tables は system.tables を読み取り、system.columns に対するサブクエリで各テーブルの列数を数えます。また、like ／ not_like フィルターは、エスケープ済みリテラルを使った LIKE ／ NOT LIKE 句として適用します。SELECT クエリでは FORMAT JSON を追加し、レスポンスの data 配列を返します。

読み取り専用ガード

run_select_query（および CLI の query コマンド）がクエリを受け付けるのは、次の条件をすべて満たす場合だけです。

• 先頭の空白とコメントを取り除いた後、最初のキーワードが SELECT または WITH であること。
• 1 つのステートメントだけであること。セミコロンの後に空白以外の文字が続くと、処理を中止します。
• 文字列リテラルの外に、単語全体として INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、TRUNCATE、GRANT、REVOKE、OPTIMIZE、RENAME、DETACH、ATTACH のいずれも含まれないこと。 スキャンの前にシングルクォートで囲まれたリテラルを空白に置き換えるため、SELECT 'drop table t' は問題ありません。一方、列名そのものが update の場合は受け付けられません。ガードは、扱いにくい名前を拒否するほうを、言いくるめられるよりも優先します。

一覧表示操作は、検証とエスケープを行った要素から内部で SQL を組み立てるため、ガードは不要です。

MCP サーバー

1 つのバイナリで両方の用途に対応します。mcp サブコマンドは、stdio MCP サーバーを起動します。

npx -y @reneturcios/analyticbase mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "analyticbase": {
      "command": "npx",
      "args": ["-y", "@reneturcios/analyticbase", "mcp"],
      "env": { "CLICKHOUSE_HOST": "localhost", "CLICKHOUSE_PORT": "8123" }
    }
  }
}

ツール

ツール	入力	返される内容
list_databases	(なし)	system.databases から取得した、データベースごとに 1 つのオブジェクト。
list_tables	database（文字列、必須）、like ／ not_like（文字列、任意）	指定したデータベース内のテーブルごとに 1 つのオブジェクト。スキーマ（データベース）、名前、エンジン、コメント、行数、列数が含まれます。
run_select_query	query（文字列、必須）— 読み取り専用の SQL ステートメント 1 つ	結果の行を、列名をキーとするオブジェクトの JSON 配列として返します。ガード違反、サーバーの不在、データベースエラーはすべてツールエラーとして返されます。存在しない行が作られることはありません。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live ClickHouse
npm run dev     # run the CLI from source via tsx

すべての HTTP 通信は、差し替え可能な fetch 関数を経由します。テストスイートはこれを利用し、設定の解決、ガード、SQL の組み立て、2 種類のレスポンス形式のパーサー、および 3 つすべての操作を、偽の fetch に対してテストします。

ライセンス

MIT — LICENSE を参照してください。