Package MCP server as DXT for one-click Claude Desktop install

[dougborg]

Problem

The MCP server in this repo currently requires hand-editing claude_desktop_config.json to install — pointing at a local checkout via --project and embedding the API key inline:

"statuspro-dev": {
  "command": "/Users/.../uv",
  "args": ["run", "--project", "/Users/.../statuspro-openapi-client",
           "--package", "statuspro-mcp-server", "statuspro-mcp-server"],
  "env": { "STATUSPRO_API_KEY": "..." }
}

This works for the maintainer but doesn't scale to teammates or customers: no install flow, no UI for managing the server, no env-var prompt — the API key lives in a config file users have to edit by hand.

Proposal

Adopt Anthropic's DXT (Desktop Extensions) packaging format. A .dxt is a zip containing the server + a manifest.json that declares entry point, required env vars, platform compat, etc. Claude Desktop installs them with one click and prompts for env-var values via UI — no JSON editing.

Reference: https://github.com/anthropics/dxt

Scope

• Add manifest.json at the package root declaring:
  • name / version / description (sourced from pyproject.toml so they don't drift)
  • server.type = "python" with entry point pointing at the existing statuspro-mcp-server console script
  • user_config declaring STATUSPRO_API_KEY as type: "secret" with a prompt-friendly description
  • Platform compatibility metadata (darwin / linux / win32 as applicable)
• Add a CI step in the release workflow that:
  • Builds the .dxt artifact
  • Attaches it to the GitHub release
  • Publishes alongside the PyPI release
• Document the install flow in the MCP server README ("drag the .dxt into Claude Desktop")
• Add a uvx-based fallback for CLI users who don't want DXT:

  { "command": "uvx", "args": ["statuspro-mcp-server"], "env": { ... } }

  This requires the package to be on PyPI (which the release workflow already does) and removes the --project path dependency.

Acceptance criteria

• manifest.json validates against the DXT schema
• CI builds and uploads the .dxt artifact on each MCP release
• README documents both the DXT and uvx install flows
• uvx statuspro-mcp-server works as an invocation path (no local checkout required)

Companion issues

Same packaging gap exists for the sibling MCPs — file linked once they're created:

• frontapp-openapi-client
• stocktrim-openapi-client

Context

Discussed during the katana-port catch-up session that landed #60. Current Claude Desktop config requires hand-edited paths and inline API keys; DXT eliminates both for one-click install.

[dougborg]

Implementation notes (from this PR)

Implementing this surfaced a few corrections to the original issue text — capturing here so the sibling repos (stocktrim, frontapp) skip the same dead ends:

Naming: DXT → MCPB

Anthropic renamed the format during the 2025 rebrand:

• dxt CLI → mcpb (npm install -g @anthropic-ai/mcpb)
• .dxt files → .mcpb
• @anthropic-ai/dxt → @anthropic-ai/mcpb
• Repo: https://github.com/anthropics/mcpb (the issue's anthropics/dxt link 301-redirects)

Schema is the same, just renamed.

Server type: "uv", not "python"

The reference spec at MANIFEST.md claims manifest_version: "0.3" and lists three server types: node, python, binary. But the spec has a separate "UV Runtime (v0.4+)" section that introduces a fourth type — "uv" — which is what Python servers should actually use. Bumping manifest_version to "0.4" opts in.

type: "uv" benefits over type: "python":

• No bundled interpreter / virtualenv (.venv tree)
• ~46 kB bundle vs. multi-MB
• Cross-platform (UV handles platform-specific compiled deps like pydantic)
• No user Python install required — UV bootstraps everything

The reference example to crib from is examples/hello-world-uv in the mcpb repo, not the longer python example.

Bundle structure for UV runtime

bundle.mcpb (zip)
├── manifest.json          # type: "uv", entry_point: "src/.../__main__.py"
├── pyproject.toml         # purpose-built for the bundle (see "dep mirror")
├── .mcpbignore            # python excludes (__pycache__, .venv, etc.)
├── README.md              # copied from the package's own
└── src/<package>/         # full source tree

mcp_config in the manifest:

"mcp_config": {
  "command": "uv",
  "args": ["run", "--directory", "${__dirname}", "<console-script-name>"],
  "env": { "API_KEY": "${user_config.api_key}" }
}

Dep mirror caveat

The bundle ships its own pyproject.toml separate from the package's because the bundle must NOT include [tool.uv.sources] workspace refs (those don't resolve outside the monorepo). The build script verifies the production-dep lists match between the two pyprojects and fails loudly on drift — otherwise new deps added to the package would silently be missing from the bundle.

Pack mechanics

mcpb pack <dir> <output> zips the staged bundle with max compression, automatically excluding common dev files (.git, node_modules, .DS_Store). Use mcpb validate separately during build to fail fast on schema errors before pack.

Pre-existing dep-constraint footgun (statuspro-specific)

The bundle build surfaced that 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, the bundle would fail at install time. Filing a separate issue for this — not a bundle problem, but worth checking the analogous constraints in stocktrim/frontapp before their bundle PRs.

Implementation outputs

PR: #62 (build script + manifest + CI + README)

• 3 commits, ~330 lines
• mcpb CLI v2.1.2 confirmed working
• Bundle: 46.5 kB compressed, 22 files
• Manifest validates against the 0.4 schema