Apache Pinot MCP Server

Preview or create a new Pinot schema without replacing an existing schema. The default preview performs strict local structural validation and returns a short-lived confirmation token bound to the exact normalized schema. Pass that token with ``dry_run=false`` to apply. Replacement belongs in ``update_schema``. Failure recovery: Invalid JSON, missing ``schemaName``, and controller validation failures are non-retryable until corrected. Permission failures require access changes; retry transient controller failures only after connectivity is restored.

Create a new Pinot table configuration. Accepts a typed table-config object. The default ``dry_run=true`` asks Pinot to validate the payload and returns a confirmation token without applying. Failure recovery: Invalid JSON, missing ``tableName``, and controller validation failures need a corrected payload; do not retry unchanged. Fix access failures first, and retry transient controller errors after connectivity is restored.

Get one Pinot schema, including dimensions, metrics, time, and primary keys. This is a single-object lookup, not a list, so pagination does not apply. The output preserves additional fields introduced by the connected Pinot version. Failure recovery: For not-found errors, pass the table's exact schema name (normally the table name without a type suffix). Fix permissions before retrying; retry transient controller failures after ``test_connection`` succeeds.

Get per-column index metadata for ONE segment (which indexes each column has). Use this to inspect how a specific segment is indexed (inverted, sorted, range, etc.). Requires a ``segment_name`` from ``list_segments``. For a segment's row count/size/time boundaries use ``list_segment_metadata``; for the table's declared index *configuration* (not per-segment state) use ``get_table_config``. Failure recovery: A missing segment is non-retryable with the same value; refresh ``list_segments`` and use an exact returned name. Retry transient controller errors after ``test_connection`` succeeds.

Get one table's indexing, retention, tenant, and ingestion configuration. This is a single-object lookup, not a list, so pagination does not apply. Set ``table_type`` only when one side of a hybrid table is needed. Failure recovery: For not-found errors, use an exact name from ``list_tables`` and a valid table type. Fix permissions before retrying; retry transient controller failures after ``test_connection`` succeeds.

Get a table's storage footprint: reported vs. estimated size in bytes. Use this for capacity/size questions about a whole table. It does NOT list segments (use ``list_segments``) or return row counts/time boundaries (use ``list_segment_metadata``). ``reportedSizeInBytes`` is what the servers currently hosting the segments report; ``estimatedSizeInBytes`` assumes every replica is present. Failure recovery: For not-found errors, copy an exact name from ``list_tables``. Fix permission errors before retrying; retry transient controller failures after a health check.

Get a deterministic page of segment rows, sizes, and time boundaries. Pinot can return thousands of segment objects. Results are sorted by exact segment name, then sliced with ``limit``/``offset``; follow ``has_more`` until false. Use ``list_segments`` when only names are needed. Failure recovery: An empty page is success. For not-found errors, use ``list_tables``; correct permissions before retrying, and retry transient server failures only after ``test_connection`` succeeds.

List a table's segment names, grouped by table type (OFFLINE/REALTIME). Use this to discover segment names — e.g. to get a ``segment_name`` for ``get_segment_index_metadata``, or to see how a table is partitioned. For per-segment row counts / sizes / time boundaries call ``list_segment_metadata`` instead; for total storage call ``get_table_size``. Segment names are paginated (a busy table can have thousands) — use ``limit``/``offset`` and the ``has_more`` flag to page through them. Failure recovery: An empty page is success. For not-found errors, use an exact name from ``list_tables``; correct access errors, or retry transient controller errors.

List Pinot tables visible to this server (subject to table filters). Returns a paginated list of table names. Use ``limit``/``offset`` and the ``has_more`` flag to page through clusters with many tables. Failure recovery: An empty page is success. For authentication/connectivity errors, verify the controller with ``test_connection`` and retry after access is restored.

Run a read-only SQL query against Pinot and return a page of rows. Only a single SELECT (or WITH ... SELECT) statement is allowed; the query is rejected if it contains multiple statements or write/DDL/admin keywords. Results are paginated to keep responses small — use ``limit``/``offset`` and the ``has_more`` flag to page through large result sets. Returns ``QueryResult`` with the page of rows, the column list, fetched row count, and a ``has_more`` flag. Failure recovery: SQL/allow-list/permission failures require correcting the query or access; do not retry unchanged. A timeout or connection failure can be retried after ``test_connection`` succeeds. Zero rows is a successful result.

Preview or apply the configured table-filter YAML without restarting. Reads only the path configured by ``PINOT_TABLE_FILTER_FILE``. The YAML must be an object whose ``included_tables`` value is a non-empty list of glob strings. Allowing every table requires an explicit ``allow_all: true``. The default ``dry_run=true`` validates and reports the before/after patterns and returns a short-lived confirmation token. Pass ``dry_run=false`` with that token to apply the exact candidate atomically. Editing the file after preview invalidates the confirmation and requires another preview. Returns: Preview/application status, whether it was applied, old/new patterns, and a confirmation token on previews. Failure recovery: A missing setting/file or malformed YAML is non-retryable until corrected; fix ``PINOT_TABLE_FILTER_FILE`` or its ``included_tables`` list, then retry.

Probe Pinot connectivity and return diagnostics. Runs three checks — broker connection, a trivial ``SELECT 1`` query, and a controller table listing — and reports which succeeded plus a small sample of tables. Useful for troubleshooting configuration before using other tools. Failure recovery: Individual check failures are returned in ``error``. Verify the broker and controller URLs, credentials, and network, then retry only failed checks.

Update an existing Pinot schema. Accepts a typed schema object. This can change column definitions on a live table; the default ``dry_run=true`` previews without applying and returns a confirmation token bound to the exact replacement. Failure recovery: Invalid JSON/name or schema validation failures require a corrected payload; do not retry unchanged. Fix permission errors first, and retry transient controller failures only after connectivity is restored.

Update an existing Pinot table configuration. Accepts a typed replacement table-config object. This changes a live table; the default ``dry_run=true`` asks Pinot to validate it, compares it with the current configuration, and returns a token without applying. Failure recovery: Invalid JSON/name or controller validation failures require a corrected payload; do not retry unchanged. Fix access errors first, and retry transient controller failures only after connectivity is restored.