check_ansible_service

Verify the deployment status of Ansible-managed services on homelab infrastructure by checking service status across specified hosts.

Instructions

Check the status of an Ansible-managed service deployment

Input Schema

TableJSON Schema

Name	Required	Description	Default
`service_name`	Yes	Name of the service to check
`hostname`	Yes	Hostname or IP address of the device
`username`	No	SSH username (use 'mcp_admin' for passwordless access after setup)	mcp_admin
`password`	No	SSH password (not needed for mcp_admin after setup)
`port`	No	SSH port (default: 22)

Implementation Reference

src/homelab_mcp/tool_handlers/service_handlers.py:78-82 (handler)

Main MCP tool handler function that creates a ServiceInstaller instance and calls check_ansible_service method with provided arguments, returning the result as formatted JSON.

async def handle_check_ansible_service(arguments: dict[str, Any]) -> dict[str, Any]:
    """Handle check_ansible_service tool."""
    installer = ServiceInstaller()
    ansible_result = await installer.check_ansible_service(**arguments)
    return {"content": [{"type": "text", "text": json.dumps(ansible_result, indent=2)}]}

src/homelab_mcp/service_installer.py:1334-1406 (handler)

Actual implementation of check_ansible_service that checks if an Ansible-managed service deployment exists by verifying the Ansible directory, playbook file, checking if Ansible is installed, and returning detailed status information.

async def check_ansible_service(
    self,
    service_name: str,
    hostname: str,
    username: str = "mcp_admin",
    password: str | None = None,
) -> dict[str, Any]:
    """Check the status of an Ansible-managed service."""
    ansible_dir = f"/opt/ansible/{service_name}"

    # Check if Ansible directory exists
    dir_check = await ssh_execute_command(
        hostname=hostname,
        username=username,
        password=password,
        command=f"test -d {ansible_dir}",
    )

    dir_data = json.loads(dir_check)
    if dir_data.get("exit_code") != 0:
        return {
            "status": "not_found",
            "service": service_name,
            "error": f"Ansible deployment not found: {ansible_dir}",
        }

    # Check playbook exists
    playbook_path = f"{ansible_dir}/playbooks/{service_name}.yml"
    playbook_check = await ssh_execute_command(
        hostname=hostname,
        username=username,
        password=password,
        command=f"test -f {playbook_path}",
    )

    playbook_data = json.loads(playbook_check)
    if playbook_data.get("exit_code") != 0:
        return {
            "status": "error",
            "service": service_name,
            "error": f"Playbook not found: {playbook_path}",
        }

    # Get file information
    info_result = await ssh_execute_command(
        hostname=hostname,
        username=username,
        password=password,
        command=f"ls -la {ansible_dir}/playbooks/{service_name}.yml {ansible_dir}/inventory/hosts",
    )

    info_data = json.loads(info_result)

    # Check if Ansible is installed
    ansible_check = await ssh_execute_command(
        hostname=hostname,
        username=username,
        password=password,
        command="ansible-playbook --version",
    )

    ansible_data = json.loads(ansible_check)
    ansible_installed = ansible_data.get("exit_code") == 0

    return {
        "status": "deployed",
        "service": service_name,
        "ansible_dir": ansible_dir,
        "playbook_path": playbook_path,
        "ansible_installed": ansible_installed,
        "ansible_version": ansible_data.get("output", "").split("\n")[0] if ansible_installed else None,
        "files_info": info_data.get("output", ""),
    }

src/homelab_mcp/tool_schemas/service_tools_schema.py:217-247 (schema)

Tool schema definition for check_ansible_service including description and inputSchema with required parameters (service_name, hostname) and optional parameters (username, password, port) with defaults.

"check_ansible_service": {
    "description": "Check the status of an Ansible-managed service deployment",
    "inputSchema": {
        "type": "object",
        "properties": {
            "service_name": {
                "type": "string",
                "description": "Name of the service to check",
            },
            "hostname": {
                "type": "string",
                "description": "Hostname or IP address of the device",
            },
            "username": {
                "type": "string",
                "description": "SSH username (use 'mcp_admin' for passwordless access after setup)",
                "default": "mcp_admin",
            },
            "password": {
                "type": "string",
                "description": "SSH password (not needed for mcp_admin after setup)",
            },
            "port": {
                "type": "integer",
                "description": "SSH port (default: 22)",
                "default": 22,
            },
        },
        "required": ["service_name", "hostname"],
    },
},

src/homelab_mcp/tool_handlers/__init__.py:113-113 (registration)
Tool registration mapping check_ansible_service to its handler function in the tools dictionary.
```
"check_ansible_service": handle_check_ansible_service,
```

Homelab MCP Server