pyro-mcp/AGENTS.md

AGENTS.md

Repository guidance for contributors and coding agents.

Purpose

This repository ships pyro-mcp, an MCP-compatible package for ephemeral VM lifecycle tools used by coding agents.

Development Workflow

• Use uv for all Python environment and command execution.
• Run make setup after cloning.
• Run make check before opening a PR.
• Use make demo to validate deterministic VM lifecycle execution.
• Use make ollama-demo to validate model-triggered lifecycle tool usage.
• Use make doctor to inspect bundled runtime integrity and host prerequisites.
• If you need full log payloads from the Ollama demo, use make ollama-demo OLLAMA_DEMO_FLAGS=-v.

Quality Gates

• Linting: ruff
• Type checking: mypy (strict mode)
• Tests: pytest with coverage threshold

These checks run in pre-commit hooks and should all pass locally.

Key API Contract

• Public factory: pyro_mcp.create_server()
• Runtime diagnostics CLI: pyro-mcp-doctor
• Current bundled runtime is shim-based unless replaced with a real guest-capable bundle; check make doctor for runtime capabilities.
• Lifecycle tools:
  • vm_list_profiles
  • vm_create
  • vm_start
  • vm_exec
  • vm_stop
  • vm_delete
  • vm_status
  • vm_network_info
  • vm_reap_expired