Skip to content

Developer Guide.md

Latest commit

 

History

History
118 lines (86 loc) · 4.12 KB

Developer Guide.md

File metadata and controls

118 lines (86 loc) · 4.12 KB
Raw

Developer Guide

This guide covers local development, testing, and release work for ProxmoxMCP-Plus.

Local Setup

uv venv
uv pip install -e ".[dev]"
cp proxmox-config/config.example.json proxmox-config/config.json

Set proxmox-config/config.json to a real environment or use a test config path through PROXMOX_MCP_CONFIG.

Common Commands

pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75
ruff check .
mypy src --ignore-missing-imports
pip-audit -r requirements.txt
black .
python main.py
export PROXMOX_API_KEY="${PROXMOX_API_KEY:-$(openssl rand -hex 32)}"
python -m proxmox_mcp.openapi_proxy --host 0.0.0.0 --port 8811 -- python main.py

The coverage gate starts at 60% so CI tracks regressions while coverage is expanded around high-risk tools and the JobStore/OpenAPI boundary. OpenAPI mode requires PROXMOX_API_KEY by default. For local unauthenticated development only, set PROXMOX_ALLOW_NO_AUTH=true.

Project Layout

Path Purpose
main.py bootstrap entrypoint used by the packaged bundle
src/proxmox_mcp/server.py MCP server initialization and tool registration
src/proxmox_mcp/openapi_proxy.py FastAPI wrapper for HTTP/OpenAPI mode
src/proxmox_mcp/config/ config models and loader
src/proxmox_mcp/security/ command policy checks
src/proxmox_mcp/services/jobs.py persistent SQLite-backed job store
src/proxmox_mcp/services/builtin_tool_plugins.py plugin-based tool registration
src/proxmox_mcp/tools/ Proxmox-facing tool implementations
tests/ unit and integration-facing test coverage
docs/wiki/ wiki seed pages

Development Expectations

  • Keep behavior changes covered by tests
  • Prefer clear, typed interfaces for tool contracts
  • Update docs when a tool, config field, or runtime behavior changes
  • Avoid documenting features that are not actually registered in server.py

What To Check When Changing Tools

If you add or change a tool:

  • Update the implementation in src/proxmox_mcp/tools/
  • Register or adjust it in src/proxmox_mcp/services/builtin_tool_plugins.py
  • Update descriptions in src/proxmox_mcp/tools/definitions.py
  • Add or update tests under tests/
  • Update API & Tool Reference if the surface changed

If the tool launches an asynchronous Proxmox task, also:

  • return a stable job_id alongside the raw Proxmox task_id
  • add or update the persisted retry recipe in src/proxmox_mcp/services/jobs.py
  • verify the job is queryable through both MCP tools and the OpenAPI /jobs routes

Configuration Development Notes

The config loader supports:

  • JSON file loading through PROXMOX_MCP_CONFIG
  • Environment-only fallback when no config file is available
  • TLS safety checks that block verify_ssl=false unless security.dev_mode=true
  • MCP transport normalization, including STREAMABLE_HTTP to STREAMABLE
  • jobs.sqlite_path fallback through PROXMOX_JOBS_SQLITE_PATH

If you change config semantics, keep the example files in proxmox-config/ consistent.

Packaging and Release

The package metadata lives in pyproject.toml.

Notable details:

  • Package name: proxmox-mcp-plus
  • Console script: proxmox-mcp = proxmox_mcp.server:main
  • Build backend: hatchling
  • Supported Python versions in metadata: 3.11 and 3.12

Local packaging check:

python -m pip install --upgrade build twine
python -m build
twine check dist/*

Test Coverage Focus

The current tests cover several important behaviors already:

  • tool registration with and without SSH config
  • config validation and TLS safety checks
  • OpenAPI root and health endpoints
  • OpenAPI /metrics and /jobs endpoints
  • VM and container tool behavior
  • backup, storage, ISO, and cluster-related flows
  • SQLite-backed job persistence and retry behavior

When adding a new feature, extend tests in the same area rather than only relying on manual checks.

Documentation Workflow

  • Update README.md for top-level positioning or setup changes
  • Update docs/wiki/ for details, examples, and operational behavior
  • Keep wiki titles stable so the GitHub Wiki URLs do not change