Thales Maciel 535efc6919 Add project-aware chat startup defaults

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.

2026-03-13 15:51:47 -03:00

3.6 KiB

Raw Blame History

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 or 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.

pyro mcp serve

If the host does not preserve cwd, fall back to:

pyro mcp serve --project-path /abs/path/to/repo

If you are outside a repo checkout entirely, start from a clean clone source:

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:

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:

claude mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo

Already installed:

claude mcp add pyro -- pyro mcp serve
claude mcp list

Reference:

claude_code_mcp.md

Codex

Package without install:

codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve
codex mcp list

If Codex launches the server from an unexpected cwd, use:

codex mcp add pyro -- uvx --from pyro-mcp pyro mcp serve --project-path /abs/path/to/repo

Already installed:

codex mcp add pyro -- pyro mcp serve
codex mcp list

Reference:

codex_mcp.md

OpenCode

Use the local MCP config shape from:

opencode_mcp_config.json

Minimal opencode.json snippet:

{
  "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

Generic mcpServers shape:

{
  "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:

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:

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:

make smoke-use-cases

3.6 KiB Raw Blame History