Improve UX for users without uvx installed

[paddymul]

Problem

When a user runs claude mcp add buckaroo-table -- uvx --from "buckaroo[mcp]" buckaroo-table, Claude Code registers the command but does not verify that uvx exists on PATH. The failure is deferred until the user starts a Claude Code session and the MCP server silently fails to start — a confusing experience with no actionable error message.

Proposed Changes

1. README.md — Add prerequisites before the install command

Add a "Prerequisites" subsection between the "### Install" heading and the claude mcp add command:

• Explain that uvx (part of uv) is required
• Provide a uvx --version verification command
• Link to uv install instructions with a curl one-liner

2. docs/buckaroo-mcp-troubleshooting.md — Two additions

a) Pre-flight check section (after Install options, before Upgrade):

uvx --version && uvx --from "buckaroo[mcp]" buckaroo-table --help

• If uvx: command not found → install uv
• If uvx is found but resolution fails → check network, try uv cache prune

b) New "Common issues" entry: "MCP server not available (uvx not found)"

Explain that claude mcp add registers the command but doesn't verify uvx exists. Provide a diagnostic check (which uvx) and fix (install uv, re-run claude mcp add).

3. .github/workflows/checks.yml — Add prerequisite note to PR comment

The PublishTestPyPI job posts a PR comment with install commands. Add a prerequisite reminder before the MCP section:

Prerequisite: Requires uvx (part of uv). Verify with uvx --version.

Future Work

A debug_install CLI command to automate pre-flight checks is a follow-on task.

[paddymul]

Implementation Plan

Overview

Detect missing uvx early and provide a helpful error message instead of a silent MCP server failure.

Steps

1. Pre-flight check at registration time — when claude mcp add is called (or documented in install instructions), add a wrapper script or check:

   • Run which uvx or uvx --version to verify it exists
   • If missing, print a clear error: "uvx not found. Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh"

2. Runtime fallback — in the MCP server startup code (mcp_tool.py or entry point):

   • Catch the "command not found" error from the subprocess
   • Return a structured MCP error response instead of silently dying
   • Include install instructions in the error message

3. Documentation — update README/install docs to list uvx as a prerequisite with install instructions for macOS (brew install uv), Linux (curl), and Windows (pip/scoop).

4. Test — integration test that mocks uvx not on PATH, verifies the error message is user-friendly.

Files to modify

• buckaroo/mcp_tool.py or server entry point — startup check
• README / docs — prerequisite section

@codex

[chatgpt-codex-connector]

Summary

• Added a new Prerequisites section to the Claude Code MCP install docs in README.md, including uvx --version verification and platform-specific uv install commands for macOS, Linux, and Windows. README.mdL30-L56
• Expanded docs/buckaroo-mcp-troubleshooting.md with a Pre-flight check section that validates both uvx presence and MCP package resolution, plus remediation guidance (uv cache prune, install instructions). docs/buckaroo-mcp-troubleshooting.mdL53-L70
• Added a new Common issues troubleshooting entry for uvx missing at runtime, including diagnostics (which uvx) and re-registration guidance. docs/buckaroo-mcp-troubleshooting.mdL143-L158
• Updated the TestPyPI PR comment template in .github/workflows/checks.yml to include a prerequisite reminder that uvx is required and should be validated with uvx --version before MCP setup. .github/workflows/checks.ymlL149-L155
• Committed the changes on branch work with commit 3b0e5b7, and created a follow-up PR via the make_pr tool.

Testing

• ✅ pytest -q tests/unit/server/test_mcp_uvx_install.py::TestUvxFailureModes::test_uvx_nonexistent_package_fails_gracefully -m slow

View task →

[paddymul]

Related: PRs #490, #496

• PR Feat/mcp install tweaks 2 #490 (merged): MCP install tweaks
• PR Auto-kill old server on upgrade when version mismatches #496 (merged): Auto-kill old server on upgrade when version mismatches

These improved MCP installation reliability. The uvx pre-flight check specifically is not yet implemented — this issue remains open for that specific UX improvement.