alibabacloud-hologres-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Test Commands

# Run all tests
uv run pytest tests/ -v

# Run unit tests only (no database required)
uv run pytest tests/unit/ -v

# Run integration tests (requires Hologres database)
uv run pytest tests/integration/ -v -m integration

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

# Run specific test class or method
uv run pytest tests/unit/test_new_tools.py::TestListDynamicTables -v
uv run pytest tests/integration/test_mcp_integration.py::TestMCPTools::test_execute_select -v

# Run with coverage
uv run pytest tests/unit/ --cov=hologres_mcp_server --cov-report=term-missing

# Lint and format
uv run ruff check .
uv run ruff check . --fix
uv run ruff format .
uv run ruff format . --check

# Build package
uv build

Integration Test Setup

Integration tests require a real Hologres connection. Configure via:

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

Edit the file with your Hologres credentials (HOLOGRES_HOST, HOLOGRES_PORT, HOLOGRES_USER, HOLOGRES_PASSWORD, HOLOGRES_DATABASE). Tests will be skipped if the config file is missing or incomplete.

Architecture

This is a FastMCP v3-based MCP server for Alibaba Cloud Hologres (a PostgreSQL-compatible data warehouse). The entry point is __init__.py:main() → server.py:main() which parses CLI arguments (--transport, --host, --port) and starts the FastMCP app with the selected transport (stdio by default, also supports streamable-http and sse).

Core Files

• server.py: All MCP capabilities registered on a single FastMCP app instance via decorators:
  • 39 tools (@app.tool) with tags (query, dml, ddl, admin, analysis, schema)
  • 13 resources (@app.resource) including parameterized URI templates (hologres:///{schema}/{table}/...) and system resources (system:///...)
  • 3 prompts (@app.prompt)
  • A @lifespan handler that validates the DB connection on startup (warns but doesn't fail)