Hologres

ไทย | 中文

Hologres MCP Server

Hologres MCP Server ทำหน้าที่เป็นอินเทอร์เฟซสากลระหว่าง AI Agents และฐานข้อมูล Hologres ช่วยให้การสื่อสารระหว่าง AI Agents และ Hologres เป็นไปอย่างราบรื่น ช่วยให้ AI Agents ดึงข้อมูลเมตาดาต้าของฐานข้อมูล 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 Server โดยใช้แพ็คเกจต่อไปนี้:

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: การใช้ Streamable HTTP Transport

เซิร์ฟเวอร์รองรับ Streamable HTTP transport สำหรับสถานการณ์การปรับใช้ระยะไกลที่ไม่มี STDIO

เริ่มต้นเซิร์ฟเวอร์

ก่อนเริ่มต้นเซิร์ฟเวอร์ ให้ตั้งค่าตัวแปรสภาพแวดล้อมการเชื่อมต่อ 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://<host>:<port>/mcp

ตัวเลือก CLI

ตัวเลือก	ค่าเริ่มต้น	คำอธิบาย
--transport	stdio	ประเภทการขนส่ง: stdio, streamable-http, หรือ sse
--host	127.0.0.1	โฮสต์ที่จะผูก (เฉพาะ HTTP transports)
--port	8000	พอร์ตที่จะรับฟัง (เฉพาะ HTTP transports)

การรวม MCP

เพิ่มการกำหนดค่าต่อไปนี้ลงในไฟล์การกำหนดค่าไคลเอนต์ MCP:

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

การใช้งานกับ 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

ส่วนประกอบ

เครื่องมือ

• execute_hg_select_sql: ดำเนินการคิวรี SELECT SQL ในฐานข้อมูล Hologres
• execute_hg_select_sql_with_serverless: ดำเนินการคิวรี SELECT SQL ในฐานข้อมูล Hologres ด้วยการประมวลผลแบบไร้เซิร์ฟเวอร์
• execute_hg_dml_sql: ดำเนินการคิวรี DML (INSERT, UPDATE, DELETE) SQL ในฐานข้อมูล Hologres
• execute_hg_ddl_sql: ดำเนินการคิวรี DDL (CREATE, ALTER, DROP, COMMENT ON) SQL ในฐานข้อมูล Hologres
• gather_hg_table_statistics: รวบรวมสถิติตารางในฐานข้อมูล Hologres
  • พารามิเตอร์: schema_name (string), table (string)
• get_hg_query_plan: รับแผนคิวรีในฐานข้อมูล Hologres
• get_hg_execution_plan: รับแผนการดำเนินการในฐานข้อมูล Hologres
• call_hg_procedure: เรียกใช้โพรซีเยอร์ในฐานข้อมูล Hologres
• create_hg_maxcompute_foreign_table: สร้างตารางภายนอก MaxCompute ในฐานข้อมูล Hologres

เนื่องจากบาง Agents ไม่รองรับทรัพยากรและเทมเพลตทรัพยากร จึงมีเครื่องมือต่อไปนี้เพื่อรับข้อมูลเมตาดาต้าของสกีมา ตาราง วิว และตารางภายนอก

• list_hg_schemas: แสดงรายการสกีมาทั้งหมดในฐานข้อมูล Hologres ปัจจุบัน ยกเว้นสกีมาระบบ
• list_hg_tables_in_a_schema: แสดงรายการตารางทั้งหมดในสกีมาเฉพาะ รวมถึงประเภทของตาราง (table, view, external table, partitioned table)
  • พารามิเตอร์: schema_name (string)
• show_hg_table_ddl: แสดงสคริปต์ DDL ของตาราง วิว หรือตารางภายนอกในฐานข้อมูล Hologres
  • พารามิเตอร์: schema_name (string), table (string)
• query_and_plotly_chart: ดำเนินการคิวรี SELECT SQL และสร้างแผนภูมิ (bar, line, scatter, pie, histogram, area) ส่งคืนผลลัพธ์คิวรีและรูปภาพ PNG ที่เข้ารหัส base64
  • พารามิเตอร์: query (string), chart_type (string, default "bar"), x_column (string), y_column (string), title (string)
• analyze_hg_query_by_id: วิเคราะห์โปรไฟล์ประสิทธิภาพของคิวรีเฉพาะโดยใช้ query_id จาก hg_query_log ส่งคืนเมตริกโดยละเอียดรวมถึงระยะเวลา หน่วยความจำ เวลา CPU สถิติการอ่าน/เขียน
  • พารามิเตอร์: query_id (string)
• get_hg_slow_queries: รับคิวรีที่ช้าจาก hg_query_log เรียงตามระยะเวลา
  • พารามิเตอร์: min_duration_ms (int, default 1000), limit (int, default 20)
• list_hg_dynamic_tables: แสดงรายการ Dynamic Tables ทั้งหมดพร้อมสถานะ การตั้งค่าความสดใหม่ และข้อมูลการรีเฟรชล่าสุด
  • พารามิเตอร์: schema_name (string, optional)
• get_hg_dynamic_table_refresh_history: รับประวัติการรีเฟรชสำหรับ Dynamic Table เฉพาะ รวมถึงระยะเวลา สถานะ และความหน่วง
  • พารามิเตอร์: schema_name (string), table_name (string), limit (int, default 10)
• list_hg_recyclebin: แสดงรายการตารางทั้งหมดในถังรีไซเคิล Hologres (ตารางที่ถูกลบที่สามารถกู้คืนได้)
• restore_hg_table_from_recyclebin: กู้คืนตารางที่ถูกลบจากถังรีไซเคิล Hologres
  • พารามิเตอร์: table_name (string), schema_name (string, default "public")
• list_hg_warehouses: แสดงรายการกลุ่มการประมวลผล (warehouses) ทั้งหมดพร้อม CPU หน่วยความจำ จำนวนคลัสเตอร์ และสถานะ
• switch_hg_warehouse: สลับทรัพยากรการประมวลผลของเซสชันปัจจุบันไปยัง warehouse ที่ระบุ
  • พารามิเตอร์: warehouse_name (string)
• get_hg_table_storage_size: รับรายละเอียดขนาดพื้นที่จัดเก็บของตาราง รวมถึงการแจกแจงรวม ข้อมูล ดัชนี และเมตาดาต้า
  • พารามิเตอร์: schema_name (string), table (string)
• cancel_hg_query: ยกเลิกหรือยุติคิวรีที่กำลังทำงานโดยใช้รหัสกระบวนการ
  • พารามิเตอร์: pid (int), terminate (bool, default false)
• list_hg_active_queries: แสดงรายการคิวรีและการเชื่อมต่อที่กำลังทำงานอยู่จาก pg_stat_activity
  • พารามิเตอร์: state (string: "active", "idle", หรือ "all", default "active")
• list_hg_query_queues: แสดงรายการ Query Queues ทั้งหมดและตัวแยกประเภท (ขีดจำกัดการทำงานพร้อมกัน กฎการกำหนดเส้นทาง) ต้องการ V3.0+
• get_hg_table_properties: รับคุณสมบัติของตารางรวมถึง distribution_key, clustering_key, segment_key, bitmap_columns, การตั้งค่า binlog ฯลฯ
  • พารามิเตอร์: schema_name (string), table (string)
• get_hg_table_shard_info: รับข้อมูล Table Group และจำนวน shard ของตารางสำหรับการวินิจฉัยความเบ้ของข้อมูล
  • พารามิเตอร์: schema_name (string), table (string)
• list_hg_external_databases: แสดงรายการ External Databases และ Foreign Servers ทั้งหมดสำหรับการเร่งความเร็ว Lakehouse ต้องการ V3.0+
• get_hg_lock_diagnostics: วินิจฉัยการแย่งล็อกโดยแสดงคิวรีที่บล็อกและคิวรีที่รอ
• get_hg_table_info_trend: รับแนวโน้มพื้นที่จัดเก็บตารางจาก hg_table_info แสดงขนาดพื้นที่จัดเก็บรายวัน จำนวนไฟล์ และการเปลี่ยนแปลงจำนวนแถว
  • พารามิเตอร์: schema_name (string), table (string), days (int, default 7)
• manage_hg_query_queue: สร้าง ลบ หรือล้าง Query Queue ต้องการ V3.0+ และสิทธิ์ superuser
  • พารามิเตอร์: action (string: "create", "drop", "clear"), queue_name (string), max_concurrency (int, สำหรับ create), max_queue_size (int, สำหรับ create)
• manage_hg_classifier: สร้างหรือลบตัวแยกประเภทสำหรับ Query Queue ต้องการ V3.0+
  • พารามิเตอร์: action (string: "create", "drop"), queue_name (string), classifier_name (string), priority (int, สำหรับ create)
• set_hg_query_queue_property: ตั้งค่าหรือลบคุณสมบัติบน Query Queue หรือตัวแยกประเภท ต้องการ V3.0+
  • พารามิเตอร์: target (string: "queue", "classifier"), queue_name (string), property_key (string), property_value (string), classifier_name (string, สำหรับ classifier), action (string: "set", "remove")
• manage_hg_warehouse: จัดการกลุ่มการประมวลผล: ระงับ ดำเนินการต่อ เริ่มใหม่ เปลี่ยนชื่อ หรือปรับขนาด ต้องการ superuser
  • พารามิเตอร์: action (string: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (string), cu (int, สำหรับ resize), new_name (string, สำหรับ rename)
• get_hg_warehouse_status: รับสถานะการทำงานโดยละเอียดและความคืบหน้าการปรับขนาดของกลุ่มการประมวลผล
  • พารามิเตอร์: warehouse_name (string)
• rebalance_hg_warehouse: เรียกใช้การปรับสมดุล shard สำหรับกลุ่มการประมวลผลเพื่อขจัดความเบ้ของข้อมูล
  • พารามิเตอร์: warehouse_name (string)
• list_hg_data_masking_rules: แสดงรายการกฎการปกปิดข้อมูลทั้งหมดที่กำหนดค่าผ่านส่วนขยาย hg_anon (ระดับคอลัมน์และระดับผู้ใช้)
• query_hg_external_files: คิวรีไฟล์โดยตรงจาก OSS โดยใช้ฟังก์ชัน EXTERNAL_FILES โดยไม่ต้องสร้างตารางภายนอก ต้องการ V4.1+
  • พารามิเตอร์: path (string), format (string: "csv", "parquet", "orc"), columns (string, optional), oss_endpoint (string, optional), role_arn (string, optional)
• get_hg_guc_config: รับค่าปัจจุบันของพารามิเตอร์ GUC (Grand Unified Configuration)
  • พารามิเตอร์: guc_name (string)

ทรัพยากร

ทรัพยากรในตัว

• hologres:///schemas: รับสกีมาทั้งหมดในฐานข้อมูล Hologres

เทมเพลตทรัพยากร

• hologres:///{schema}/tables: แสดงรายการตารางทั้งหมดในสกีมาในฐานข้อมูล Hologres

• hologres:///{schema}/{table}/partitions: แสดงรายการพาร์ติชันทั้งหมดของตารางที่มีพาร์ติชันในฐานข้อมูล Hologres

• hologres:///{schema}/{table}/ddl: รับ DDL ของตารางในฐานข้อมูล Hologres

• hologres:///{schema}/{table}/statistic: แสดงสถิติตารางที่รวบรวมในฐานข้อมูล Hologres

• system:///{+system_path}: พาธระบบรวมถึง:

  • hg_instance_version - แสดงเวอร์ชันของอินสแตนซ์ hologres
  • guc_value/<guc_name> - แสดงค่า guc (Grand Unified Configuration)
  • missing_stats_tables - แสดงตารางที่ขาดสถิติ
  • stat_activity - แสดงข้อมูลของคิวรีที่กำลังทำงานอยู่
  • query_log/latest/<row_limits> - รับประวัติบันทึกคิวรีล่าสุดด้วยจำนวนแถวที่ระบุ
  • query_log/user/<user_name>/<row_limits> - รับประวัติบันทึกคิวรีสำหรับผู้ใช้เฉพาะพร้อมขีดจำกัดแถว
  • query_log/application/<application_name>/<row_limits> - รับประวัติบันทึกคิวรีสำหรับแอปพลิเคชันเฉพาะพร้อมขีดจำกัดแถว
  • query_log/failed/<interval>/<row_limits> - รับประวัติบันทึกคิวรีที่ล้มเหลวพร้อมช่วงเวลาและจำนวนแถวที่ระบุ

พรอมต์

• analyze_table_performance: สร้างพรอมต์เพื่อวิเคราะห์ประสิทธิภาพของตารางใน Hologres
• optimize_query: สร้างพรอมต์เพื่อเพิ่มประสิทธิภาพคิวรี SQL ใน Hologres
• 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 คลาสทดสอบ:

คลาสทดสอบ	การทดสอบ	คำอธิบาย
TestMCPConnection	5	การเชื่อมต่อเซิร์ฟเวอร์ MCP และฟังก์ชันพื้นฐาน
TestMCPResources	14	ฟังก์ชันการอ่านทรัพยากร (สกีมา, ตาราง, DDL, สถิติ, พาร์ติชัน, บันทึกคิวรี)
TestMCPTools	10	การเรียกใช้เครื่องมือสำหรับการดำเนินการอ่านอย่างเดียว
TestMCPProcedureTools	3	การเรียกใช้เครื่องมือโพรซีเยอร์ที่จัดเก็บ
TestMCPMaxComputeTools	1	การสร้างตารางภายนอก MaxCompute
TestMCPDDLTools	5	การดำเนินการ DDL (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	การดำเนินการ DML (INSERT, UPDATE, DELETE)
TestErrorHandling	3	การจัดการข้อผิดพลาดและกรณีขอบ
TestMCPPrompts	4	ฟังก์ชันการสร้างพรอมต์
TestMCPConcurrency	3	การดำเนินการ MCP พร้อมกัน
TestMCPBoundaryConditions	4	กรณีขอบ (Unicode, NULL, ผลลัพธ์ว่างเปล่า)
TestMCPPerformance	3	สถานการณ์ประสิทธิภาพ (ชุดผลลัพธ์ขนาดใหญ่/กว้าง)

1. สร้างไฟล์การกำหนดค่าจากตัวอย่าง:

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

2. แก้ไขไฟล์การกำหนดค่าด้วยข้อมูลประจำตัว Hologres ของคุณ:

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

3. เรียกใช้การทดสอบการรวมระบบ:

# 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 หายไปหรือมีการกำหนดค่าที่ไม่สมบูรณ์

คุณภาพของโค้ด

โปรเจกต์นี้ใช้ ruff สำหรับการตรวจสอบและจัดรูปแบบโค้ด

# 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

การสร้าง & เผยแพร่

การสร้าง

โปรเจกต์นี้ใช้ hatchling เป็นแบ็กเอนด์การสร้าง อาร์ติแฟกต์การสร้างจะถูกสร้างขึ้นในไดเรกทอรี 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