Skip to main content
Glama

Maverick MCP Server

by VigneshR1812

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:
cd /Users/vigneshwaran.rajesh/companyWork/EE-hackathon/maverick-mcp pip install -e . pip install -r requirements.txt
  1. Test the installation:
python3 test_all.py # Comprehensive test suite (recommended) python3 diagnose_api.py # Diagnose API connection issues (if needed)
  1. Set up environment variables:
export MAVERICK_BASE_URL="https://maverick-staging.appiancloud.com" export MAVERICK_API_TOKEN="your-api-token-here"

Configuration for Amazon Q CLI

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

{ "mcpServers": { "maverick": { "command": "python3", "args": ["/Users/vigneshwaran.rajesh/companyWork/EE-hackathon/maverick-mcp/server.py"], "env": { "MAVERICK_BASE_URL": "https://maverick-staging.appiancloud.com", "MAVERICK_API_TOKEN": "your-actual-api-token-here" } } } }

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

Debug site startup issues for site 234517

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

Enhanced Pod Status Monitoring

Check site pods for site 234517

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

Monitor Operators

Check Appian operator logs for site 234517 Check SWG operator logs for site 234517

Analyze Custom Resources

Check Appian CR status for site 234517

Get Specific Logs with Priority Focus

Get pod logs for site 234517 pod appian-webapp-0 Get pod logs for site 234517 pod appian-rdbms-0 Get pod logs for site 234517 pod appian-webapp-0 with previous logs Get pod logs for site 234517 pod appian-service-manager-0 with 200 lines

Advanced Debugging Scenarios

Debug site startup for site 234517 with detailed output Check site pods for site 234517 using custom kubeconfig /path/to/config Get pod logs for site 234517 pod appian-kafka-0 container kafka

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:

RDBMS Pod (if enabled) → Zookeeper → Kafka → Data Server → Service Manager → Webapp

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

Zookeeper → Kafka, Data Server, Service Manager, Webapp Kafka → Data Server, Service Manager, Webapp Search Server → Webapp Data Server → Webapp Service Manager → Webapp Webapp → Apache Web Server (httpd)

Common Issues and Solutions

IssueSymptomsSolution
ImagePullBackOffPods can't pull imagesCheck installer/image availability
CrashLoopBackOffPods keep restartingCheck pod logs for startup errors
Pending PodsPods stuck in PendingCheck resource constraints and node capacity
No NamespaceSite namespace doesn't existSWG operator hasn't completed bootstrapping
No Appian CRAppian CR not foundCloud-scripts haven't run successfully
Webapp Not RunningSite not accessibleCheck upstream dependencies and logs

Testing

Run the comprehensive test suite to verify all functionality:

python3 test_all.py # Complete test suite with detailed results python3 diagnose_api.py # Diagnose API connection issues (if needed)

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:

# Run diagnostic tool python3 diagnose_api.py # Check your API token echo $MAVERICK_API_TOKEN # Verify API URL echo $MAVERICK_BASE_URL

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.

Related MCP Servers

  • Amazon Web Services
    aws-mcp

    A
    security
    F
    license
    A
    quality
    A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your AWS environment. This allows for natural language querying and management of your AWS resources during conversations. Think of better Amazon Q alternative.
    Last updated -
    3
    280
    TypeScript
    • Apple
  • -
    security
    A
    license
    -
    quality
    An MCP server that allows managing Docker containers through natural language, enabling users to compose, introspect, and debug containers without running commands themselves.
    Last updated -
    544
    Python
    GPL 3.0
    • Apple
  • -
    security
    A
    license
    -
    quality
    A lightweight service that enables AI assistants to execute AWS CLI commands through the Model Context Protocol (MCP), allowing AI tools to retrieve AWS documentation and interact with AWS services.
    Last updated -
    148
    Python
    MIT License
    • Apple
  • -
    security
    F
    license
    -
    quality
    An MCP server that enables Claude to generate and execute AWS CLI commands, allowing users to manage AWS resources through natural language conversations.
    Last updated -
    2
    TypeScript

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/VigneshR1812/Maverick-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server