Hologres

Tiếng Việt | 中文

Hologres MCP Server

Hologres MCP Server đóng vai trò là giao diện chung giữa AI Agents và cơ sở dữ liệu Hologres. Nó cho phép giao tiếp liền mạch giữa AI Agents và Hologres, giúp AI Agents truy xuất siêu dữ liệu cơ sở dữ liệu Hologres và thực thi các thao tác SQL.

Cấu hình

Chế độ 1: Sử dụng tệp cục bộ

Tải xuống

Tải xuống từ Github

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

Tích hợp MCP

Thêm cấu hình sau vào tệp cấu hình máy khách 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"
            }
        }
    }
}

Chế độ 2: Sử dụng chế độ PIP

Cài đặt

Cài đặt MCP Server bằng gói sau:

pip install hologres-mcp-server

Tích hợp MCP

Thêm cấu hình sau vào tệp cấu hình máy khách MCP:

Sử dụng chế độ 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"
            }
        }
    }
}

Sử dụng chế độ 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"
            }
        }
    }
}

Chế độ 3: Sử dụng Streamable HTTP Transport

Máy chủ hỗ trợ Streamable HTTP transport cho các kịch bản triển khai từ xa khi STDIO không khả dụng.

Khởi động máy chủ

Trước khi khởi động máy chủ, hãy đặt các biến môi trường kết nối 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"

Sau đó khởi động máy chủ:

# 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

Điểm cuối MCP sẽ khả dụng tại http://<host>:<port>/mcp.

Tùy chọn CLI

Tùy chọn	Mặc định	Mô tả
--transport	stdio	Loại transport: stdio, streamable-http, hoặc sse
--host	127.0.0.1	Máy chủ liên kết đến (chỉ dành cho HTTP transports)
--port	8000	Cổng lắng nghe (chỉ dành cho HTTP transports)

Tích hợp MCP

Thêm cấu hình sau vào tệp cấu hình máy khách MCP:

{
    "mcpServers": {
        "hologres-mcp-server": {
            "url": "http://<host>:<port>/mcp"
        }
    }
}

Sử dụng với Claude Code

# Add to Claude Code
claude mcp add hologres-mcp-server \
  -e HOLOGRES_HOST=<your_host> \
  -e HOLOGRES_PORT=<your_port> \
  -e HOLOGRES_USER=<your_access_id> \
  -e HOLOGRES_PASSWORD=<your_access_key> \
  -e HOLOGRES_DATABASE=<your_database> \
  -- uvx hologres-mcp-server

Thành phần

Công cụ

• execute_hg_select_sql: Thực thi truy vấn SELECT SQL trong cơ sở dữ liệu Hologres
• execute_hg_select_sql_with_serverless: Thực thi truy vấn SELECT SQL trong cơ sở dữ liệu Hologres với serverless computing
• execute_hg_dml_sql: Thực thi truy vấn DML (INSERT, UPDATE, DELETE) SQL trong cơ sở dữ liệu Hologres
• execute_hg_ddl_sql: Thực thi truy vấn DDL (CREATE, ALTER, DROP, COMMENT ON) SQL trong cơ sở dữ liệu Hologres
• gather_hg_table_statistics: Thu thập thống kê bảng trong cơ sở dữ liệu Hologres
  • Tham số: schema_name (chuỗi), table (chuỗi)
• get_hg_query_plan: Lấy kế hoạch truy vấn trong cơ sở dữ liệu Hologres
• get_hg_execution_plan: Lấy kế hoạch thực thi trong cơ sở dữ liệu Hologres
• call_hg_procedure: Gọi một thủ tục trong cơ sở dữ liệu Hologres
• create_hg_maxcompute_foreign_table: Tạo bảng ngoại MaxCompute trong cơ sở dữ liệu Hologres.

Vì một số Agents không hỗ trợ resources và resource templates, các công cụ sau được cung cấp để lấy siêu dữ liệu của lược đồ, bảng, khung nhìn và bảng ngoại.

• list_hg_schemas: Liệt kê tất cả lược đồ trong cơ sở dữ liệu Hologres hiện tại, ngoại trừ lược đồ hệ thống.
• list_hg_tables_in_a_schema: Liệt kê tất cả bảng trong một lược đồ cụ thể, bao gồm loại của chúng (bảng, khung nhìn, bảng ngoại, bảng phân vùng).
  • Tham số: schema_name (chuỗi)
• show_hg_table_ddl: Hiển thị tập lệnh DDL của một bảng, khung nhìn hoặc bảng ngoại trong cơ sở dữ liệu Hologres.
  • Tham số: schema_name (chuỗi), table (chuỗi)
• query_and_plotly_chart: Thực thi truy vấn SELECT SQL và tạo biểu đồ (cột, đường, phân tán, tròn, histogram, vùng). Trả về kết quả truy vấn và ảnh PNG mã hóa base64.
  • Tham số: query (chuỗi), chart_type (chuỗi, mặc định "bar"), x_column (chuỗi), y_column (chuỗi), title (chuỗi)
• analyze_hg_query_by_id: Phân tích hồ sơ hiệu suất của một truy vấn cụ thể bằng query_id từ hg_query_log. Trả về các chỉ số chi tiết bao gồm thời lượng, bộ nhớ, thời gian CPU, thống kê đọc/ghi.
  • Tham số: query_id (chuỗi)
• get_hg_slow_queries: Lấy các truy vấn chậm từ hg_query_log được sắp xếp theo thời lượng.
  • Tham số: min_duration_ms (số nguyên, mặc định 1000), limit (số nguyên, mặc định 20)
• list_hg_dynamic_tables: Liệt kê tất cả Dynamic Tables với trạng thái, cài đặt độ mới và thông tin làm mới cuối cùng.
  • Tham số: schema_name (chuỗi, tùy chọn)
• get_hg_dynamic_table_refresh_history: Lấy lịch sử làm mới cho một Dynamic Table cụ thể, bao gồm thời lượng, trạng thái và độ trễ.
  • Tham số: schema_name (chuỗi), table_name (chuỗi), limit (số nguyên, mặc định 10)
• list_hg_recyclebin: Liệt kê tất cả bảng trong thùng rác Hologres (các bảng đã xóa có thể khôi phục).
• restore_hg_table_from_recyclebin: Khôi phục một bảng đã xóa từ thùng rác Hologres.
  • Tham số: table_name (chuỗi), schema_name (chuỗi, mặc định "public")
• list_hg_warehouses: Liệt kê tất cả nhóm tính toán (warehouses) với CPU, bộ nhớ, số cụm và trạng thái của chúng.
• switch_hg_warehouse: Chuyển tài nguyên tính toán của phiên hiện tại sang một warehouse được chỉ định.
  • Tham số: warehouse_name (chuỗi)
• get_hg_table_storage_size: Lấy chi tiết kích thước lưu trữ của một bảng, bao gồm phân tích tổng, dữ liệu, chỉ mục và siêu dữ liệu.
  • Tham số: schema_name (chuỗi), table (chuỗi)
• cancel_hg_query: Hủy hoặc chấm dứt một truy vấn đang chạy bằng ID tiến trình của nó.
  • Tham số: pid (số nguyên), terminate (boolean, mặc định false)
• list_hg_active_queries: Liệt kê các truy vấn và kết nối hiện đang hoạt động từ pg_stat_activity.
  • Tham số: state (chuỗi: "active", "idle", hoặc "all", mặc định "active")
• list_hg_query_queues: Liệt kê tất cả Hàng đợi Truy vấn và bộ phân loại của chúng (giới hạn đồng thời, quy tắc định tuyến). Yêu cầu V3.0+.
• get_hg_table_properties: Lấy thuộc tính bảng bao gồm distribution_key, clustering_key, segment_key, bitmap_columns, cài đặt binlog, v.v.
  • Tham số: schema_name (chuỗi), table (chuỗi)
• get_hg_table_shard_info: Lấy thông tin Nhóm Bảng và số lượng shard của bảng để chẩn đoán lệch dữ liệu.
  • Tham số: schema_name (chuỗi), table (chuỗi)
• list_hg_external_databases: Liệt kê tất cả Cơ sở dữ liệu Ngoại và Máy chủ Ngoại để tăng tốc Lakehouse. Yêu cầu V3.0+.
• get_hg_lock_diagnostics: Chẩn đoán tranh chấp khóa bằng cách hiển thị các truy vấn đang chặn và đang chờ.
• get_hg_table_info_trend: Lấy xu hướng lưu trữ bảng từ hg_table_info, hiển thị kích thước lưu trữ hàng ngày, số lượng tệp và thay đổi số hàng.
  • Tham số: schema_name (chuỗi), table (chuỗi), days (số nguyên, mặc định 7)
• manage_hg_query_queue: Tạo, xóa hoặc dọn sạch Hàng đợi Truy vấn. Yêu cầu V3.0+ và đặc quyền superuser.
  • Tham số: action (chuỗi: "create", "drop", "clear"), queue_name (chuỗi), max_concurrency (số nguyên, cho create), max_queue_size (số nguyên, cho create)
• manage_hg_classifier: Tạo hoặc xóa bộ phân loại cho Hàng đợi Truy vấn. Yêu cầu V3.0+.
  • Tham số: action (chuỗi: "create", "drop"), queue_name (chuỗi), classifier_name (chuỗi), priority (số nguyên, cho create)
• set_hg_query_queue_property: Đặt hoặc xóa thuộc tính trên Hàng đợi Truy vấn hoặc bộ phân loại. Yêu cầu V3.0+.
  • Tham số: target (chuỗi: "queue", "classifier"), queue_name (chuỗi), property_key (chuỗi), property_value (chuỗi), classifier_name (chuỗi, cho classifier), action (chuỗi: "set", "remove")
• manage_hg_warehouse: Quản lý nhóm tính toán: tạm dừng, tiếp tục, khởi động lại, đổi tên hoặc thay đổi kích thước. Yêu cầu superuser.
  • Tham số: action (chuỗi: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (chuỗi), cu (số nguyên, cho resize), new_name (chuỗi, cho rename)
• get_hg_warehouse_status: Lấy trạng thái chạy chi tiết và tiến trình mở rộng của một nhóm tính toán.
  • Tham số: warehouse_name (chuỗi)
• rebalance_hg_warehouse: Kích hoạt tái cân bằng shard cho một nhóm tính toán để loại bỏ lệch dữ liệu.
  • Tham số: warehouse_name (chuỗi)
• list_hg_data_masking_rules: Liệt kê tất cả quy tắc che dữ liệu được cấu hình qua tiện ích mở rộng hg_anon (cấp cột và cấp người dùng).
• query_hg_external_files: Truy vấn tệp trực tiếp từ OSS bằng hàm EXTERNAL_FILES mà không cần tạo bảng ngoại. Yêu cầu V4.1+.
  • Tham số: path (chuỗi), format (chuỗi: "csv", "parquet", "orc"), columns (chuỗi, tùy chọn), oss_endpoint (chuỗi, tùy chọn), role_arn (chuỗi, tùy chọn)
• get_hg_guc_config: Lấy giá trị hiện tại của tham số GUC (Grand Unified Configuration).
  • Tham số: guc_name (chuỗi)

Tài nguyên

Tài nguyên tích hợp sẵn

• hologres:///schemas: Lấy tất cả lược đồ trong cơ sở dữ liệu Hologres

Mẫu tài nguyên

• hologres:///{schema}/tables: Liệt kê tất cả bảng trong một lược đồ trong cơ sở dữ liệu Hologres

• hologres:///{schema}/{table}/partitions: Liệt kê tất cả phân vùng của một bảng phân vùng trong cơ sở dữ liệu Hologres

• hologres:///{schema}/{table}/ddl: Lấy DDL bảng trong cơ sở dữ liệu Hologres

• hologres:///{schema}/{table}/statistic: Hiển thị thống kê bảng đã thu thập trong cơ sở dữ liệu Hologres

• system:///{+system_path}: Đường dẫn hệ thống bao gồm:

  • hg_instance_version - Hiển thị phiên bản của instance hologres.
  • guc_value/<guc_name> - Hiển thị giá trị guc (Grand Unified Configuration).
  • missing_stats_tables - Hiển thị các bảng thiếu thống kê.
  • stat_activity - Hiển thị thông tin các truy vấn hiện đang chạy.
  • query_log/latest/<row_limits> - Lấy lịch sử nhật ký truy vấn gần đây với số hàng được chỉ định.
  • query_log/user/<user_name>/<row_limits> - Lấy lịch sử nhật ký truy vấn cho một người dùng cụ thể với giới hạn hàng.
  • query_log/application/<application_name>/<row_limits> - Lấy lịch sử nhật ký truy vấn cho một ứng dụng cụ thể với giới hạn hàng.
  • query_log/failed/<interval>/<row_limits> - Lấy lịch sử nhật ký truy vấn thất bại với khoảng thời gian và số hàng được chỉ định.

Lời nhắc

• analyze_table_performance: Tạo lời nhắc để phân tích hiệu suất bảng trong Hologres
• optimize_query: Tạo lời nhắc để tối ưu hóa truy vấn SQL trong Hologres
• explore_schema: Tạo lời nhắc để khám phá lược đồ trong cơ sở dữ liệu Hologres

Kiểm thử

Dự án bao gồm các bài kiểm thử đơn vị và kiểm thử tích hợp toàn diện.

Kiểm thử đơn vị

Kiểm thử đơn vị không yêu cầu kết nối cơ sở dữ liệu và sử dụng các phụ thuộc giả lập. Bộ kiểm thử bao gồm 326 trường hợp kiểm thử bao gồm:

• Chức năng công cụ và xác thực SQL
• Tài nguyên và mẫu tài nguyên
• Tạo lời nhắc
• Hàm tiện ích và xử lý lỗi
• Kịch bản đồng thời
• Bảo vệ chống SQL injection

# 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

Kiểm thử tích hợp

Kiểm thử tích hợp yêu cầu kết nối cơ sở dữ liệu Hologres thực. Bộ kiểm thử bao gồm 61 trường hợp kiểm thử được tổ chức thành 12 lớp kiểm thử:

Lớp kiểm thử	Số bài kiểm thử	Mô tả
TestMCPConnection	5	Kết nối máy chủ MCP và chức năng cơ bản
TestMCPResources	14	Chức năng đọc tài nguyên (lược đồ, bảng, DDL, thống kê, phân vùng, nhật ký truy vấn)
TestMCPTools	10	Gọi công cụ cho các thao tác chỉ đọc
TestMCPProcedureTools	3	Gọi công cụ thủ tục lưu trữ
TestMCPMaxComputeTools	1	Tạo bảng ngoại MaxCompute
TestMCPDDLTools	5	Thao tác DDL (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	Thao tác DML (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Xử lý lỗi và trường hợp biên
TestMCPPrompts	4	Chức năng tạo lời nhắc
TestMCPConcurrency	3	Thao tác MCP đồng thời
TestMCPBoundaryConditions	4	Trường hợp biên (Unicode, NULL, kết quả rỗng)
TestMCPPerformance	3	Kịch bản hiệu suất (tập kết quả lớn/rộng)

1. Tạo tệp cấu hình từ ví dụ:

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

2. Chỉnh sửa tệp cấu hình với thông tin xác thực Hologres của bạn:

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

3. Chạy kiểm thử tích hợp:

# 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

Lưu ý: Kiểm thử tích hợp sẽ bị bỏ qua nếu tệp .test_mcp_client_env bị thiếu hoặc chứa cấu hình không đầy đủ.

Chất lượng mã nguồn

Dự án này sử dụng ruff để kiểm tra và định dạng mã nguồn.

# 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

Xây dựng & Xuất bản

Xây dựng

Dự án này sử dụng hatchling làm backend xây dựng. Các tạo phẩm xây dựng sẽ được tạo trong thư mục dist/.

# Using uv (recommended)
uv build

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

Xuất bản lên 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/*

Quy trình phát hành

# 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

Tính năng cập nhật 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