StarTree MCP Server for Apache Pinot

Instructions

Implementation Reference

• mcp_pinot/server.py:100-110 (handler)

  MCP tool handler for 'index-column-details'. This function is decorated with @mcp.tool (FastMCP registration) and delegates to PinotClient.get_index_column_detail, returning JSON results.

  @mcp.tool
  def index_column_details(tableName: str, segmentName: str) -> str:
      """Get index/column details for a segment"""
      try:
          results = pinot_client.get_index_column_detail(
              tableName=tableName,
              segmentName=segmentName,
          )
          return json.dumps(results, indent=2)
      except Exception as e:
          return f"Error: {str(e)}"

• mcp_pinot/pinot_client.py:351-373 (helper)

  Core implementation logic in PinotClient that fetches segment metadata details (with columns=*) via HTTP to Pinot controller endpoints for both REALTIME and OFFLINE table types.

  def get_index_column_detail(
      self,
      tableName: str,
      segmentName: str,
      params: dict[str, Any] | None = None,
  ) -> dict[str, Any]:
      for type_suffix in ["REALTIME", "OFFLINE"]:
          endpoint = PinotEndpoints.SEGMENT_DETAIL.format(
              tableName, type_suffix, segmentName
          )
          url = f"{self.config.controller_url}/{endpoint}"
          logger.debug(f"Trying to fetch index column details from: {url}")
          try:
              response = self.http_request(url)
              return response.json()
          except Exception as e:
              error_msg = (
                  f"Failed to fetch index column details for "
                  f"{tableName}_{type_suffix}/{segmentName}: {e}"
              )
              logger.error(error_msg)
              continue
      raise ValueError("Index column detail not found")

• mcp_pinot/pinot_client.py:34-42 (helper)

  Defines the SEGMENT_DETAIL endpoint pattern used: 'segments/{}_{}/{}/metadata?columns=*' for fetching column details.

  class PinotEndpoints:
      QUERY_SQL = "query/sql"
      TABLES = "tables"
      SCHEMAS = "schemas"
      TABLE_SIZE = "tables/{}/size"
      SEGMENTS = "segments/{}"
      SEGMENT_METADATA = "segments/{}/metadata"
      SEGMENT_DETAIL = "segments/{}_{}/{}/metadata?columns=*"
      TABLE_CONFIG = "tableConfigs/{}"

• mcp_pinot/server.py:101-102 (schema)

  Input schema defined by type hints: tableName (str), segmentName (str) -> str (JSON output).

  def index_column_details(tableName: str, segmentName: str) -> str:
      """Get index/column details for a segment"""

• mcp_pinot/prompts.py:35-35 (helper)

  Tool description in prompt template for the AI assistant.

  5. index-column-details: Get index details for a specific column in a table