Hologres MCP Server

英语| 中文

Hologres MCP服务器

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

配置

模式1：使用本地文件

下载

从Github下载

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

MCP集成

将以下配置添加到MCP客户端配置文件中：

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/alibabacloud-hologres-mcp-server",
                "run",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

模式2：使用PIP模式

安装

使用以下软件包安装MCP服务器：

pip install hologres-mcp-server

MCP集成

将以下配置添加到MCP客户端配置文件中：

使用uv模式

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "hologres-mcp-server",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

使用uvx模式

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uvx",
            "args": [
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

模式3：使用流式HTTP传输

对于STDIO不可用的远程部署场景，服务器支持流式HTTP传输。

启动服务器

启动服务器之前，设置Hologres连接环境变量：

export HOLOGRES_HOST="your-hologres-instance.hologres.aliyuncs.com"
export HOLOGRES_PORT="80"
export HOLOGRES_USER="your_access_id"
export HOLOGRES_PASSWORD="your_access_key"
export HOLOGRES_DATABASE="your_database"

然后启动服务器：

# Using pip-installed package
hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

# Or using uvx
uvx hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

MCP端点将在 http://: /mcp.

CLI选项

MCP集成

将以下配置添加到MCP客户端配置文件中：

{
    "mcpServers": {
        "hologres-mcp-server": {
            "url": "http://:
/mcp"
        }
    }
}

使用Claude代码

# Add to Claude Code
claude mcp add hologres-mcp-server \
  -e HOLOGRES_HOST= \
  -e HOLOGRES_PORT= \
  -e HOLOGRES_USER= \
  -e HOLOGRES_PASSWORD= \
  -e HOLOGRES_DATABASE= \
  -- uvx hologres-mcp-server

组件

工具

• execute_hg_select_sql：在Hologres数据库中执行SELECT SQL查询
• execute_hg_select_sql_with_serverless：使用无服务器计算在Hologres数据库中执行SELECT SQL查询
• execute_hg_dml_sql：在Hologres数据库中执行DML（INSERT、UPDATE、DELETE）SQL查询
• execute_hg_ddl_sql：在Hologres数据库中执行DDL（CREATE、ALTER、DROP、COMMENT ON）SQL查询
• gather_hg_table_statistics：在Hologres数据库中收集表统计信息

- 参数： schema_name （字符串）， table （字符串）

• get_hg_query_plan：在Hologres数据库中获取查询计划
• get_hg_execution_plan：在Hologres数据库中获取执行计划
• call_hg_procedure：调用Hologres数据库中的过程
• create_hg_maxcompute_foreign_table：在Hologres数据库中创建MaxCompute外部表。

由于某些代理不支持资源和资源模板，因此提供了以下工具来获取模式、表、视图和外部表的元数据。

• list_hg_schemas：列出当前Hologres数据库中的所有模式，不包括系统模式。
• list_hg_tables_in_a_schema：列出特定架构中的所有表，包括其类型（表、视图、外部表、分区表）。

- 参数： schema_name （字符串）

• show_hg_table_ddl：显示Hologres数据库中表、视图或外部表的DDL脚本。

- 参数： schema_name （字符串）， table （字符串）

• query_and_plotly_chart：执行SELECT SQL查询并生成图表（条形图、折线图、散点图、饼图、直方图、面积图）。返回查询结果和base64编码的PNG图像。

- 参数： query （字符串）， chart_type （字符串，默认“bar”）， x_column （字符串）， y_column （字符串）， title （字符串）

• analyze_hg_query_by_id：通过hg_query_log中的query_id分析特定查询的性能配置文件。返回详细的指标，包括持续时间、内存、CPU时间、读/写统计数据。

- 参数： query_id （字符串）

• get_hg_slow_queries：从hg_query_log获取按持续时间排序的慢速查询。

- 参数： min_duration_ms （int，默认值1000）， limit （int，默认值20）

• list_hg_dynamic_tables：列出所有动态表及其状态、新鲜度设置和上次刷新信息。

- 参数： schema_name （字符串，可选）

• get_hg_dynamic_table_refresh_history：获取特定动态表的刷新历史记录，包括持续时间、状态和延迟。

- 参数： schema_name （字符串）， table_name （字符串）， limit （int，默认值10）

• list_hg_recyclebin：列出Hologres回收站中的所有表（可以恢复的已删除表）。
• restore_hg_table_from_recyclebin：从Hologres回收站还原掉落的桌子。

- 参数： table_name （字符串）， schema_name （字符串，默认为“public”）

• list_hg_warehouses：列出所有计算组（仓库）及其CPU、内存、集群计数和状态。
• switch_hg_warehouse：将当前会话的计算资源切换到指定的仓库。

- 参数： warehouse_name （字符串）

• get_hg_table_storage_size：获取表的存储大小详细信息，包括总计、数据、索引和元数据细分。

- 参数： schema_name （字符串）， table （字符串）

• cancel_hg_query：根据进程ID取消或终止正在运行的查询。

- 参数： pid （int）， terminate （bool，默认为false）

• list_hg_active_queries：列出pg_stat_activity中当前活动的查询和连接。

- 参数： state （字符串：“活动”、“空闲”或“全部”，默认为“活动”）

• list_hg_query_queues：列出所有查询队列及其分类器（并发限制、路由规则）。需要V3.0+版本。
• get_hg_table_properties：获取表属性，包括distribution_key、clustering_key、segment_key、bitmap_columns、binlog设置等。

- 参数： schema_name （字符串）， table （字符串）

• get_hg_table_shard_info：获取表的表组和分片计数信息，用于诊断数据倾斜。

- 参数： schema_name （字符串）， table （字符串）

• list_hg_external_databases：列出用于Lakehouse加速的所有外部数据库和外部服务器。需要V3.0+版本。
• get_hg_lock_diagnostics：通过显示阻塞和等待查询来诊断锁争用。
• get_hg_table_info_trend：从hg_table_info获取表存储趋势，显示每日存储大小、文件数和行数变化。

- 参数： schema_name （字符串）， table （字符串）， days （int，默认值7）

• manage_hg_query_queue：创建、删除或清除查询队列。需要V3.0+和超级用户权限。

- 参数： action （字符串：“创建”、“删除”、“清除”）， queue_name （字符串）， max_concurrency （int，用于创建）， max_queue_size （int，用于创建）

• manage_hg_classifier：为查询队列创建或删除分类器。需要V3.0+版本。

- 参数： action （字符串：“创建”、“删除”）， queue_name （字符串）， classifier_name （字符串）， priority （int，用于创建）

• set_hg_query_queue_property：设置或删除查询队列或分类器的属性。需要V3.0+版本。

- 参数： target （字符串：“队列”、“分类器”）， queue_name （字符串）， property_key （字符串）， property_value （字符串）， classifier_name （字符串，用于分类器）， action （字符串：“set”、“remove”）

• manage_hg_warehouse：管理计算组：挂起、恢复、重新启动、重命名或调整大小。需要超级用户。

- 参数： action （字符串：“暂停”、“恢复”、“重新启动”、“重命名”、“调整大小”）， warehouse_name （字符串）， cu （int，用于调整大小）， new_name （字符串，用于重命名）

• get_hg_warehouse_status：获取计算组的详细运行状态和扩展进度。

- 参数： warehouse_name （字符串）

• rebalance_hg_warehouse：触发计算组的分片重新平衡，以消除数据倾斜。

- 参数： warehouse_name （字符串）

• list_hg_data_masking_rules：列出通过hg_anon扩展配置的所有数据屏蔽规则（列级和用户级）。
• query_hg_external_files：使用EXTERNAL_files函数直接从OSS查询文件，而无需创建外部表。需要V4.1+版本。

- 参数： path （字符串）， format （字符串：“csv”、“拼花地板”、“orc”）， columns （字符串，可选）， oss_endpoint （字符串，可选）， role_arn （字符串，可选）

• get_hg_guc_config：获取GUC（大统一配置）参数的当前值。

- 参数： guc_name （字符串）

资源

内置资源

• hologres:///schemas：获取Hologres数据库中的所有模式

资源模板

• hologres:///{schema}/tables：列出Hologres数据库中模式中的所有表

• hologres:///{schema}/{table}/partitions：列出Hologres数据库中分区表的所有分区

• hologres:///{schema}/{table}/ddl：获取Hologres数据库中的表DDL

• hologres:///{schema}/{table}/statistic：显示Hologres数据库中收集的表统计信息

• system:///{+system_path}:

系统路径包括：

- hg_instance_version -显示holores实例版本。 - guc_value/ -显示guc（大统一配置）值。 - missing_stats_tables -显示缺少统计信息的表。 - stat_activity -显示当前正在运行的查询的信息。 - query_log/latest/ -获取具有指定行数的最近查询日志历史记录。 - query_log/user// -获取具有行限制的特定用户的查询日志历史记录。 - query_log/application// -获取具有行限制的特定应用程序的查询日志历史记录。 - query_log/failed// -获取具有间隔和指定行数的失败查询日志历史记录。

提示

• analyze_table_performance：在Hologres中生成分析表性能的提示
• optimize_query：在Hologres中生成优化SQL查询的提示
• explore_schema：生成提示以探索Hologres数据库中的模式

测试

该项目包括全面的单元测试和集成测试。

单元测试

单元测试不需要数据库连接，并使用模拟依赖关系。测试套件包括 326个测试用例 涵盖：

• 工具功能和SQL验证
• 资源和资源模板
• 提示生成
• 实用功能和错误处理
• 并发场景
• SQL注入保护

# Run all unit tests
uv run pytest tests/unit/ -v

# Run specific test file
uv run pytest tests/unit/test_tools.py -v

# Run with coverage
uv run pytest tests/unit/ --cov=src/hologres_mcp_server --cov-report=html

集成测试

集成测试需要一个真正的Hologres数据库连接。测试套件包括 61个测试用例 分为12个测试班：

1. 根据示例创建配置文件：

cp tests/integration/.test_mcp_client_env_example tests/integration/.test_mcp_client_env

1. 使用您的Hologres凭据编辑配置文件：

HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com
HOLOGRES_PORT=80
HOLOGRES_USER=your_username
HOLOGRES_PASSWORD=your_password
HOLOGRES_DATABASE=your_database

1. 运行集成测试：

# Run all integration tests
uv run pytest tests/integration/ -v -m integration

# Run specific test class
uv run pytest tests/integration/test_mcp_integration.py::TestMCPTools -v

# Run all tests (unit + integration)
uv run pytest tests/ -v

注： 如果出现以下情况，将跳过集成测试 .test_mcp_client_env 文件丢失或包含不完整的配置。

代码质量

此项目使用 颈毛 用于代码过滤和格式化。

# Install dev dependencies
uv sync --dev
uv pip install ruff

# Check code style
uv run ruff check .

# Check and auto-fix
uv run ruff check . --fix

# Format code
uv run ruff format .

# Format check only (no changes)
uv run ruff format . --check

构建和发布

构建

此项目使用 雏鸟 作为构建后端。构建工件将在 dist/ 目录。

# Using uv (recommended)
uv build

# Or using python build module
pip install build
python -m build

发布到PyPI

# Install twine
pip install twine

# Upload to PyPI
twine upload dist/*

# Or upload to Test PyPI first for verification
twine upload --repository testpypi dist/*

发布工作流

# 1. Update version in pyproject.toml
# 2. Clean old build artifacts
rm -rf dist/

# 3. Build
uv build

# 4. Publish
twine upload dist/*

# 5. Tag the release
git tag -a v1.0.3 -m "Release v1.0.3"
git push origin v1.0.3

更新CLI功能

# Use FastMCP framework to generate CLI code and Skill
uv run fastmcp generate-cli hologres-mcp-server hologres_mcp_cli/hologres_mcp_cli.py -f