feat(mcp): package server as MCPB (.mcpb) for one-click Claude Desktop install

[dougborg]

Summary

Implements #61 — adds the build-time machinery to produce a statuspro-mcp-server-<version>.mcpb artifact on every MCP release. Users install with one click in Claude Desktop and get prompted for the API key via UI; no more hand-editing claude_desktop_config.json.

The format is MCP Bundles (MCPB) — Anthropic's one-click install format for local MCP servers. (Originally branded as DXT; renamed during the 2025 rebrand.) Spec: https://github.com/anthropics/mcpb.

What's in the box

• statuspro_mcp_server/mcpb/manifest.template.json — manifest_version: "0.4" with server.type: "uv" (the v0.4-only "UV Runtime" type — no bundled interpreter or virtualenv, UV handles deps at install time, ~46 kB bundle vs. multi-MB). Declares user_config.api_key as a sensitive string; Claude Desktop prompts and injects it as STATUSPRO_API_KEY.
• statuspro_mcp_server/mcpb/pyproject.template.toml — bundle's own pyproject. Hand-mirrors production deps from the package's pyproject minus [tool.uv.sources] (workspace refs don't resolve outside the monorepo). The build script verifies the dep lists match and fails loudly on drift.
• statuspro_mcp_server/mcpb/.mcpbignore — pack-time excludes for Python build artefacts on top of the CLI's defaults.
• scripts/build_mcpb.py — orchestrator. Reads version from package pyproject, verifies dep mirror, stages build/mcpb/, runs mcpb validate then mcpb pack to produce dist/statuspro-mcp-server-<version>.mcpb. MCPB_SKIP_PACK=1 for local dry-runs without the CLI installed.
• uv run poe build-mcpb — local build task.
• .github/workflows/release-mcp.yml — new build-mcpb job runs alongside publish-pypi, installs the mcpb CLI, builds the bundle, attaches it to the GitHub release matching the triggering mcp-v* tag.
• statuspro_mcp_server/README.md — install section now leads with the .mcpb flow, keeps uvx as a labeled fallback.

What I learned (corrections to the original issue text)

Posted these to issue #61 plus the sibling issues for stocktrim (dougborg/stocktrim-openapi-client#160) and frontapp (dougborg/frontapp-openapi-client#99) so they can skip the same dead ends:

• DXT → MCPB rename (CLI, file extension, npm package, repo URL).
• server.type: "uv" is the right answer for Python servers, not "python" — the v0.4-only UV runtime type ships zero interpreter/venv tree, supports cross-platform compiled deps, and is what examples/hello-world-uv actually uses.
• Bundle's pyproject is purpose-built, not the package's own. Stripping [tool.uv.sources] is mandatory; the build script's dep-mirror verification catches the inevitable drift.

Pre-existing footgun surfaced (not fixed in this PR)

While testing the bundle launch end-to-end, I hit a dep-resolution failure: statuspro_mcp_server/pyproject.toml declares statuspro-openapi-client>=0.51.0 but only 0.1.0 is on PyPI. Inside the monorepo the workspace ref masks this; outside (i.e. in the bundle), uv can't resolve. This was set in the initial commit and never updated.

The bundle infrastructure (manifest, build script, CI) is correct and validates against the schema; the runtime gap is a separate dep-version concern and will be filed as its own issue. Don't block this PR on it — the bundle is shippable infrastructure, the constraint fix is one line in a separate change.

Branches

• This branch is off origin/main, not off the open PR chore: align with katana-openapi-client safety + MCP fixes #60 (chore/align-katana-safety-fixes). Once that PR merges, this one will get the pre-push guard / list_coercion goodies via the next rebase forward.
• Pre-push guard fired and passed on push (since it isn't merged to main yet, the guard hook runs from this branch's checkout if I'd had it installed — moot for now, but the safe refspec form was used regardless).

Test plan

• uv run poe build-mcpb succeeds locally (requires npm install -g @anthropic-ai/mcpb first); produces dist/statuspro-mcp-server-<version>.mcpb
• mcpb info dist/statuspro-mcp-server-<version>.mcpb shows expected metadata
• mcpb validate build/mcpb/manifest.json passes
• unzip -l dist/statuspro-mcp-server-<version>.mcpb shows manifest.json, pyproject.toml, .mcpbignore, src/statuspro_mcp/* (no __pycache__, no .venv)
• CI's build-mcpb job runs and uploads the artifact
• MCPB_SKIP_PACK=1 uv run python scripts/build_mcpb.py works without the CLI installed (stages, returns build dir)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds MCP Bundle (MCPB, .mcpb) packaging and release automation for statuspro-mcp-server to enable one-click installation in Claude Desktop, with UI-prompted API key configuration.

Changes:

• Introduces MCPB bundle templates (manifest.template.json, pyproject.template.toml) and a .mcpbignore for bundle contents control.
• Adds scripts/build_mcpb.py plus a poe build-mcpb task to stage/validate/pack the bundle into dist/.
• Extends the MCP release workflow to build and attach the .mcpb asset; updates MCP server README to recommend the bundle install flow.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
statuspro_mcp_server/mcpb/pyproject.template.toml	Bundle pyproject template with mirrored runtime dependencies and version placeholder.
statuspro_mcp_server/mcpb/manifest.template.json	MCPB manifest template using the v0.4 uv runtime and sensitive user config for API key.
statuspro_mcp_server/mcpb/.mcpbignore	Additional ignore rules to keep the bundle clean of build/test artifacts.
statuspro_mcp_server/README.md	Documents .mcpb as the recommended Claude Desktop install path, keeps uvx as fallback.
scripts/build_mcpb.py	Build orchestrator: stages bundle dir, validates manifest, packs .mcpb artifact.
pyproject.toml	Adds poe task build-mcpb for local bundle builds.
.github/workflows/release-mcp.yml	Adds a build-mcpb job to build/upload the bundle and attach it to the GitHub release.