ouroboros-ai 0.26.2.dev37__tar.gz → 0.26.2.dev38__tar.gz

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.26.2.dev37
+Version: 0.26.2.dev38
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/scripts/install.sh

@@ -140,11 +140,9 @@ if [ "$HAS_UV" = true ]; then
 elif [ "$HAS_PIPX" = true ]; then
   INSTALL_METHOD="pipx"
   if [ -n "$PRE_FLAG" ]; then
-    pipx install --pip-args='--pre' "$INSTALL_SPEC" 2>/dev/null \
-      || pipx upgrade --pip-args='--pre' "$INSTALL_SPEC"
+    pipx install --force --pip-args='--pre' "$INSTALL_SPEC"
   else
-    pipx install "$INSTALL_SPEC" 2>/dev/null \
-      || pipx upgrade "$INSTALL_SPEC"
+    pipx install --force "$INSTALL_SPEC"
   fi
 else
   INSTALL_METHOD="pip"
@@ -184,11 +182,11 @@ if command -v claude &>/dev/null; then
 
   # MCP command matches the installer that actually ran in step 3
   if [ "$INSTALL_METHOD" = "uv" ]; then
-    OUROBOROS_ENTRY='{"command":"uvx","args":["--from","ouroboros-ai[claude]","ouroboros","mcp","serve"],"timeout":600}'
+    OUROBOROS_ENTRY='{"command":"uvx","args":["--from","ouroboros-ai[claude]","ouroboros","mcp","serve"]}'
   elif [ "$INSTALL_METHOD" = "pipx" ]; then
-    OUROBOROS_ENTRY='{"command":"ouroboros","args":["mcp","serve"],"timeout":600}'
+    OUROBOROS_ENTRY='{"command":"ouroboros","args":["mcp","serve"]}'
   else
-    OUROBOROS_ENTRY='{"command":"python3","args":["-m","ouroboros","mcp","serve"],"timeout":600}'
+    OUROBOROS_ENTRY='{"command":"python3","args":["-m","ouroboros","mcp","serve"]}'
   fi
 
   # Find a working Python: system python3, or uv-managed python

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/skills/pm/SKILL.md

@@ -15,7 +15,26 @@ PM-focused Socratic interview that produces a Product Requirements Document.
 ToolSearch query: "+ouroboros pm_interview"
 ```
 
-If not found → tell user to run `ooo setup` first. Stop.
+If not found → **diagnose before telling user to run setup**:
+
+1. Check if MCP is already configured:
+   ```bash
+   grep -q '"ouroboros"' ~/.claude/mcp.json 2>/dev/null && echo "CONFIGURED" || echo "NOT_CONFIGURED"
+   ```
+
+2. **If NOT_CONFIGURED** → tell user to run `ooo setup` first. Stop.
+
+3. **If CONFIGURED** → MCP is registered but the server isn't connecting. Do NOT tell the user to run `ooo setup` again. Instead show:
+   ```
+   Ouroboros MCP is configured but not connected.
+
+   Try these steps in order:
+   1. Restart Claude Code (Cmd+Shift+P → "Reload Window" or close/reopen terminal)
+   2. Check MCP status: type /mcp in Claude Code
+   3. If ouroboros shows "error", try: ooo update
+   4. If still failing, re-run: ooo setup
+   ```
+   Stop.
 
 ### Step 2: Start Interview
 

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/skills/setup/SKILL.md

@@ -123,16 +123,44 @@ Runtime backend            [✓] Detected
 
 | Environment | Mode | Action |
 |:------------|:-----|:-------|
-| uvx + uv Python >= 3.12 | **Ready** | Proceed to MCP registration |
-| System Python >= 3.12 | **Ready** | Proceed to MCP registration |
+| uvx + Python >= 3.12 | **Ready** | Proceed to MCP registration (uvx mode — extras always included) |
+| No uvx + `ouroboros` binary in PATH | **Check deps** | Verify `[claude]` extras, then proceed (binary mode) |
+| No uvx + Python >= 3.12 + `python3 -m ouroboros` works | **Check deps** | Verify `[claude]` extras, then proceed (pip mode) |
 | uvx + Python < 3.12 only | **Install needed** | Run `uv python install 3.12` then proceed |
-| No uvx | **Install needed** | Run `curl -LsSf https://astral.sh/uv/install.sh \| sh` then `uv python install 3.12` |
+| No uvx + no ouroboros binary + no pip package | **Install needed** | Install uv first, then proceed |
 
-**IMPORTANT**: If Python >= 3.12 is not available, DO NOT skip to "Plugin-Only mode". Guide the user to install the prerequisites. MCP is required for the full Ouroboros experience.
+**For binary/pip modes — verify `[claude]` extras are installed:**
+
+Check method depends on how ouroboros was installed:
+```bash
+# Detect install method
+pipx list 2>/dev/null | grep -q ouroboros && echo "PIPX" || echo "NOT_PIPX"
+```
+
+- **pipx users** (binary mode, installed via pipx):
+  ```bash
+  pipx runpip ouroboros-ai show claude-agent-sdk 2>/dev/null && echo "DEPS_OK" || echo "DEPS_MISSING"
+  ```
+  If `DEPS_MISSING`: `pipx install --force ouroboros-ai[claude]`
+
+- **pip users** (pip mode):
+  ```bash
+  python3 -c "import claude_agent_sdk" 2>/dev/null && echo "DEPS_OK" || echo "DEPS_MISSING"
+  ```
+  If `DEPS_MISSING`: `python3 -m pip install ouroboros-ai[claude]`
+
+If deps are missing and the user doesn't want to fix manually, recommend uvx:
+```
+Or install uvx (recommended — handles deps automatically):
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+Then re-run: ooo setup
+```
+
+**IMPORTANT**: The MCP server requires one of: (1) uvx, (2) ouroboros binary in PATH, or (3) ouroboros pip-installed. For options 2 and 3, the `[claude]` extra must also be installed. If none are available, guide the user to install uv — do NOT write a non-working fallback to mcp.json.
 
 **If prerequisites are missing, show:**
 ```
-Ouroboros requires Python >= 3.12 for the MCP server.
+Ouroboros requires uvx (recommended) or the ouroboros package installed.
 
 Quick install (< 1 minute):
   curl -LsSf https://astral.sh/uv/install.sh | sh
@@ -173,12 +201,13 @@ This enables:
 
 **Automatically create or update `~/.claude/mcp.json`** (user-level, works across all projects).
 
-Choose the MCP command based on how ouroboros is installed:
-- If `uvx` is available: `{"command": "uvx", "args": ["--from", "ouroboros-ai[claude]", "ouroboros", "mcp", "serve"], "timeout": 600}`
-- If `ouroboros` binary is in PATH (pipx install): `{"command": "ouroboros", "args": ["mcp", "serve"], "timeout": 600}`
-- Fallback (pip install): `{"command": "python3", "args": ["-m", "ouroboros", "mcp", "serve"], "timeout": 600}`
+Choose the MCP command based on how ouroboros is installed (check in order):
+1. If `which uvx` succeeds: `{"command": "uvx", "args": ["--from", "ouroboros-ai[claude]", "ouroboros", "mcp", "serve"]}`
+2. If `which ouroboros` succeeds: `{"command": "ouroboros", "args": ["mcp", "serve"]}`
+3. If `python3 -c "import ouroboros"` succeeds: `{"command": "python3", "args": ["-m", "ouroboros", "mcp", "serve"]}`
+4. If none of the above → **do NOT write to mcp.json**. Instead show the prerequisites message from Step 1 and stop.
 
-If `~/.claude/mcp.json` already exists, merge intelligently (preserve other servers).
+If `~/.claude/mcp.json` already exists, read it, **always overwrite the `ouroboros` key** with the entry above (to fix stale args from older versions), and preserve all other server entries.
 
 **Celebration Checkpoint 2:**
 ```

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/skills/update/SKILL.md

@@ -80,38 +80,46 @@ When the user invokes this skill:
 
 4. **Run update** (if user chose to update):
 
-   a. **Update PyPI package** — detect the original install method and use the same one:
+   a. **Update PyPI package** — detect the original install method and preserve `[claude]` extras:
 
-   Check which installer was used (in priority order):
+   Check which installer was used:
    ```bash
    uv tool list 2>/dev/null | grep -q ouroboros && echo "uv"
    pipx list 2>/dev/null | grep -q ouroboros && echo "pipx"
    ```
 
+   > This skill runs inside Claude Code, so always use `ouroboros-ai[claude]`
+   > (includes `claude-agent-sdk` and `anthropic` required for MCP tools).
+
    - If installed via **uv tool** (most common with install.sh):
      ```bash
      # For pre-release targets:
-     uv tool install --upgrade --prerelease=allow ouroboros-ai
+     uv tool install --upgrade --prerelease=allow ouroboros-ai[claude]
      # For stable targets:
-     uv tool install --upgrade ouroboros-ai
+     uv tool install --upgrade ouroboros-ai[claude]
      ```
 
    - If installed via **pipx**:
+     > `pipx upgrade` cannot add extras to an existing venv — use `install --force` to reinstall with extras.
      ```bash
      # For pre-release targets:
-     pipx upgrade --pip-args='--pre' ouroboros-ai
+     pipx install --force --pip-args='--pre' ouroboros-ai[claude]
      # For stable targets:
-     pipx upgrade ouroboros-ai
+     pipx install --force ouroboros-ai[claude]
      ```
 
    - If installed via **pip** (fallback):
      ```bash
      # For pre-release targets:
-     python3 -m pip install --upgrade --pre ouroboros-ai
+     python3 -m pip install --upgrade --pre ouroboros-ai[claude]
      # For stable targets:
-     python3 -m pip install --upgrade ouroboros-ai
+     python3 -m pip install --upgrade ouroboros-ai[claude]
      ```
 
+   > **Note**: The `[claude]` extra is critical — it installs `claude-agent-sdk` and
+   > `anthropic` which are required for MCP tool execution. Omitting it causes MCP
+   > tools to fail silently at call time.
+
    b. **Update runtime integration**:
 
    For Claude Code:
@@ -125,7 +133,21 @@ When the user invokes this skill:
    ouroboros setup --runtime codex --non-interactive
    ```
 
-   c. **Verify and update CLAUDE.md version marker**:
+   c. **Refresh MCP server config** (fixes stale args from older versions):
+
+   Run the same setup command used in step b to ensure MCP config is current:
+
+   For Claude Code:
+   ```bash
+   ouroboros setup --runtime claude --non-interactive
+   ```
+
+   For Codex CLI (already handled by step b above — skip this step).
+
+   This ensures `~/.claude/mcp.json` has the latest MCP command and args
+   (e.g., `ouroboros-ai[claude]` extras). Skips if already up to date.
+
+   d. **Verify and update CLAUDE.md version marker**:
    ```bash
    NEW_VERSION=$(ouroboros --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+[a-z0-9.]*')
    echo "Installed: v$NEW_VERSION"

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/src/ouroboros/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.26.2.dev37'
-__version_tuple__ = version_tuple = (0, 26, 2, 'dev37')
+__version__ = version = '0.26.2.dev38'
+__version_tuple__ = version_tuple = (0, 26, 2, 'dev38')
 
 __commit_id__ = commit_id = None

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/src/ouroboros/cli/commands/setup.py

@@ -32,6 +32,101 @@ from ouroboros.cli.formatters.panels import (
 )
 from ouroboros.persistence.brownfield import BrownfieldStore
 
+# Canonical MCP args for Claude Code uvx installs — single source of truth.
+_CLAUDE_UVX_ARGS: list[str] = [
+    "--from",
+    "ouroboros-ai[claude]",
+    "ouroboros",
+    "mcp",
+    "serve",
+]
+
+
+def _detect_mcp_entry() -> dict[str, object] | None:
+    """Build the correct MCP entry based on how ouroboros is installed.
+
+    Priority: uvx > ouroboros binary > python3 -m ouroboros (verified).
+    Returns None if no working method is found.
+    Matches the contract in install.sh and skills/setup/SKILL.md.
+    """
+    if shutil.which("uvx"):
+        return {"command": "uvx", "args": list(_CLAUDE_UVX_ARGS)}
+    if shutil.which("ouroboros"):
+        return {"command": "ouroboros", "args": ["mcp", "serve"]}
+    # Only use python3 fallback if ouroboros is actually importable
+    import subprocess
+
+    try:
+        subprocess.run(
+            ["python3", "-c", "import ouroboros"],
+            capture_output=True,
+            timeout=10,
+            check=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    return {"command": "python3", "args": ["-m", "ouroboros", "mcp", "serve"]}
+
+
+def _ensure_claude_mcp_entry() -> None:
+    """Ensure ~/.claude/mcp.json has a correct ouroboros MCP entry.
+
+    Creates the entry if missing (detecting install method), updates stale
+    uvx args (e.g. ouroboros-ai without [claude] extras), and removes the
+    legacy timeout key.  Skips the file write when nothing changed.
+    """
+    mcp_config_path = Path.home() / ".claude" / "mcp.json"
+    mcp_config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    mcp_data: dict = {}
+    if mcp_config_path.exists():
+        mcp_data = json.loads(mcp_config_path.read_text())
+
+    mcp_data.setdefault("mcpServers", {})
+
+    existing = mcp_data["mcpServers"].get("ouroboros")
+    detected = _detect_mcp_entry()
+    needs_write = False
+
+    if existing is None:
+        if detected is None:
+            print_warning(
+                "Cannot register MCP server: no working ouroboros installation found.\n"
+                "Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"
+            )
+            return
+        mcp_data["mcpServers"]["ouroboros"] = detected
+        needs_write = True
+        print_success("Registered MCP server in ~/.claude/mcp.json")
+    else:
+        # Remove legacy timeout key
+        if "timeout" in existing:
+            del existing["timeout"]
+            needs_write = True
+            print_info("Removed legacy MCP timeout override.")
+
+        # Update entry to match currently detected install method, but only
+        # for known standard commands. Custom entries (docker, nix, etc.) are
+        # left untouched so we don't break user-managed configurations.
+        _KNOWN_COMMANDS = {"uvx", "ouroboros", "python3", "python"}
+        if detected is not None and existing.get("command") in _KNOWN_COMMANDS:
+            if (
+                existing.get("command") != detected["command"]
+                or existing.get("args") != detected["args"]
+            ):
+                existing["command"] = detected["command"]
+                existing["args"] = detected["args"]
+                needs_write = True
+                print_info("Updated MCP server entry to match current install method.")
+
+        if not needs_write:
+            print_info("MCP server already registered.")
+
+    if needs_write:
+        with mcp_config_path.open("w") as f:
+            json.dump(mcp_data, f, indent=2)
+
+
 app = typer.Typer(
     name="setup",
     help="Set up Ouroboros for your environment.",
@@ -227,32 +322,9 @@ def _setup_codex(codex_path: str) -> None:
     _register_codex_mcp_server()
     _print_codex_config_guidance(config_path)
 
-    # Also register MCP server for Codex users who also have Claude Code
-    mcp_config_path = Path.home() / ".claude" / "mcp.json"
-    if mcp_config_path.exists() or (Path.home() / ".claude").is_dir():
-        mcp_config_path.parent.mkdir(parents=True, exist_ok=True)
-
-        mcp_data: dict = {}
-        if mcp_config_path.exists():
-            mcp_data = json.loads(mcp_config_path.read_text())
-
-        mcp_data.setdefault("mcpServers", {})
-        entry = mcp_data["mcpServers"].get("ouroboros", {})
-        if not entry:
-            entry = {
-                "command": "uvx",
-                "args": ["--from", "ouroboros-ai", "ouroboros", "mcp", "serve"],
-            }
-        removed_timeout = entry.pop("timeout", None) is not None
-        mcp_data["mcpServers"]["ouroboros"] = entry
-
-        with mcp_config_path.open("w") as f:
-            json.dump(mcp_data, f, indent=2)
-
-        if removed_timeout:
-            print_info("Removed legacy Claude MCP timeout override.")
-        else:
-            print_info("Updated Claude MCP server config.")
+    # Also register/fix MCP server for Codex users who also have Claude Code
+    if (Path.home() / ".claude").is_dir():
+        _ensure_claude_mcp_entry()
 
 
 def _setup_claude(claude_path: str) -> None:
@@ -279,32 +351,8 @@ def _setup_claude(claude_path: str) -> None:
     with config_path.open("w") as f:
         yaml.dump(config_dict, f, default_flow_style=False, sort_keys=False)
 
-    # Register MCP server in ~/.claude/mcp.json
-    mcp_config_path = Path.home() / ".claude" / "mcp.json"
-    mcp_config_path.parent.mkdir(parents=True, exist_ok=True)
-
-    mcp_data: dict = {}
-    if mcp_config_path.exists():
-        mcp_data = json.loads(mcp_config_path.read_text())
-
-    mcp_data.setdefault("mcpServers", {})
-    if "ouroboros" not in mcp_data["mcpServers"]:
-        mcp_data["mcpServers"]["ouroboros"] = {
-            "command": "uvx",
-            "args": ["--from", "ouroboros-ai", "ouroboros", "mcp", "serve"],
-        }
-        with mcp_config_path.open("w") as f:
-            json.dump(mcp_data, f, indent=2)
-        print_success("Registered MCP server in ~/.claude/mcp.json")
-    else:
-        entry = mcp_data["mcpServers"]["ouroboros"]
-        if "timeout" in entry:
-            del entry["timeout"]
-            with mcp_config_path.open("w") as f:
-                json.dump(mcp_data, f, indent=2)
-            print_info("Removed legacy MCP timeout override.")
-        else:
-            print_info("MCP server already registered.")
+    # Register/fix MCP server in ~/.claude/mcp.json
+    _ensure_claude_mcp_entry()
 
     print_success(f"Configured Claude Code runtime (CLI: {claude_path})")
     print_info(f"Config saved to: {config_path}")

{ouroboros_ai-0.26.2.dev37 → ouroboros_ai-0.26.2.dev38}/tests/unit/cli/test_setup.py

@@ -264,9 +264,173 @@ class TestClaudeSetup:
         config_dict = yaml.safe_load(config_path.read_text(encoding="utf-8"))
 
         assert "timeout" not in claude_mcp["mcpServers"]["ouroboros"]
+        # Stale args (ouroboros-ai without [claude]) should be updated
+        assert claude_mcp["mcpServers"]["ouroboros"]["args"] == [
+            "--from",
+            "ouroboros-ai[claude]",
+            "ouroboros",
+            "mcp",
+            "serve",
+        ]
         assert config_dict["orchestrator"]["runtime_backend"] == "claude"
         assert config_dict["llm"]["backend"] == "claude"
 
+    @pytest.mark.parametrize(
+        "which_side_effect, expected_cmd, expected_args",
+        [
+            # uvx available → uvx entry with [claude] extras
+            (
+                lambda cmd: "/usr/local/bin/uvx" if cmd == "uvx" else None,
+                "uvx",
+                ["--from", "ouroboros-ai[claude]", "ouroboros", "mcp", "serve"],
+            ),
+            # no uvx, ouroboros binary available → binary entry
+            (
+                lambda cmd: "/usr/local/bin/ouroboros" if cmd == "ouroboros" else None,
+                "ouroboros",
+                ["mcp", "serve"],
+            ),
+            # no uvx, no binary → python3 -m fallback
+            (
+                lambda _cmd: None,
+                "python3",
+                ["-m", "ouroboros", "mcp", "serve"],
+            ),
+        ],
+        ids=["uvx", "pipx-binary", "pip-fallback"],
+    )
+    def test_setup_claude_creates_new_entry_per_install_method(
+        self,
+        tmp_path: Path,
+        which_side_effect,
+        expected_cmd: str,
+        expected_args: list[str],
+    ) -> None:
+        """New MCP entry command/args should match the detected install method."""
+        config_dir = tmp_path / ".ouroboros"
+        config_dir.mkdir()
+        config_path = config_dir / "config.yaml"
+        config_path.write_text("{}", encoding="utf-8")
+
+        claude_dir = tmp_path / ".claude"
+        claude_dir.mkdir()
+        claude_config = claude_dir / "mcp.json"
+        claude_config.write_text(json.dumps({"mcpServers": {}}), encoding="utf-8")
+
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch("ouroboros.config.loader.ensure_config_dir", return_value=config_dir),
+            patch("ouroboros.cli.commands.setup.shutil.which", side_effect=which_side_effect),
+        ):
+            setup_cmd._setup_claude("/usr/local/bin/claude")
+
+        claude_mcp = json.loads(claude_config.read_text(encoding="utf-8"))
+        entry = claude_mcp["mcpServers"]["ouroboros"]
+        assert entry["command"] == expected_cmd
+        assert entry["args"] == expected_args
+
+    def test_setup_claude_preserves_custom_command(self, tmp_path: Path) -> None:
+        """Custom (non-standard) MCP command should not be overwritten."""
+        config_dir = tmp_path / ".ouroboros"
+        config_dir.mkdir()
+        config_path = config_dir / "config.yaml"
+        config_path.write_text("{}", encoding="utf-8")
+
+        custom_args = ["run", "--rm", "ouroboros-mcp"]
+        claude_dir = tmp_path / ".claude"
+        claude_dir.mkdir()
+        claude_config = claude_dir / "mcp.json"
+        claude_config.write_text(
+            json.dumps(
+                {
+                    "mcpServers": {
+                        "ouroboros": {
+                            "command": "docker",
+                            "args": custom_args,
+                        }
+                    }
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch("ouroboros.config.loader.ensure_config_dir", return_value=config_dir),
+        ):
+            setup_cmd._setup_claude("/usr/local/bin/claude")
+
+        claude_mcp = json.loads(claude_config.read_text(encoding="utf-8"))
+        # Custom command (docker) should be left untouched
+        assert claude_mcp["mcpServers"]["ouroboros"]["command"] == "docker"
+        assert claude_mcp["mcpServers"]["ouroboros"]["args"] == custom_args
+
+    def test_setup_claude_updates_stale_standard_entry(self, tmp_path: Path) -> None:
+        """Stale standard entry (e.g. python3) should be updated to detected method."""
+        config_dir = tmp_path / ".ouroboros"
+        config_dir.mkdir()
+        config_path = config_dir / "config.yaml"
+        config_path.write_text("{}", encoding="utf-8")
+
+        claude_dir = tmp_path / ".claude"
+        claude_dir.mkdir()
+        claude_config = claude_dir / "mcp.json"
+        claude_config.write_text(
+            json.dumps(
+                {
+                    "mcpServers": {
+                        "ouroboros": {
+                            "command": "python3",
+                            "args": ["-m", "ouroboros", "mcp", "serve"],
+                        }
+                    }
+                }
+            ),
+            encoding="utf-8",
+        )
+
+        # Simulate uvx now being available
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch("ouroboros.config.loader.ensure_config_dir", return_value=config_dir),
+            patch(
+                "ouroboros.cli.commands.setup.shutil.which",
+                side_effect=lambda cmd: "/usr/local/bin/uvx" if cmd == "uvx" else None,
+            ),
+        ):
+            setup_cmd._setup_claude("/usr/local/bin/claude")
+
+        claude_mcp = json.loads(claude_config.read_text(encoding="utf-8"))
+        # Should be updated from python3 to uvx
+        assert claude_mcp["mcpServers"]["ouroboros"]["command"] == "uvx"
+        assert "ouroboros-ai[claude]" in str(claude_mcp["mcpServers"]["ouroboros"]["args"])
+
+    def test_setup_claude_skips_write_when_args_already_current(self, tmp_path: Path) -> None:
+        """No file write when args are already up to date."""
+        config_dir = tmp_path / ".ouroboros"
+        config_dir.mkdir()
+        config_path = config_dir / "config.yaml"
+        config_path.write_text("{}", encoding="utf-8")
+
+        current_args = ["--from", "ouroboros-ai[claude]", "ouroboros", "mcp", "serve"]
+        claude_dir = tmp_path / ".claude"
+        claude_dir.mkdir()
+        claude_config = claude_dir / "mcp.json"
+        claude_config.write_text(
+            json.dumps({"mcpServers": {"ouroboros": {"command": "uvx", "args": current_args}}}),
+            encoding="utf-8",
+        )
+        mtime_before = claude_config.stat().st_mtime
+
+        with (
+            patch("pathlib.Path.home", return_value=tmp_path),
+            patch("ouroboros.config.loader.ensure_config_dir", return_value=config_dir),
+        ):
+            setup_cmd._setup_claude("/usr/local/bin/claude")
+
+        # File should not be rewritten when nothing changed
+        assert claude_config.stat().st_mtime == mtime_before
+
 
 # ── Brownfield helper function tests ─────────────────────────────