使用说明

Hologres MCP服务器

Hologres MCP服务器是AI代理和Hologres数据库之间的通用接口。它实现了AI代理和Hologres之间的无缝通信，帮助AI代理检索Hologres数据库元数据并执行SQL操作。

特性

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

运输方式

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

STDIO模式：使用标准输入/输出流进行通信。这是许多MCP服务器使用的传统模式。
SSE模式（服务器发送事件）：使用基于HTTP的流媒体进行通信。此模式允许更容易地与web应用程序和云环境集成。

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

配置

环境变量

服务器是通过环境变量配置的：

变量	描述	默认值
SERVER_HOST	SSE模式的主机地址	0.0.0.0
SERVER_PORT	SSE模式的端口号	8001
HOLOGRES_HOST	HOLOGRES数据库主机	本地主机
HOLOGRES_PORT	HOLOGRES数据库端口	5432
HOLOGRES_USER	HOLOGRES数据库用户名	（必填）
HOLOGRES_PASSWORD	HOLOGRES数据库密码	（必填）
HOLOGRES_DATABASE	HOLOGRES数据库名称	（必填）

安装方法

方法1：使用本地存储库

克隆存储库：

git clone https://github.com/aliyun/alibabacloud-hologres-mcp-server.git

将以下配置添加到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安装

安装MCP服务器软件包：

pip install hologres-mcp-server

将以下配置添加到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_strio_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客户端集成

樱桃工作室

樱桃工作室是一个支持MCP服务器的开源AI客户端。要与Cherry Studio集成，请执行以下操作：

从安装Cherry Studio GitHub发布页面
在Cherry Studio中配置MCP服务器：
- 对于SSE模式：使用主机和端口（例如。， http://localhost:8001)
- 对于STDIO模式：按照上面的配置示例配置命令和参数

发展

先决条件

Python 3.10或更高版本
紫外线用于包管理

地方发展

克隆存储库
设置环境变量

在开发模式下运行服务器：

# For SSE mode
python -m hologres_mcp_server.main

# For STDIO mode
python -m hologres_mcp_server.main --transport stdio

测试

对于MCP检查员的测试：

npx @modelcontextprotocol/inspector

然后连接到您的服务器：

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

模型上下文协议（MCP）

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

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

许可证

此项目在Apache License 2.0下获得许可-有关详细信息，请参阅License文件。