mcp-homelab: Instructions file for GitHub Copilot

mcp-homelab Code Review Instructions

Project Summary

mcp-homelab is a Python MCP server (built on Anthropic's FastMCP SDK) that gives AI assistants real-time access to homelab infrastructure via SSH and REST APIs. It supports Linux and FreeBSD hosts, Docker container management, Proxmox VE, and OPNsense firewalls.

Tech Stack

• Python 3.10+ — minimum version, use from __future__ import annotations for modern syntax
• Pydantic v2 — config models with strict validation (Literal, BaseModel)
• TypedDict — all tool return types are TypedDict subclasses, not raw dicts
• paramiko — SSH transport (wrapped in core/ssh.py, never used directly in tools)
• httpx — async HTTP for Proxmox/OPNsense APIs (wrapped in core modules)
• pytest + pytest-asyncio — test framework

Design Principles (enforce these in review)

1. Generic over specific — no hardcoded host names; tools take hostname: str parameters that resolve against config.yaml
2. Config-driven — infrastructure knowledge lives in config.yaml, not in code
3. Fail explicitly — raise meaningful exceptions, never swallow errors silently
4. Return structured data — return TypedDicts or Pydantic models, not raw strings
5. Abstract the transport — SSH/HTTP logic stays in core/, tool functions in tools/ never import paramiko or httpx directly
6. Timeout on all I/O — every SSH call and HTTP request must have a timeout
7. Lazy connection — don't connect until a tool is actually called
8. Credential injection — secrets come from env vars (.env), config holds only non-secret metadata
9. Validate on startup — check required env vars exist when server starts, fail fast

Layer Separation

tools/          ← Tool functions only — no transport logic
core/ssh.py     ← SSH transport, connection pooling
core/config.py  ← Config loading, Pydantic models, env validation
config.yaml     ← Host metadata (IPs, users, roles) — NO secrets
.env            ← Secrets only, never committed