From 1471e432297ba44742741d3e313c3d656ade8560 Mon Sep 17 00:00:00 2001 From: wompmacho Date: Fri, 29 May 2026 23:53:45 +0000 Subject: [PATCH] adding mcp --- ai/plan.md | 114 +++++++++++++++++++ docker_compose/homelabel/docker-compose.yaml | 15 +++ 2 files changed, 129 insertions(+) create mode 100644 ai/plan.md diff --git a/ai/plan.md b/ai/plan.md new file mode 100644 index 0000000..ef1cb05 --- /dev/null +++ b/ai/plan.md @@ -0,0 +1,114 @@ +# AI Agent Infrastructure Strategy: Homelab Management + +This document establishes the architecture, workflow rules, and skill definitions for an AI agent to interface with the self-hosted environment using the Model Context Protocol (MCP) and local system aliases. + +--- + +## 1. Primary AI Workspace and Persistence Directive + +The agent must treat the `/srv/configs/ai` directory as its absolute source of truth for its own configuration, execution memory, and custom skill scripts. + +### Operational Rules + +* **Storage Location:** All agent workflows, system prompts, automated rules, markdown runbooks, and custom skill definitions *must* be stored in `/srv/configs/ai/`. +* **State Management:** Before executing any systemic infrastructure review, the agent must read the current context files in this directory to ensure it is operating under the latest user definitions. +* **No Side Effects:** The agent is strictly prohibited from writing or modifying configuration files outside of this path unless explicitly authorized by the user during an interactive session. + +--- + +## 2. Homelable MCP Server Integration + +The agent leverages the Model Context Protocol to interface directly with the `homelable-mcp` container running locally. This allows the agent to bind physical network topologies to visual infrastructure diagrams. + +### Connection Architecture + +* **Location:** Co-located on the same local host node. +* **Transport Method:** Server-Sent Events (SSE) or local port binding. +* **API Endpoint:** `http://localhost:8001` + +### Capabilities Matrix + +| Permission | Action | Operational Boundaries | +| ---------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | +| **Read** | List all nodes, edges, full canvas, pending devices, scan history. | Executed proactively during an audit cycle. | +| **Write** | Add/update/delete nodes and edges, trigger network scans, approve/hide discovered devices. | **DISABLED BY DEFAULT.** Requires explicit, per-action user confirmation. | + +--- + +## 3. Host System Execution Environment & Aliases + +The agent interacts with the host infrastructure by executing commands directly within the host shell session. It relies on system aliases defined in the central configuration file. + +* **Alias Configuration File:** `/srv/configs/.bash_aliases` + +### Required Core Aliases + +The agent must parse and respect the following explicit wrappers found in the alias file: + +* `docker-service`: Used to query container states, image updates, and running stacks. +* `nginx`: Used to inspect reverse proxy server blocks, active upstreams, and active domain routings. + +--- + +## 4. Skill Definition: Infrastructure Reconciliation & Audit + +### Skill Name + +`review_homelab_infrastructure` + +### Objective + +Cross-reference the active compute and reverse-proxy states against the `homelable` canvas topology and the primary markdown infrastructure log. + +### Source of Truth Inventory Documentation + +* **Target File:** `/srv/docs/public/projects/homelab/homelab_Infra.md` +* **Policy:** The agent must maintain and preserve the existing structural formatting of this file when suggesting updates. + +### Execution Workflow + +``` +[Trigger: Audit Command] + │ + ▼ +┌────────────────────────────────────────────────────────┐ +│ 1. Parse aliases via `/srv/configs/.bash_aliases` │ +│ 2. Read active inventory from `homelab_Infra.md` │ +│ 3. Fetch live container states via `docker-service` │ +│ 4. Fetch proxy mappings via host `nginx` commands │ +│ 5. Pull active topology via Homelable MCP (Port 8001) │ +└─────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────┐ +│ Perform 3-Way Reconciliation │ +│ (homelab_Infra.md vs. Live States vs. MCP Canvas) │ +└─────────────────────────┬──────────────────────────────┘ + │ + ▼ +┌────────────────────────────────────────────────────────┐ +│ Generate Diff Report & Proposed Changes (Markdown) │ +└─────────────────────────┬──────────────────────────────┘ + │ + ▼ + { User Explicitly Approves? } + / \ + (Approved) (Denied) + / \ + ▼ ▼ +┌─────────────────────────┐ ┌─────────────────────────┐ +│ - Update MCP Canvas │ │ Abort & Log Audit │ +│ - Append/Modify │ │ Failure in Workspace │ +│ homelab_Infra.md │ │ (/srv/configs/ai/) │ +└─────────────────────────┘ └─────────────────────────┘ + +``` + +### Safety and Guardrails + +> [!IMPORTANT] +> **Strict Read-Only Default:** The agent is explicitly forbidden from making automatic writes or commits. +> * **No silent canvas updates:** Every node change, edge modification, or scan approval on the Homelable MCP requires manual confirmation. +> * **No silent documentation updates:** Under no circumstances should the agent modify `/srv/docs/public/projects/homelab/homelab_Infra.md` without presenting a clear diff block and receiving confirmation first. +> +> \ No newline at end of file diff --git a/docker_compose/homelabel/docker-compose.yaml b/docker_compose/homelabel/docker-compose.yaml index 8be8b17..28f737c 100644 --- a/docker_compose/homelabel/docker-compose.yaml +++ b/docker_compose/homelabel/docker-compose.yaml @@ -5,6 +5,8 @@ image: ghcr.io/pouzor/homelable-backend:latest container_name: homelable-backend restart: unless-stopped + env_file: + - .env environment: - AUTH_USERNAME=${AUTH_USERNAME} - AUTH_PASSWORD_HASH=${AUTH_PASSWORD_HASH} # Use a bcrypt hash for security @@ -15,6 +17,19 @@ ports: - "${HOMELABEL_BACK_PORT}:8000" + mcp: + image: ghcr.io/pouzor/homelable-mcp:latest + container_name: homelable-mcp + restart: unless-stopped + env_file: + - .env + ports: + - "8001:8001" + environment: + BACKEND_URL: "http://backend:8000" + depends_on: + - backend + frontend: #image: ghcr.io/pouzor/homelable-frontend-standalone:latest # standalone version image: ghcr.io/pouzor/homelable-frontend:latest