mcp-name-cheap/PUBLISHING.md

Publishing Guide

This document explains how to publish the MCP Name Cheap package to TestPyPI and PyPI.

Prerequisites

1. Install dependencies:

   uv sync --extra dev
   

2. Set up accounts:

   • TestPyPI account
   • PyPI account

3. Configure API tokens (recommended over username/password):

   • Create API tokens in your PyPI account settings
   • Store in ~/.pypirc or use environment variables

Publishing Methods

Method 1: Using the Publishing Script (Recommended)

The project includes a convenient publishing script:

# Publish to TestPyPI (safe testing)
python scripts/publish.py --target testpypi

# Publish to production PyPI
python scripts/publish.py --target pypi

# Skip tests (if already run)
python scripts/publish.py --target testpypi --skip-tests

# Skip building (if dist/ already exists)
python scripts/publish.py --target testpypi --skip-build

Method 2: Manual Publishing

Step 1: Run Tests and Quality Checks

python run_tests.py --all

Step 2: Clean and Build

# Clean old builds
rm -rf dist/ build/

# Build package
python -m build

Step 3: Check Package

python -m twine check dist/*

Step 4: Publish to TestPyPI

python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Step 5: Test Installation from TestPyPI

pip install -i https://test.pypi.org/simple/ mcp-namecheap

Step 6: Publish to PyPI (if TestPyPI works)

python -m twine upload dist/*

Method 3: GitHub Actions (Automated)

For TestPyPI

# Manual workflow dispatch
gh workflow run publish.yml -f environment=testpypi

For PyPI

# Create and push a version tag
git tag v1.0.0
git push origin v1.0.0
# This automatically triggers PyPI publishing

Version Management

Update Version

1. Update version in pyproject.toml:

   version = "1.0.1"
   

2. Update version in src/mcp_namecheap/__init__.py:

   __version__ = "1.0.1"
   

3. Commit changes:

   git add .
   git commit -m "Bump version to 1.0.1"
   

4. Tag release:

   git tag v1.0.1
   git push origin main
   git push origin v1.0.1
   

Semantic Versioning

Follow Semantic Versioning:

• MAJOR (1.0.0): Breaking changes
• MINOR (0.1.0): New features, backwards compatible
• PATCH (0.0.1): Bug fixes, backwards compatible

Testing Published Packages

TestPyPI

# Install from TestPyPI
pip install -i https://test.pypi.org/simple/ mcp-namecheap

# Test basic functionality
python -c "import mcp_namecheap; print(mcp_namecheap.__version__)"
mcp-namecheap --help

PyPI

# Install from PyPI
pip install mcp-namecheap

# Test installation
mcp-namecheap --help

Configuration Files

.pypirc (Optional)

Store credentials in ~/.pypirc:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-your-api-token-here

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

Environment Variables

Alternatively, use environment variables:

export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-your-api-token-here

GitHub Repository Setup

Secrets Configuration

Add these secrets to your GitHub repository:

1. Go to Settings → Secrets and variables → Actions
2. Add repository secrets:
   • PYPI_API_TOKEN: Your PyPI API token
   • TEST_PYPI_API_TOKEN: Your TestPyPI API token

Environments

Configure environments for additional security:

1. Go to Settings → Environments
2. Create environments:
   • testpypi: For TestPyPI publishing
   • pypi: For PyPI publishing (with protection rules)

Publishing Checklist

Pre-Publishing

• All tests pass (python run_tests.py --all)
• Version number updated in both places
• CHANGELOG.md updated (if exists)
• Documentation updated
• Clean working directory (git status)

TestPyPI Publishing

• Publish to TestPyPI
• Install from TestPyPI
• Test basic functionality
• Test MCP server functionality
• Verify documentation renders correctly

PyPI Publishing

• TestPyPI version works correctly
• Create git tag for version
• Publish to PyPI
• Verify PyPI page looks correct
• Test installation from PyPI
• Update documentation with new version

Troubleshooting

Common Issues

"File already exists" error

• Version already published
• Update version number in pyproject.toml

"Invalid credentials" error

• Check API token
• Verify .pypirc configuration
• Try environment variables instead

"Package validation failed" error

• Run twine check dist/*
• Fix any metadata issues
• Rebuild package

Import errors after installation

• Check package structure
• Verify __init__.py files exist
• Test in clean environment

Getting Help

• PyPI Help
• TestPyPI Help
• Twine Documentation
• Python Packaging Guide

Best Practices

1. Always test on TestPyPI first
2. Use API tokens instead of passwords
3. Tag releases in git
4. Keep version numbers in sync
5. Test in clean environments
6. Use semantic versioning
7. Automate with GitHub Actions
8. Document changes in releases