Add adoption-focused examples, contract docs, and CLI polish

examples/agent_vm_run.py

@@ -0,0 +1,62 @@
+"""Provider-agnostic agent tool example centered on vm_run."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from pyro_mcp import Pyro
+
+VM_RUN_TOOL: dict[str, Any] = {
+    "name": "vm_run",
+    "description": "Run one command in an ephemeral Firecracker VM and clean it up.",
+    "input_schema": {
+        "type": "object",
+        "properties": {
+            "profile": {"type": "string"},
+            "command": {"type": "string"},
+            "vcpu_count": {"type": "integer"},
+            "mem_mib": {"type": "integer"},
+            "timeout_seconds": {"type": "integer", "default": 30},
+            "ttl_seconds": {"type": "integer", "default": 600},
+            "network": {"type": "boolean", "default": False},
+        },
+        "required": ["profile", "command", "vcpu_count", "mem_mib"],
+    },
+}
+
+
+def call_vm_run(arguments: dict[str, Any]) -> dict[str, Any]:
+    pyro = Pyro()
+    return pyro.run_in_vm(
+        profile=str(arguments["profile"]),
+        command=str(arguments["command"]),
+        vcpu_count=int(arguments["vcpu_count"]),
+        mem_mib=int(arguments["mem_mib"]),
+        timeout_seconds=int(arguments.get("timeout_seconds", 30)),
+        ttl_seconds=int(arguments.get("ttl_seconds", 600)),
+        network=bool(arguments.get("network", False)),
+    )
+
+
+def main() -> None:
+    tool_arguments: dict[str, Any] = {
+        "profile": "debian-git",
+        "command": "git --version",
+        "vcpu_count": 1,
+        "mem_mib": 1024,
+        "timeout_seconds": 30,
+        "network": False,
+    }
+    tool_call: dict[str, Any] = {
+        "name": "vm_run",
+        "arguments": tool_arguments,
+    }
+
+    print(json.dumps({"tool": VM_RUN_TOOL, "tool_call": tool_call}, indent=2, sort_keys=True))
+    result = call_vm_run(tool_arguments)
+    print(json.dumps({"tool_result": result}, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

examples/mcp_client_config.md

@@ -0,0 +1,35 @@
+# MCP Client Config Example
+
+`pyro-mcp` is intended to be exposed to LLM clients through the public `pyro` CLI.
+
+Generic stdio MCP configuration using `uvx`:
+
+```json
+{
+  "mcpServers": {
+    "pyro": {
+      "command": "uvx",
+      "args": ["--from", "pyro-mcp", "pyro", "mcp", "serve"]
+    }
+  }
+}
+```
+
+If `pyro-mcp` is already installed locally, the same server can be configured with:
+
+```json
+{
+  "mcpServers": {
+    "pyro": {
+      "command": "pyro",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+Primary tool for most agents:
+
+- `vm_run`
+
+Use lifecycle tools only when the agent needs persistent VM state across multiple tool calls.

examples/python_lifecycle.py

@@ -0,0 +1,30 @@
+"""Manage VM lifecycle directly through the public Python SDK."""
+
+from __future__ import annotations
+
+import json
+
+from pyro_mcp import Pyro
+
+
+def main() -> None:
+    pyro = Pyro()
+    created = pyro.create_vm(
+        profile="debian-git",
+        vcpu_count=1,
+        mem_mib=1024,
+        ttl_seconds=600,
+        network=False,
+    )
+    vm_id = str(created["vm_id"])
+
+    try:
+        pyro.start_vm(vm_id)
+        result = pyro.exec_vm(vm_id, command="git --version", timeout_seconds=30)
+        print(json.dumps(result, indent=2, sort_keys=True))
+    finally:
+        pyro.delete_vm(vm_id)
+
+
+if __name__ == "__main__":
+    main()

examples/python_run.py

@@ -0,0 +1,24 @@
+"""Run one command in an ephemeral VM through the public Python SDK."""
+
+from __future__ import annotations
+
+import json
+
+from pyro_mcp import Pyro
+
+
+def main() -> None:
+    pyro = Pyro()
+    result = pyro.run_in_vm(
+        profile="debian-git",
+        command="git --version",
+        vcpu_count=1,
+        mem_mib=1024,
+        timeout_seconds=30,
+        network=False,
+    )
+    print(json.dumps(result, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()