From bb1aa29c039d781023ab6830efc5d68f05f15f40 Mon Sep 17 00:00:00 2001 From: Xiang Fu Date: Mon, 16 Mar 2026 19:24:03 -0700 Subject: [PATCH] Add GitHub Pages documentation site Create a modern, responsive single-page documentation site with dark theme, feature highlights, tools reference, quick start guide, tabbed integration examples, and screenshot gallery. Add GitHub Actions workflow to deploy the site from docs/ and assets/ directories. Co-Authored-By: Claude Opus 4.6 --- .github/workflows/pages.yml | 46 ++ docs/index.html | 1057 +++++++++++++++++++++++++++++++++++ 2 files changed, 1103 insertions(+) create mode 100644 .github/workflows/pages.yml create mode 100644 docs/index.html diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..642484c --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,46 @@ +name: Deploy GitHub Pages + +on: + push: + branches: ["main"] + paths: + - "docs/**" + - "assets/**" + - ".github/workflows/pages.yml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Build site + run: | + mkdir -p _site + cp -r docs/* _site/ + cp -r assets _site/assets + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..a056af1 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,1057 @@ + + + + + + MCP Pinot Server - Model Context Protocol for Apache Pinot + + + + + + + + + + +
+
+ + Production-Ready MCP Server +
+

+ Real-Time Analytics
+ with Apache Pinot + Claude AI +

+

+ A production-grade Model Context Protocol server that connects Claude AI to your Apache Pinot cluster for real-time analytics, metadata queries, and schema management. +

+
+ Get Started + + + View on GitHub + +
+
+ $ + pip install mcp-pinot-server + +
+
+ + +
+
+

Why MCP Pinot?

+

Bridge the gap between conversational AI and real-time OLAP analytics with a secure, production-ready server.

+
+
+
+
🔍
+

15 MCP Tools

+

Query data, list tables, inspect schemas, manage configurations, and more — all through natural language via Claude.

+
+
+
🔒
+

Security First

+

Read-only SQL queries, table-level filtering with glob patterns, OAuth authentication, and TLS/SSL support.

+
+
+
🌐
+

Dual Transport

+

STDIO for Claude Desktop integration and HTTP/SSE for web applications — run both simultaneously.

+
+
+
☸
+

Kubernetes Ready

+

Complete Helm charts and K8s manifests with health checks, autoscaling, and Ingress TLS termination.

+
+
+
⚡
+

REST API

+

Direct HTTP endpoints for tool calls — integrate with any language or framework using simple JSON requests.

+
+
+
🧪
+

Battle Tested

+

45+ tests with comprehensive coverage, async support, structured logging, and graceful error handling.

+
+
+
+ + +
+
+

Available Tools

+

15 MCP tools for querying data, managing schemas, and controlling table configurations.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolDescriptionCategory
test-connectionTest and diagnose Pinot cluster connectivityQuery
read-queryExecute read-only SELECT queries on Pinot tablesQuery
list-tablesList all available tables in the clusterMetadata
table-detailsGet table size and storage informationMetadata
segment-listList all segments for a given tableMetadata
segment-metadata-detailsGet detailed metadata for table segmentsMetadata
index-column-detailsInspect index and column-level informationMetadata
tableconfig-schema-detailsGet combined table config and schemaConfig
get-schemaFetch a schema by nameConfig
create-schemaCreate new schemas with override/force optionsConfig
update-schemaModify existing schemasConfig
get-table-configRetrieve table configurationConfig
create-table-configCreate new table configurationsConfig
update-table-configModify existing table configurationsConfig
reload-table-filtersDynamically reload table access filters without restartingConfig
+
+
+ + +
+
+

Quick Start

+

Get up and running in under 5 minutes.

+
+
+
+
1
+
+

Install uv

+

A fast Python package installer written in Rust.

+
+
Terminal
+ 
curl -LsSf https://astral.sh/uv/install.sh | sh
+
+
+
+
+
2
+
+

Clone & Install

+

Clone the repository and install dependencies.

+
+
Terminal
+ 
git clone https://github.com/startreedata/mcp-pinot.git
+cd mcp-pinot
+uv pip install -e .
+
+
+
+
+
3
+
+

Configure

+

Set up your Pinot cluster connection.

+
+
Terminal
+ 
# Copy the example config
+mv .env.example .env
+
+# Edit with your Pinot cluster details
+# PINOT_CONTROLLER_URL=http://localhost:9000
+# PINOT_BROKER_URL=http://localhost:8000
+
+
+
+
+
4
+
+

Run the Server

+

Start the MCP server with dual transport support.

+
+
Terminal
+ 
uv --directory . run mcp_pinot/server.py
+
+
+
+
+ +
+

Optional: Launch Pinot QuickStart

+

If you don't have a Pinot cluster, start the QuickStart with Docker:

+
+
Terminal
+ 
docker run --name pinot-quickstart \
+  -p 2123:2123 -p 9000:9000 -p 8000:8000 \
+  -d apachepinot/pinot:latest QuickStart -type batch
+
+
+
+ + +
+
+

Integration

+

Connect to Claude Desktop, use HTTP APIs, or deploy on Kubernetes.

+
+ +
+
+ + + + +
+ +
+
+
~/Library/Application Support/Claude/claude_desktop_config.json
+ 
{
+  "mcpServers": {
+    "pinot_mcp": {
+      "command": "/path/to/uv",
+      "args": [
+        "--directory",
+        "/path/to/mcp-pinot",
+        "run",
+        "mcp_pinot/server.py"
+      ]
+    }
+  }
+}
+
+

+ Replace paths with your actual uv and repo locations. Run which uv to find the uv path. + Use STDIO transport for Claude Desktop. +

+
+ +
+
+
Terminal — curl
+ 
# List available tools
+curl -s http://127.0.0.1:8080/api/tools/list | jq
+
+# Execute a query
+curl -X POST http://127.0.0.1:8080/api/tools/call \
+  -H "Content-Type: application/json" \
+  -d '{"name": "read-query", "arguments": {"query": "SELECT * FROM airlineStats LIMIT 5"}}'
+
+# List tables
+curl -X POST http://127.0.0.1:8080/api/tools/call \
+  -H "Content-Type: application/json" \
+  -d '{"name": "list-tables", "arguments": {}}'
+
+
+ +
+
+
Terminal
+ 
# Build the image
+docker build -t mcp-pinot .
+
+# Run with your config
+docker run -v $(pwd)/.env:/app/.env mcp-pinot
+
+
+ +
+
+
Terminal — Helm
+ 
# Deploy with Helm
+helm install mcp-pinot ./helm/mcp-pinot \
+  --set pinot.controllerUrl=http://pinot-controller:9000 \
+  --set pinot.brokerUrl=http://pinot-broker:8000
+
+# Or use kubectl directly
+kubectl apply -f k8s/
+
+
+
+
+ + +
+
+

See It in Action

+

MCP Pinot Server working with Claude AI for real-time data analysis.

+
+
+
+ MCP Pinot fetching metadata from a Pinot cluster +
+ Metadata Exploration +

Ask Claude to explore your Pinot cluster — list tables, inspect schemas, and understand your data model.

+
+
+
+ MCP Pinot analyzing GitHub events data with histogram +
+ Data Analysis & Visualization +

Query data and generate visualizations like histograms, all through natural language prompts.

+
+
+
+
+ + +
+
+

Configuration

+

Fine-tune the server with environment variables.

+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDescriptionDefault
PINOT_CONTROLLER_URLPinot controller endpointhttp://localhost:9000
PINOT_BROKER_URLPinot broker endpointhttp://localhost:8000
MCP_TRANSPORTTransport mode: stdio, http, or bothhttp
MCP_HOSTHTTP bind address0.0.0.0
MCP_PORTHTTP port8080
MCP_SSL_CERTFILEPath to SSL certificate for HTTPS—
MCP_SSL_KEYFILEPath to SSL private key—
PINOT_TABLE_FILTER_FILEYAML file for table filtering—
OAUTH_ENABLEDEnable OAuth authenticationfalse
PINOT_USE_MSQEEnable multi-stage query enginefalse
+
+

+ See the full configuration guide for all available options including OAuth, table filtering, and timeout settings. +

+
+
+ + + + + + + +