Add host-specific MCP onramps for major chat clients
Ship first-class MCP setup examples for Claude Code, Codex, and OpenCode so new users can copy one exact command or config instead of translating the generic MCP template by hand. Reposition the docs to surface those host-specific examples before the generic config fallback, keep workspace-core as the recommended profile everywhere user-facing, and retain Claude Desktop/Cursor as secondary fallback examples. Bump the package and catalog to 3.11.0, mark the roadmap milestone done, and add docs-alignment coverage that pins the new examples to the canonical workspace-core server command and the expected OpenCode config shape. Validation: - uv lock - ./.venv/bin/pytest --no-cov tests/test_cli.py - UV_CACHE_DIR=.uv-cache make check - UV_CACHE_DIR=.uv-cache make dist-check
This commit is contained in:
parent
79a7d71d3b
commit
68d8e875e0
15 changed files with 211 additions and 28 deletions
|
|
@ -22,7 +22,7 @@ Networking: tun=yes ip_forward=yes
|
|||
|
||||
```bash
|
||||
$ uvx --from pyro-mcp pyro env list
|
||||
Catalog version: 3.10.0
|
||||
Catalog version: 3.11.0
|
||||
debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
|
||||
debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
|
||||
debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
|
||||
|
|
@ -116,12 +116,21 @@ $ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID app --secret-env
|
|||
$ uvx --from pyro-mcp pyro workspace create debian:12 --network-policy egress+published-ports
|
||||
$ uvx --from pyro-mcp pyro workspace service start WORKSPACE_ID app --ready-http http://127.0.0.1:8080/ --publish 18080:8080 -- ./start-app
|
||||
$ uvx --from pyro-mcp pyro mcp serve --profile workspace-core
|
||||
$ claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --profile workspace-core
|
||||
$ codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --profile workspace-core
|
||||
```
|
||||
|
||||
For most chat hosts, `workspace-core` is the recommended first MCP profile.
|
||||
Move to `workspace-full` only when the host truly needs shells, services,
|
||||
snapshots, secrets, network policy, or disk tools.
|
||||
|
||||
Host-specific MCP starts:
|
||||
|
||||
- Claude Code: [examples/claude_code_mcp.md](../examples/claude_code_mcp.md)
|
||||
- Codex: [examples/codex_mcp.md](../examples/codex_mcp.md)
|
||||
- OpenCode: [examples/opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
||||
- Generic MCP config: [examples/mcp_client_config.md](../examples/mcp_client_config.md)
|
||||
|
||||
`pyro demo` proves the one-shot create/start/exec/delete VM lifecycle works end to end.
|
||||
|
||||
Once that stable workspace flow works, continue with the five recipe docs in
|
||||
|
|
@ -259,7 +268,7 @@ State: started
|
|||
Use `--seed-path` when the workspace should start from a host directory or a local
|
||||
`.tar` / `.tar.gz` / `.tgz` archive instead of an empty `/workspace`. Use
|
||||
`pyro workspace sync push` when you need to import later host-side changes into a started
|
||||
workspace. Sync is non-atomic in `3.10.0`; if it fails partway through, prefer `pyro workspace reset`
|
||||
workspace. Sync is non-atomic in `3.11.0`; if it fails partway through, prefer `pyro workspace reset`
|
||||
to recover from `baseline` or one named snapshot. Use `pyro workspace diff` to compare the current
|
||||
`/workspace` tree to its immutable create-time baseline, `pyro workspace snapshot *` to create
|
||||
named checkpoints, and `pyro workspace export` to copy one changed file or directory back to the
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ uvx --from pyro-mcp pyro env list
|
|||
Expected output:
|
||||
|
||||
```bash
|
||||
Catalog version: 3.10.0
|
||||
Catalog version: 3.11.0
|
||||
debian:12 [installed|not installed] Debian 12 environment with Git preinstalled for common agent workflows.
|
||||
debian:12-base [installed|not installed] Minimal Debian 12 environment for shell and core Unix tooling.
|
||||
debian:12-build [installed|not installed] Debian 12 environment with Git and common build tools preinstalled.
|
||||
|
|
@ -243,6 +243,30 @@ For most chat-host integrations, start with `workspace-core`:
|
|||
uvx --from pyro-mcp pyro mcp serve --profile workspace-core
|
||||
```
|
||||
|
||||
Copy-paste host-specific starts:
|
||||
|
||||
- Claude Code: [examples/claude_code_mcp.md](../examples/claude_code_mcp.md)
|
||||
- Codex: [examples/codex_mcp.md](../examples/codex_mcp.md)
|
||||
- OpenCode: [examples/opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
||||
- Generic MCP config: [examples/mcp_client_config.md](../examples/mcp_client_config.md)
|
||||
|
||||
Claude Code:
|
||||
|
||||
```bash
|
||||
claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --profile workspace-core
|
||||
```
|
||||
|
||||
Codex:
|
||||
|
||||
```bash
|
||||
codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --profile workspace-core
|
||||
```
|
||||
|
||||
OpenCode uses the `mcp`/`type: "local"` config shape shown in
|
||||
[examples/opencode_mcp_config.json](../examples/opencode_mcp_config.json). If
|
||||
`pyro-mcp` is already installed, replace the `uvx --from pyro-mcp pyro`
|
||||
command with `pyro` in the same host-specific command or config shape.
|
||||
|
||||
Use profile progression like this:
|
||||
|
||||
- `workspace-core`: recommended first profile for normal persistent chat editing
|
||||
|
|
@ -296,7 +320,7 @@ the identifier programmatically, use `--id-only` for only the identifier or `--j
|
|||
workspace payload. Use `--seed-path`
|
||||
when the workspace should start from a host directory or a local `.tar` / `.tar.gz` / `.tgz`
|
||||
archive. Use `pyro workspace sync push` for later host-side changes to a started workspace. Sync
|
||||
is non-atomic in `3.10.0`; if it fails partway through, prefer `pyro workspace reset` to recover
|
||||
is non-atomic in `3.11.0`; if it fails partway through, prefer `pyro workspace reset` to recover
|
||||
from `baseline` or one named snapshot. Use `pyro workspace diff` to compare the current workspace
|
||||
tree to its immutable create-time baseline, `pyro workspace snapshot *` to capture named
|
||||
checkpoints, and `pyro workspace export` to copy one changed file or directory back to the host. Use
|
||||
|
|
|
|||
|
|
@ -63,12 +63,15 @@ Profile progression:
|
|||
- `pyro mcp serve --profile workspace-core` for the normal persistent chat loop
|
||||
- `pyro mcp serve --profile workspace-full` only when the model truly needs advanced workspace tools
|
||||
|
||||
Starter config:
|
||||
Host-specific onramps:
|
||||
|
||||
- [examples/mcp_client_config.md](../examples/mcp_client_config.md)
|
||||
- [examples/claude_desktop_mcp_config.json](../examples/claude_desktop_mcp_config.json)
|
||||
- [examples/cursor_mcp_config.json](../examples/cursor_mcp_config.json)
|
||||
- [docs/use-cases/README.md](use-cases/README.md)
|
||||
- Claude Code: [examples/claude_code_mcp.md](../examples/claude_code_mcp.md)
|
||||
- Codex: [examples/codex_mcp.md](../examples/codex_mcp.md)
|
||||
- OpenCode: [examples/opencode_mcp_config.json](../examples/opencode_mcp_config.json)
|
||||
- Generic MCP config: [examples/mcp_client_config.md](../examples/mcp_client_config.md)
|
||||
- Claude Desktop fallback: [examples/claude_desktop_mcp_config.json](../examples/claude_desktop_mcp_config.json)
|
||||
- Cursor fallback: [examples/cursor_mcp_config.json](../examples/cursor_mcp_config.json)
|
||||
- Use-case recipes: [docs/use-cases/README.md](use-cases/README.md)
|
||||
|
||||
## Direct Python SDK
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ goal:
|
|||
make the core agent-workspace use cases feel trivial from a chat-driven LLM
|
||||
interface.
|
||||
|
||||
Current baseline is `3.10.0`:
|
||||
Current baseline is `3.11.0`:
|
||||
|
||||
- the stable workspace contract exists across CLI, SDK, and MCP
|
||||
- one-shot `pyro run` still exists as the narrow entrypoint
|
||||
|
|
@ -63,7 +63,7 @@ The remaining UX friction for a technically strong new user is now narrower:
|
|||
7. [`3.8.0` Chat-Host Onramp And Recommended Defaults](llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md) - Done
|
||||
8. [`3.9.0` Content-Only Reads And Human Output Polish](llm-chat-ergonomics/3.9.0-content-only-reads-and-human-output-polish.md) - Done
|
||||
9. [`3.10.0` Use-Case Smoke Trust And Recipe Fidelity](llm-chat-ergonomics/3.10.0-use-case-smoke-trust-and-recipe-fidelity.md) - Done
|
||||
10. [`3.11.0` Host-Specific MCP Onramps](llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md)
|
||||
10. [`3.11.0` Host-Specific MCP Onramps](llm-chat-ergonomics/3.11.0-host-specific-mcp-onramps.md) - Done
|
||||
11. [`4.0.0` Workspace-Core Default Profile](llm-chat-ergonomics/4.0.0-workspace-core-default-profile.md)
|
||||
|
||||
Completed so far:
|
||||
|
|
@ -90,12 +90,12 @@ Completed so far:
|
|||
transcript separation for files that do not end with a trailing newline.
|
||||
- `3.10.0` aligned the five guest-backed use-case smokes with their recipe docs and promoted
|
||||
`make smoke-use-cases` as the trustworthy verification path for the advertised workspace flows.
|
||||
- `3.11.0` added exact host-specific MCP onramps for Claude Code, Codex, and OpenCode so new
|
||||
chat-host users can copy one known-good setup example instead of translating the generic MCP
|
||||
config manually.
|
||||
|
||||
Planned next:
|
||||
|
||||
- `3.11.0` adds exact host-specific onramps for Claude, Codex, and OpenCode so
|
||||
a new chat-host user can copy one known-good config or command instead of
|
||||
translating the generic MCP example by hand.
|
||||
- `4.0.0` flips the default MCP profile from `workspace-full` to
|
||||
`workspace-core` so the no-flag server entrypoint finally matches the
|
||||
recommended docs path, while keeping explicit opt-in access to the full
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# `3.11.0` Host-Specific MCP Onramps
|
||||
|
||||
Status: Planned
|
||||
Status: Done
|
||||
|
||||
## Goal
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue