Tracking: path to a .mcpb release (S2→S3 first, then MCPB packaging)

[millsmillsymills]

Goal

Ship flipperzero-mcp as an MCPB bundle: a flipperzero-mcp.mcpb file attached
to a GitHub Release, installable into MCPB-capable hosts (Claude Desktop and
others) in one click. A Flipper Zero driven over USB serial (or WiFi bridge) is
the canonical MCPB use case — the server must run on the machine next to the
device.

Spec: https://github.com/modelcontextprotocol/mcpb —
MANIFEST.md,
CLI.md.

Facts from the spec that shape the plan:

• A .mcpb is a zip of the server plus manifest.json; the host launches the
  server over stdio.
• The uv server type (manifest v0.4+) has the host install Python
  dependencies from pyproject.toml/uv.lock at install time. That sidesteps
  both compiled-wheel problems in this dependency tree (pydantic-core, and
  protobuf's C extension — pinned protobuf==7.35.1): the host resolves
  correct platform wheels from uv.lock.
• user_config fields render in the host's install UI and substitute into
  mcp_config.env.
• @anthropic-ai/mcpb CLI: mcpb validate + mcpb pack. Signing optional.

shortcut-mcp already implements the uv-bundle pipeline
(https://github.com/millsymills-com/shortcut-mcp — manifest,
scripts/build_mcpb.py, mcpb.yml release-attach workflow) and is the pattern
to copy once this repo reaches S3.

Current state

• Stage S2 (per README). The README tracks the S3 climb (the
  /flipper-install flagship and live integration suite) under the
  public-launch umbrella [launch] Public launch readiness (umbrella) #37, which is now closed — the Status section needs a
  refresh as part of this work.
• Version 0.1.0 in pyproject; CHANGELOG has [0.1.0] released plus
  [Unreleased] content. No git tags and no GitHub Releases have ever been
  cut; no release workflow, no RELEASING.md.
• Default branch is phase1; no main branch exists. ci.yml triggers on
  pull_request and push: branches: [main] — meaning CI never runs on direct
  pushes to the default branch; only codeql.yml lists phase1.
• stdio FastMCP server, console script flipperzero-mcp, Python >=3.13,
  uv.lock committed. Generated protobuf modules are checked into src/ (no
  runtime codegen).
• Transport/config surface (FLIPPER_* env prefix): FLIPPER_TRANSPORT
  (auto default — USB first, WiFi fallback), FLIPPER_USB_PORT (optional,
  auto-detect when unset), FLIPPER_USB_BAUDRATE (default 115200),
  FLIPPER_WIFI_HOST/FLIPPER_WIFI_PORT (optional WiFi bridge), and three
  independent safety gates, all default-off:
  • FLIPPER_ENABLE_WRITE_TOOLS — device-mutating storage/app operations
  • FLIPPER_ENABLE_TX_TOOLS — transmit/destructive CLI commands (which also
    require a per-call acknowledgment flag)
  • FLIPPER_ENABLE_FIRMWARE_FLASH — firmware flashing (additionally requires
    write tools enabled and a per-call confirm token)
• No secrets anywhere; no MCPB artifacts (manifest, icon, build script,
  .mcpbignore).

Work items

Phase 0 — S2→S3 (prerequisite for distribution packaging)

• Refresh README ## Status: [launch] Public launch readiness (umbrella) #37 is closed; restate what actually remains
  for S3 and declare S3 when it's done.
• Fix CI triggers: ci.yml must run on pushes to the default branch
  (currently only main, which doesn't exist).

Phase 1 — repo/release groundwork

• Decide the default-branch question: rename phase1 → main (update CI
  triggers, CodeQL branch list, branch protection) or keep phase1 and
  parameterize the workflows. Renaming is recommended — sibling repos'
  release tooling assumes main.
• RELEASING.md: semver policy, pyproject version bump, CHANGELOG roll,
  tag vX.Y.Z, create the GitHub Release from the tag (port from
  shortcut-mcp).
• Cut the first tagged release (roll the current [Unreleased] section)
  so the release mechanics work before the bundle lands.

Phase 2 — bundle assets

• mcpb/manifest.json — manifest_version 0.4, server.type: "uv",
  mcp_config launching uv run --directory ${__dirname} flipperzero-mcp;
  repository/homepage/support metadata; MIT license field (LICENSE +
  NOTICE fork attribution ride along in the bundle); compatibility
  declaring python >=3.13,<4 and darwin/win32/linux.
• user_config mapping:
  - usb_port (string, optional, blank = auto-detect) →
  FLIPPER_USB_PORT
  - enable_write_tools (boolean, default false) →
  FLIPPER_ENABLE_WRITE_TOOLS
  - enable_tx_tools (boolean, default false) → FLIPPER_ENABLE_TX_TOOLS
  Keep FLIPPER_ENABLE_FIRMWARE_FLASH env-only (not in the install UI) so
  firmware flashing keeps its extra friction; transport/WiFi/baud settings
  stay env-tunable too. Confirm this split before building the manifest.
• mcpb/icon.png.

Phase 3 — build script + CI

• scripts/build_mcpb.py (port from shortcut-mcp): stage pyproject.toml,
  uv.lock, README.md, LICENSE, NOTICE, src/ into a clean dir,
  sync manifest version from pyproject.toml, zip to
  dist/flipperzero-mcp.mcpb. The checked-in generated protobuf modules
  under src/ must ride along (no codegen at install time).
• mcpb validate on the built manifest.
• .github/workflows/mcpb.yml: build on push/PR; on release: published,
  build and attach dist/flipperzero-mcp.mcpb via gh release upload.
  SHA-pinned actions, persist-credentials: false, contents: write only
  on the attach job.

Phase 4 — docs + verification

• README: MCPB install section (download .mcpb, open with Claude
  Desktop, plug in the Flipper). Note the Linux serial-permissions caveat
  (user must be in the dialout group — nothing the bundle can fix).
• Install the built .mcpb into Claude Desktop with a Flipper attached:
  auto-detect finds the device, tools list, a read tool works; storage
  writes, transmit tools, and firmware flash all stay unavailable until
  their respective gates are enabled.
• Confirm the workflow attached the asset on a real release.

Acceptance criteria

• Repo is at S3 with a tagged, released version.
• A GitHub Release has flipperzero-mcp.mcpb attached, built by CI.
• A fresh Claude Desktop install from that file talks to a plugged-in Flipper
  with no terminal steps (macOS; Linux modulo the dialout caveat).
• All three safety gates stay opt-in (default off); firmware flash is not
  exposed in the install UI at all.

Out of scope / follow-ups

• Bundle signing (mcpb sign) — optional per spec.
• MCP registry submission — follow-up once bundle releases are routine.