Hologres MCP Server

Hologres MCP サーバー

Hologres MCP サーバーは、AI エージェントと Hologres データベースをつなぐ汎用インターフェースです。AI エージェントと Hologres 間のシームレスな通信を可能にし、AI エージェントによる Hologres データベースのメタデータ取得や SQL 操作の実行を支援します。

機能

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

トランスポートモード

Hologres MCP サーバーは、次の 3 つのトランスポートモードに対応しています。

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

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

3. HTTP Stream トランスポート：MCP 仕様の Streamable HTTP トランスポートプロトコルを実装しています。このモードは、バッチレスポンスと Server-Sent Events（SSE）によるストリーミングの両方に対応し、高度な機能を備えた最新の柔軟なトランスポート層を提供します。

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

設定

環境変数

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

変数	説明	デフォルト
SERVER_HOST	SSE および HTTP Stream モードのホストアドレス	0.0.0.0
SERVER_PORT	SSE および HTTP Stream モードのポート番号	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, or "http-stream" for HTTP Stream 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 and HTTP Stream modes
      "SERVER_PORT": "8001"      // Only needed for SSE and HTTP Stream modes
    }
  }
}

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

1. MCP サーバーパッケージをインストールします：

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, or "http-stream" for HTTP Stream 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 and HTTP Stream modes
      "SERVER_PORT": "8001"      // Only needed for SSE and HTTP Stream modes
    }
  }
}

サーバーの実行

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

HTTP Stream モードで実行する

# 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 with HTTP Stream transport
hologres-mcp-server --transport http-stream

コンポーネント

ツール

• 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 サーバーの使い方を理解するのに役立つ例とテストケースがいくつか含まれています。

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

HTTP Stream モードのクライアント

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

# Test batch mode
# Send a batch of requests
batch_requests = [
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": {
            "clientInfo": {
                "name": "python-http-stream-test-client",
                "version": "1.0.0"
            }
        }
    },
    {
        "jsonrpc": "2.0",
        "id": 2,
        "method": "listTools"
    }
]
batch_responses = send_batch_request(batch_requests)

# Test stream mode
# Send a request with streaming response
initialize_stream_response = initialize(stream_mode=True)

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）
   • HTTP Stream モードの場合：/mcp エンドポイントを含むホストとポートを使用します（例：http://localhost:8001/mcp）
   • 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
   
   # For HTTP Stream mode
   python -m hologres_mcp_server.main --transport http-stream
   

テスト

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

npx @modelcontextprotocol/inspector

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

• SSE モードの場合：URL を使用します（例：http://localhost:8001）
• HTTP Stream モードの場合：/mcp エンドポイントを含む URL を使用します（例：http://localhost:8001/mcp）
• STDIO モードの場合：コマンド設定を使用します

Model Context Protocol（MCP）

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

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

ライセンス

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