Hologres MCP Server

Hologres MCP 服务

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

功能

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

传输模式

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

1. STDIO 模式：使用标准输入/输出流进行通信。这是许多 MCP 服务使用的传统模式。

2. SSE 模式（服务器发送事件）：使用基于 HTTP 的流式传输进行通信。此模式更便于与 Web 应用和云环境集成。

默认情况下，服务以 SSE 模式运行。你可以使用命令行参数 --transport 指定模式。

配置

环境变量

服务通过环境变量进行配置：

变量	描述	默认值
SERVER_HOST	SSE 模式的主机地址	0.0.0.0
SERVER_PORT	SSE 模式的端口号	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
    ],
    "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
    }
  }
}

方法 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
    ],
    "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
    }
  }
}

运行服务

在 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

组件

工具

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

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）
   • 对于 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
   

测试

使用 MCP Inspector 进行测试：

npx @modelcontextprotocol/inspector

然后连接到你的服务：

• 对于 SSE 模式：使用 URL（例如，http://localhost:8001）
• 对于 STDIO 模式：使用命令配置

模型上下文协议（MCP）

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

Hologres MCP 服务实现了 MCP 协议，使 AI Agent 能够轻松访问 Hologres 数据库中的数据和功能。它同时支持 STDIO 和 SSE 传输模式，可为各种环境和用例提供灵活的部署选项。

许可证

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