sibilleb/AAP-Enterprise-MCP-Server
If you are the rightful owner of AAP-Enterprise-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
AAP Enterprise MCP Server is a comprehensive Model Context Protocol (MCP) server suite designed for Red Hat's automation and infrastructure ecosystem.
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.
Features
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
Event-Driven Ansible (EDA) Integration
- 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
Ansible Galaxy Integration
- 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
Ansible Lint Integration
- 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
Installation
Prerequisites
- Python 3.11 or higher
- UV package manager (recommended) or pip
- Access to an Ansible Automation Platform instance
- Valid AAP API token
Setup
-
Clone the repository:
git clone https://github.com/sibilleb/AAP-Enterprise-MCP-Server.git cd AAP-Enterprise-MCP-Server
-
Install dependencies:
# Using UV (recommended) uv sync # Or using pip pip install -e .
-
Set up environment variables:
# 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"
Getting Your API Token
Method 1: AAP Web Interface
- 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)
Method 2: Command Line
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"
}'
Configuration
MCP Client Configuration
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"
}
}
}
}
SSL/TLS Configuration
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.
Server Architecture
This project implements a four-server MCP architecture for comprehensive Red Hat ecosystem coverage:
Server | File | Purpose | Key Features |
---|---|---|---|
Ansible Automation Platform | ansible.py | AAP integration with Galaxy search | Job management, inventory control, Galaxy discovery (855 lines) |
Event-Driven Ansible | eda.py | EDA integration | Activation management, rulebook handling (96 lines) |
Ansible Lint | ansible-lint.py | Code quality and best practices | Progressive quality profiles, project analysis (502 lines) |
Red Hat Documentation | redhat_docs.py | Official Red Hat documentation access | Domain validation, hybrid search, PDF access |
Combined Capabilities
- 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
Available Tools
Ansible Automation Platform Tools
Tool | Description |
---|---|
list_inventories | List all inventories |
get_inventory | Get inventory details by ID |
create_inventory | Create a new inventory |
list_hosts | List hosts in an inventory |
add_host_to_inventory | Add a host to inventory |
run_job | Execute a job template |
job_status | Check job execution status |
job_logs | Retrieve job execution logs |
list_job_templates | List available job templates |
create_job_template | Create a new job template |
create_project | Create a new project |
run_adhoc_command | Execute ad-hoc ansible commands |
list_projects | List all projects |
get_project | Get project details by ID |
list_project_updates | List project update jobs (SCM sync) |
get_project_update | Get project update job status |
get_project_update_logs | Get project update job logs |
update_project | Trigger project update (SCM sync) |
Ansible Galaxy Search Tools
Tool | Description |
---|---|
search_galaxy_collections | Search Ansible Galaxy collections by query, tags, or namespace |
search_galaxy_roles | Search Ansible Galaxy roles by keyword, name, or author |
get_collection_details | Get detailed information about a specific collection |
get_role_details | Get detailed information about a specific role |
suggest_ansible_content | Intelligently suggest collections and roles based on use case description |
Ansible Lint Tools
Tool | Description |
---|---|
lint_playbook | Lint Ansible playbook content with configurable profiles and rules |
lint_file | Lint specific Ansible files on disk |
lint_role | Comprehensive validation of Ansible role directories |
validate_syntax | Quick syntax-only validation for immediate feedback |
check_best_practices | Context-aware best practice checking (dev/staging/production) |
analyze_project | Analyze entire Ansible project structure with comprehensive reporting |
list_rules | List available ansible-lint rules, optionally filtered by tags |
list_tags | List all available tags for ansible-lint rules |
get_ansible_lint_version | Get version information for installed ansible-lint |
Event-Driven Ansible Tools
Tool | Description |
---|---|
list_activations | List EDA activations |
get_activation | Get activation details |
create_activation | Create new activation |
enable_activation | Enable an activation |
disable_activation | Disable an activation |
restart_activation | Restart an activation |
list_rulebooks | List available rulebooks |
get_rulebook | Get rulebook details |
list_decision_environments | List decision environments |
Red Hat Documentation Tools
Tool | Description |
---|---|
read_documentation | Read Red Hat documentation with domain validation and PDF-first access |
list_products | List all available Red Hat products and versions |
search_documentation | Search Red Hat documentation with version prioritization |
search_documentation_enhanced | NEW: Hybrid search combining sitemap + web search discovery |
search_with_web_guidance | NEW: Get direct results + optimized Red Hat domain-restricted web search queries |
smart_documentation_finder | NEW: Intelligent multi-source documentation discovery |
get_product_guides | Get product guides with semantic version sorting (13 guides for OpenShift 4.18) |
recommend_content | Intelligent recommendations with telco/edge/CNF specialization |
Usage Examples
Running a Job Template
# 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"])
Managing Inventory
# 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"
)
Galaxy Content Discovery
# 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)
Ansible Lint Quality Assurance
# 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()
EDA Activation Management
# 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)
Red Hat Documentation Access
# 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")
Development
Running Tests
# Install development dependencies
uv sync --group dev
# Run tests
pytest
# Run with coverage
pytest --cov=.
Code Formatting
# Format code
black .
# Lint code
ruff check .
# Type checking
mypy .
Troubleshooting
Common Issues
-
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.
Debug Mode
Set environment variable for verbose logging:
export MCP_DEBUG=1
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
License
This project is licensed under the MIT License - see the file for details.
Key Achievements
🎯 Red Hat Documentation Success Metrics
- ✅ Version Detection: OpenShift 4.18 correctly identified as latest (not 3.x)
- ✅ PDF Access: 1.4MB+ PDF files successfully accessible
- ✅ Search Relevance: Telco edge queries return specialized documentation
- ✅ Domain Security: 100% Red Hat domain validation (50+ domains tested)
- ✅ Web Search Integration: Hybrid approach with official source restriction
📊 Performance Improvements
Metric | Before | After | Status |
---|---|---|---|
Latest Version Detection | ❌ 3.x versions | ✅ 4.18+ versions | Fixed |
PDF Access Success Rate | ❌ 301/404 errors | ✅ 200 OK responses | 100% |
Domain Validation | ❌ No filtering | ✅ 50+ official domains | Secured |
Available OpenShift Guides | 8 generic | 13 specialized | +62% |
Support
- Repository: AAP Enterprise MCP Server
- Issues: GitHub Issues
- Documentation: |
- Ansible Community: Ansible Community Forum
Related Projects
- Ansible Automation Platform
- Event-Driven Ansible
- OpenShift Container Platform
- Red Hat Enterprise Linux
- Model Context Protocol
- FastMCP
Ready for production use with secure, domain-validated Red Hat ecosystem access! 🚀