Skip to content

user_guide.md

Latest commit

 

History

History
186 lines (145 loc) · 5.27 KB

user_guide.md

File metadata and controls

186 lines (145 loc) · 5.27 KB

🚀 MCP Pinot Server - User Guide

Your MCP Pinot Server is running successfully with dual transport support!

🌐 Server Status

  • ✅ STDIO Transport: Running (for Claude Desktop)
  • ✅ HTTP Transport: Running at http://127.0.0.1:8080
  • ✅ REST API: Available at /api/tools/* endpoints
  • ✅ Pinot Connection: Connected to local quickstart
  • ✅ Tables Found: 10 tables with sample data

📊 Your Pinot Tables

  1. airlineStats - 1,824+ records
  2. dailySales - Sales data
  3. fineFoodReviews - Food review data
  4. githubEvents - GitHub events data
  5. meetupRsvp - Meetup RSVP data
  6. meetupRsvpComplexType - Complex meetup data
  7. meetupRsvpJson - JSON meetup data
  8. upsertJsonMeetupRsvp - Upsert JSON data
  9. upsertMeetupRsvp - Upsert meetup data
  10. upsertPartialMeetupRsvp - Partial upsert data

🔧 How to Query Tables

Method 1: Python Script (No Dependencies)

python3 simple_query_builtin.py

Method 2: Direct curl Commands

List All Tables

curl -X POST http://127.0.0.1:8080/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "list-tables", "arguments": {}}'

Count Records in a Table

curl -X POST http://127.0.0.1:8080/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "read-query", "arguments": {"query": "SELECT COUNT(*) as total FROM airlineStats"}}'

Get Sample Data

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 githubEvents LIMIT 5"}}'

Test Connection

curl -X POST http://127.0.0.1:8080/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "test-connection", "arguments": {}}'

Get Table Details

curl -X POST http://127.0.0.1:8080/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "table-details", "arguments": {"tableName": "airlineStats"}}'

Method 3: Comprehensive Test Script

./test_rest_api.sh

🛠 Available Tools

Tool Description Example
list-tables List all tables {"name": "list-tables", "arguments": {}}
read-query Execute SQL SELECT {"name": "read-query", "arguments": {"query": "SELECT * FROM table LIMIT 5"}}
test-connection Test Pinot connection {"name": "test-connection", "arguments": {}}
table-details Get table size info {"name": "table-details", "arguments": {"tableName": "airlineStats"}}

📈 Sample Queries You Can Try

Basic Queries

-- Count all records
SELECT COUNT(*) FROM airlineStats

-- Get recent GitHub events
SELECT id, type, created_at FROM githubEvents ORDER BY created_at DESC LIMIT 10

-- Analyze meetup data
SELECT COUNT(*) as total_rsvps FROM meetupRsvp

-- Sample airline data
SELECT * FROM airlineStats LIMIT 5

Advanced Queries

-- Group by event type
SELECT type, COUNT(*) as count FROM githubEvents GROUP BY type ORDER BY count DESC LIMIT 5

-- Date-based analysis (if date columns exist)
SELECT DATE_TRUNC('day', created_at) as day, COUNT(*) 
FROM githubEvents 
GROUP BY DATE_TRUNC('day', created_at) 
ORDER BY day DESC LIMIT 7

🌐 API Endpoints

  • GET /api/tools/list - List available tools
  • POST /api/tools/call - Execute tool calls
  • GET /sse - MCP SSE endpoint (for MCP clients)

🎯 Quick Examples

Count Records in All Tables

for table in airlineStats githubEvents meetupRsvp dailySales; do
  echo -n "$table: "
  curl -s -X POST http://127.0.0.1:8080/api/tools/call \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"read-query\", \"arguments\": {\"query\": \"SELECT COUNT(*) as count FROM $table\"}}" \
    | grep -o '"count":[0-9]*' | cut -d':' -f2
done

Get Schema Information

# List all available tools
curl -s http://127.0.0.1:8080/api/tools/list | jq '.tools[].name'

# Test if server is responsive
curl -s -X POST http://127.0.0.1:8080/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "test-connection", "arguments": {}}' | jq '.result.connection_test'

🚀 Integration Options

For Claude Desktop

  • Use the STDIO transport (already running)
  • Configure in Claude Desktop settings

For Web Applications

  • Use the REST API endpoints
  • Base URL: http://127.0.0.1:8080
  • JSON request/response format

For Kubernetes

  • Use the provided k8s manifests in k8s/ directory
  • Supports HTTPS with Ingress

🔍 Troubleshooting

Server Not Responding

# Check if server is running
curl -s http://127.0.0.1:8080/api/tools/list

# Restart server if needed
uv run python examples/http_server_demo.py both

Query Errors

  • Only SELECT queries are allowed for security
  • Table names are case-sensitive
  • Use proper SQL syntax for Pinot

Connection Issues

  • Ensure Pinot quickstart is running (ports 8000, 9000)
  • Check if tables are loaded: curl -s http://localhost:9000/tables

🎉 Success!

Your MCP Pinot Server is working perfectly with:

  • ✅ 10 tables loaded and queryable
  • ✅ REST API returning actual results
  • ✅ Dual transport (STDIO + HTTP)
  • ✅ Production-ready for Kubernetes

You can now query your Pinot data using simple HTTP requests! 🚀