Thales Maciel
535efc6919
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.
157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
- [claude_code_mcp.md](../examples/claude_code_mcp.md)
|
|
- [codex_mcp.md](../examples/codex_mcp.md)
|
|
- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
|
- [mcp_client_config.md](../examples/mcp_client_config.md)
|
|
|
|
## 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](use-cases/cold-start-repo-validation.md) |
|
|
| Repro plus fix loop | `workspace-core` | [use-cases/repro-fix-loop.md](use-cases/repro-fix-loop.md) |
|
|
| Parallel isolated workspaces | `workspace-core` | [use-cases/parallel-workspaces.md](use-cases/parallel-workspaces.md) |
|
|
| Unsafe or untrusted code inspection | `workspace-core` | [use-cases/untrusted-inspection.md](use-cases/untrusted-inspection.md) |
|
|
| Review and evaluation workflows | `workspace-full` | [use-cases/review-eval-workflows.md](use-cases/review-eval-workflows.md) |
|
|
|
|
Treat this smoke pack as the trustworthy guest-backed verification path for the
|
|
advertised product:
|
|
|
|
```bash
|
|
make smoke-use-cases
|
|
```
|
|
|
|
The chat-host MCP path above is the thing the docs are intentionally shaping
|
|
around.
|