AAP MCP Server

# Ansible Automation Platform (AAP) Controller + Gateway MCP Server A comprehensive Model Context Protocol (MCP) server for managing both Ansible Automation Platform Controller and Gateway APIs. This server provides 17 specialized tools that cover all major AAP Controller and Gateway functions with near-complete API coverage. ## Project Structure - **MCP Server**: `mcp_server.py` - Main server that handles MCP protocol - **API Connectors**: `connectors/` directory contains HTTP API connectors - `aap_connector.py` - Connects to AAP Controller API - `gateway_connector.py` - Connects to AAP Gateway API - **Tools**: `tools/` directory contains 17 specialized tool modules - **Controller Tools**: `controller_*` prefix - AAP Controller API tools (13 tools) - **Gateway Tools**: `gateway_*` prefix - AAP Gateway API tools (4 tools) - **Authentication**: Environment variable based (tokens preferred) ## Setup & Installation ### 1. Clone this repository: ```bash git clone <repository-url> cd aap-mcp-server ``` ### 2. Setting up uv (Python package manager) [uv](https://github.com/astral-sh/uv) is a fast, modern Python package manager that can be used as a drop-in replacement for pip. It is recommended for faster dependency management. #### On macOS (using Homebrew): ```bash brew install uv ``` #### On Linux (using the official install script): ```bash curl -Ls https://astral.sh/uv/install.sh | sh ``` For more installation options and details, see the [uv documentation](https://github.com/astral-sh/uv). Once installed, you can use `uv` instead of `pip`: ```bash uv pip install -r requirements.txt ``` ### MCP Cursor Configuration Example (using uv) To run the server with uv in an MCP Cursor client, use a configuration like this: ```json { "mcpServers": { "aap-controller": { "command": "uv", "args": [ "--directory", "/path/to/aap-mcp-pilot", "run", "mcp_server.py" ], "env": { "AAP_TOKEN": "<your-api-token>", "AAP_BASE_URL": "https://your-aap-controller.example.com/" } } } } ``` - Update the `--directory` path to your project location. - Replace the URLs and token with your actual values. - **Note:** If you only provide `AAP_URL`, the server will automatically infer `GATEWAY_URL` (and vice versa) if possible. Only set both if your deployment uses non-standard URLs. ### 3. Install dependencies (if not using uv): ```bash pip install -r requirements.txt ``` ### 4. Configure environment variables: **For AAP Controller:** ```bash export AAP_URL="https://your-aap-controller.example.com/api/controller/v2" export AAP_TOKEN="your-api-token" # Or use username/password ``` **For AAP Gateway (optional):** ```bash # If not set, GATEWAY_URL will be inferred from AAP_URL if possible export GATEWAY_URL="https://your-aap-gateway.example.com/api/gateway/v1" ``` ### 5. Configuration #### MCP Client Configuration To use this server with an MCP client (like Cursor), create a configuration file: ```json { "mcpServers": { "aap-controller": { "command": "python", "args": ["mcp_server.py"], "cwd": "/path/to/aap-mcp-pilot", "env": { "AAP_BASE_URL": "https://your-aap-controller.example.com", "AAP_TOKEN": "your-api-token-here" } } } } ``` **Important Configuration Notes:** - Update the `cwd` path to match your installation directory - Replace `AAP_BASE_URL` with your actual AAP Controller URL - Replace `AAP_TOKEN` with your actual API token ### Authentication Configuration The server supports authentication for both AAP Controller and Gateway. See the environment variable section above for details. ## Features This MCP server provides comprehensive access to both AAP Controller and Gateway through these 17 specialized tools: ### AAP Controller Tools (13 tools) ### 1. Job Management (`job_management`) - Launch jobs from templates - Monitor job status and progress - Cancel and relaunch jobs - Retrieve job logs and output - List and filter jobs ### 2. Inventory Management (`inventory_management`) - Create, update, and delete inventories - Add and remove hosts - Manage groups and host relationships - Sync inventory sources - List and filter inventory components ### 3. Project Management (`project_management`) - Create and manage SCM projects - Sync projects from source control - List available playbooks - Update project configurations - Handle project updates ### 4. Template Management (`template_management`) - Manage job templates - Handle workflow job templates - Create and configure system job templates - Template lifecycle management ### 5. User & Organization Management (`user_organization_management`) - Create and manage users - Handle organizations and teams - Manage user permissions and roles - Organization membership management ### 6. Credential Management (`credential_management`) - Create and manage credentials - Handle different credential types - Test credential connectivity - Secure credential storage ### 7. Workflow Management (`workflow_management`) - Create and launch workflow templates - Manage workflow nodes and dependencies - Monitor workflow execution - Configure workflow logic ### 8. Scheduling & Automation (`scheduling_automation`) - Create and manage schedules - Configure notifications - Enable/disable automation - Handle recurring tasks ### 9. Monitoring & Analytics (`monitoring_analytics`) - View system dashboard - Get job statistics and metrics - Monitor host performance - View activity streams ### 10. Configuration Management (`configuration_management`) - Manage system settings - Configure instance groups - View license information - System health monitoring ### 11. Generic API Access (`generic_api`) - Direct access to any AAP Controller API endpoint - Support for GET, POST, PATCH, DELETE operations - 100% API coverage as fallback - Flexible parameter handling ### 12. Advanced Analytics (`advanced_analytics`) - Job explorer and analysis - Host performance analytics - Event stream analysis - ROI and adoption metrics ### 13. System Extensions (`system_extensions`) - Mesh visualization and management - Receptor network management - Constructed inventories - Debug tools and utilities ### AAP Gateway Tools (4 tools) ### 14. Gateway Service Management (`gateway_service_management`) - Manage services and service types - Configure service clusters and nodes - Handle route management - Service discovery and indexing ### 15. Gateway Authentication & Access Management (`gateway_auth_management`) - User and team management - Organization administration - Role definitions and assignments - Authenticator configuration - OAuth application management ### 16. Gateway Monitoring & Configuration (`gateway_monitoring`) - Activity stream monitoring - System status and health checks - Settings and configuration management - HTTP port management - Feature flags and service keys ### 17. Gateway Generic API Access (`gateway_generic_api`) - Direct access to any AAP Gateway API endpoint - Support for all HTTP methods - Complete Gateway API coverage - Flexible endpoint access ## Usage ### Running the Server ```bash python mcp_server.py ``` ### Using with MCP Clients Connect your MCP client to this server to access AAP Controller functionality. Each tool provides comprehensive access to different aspects of AAP. ### Example Tool Usage #### Launch a Job ```python # Using job_management tool { "action": "launch", "job_template_id": 123, "extra_vars": {"target_hosts": "web_servers"}, "limit": "production" } ``` #### Create an Inventory ```python # Using inventory_management tool { "action": "create", "inventory_data": { "name": "Production Servers", "description": "Production environment inventory", "organization": 1 } } ``` #### Monitor Job Status ```python # Using monitoring_analytics tool { "action": "job_stats", "time_range": "24h" } ``` ## Tool Reference ### job_management **Actions:** `list`, `launch`, `cancel`, `relaunch`, `get_status`, `get_logs` **Parameters:** - `job_template_id`: Template ID for launching jobs - `job_id`: Job ID for operations on specific jobs - `extra_vars`: Extra variables for job launch - `limit`: Limit hosts for job execution - `filters`: Filters for listing jobs ### inventory_management **Actions:** `list`, `create`, `update`, `delete`, `add_host`, `remove_host`, `list_hosts`, `sync` **Parameters:** - `inventory_id`: Inventory ID for operations - `inventory_data`: Inventory data for create/update - `host_data`: Host data for adding hosts - `host_id`: Host ID for operations - `filters`: Filters for listing ### project_management **Actions:** `list`, `create`, `update`, `delete`, `sync`, `get_playbooks` **Parameters:** - `project_id`: Project ID for operations - `project_data`: Project data for create/update - `filters`: Filters for listing ### template_management **Actions:** `list`, `create`, `update`, `delete`, `list_job_templates`, `list_workflow_templates` **Parameters:** - `template_id`: Template ID for operations - `template_data`: Template data for create/update - `template_type`: Template type (`job`, `workflow`, `system`) - `filters`: Filters for listing ### user_organization_management **Actions:** `list_users`, `create_user`, `list_orgs`, `create_org`, `list_teams`, `add_user_to_team` **Parameters:** - `user_id`: User ID for operations - `org_id`: Organization ID for operations - `team_id`: Team ID for operations - `user_data`: User data for create/update - `org_data`: Organization data for create/update - `team_data`: Team data for create/update - `filters`: Filters for listing ### credential_management **Actions:** `list`, `create`, `update`, `delete`, `list_types` **Parameters:** - `credential_id`: Credential ID for operations - `credential_data`: Credential data for create/update - `credential_type_id`: Credential type ID - `filters`: Filters for listing ### workflow_management **Actions:** `list`, `create`, `launch`, `get_nodes`, `add_node`, `update_node` **Parameters:** - `workflow_id`: Workflow template ID - `workflow_job_id`: Workflow job ID - `node_id`: Workflow node ID - `workflow_data`: Workflow data - `node_data`: Node data for workflow nodes - `extra_vars`: Extra variables for workflow launch - `filters`: Filters for listing ### scheduling_automation **Actions:** `list_schedules`, `create_schedule`, `enable_schedule`, `disable_schedule`, `list_notifications` **Parameters:** - `schedule_id`: Schedule ID for operations - `template_id`: Template ID for scheduling - `schedule_data`: Schedule data for create/update - `notification_data`: Notification data - `template_type`: Template type (`job`, `workflow`) - `filters`: Filters for listing ### monitoring_analytics **Actions:** `dashboard`, `job_stats`, `host_metrics`, `activity_stream`, `system_jobs` **Parameters:** - `time_range`: Time range for metrics (`1h`, `24h`, `7d`, `30d`) - `job_id`: Job ID for specific job analytics - `host_id`: Host ID for host metrics - `filters`: Filters for analytics ### configuration_management **Actions:** `get_config`, `update_config`, `get_settings`, `list_instance_groups`, `get_license` **Parameters:** - `setting_key`: Specific setting key to retrieve - `config_data`: Configuration data for updates - `instance_group_id`: Instance group ID - `filters`: Filters for listing ## Security Considerations 1. **Use API tokens** instead of username/password when possible 2. **Enable SSL/TLS** for your AAP Controller 3. **Limit API access** through AAP's RBAC system 4. **Monitor API usage** through AAP's activity stream 5. **Rotate credentials** regularly ## Error Handling All tools include comprehensive error handling and will return error messages in this format: ```json { "error": "Description of the error" } ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License This project is licensed under the MIT License. ## Support For issues and questions: 1. Check the AAP Controller API documentation 2. Review the tool reference above 3. Check environment variable configuration 4. Verify network connectivity to AAP Controller ## Quickstart ### Using venv ```sh python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python mcp_server.py ``` ### Using uv ```sh uv venv .venv source .venv/bin/activate uv pip install -r requirements.txt python mcp_server.py ``` - **Tip:** If you only set `AAP_URL`, the code will try to infer `GATEWAY_URL` automatically. Only set both if your URLs are non-standard.