homelab_mcp: Instructions file for Codex

AGENTS.md - Project Guidelines for Codex

Project Overview

Homelab MCP Server - A Python Model Context Protocol (MCP) server for AI-powered homelab infrastructure management. Provides 34+ tools for VM management, SSH discovery, service installation, and network topology mapping.

Tech Stack

• Python: 3.12+ (strict typing with mypy)
• Package Manager: uv (preferred) - ultrafast Python package manager
• MCP Framework: mcp[cli] for Model Context Protocol support
• Testing: pytest with pytest-asyncio for async tests
• Code Quality: ruff (linting/formatting), mypy (type checking), bandit (security)
• SSH: asyncssh for async SSH operations
• Database: SQLite for device tracking

Key Commands

# Install dependencies
uv sync

# Run the MCP server
uv run python run_server.py

# Run all tests
uv run pytest

# Run unit tests only (fast, no Docker)
uv run pytest tests/ -m "not integration"

# Run integration tests (requires Docker)
uv run pytest tests/integration/ -m integration -v

# Run specific test file
uv run pytest tests/test_server.py -v

# Code quality checks
uv run ruff check src/ tests/       # Linting
uv run ruff format src/ tests/      # Formatting
uv run mypy src/                    # Type checking
uv run bandit -r src/               # Security scan

# Run full quality check
./scripts/quality-check.sh

Project Structure

src/homelab_mcp/           # Main package
├── server.py              # MCP server with JSON-RPC protocol
├── tools.py               # Tool registry (34 tools defined here)
├── ssh_tools.py           # SSH discovery & hardware detection
├── service_installer.py   # Service installation framework
├── infrastructure_crud.py # Infrastructure lifecycle management
├── vm_operations.py       # VM/container operations
├── sitemap.py             # Network topology mapping
├── database.py            # SQLite database operations
├── config.py              # Configuration management
├── error_handling.py      # Centralized error handling
├── migration.py           # Database migrations
└── service_templates/     # YAML service definitions

tests/                     # Test suite
├── integration/           # Integration tests (require Docker)
└── test_*.py             # Unit tests