Hologres MCP Server

Hologres MCP Server

Hologres MCP Server serves as a universal interface between AI Agents and Hologres databases. It enables seamless communication between AI Agents and Hologres, helping AI Agents retrieve Hologres database metadata and execute SQL operations.

Features

• Multiple Transport Mode Support: Run in STDIO, SSE, or HTTP Stream mode
• Database Metadata Access: Retrieve schema and table information
• SQL Execution: Execute SQL queries and analyze results
• Statistics Management: Collect and view table statistics
• Query Planning: Get query plans and execution plans

Transport Modes

Hologres MCP Server supports three transport modes:

1. STDIO Mode: Uses standard input/output streams for communication. This is the traditional mode used by many MCP servers.

2. SSE Mode (Server-Sent Events): Uses HTTP-based streaming for communication. This mode allows for easier integration with web applications and cloud environments.

3. HTTP Stream Transport: Implements the Streamable HTTP transport protocol from the MCP specification. This mode supports both batch responses and streaming via Server-Sent Events (SSE), providing a modern, flexible transport layer with advanced features.

By default, the server runs in SSE mode. You can specify the mode using the --transport command-line argument.

Configuration

Environment Variables

The server is configured through environment variables:

Variable	Description	Default
SERVER_HOST	Host address for SSE and HTTP Stream modes	0.0.0.0
SERVER_PORT	Port number for SSE and HTTP Stream modes	8001
HOLOGRES_HOST	Hologres database host	localhost
HOLOGRES_PORT	Hologres database port	5432
HOLOGRES_USER	Hologres database username	(required)
HOLOGRES_PASSWORD	Hologres database password	(required)
HOLOGRES_DATABASE	Hologres database name	(required)

Installation Methods

Method 1: Using Local Repository

1. Clone the repository:

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

2. Add the following configuration to the MCP client configuration file:

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

Method 2: Using PIP Installation

1. Install the MCP Server package:

pip install hologres-mcp-server

2. Add the following configuration to the MCP client configuration file:

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

Running the Server

Running in SSE Mode (Default)

# 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

Running in STDIO Mode

# 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

Running in HTTP Stream Mode

# 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

Components

Tools

• execute_sql: Execute queries in Hologres

• analyze_table: Collect table statistics

• get_query_plan: Get query plan

• get_execution_plan: Get execution plan

Resources

Built-in Resources

• hologres:///schemas: Get all schemas in the database

Resource Templates

• hologres:///{schema}/tables: List all tables in a schema

• hologres:///{schema}/{table}/ddl: Get table DDL

• hologres:///{schema}/{table}/statistic: Show collected table statistics

• system:///{+system_path}: System paths include:

  • missing_stats_tables - Shows the tables that are missing statistics.
  • stat_activity - Shows the information of current running queries.
  • query_log/latest/<row_limits> - Get recent query log history with specified number of rows.
  • query_log/user/<user_name>/<row_limits> - Get query log history for a specific user with row limits.
  • query_log/application/<application_name>/<row_limits> - Get query log history for a specific application with row limits.

Test Cases and Examples

The repository includes several examples and test cases to help you understand how to use the Hologres MCP Server:

Python Examples

SSE Mode Client

The python_sse_client.py example demonstrates how to connect to the server in SSE mode using Python:

# 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 Mode Client

The python_stdio_client.py example shows how to interact with the server in STDIO mode:

# 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 Mode Client

The python_http_stream_client.py example demonstrates how to connect to the server in HTTP Stream mode using Python:

# 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 Example

The nodejs_sse_client.js example demonstrates how to connect to the server in SSE mode using Node.js:

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

Unit Tests

The test_server.py file contains unit tests that verify the server's functionality:

# 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"])

To run the tests:

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

Integration with MCP Clients

Cherry Studio

Cherry Studio is an open-source AI Client that supports MCP servers. To integrate with Cherry Studio:

1. Install Cherry Studio from the GitHub releases page
2. Configure your MCP server in Cherry Studio:
   • For SSE mode: Use the host and port (e.g., http://localhost:8001)
   • For HTTP Stream mode: Use the host and port with the /mcp endpoint (e.g., http://localhost:8001/mcp)
   • For STDIO mode: Configure the command and arguments as shown in the configuration examples above

Development

Prerequisites

• Python 3.10 or higher
• uv for package management

Local Development

1. Clone the repository
2. Set up environment variables
3. Run the server in development mode:

   # 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
   

Testing

For testing with the MCP Inspector:

npx @modelcontextprotocol/inspector

Then connect to your server:

• For SSE mode: Use the URL (e.g., http://localhost:8001)
• For HTTP Stream mode: Use the URL with the /mcp endpoint (e.g., http://localhost:8001/mcp)
• For STDIO mode: Use the command configuration

Model Context Protocol (MCP)

Model Context Protocol (MCP) is an open protocol that standardizes how AI applications communicate with external data sources and tools. Whether you're building AI-powered IDEs, enhancing chat interfaces, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.

Hologres MCP Server implements the MCP protocol, enabling AI agents to easily access data and functionality in Hologres databases. By supporting STDIO, SSE, and HTTP Stream transport modes, it provides flexible deployment options for various environments and use cases.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.