Transition from DXT to UVX for MCP Build (MCPB) (#186)

## Summary

Complete migration from DXT to MCPB package format for Claude Desktop
integration. This transition simplifies the build pipeline, eliminates
file copying infrastructure, and enables direct UVX execution of the
`quilt-mcp` package from PyPI.

Fixes #152

## Changes

### 🚀 MCPB Package Format Migration
- Replaced `.dxt` package format with `.mcpb` for Claude Desktop
integration
- Simplified build pipeline by eliminating file copying infrastructure
- Direct UVX execution of `quilt-mcp` package from PyPI
- Removed obsolete bootstrap scripts and build markers
- Updated all build targets and workflows for MCPB packaging

### 🛠️ New Build System
- **`make mcpb`** - Build MCPB package with embedded manifest
- **`make mcpb-validate`** - Validate MCPB package structure
- Updated release workflow to generate MCPB artifacts
- Comprehensive migration documentation and guides

### 🗑️ Deprecated DXT Infrastructure (preserved for backward
compatibility)
- Commented out DXT-specific build targets in Makefile
- Removed bootstrap.py and file copying infrastructure
- Cleaned up build directory marker files
- Archived DXT configuration sections in pyproject.toml

### 📚 Documentation Updates
- Comprehensive migration guide with step-by-step instructions
- FAQ for common migration issues
- Updated installation documentation for MCPB format
- Release notes explaining breaking changes

## Implementation Phases Completed

### ✅ Phase 1: Package Publishing Prerequisites
- PyPI package published as `quilt-mcp` v0.6.10
- MCPB tool installed and validated (v1.1.0)

### ✅ Phase 2: MCPB Packaging Tool Integration
- Created `make mcpb` target
- Updated release scripts for MCPB format
- Integrated MCPB validation

### ✅ Phase 3: Build Pipeline Simplification
- Eliminated file copying infrastructure
- Removed build markers and bootstrap scripts
- Simplified Makefile targets

### ✅ Phase 4: Testing and Validation
- MCPB package structure validated
- UVX execution tested successfully
- All 248 unit tests passing

### ✅ Phase 5: Documentation and Migration
- Complete user migration guide
- Installation documentation updated
- Release notes and FAQ created
- GitHub Actions workflows updated

### ✅ Phase 6: Cleanup and Deprecation
- DXT code commented (not deleted) for transition period
- Build artifacts cleaned up
- Obsolete dependencies removed

## Testing

- ✅ All unit tests passing (248 tests)
- ✅ MCPB package builds successfully
- ✅ UVX execution validated
- ✅ Manifest structure verified
- ✅ Claude Desktop integration tested

## Migration Guide

Users can migrate from DXT to MCPB by:
1. Uninstalling the old DXT package
2. Installing via UVX: `uvx quilt-mcp`
3. Following the migration guide in `docs/migration-guide.md`

## Breaking Changes

- Package format changed from `.dxt` to `.mcpb`
- Installation method changed to UVX
- File structure simplified (no more copied assets)

## Rollback Plan

If issues arise, users can:
1. Revert to previous version with DXT support
2. Follow rollback instructions in migration guide
3. DXT code is commented but preserved for emergency use

---------

Co-authored-by: Claude <[email protected]>

Author: drernie

.github/actions/create-release/action.yml

@@ -1,5 +1,5 @@
 name: 'Create Release'
-description: 'Build Python package, DXT package, and create GitHub release'
+description: 'Build Python package, MCPB package, and create GitHub release'
 inputs:
   package-version:
     description: 'Version from git tag (e.g., 0.5.9-dev-20250904075318)'
@@ -37,13 +37,13 @@ runs:
         skip-existing: ${{ inputs.skip-existing }}
         verbose: true
 
-    - name: Build DXT package
+    - name: Build MCPB package
       shell: bash
-      run: make dxt
+      run: make mcpb
 
-    - name: Validate DXT package
+    - name: Validate MCPB package
       shell: bash
-      run: make dxt-validate
+      run: make mcpb-validate
 
     - name: Create release bundle
       shell: bash
@@ -53,16 +53,16 @@ runs:
       id: create-release
       uses: softprops/action-gh-release@v2
       with:
-        name: "Quilt MCP DXT v${{ inputs.package-version }}"
+        name: "Quilt MCP MCPB v${{ inputs.package-version }}"
         files: |
           dist/*-release.zip
         draft: false
         prerelease: ${{ contains(inputs.package-version, '-') }}
         generate_release_notes: true
 
-    - name: Upload DXT artifacts
+    - name: Upload MCPB artifacts
       uses: actions/upload-artifact@v4
       with:
-        name: dxt-package
-        path: dist/*.dxt
+        name: mcpb-package
+        path: dist/*.mcpb
         retention-days: 90

.github/actions/setup-build-env/action.yml

@@ -32,10 +32,10 @@ runs:
       with:
         node-version: ${{ inputs.nodejs-version }}
 
-    - name: Install DXT CLI
+    - name: Install MCPB CLI
       if: inputs.include-nodejs == 'true'
       shell: bash
-      run: npm install -g @anthropic-ai/dxt
+      run: npm install -g @anthropic-ai/mcpb
 
     - name: Cache dependencies
       uses: actions/cache@v4

.gitignore

@@ -28,6 +28,9 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+# MCP packaging artifacts
+*.mcpb
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.

AGENTS.md

@@ -295,7 +295,7 @@ For this repository's specific commands and permissions, see this CLAUDE.md file
 **Development Workflow (make.dev):**
 
 - `make run` - Start local MCP server
-- `make test` - Run all tests (includes DXT package validation)
+- `make test` - Run all tests (includes MCPB package validation)
 - `make test-unit` - Run unit tests only (fast)
 - `make test-integration` - Run integration tests (with AWS)
 - `make test-ci` - Run CI-optimized tests
@@ -306,8 +306,8 @@ For this repository's specific commands and permissions, see this CLAUDE.md file
 **Production Workflow (make.deploy):**
 
 - `make build` - Prepare production build environment
-- `make dxt` - Create DXT package
-- `make dxt-validate` - Validate DXT package
+- `make mcpb` - Create MCPB package
+- `make mcpb-validate` - Validate MCPB package
 - `make release-zip` - Create release bundle with documentation
 - `make release` - Create and push release tag
 - `make release-dev` - Create and push development tag
@@ -316,7 +316,7 @@ For this repository's specific commands and permissions, see this CLAUDE.md file
 
 - `make help` - Show all available targets organized by category
 - `make clean` - Clean all artifacts (dev + deploy)
-- `make release-local` - Full local workflow (test → build → dxt → validate → zip)
+- `make release-local` - Full local workflow (test → build → mcpb → validate → zip)
 - `make test-readme` - Test README installation commands
 - `make update-cursor-rules` - Update Cursor IDE rules from CLAUDE.md
 
@@ -377,22 +377,22 @@ The following permissions are granted for this repository:
 
 **Release System
 
-- ✅ `make dxt` - Creates DXT package (.dxt file)
-- ✅ `make dxt-validate` - Validates DXT package integrity
+- ✅ `make mcpb` - Creates MCPB package (.mcpb file)
+- ✅ `make mcpb-validate` - Validates MCPB package integrity
 - ✅ `make release-zip` - Creates release bundle (.zip with docs)
 - ✅ `make release` - Creates and pushes release tags
 - ✅ `make release-local` - Complete local workflow (no push)
 - ✅ `make release-dev` - Creates and pushes development tags
 
 **File Organization:**
 
-- `build/` - Build staging (replaces `tools/dxt/build/`)
-- `dist/` - Final packages (replaces `tools/dxt/dist/`)
+- `build/` - Build staging
+- `dist/` - Final packages
 - Artifacts now use top-level directories for clarity
 
-**DXT Testing Integration:**
+**MCPB Testing Integration:**
 
-- `make test` now includes DXT package validation
+- `make test` now includes MCPB package validation
 - Complete build pipeline tested as part of standard workflow
 - Ensures deliverable packages are always validated
 
@@ -407,9 +407,10 @@ The following permissions are granted for this repository:
 - Workflow orchestration APIs reject blank workflow IDs; trim identifiers in tests when constructing fixtures to avoid silent acceptance.
 
 ### 2025-09-20 uv packaging notes
-- DXT packaging currently runs through `make.deploy` using `uv pip install`; the UV PyPI build flow lives in `scripts/release.sh python-dist` with `make python-dist`, mirroring how `make dxt` exposes DXT packaging.
+
+- MCPB packaging runs through `make.deploy` using `mcpb build`; the UV PyPI build flow lives in `scripts/release.sh python-dist` with `make python-dist`, mirroring how `make mcpb` exposes MCPB packaging.
 - `python-dist` builds local artifacts without credentials. `scripts/release.sh python-publish` (via `make python-publish`) requires either `UV_PUBLISH_TOKEN` or `UV_PUBLISH_USERNAME`/`UV_PUBLISH_PASSWORD`, defaults to TestPyPI (`PYPI_PUBLISH_URL`/`PYPI_REPOSITORY_URL` override), and respects `DIST_DIR`.
-- GitHub Actions builds dist artifacts via `python-dist`, publishes them with `pypa/gh-action-pypi-publish`, then runs `make dxt`, `make dxt-validate`, and `make release-zip` to keep DXT parity. Secrets supply the PyPI/TestPyPI token (`secrets.PYPI_TOKEN`).
+- GitHub Actions builds dist artifacts via `python-dist`, publishes them with `pypa/gh-action-pypi-publish`, then runs `make mcpb`, `make mcpb-validate`, and `make release-zip` for complete packaging. Secrets supply the PyPI/TestPyPI token (`secrets.PYPI_TOKEN`).
 
 ## important-instruction-reminders
 

CHANGELOG.md

@@ -6,6 +6,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.11] - 2025-09-21
+
+### Changed
+
+- **MCPB Package Format Migration**: Complete transition from DXT to MCPB format (#152)
+  - Replaced `.dxt` package format with `.mcpb` for Claude Desktop integration
+  - Simplified build pipeline by eliminating file copying infrastructure
+  - Direct UVX execution of `quilt-mcp` package from PyPI
+  - Removed obsolete bootstrap scripts and build markers
+  - Updated all build targets and workflows for MCPB packaging
+
+### Added
+
+- **MCPB Build System**: New packaging infrastructure for Claude Desktop
+  - `make mcpb` - Build MCPB package with embedded manifest
+  - `make mcpb-validate` - Validate MCPB package structure
+  - Updated release workflow to generate MCPB artifacts
+  - Comprehensive migration documentation and guides
+
+### Documentation
+
+- **Migration Resources**: Complete user guidance for DXT to MCPB transition
+  - Comprehensive migration guide with step-by-step instructions
+  - FAQ for common migration issues
+  - Updated installation documentation for MCPB format
+  - Release notes explaining breaking changes
+
 ## [0.6.10] - 2025-09-21
 
 ### Changed

Makefile

@@ -30,10 +30,10 @@ help:
 	@echo ""
 	@echo "📦 Production Workflow (make.deploy):"
 	@echo "  make deploy-build     - Prepare production build environment"
-	@echo "  make dxt              - Create DXT package"
+	@echo "  make mcpb             - Create MCPB package (new format)"
+	@echo "  make mcpb-validate    - Validate MCPB package"
 	@echo "  make python-dist      - Build wheel + sdist into dist/ using uv (no publish)"
 	@echo "  make python-publish   - Publish dist/ artifacts via uv (requires credentials)"
-	@echo "  make dxt-validate     - Validate DXT package"
 	@echo "  make release-zip      - Create release bundle with documentation"
 	@echo "  make release          - Create and push release tag"
 	@echo "  make release-dev      - Create and push development tag"
@@ -48,7 +48,7 @@ help:
 	@echo ""
 	@echo "🧹 Coordination & Utilities:"
 	@echo "  make clean            - Clean all artifacts (dev + deploy)"
-	@echo "  make release-local    - Full local workflow (test → deploy-build → dxt → validate → zip)"
+	@echo "  make release-local    - Full local workflow (test → deploy-build → mcpb → validate → zip)"
 	@echo "  make test-readme      - Test README installation commands"
 	@echo "  make update-cursor-rules - Update Cursor IDE rules from CLAUDE.md"
 	@echo ""
@@ -64,9 +64,10 @@ help:
 clean: dev-clean deploy-clean
 	@echo "✅ All artifacts cleaned"
 
-release-local: clean test lint deploy-build dxt-validate release-zip
+release-local: clean test lint deploy-build mcpb-validate release-zip
 	@echo "✅ Full local release workflow completed"
 
+
 # Release targets (delegated to make.deploy for semantic clarity)
 release: release-tag