NL Analytics MCP Server for Apache Druid

# # Copyright (C) 2025 Christian Schmitt, Tim Frey # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # # MCP Prompt Templates Configuration mcp.prompts.enabled=true mcp.prompts.watermark=Generated by Druid MCP Server v${spring.ai.mcp.server.version} | Contact: contact@iunera.com | Website: https://www.iunera.com/ # Default prompt configurations mcp.prompts.data-exploration.enabled=true mcp.prompts.query-optimization.enabled=true mcp.prompts.health-check.enabled=true mcp.prompts.cluster-overview.enabled=true mcp.prompts.ingestion-troubleshooting.enabled=true mcp.prompts.ingestion-setup.enabled=true mcp.prompts.retention-management.enabled=true mcp.prompts.compaction-optimization.enabled=true mcp.prompts.emergency-response.enabled=true mcp.prompts.maintenance-mode.enabled=true # Prompt customization mcp.prompts.custom.organization-name=Iunera GmbH & Co KG mcp.prompts.custom.environment=${ENVIRONMENT:production} mcp.prompts.custom.contact-info=contact@iunera.com | Website: https://www.iunera.com/ # ======================================== # PROMPT TEMPLATES # ======================================== # All prompt templates used by MCP prompt providers # These can be overridden using Java system properties with -D flags # Data Analysis Prompts prompts.druid-data-exploration.template=I need to explore data in the Druid cluster. Please help me:\n\n\ 1. First, list all available datasources with their column information\n\ {datasource_section}\ 3. Show me the schema and data types for the columns\n\ 4. Suggest some useful analytical queries I could run\n\ 5. Provide sample queries for common patterns like time-series analysis, aggregations, and filtering\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\n\ {watermark} prompts.druid-data-exploration.datasource-section=2. Focus on the datasource: {datasource}\n prompts.druid-query-optimization.template=I have a Druid SQL query that needs optimization:\n\n\ Query: {query}\n\n\ Please help me:\n\ 1. Analyze the query structure and identify potential performance issues\n\ 2. Suggest optimizations for better performance\n\ 3. Recommend appropriate indexing strategies if needed\n\ 4. Show me how to use multi-stage query engine if beneficial\n\ 5. Provide the optimized version of the query\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ {watermark} # Data Management Prompts prompts.druid-retention-management.template=I need to manage data retention policies. Please help me:\n\n\ {datasource_section}\ 2. Analyze current data storage and age distribution\n\ 3. Recommend optimal retention policies based on usage patterns\n\ 4. Calculate storage savings from proposed changes\n\ 5. Provide step-by-step instructions to update retention rules\n\ 6. Set up monitoring for retention policy effectiveness\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ {watermark} prompts.druid-retention-management.datasource-section-specific=1. Review retention rules for datasource: {datasource}\n prompts.druid-retention-management.datasource-section-all=1. Show retention rules for all datasources\n prompts.druid-compaction-optimization.template=I want to optimize segment compaction for better query performance:\n\n\ {datasource_section}\ 2. Check current segment sizes and distribution\n\ 3. Identify datasources that would benefit from compaction\n\ 4. Recommend optimal compaction configurations\n\ 5. Provide compaction configuration updates\n\ 6. Estimate performance improvements and storage savings\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ {watermark} prompts.druid-compaction-optimization.datasource-section-specific=1. Analyze compaction status for: {datasource}\n prompts.druid-compaction-optimization.datasource-section-all=1. Review compaction across all datasources\n # Compaction Prompts prompts.druid-compaction-suggestions.template=# Apache Druid Compaction Configuration Suggestions\n\n\ I need expert guidance on optimizing compaction configuration based on Apache Druid best practices.\n\n\ ## Current Context:\n\ {context_section}\ - **Environment**: {environment}\n\n\ ## Please help me with the following analysis:\n\n\ ### 1. Current State Assessment\n\ - Analyze current segment sizes and distribution\n\ - Check segment count per time chunk\n\ - Review current compaction configuration status\n\ - Identify segments that are too small (< 300-700MB) or too large (> 1GB)\n\n\ ### 2. Apache Druid Best Practice Recommendations\n\ **Segment Size Optimization:**\n\ - Target segment size: 300-700MB (optimal for most use cases)\n\ - For high-cardinality data: Consider smaller segments (200-500MB)\n\ - For time-series data: Larger segments acceptable (500MB-1GB)\n\n\ **Row Count Guidelines:**\n\ - Target 5-10 million rows per segment for balanced performance\n\ - Adjust based on row size and query patterns\n\ - Consider maxRowsPerSegment configuration\n\n\ **Partitioning Strategy:**\n\ - Use appropriate time granularity (HOUR, DAY, WEEK)\n\ - Consider secondary partitioning for high-cardinality dimensions\n\ - Evaluate hash vs range partitioning based on query patterns\n\n\ ### 3. Configuration Parameters Analysis\n\ **Core Settings:**\n\ - `inputSegmentSizeBytes`: Minimum segment size to trigger compaction\n\ - `maxRowsPerSegment`: Balance between segment size and query performance\n\ - `skipOffsetFromLatest`: Skip recent data to avoid compacting actively written segments\n\ - `taskPriority`: Set appropriate priority (25 for low, 50 for normal, 75 for high)\n\n\ **Tuning Configuration:**\n\ - `maxNumConcurrentSubTasks`: Parallel processing (typically 1-4)\n\ - `splitHintSpec`: Control how input segments are split\n\ - `partitionsSpec`: Define output partitioning strategy\n\ - `indexSpec`: Compression and encoding settings\n\n\ **Resource Management:**\n\ - Task context settings for memory allocation\n\ - Appropriate worker selection and resource limits\n\ - Scheduling considerations for production workloads\n\n\ ### 4. Performance Impact Estimation\n\ - Query performance improvements expected\n\ - Storage space optimization potential\n\ - Compaction task resource requirements\n\ - Timeline for compaction completion\n\n\ ### 5. Implementation Strategy\n\ - Phased rollout approach for multiple datasources\n\ - Monitoring and validation steps\n\ - Rollback procedures if needed\n\ - Production deployment best practices\n\n\ ### 6. Monitoring and Maintenance\n\ - Key metrics to monitor post-compaction\n\ - Automated compaction health checks\n\ - Regular review and adjustment procedures\n\ - Alert configuration for compaction failures\n\n\ ---\n\ **Environment**: {environment}\n\ **Organization**: {organizationName}\n\ **Contact**: {contactInfo}\n\n\ *{watermark}*\n\n\ Please provide specific configuration recommendations based on the current state analysis and Apache Druid best practices. prompts.druid-compaction-suggestions.context-datasource=- **Target Datasource**: {datasource}\n prompts.druid-compaction-suggestions.context-all-datasources=- **Scope**: All datasources in cluster\n prompts.druid-compaction-suggestions.context-query-patterns=- **Query Patterns**: {queryPatterns}\n prompts.druid-compaction-suggestions.context-data-volume=- **Data Volume**: {dataVolume}\n prompts.druid-compaction-troubleshooting.template=# Druid Compaction Troubleshooting & Optimization\n\n\ I need help troubleshooting and optimizing compaction performance issues.\n\n\ ## Issue Context:\n\ {context_section}\ - **Environment**: {environment}\n\n\ ## Please help me diagnose and resolve:\n\n\ ### 1. Common Compaction Issues Diagnosis\n\ **Task Failures:**\n\ - Check for out-of-memory errors in compaction tasks\n\ - Analyze task logs for specific error patterns\n\ - Verify resource allocation and limits\n\n\ **Performance Issues:**\n\ - Slow compaction task execution\n\ - High resource consumption during compaction\n\ - Compaction tasks getting stuck or hanging\n\n\ **Configuration Problems:**\n\ - Inappropriate segment size targets\n\ - Incorrect partitioning specifications\n\ - Suboptimal tuning parameters\n\n\ ### 2. Apache Druid Troubleshooting Best Practices\n\ **Resource Optimization:**\n\ - Adjust heap size based on segment size and complexity\n\ - Optimize direct memory allocation\n\ - Configure appropriate number of concurrent subtasks\n\n\ **Segment Analysis:**\n\ - Identify segments causing compaction bottlenecks\n\ - Check for data skew or unusual segment characteristics\n\ - Analyze input segment distribution and sizes\n\n\ **Configuration Tuning:**\n\ - Review and optimize inputSegmentSizeBytes threshold\n\ - Adjust maxRowsPerSegment based on data characteristics\n\ - Fine-tune skipOffsetFromLatest for active ingestion\n\n\ ### 3. Performance Optimization Strategies\n\ - Parallel processing optimization\n\ - Memory usage optimization\n\ - I/O and network optimization\n\ - Scheduling and resource management\n\n\ ### 4. Monitoring and Alerting Setup\n\ - Key metrics for compaction health monitoring\n\ - Alert thresholds and notification setup\n\ - Dashboard configuration for compaction visibility\n\n\ ### 5. Resolution Steps\n\ - Immediate actions to resolve current issues\n\ - Long-term optimization recommendations\n\ - Prevention strategies for future issues\n\n\ ---\n\ **Environment**: {environment}\n\ **Organization**: {organizationName}\n\ **Contact**: {contactInfo}\n\n\ *{watermark}*\n\n\ Please provide specific troubleshooting steps and optimization recommendations based on Apache Druid best practices. prompts.druid-compaction-troubleshooting.context-issue=- **Issue Description**: {issueDescription}\n prompts.druid-compaction-troubleshooting.context-datasource=- **Affected Datasource**: {datasource}\n # Ingestion Management Prompts prompts.druid-ingestion-troubleshooting.template=I'm experiencing data ingestion issues. Please help me troubleshoot:\n\n\ 1. List all supervisors and their current status\n\ {supervisor_section}\ 3. Check for any failed or problematic supervisors\n\ 4. Review recent tasks and their status\n\ 5. Identify any error patterns or common issues\n\ 6. Provide step-by-step troubleshooting recommendations\n\ 7. Suggest corrective actions for any problems found\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ {watermark} prompts.druid-ingestion-troubleshooting.supervisor-section=2. Focus on supervisor: {supervisorId}\n prompts.druid-ingestion-setup.template=I want to set up data ingestion for a new datasource. Please guide me through:\n\n\ {data_source_section}\ {datasource_name_section}\ 3. Create an appropriate ingestion specification\n\ 4. Configure the supervisor settings\n\ 5. Set up proper schema and data mapping\n\ 6. Recommend retention and compaction policies\n\ 7. Provide monitoring and validation steps\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ {watermark} prompts.druid-ingestion-setup.data-source-section-specific=1. **Data Source**: {dataSource}\n prompts.druid-ingestion-setup.data-source-section-help=1. **Data Source**: Help me identify the best ingestion method\n prompts.druid-ingestion-setup.datasource-name-section-specific=2. **Datasource Name**: {datasourceName}\n prompts.druid-ingestion-setup.datasource-name-section-suggest=2. **Datasource Name**: Suggest naming conventions\n # Cluster Management Prompts prompts.druid-health-check.template=Please perform a comprehensive health check of the Druid cluster:\n\n\ 1. Check overall cluster health status\n\ 2. Verify coordinator and router health\n\ 3. Check all server statuses with details\n\ 4. Identify the current leader and verify leadership status\n\ 5. Review cluster metadata and configuration\n\ 6. Highlight any issues or warnings that need attention\n\ 7. Provide recommendations for any problems found\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ {watermark} prompts.druid-cluster-overview.template=I need a complete overview of my Druid cluster. Please provide:\n\n\ 1. **Cluster Health**: Overall status and any alerts\n\ 2. **Datasources**: List all datasources with their key metrics\n\ 3. **Ingestion Status**: Current supervisors and their states\n\ 4. **Tasks**: Active and recent tasks overview\n\ 5. **Segments**: Segment distribution and health\n\ 6. **Configuration**: Key cluster settings and properties\n\ 7. **Recommendations**: Any optimization suggestions\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ {watermark} # Operational Prompts prompts.druid-emergency-response.template=There's an urgent issue with the Druid cluster. Please help me with emergency response:\n\n\ 1. **Immediate Assessment**: Check cluster health and identify critical issues\n\ 2. **Impact Analysis**: Determine which services/datasources are affected\n\ 3. **Quick Fixes**: Provide immediate actions to stabilize the cluster\n\ 4. **Supervisor Management**: Suspend problematic supervisors if needed\n\ 5. **Task Management**: Kill stuck or problematic tasks\n\ 6. **Monitoring**: Set up enhanced monitoring during recovery\n\ 7. **Recovery Plan**: Step-by-step recovery procedures\n\ 8. **Prevention**: Recommendations to prevent similar issues\n\n\ **URGENT - Environment: {environment}**\n\ Organization: {organizationName}\n\ Emergency Contact: {contactInfo}\n\n\ {watermark} prompts.druid-maintenance-mode.template=I need to perform maintenance on the Druid cluster. Please help me:\n\n\ 1. **Pre-maintenance checklist**: Verify cluster stability\n\ 2. **Graceful shutdown**: Suspend supervisors and complete running tasks\n\ 3. **Data safety**: Ensure all data is properly persisted\n\ 4. **Backup verification**: Confirm backup status and integrity\n\ 5. **Maintenance window**: Estimate required downtime\n\ 6. **Post-maintenance**: Verification and restart procedures\n\ 7. **Rollback plan**: Emergency rollback procedures if needed\n\n\ Environment: {environment}\n\ Organization: {organizationName}\n\ Contact: {contactInfo}\n\n\ **MAINTENANCE OPERATION - PROCEED WITH CAUTION**\n\n\ {watermark}