2025 09 20 uv package (#174)

## Summary
- add Phase 1 design/episodes/checklist documents for uv packaging in
release.sh
- implement credential-free `python-dist` build command in
`bin/release.sh` with matching make target
- add behavioral tests for the build command; document future
`python-publish` path in specs and CLAUDE notes

## Testing
- PYTHONPATH=src uv run pytest tests/unit/test_release_uv.py -k python
-v
- make test-unit

---------

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

Author: drernie

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

@@ -1,9 +1,17 @@
 name: 'Create Release'
-description: 'Build DXT package and create GitHub release with bundle'
+description: 'Build Python package, DXT package, and create GitHub release'
 inputs:
-  tag-version:
+  package-version:
     description: 'Version from git tag (e.g., 0.5.9-dev-20250904075318)'
     required: true
+  pypi-repository-url:
+    description: 'PyPI repository URL (empty for PyPI, https://test.pypi.org/legacy/ for TestPyPI)'
+    required: false
+    default: ''
+  skip-existing:
+    description: 'Skip existing packages during upload'
+    required: false
+    default: 'false'
 
 outputs:
   release-url:
@@ -13,10 +21,26 @@ outputs:
 runs:
   using: 'composite'
   steps:
+    - name: Install build dependencies
+      shell: bash
+      run: uv sync --group dev
+
+    - name: Build python distributions
+      shell: bash
+      run: make python-dist
+
+    - name: Publish to PyPI/TestPyPI
+      uses: pypa/gh-action-pypi-publish@ec4db0b4ddc65acdf4bff5fa45ac92d78b56bdf0
+      with:
+        repository-url: ${{ inputs.pypi-repository-url }}
+        packages-dir: dist/
+        skip-existing: ${{ inputs.skip-existing }}
+        verbose: true
+
     - name: Build DXT package
-      shell: bash  
+      shell: bash
       run: make dxt
-      
+
     - name: Validate DXT package
       shell: bash
       run: make dxt-validate
@@ -29,13 +53,13 @@ runs:
       id: create-release
       uses: softprops/action-gh-release@v2
       with:
-        name: "Quilt MCP DXT v${{ inputs.tag-version }}"
+        name: "Quilt MCP DXT v${{ inputs.package-version }}"
         files: |
           dist/*-release.zip
         draft: false
-        prerelease: ${{ contains(inputs.tag-version, '-') }}
+        prerelease: ${{ contains(inputs.package-version, '-') }}
         generate_release_notes: true
-        
+
     - name: Upload DXT artifacts
       uses: actions/upload-artifact@v4
       with:

.github/workflows/pr.yml

@@ -60,6 +60,10 @@ jobs:
     runs-on: ubuntu-latest
     needs: test
     timeout-minutes: 30
+    environment: testpypi
+    permissions:
+      contents: write
+      id-token: write
     if: startsWith(github.ref, 'refs/tags/v') && contains(github.ref, '-dev-')
 
     steps:
@@ -93,4 +97,6 @@ jobs:
     - name: Create dev release
       uses: ./.github/actions/create-release
       with:
-        tag-version: ${{ steps.version.outputs.tag_version }}
+        package-version: ${{ steps.version.outputs.tag_version }}
+        pypi-repository-url: https://test.pypi.org/legacy/
+        skip-existing: true

.github/workflows/push.yml

@@ -53,6 +53,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 30
     needs: [test]
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
     # Only run for production tags (v* but not v*-dev-*) and only after tests pass
     if: startsWith(github.ref, 'refs/tags/v') && (!contains(github.ref, '-dev-')) && contains(needs.test.result, 'success')
 
@@ -76,4 +80,5 @@ jobs:
     - name: Create production release
       uses: ./.github/actions/create-release
       with:
-        tag-version: ${{ steps.version.outputs.tag_version }}
+        package-version: ${{ steps.version.outputs.tag_version }}
+        # pypi-repository-url defaults to '' for PyPI

AGENTS.md

@@ -406,6 +406,11 @@ The following permissions are granted for this repository:
 - `TelemetryCollector.cleanup_old_sessions` clears `current_session_id` when an aged session is evicted—tests that probe cleanup should confirm the pointer resets.
 - 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 `bin/release.sh python-dist` with `make python-dist`, mirroring how `make dxt` exposes DXT packaging.
+- `python-dist` builds local artifacts without credentials. `bin/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`).
+
 ## important-instruction-reminders
 
 Do what has been asked; nothing more, nothing less.

CHANGELOG.md

@@ -6,6 +6,16 @@ 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.9] - 2025-09-21
+
+### Added
+
+- **uv-based Python Packaging Pipeline**: Complete integration for PyPI/TestPyPI publishing
+  - `make python-dist` - Build wheel and sdist artifacts using uv build system
+  - `make python-publish` - Publish artifacts to PyPI/TestPyPI with credential validation
+  - GitHub Actions integration with Trusted Publishing support via PyPA action
+  - Full compatibility with existing DXT packaging system
+
 ## [0.6.8] - 2025-09-20
 
 ### Added

Makefile

@@ -31,6 +31,8 @@ help:
 	@echo "📦 Production Workflow (make.deploy):"
 	@echo "  make deploy-build     - Prepare production build environment"
 	@echo "  make dxt              - Create DXT 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"

bin/release.sh

@@ -8,6 +8,117 @@ set -e
 REPO_URL=$(git config --get remote.origin.url | sed 's/.*github.com[:/]\(.*\)\.git/\1/')
 DRY_RUN=${DRY_RUN:-0}
 
+
+ensure_publish_env() {
+    if [ -n "$UV_PUBLISH_TOKEN" ]; then
+        PUBLISH_AUTH_MODE="token"
+        return 0
+    fi
+
+    if [ -n "$UV_PUBLISH_USERNAME" ] && [ -n "$UV_PUBLISH_PASSWORD" ]; then
+        PUBLISH_AUTH_MODE="userpass"
+        return 0
+    fi
+
+    echo "❌ Missing publish credentials. Set UV_PUBLISH_TOKEN or UV_PUBLISH_USERNAME and UV_PUBLISH_PASSWORD."
+    return 1
+}
+
+python_publish() {
+    echo "🚀 Starting python-publish workflow"
+
+    ensure_publish_env || return 1
+
+    if ! command -v uv >/dev/null 2>&1; then
+        echo "❌ uv not found - install uv package manager"
+        return 1
+    fi
+
+    local dist_dir="${DIST_DIR:-dist}"
+    if [ ! -d "$dist_dir" ]; then
+        echo "❌ Distribution directory '$dist_dir' does not exist. Run 'make python-dist' to build artifacts first."
+        return 1
+    fi
+
+    local artifact_count
+    artifact_count=$(find "$dist_dir" -maxdepth 1 -type f \( -name "*.whl" -o -name "*.tar.gz" \) | wc -l | tr -d ' ')
+    if [ "$artifact_count" = "0" ]; then
+        echo "❌ No artifacts found in '$dist_dir'. Run 'make python-dist' to build artifacts before publishing."
+        return 1
+    fi
+
+    local publish_url="${PYPI_PUBLISH_URL:-${PYPI_REPOSITORY_URL:-https://test.pypi.org/legacy/}}"
+    local -a artifacts
+    while IFS= read -r artifact; do
+        artifacts+=("$artifact")
+    done < <(find "$dist_dir" -maxdepth 1 -type f \( -name "*.whl" -o -name "*.tar.gz" \) | sort)
+
+    local log_cmd="uv publish"
+    local -a publish_cmd
+    publish_cmd=(uv publish)
+
+    if [ -n "$publish_url" ]; then
+        log_cmd="$log_cmd --publish-url $publish_url"
+        publish_cmd+=(--publish-url "$publish_url")
+    fi
+
+    if [ ${#artifacts[@]} -eq 0 ]; then
+        echo "❌ No artifacts found in '$dist_dir'. Run 'make python-dist' to build artifacts before publishing."
+        return 1
+    fi
+
+    for artifact in "${artifacts[@]}"; do
+        log_cmd="$log_cmd $artifact"
+        publish_cmd+=("$artifact")
+    done
+
+    if [ "$PUBLISH_AUTH_MODE" = "token" ]; then
+        log_cmd="$log_cmd --token ****"
+        publish_cmd+=(--token "$UV_PUBLISH_TOKEN")
+    else
+        log_cmd="$log_cmd --username $UV_PUBLISH_USERNAME --password ****"
+        publish_cmd+=(--username "$UV_PUBLISH_USERNAME" --password "$UV_PUBLISH_PASSWORD")
+    fi
+
+    if [ "$DRY_RUN" = "1" ]; then
+        echo "🔍 DRY RUN: Would run: $log_cmd"
+        return 0
+    fi
+
+    echo "📦 Publishing artifacts from $dist_dir to ${publish_url:-https://test.pypi.org/legacy/}"
+    "${publish_cmd[@]}"
+    echo "✅ python-publish completed"
+
+    local package_name
+    package_name=$(python3 - <<'PY'
+import tomllib
+with open('pyproject.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data["project"]["name"])
+PY
+)
+
+    local package_version
+    package_version=$(python3 - <<'PY'
+import tomllib
+with open('pyproject.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data["project"]["version"])
+PY
+)
+
+    local project_url=""
+    if [[ "${publish_url:-https://test.pypi.org/legacy/}" == *"test.pypi.org"* ]]; then
+        project_url="https://test.pypi.org/project/${package_name}/${package_version}/"
+    elif [[ "${publish_url}" == *"pypi.org"* ]]; then
+        project_url="https://pypi.org/project/${package_name}/${package_version}/"
+    fi
+
+    if [ -n "$project_url" ]; then
+        echo "🔗 View package at $project_url"
+    fi
+}
+
 check_clean_repo() {
     echo "🔍 Checking repository state..."
     if [ -n "$(git status --porcelain)" ]; then
@@ -232,18 +343,25 @@ case "${1:-}" in
         fi
         tag_release
         ;;
+    "python-publish")
+        if [ "${2:-}" = "--dry-run" ]; then
+            DRY_RUN=1
+        fi
+        python_publish
+        ;;
     "bump")
         if [ "${3:-}" = "--dry-run" ]; then
             DRY_RUN=1
         fi
         bump_version "${2:-}"
         ;;
     *)
-        echo "Usage: $0 {dev|release|bump} [options]"
+        echo "Usage: $0 {dev|release|python-publish|bump} [options]"
         echo ""
         echo "Commands:"
         echo "  dev              - Create development tag with timestamp"
-        echo "  release          - Create release tag from pyproject.toml version"  
+        echo "  release          - Create release tag from pyproject.toml version"
+        echo "  python-publish   - Publish artifacts to PyPI/TestPyPI via uv"
         echo "  bump {type}      - Bump version in pyproject.toml"
         echo ""
         echo "Bump types:"
@@ -256,6 +374,11 @@ case "${1:-}" in
         echo ""
         echo "Environment Variables:"
         echo "  DRY_RUN=1        - Enable dry-run mode"
+        echo "  DIST_DIR         - Override packaging output directory (default: dist)"
+        echo "  PYPI_PUBLISH_URL    - Override publish endpoint (default: https://test.pypi.org/legacy/)"
+        echo "  PYPI_REPOSITORY_URL - Deprecated alias for PYPI_PUBLISH_URL"
+        echo "  UV_PUBLISH_TOKEN or UV_PUBLISH_USERNAME/UV_PUBLISH_PASSWORD"
+        echo "                    - Credentials required before running python-publish"
         echo ""
         echo "Examples:"
         echo "  $0 bump patch           # Bump patch version"
@@ -264,4 +387,4 @@ case "${1:-}" in
         echo "  $0 release              # Create release tag"
         exit 1
         ;;
-esac
+esac

env.example

@@ -22,3 +22,16 @@ FASTMCP_TRANSPORT=stdio
 
 # ngrok Configuration for remote tunneling (optional)
 NGROK_DOMAIN=my-free-domain.ngrok-free.app
+
+# Python packaging (uv)
+# Required for publishing: set either UV_PUBLISH_TOKEN or both UV_PUBLISH_USERNAME/UV_PUBLISH_PASSWORD.
+# Leave unset to build locally without publishing.
+UV_PUBLISH_TOKEN=your-testpypi-token
+UV_PUBLISH_USERNAME=testpypi-username
+UV_PUBLISH_PASSWORD=testpypi-password
+
+# Optional: Override publish endpoint (defaults to TestPyPI)
+PYPI_PUBLISH_URL=https://test.pypi.org/legacy/
+
+# Optional: Override dist output directory (defaults to dist/)
+DIST_DIR=dist

make.deploy

@@ -26,7 +26,7 @@ DEPS_MARKER := $(BUILD_DIR)/.deps-installed
 ASSET_FILES := $(wildcard $(ASSETS_DIR)/*)
 APP_FILES := $(shell find $(APP_DIR)/quilt_mcp -name "*.py" 2>/dev/null || true)
 
-.PHONY: deploy-build dxt dxt-validate release-zip deploy-clean check-tools
+.PHONY: deploy-build dxt dxt-validate python-dist python-publish release-zip deploy-clean check-tools
 
 # Check for required tools
 check-tools:
@@ -87,6 +87,17 @@ $(DXT_PACKAGE): build-contents
 dxt: $(DXT_PACKAGE)
 	@echo "✅ DXT package created: $(DXT_PACKAGE)"
 
+# Python Package Distribution
+python-dist: check-tools
+	@echo "🚀 Building Python artifacts..."
+	@mkdir -p $(DIST_DIR)
+	@uv sync --group dev
+	@uv run python -m build --wheel --sdist --outdir $(DIST_DIR)
+	@echo "✅ Python packaging complete"
+
+python-publish:
+	@./bin/release.sh python-publish
+
 # DXT Package Validation
 dxt-validate: check-tools dxt
 	@echo "Validating DXT package..."
@@ -133,4 +144,4 @@ release-dev-tag:
 deploy-clean:
 	@echo "Cleaning build artifacts..."
 	@rm -rf $(BUILD_DIR) $(DIST_DIR)
-	@echo "✅ Deploy cleanup completed"
+	@echo "✅ Deploy cleanup completed"