thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions
pyro-mcp/docs/public-contract.md
Thales Maciel 535efc6919 Add project-aware chat startup defaults 
Make repo-root chat startup native by letting MCP servers carry a default project source for workspace creation. When a chat host starts from a Git checkout, workspace_create can now omit seed_path and inherit the server startup source; explicit --project-path and clean-clone --repo-url/--repo-ref paths are supported as fallbacks.

Add project startup resolution and materialization, surface origin_kind/origin_ref in workspace_seed, update chat-host docs and the repro/fix smoke to use project-aware workspace creation, and switch dist-check to uv run pyro so verification stays stable after uv reinstalls.

Validated with uv lock, focused startup/server/CLI pytest coverage, UV_CACHE_DIR=.uv-cache make check, UV_CACHE_DIR=.uv-cache make dist-check, and real guest-backed smokes for both explicit project_path and bare repo-root auto-detection.
2026-03-13 15:51:47 -03:00

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

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.