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 - **Dual Transport Mode Support**: Run in either STDIO or SSE 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 two 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. 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 mode | 0.0.0.0 | | SERVER_PORT | Port number for SSE mode | 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: ```shell git clone https://github.com/aliyun/alibabacloud-hologres-mcp-server.git ``` 2. Add the following configuration to the MCP client configuration file: ```json "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 } } } ``` #### Method 2: Using PIP Installation 1. Install the MCP Server package: ```bash pip install hologres-mcp-server ``` 2. Add the following configuration to the MCP client configuration file: ```json "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 } } } ``` ## Running the Server ### Running in SSE Mode (Default) ```bash # 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 ```bash # 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 ``` ## 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](examples/python_sse_client.py) example demonstrates how to connect to the server in SSE mode using Python: ```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](examples/python_stdio_client.py) example shows how to interact with the server in STDIO mode: ```python # 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 Example The [nodejs_sse_client.js](examples/nodejs_sse_client.js) example demonstrates how to connect to the server in SSE mode using Node.js: ```javascript // 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](examples/test_server.py) file contains unit tests that verify the server's functionality: ```python # 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: ```bash # Set up environment variables first python examples/test_server.py ``` ## Integration with MCP Clients ### Cherry Studio [Cherry Studio](https://github.com/CherryHQ/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](https://github.com/CherryHQ/cherry-studio/releases) 2. Configure your MCP server in Cherry Studio: - For SSE mode: Use the host and port (e.g., `http://localhost:8001`) - For STDIO mode: Configure the command and arguments as shown in the configuration examples above ## Development ### Prerequisites - Python 3.10 or higher - [uv](https://docs.astral.sh/uv) for package management ### Local Development 1. Clone the repository 2. Set up environment variables 3. Run the server in development mode: ```bash # For SSE mode python -m hologres_mcp_server.main # For STDIO mode python -m hologres_mcp_server.main --transport stdio ``` ### Testing For testing with the MCP Inspector: ```bash npx @modelcontextprotocol/inspector ``` Then connect to your server: - For SSE mode: Use the URL (e.g., `http://localhost:8001`) - For STDIO mode: Use the command configuration ## Model Context Protocol (MCP) [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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 both STDIO and SSE 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.