thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions
pyro-mcp/docs/public-contract.md
Thales Maciel d0cf6d8f21 Add opinionated MCP modes for workspace workflows 
Introduce explicit repro-fix, inspect, cold-start, and review-eval modes across the MCP server, CLI, and host helpers, with canonical mode-to-tool mappings, narrowed schemas, and mode-specific tool descriptions on top of the existing workspace runtime.

Reposition the docs, host onramps, and use-case recipes so named modes are the primary user-facing startup story while the generic no-mode workspace-core path remains the escape hatch, and update the shared smoke runner to validate repro-fix and cold-start through mode-backed servers.

Validation: UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache uv run pytest --no-cov tests/test_api.py tests/test_server.py tests/test_host_helpers.py tests/test_public_contract.py tests/test_cli.py tests/test_workspace_use_case_smokes.py; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check; UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check; real guest-backed make smoke-repro-fix-loop smoke-cold-start-validation outside the sandbox.
2026-03-13 20:00:35 -03:00

6.1 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:

  • named modes are now the first chat-host story:
    • pyro mcp serve --mode repro-fix
    • pyro mcp serve --mode inspect
    • pyro mcp serve --mode cold-start
    • pyro mcp serve --mode review-eval
  • bare pyro mcp serve remains the generic no-mode path and 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
  • 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.

Named Modes

The supported named modes are:

Mode Intended workflow Key tools
repro-fix reproduce, patch, rerun, diff, export, reset file ops, patch, diff, export, reset, summary
inspect inspect suspicious or unfamiliar code with the smallest persistent surface file list/read, exec, export, summary
cold-start validate a fresh repo and keep services alive long enough to prove readiness exec, export, reset, summary, service tools
review-eval interactive review, checkpointing, shell-driven evaluation, and export shell tools, snapshot tools, diff/export, summary

Use the generic no-mode path when one of those named modes feels too narrow for the job.

Generic 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_summary
  • 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
  • review the current session in one concise summary
  • 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 mode Doc
Cold-start repo validation cold-start use-cases/cold-start-repo-validation.md
Repro plus fix loop repro-fix use-cases/repro-fix-loop.md
Parallel isolated workspaces repro-fix use-cases/parallel-workspaces.md
Unsafe or untrusted code inspection inspect use-cases/untrusted-inspection.md
Review and evaluation workflows review-eval 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.