thaloco/pyro-mcp
1
Fork 0
Code Pull requests Releases Packages Activity Actions

Add opinionated MCP modes for workspace workflows

Browse source 
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.
This commit is contained in:
Thales Maciel 2026-03-13 20:00:35 -03:00
parent dc86d84e96
commit d0cf6d8f21
33 changed files with 1034 additions and 274 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/integrations.md
View file

@ -13,7 +13,29 @@ 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 Default
## 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
@ -43,22 +65,25 @@ snapshots, secrets, network policy, or disk tools.
Use the helper flow before the raw host CLI commands:
```bash
pyro host connect claude-code
pyro host connect codex
pyro host print-config opencode
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, preserve the current
`workspace-core` default, and make it obvious how to repair drift later.
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
pyro host connect claude-code --mode cold-start
```
Repair:
@ -70,14 +95,14 @@ pyro host repair claude-code
Package without install:
```bash
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
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 --project-path /abs/path/to/repo
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode cold-start --project-path /abs/path/to/repo
```
Already installed:
@ -96,7 +121,7 @@ Reference:
Preferred:
```bash
pyro host connect codex
pyro host connect codex --mode repro-fix
```
Repair:
@ -108,14 +133,14 @@ pyro host repair codex
Package without install:
```bash
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
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 --project-path /abs/path/to/repo
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --mode repro-fix --project-path /abs/path/to/repo
```
Already installed:
@ -150,7 +175,7 @@ Minimal `opencode.json` snippet:
"pyro": {
"type": "local",
"enabled": true,
"command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve"]
"command": ["uvx", "--from", "pyro-mcp", "pyro", "mcp", "serve", "--mode", "repro-fix"]
}
}
}
@ -165,8 +190,9 @@ array.
## Generic MCP Fallback
Use this only when the host expects a plain `mcpServers` JSON config and does
not already have a dedicated example in the repo:
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)