packaging: make optional MCP SDK installation deterministic and supportable #2600

Goal

Define the supported installation, pinning, diagnostics, upgrade, and removal contract for the optional MCP SDK used by basectl mcp serve.

Background

Base currently has no Python package of its own. Its Base virtual environment installs the selected base-cli package and bootstrap requirements, while basectl setup --profile ai currently manages AI command-line tools. The MCP plan says “official mcp Python package as an optional extra” but does not identify where that extra lives or how a Base user installs it. Project requirements currently reject package-extra syntax, so the new contract must use an explicit Base-owned setup path.

Tracking: #2555. Depends on #2587's protocol design and the existing ai setup profile.

Scope

• Extend the existing ai profile with the pinned official mcp SDK needed by the Base MCP server, or document a narrower Base-owned opt-in if the implementation proves that safer.
• Define the package/version/hash source, supported Python versions, platform behavior, and offline failure message under docs/ci-supply-chain-policy.md.
• Add basectl check --profile ai and doctor --profile ai findings for the MCP SDK independently from external AI CLIs.
• Make setup idempotent and ensure upgrade and uninstall behavior do not remove unrelated project dependencies.
• Cover source-provider, installed-provider, CI, Homebrew, and no-network paths.

Acceptance Criteria

• One documented command installs the MCP SDK without requiring users to edit requirements-dev.txt or a project manifest.
• The installed version is pinned and audited according to the supply-chain policy.
• Check/doctor distinguish missing MCP support from missing Codex/Claude tools.
• Repeated setup is a no-op; upgrade and uninstall behavior are documented and tested.
• Missing package, unsupported Python, and offline-index failures return actionable finding IDs without tracebacks.
• The release BOM and Base setup tests exercise the exact MCP dependency input.

Validation

BASE_CLI_SOURCE_DIR=../base-cli/lib/python \
PYTHONPATH=../base-cli/lib/python:lib/python:cli/python \
python -m pytest cli/python/base_dev/tests cli/python/base_setup/tests <new MCP setup tests>
bats cli/bash/commands/basectl/tests/setup.bats cli/bash/commands/basectl/tests/check.bats
git diff --check

Non-Goals

• Do not install MCP by default for users who do not request AI tooling.
• Do not add a network listener or provider-specific agent configuration.
• Do not loosen the existing project dependency parser.

Project Fields

• Status: Ready
• Priority: P1
• Area: Packaging
• Initiative: Agentic Coding Platform
• Size: M
• Milestone: v1.12.0
• Category: enhancement

Agent Assignment

Assignee: codeforester. Implementation-ready after the SDK version is selected; use an issue-backed worktree.