mcp-server-starrocks

# 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:**
```bash
# 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:**
```bash
# 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