Skip to content

CLAUDE.md

Latest commit

 

History

History
106 lines (75 loc) · 3.94 KB

CLAUDE.md

File metadata and controls

106 lines (75 loc) · 3.94 KB

CLAUDE.md

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

Project Overview

StarRocks Official MCP Server - A bridge between AI assistants and StarRocks databases, built using FastMCP framework. Enables direct SQL execution, database exploration, data visualization, and schema introspection through the Model Context Protocol (MCP).

Development Commands

Local Development:

# Run the server directly for testing
uv run mcp-server-starrocks

# Run with test mode to verify table overview functionality
uv run mcp-server-starrocks --test

# Run in Streamable HTTP mode (recommended for integration)
export MCP_TRANSPORT_MODE=streamable-http
uv run mcp-server-starrocks

Package Management:

# Install dependencies (handled by uv automatically)
uv sync

# Build package
uv build

Architecture Overview

Core Components

  • src/mcp_server_starrocks/server.py: Main server implementation containing all MCP tools, resources, and database connection logic
  • src/mcp_server_starrocks/__init__.py: Entry point that starts the async server

Connection Architecture

The server supports two connection modes:

  • Standard MySQL Protocol: Default connection using mysql.connector
  • Arrow Flight SQL: High-performance connection using ADBC drivers (enabled when STARROCKS_FE_ARROW_FLIGHT_SQL_PORT is set)

Connection management uses a global singleton pattern with automatic reconnection handling.

Tool Categories

  1. Query Execution Tools:

    • read_query: Execute SELECT and other result-returning queries
    • write_query: Execute DDL/DML commands
    • analyze_query: Query performance analysis via EXPLAIN ANALYZE

  2. Overview Tools with Caching:

    • table_overview: Get table schema, row count, and sample data (cached)
    • db_overview: Get overview of all tables in a database (uses table cache)

  3. Visualization Tool:

    • query_and_plotly_chart: Execute query and generate Plotly charts from results

Resource Endpoints

  • starrocks:///databases: List all databases
  • starrocks:///{db}/tables: List tables in a database
  • starrocks:///{db}/{table}/schema: Get table CREATE statement
  • proc:///{path}: Access StarRocks internal system information (similar to Linux /proc)

Caching System

In-memory cache for table overviews using (database_name, table_name) as cache keys. Cache includes both successful results and error messages. Controlled by STARROCKS_OVERVIEW_LIMIT environment variable (default: 20000 characters).

Configuration

Environment variables for database connection:

  • STARROCKS_HOST: Database host (default: localhost)
  • STARROCKS_PORT: MySQL port (default: 9030)
  • STARROCKS_USER: Username (default: root)
  • STARROCKS_PASSWORD: Password (default: empty)
  • STARROCKS_DB: Default database for session
  • STARROCKS_MYSQL_AUTH_PLUGIN: Auth plugin (e.g., mysql_clear_password)
  • STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: Enables Arrow Flight SQL mode
  • MCP_TRANSPORT_MODE: Communication mode (stdio/streamable-http/sse)

Code Patterns

Error Handling

  • Database errors trigger connection reset via reset_connection()
  • All tools return string error messages rather than raising exceptions
  • Cursors are always closed in finally blocks

Security

  • SQL injection prevention through parameterized queries and backtick escaping
  • Plotly expressions are validated using AST parsing to prevent code injection
  • Limited eval() usage with restricted scope for chart generation

Async Patterns

  • Tools are defined as async functions even though database operations are synchronous
  • Main server runs in async context using FastMCP.run_async()

Package Structure

This is a simple Python package built with hatchling:

  • Single module in src/mcp_server_starrocks/
  • Entry point defined in pyproject.toml as mcp-server-starrocks command
  • Dependencies managed through pyproject.toml, no requirements.txt files