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.
171 lines
3.6 KiB
Markdown
171 lines
3.6 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.
|
|
|
|
## 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
|
|
|
|
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
|
|
|
|
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
|
|
```
|