Provides tools for managing Maverick sites on Appian's platform, including creating new sites, querying existing sites, retrieving site details, performing maintenance actions (start, stop, restart), and modifying site configurations such as server size, region, and volume.
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
- Install the package:
- Test the installation:
- 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:
- Checks SWG Custom Resource in default namespace
- Verifies Site-Worker-Group operator health
- Confirms site namespace existence
- Examines Appian Custom Resource status
- Validates Appian operator functionality
- Analyzes site pod status
- Focuses on critical webapp pod
- Provides actionable recommendations
Parameters:
siteId
: Site ID (numeric) - becomes the Kubernetes namespacekubeconfig
: 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 fromcontainer
: 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 (whenrdbms.deployAsPod=true
)appian-service-manager-0
- Process execution enginesappian-data-server-0
- Database connectivity layerappian-search-server-0
- Full-text search capabilitiesappian-kafka-0
- Event streaming and messagingappian-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) orappian-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
- SWG Custom Resource: Deployed to default namespace with site ID as name
- Site-Worker-Group Operator: Reads SWG CR and creates EC2 instances
- Bootstrapping: EC2 instances run cloud-scripts to deploy Appian CR
- Site Namespace: Created with site ID as namespace name (e.g., "234517")
- Appian Operator: Reads Appian CR and deploys application pods
- Critical Pod:
appian-webapp-0
must be Running for site to be accessible
Debugging Workflow
- Start with comprehensive debugging: Use
debug_site_startup
for overview - Check pod status: Use
check_site_pods
to identify problematic pods - Examine operators: Check both Appian and SWG operators for issues
- Analyze Custom Resources: Use
check_appian_cr_status
for deployment state - Get detailed logs: Use
get_pod_logs
for specific error analysis - Follow dependencies: Troubleshoot upstream components first
Component Dependencies
Common Issues and Solutions
Issue | Symptoms | Solution |
---|---|---|
ImagePullBackOff | Pods can't pull images | Check installer/image availability |
CrashLoopBackOff | Pods keep restarting | Check pod logs for startup errors |
Pending Pods | Pods stuck in Pending | Check resource constraints and node capacity |
No Namespace | Site namespace doesn't exist | SWG operator hasn't completed bootstrapping |
No Appian CR | Appian CR not found | Cloud-scripts haven't run successfully |
Webapp Not Running | Site not accessible | Check upstream dependencies and logs |
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 libraryhttpx>=0.25.0
: Async HTTP clientpyyaml>=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 functionalityrequirements.txt
- Python dependenciessetup.py
- Package configurationtest_all.py
- Comprehensive test suite for all functionalitydiagnose_api.py
- API connection diagnostic toolq-config-example.json
- Example Q CLI configurationDEBUGGING_GUIDE.md
- Comprehensive debugging guideTROUBLESHOOTING.md
- Common issues and solutionsREADME.md
- This documentation
Next Steps
- Get your Maverick API token from your Maverick instance
- Set the environment variables with your actual token
- Ensure kubectl access to your Kubernetes clusters
- Add the MCP server configuration to
~/.aws/amazonq/mcp.json
- Restart Amazon Q CLI and test with:
q chat
- Try the debugging commands to troubleshoot site issues
Development
To extend the server with additional debugging capabilities:
- Add new tool definitions to
handle_list_tools()
- Add corresponding handlers to
handle_call_tool()
- Implement the debugging functions using
run_kubectl_command()
- Update this README with the new functionality
- Add tests to
test_debug.py
The debugging framework is designed to be extensible and follows Kubernetes best practices for troubleshooting Appian deployments.
This server cannot be installed
An MCP server that enables Amazon Q CLI users to create, query, and manage Maverick sites through natural language commands.
- 🆕 Recent Updates
- Features
- Installation
- Configuration for Amazon Q CLI
- Available Tools
- Site Management Tools
- 1. maverick___create_site
- 2. maverick___query_sites
- 3. maverick___get_site_by_id
- 4. maverick___manage_site
- 5. maverick___get_site_resize_status
- 🆕 Kubernetes Debugging Tools
- 6. maverick___debug_site_startup
- 7. maverick___check_site_pods
- 8. maverick___check_appian_operator
- 9. maverick___check_swg_operator
- 10. maverick___check_appian_cr_status
- 11. maverick___get_pod_logs
- 🔧 Enhanced Debugging Usage Examples
- 🏗️ Enhanced Appian Architecture Understanding
- Testing
- 🚨 Troubleshooting
- Response Format
- Dependencies
- Environment Variables
- Files in this Project
- Next Steps
- Development
Related MCP Servers
- AsecurityFlicenseAqualityA 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 -3280TypeScript
- -securityAlicense-qualityAn MCP server that allows managing Docker containers through natural language, enabling users to compose, introspect, and debug containers without running commands themselves.Last updated -544PythonGPL 3.0
- -securityAlicense-qualityA 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 -148PythonMIT License
- -securityFlicense-qualityAn MCP server that enables Claude to generate and execute AWS CLI commands, allowing users to manage AWS resources through natural language conversations.Last updated -2TypeScript