thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions
pyro-mcp/docs/public-contract.md
Thales Maciel 899a6760c4 Add host bootstrap and repair helpers 
Add a dedicated pyro host surface for supported chat hosts so Claude Code, Codex, and OpenCode users can connect or repair the canonical MCP setup without hand-writing raw commands or config edits.

Implement the shared host helper layer and wire it through the CLI with connect, print-config, doctor, and repair, all generated from the same canonical pyro mcp serve command shape and project-source flags. Update the docs, public contract, examples, changelog, and roadmap so the helper flow becomes the primary onramp while raw host-specific commands remain as reference material.

Harden the verification path that this milestone exposed: temp git repos in tests now disable commit signing, socket-based port tests skip cleanly when the sandbox forbids those primitives, and make test still uses multiple cores by default but caps xdist workers to a stable value so make check stays fast and deterministic here.

Validation:
- uv lock
- UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check
- UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check
2026-03-13 16:46:29 -03:00

5.2 KiB
Raw Blame History

Public Contract

This document describes the chat way to use pyro-mcp in 4.x.

pyro-mcp currently has no users. Expect breaking changes while this chat-host path is still being shaped.

This document is intentionally biased. It describes the path users are meant to follow today:

  • prove the host with the terminal companion commands
  • serve disposable workspaces over MCP
  • connect Claude Code, Codex, or OpenCode
  • use the recipe-backed workflows

This page does not try to document every building block in the repo. It documents the chat-host path the project is actively shaping.

Package Identity

  • distribution name: pyro-mcp
  • public executable: pyro
  • primary product entrypoint: pyro mcp serve

pyro-mcp is a disposable MCP workspace for chat-based coding agents on Linux x86_64 KVM hosts.

Supported Product Path

The intended user journey is:

  1. pyro doctor
  2. pyro env list
  3. pyro env pull debian:12
  4. pyro run debian:12 -- git --version
  5. pyro mcp serve
  6. connect Claude Code, Codex, or OpenCode
  7. run one of the documented recipe-backed workflows
  8. validate the whole story with make smoke-use-cases

Evaluator CLI

These terminal commands are the documented companion path for the chat-host product:

  • pyro doctor
  • pyro env list
  • pyro env pull
  • pyro run
  • pyro demo

What to expect from that path:

  • pyro run <environment> -- <command> defaults to 1 vCPU / 1024 MiB
  • pyro run fails if guest boot or guest exec is unavailable unless --allow-host-compat is set
  • pyro run, pyro env list, pyro env pull, pyro env inspect, pyro env prune, and pyro doctor are human-readable by default and return structured JSON with --json
  • the first official environment pull downloads from public Docker Hub into the local environment cache
  • pyro demo proves the one-shot create/start/exec/delete VM lifecycle end to end

These commands exist to validate and debug the chat-host path. They are not the main product destination.

MCP Entry Point

The product entrypoint is:

pyro mcp serve

What to expect:

  • bare pyro mcp serve starts workspace-core
  • from a repo root, bare pyro mcp serve also auto-detects the current Git checkout so workspace_create can omit seed_path
  • workspace-core is the default product path for chat hosts
  • pyro mcp serve --profile workspace-full explicitly opts into the larger tool surface
  • pyro mcp serve --profile vm-run exposes the smallest one-shot-only surface
  • pyro mcp serve --project-path /abs/path/to/repo is the fallback when the host does not preserve cwd
  • pyro mcp serve --repo-url ... [--repo-ref ...] starts from a clean clone source instead of a local checkout

Host-specific setup docs:

The chat-host bootstrap helper surface is:

  • pyro host connect claude-code
  • pyro host connect codex
  • pyro host print-config opencode
  • pyro host doctor
  • pyro host repair HOST

These helpers wrap the same pyro mcp serve entrypoint and are the preferred setup and repair path for supported hosts.

Chat-Facing Workspace Contract

workspace-core is the normal chat path. It exposes:

  • vm_run
  • workspace_create
  • workspace_list
  • workspace_update
  • workspace_status
  • workspace_sync_push
  • workspace_exec
  • workspace_logs
  • workspace_file_list
  • workspace_file_read
  • workspace_file_write
  • workspace_patch_apply
  • workspace_diff
  • workspace_export
  • workspace_reset
  • workspace_delete

That is enough for the normal persistent editing loop:

  • create one workspace, often without seed_path when the server already has a project source
  • sync or seed repo content
  • inspect and edit files without shell quoting
  • run commands repeatedly in one sandbox
  • diff and export results
  • reset and retry
  • delete the workspace when the task is done

Move to workspace-full only when the chat truly needs:

  • persistent PTY shell sessions
  • long-running services and readiness probes
  • secrets
  • guest networking and published ports
  • stopped-workspace disk inspection

Recipe-Backed Workflows

The documented product workflows are:

Workflow Recommended profile Doc
Cold-start repo validation workspace-full use-cases/cold-start-repo-validation.md
Repro plus fix loop workspace-core use-cases/repro-fix-loop.md
Parallel isolated workspaces workspace-core use-cases/parallel-workspaces.md
Unsafe or untrusted code inspection workspace-core use-cases/untrusted-inspection.md
Review and evaluation workflows workspace-full use-cases/review-eval-workflows.md

Treat this smoke pack as the trustworthy guest-backed verification path for the advertised product:

make smoke-use-cases

The chat-host MCP path above is the thing the docs are intentionally shaping around.