Hologres MCP Server

Hologres MCP Server

Hologres MCP Server は、AI エージェントと Hologres データベースをつなぐ汎用インターフェースとして機能します。AI エージェントと Hologres のシームレスな通信を可能にし、AI エージェントが Hologres データベースのメタデータを取得したり、SQL 操作を実行したりできるようにします。

特長

• 2 種類のトランスポートモードに対応：STDIO モードまたは SSE モードで実行できます
• データベースメタデータへのアクセス：スキーマとテーブルの情報を取得します
• SQL の実行：SQL クエリを実行して結果を分析します
• 統計情報の管理：テーブルの統計情報を収集して表示します
• クエリプランニング：クエリプランと実行プランを取得します

トランスポートモード

Hologres MCP Server は、次の 2 種類のトランスポートモードに対応しています。

1. STDIO モード：標準入出力ストリームを使用して通信します。多くの MCP サーバーで使用されている従来のモードです。

2. SSE モード（Server-Sent Events）：HTTP ベースのストリーミングを使用して通信します。このモードでは、Web アプリケーションやクラウド環境との統合が容易になります。

デフォルトでは、サーバーは SSE モードで実行されます。--transport コマンドライン引数を使用してモードを指定できます。

設定

環境変数

サーバーは環境変数で設定します。

変数	説明	デフォルト
SERVER_HOST	SSE モードのホストアドレス	0.0.0.0
SERVER_PORT	SSE モードのポート番号	8001
HOLOGRES_HOST	Hologres データベースのホスト	localhost
HOLOGRES_PORT	Hologres データベースのポート	5432
HOLOGRES_USER	Hologres データベースのユーザー名	(必須)
HOLOGRES_PASSWORD	Hologres データベースのパスワード	(必須)
HOLOGRES_DATABASE	Hologres データベース名	(必須)

インストール方法

方法 1：ローカルリポジトリを使用する

1. リポジトリをクローンします。

git clone https://github.com/aliyun/alibabacloud-hologres-mcp-server.git

2. MCP クライアントの設定ファイルに次の設定を追加します。

"mcpServers": {
  "hologres-mcp-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/alibabacloud-hologres-mcp-server",
      "run",
      "hologres-mcp-server",
      "--transport",
      "sse"  // or "stdio" for STDIO mode
    ],
    "env": {
      "HOLOGRES_HOST": "host",
      "HOLOGRES_PORT": "port",
      "HOLOGRES_USER": "access_id",
      "HOLOGRES_PASSWORD": "access_key",
      "HOLOGRES_DATABASE": "database",
      "SERVER_HOST": "0.0.0.0",  // Only needed for SSE mode
      "SERVER_PORT": "8001"      // Only needed for SSE mode
    }
  }
}

方法 2：PIP インストールを使用する

1. MCP Server パッケージをインストールします。

pip install hologres-mcp-server

2. MCP クライアントの設定ファイルに次の設定を追加します。

"mcpServers": {
  "hologres-mcp-server": {
    "command": "uv",
    "args": [
      "run",
      "--with",
      "hologres-mcp-server",
      "hologres-mcp-server",
      "--transport",
      "sse"  // or "stdio" for STDIO mode
    ],
    "env": {
      "HOLOGRES_HOST": "host",
      "HOLOGRES_PORT": "port",
      "HOLOGRES_USER": "access_id",
      "HOLOGRES_PASSWORD": "access_key",
      "HOLOGRES_DATABASE": "database",
      "SERVER_HOST": "0.0.0.0",  // Only needed for SSE mode
      "SERVER_PORT": "8001"      // Only needed for SSE mode
    }
  }
}

サーバーの実行

SSE モードで実行する（デフォルト）

# Set environment variables
export HOLOGRES_HOST=your_host
export HOLOGRES_PORT=your_port
export HOLOGRES_USER=your_user
export HOLOGRES_PASSWORD=your_password
export HOLOGRES_DATABASE=your_database
export SERVER_HOST=0.0.0.0
export SERVER_PORT=8001

# Run the server
hologres-mcp-server

STDIO モードで実行する

# Set environment variables
export HOLOGRES_HOST=your_host
export HOLOGRES_PORT=your_port
export HOLOGRES_USER=your_user
export HOLOGRES_PASSWORD=your_password
export HOLOGRES_DATABASE=your_database

# Run the server with STDIO transport
hologres-mcp-server --transport stdio

コンポーネント

ツール

• execute_sql：Hologres でクエリを実行します

• analyze_table：テーブルの統計情報を収集します

• get_query_plan：クエリプランを取得します

• get_execution_plan：実行プランを取得します

リソース

組み込みリソース

• hologres:///schemas：データベース内のすべてのスキーマを取得します

リソーステンプレート

• hologres:///{schema}/tables：スキーマ内のすべてのテーブルを一覧表示します

• hologres:///{schema}/{table}/ddl：テーブルの DDL を取得します

• hologres:///{schema}/{table}/statistic：収集済みのテーブル統計情報を表示します

• system:///{+system_path}： システムパスは次のとおりです。

  • missing_stats_tables - 統計情報が不足しているテーブルを表示します。
  • stat_activity - 現在実行中のクエリの情報を表示します。
  • query_log/latest/<row_limits> - 指定した行数の最新のクエリログ履歴を取得します。
  • query_log/user/<user_name>/<row_limits> - 行数を指定して、特定のユーザーのクエリログ履歴を取得します。
  • query_log/application/<application_name>/<row_limits> - 行数を指定して、特定のアプリケーションのクエリログ履歴を取得します。

テストケースと例

このリポジトリには、Hologres MCP Server の使用方法を理解するのに役立つ例とテストケースがいくつか含まれています。

Python の例

SSE モードのクライアント

python_sse_client.py の例では、Python を使用して SSE モードでサーバーに接続する方法を示します。

# Connect to SSE endpoint
sse_client = connect_to_sse()

# Initialize the connection
initialize()

# List available tools
tools_response = list_tools()

# Execute a SQL query
sql_result = call_tool("execute_sql", {
    "query": "SELECT 'Hello, Hologres!' AS greeting"
})

# List all schemas
schemas_result = read_resource("hologres:///schemas")

STDIO モードのクライアント

python_stdio_client.py の例では、STDIO モードでサーバーとやり取りする方法を示します。

# Start the client
client = StdioClient(command)

# Initialize the connection
client.send_message("initialize", {
    "clientInfo": {
        "name": "python-stdio-test-client",
        "version": "1.0.0"
    }
})

# Execute a SQL query
client.send_message("callTool", {
    "name": "execute_sql",
    "arguments": {
        "query": "SELECT 'Hello, Hologres!' AS greeting"
    }
})

Node.js の例

nodejs_sse_client.js の例では、Node.js を使用して SSE モードでサーバーに接続する方法を示します。

// Connect to SSE endpoint
eventSource = await connectToSSE();

// Initialize the connection
await initialize();

// Execute a SQL query
const sqlResult = await callTool('execute_sql', {
  query: "SELECT 'Hello, Hologres!' AS greeting"
});

単体テスト

test_server.py ファイルには、サーバーの機能を検証する単体テストが含まれています。

# Test initializing the connection
def test_01_initialize(self):
    response = self.send_message("initialize", {
        "clientInfo": {
            "name": "test-client",
            "version": "1.0.0"
        }
    })
    
    self.assertIn("result", response)
    self.assertIn("protocolVersion", response["result"])

# Test listing available tools
def test_02_list_tools(self):
    response = self.send_message("listTools")
    
    self.assertIn("result", response)
    self.assertIn("tools", response["result"])

テストを実行するには、次のようにします。

# Set up environment variables first
python examples/test_server.py

MCP クライアントとの統合

Cherry Studio

Cherry Studio は、MCP サーバーに対応したオープンソースの AI クライアントです。Cherry Studio と連携するには、次の手順に従ってください。

1. GitHub のリリースページから Cherry Studio をインストールします
2. Cherry Studio で MCP サーバーを設定します：
   • SSE モードの場合：ホストとポートを使用します（例：http://localhost:8001）
   • STDIO モードの場合：上記の設定例に示すように、コマンドと引数を設定します

開発

前提条件

• Python 3.10 以降
• パッケージ管理用の uv

ローカル開発

1. リポジトリをクローンします
2. 環境変数を設定します
3. 開発モードでサーバーを実行します：

   # For SSE mode
   python -m hologres_mcp_server.main
   
   # For STDIO mode
   python -m hologres_mcp_server.main --transport stdio
   

テスト

MCP Inspector を使用してテストするには：

npx @modelcontextprotocol/inspector

次に、サーバーに接続します：

• SSE モードの場合：URL を使用します（例：http://localhost:8001）
• STDIO モードの場合：コマンドの設定を使用します

Model Context Protocol (MCP)

Model Context Protocol (MCP) は、AI アプリケーションが外部データソースやツールと通信する方法を標準化するオープンプロトコルです。AI を活用した IDE の構築、チャットインターフェースの機能強化、カスタム AI ワークフローの作成など、MCP は LLM を必要なコンテキストに接続する標準的な方法を提供します。

Hologres MCP Server は MCP プロトコルを実装しており、AI エージェントが Hologres データベースのデータや機能に簡単にアクセスできるようにします。STDIO と SSE の両方のトランスポートモードに対応し、さまざまな環境やユースケースに柔軟なデプロイ方法を提供します。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。