Skip to content

PUBLISHING.md

Latest commit

 

History

History
394 lines (290 loc) · 8.29 KB

PUBLISHING.md

File metadata and controls

394 lines (290 loc) · 8.29 KB

Publishing to PyPI - Step-by-Step Guide

This guide walks you through publishing the Method CRM MCP Server to PyPI.

Prerequisites

  1. PyPI Account

  2. TestPyPI Account (for testing)

  3. API Tokens

  4. Install Build Tools

    pip install --upgrade build twine

Step 1: Prepare Your Package

1.1 Update Version Number

Edit pyproject.toml and update version:

version = "1.0.0"  # Update for each release

1.2 Update Your Email

Edit pyproject.toml and replace placeholder email:

authors = [
    {name = "Avinash Sangle", email = "your-real-email@example.com"}
]
maintainers = [
    {name = "Avinash Sangle", email = "your-real-email@example.com"}
]

1.3 Verify Files are Complete

# Check that all required files exist
ls -la README.md LICENSE pyproject.toml MANIFEST.in

# Check source code structure
tree src/method_mcp

1.4 Clean Previous Builds

# Remove old build artifacts
rm -rf build/ dist/ *.egg-info src/*.egg-info

Step 2: Build Distribution Packages

# Build source distribution and wheel
python -m build

# Verify build succeeded
ls -lh dist/
# Should see:
# - method-crm-mcp-1.0.0.tar.gz (source distribution)
# - method_crm_mcp-1.0.0-py3-none-any.whl (wheel)

2.1 Check Package Contents

# Inspect wheel contents
unzip -l dist/method_crm_mcp-1.0.0-py3-none-any.whl

# Inspect source distribution
tar -tzf dist/method-crm-mcp-1.0.0.tar.gz

2.2 Validate Package Metadata

# Check package for errors
twine check dist/*

# Should output: "Checking dist/... PASSED"

Step 3: Test on TestPyPI (RECOMMENDED)

3.1 Configure TestPyPI Token

Create ~/.pypirc:

[distutils]
index-servers =
    pypi
    testpypi

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-AgEIcH...your-testpypi-token-here...

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-AgEIcH...your-pypi-token-here...

Security Note: Set proper permissions:

chmod 600 ~/.pypirc

3.2 Upload to TestPyPI

# Upload to TestPyPI
twine upload --repository testpypi dist/*

# If successful, you'll see:
# Uploading distributions to https://test.pypi.org/legacy/
# Uploading method_crm_mcp-1.0.0-py3-none-any.whl
# Uploading method-crm-mcp-1.0.0.tar.gz

3.3 Test Installation from TestPyPI

# Create clean virtual environment
python -m venv test_env
source test_env/bin/activate  # On Windows: test_env\Scripts\activate

# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    method-crm-mcp

# Test import
python -c "from method_mcp.server import mcp; print('✓ Package works!')"

# Test CLI
python -m method_mcp.server --help

# Cleanup
deactivate
rm -rf test_env

3.4 View on TestPyPI

Visit: https://test.pypi.org/project/method-crm-mcp/

Step 4: Publish to Production PyPI

⚠️ WARNING: This cannot be undone! Once published, you cannot:

  • Delete the release
  • Reuse the version number
  • Modify the uploaded files

4.1 Final Pre-flight Checks

# Verify version in pyproject.toml
grep "version" pyproject.toml

# Verify all tests pass
pytest

# Verify README renders correctly
python -m readme_renderer README.md

# Check for security issues (optional)
pip install safety
safety check

4.2 Upload to PyPI

# Upload to production PyPI
twine upload dist/*

# If successful, you'll see:
# Uploading distributions to https://upload.pypi.org/legacy/
# Uploading method_crm_mcp-1.0.0-py3-none-any.whl
# Uploading method-crm-mcp-1.0.0.tar.gz
# View at: https://pypi.org/project/method-crm-mcp/1.0.0/

4.3 Verify Installation

# Create clean environment
python -m venv verify_env
source verify_env/bin/activate

# Install from PyPI
pip install method-crm-mcp

# Verify it works
python -c "from method_mcp.server import mcp; print('✓ Published successfully!')"

# Cleanup
deactivate
rm -rf verify_env

4.4 View on PyPI

Visit: https://pypi.org/project/method-crm-mcp/

Step 5: Post-Publication Tasks

5.1 Create Git Tag

# Tag the release
git tag -a v1.0.0 -m "Release v1.0.0 - Published to PyPI"
git push origin v1.0.0

5.2 Update GitHub Release

Add PyPI installation instructions to GitHub release:

gh release edit v1.0.0 --notes-file - <<EOF
# Installation

\`\`\`bash
pip install method-crm-mcp
\`\`\`

[View on PyPI](https://pypi.org/project/method-crm-mcp/)

[Rest of release notes...]
EOF

5.3 Update Documentation

Update README.md installation section:

## Installation

### From PyPI (Recommended)

\`\`\`bash
pip install method-crm-mcp
\`\`\`

### From Source

\`\`\`bash
git clone https://github.com/avisangle/method-crm-mcp.git
cd method-crm-mcp
pip install -e .
\`\`\`

5.4 Announce the Release

  • Tweet about the release
  • Post in relevant Reddit communities (r/Python, r/programming)
  • Share in Discord/Slack communities
  • Update MCP servers registry
  • Post in Method CRM community forums

Troubleshooting

Error: "File already exists"

You tried to upload a version that already exists. You must:

  1. Increment version number in pyproject.toml
  2. Rebuild: python -m build
  3. Upload again: twine upload dist/*

Error: "Invalid credentials"

Check your ~/.pypirc token or use command line:

twine upload --username __token__ --password pypi-YOUR-TOKEN-HERE dist/*

Error: "403 Forbidden"

You don't have permissions. Possible causes:

  • Wrong API token
  • Token doesn't have upload permissions
  • Package name already taken by someone else

Package Name Already Taken

Choose a different name in pyproject.toml:

name = "method-crm-mcp-avisangle"  # Add your username

Version Management

Semantic Versioning

Follow SemVer:

  • 1.0.0 → 1.0.1: Bug fixes (patch)
  • 1.0.0 → 1.1.0: New features (minor)
  • 1.0.0 → 2.0.0: Breaking changes (major)

Release Process

For each new release:

  1. Update version in pyproject.toml
  2. Update CHANGELOG.md (create if needed)
  3. Clean old builds: rm -rf dist/
  4. Build: python -m build
  5. Test on TestPyPI
  6. Upload to PyPI
  7. Tag in git: git tag v1.x.x
  8. Push tag: git push origin v1.x.x
  9. Create GitHub release

Security Best Practices

  1. Never commit .pypirc or API tokens to git
  2. Use API tokens, not passwords
  3. Enable 2FA on PyPI account
  4. Rotate tokens periodically (every 6-12 months)
  5. Use environment variables for CI/CD: 
    export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-YOUR-TOKEN
twine upload dist/*

Automated Publishing with GitHub Actions

Create .github/workflows/publish.yml:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.10'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install build twine
    - name: Build package
      run: python -m build
    - name: Publish to PyPI
      env:
        TWINE_USERNAME: __token__
        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
      run: twine upload dist/*

Add PYPI_API_TOKEN to GitHub repository secrets.

Resources

Support

If you encounter issues:

  1. Check PyPI Help
  2. Search Python Packaging Discussions
  3. Open an issue in this repository

Good luck with your PyPI publication! 🚀