Specialized AI Database Server

**Referenced Files in This Document** - [[README.md]](file/readme.md) - [[pyproject.toml]](file/pyproject.toml) - [[__init__.py]](file/src/mcp-server-starrocks/init-.py) - [[server.py]](file/src/mcp-server-starrocks/server.py) - [[db_client.py]](file/src/mcp-server-starrocks/db-client.py) - [[connection_health_checker.py]](file/src/mcp-server-starrocks/connection-health-checker.py) - [[db_summary_manager.py]](file/src/mcp-server-starrocks/db-summary-manager.py) - [[test_db_client.py]](file/tests/test-db-client.py) - [[test_env_config.py]](file/test-env-config.py) - [[Dockerfile]](file/dockerfile) - [[deployment.yaml]](file/k8s/deployment.yaml) - [[service.yaml]](file/k8s/service.yaml) - [[architecture-mcp-server-starrocks.md]](file/docs/architecture-mcp-server-starrocks.md)

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion
10. Appendices

Introduction

This document describes the specialized StarRocks Model Context Protocol (MCP) server designed to enable AI agents to interact with StarRocks databases through standardized interfaces. The server extends standard database connectivity with AI-focused capabilities such as entity retrieval, schema discovery, metadata management, and intelligent caching. It provides secure, auditable access to StarRocks for AI workloads via tools for SQL execution, data visualization, and system introspection, while ensuring reliable connectivity through a dedicated connection health monitoring system.

Project Structure

The MCP server is implemented as a Python package with a clear separation of concerns:

• Entry point and CLI orchestration
• MCP protocol integration and tool/resource definitions
• Database client abstraction supporting both MySQL and Arrow Flight SQL
• Connection health monitoring
• Database summary manager for AI-friendly overviews
• Tests and Kubernetes deployment artifacts

Diagram sources

• [init.py]
• [server.py]
• [db_client.py]
• [connection_health_checker.py]
• [db_summary_manager.py]
• [pyproject.toml]
• [README.md]
• [deployment.yaml]
• [service.yaml]

Section sources

• [README.md]
• [pyproject.toml]

Core Components

• MCP Server Orchestrator: Initializes FastMCP, registers tools and resources, configures transport modes, and starts health monitoring.
• Database Client: Provides unified execution interface supporting MySQL pooling and Arrow Flight SQL, with robust error handling and connection lifecycle management.
• Connection Health Checker: Monitors database connectivity via periodic checks and logs status transitions.
• Database Summary Manager: Produces AI-friendly summaries of databases and tables, with caching and prioritization for large datasets.
• Tools and Resources: Expose standardized operations for SQL execution, schema discovery, system introspection, and data visualization.

Section sources

• [server.py]
• [db_client.py]
• [connection_health_checker.py]
• [db_summary_manager.py]

Architecture Overview

The server integrates the FastMCP framework to expose tools and resources over multiple transport modes. It encapsulates database connectivity behind a resilient client that supports both MySQL and Arrow Flight SQL, with health monitoring and caching to optimize AI workflows.

Diagram sources

• [server.py]
• [db_client.py]
• [connection_health_checker.py]
• [db_summary_manager.py]

Detailed Component Analysis

MCP Server Orchestrator

The orchestrator initializes logging, FastMCP, and global instances for DB client and summary manager. It defines resources for database discovery and system introspection, and registers tools for SQL execution, analysis, visualization, and overviews. It supports multiple transport modes and applies CORS middleware for HTTP transports.

Diagram sources

• [server.py]
• [db_client.py]

Section sources

• [server.py]
• [server.py]
• [server.py]

Database Client Implementation

The DB client abstracts connection management and query execution:

• Connection configuration via environment variables or URL parsing
• MySQL connection pooling with health checks and automatic reconnection
• Optional Arrow Flight SQL support for modern data transfer
• Unified result handling with CSV-like formatting and pandas conversion
• Performance analysis utilities for query diagnostics

Diagram sources

• [db_client.py]

Section sources

• [db_client.py]
• [db_client.py]
• [db_client.py]
• [db_client.py]

Connection Health Checking System

The health checker runs a background thread that periodically validates connectivity by executing a simple query. It logs transitions and periodic status updates, enabling proactive detection of connectivity issues.

Diagram sources

• [connection_health_checker.py]
• [connection_health_checker.py]

Section sources

• [connection_health_checker.py]
• [connection_health_checker.py]

Database Summary Manager

The summary manager provides AI-friendly overviews of databases and tables:

• Intelligent prioritization of large tables for focused insights
• Efficient caching with expiration and refresh controls
• Column metadata extraction and CREATE statement retrieval for large tables
• Truncated formatting respecting configurable limits

Diagram sources

• [db_summary_manager.py]
• [db_summary_manager.py]

Section sources

• [db_summary_manager.py]
• [db_summary_manager.py]

MCP Protocol Implementation

The server implements the MCP protocol using FastMCP decorators to define:

• Tools: read_query, write_query, analyze_query, query_and_plotly_chart, table_overview, db_overview, db_summary
• Resources: starrocks:///databases, starrocks:///{db}/{table}/schema, starrocks:///{db}/tables, proc:///

Diagram sources

• [server.py]
• [server.py]

Section sources

• [server.py]
• [server.py]
• [server.py]

Dependency Analysis

External dependencies include FastMCP for protocol handling, MySQL Connector for database connectivity, pandas and Plotly for analytics and visualization, and ADBC drivers for Arrow Flight SQL.

Diagram sources

• [pyproject.toml]

Section sources

• [pyproject.toml]

Performance Considerations

• Connection pooling: The MySQL connector pool improves concurrency and reduces connection overhead.
• Caching: Both table-level and database-level caches reduce repeated metadata queries; limits control memory usage for overviews.
• Arrow Flight SQL: Enables efficient data transfer for large analytical queries when available.
• Query formatting: Results are truncated to prevent oversized responses; visualization tools support JSON or image outputs.
• Health monitoring: Periodic checks proactively detect connectivity issues, minimizing downtime impact.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

• Connectivity issues: Use the health checker logs to diagnose persistent failures; reset connections programmatically on errors.
• Configuration problems: Validate environment variables and connection URLs; tests demonstrate expected parsing behavior.
• Transport mode: Ensure the MCP host configuration matches the server's transport mode (prefer Streamable HTTP).
• Logging: Configure LOG_LEVEL to capture detailed traces; logs include timestamps, levels, and stack traces for exceptions.

Section sources

• [connection_health_checker.py]
• [server.py]
• [test_db_client.py]
• [test_env_config.py]

Conclusion

The StarRocks MCP server provides a robust, AI-centric interface to StarRocks, combining standardized MCP tooling with resilient database connectivity, intelligent caching, and health monitoring. Its modular design supports both traditional MySQL and modern Arrow Flight SQL pathways, enabling scalable analytics and visualization for AI agents.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

AI-Specific Operations and Examples

• Entity retrieval: Use read_query for SELECT statements and write_query for DDL/DML commands.
• Schema discovery: Access starrocks:///databases and starrocks:///{db}/tables resources.
• Metadata management: Retrieve table schemas via starrocks:///{db}/{table}/schema and system information via proc:///{path*}.
• Data visualization: Execute query_and_plotly_chart to generate charts from query results.
• Performance tuning: Use analyze_query and collect_query_dump_and_profile for query diagnostics.

Section sources

• [README.md]
• [server.py]
• [server.py]

Monitoring, Logging, and Observability

• Logging: Structured logs with level, timestamp, and stack traces; adjust LOG_LEVEL via environment.
• Health monitoring: Dedicated checker thread logs periodic and transition statuses.
• Kubernetes: Deployment and service manifests define resource limits and network exposure.

Section sources

• [server.py]
• [connection_health_checker.py]
• [deployment.yaml]
• [service.yaml]

Integration Patterns with the AI Ecosystem

• MCP Host configuration: Point to the server’s Streamable HTTP endpoint and configure environment variables for connection details.
• Visualization: Use query_and_plotly_chart to produce UI-ready charts or JSON representations.
• Security: Leverage MCP protocol transparency and isolation; apply column-level protections as defined in the broader ecosystem.

Section sources

• [README.md]
• [server.py]
• [architecture-mcp-server-starrocks.md]