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 模式 (Server-Sent Events)：使用基于 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 Server 包：

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 模式运行（默认）

# 设置环境变量
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

# 运行服务器
hologres-mcp-server

以 STDIO 模式运行

# 设置环境变量
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

# 以 STDIO 传输模式运行服务器
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 模式连接到服务器：

# 连接到 SSE 端点
sse_client = connect_to_sse()

# 初始化连接
initialize()

# 列出可用工具
tools_response = list_tools()

# 执行 SQL 查询
sql_result = call_tool("execute_sql", {
    "query": "SELECT 'Hello, Hologres!' AS greeting"
})

# 列出所有模式
schemas_result = read_resource("hologres:///schemas")

STDIO 模式客户端

python_stdio_client.py 示例演示了如何以 STDIO 模式与服务器交互：

# 启动客户端
client = StdioClient(command)

# 初始化连接
client.send_message("initialize", {
    "clientInfo": {
        "name": "python-stdio-test-client",
        "version": "1.0.0"
    }
})

# 执行 SQL 查询
client.send_message("callTool", {
    "name": "execute_sql",
    "arguments": {
        "query": "SELECT 'Hello, Hologres!' AS greeting"
    }
})

Node.js 示例

nodejs_sse_client.js 示例演示了如何使用 Node.js 以 SSE 模式连接到服务器：

// 连接到 SSE 端点
eventSource = await connectToSSE();

// 初始化连接
await initialize();

// 执行 SQL 查询
const sqlResult = await callTool('execute_sql', {
  query: "SELECT 'Hello, Hologres!' AS greeting"
});

单元测试

test_server.py 文件包含验证服务器功能的单元测试：

# 测试初始化连接
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"])

# 测试列出可用工具
def test_02_list_tools(self):
    response = self.send_message("listTools")
    
    self.assertIn("result", response)
    self.assertIn("tools", response["result"])

要运行测试：

# 首先设置环境变量
python examples/test_server.py

与 MCP 客户端集成

Cherry Studio

Cherry Studio 是一个支持 MCP 服务器的开源 AI 客户端。要与 Cherry Studio 集成：

1. 从 GitHub releases page 安装 Cherry Studio
2. 在 Cherry Studio 中配置您的 MCP 服务器：
   • 对于 SSE 模式：使用主机和端口（例如，http://localhost:8001）
   • 对于 STDIO 模式：按照上面的配置示例配置命令和参数

开发

前提条件

• Python 3.10 或更高版本
• uv 用于包管理

本地开发

1. 克隆仓库
2. 设置环境变量
3. 以开发模式运行服务器：

   # 对于 SSE 模式
   python -m hologres_mcp_server.main
   
   # 对于 STDIO 模式
   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 都提供了一种标准化的方式来将 LLM 与它们需要的上下文连接起来。

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

许可证

该项目根据 Apache License 2.0 获得许可 - 有关详细信息，请参阅 LICENSE 文件。