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:

"frontapp-dev": {
  "command": "/Users/.../uv",
  "args": ["run", "--project", "/Users/.../frontapp-openapi-client",
           "--package", "frontapp-mcp-server", "frontapp-mcp-server"],
  "env": { "FRONTAPP_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 frontapp-mcp-server console script
  • user_config declaring FRONTAPP_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:

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

  This requires the package to be on PyPI 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 frontapp-mcp-server works as an invocation path (no local checkout required)

Companion issues

Same packaging gap exists for the sibling MCPs:

• statuspro-openapi-client
• stocktrim-openapi-client

Context

Surfaced during a parallel catch-up session on the statuspro repo. Current Claude Desktop config requires hand-edited paths and inline API keys; DXT eliminates both for one-click install.

[dougborg]

Notes from the parallel implementation in statuspro-openapi-client

Implementing this on the statuspro side surfaced a few corrections to the issue text — capturing here so this implementation doesn't repeat 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
• 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"

Use manifest_version: "0.4" and server.type: "uv" (the v0.4-only "UV Runtime" type — the spec's main schema only lists node/python/binary but a separate section introduces uv).

Benefits over type: "python":

• No bundled interpreter / virtualenv
• ~46 kB bundle vs. multi-MB
• UV handles platform-specific compiled deps (pydantic, etc.)
• No user Python install required

Reference example to crib from: examples/hello-world-uv in the mcpb repo.

Single-key user_config (frontapp shape)

Frontapp uses a single FRONTAPP_API_KEY, same as statuspro. The user_config block is one prompt:

"user_config": {
  "api_key": {
    "type": "string",
    "title": "Frontapp API Key",
    "description": "...",
    "required": true,
    "sensitive": true
  }
}

Then mcp_config.env:

"env": { "FRONTAPP_API_KEY": "${user_config.api_key}" }

Bundle structure for UV runtime

bundle.mcpb (zip)
├── manifest.json          # type: "uv", entry_point points at __main__.py
├── pyproject.toml         # purpose-built for the bundle, deps from PyPI only
├── .mcpbignore            # python excludes
├── README.md
└── src/<package>/         # full source tree

Dep mirror caveat

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). Worth having the build script verify dep lists match between the two and fail on drift — otherwise new package deps would silently be missing from the bundle.

Build mechanics

mcpb validate <bundle-dir>/manifest.json   # fail fast on schema errors
mcpb pack <bundle-dir> <output.mcpb>       # auto-excludes .git, node_modules, .DS_Store
mcpb info <output.mcpb>                    # inspect the resulting archive

Reference implementation

statuspro PR landing this: dougborg/statuspro-openapi-client#62 — scripts/build_mcpb.py, statuspro_mcp_server/mcpb/, and the CI step in .github/workflows/release-mcp.yml are all directly portable to frontapp's layout. The build script's dep-mirror verification is particularly worth lifting.

Pre-existing dep-constraint check

The statuspro build surfaced an unrelated bug: the package's pyproject declared statuspro-openapi-client>=0.51.0 but only 0.1.0 was on PyPI. Worth checking frontapp's analogous frontapp-mcp-server constraint on frontapp-openapi-client before the bundle PR — the workspace ref hides this kind of skew inside the monorepo, the bundle exposes it.