Maverick MCP Server

Maverick MCP Server

An MCP (Model Context Protocol) server for managing Maverick sites through Amazon Q CLI with comprehensive Kubernetes debugging capabilities. Now fully consolidated into a single, optimized server.py file for better performance and timeout prevention.

🆕 Recent Updates

API Endpoint & Authentication Updates:

• ✅ Fixed API endpoint structure: Now uses /suite/webapi/sites as base URL
• ✅ Updated authentication headers: Uses appian-api-key header format
• ✅ Enhanced dry-run support: Proper dryRun=true parameter handling
• ✅ Improved error handling: Better API response parsing and error messages

Features

• Create Sites: Create new Maverick sites with comprehensive configuration options
• Query Sites: Search and filter sites using various criteria
• Get Site Details: Retrieve detailed information about specific sites
• Site Management: Start, stop, restart, delete, edit, clone, move, and resize sites
• 🆕 Kubernetes Debugging: Comprehensive troubleshooting tools for Appian site startup issues
• 🆕 Pod Monitoring: Check pod status and health in site namespaces
• 🆕 Operator Health: Monitor Appian and Site-Worker-Group operators
• 🆕 Log Analysis: Retrieve and analyze pod logs for troubleshooting
• ⚡ Performance Optimized: Consolidated architecture with timeout protection to prevent hanging

Installation

1. Install the package:

2. Test the installation:

3. Set up environment variables:

Configuration for Amazon Q CLI

Add to your Q CLI MCP configuration file at ~/.aws/amazonq/mcp.json:

Note: Use the full path to your server.py file in the configuration.

Available Tools

Site Management Tools

1. maverick___create_site

Creates a new Maverick site with specified configuration.

2. maverick___query_sites

Query sites using various filters and criteria.

3. maverick___get_site_by_id

Get detailed information about a specific site.

4. maverick___manage_site

Perform various actions on existing Maverick sites.

5. maverick___get_site_resize_status

Check the status of an ongoing site resize operation.

🆕 Kubernetes Debugging Tools

6. maverick___debug_site_startup

Comprehensive site startup debugging workflow

Performs a complete diagnostic check following the Appian troubleshooting methodology:

1. Checks SWG Custom Resource in default namespace
2. Verifies Site-Worker-Group operator health
3. Confirms site namespace existence
4. Examines Appian Custom Resource status
5. Validates Appian operator functionality
6. Analyzes site pod status
7. Focuses on critical webapp pod
8. Provides actionable recommendations

Parameters:

• siteId: Site ID (numeric) - becomes the Kubernetes namespace
• kubeconfig: Path to kubeconfig file (optional)
• context: Kubernetes context to use (optional)
• detailed: Include detailed logs and descriptions (default: true)

7. maverick___check_site_pods

Check pod status in site namespace

Analyzes all pods in a site's Kubernetes namespace and identifies issues:

• Shows pod status, readiness, and restart counts
• Identifies problematic pods (not Running/Completed)
• Provides detailed information about failed pods
• Checks critical Appian components status
• Offers troubleshooting recommendations

Parameters:

• siteId: Site ID (numeric)
• kubeconfig: Path to kubeconfig file (optional)
• context: Kubernetes context to use (optional)

8. maverick___check_appian_operator

Monitor Appian operator health

Examines the Appian operator responsible for managing site deployments:

• Checks operator pod status and health
• Retrieves operator logs (filtered by site ID if provided)
• Monitors operator deployments
• Identifies operator-related issues

Parameters:

• siteId: Site ID to filter logs for (optional)
• kubeconfig: Path to kubeconfig file (optional)
• context: Kubernetes context to use (optional)
• tailLines: Number of log lines to retrieve (default: 100)

9. maverick___check_swg_operator

Monitor Site-Worker-Group operator health

Examines the SWG operator that manages EC2 instances and bootstrapping:

• Checks SWG operator pod status
• Retrieves SWG operator logs (filtered by site ID if provided)
• Identifies bootstrapping and instance allocation issues

Parameters:

• siteId: Site ID to filter logs for (optional)
• kubeconfig: Path to kubeconfig file (optional)
• context: Kubernetes context to use (optional)
• tailLines: Number of log lines to retrieve (default: 100)

10. maverick___check_appian_cr_status

Analyze Appian Custom Resource status

Provides detailed analysis of the Appian Custom Resource:

• Shows CR state (Ready, Starting, Creating, Requested)
• Displays conditions and component status
• Reveals configuration details
• Shows recent events related to the site

Parameters:

• siteId: Site ID (numeric)
• kubeconfig: Path to kubeconfig file (optional)
• context: Kubernetes context to use (optional)

11. maverick___get_pod_logs

Retrieve and analyze pod logs

Gets logs from specific pods with intelligent analysis:

• Retrieves logs with configurable tail length
• Supports previous logs for crashed pods
• Analyzes logs for errors and warnings
• Highlights critical issues
• Supports container-specific logs

Parameters:

• siteId: Site ID (numeric)
• podName: Name of the pod to get logs from
• container: Container name within pod (optional)
• tailLines: Number of log lines to retrieve (default: 100)
• previous: Get logs from previous container instance (for crashed pods)
• kubeconfig: Path to kubeconfig file (optional)
• context: Kubernetes context to use (optional)
• previous: Get logs from previous container instance (for crashed pods)
• kubeconfig: Path to kubeconfig file (optional)
• context: Kubernetes context to use (optional)

🔧 Enhanced Debugging Usage Examples

Prerequisites: Ensure you have AWS SSO authentication and kubectl access configured manually before starting Q chat.

Comprehensive Site Debugging with Timing Analysis

Now includes webapp timing analysis, RDBMS dependency checks, and topology detection

Enhanced Pod Status Monitoring

Now provides webapp startup timing analysis, restart pattern detection, and topology-aware critical component monitoring

Monitor Operators

Analyze Custom Resources

Get Specific Logs with Priority Focus

Advanced Debugging Scenarios

New Enhanced Features in Action

Webapp Timing Analysis:

• Automatically detects if webapp startup is within optimal (12-15 min), warning (15-20 min), or critical (>20 min) thresholds
• Monitors restart patterns and flags excessive restarts (>1) as critical issues
• Provides color-coded status indicators for quick assessment

RDBMS Dependency Detection:

• Automatically detects if rdbms.deployAsPod=true from Appian Custom Resource
• Prioritizes RDBMS pod health checks when webapp issues are detected
• Explains webapp dependency on database pod when applicable

Topology-Aware Analysis:

• Automatically detects single vs HA topology based on pod naming patterns
• Adjusts critical component expectations based on detected topology
• Provides appropriate pod counts and naming conventions for each topology

Enhanced Troubleshooting Workflow:

• Prioritizes webapp pod log analysis as first step
• Follows dependency chain: RDBMS → Zookeeper → Kafka → Data Server → Webapp
• Provides actionable recommendations based on detected issues

🏗️ Enhanced Appian Architecture Understanding

Webapp Startup Timing & Performance Criteria

Optimal Performance Thresholds:

• Optimal startup time: 12-15 minutes
• Warning threshold: 15-20 minutes
• Maximum acceptable: 20 minutes
• Restart tolerance: 1 restart is acceptable, >1 indicates issues

Critical Pod Dependencies & Topology

Single Topology (all pods end with -0):

• appian-webapp-0 - Primary user interface (CRITICAL)
• appian-rdbms-0 - Database pod (when rdbms.deployAsPod=true)
• appian-service-manager-0 - Process execution engines
• appian-data-server-0 - Database connectivity layer
• appian-search-server-0 - Full-text search capabilities
• appian-kafka-0 - Event streaming and messaging
• appian-zookeeper-0 - Coordination service

HA Topology (3 replicas: -0, -1, -2):

• All components have 3 instances for high availability
• Example: appian-webapp-0, appian-webapp-1, appian-webapp-2

Enhanced Dependency Chain

Critical Path for Site Accessibility:

Key Dependencies:

• Webapp depends on: RDBMS (if deployed as pod), Data Server, Service Manager, Search Server
• Service Manager depends on: Kafka, Zookeeper
• Data Server depends on: Kafka, Zookeeper, RDBMS (if deployed as pod)
• Kafka depends on: Zookeeper

RDBMS Pod Configuration

When rdbms.deployAsPod=true in the Appian Custom Resource:

• Database runs as appian-rdbms-0 pod (single) or appian-rdbms-{0,1,2} (HA)
• CRITICAL: Webapp cannot start without RDBMS pod being Running
• Priority: Always check RDBMS pod logs first if webapp fails to start

How Appian Sites are Deployed

1. SWG Custom Resource: Deployed to default namespace with site ID as name
2. Site-Worker-Group Operator: Reads SWG CR and creates EC2 instances
3. Bootstrapping: EC2 instances run cloud-scripts to deploy Appian CR
4. Site Namespace: Created with site ID as namespace name (e.g., "234517")
5. Appian Operator: Reads Appian CR and deploys application pods
6. Critical Pod: appian-webapp-0 must be Running for site to be accessible

Debugging Workflow

1. Start with comprehensive debugging: Use debug_site_startup for overview
2. Check pod status: Use check_site_pods to identify problematic pods
3. Examine operators: Check both Appian and SWG operators for issues
4. Analyze Custom Resources: Use check_appian_cr_status for deployment state
5. Get detailed logs: Use get_pod_logs for specific error analysis
6. Follow dependencies: Troubleshoot upstream components first

Component Dependencies

Common Issues and Solutions

Testing

Run the comprehensive test suite to verify all functionality:

The test_all.py script provides:

• ✅ Environment setup validation
• ✅ Server import and utility function testing
• ✅ MCP tools verification
• ✅ API connectivity testing (if token provided)
• ✅ Site management tools testing (dry run)
• ✅ Debugging tools validation
• 📊 Comprehensive test results and success rate
• 📚 Usage guide and troubleshooting tips

🚨 Troubleshooting

Timeout Issues

If you experience timeout errors like "Amazon Q is having trouble responding right now", the consolidated server now includes:

• Reduced timeouts: kubectl commands timeout after 15 seconds (down from 30)
• HTTP timeouts: API requests timeout after 10 seconds (down from 30)
• Global timeout: All operations timeout after 45 seconds maximum
• Graceful cleanup: Processes are properly terminated on timeout

Common Error: "unexpected token '<'"

This error occurs when the API returns HTML instead of JSON.

Quick Fix:

Performance Optimization

The server is now fully consolidated with:

• ✅ All debugging logic integrated into server.py
• ✅ No separate files that could cause import delays
• ✅ Optimized timeout handling
• ✅ Reduced log output for faster responses
• ✅ Efficient pod analysis and log parsing

See TROUBLESHOOTING.md for detailed solutions.

Response Format

The server provides formatted, human-readable responses with:

• ✅ Success indicators
• ❌ Error indicators
• 📊 Structured information with emojis for easy reading
• 🔍 Detailed diagnostic information
• 💡 Actionable recommendations
• 📝 Code blocks for logs and YAML output

Dependencies

• mcp>=1.10.0: Model Context Protocol library
• httpx>=0.25.0: Async HTTP client
• pyyaml>=6.0: YAML parsing for Kubernetes resources
• Python 3.8+
• kubectl: Kubernetes command-line tool (for debugging features)

Environment Variables

• MAVERICK_BASE_URL: Base URL for Maverick API (default: staging)
• MAVERICK_API_TOKEN: Authentication token for Maverick API (required)

Files in this Project

• server.py - Main consolidated MCP server with all tools and debugging functionality
• requirements.txt - Python dependencies
• setup.py - Package configuration
• test_all.py - Comprehensive test suite for all functionality
• diagnose_api.py - API connection diagnostic tool
• q-config-example.json - Example Q CLI configuration
• DEBUGGING_GUIDE.md - Comprehensive debugging guide
• TROUBLESHOOTING.md - Common issues and solutions
• README.md - This documentation

Next Steps

1. Get your Maverick API token from your Maverick instance
2. Set the environment variables with your actual token
3. Ensure kubectl access to your Kubernetes clusters
4. Add the MCP server configuration to ~/.aws/amazonq/mcp.json
5. Restart Amazon Q CLI and test with: q chat
6. Try the debugging commands to troubleshoot site issues

Development

To extend the server with additional debugging capabilities:

1. Add new tool definitions to handle_list_tools()
2. Add corresponding handlers to handle_call_tool()
3. Implement the debugging functions using run_kubectl_command()
4. Update this README with the new functionality
5. Add tests to test_debug.py

The debugging framework is designed to be extensible and follows Kubernetes best practices for troubleshooting Appian deployments.