# 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:
```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, 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:
```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, 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)

```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
```

### Running in HTTP Stream 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
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](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"
    }
})
```

#### HTTP Stream Mode Client
The [python_http_stream_client.py](examples/python_http_stream_client.py) example demonstrates how to connect to the server in HTTP Stream mode using Python:

```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](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 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](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
   
   # For HTTP Stream mode
   python -m hologres_mcp_server.main --transport http-stream
   ```

### 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 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)](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 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.