From be675d4165bba3ba2eb08b0f1ae98fa9f0e30f28 Mon Sep 17 00:00:00 2001
From: Rene Cannao <rene@proxysql.com>
Date: Sun, 18 Jan 2026 23:17:14 +0000
Subject: [PATCH] wip: Add interactive MCP query agent demo script using Claude
 Code

Add demo_agent_claude.sh script for demonstrating the MCP query
agent workflow with Claude Code interactive sessions.

The script:
- Configures MCP connection via proxysql_mcp_stdio_bridge.py
- Sets up system prompt with agent workflow instructions
- Demonstrates step-by-step query answering process

Note: Script highlights current implementation gaps that need
to be addressed before full functionality.
---
 scripts/mcp/demo_agent_claude.sh | 156 +++++++++++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100755 scripts/mcp/demo_agent_claude.sh

diff --git a/scripts/mcp/demo_agent_claude.sh b/scripts/mcp/demo_agent_claude.sh
new file mode 100755
index 000000000..86f1db4c3
--- /dev/null
+++ b/scripts/mcp/demo_agent_claude.sh
@@ -0,0 +1,156 @@
+#!/bin/bash
+#
+# Interactive MCP Query Agent Demo using Claude Code
+#
+# Usage: ./demo_agent_claude.sh <schema_name>
+#
+# Example: ./demo_agent_claude.sh Chinook
+#
+
+set -e
+
+SCHEMA="${1:-Chinook}"
+MCP_CATALOG_DB="/home/rene/proxysql-vec/src/mcp_catalog.db"
+
+# Check if catalog exists
+if [ ! -f "$MCP_CATALOG_DB" ]; then
+    echo "Error: MCP catalog database not found at $MCP_CATALOG_DB"
+    echo "Please run two-phase discovery first."
+    exit 1
+fi
+
+# System prompt for Claude Code
+SYSTEM_PROMPT="You are an intelligent SQL Query Agent for the '${SCHEMA}' database schema. You have access to a Model Context Protocol (MCP) server that provides tools for database discovery and query generation.
+
+## Available MCP Tools
+
+You have access to these MCP tools (use mcp__proxysql-stdio__ prefix):
+
+1. **llm_search** - Search for similar pre-defined queries and LLM artifacts
+   - Parameters: run_id (schema name), query (search terms), limit
+   - Returns: List of matching question templates, metrics, notes with scores
+   - Use this FIRST when user asks a question
+
+2. **catalog_list_objects** - List all tables/views in the schema
+   - Parameters: run_id, page_size
+   - Returns: Tables with row counts, sizes, etc.
+
+3. **catalog_get_object** - Get detailed schema for a specific table
+   - Parameters: run_id, schema_name, object_name
+   - Returns: Columns, indexes, foreign keys
+
+4. **run_sql_readonly** - Execute a read-only SQL query
+   - Parameters: sql (the query to execute)
+   - Returns: Query results
+
+## Your Workflow - Show Step by Step
+
+When a user asks a natural language question, follow these steps **explicitly**:
+
+### Step 1: Search for Similar Queries
+\`\`\`
+I'll search for similar pre-defined queries in the catalog...
+[Call llm_search with the user's question keywords]
+\`\`\`
+
+### Step 2: Analyze Results
+\`\`\`
+Found X matches:
+- Match 1: [title] (score: X.XX) - [body/description]
+- Match 2: ...
+
+[Explain if you found a close match or need to generate new query]
+\`\`\`
+
+### Step 3: Get Schema Details (if needed)
+\`\`\`
+Since I need to understand the table structure...
+[Call catalog_get_object for relevant tables]
+\`\`\`
+
+### Step 4: Execute Query
+\`\`\`
+Now I'll execute the query...
+[Call run_sql_readonly with the SQL]
+\`\`\`
+
+### Step 5: Present Results
+\`\`\`
+Here are the results:
+[Format the results nicely]
+\`\`\`
+
+## Important Notes
+
+- **Always show your work** - Explain each step you're taking
+- **Use llm_search first** - Reuse existing queries when possible
+- **Score interpretation**: Lower scores = better match (< -3.0 is good)
+- **If no good match**: Generate SQL from scratch using catalog schema
+- **run_id**: Always use '${SCHEMA}' as the run_id
+
+## Example Interaction
+
+User: \"What are the most expensive tracks?\"
+
+Your response:
+Step 1: Search for similar queries...
+[llm_search call]
+Step 2: Found match: \"Most Expensive Tracks\" (score: -0.66)
+Step 3: Execute the query...
+[run_sql_readonly call]
+Step 4: Results: [table of tracks]
+
+---
+
+Ready to help! Ask me anything about the ${SCHEMA} database."
+
+echo "=========================================="
+echo "  MCP Query Agent Demo - Schema: ${SCHEMA}"
+echo "=========================================="
+echo ""
+echo "Starting Claude Code with MCP tools enabled..."
+echo ""
+
+# Get script directory to find paths
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Create MCP config
+MCP_CONFIG_FILE=$(mktemp)
+cat > "$MCP_CONFIG_FILE" << EOF
+{
+  "mcpServers": {
+    "proxysql": {
+      "command": "python3",
+      "args": ["$SCRIPT_DIR/proxysql_mcp_stdio_bridge.py"],
+      "env": {
+        "PROXYSQL_MCP_ENDPOINT": "https://127.0.0.1:6071/mcp/query",
+        "PROXYSQL_MCP_TOKEN": "",
+        "PROXYSQL_MCP_INSECURE_SSL": "1"
+      }
+    }
+  }
+}
+EOF
+
+# Create append prompt (initial task)
+APPEND_PROMPT="
+
+---
+
+INITIAL REQUEST: Show me how you would answer the question: \"What are the most expensive tracks?\"
+
+Please walk through each step explicitly, showing:
+1. The llm_search call and results
+2. How you interpret the results
+3. The final SQL execution
+4. The formatted results
+
+This is a demonstration, so be very verbose about your process."
+
+# Start Claude Code with the MCP config
+claude --mcp-config "$MCP_CONFIG_FILE" \
+    --system-prompt "$SYSTEM_PROMPT" \
+    --append-system-prompt "$APPEND_PROMPT"
+
+# Cleanup
+rm -f "$MCP_CONFIG_FILE"