QueryMaster MCP

Natural language database querying powered by Archestra and the Model Context Protocol.

2 Fast 2 MCP Hackathon Entry | Built on Archestra

Ask questions in plain English. Get SQL results instantly. Visualize your schema. All secured by Archestra.

Demo here: https://youtu.be/cCExnJntogk

---

What It Does

QueryMaster lets anyone query a PostgreSQL database using plain English. No SQL knowledge required.

User: "Show me the top 10 customers by total spend"

QueryMaster:
  1. Calls introspect_schema -> understands tables & relationships
  2. Generates SQL -> SELECT c.name, SUM(o.total) ...
  3. Executes safely -> read-only, timeout-protected
  4. Returns formatted results with insights

Architecture

User (natural language) --> Archestra Chat UI --> QueryMaster Agent
                                                      |
                                          MCP Gateway (secure)
                                                      |
                                          QueryMaster MCP Server
                                           /    |    |    \    \
                               introspect  query explain list  visualize
                                  _schema  _db   _results _dbs  _schema
                                                      |
                                                  PostgreSQL

QueryMaster is a single, focused MCP server deployed through Archestra's Kubernetes orchestrator. The LLM agent (running in Archestra) decides which tools to call and in what order -- the MCP server just provides the capabilities.

MCP Tools (5)

Tool	Description
introspect_schema	Discovers tables, columns, types, foreign keys, and sample data
query_database	Executes safe, read-only SQL queries with timeout and row limits
explain_results	Analyzes query performance with PostgreSQL EXPLAIN and optimization tips
list_databases	Shows configured database connections and their status
visualize_schema	Generates Mermaid ER diagrams for visual schema exploration

Safety Features

Server-Side (QueryMaster MCP)

• Read-only enforcement: Only SELECT/WITH queries allowed. INSERT, UPDATE, DELETE, DROP, and all other mutations are blocked at parse time.
• Statement timeout: Queries that run too long are automatically killed (default: 30s).
• Row limit: Results capped at 1,000 rows to prevent memory issues.
• Single statement: Multi-statement queries (SQL injection attempts) are rejected.
• No credential exposure: Database URLs are stored as K8s secrets, never returned to the LLM.

Platform-Side (Archestra)

• Tool invocation policies: Archestra's dual-LLM security blocks untrusted contexts from executing queries.
• Cost limits: Token usage caps prevent runaway LLM costs.
• Audit logging: Every tool call is logged with full context for compliance.
• MCP Gateway auth: Bearer token / OAuth 2.1 authentication on the gateway.

How Archestra Is Used

This project deeply leverages Archestra's platform capabilities:

1. MCP Catalog & Registry -- QueryMaster is registered as a reusable MCP server that any team can install with their own DATABASE_URL.
2. Kubernetes Orchestrator -- The MCP server runs as a K8s Deployment managed by Archestra's orchestrator, with automatic secret management.
3. Streamable HTTP Transport -- Production-grade HTTP transport with session management, not just stdio.
4. Chat UI -- Zero frontend code needed. Archestra provides the ChatGPT-style interface.
5. Security Policies -- Tool invocation policies and trusted data evaluation protect against prompt injection.
6. Cost Controls -- Token limits and usage tracking per agent.
7. Observability -- Tool call logs, execution metrics, and traces via Archestra's built-in monitoring.

Quick Start

Prerequisites

• Archestra running locally (tilt up)
• Docker Desktop with Kubernetes enabled
• Node.js 20+

1. Start the Demo Database

cd querymaster-mcp
docker compose up -d postgres-demo

This starts PostgreSQL with a pre-seeded e-commerce dataset (6 tables, 512 rows).

2. Build the Docker Image

npm install
npm run build
docker build -t querymaster-mcp:latest .

3. Register in Archestra

In the Archestra UI (http://localhost:3000):

1. Go to MCP Registry > Add the querymaster-mcp catalog entry
2. Install with DATABASE_URL: postgresql://querymaster:querymaster_dev@host.docker.internal:5433/querymaster_demo
3. Create an agent, assign all 5 QueryMaster tools
4. Set the system prompt (see system-prompt.md)
5. Chat!

Demo Queries to Try

"How many tables are in the database?"
"Show me the top 10 customers by total spend"
"Which product categories have the highest revenue?"
"What's the average order value per month in 2025?"
"Show me products with an average rating below 4"
"Compare revenue across countries"
"Visualize the database schema"
"Explain the performance of: SELECT * FROM orders JOIN customers ON ..."

Tech Stack

• Runtime: Node.js 20, TypeScript
• MCP SDK: @modelcontextprotocol/sdk v1.26+
• Transport: Streamable HTTP (port 8080)
• Database: PostgreSQL via pg driver
• Container: Archestra MCP Server Base Image
• Orchestration: Archestra + Kubernetes

Project Structure

querymaster-mcp/
  src/
    index.ts                  # MCP server entry (streamable-http)
    config.ts                 # Environment configuration
    tools/
      introspect-schema.ts    # Schema discovery tool
      query-database.ts       # Safe SQL execution
      explain-results.ts      # EXPLAIN ANALYZE tool
      list-databases.ts       # Database listing
      visualize-schema.ts     # Mermaid ER diagram generator
    db/
      connection.ts           # PostgreSQL connection pool
      safety.ts               # SQL validation (read-only enforcement)
  seed/
    init.sql                  # E-commerce demo dataset
  Dockerfile                  # Based on Archestra MCP base image
  docker-compose.yml          # Local dev database

License

MIT