AAP Enterprise MCP Server

A comprehensive Model Context Protocol (MCP) server suite for Red Hat's automation and infrastructure ecosystem, enabling AI assistants to interact with Ansible Automation Platform (AAP), Event-Driven Ansible (EDA), ansible-lint code quality tools, and Red Hat's official documentation with secure domain validation.

Ansible Automation Platform (AAP) Integration

- Inventory Management: List, create, update inventories and manage hosts/groups
- Job Management: Run job templates, monitor job status, and retrieve logs
- Project Management: Create and manage SCM-based projects
- Template Management: Create and manage job templates
- Host Operations: Add/remove hosts, manage host variables and facts
- Ad-hoc Commands: Execute ansible commands directly on inventory hosts

- Activation Management: List, create, enable/disable EDA activations
- Rulebook Management: Manage and query rulebooks
- Decision Environment Management: Manage decision environments
- Event Stream Monitoring: Monitor event streams

- Collection Search: Search and discover Ansible collections by name, namespace, or keywords
- Role Search: Find community roles by keyword, author, or specific criteria
- Content Details: Get comprehensive information about collections and roles including versions, dependencies, and installation instructions
- Smart Suggestions: AI-powered content recommendations based on use case descriptions
- AAP Integration: Intelligent suggestions that consider existing AAP infrastructure and inventories

- Playbook Validation: Real-time linting of Ansible playbook content with configurable quality profiles
- File Analysis: Comprehensive analysis of Ansible files, roles, and entire project structures
- Best Practice Enforcement: Automated checking against Ansible community standards and best practices
- Syntax Validation: Quick syntax checking for immediate feedback during development
- Multi-Profile Support: Progressive quality improvement with profiles from basic to production-ready
- Rule Management: List, filter, and understand ansible-lint rules with detailed explanations

Red Hat Documentation Integration (Streamlined)

- Efficient Discovery: Web search-based content discovery using official Red Hat domains
- Smart Content Fetching: PDF-first strategy handling Red Hat's JavaScript rendering issues
- Domain Security: Validates access to 50+ official Red Hat domains for secure documentation access
- Minimal MCP Overhead: Streamlined 2-tool approach reduces API calls by 75%
- Search Query Generation: Creates optimized search queries for external WebSearch MCP tool usage
- Authentication Handling: Smart detection of subscription-required vs public content

- Python 3.11 or higher
- UV package manager (recommended) or pip
- Access to an Ansible Automation Platform instance
- Valid AAP API token

git clone https://github.com/sibilleb/AAP-Enterprise-MCP-Server.git cd AAP-Enterprise-MCP-Server

# Using UV (recommended) uv sync # Or using pip pip install -e .

# Required for AAP/EDA servers export AAP_TOKEN="your-aap-api-token" export AAP_URL="https://your-aap-server.com/api/controller/v2" export EDA_TOKEN="your-eda-api-token" # Can be same as AAP_TOKEN export EDA_URL="https://your-aap-server.com/api/eda/v1" # Optional for Red Hat Customer Portal access export REDHAT_USERNAME="your-redhat-username" export REDHAT_PASSWORD="your-redhat-password"

- Log into your AAP web interface
- Click on your username in the top right corner
- Select "User Settings" or "My Profile"
- Navigate to the "Tokens" section
- Click "Add" or "Create Token"
- Set the scope to "Write" for full functionality
- Copy the generated token immediately (it won't be shown again)

curl -k -X POST \ "https://your-aap-server.com/api/v2/tokens/" \ -H "Content-Type: application/json" \ -u "username:password" \ -d '{ "description": "MCP Server Token", "application": null, "scope": "write" }'

Add the following to your MCP client configuration (e.g., Claude Desktop, Cursor):

{ "mcpServers": { "ansible": { "command": "uv", "args": [ "--directory", "/path/to/AAP-Enterprise-MCP-Server", "run", "ansible.py" ], "env": { "AAP_TOKEN": "your-aap-api-token", "AAP_URL": "https://your-aap-server.com/api/controller/v2" } }, "eda": { "command": "uv", "args": [ "--directory", "/path/to/AAP-Enterprise-MCP-Server", "run", "eda.py" ], "env": { "EDA_TOKEN": "your-eda-api-token", "EDA_URL": "https://your-aap-server.com/api/eda/v1" } }, "ansible-lint": { "command": "uv", "args": [ "--directory", "/path/to/AAP-Enterprise-MCP-Server", "run", "ansible-lint.py" ] }, "redhat-docs": { "command": "uv", "args": [ "--directory", "/path/to/AAP-Enterprise-MCP-Server", "run", "redhat_docs.py" ], "env": { "REDHAT_USERNAME": "your-username", "REDHAT_PASSWORD": "your-password" } } } }

For lab environments with self-signed certificates, the servers automatically:

- Disable SSL warnings
- Skip certificate verification
- Handle insecure connections gracefully

For production environments, ensure proper SSL certificates are configured on your AAP instance.

This project implements afour-server MCP architecturefor comprehensive Red Hat ecosystem coverage:

- Complete Automation Lifecycle: From documentation discovery to implementation with quality assurance
- Security: Domain-validated access ensures only official Red Hat sources
- Intelligence: AI-powered recommendations and specialized telco/edge guidance
- Scalability: Independent servers allow focused functionality and scaling

# List available job templates templates = await list_job_templates() # Run a specific job template with variables result = await run_job( template_id=5, extra_vars={"target_env": "production", "app_version": "1.2.3"} ) # Check job status status = await job_status(result["job"])

# List all inventories inventories = await list_inventories() # Add a new host to inventory await add_host_to_inventory( inventory_id=1, hostname="web-server-01.example.com", variables={"ansible_host": "192.168.1.100", "role": "webserver"} ) # Run ad-hoc command on inventory await run_adhoc_command( inventory_id=1, module_name="setup", limit="web-server-01.example.com" )

# Get intelligent suggestions for a specific use case suggestions = await suggest_ansible_content( use_case="I am developing a playbook that spins up and down EC2 servers on AWS using ansible", check_aap_inventory=True ) # Search for AWS-related collections collections = await search_galaxy_collections(query="aws", limit=10) # Search for EC2-specific roles roles = await search_galaxy_roles(keyword="ec2", limit=5) # Get detailed information about a specific collection details = await get_collection_details(namespace="amazon", name="aws") # Get detailed information about a specific role role_info = await get_role_details(role_id=12345)

# Lint playbook content with different quality profiles playbook_content = """ --- - hosts: all tasks: - name: install package yum: name=nginx state=present """ # Basic linting for development basic_results = await lint_playbook( content=playbook_content, profile="basic", format_type="json" ) # Production-ready validation production_results = await lint_playbook( content=playbook_content, profile="production", format_type="json" ) # Quick syntax validation syntax_check = await validate_syntax(content=playbook_content) # Context-aware best practices checking best_practices = await check_best_practices( content=playbook_content, context="production" ) # Analyze entire project structure project_analysis = await analyze_project( project_path="/path/to/ansible/project", profile="moderate" ) # List available rules and tags rules = await list_rules(tags="idempotency,syntax") tags = await list_tags()

# List all activations activations = await list_activations() # Enable a specific activation await enable_activation(activation_id=3) # Check activation details details = await get_activation(activation_id=3)

# Access OpenShift documentation with PDF preference content = await read_documentation( "https://docs.redhat.com/en/documentation/openshift_container_platform/4.18/html/updating_clusters/index", format_preference="pdf" # Ensures reliable content extraction ) # Search for telco edge content with hybrid approach guidance = await search_with_web_guidance( "openshift telco edge cluster upgrade", product="openshift_container_platform" ) # Returns direct results + 5 Red Hat domain-restricted web search queries # Get comprehensive telco/edge recommendations recommendations = await recommend_content( "telco edge CNF cluster upgrade", role="administrator" ) # Returns specialized edge computing and cluster update recommendations # Get latest OpenShift guides (auto-detects 4.18, not 3.x) guides = await get_product_guides("openshift_container_platform", version="latest") # Returns 13 specialized guides including Updating Clusters, Edge Computing, etc. # Domain-validated web search workflow guidance = await search_with_web_guidance("kubernetes edge computing") # Use generated queries like: "site:docs.redhat.com openshift 4.18 kubernetes edge computing" # Then feed discovered URLs back: content = await read_documentation(discovered_url, format_preference="pdf")

# Install development dependencies uv sync --group dev # Run tests pytest # Run with coverage pytest --cov=.

# Format code black . # Lint code ruff check . # Type checking mypy .

-

SSL Certificate Errors: The server handles self-signed certificates automatically. If you encounter SSL issues, verify your AAP server configuration.

Authentication Failures: Ensure your API token has sufficient permissions (Write scope recommended).

Connection Timeouts: Check network connectivity to your AAP server and verify the URL format.

Tool Not Found: Restart your MCP client after configuration changes.

Set environment variable for verbose logging:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request

This project is licensed under the MIT License - see theLICENSEfile for details.

- Repository:AAP Enterprise MCP Server
- Issues:GitHub Issues
- Documentation:README|Red Hat Docs README
- Ansible Community:Ansible Community Forum

- Ansible Automation Platform
- Event-Driven Ansible
- OpenShift Container Platform
- Red Hat Enterprise Linux
- Model Context Protocol
- FastMCP

MCPMate is a comprehensive Model Context Protocol (MCP) management center designed to address configuration complexity, resource consumption, security risks, and other issues in the MCP ecosystem, providing users with a unified management platform.