homelab-mcp

# Homelab Infrastructure - AI Agent Instructions ## Project Metadata **Project:** Homelab MCP Servers **Repository:** https://github.com/bjeans/homelab-mcp **Version:** 1.0.0 (Released: 2025-10-11) **License:** MIT **Documentation:** README.md, SECURITY.md, CONTRIBUTING.md in repository **About:** Open-source MCP server collection for managing homelab infrastructure through Claude Desktop. Provides real-time monitoring of Docker/Podman, Ollama AI, Pi-hole DNS, Unifi networks, and Ansible inventory. ## Project Context This is a homelab MCP (Model Context Protocol) server collection providing real-time infrastructure monitoring and management for Claude Desktop. **Key insight**: This is production infrastructure with specialized MCP servers monitoring hosts across multiple services. ## Architecture Overview **Core Pattern**: Configuration hierarchy with Ansible inventory as single source of truth → .env fallback → defaults ### Example Infrastructure - **Primary Server** - Docker, LiteLLM proxy, Ollama, Pi-hole, automation - **Secondary Server** - Docker, Ollama, Pi-hole, Home Assistant - **Storage Server** - Rocky Linux, Podman, NAS, Ollama - **Monitoring Server** - Docker monitoring tools ## MCP Server Architecture **Critical**: Each MCP server follows async pattern with `@server.list_tools()` and `@server.call_tool()` decorators. All return `list[types.TextContent]`. ### Production Monitors - **ansible_mcp_server.py** - Infrastructure source of truth from Ansible inventory - **docker_mcp_podman.py** - Container monitoring across Docker and Podman hosts - **ollama_mcp.py** - AI model tracking with LiteLLM proxy support - **pihole_mcp.py** - DNS filtering stats from Pi-hole instances - **unifi_mcp_optimized.py** - Network monitoring via Unifi controller - **ping_mcp_server.py** - Network connectivity testing (ICMP ping) ### Development Tools - **mcp_registry_inspector.py** - **Unique capability**: Direct file read/write for MCP development ## Configuration Patterns ### Three-Tier Config Hierarchy 1. **Ansible Inventory** (Primary) - Path configured in `ANSIBLE_INVENTORY_PATH` 2. **Environment Variables** (Fallback) - `.env` file (gitignored) 3. **Defaults** (Last resort) - Generic defaults in source ### Essential Files - `.env.example` - Configuration template (safe to commit) - `requirements.txt` - Python dependencies - `PROJECT_INSTRUCTIONS.md` - Detailed usage guide (gitignored) - `LICENSE` - MIT License - `CHANGELOG.md` - Version history ## Development Standards ### MCP Server Pattern (Required) ```python import mcp.types as types from mcp.server import Server from mcp.server.stdio import stdio_server server = Server("server-name") @server.list_tools() async def list_tools() -> list[types.Tool]: return [types.Tool(...)] @server.call_tool() async def call_tool(name: str, arguments: dict) -> list[types.TextContent]: return [types.TextContent(type="text", text="result")] async def main(): async with stdio_server() as (read_stream, write_stream): await server.run(read_stream, write_stream) ``` ### Critical Rules - **Logging**: Use `logging.basicConfig(stream=sys.stderr)` - stdout conflicts with MCP protocol - **Config Loading**: Try Ansible → .env → defaults (see `docker_mcp_podman.py` for example) - **Windows Paths**: Use `Path()` objects, mind backslashes - **Dependencies**: Async HTTP with `aiohttp`, YAML with `pyyaml` ### Never Hardcode Infrastructure Values Use the three-tier config hierarchy. Example: `pihole_mcp.py` loads Pi-hole endpoints from Ansible inventory first. ## Key Developer Workflows ### Testing MCP Servers 1. Make changes to `.py` file 2. Restart Claude Desktop (required for MCP reload) 3. Test functionality through Claude chat 4. Check logs via `logging` to stderr (not visible in Claude) ### Adding New Infrastructure 1. **Always** add to Ansible inventory first (`ansible_hosts.yml`) 2. MCP servers auto-discover via inventory parsing 3. Add secrets to `.env` only if needed 4. Test with `ansible-inventory` MCP to verify discovery ### Using mcp_registry_inspector **Unique capability**: Direct file modification ```python # Can read any MCP file read_mcp_file("docker_mcp_podman.py") # Can write/update MCP files directly write_mcp_file("new_server.py", content) ``` ### Contributing to Project 1. Review CONTRIBUTING.md and SECURITY.md on GitHub 2. Fork repository at https://github.com/bjeans/homelab-mcp 3. Follow coding standards and security guidelines 4. Test thoroughly with real infrastructure 5. Run `pre_publish_check.py` before committing 6. Submit PR with clear description ## Security Guidelines ### Critical Security Rules - **Never commit** `.env`, `ansible_hosts.yml`, or `PROJECT_INSTRUCTIONS.md` - **Always use** environment variables for API keys and passwords - **Run** `pre_publish_check.py` before every git push - **Install** git pre-push hook: `python install_git_hook.py` - See SECURITY.md for comprehensive security guidelines ### Git Pre-Push Hook Automatically runs security checks before every push: ```bash # Install once python install_git_hook.py # Bypass only in emergencies git push --no-verify ``` ## Critical Gotchas ### Windows Environment - Use `Path()` objects for file paths (handles backslashes) - PowerShell is default shell (`pwsh.exe`) - Config hierarchy prevents hardcoded paths/IPs ### MCP Protocol Constraints - **Never** print to stdout (breaks MCP communication) - All logging must go to `sys.stderr` - Must return `list[types.TextContent]` from tool calls - Claude Desktop restart required after code changes ### Production Infrastructure - Multiple hosts across VLANs and services - Real services with active DNS queries - Use Ansible inventory, not hardcoded values - Test changes carefully - this affects real infrastructure ### Open Source Project - **Never include** real IP addresses, hostnames, or credentials in code - Use generic examples (192.168.1.x, server1, server2) - All example files must use `.example` suffix - Remember: code is public at https://github.com/bjeans/homelab-mcp ## File Patterns - MCP servers: `{service}_mcp.py` or `{service}_mcp_{variant}.py` - Config templates: `.example` suffix (safe to commit) - Archives: `archive-ignore/` directory (gitignored) - Real configs: `.env`, `ansible_hosts.yml`, `PROJECT_INSTRUCTIONS.md` (gitignored) **Dependencies**: `mcp`, `aiohttp`, `pyyaml`, `requests` (see `requirements.txt`) ## Project Links - **Repository:** https://github.com/bjeans/homelab-mcp - **Issues:** https://github.com/bjeans/homelab-mcp/issues - **Discussions:** https://github.com/bjeans/homelab-mcp/discussions - **Security:** See SECURITY.md for vulnerability reporting