Infra-MCP v2 with tools for container deployment

.claude/commands/fix-lint-issue.md

@@ -0,0 +1,23 @@
+# Fix specific lint issue (parameter: issue code or description)
+
+## Variables
+
+ISSUE_ID: $ARGUMENTS
+
+## Instructions
+
+1. Run "task lint-app" to identify all lint issues
+2. Filter for issues matching "ISSUE_ID" (can be a specific error code like S607 or a description like "subprocess")
+3. Analyze each matching issue and implement fixes according to best practices
+4. For each fixed issue:
+   - Explain the problem and why it's a concern
+   - Show the original code
+   - Explain your fix and its benefits
+5. After implementing fixes, run "task lint-app" again to verify the issues are resolved
+6. Summarize your changes and list any remaining issues grouped by type
+
+Notes:
+- Focus only on issues matching the specified ISSUE_ID
+- Apply consistent fixes across similar issues
+- For Python security issues (S-prefixed codes), consult Python security best practices
+- For other issues, follow the appropriate linting tool's recommendations

.claude/commands/implement-container-deployment.md

@@ -23,4 +23,4 @@ Follow closely the architectural patterns described in the `docker/guidelines.md
 
 - After writing the compose file, run `pre-commit run --files <docker-compose-filename>` and resolve any reported issues.
 - Validate the compose file with `scripts/labctl.py service config <category>/<application>` and fix any errors or warnings.
-- Pull the container image(s) with the command `scripts/labctl.py service pull <category>/<application>` and verify success.
+- Pull the container image(s) with the command `scripts/labctl.py service pull <category>/<application> --quiet` (with 15 minutes timeout) and verify success.

.claude/commands/plan-container-deployment.md

@@ -14,15 +14,16 @@ Your task is to collect all necessary know-how for deploying a containerized app
 - Visit the installation instructions page for APPLICATION_NAME at INSTALL_INSTRUCTIONS_URL and search for Docker Compose deployment examples. If none are found, fall back to plain Docker examples. Gather all information relevant to container deployment.
 - ABORT your work if no container-based installation method is found.
 - Starting from the installation page, find the application's main homepage and its GitHub repository page (if available).
-- Look at the subfolders under the `docker` directory (use the `tree -d -L 1 docker/` command) and select an existing category that fits the application. Do not create a new category; use the "tools" category as a fallback if no match is found.
-- Use the `uv run --directory scripts/task-mcp tools/find_app_icon.py "<APPLICATION_NAME>" "<APPLICATION_HOMEPAGE>"` command to determine the application's dashboard icon (use the command's output as-is).
-- For each container image used in the deployment, get the most specific tag (e.g. tag "1.2.0" is more specific than "1.2") by running `scripts/get-container-tags.py --quiet get-most-specific-tag <IMAGE> --tag <TAG>`. Use the tag returned by this script.
+- For each container image used in the deployment, get the most specific tag (e.g. tag "1.2.0" is more specific than "1.2") by using the `get-most-specific-container-tag` MCP tool. Use the tag returned by the tool.
+- Use the `get-container-categories` MCP tool to list subfolders under the `docker` directory and select an existing category (folder) that fits the application. Do not create a new category; use the "tools" category as a fallback if no good match is found.
+- Use the `get-dashboard-groups` MCP tool to list the available dashboard groups. Select the best matching. Do not create a new group; use the "Tools" group as a fallback if no good match is found.  
+- Use the `get-app-icon` MCP tool to determine the application's dashboard icon (use the tool output as-is).
 
 ### Part 2 - Organize information
 
-Fill the following template with the gathered information.
-THINK HARD to provide the best possible results.
-Save the filled template as a file with the filename `docker/<category>/<application>.md`
+Do not save the Docker Compose stack as a separate yaml file yet, only create a markdown document.
+Fill the following template with the gathered information. THINK HARD to provide the best possible results.
+Save the filled template as a file with the filename `docs/PRPs/containers/<application>.md`
 
 ```markdown
 ## Base information for <APPLICATION_NAME> application  
@@ -33,7 +34,8 @@ GitHub page: <GitHub page, if available>
 Install instructions URL: <INSTALL_INSTRUCTIONS_URL>
 Container image(s): <Container image of the service (or multiple images if the application consists of multiple services)>
 Category: <Subfolder name under the `docker` directory>
-Dashboard Icon: <Dashboard icon determined by find_app_icon.py>
+Dashboard Icon: <Dashboard icon determined by `get-app-icon`>
+Dashboard Group: <Dashboard group, the best matching value returned by `get-dashboard-groups`>
 Short description: <Describe the application in one short sentence, suitable to display on the Homepage dashboard>
 Long description: <Describe the application in 1–3 sentences. Optimally use the description of the GitHub repo>
 
@@ -47,4 +49,4 @@ Long description: <Describe the application in 1–3 sentences. Optimally use th
 
 As a final step write to the user:
 
-> To deploy the service run "/implement-container-deployment docker/<category>/<application>.md"
+> To deploy the service run "/implement-container-deployment docs/PRPs/containers/<application>.md"

.claude/settings.json

@@ -2,14 +2,27 @@
   "permissions": {
     "allow": [
       "mcp__ide__getDiagnostics",
+      "mcp__infra-mcp__get-most-specific-container-tag",
+      "mcp__infra-mcp__get-container-categories",
+      "mcp__infra-mcp__get-dashboard-groups",
+      "mcp__infra-mcp__get-app-icon",
+      "WebSearch",
       "WebFetch(domain:github.com)",
       "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:hub.docker.com)",
+      "WebFetch(domain:docs.linuxserver.io)",
+      "Bash(scripts/labctl.py service config:*)",
+      "Bash(scripts/labctl.py service pull:*)",
       "Bash(pre-commit run:*)",
-      "Bash(scripts/labctl.py service config *)",
-      "Bash(scripts/labctl.py service pull *)"
+      "Bash(task lint-app)",
+      "Bash(task lint)"
     ],
     "deny": [
       "Read(config/**)"
     ]
+  },
+  "env": {
+    "BASH_DEFAULT_TIMEOUT_MS": "600000",
+    "BASH_MAX_TIMEOUT_MS": "1800000"
   }
 }

.mcp.json

@@ -3,6 +3,20 @@
     "context7": {
       "type": "http",
       "url": "https://mcp.context7.com/mcp"
+    },
+    "infra-mcp": {
+      "type": "stdio",
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "scripts/infra-mcp",
+        "server.py"
+      ],
+      "env": {
+        "ENABLE_TASK_TOOLS": "false",
+        "ENABLE_CONTAINER_TOOLS": "true"
+      }
     }
   }
 }

.vscode/mcp.json

@@ -19,7 +19,7 @@
     "homelab-infra": {
       "type": "stdio",
       "command": "uv",
-      "args": ["run", "--directory", "scripts/task-mcp", "server.py"]
+      "args": ["run", "--directory", "scripts/infra-mcp", "server.py"]
     },
     "context7": {
       "type": "stdio",

AGENTS.md

@@ -0,0 +1,192 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This repository contains Infrastructure as Code (IaC) configuration for a home infrastructure setup. The main goals are:
+- Creating a local, self-hosted environment for various services minimizing reliance on cloud providers
+- Learning and organizing knowledge, best practices, and tool documentation
+
+## Key Commands
+
+### Development and Building
+
+```bash
+# List all available tasks
+task --list-all
+
+# Run all linting and build tasks
+task build
+
+# Run linting tools on all files (via pre-commit)
+task lint
+
+# Open TaskUI (terminal UI for executing tasks)
+task ui
+
+# Clear generated content and cache data
+task clean
+```
+
+### Docker Management
+
+```bash
+# Deploy locally configured containers
+task docker:apply
+
+# Update and restart containers
+task docker:update
+
+# Pull container images
+task docker:pull
+
+# Pull, update, restart containers, then show restarts
+task docker:pull-update
+
+# Stop configured containers
+task docker:stop
+
+# Create/update Docker example environment configuration files
+task docker:create-example-env
+```
+
+### Service Management
+
+```bash
+# Manage individual Docker service (pull, up, down, restart, recreate, config)
+scripts/labctl.py service [operation] [category/service-name]
+
+# Examples:
+scripts/labctl.py service up security/traefik
+scripts/labctl.py service restart ai/ollama
+scripts/labctl.py service pull media/video/jellyfin
+```
+
+### Ansible Commands
+
+```bash
+# Run Ansible for homelab setup
+task ansible:apply-homelab
+
+# Run Ansible for cloud setup
+task ansible:apply-cloud
+```
+
+### Terraform Management
+
+```bash
+# Apply Azure VM Terraform configuration
+task azure-vm:apply
+
+# Plan Azure VM Terraform changes
+task azure-vm:plan
+
+# Destroy Azure VM Terraform resources
+task azure-vm:destroy
+```
+
+### Utility Commands
+
+```bash
+# Show public IP of the server
+task get-public-ip
+
+# Show version numbers of installed software
+task versions
+
+# Create a compressed backup of the configuration directory
+task backup-config
+
+# Download data files for offline use
+task get-offline-data
+```
+
+## Architecture Overview
+
+The infrastructure is designed around the following components:
+
+1. **Core Infrastructure**:
+   - Proxmox Virtual Environment as a Type 1 hypervisor
+   - Ubuntu Server as the host OS for Docker containers
+   - Ansible for configuration management
+   - Docker Compose for container definitions
+
+2. **Key Services**:
+   - **Security**: Traefik (reverse proxy), Authelia (authentication), Cloudflared (tunnel)
+   - **Monitoring**: Grafana, Prometheus, Node-exporter, Uptime-kuma
+   - **Media**: Jellyfin, Metube, Navidrome, Calibre
+   - **Storage**: MinIO, Syncthing, FileSharing
+   - **AI Tools**: Ollama, Open-WebUI, LiteLLM, AutogenStudio
+   - **Tools**: Guacamole, Homepage (dashboard), Vaultwarden
+
+3. **Configuration Structure**:
+   - `ansible/`: Contains playbooks and roles for infrastructure setup
+   - `docker/`: Contains Docker Compose definitions for all services
+   - `docs/`: Documentation and usage instructions
+   - `terraform/`: IaC for cloud provisioning
+     - `azure-vm/`: Azure Virtual Machine deployment with CloudInit
+   - `proxmox/`: Scripts for VM creation and management
+   - `scripts/`: Utility scripts for various tasks
+   - `config/`: Host-specific configuration (not in repository)
+   - `config-example/`: Example configuration files
+
+## Development Workflow
+
+This project uses:
+- **Task** (taskfile.dev) as a task runner/build tool
+- **Pre-commit** for code quality and security checks:
+  - Shell script validation with ShellCheck
+  - YAML linting and validation
+  - Terraform validation and formatting
+  - Ansible linting
+  - Python linting with Ruff
+  - Dockerfile linting with Hadolint
+  - Security scanning with Gitleaks and KICS
+- **Docker** and Docker Compose for containerized services
+- **Python** for service management via the `scripts/labctl.py` tool
+- **GitHub Actions** for CI/CD workflows:
+  - Pre-commit checks
+  - Building devcontainer
+  - Building and deploying documentation site
+- **Renovate** for automated dependency updates
+
+## Docker Service Management
+
+The repository uses a custom Python script (`scripts/labctl.py`) to manage Docker services defined in YAML files:
+
+1. Services are organized by category (security, media, tools, etc.)
+2. Each service has a YAML definition file with container specifications
+3. Host-specific configuration is defined in `config/docker/<hostname>/services.yaml`
+4. Environment variables are loaded from `.env` files in the config directory
+5. The `labctl.py` script supports operations: up, down, restart, recreate, update, pull, config.
+
+When adding or modifying services:
+1. Create or edit the YAML file in the appropriate category directory
+2. Add the service to the host configuration in `config/docker/<hostname>/services.yaml`
+3. Provide any required environment variables in the appropriate `.env` files
+4. Deploy using `task docker:apply` or using the specific service command
+
+## File Structure
+
+Key directories and their purposes:
+
+```text
+/
+├── ansible/         # Ansible configuration for server setup
+│   ├── playbooks/   # Main playbooks for different environments
+│   └── roles/       # Individual roles for specific configurations
+├── docker/          # Docker Compose files for services
+│   ├── security/    # Auth and security services
+│   ├── media/       # Media services
+│   ├── storage/     # Storage services
+│   ├── monitoring/  # Monitoring services
+│   ├── ai/          # AI-related services
+│   └── tools/       # Various utility services
+├── docs/            # Documentation
+├── terraform/       # Terraform configurations
+│   └── azure-vm/    # Azure VM deployment with CloudInit
+└── scripts/         # Utility scripts
+```
+
+When contributing to this repository, follow the pre-commit rules defined in `.pre-commit-config.yaml` which includes linting for shell scripts, Dockerfiles, YAML files, Ansible playbooks, and Terraform configurations.