Thales Maciel
d0cf6d8f21
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.
243 lines
5.1 KiB
Markdown
243 lines
5.1 KiB
Markdown
# Chat Host Integrations
|
|
|
|
This page documents the intended product path for `pyro-mcp`:
|
|
|
|
- validate the host with the CLI
|
|
- run `pyro mcp serve`
|
|
- connect a chat host
|
|
- let the agent work inside disposable workspaces
|
|
|
|
`pyro-mcp` currently has no users. Expect breaking changes while this chat-host
|
|
path is still being shaped.
|
|
|
|
Use this page after you have already validated the host and guest execution
|
|
through [install.md](install.md) or [first-run.md](first-run.md).
|
|
|
|
## Recommended Modes
|
|
|
|
Use a named mode when one workflow already matches the job:
|
|
|
|
```bash
|
|
pyro host connect codex --mode repro-fix
|
|
pyro host connect codex --mode inspect
|
|
pyro host connect claude-code --mode cold-start
|
|
pyro host connect claude-code --mode review-eval
|
|
```
|
|
|
|
The mode-backed raw server forms are:
|
|
|
|
```bash
|
|
pyro mcp serve --mode repro-fix
|
|
pyro mcp serve --mode inspect
|
|
pyro mcp serve --mode cold-start
|
|
pyro mcp serve --mode review-eval
|
|
```
|
|
|
|
Use the generic no-mode path only when the named mode feels too narrow.
|
|
|
|
## Generic Default
|
|
|
|
Bare `pyro mcp serve` starts `workspace-core`. From a repo root, it also
|
|
auto-detects the current Git checkout so the first `workspace_create` can omit
|
|
`seed_path`. That is the product path.
|
|
|
|
```bash
|
|
pyro mcp serve
|
|
```
|
|
|
|
If the host does not preserve cwd, fall back to:
|
|
|
|
```bash
|
|
pyro mcp serve --project-path /abs/path/to/repo
|
|
```
|
|
|
|
If you are outside a repo checkout entirely, start from a clean clone source:
|
|
|
|
```bash
|
|
pyro mcp serve --repo-url https://github.com/example/project.git
|
|
```
|
|
|
|
Use `--profile workspace-full` only when the chat truly needs shells, services,
|
|
snapshots, secrets, network policy, or disk tools.
|
|
|
|
## Helper First
|
|
|
|
Use the helper flow before the raw host CLI commands:
|
|
|
|
```bash
|
|
pyro host connect codex --mode repro-fix
|
|
pyro host connect codex --mode inspect
|
|
pyro host connect claude-code --mode cold-start
|
|
pyro host connect claude-code --mode review-eval
|
|
pyro host print-config opencode --mode repro-fix
|
|
pyro host doctor
|
|
pyro host repair opencode
|
|
```
|
|
|
|
These helpers wrap the same `pyro mcp serve` entrypoint, make named modes the
|
|
first user-facing story, and still leave the generic no-mode path available
|
|
when a mode is too narrow.
|
|
|
|
## Claude Code
|
|
|
|
Preferred:
|
|
|
|
```bash
|
|
pyro host connect claude-code --mode cold-start
|
|
```
|
|
|
|
Repair:
|
|
|
|
```bash
|
|
pyro host repair claude-code
|
|
```
|
|
|
|
Package without install:
|
|
|
|
```bash
|
|
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start
|
|
claude mcp list
|
|
```
|
|
|
|
If Claude Code launches the server from an unexpected cwd, use:
|
|
|
|
```bash
|
|
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start --project-path /abs/path/to/repo
|
|
```
|
|
|
|
Already installed:
|
|
|
|
```bash
|
|
claude mcp add pyro -- pyro mcp serve
|
|
claude mcp list
|
|
```
|
|
|
|
Reference:
|
|
|
|
- [claude_code_mcp.md](../examples/claude_code_mcp.md)
|
|
|
|
## Codex
|
|
|
|
Preferred:
|
|
|
|
```bash
|
|
pyro host connect codex --mode repro-fix
|
|
```
|
|
|
|
Repair:
|
|
|
|
```bash
|
|
pyro host repair codex
|
|
```
|
|
|
|
Package without install:
|
|
|
|
```bash
|
|
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix
|
|
codex mcp list
|
|
```
|
|
|
|
If Codex launches the server from an unexpected cwd, use:
|
|
|
|
```bash
|
|
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix --project-path /abs/path/to/repo
|
|
```
|
|
|
|
Already installed:
|
|
|
|
```bash
|
|
codex mcp add pyro -- pyro mcp serve
|
|
codex mcp list
|
|
```
|
|
|
|
Reference:
|
|
|
|
- [codex_mcp.md](../examples/codex_mcp.md)
|
|
|
|
## OpenCode
|
|
|
|
Preferred:
|
|
|
|
```bash
|
|
pyro host print-config opencode
|
|
pyro host repair opencode
|
|
```
|
|
|
|
Use the local MCP config shape from:
|
|
|
|
- [opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
|
|
|
Minimal `opencode.json` snippet:
|
|
|
|
```json
|
|
{
|
|
"mcp": {
|
|
"pyro": {
|
|
"type": "local",
|
|
"enabled": true,
|
|
"command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve", "--mode", "repro-fix"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If `pyro-mcp` is already installed, replace `uvx --from pyro-mcp pyro` with
|
|
`pyro` in the same config shape.
|
|
|
|
If OpenCode launches the server from an unexpected cwd, add
|
|
`"--project-path", "/abs/path/to/repo"` after `"serve"` in the same command
|
|
array.
|
|
|
|
## Generic MCP Fallback
|
|
|
|
Use this only when the host expects a plain `mcpServers` JSON config, when the
|
|
named modes are too narrow, and when it does not already have a dedicated
|
|
example in the repo:
|
|
|
|
- [mcp_client_config.md](../examples/mcp_client_config.md)
|
|
|
|
Generic `mcpServers` shape:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"pyro": {
|
|
"command": "uvx",
|
|
"args": ["--from", "pyro-mcp", "pyro", "mcp", "serve"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## When To Use `workspace-full`
|
|
|
|
Stay on bare `pyro mcp serve` unless the chat host truly needs:
|
|
|
|
- persistent PTY shell sessions
|
|
- long-running services and readiness probes
|
|
- secrets
|
|
- guest networking and published ports
|
|
- stopped-workspace disk inspection or raw ext4 export
|
|
|
|
When that is necessary:
|
|
|
|
```bash
|
|
pyro mcp serve --profile workspace-full
|
|
```
|
|
|
|
## Recipe-Backed Workflows
|
|
|
|
Once the host is connected, move to the five real workflows in
|
|
[use-cases/README.md](use-cases/README.md):
|
|
|
|
- cold-start repo validation
|
|
- repro plus fix loops
|
|
- parallel isolated workspaces
|
|
- unsafe or untrusted code inspection
|
|
- review and evaluation workflows
|
|
|
|
Validate the whole story with:
|
|
|
|
```bash
|
|
make smoke-use-cases
|
|
```
|