ContextQMD
Back to Beads

Publishing beads-mcp to PyPI

integrations/beads-mcp/PYPI.md

1.0.34.0 KB
Original Source

Publishing beads-mcp to PyPI

This guide covers how to build and publish the beads-mcp package to the Python Package Index (PyPI).

Prerequisites

  1. PyPI Account: Create accounts on both:

  2. API Tokens: Generate API tokens for authentication:

  3. Build Tools: Install the Python build tools:

    bash
    uv pip install --upgrade build twine

Building the Package

  1. Clean previous builds (if any):

    bash
    rm -rf dist/ build/ src/*.egg-info

  2. Build the distribution packages:

    bash
    python -m build

    This creates both:

    • dist/beads_mcp-0.9.4-py3-none-any.whl (wheel)
    • dist/beads-mcp-0.9.4.tar.gz (source distribution)

  3. Verify the build:

    bash
    tar -tzf dist/beads-mcp-0.9.4.tar.gz

    Should include:

    • Source files in src/beads_mcp/
    • README.md
    • LICENSE
    • pyproject.toml

Testing the Package

Test on Test PyPI First

  1. Upload to Test PyPI:

    bash
    python -m twine upload --repository testpypi dist/*

    When prompted, use:

    • Username: __token__
    • Password: Your Test PyPI API token (including the pypi- prefix)

  2. Install from Test PyPI:

    bash
    # In a fresh virtual environment
uv venv test-env
source test-env/bin/activate

# Install from Test PyPI
pip install --index-url https://test.pypi.org/simple/ beads-mcp

# Test it works
beads-mcp --help

  3. Verify the installation:

    bash
    python -c "import beads_mcp; print(beads_mcp.__version__)"

Publishing to PyPI

Once you've verified the package works on Test PyPI:

  1. Upload to PyPI:

    bash
    python -m twine upload dist/*

    Use:

    • Username: __token__
    • Password: Your PyPI API token

  2. Verify on PyPI:

  3. Test installation:

    bash
    # In a fresh environment
pip install beads-mcp
beads-mcp --help

Updating the README Installation Instructions

After publishing, users can install simply with:

bash
pip install beads-mcp
# or with uv
uv pip install beads-mcp

Update the README.md to reflect this simpler installation method.

Version Management

When releasing a new version:

  1. Update version in src/beads_mcp/__init__.py
  2. Update version in pyproject.toml
  3. Use the version bump script from the parent project:
    bash
    cd ../..
./scripts/bump-version.sh 0.9.5 --commit
  4. Create a git tag:
    bash
    git tag v0.9.5
git push origin v0.9.5
  5. Clean, rebuild, and republish to PyPI

Troubleshooting

Package Already Exists

PyPI doesn't allow re-uploading the same version. If you need to fix something:

  1. Increment the version number (even for minor fixes)
  2. Rebuild and re-upload

Missing Files in Distribution

If files are missing from the built package, create a MANIFEST.in:

include README.md
include LICENSE
recursive-include src/beads_mcp *.py

Authentication Errors

  • Ensure you're using __token__ as the username (exactly)
  • Token should include the pypi- prefix
  • Check token hasn't expired

Test PyPI vs Production

Test PyPI is completely separate from production PyPI:

  • Different accounts
  • Different tokens
  • Different package versions (can have different versions on each)

Always test on Test PyPI first!

Continuous Deployment (Future)

Consider setting up GitHub Actions to automate this:

  1. On tag push (e.g., v0.9.5)
  2. Run tests
  3. Build package
  4. Publish to PyPI

See .github/workflows/ in the parent project for examples.

Resources