Setup PyPI publishing for remote installation via uvx

[iaminawe]

Overview

Publish spec-driven-development-mcp to PyPI so users can install it remotely with uvx instead of cloning the repository.

Prerequisites

⚠️ Required: Issue #8 must be completed first (package structure fixes)

One-Time Setup

1. Create PyPI Accounts

• TestPyPI: https://test.pypi.org/account/register/
• Production PyPI: https://pypi.org/account/register/

2. Generate API Tokens

• TestPyPI token: https://test.pypi.org/manage/account/token/
  • Scope: "Entire account" or limit to project after first publish
• PyPI token: https://pypi.org/manage/account/token/
  • Scope: "Entire account" or limit to project after first publish

3. Store Tokens Securely

Local development:

# Add to ~/.bashrc or ~/.zshrc
export UV_PUBLISH_TOKEN="pypi-..."          # Production
export UV_PUBLISH_TOKEN_TEST="pypi-..."    # Testing

GitHub Actions (recommended):

# Add as repository secrets:
# Settings → Secrets and variables → Actions → New repository secret
PYPI_TOKEN=pypi-...
PYPI_TEST_TOKEN=pypi-...

Publishing Process

Step 1: Test Build Locally

cd /Users/greggcoppen/Work/liatrio-mcp/mcp-spec-driven

# Build the package
uv build

# Inspect the built wheel
unzip -l dist/spec_driven_development_mcp-1.0.0-py3-none-any.whl

# Verify contents include:
# - mcp_server/*.py files
# - prompts/*.md files
# - Entry point metadata

Step 2: Publish to TestPyPI

# Publish to test repository
uv publish --publish-url https://test.pypi.org/legacy/ --token $UV_PUBLISH_TOKEN_TEST

# View on TestPyPI
open https://test.pypi.org/project/spec-driven-development-mcp/

Step 3: Test Installation from TestPyPI

# Install and test
uvx --from https://test.pypi.org/simple/ spec-driven-development-mcp --help

# Or test the full server
uvx --from https://test.pypi.org/simple/ spec-driven-development-mcp

# Verify prompts are accessible and server runs correctly

Step 4: Publish to Production PyPI

# If TestPyPI install works, publish to production
uv publish --token $UV_PUBLISH_TOKEN

# View on PyPI
open https://pypi.org/project/spec-driven-development-mcp/

Step 5: Verify Production Installation

# Test final installation
uvx spec-driven-development-mcp

# Users will install with:
uvx spec-driven-development-mcp

Automated Publishing (Recommended)

Create .github/workflows/publish-pypi.yml:

name: Publish to PyPI

on:
  release:
    types: [published]
  workflow_dispatch:  # Allow manual trigger

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      
    steps:
      - uses: actions/checkout@v4
      
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
        
      - name: Build package
        run: |
          export PATH="$HOME/.local/bin:$PATH"
          uv build
          
      - name: Publish to TestPyPI
        if: github.event_name == 'workflow_dispatch'
        env:
          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TEST_TOKEN }}
        run: |
          export PATH="$HOME/.local/bin:$PATH"
          uv publish --publish-url https://test.pypi.org/legacy/
          
      - name: Publish to PyPI
        if: github.event_name == 'release'
        env:
          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
        run: |
          export PATH="$HOME/.local/bin:$PATH"
          uv publish

Workflow:

1. Manual trigger → publishes to TestPyPI
2. GitHub release → publishes to production PyPI
3. Works with existing semantic-release workflow

Success Criteria

• Package published to TestPyPI
• Package installs successfully from TestPyPI
• Server runs correctly when installed via uvx
• Prompts are accessible in installed package
• Package published to production PyPI
• Package installs successfully from production PyPI
• Documentation updated with installation instructions
• GitHub Actions workflow configured (optional but recommended)

Post-Publishing Tasks

Update README.md Installation Section

Replace:

git clone https://github.com/liatrio-labs/spec-driven-workflow-mcp.git
cd spec-driven-workflow-mcp
uv sync

With:

# Install from PyPI
uvx spec-driven-development-mcp

# Or for development
git clone https://github.com/liatrio-labs/spec-driven-workflow-mcp.git
cd spec-driven-workflow-mcp
uv sync

Add PyPI Badge to README

[![PyPI version](https://badge.fury.io/py/spec-driven-development-mcp.svg)](https://pypi.org/project/spec-driven-development-mcp/)

References

• uv publishing docs: https://docs.astral.sh/uv/guides/publish/
• PyPI: https://pypi.org/
• TestPyPI: https://test.pypi.org/
• Package name: spec-driven-development-mcp
• Repository: https://github.com/liatrio-labs/spec-driven-workflow-mcp

Related Issues

• Depends on: Fix package structure for PyPI compatibility #8 (package structure fixes)