Thales Maciel
899a6760c4
Add a dedicated pyro host surface for supported chat hosts so Claude Code, Codex, and OpenCode users can connect or repair the canonical MCP setup without hand-writing raw commands or config edits. Implement the shared host helper layer and wire it through the CLI with connect, print-config, doctor, and repair, all generated from the same canonical pyro mcp serve command shape and project-source flags. Update the docs, public contract, examples, changelog, and roadmap so the helper flow becomes the primary onramp while raw host-specific commands remain as reference material. Harden the verification path that this milestone exposed: temp git repos in tests now disable commit signing, socket-based port tests skip cleanly when the sandbox forbids those primitives, and make test still uses multiple cores by default but caps xdist workers to a stable value so make check stays fast and deterministic here. Validation: - uv lock - UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make check - UV_OFFLINE=1 UV_CACHE_DIR=.uv-cache make dist-check
217 lines
4.2 KiB
Markdown
217 lines
4.2 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 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 claude-code
|
|
pyro host connect codex
|
|
pyro host print-config opencode
|
|
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.
|
|
|
|
## Claude Code
|
|
|
|
Preferred:
|
|
|
|
```bash
|
|
pyro host connect claude-code
|
|
```
|
|
|
|
Repair:
|
|
|
|
```bash
|
|
pyro host repair claude-code
|
|
```
|
|
|
|
Package without install:
|
|
|
|
```bash
|
|
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
|
|
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
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
Repair:
|
|
|
|
```bash
|
|
pyro host repair codex
|
|
```
|
|
|
|
Package without install:
|
|
|
|
```bash
|
|
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
|
|
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
|
|
```
|
|
|
|
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"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
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 and 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
|
|
```
|