Hologres MCP Server

Hologres MCP 服务

Hologres MCP 服务是 AI Agent 与 Hologres 数据库之间的通用接口。它支持 AI Agent 与 Hologres 无缝通信，帮助 AI Agent 获取 Hologres 数据库元数据并执行 SQL 操作。

功能特性

• 支持多种传输模式：以 STDIO、SSE 或 HTTP Stream 模式运行
• 数据库元数据访问：获取架构和表信息
• SQL 执行：执行 SQL 查询并分析结果
• 统计信息管理：收集和查看表统计信息
• 查询规划：获取查询计划和执行计划

传输模式

Hologres MCP 服务支持三种传输模式：

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 模式：使用命令配置

模型上下文协议（MCP）

模型上下文协议（MCP）是一种开放协议，用于标准化 AI 应用与外部数据源和工具的通信方式。无论你是在构建 AI 驱动的 IDE、增强聊天界面，还是创建自定义 AI 工作流，MCP 都提供了一种将大模型与其所需上下文连接起来的标准化方式。

Hologres MCP Server 实现了 MCP 协议，使 AI Agent 能够轻松访问 Hologres 数据库中的数据和功能。通过支持 STDIO、SSE 和 HTTP Stream 传输模式，它为各种环境和使用场景提供了灵活的部署选项。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。