MCP Boilerplate Server

# PyPI Publishing Guide This guide walks you through publishing your MCP Server Boilerplate to PyPI so others can install it with `pip install mcp-server-boilerplate`. ## Prerequisites Checklist - [ ] Python 3.12+ installed - [ ] uv installed - [ ] PyPI account created - [ ] Project is ready and tested ## Step 1: Prepare Your Project ### 1.1 Update Project URLs Edit `pyproject.toml` and replace placeholder URLs: ```toml [project.urls] Homepage = "https://github.com/YOUR_USERNAME/mcp_server" Repository = "https://github.com/YOUR_USERNAME/mcp_server" Issues = "https://github.com/YOUR_USERNAME/mcp_server/issues" ``` Replace `YOUR_USERNAME` with your actual GitHub username. ### 1.2 Set Your Email (Optional) In `pyproject.toml`, add your email: ```toml authors = [ {name = "Shaza", email = "your.email@example.com"}, ] ``` ### 1.3 Test Locally ```bash # Install in development mode uv sync # Test the CLI command works uv run mcp-server-boilerplate # Test import works uv run python -c "from mcp_server_boilerplate import mcp; print('✅ Import successful')" ``` ## Step 2: PyPI Account Setup ### 2.1 Create PyPI Account 1. Go to [https://pypi.org/account/register/](https://pypi.org/account/register/) 2. Create your account 3. Verify your email ### 2.2 Create API Token 1. Go to [https://pypi.org/manage/account/token/](https://pypi.org/manage/account/token/) 2. Click "Add API token" 3. Name it (e.g., "mcp-server-boilerplate") 4. Set scope to "Entire account" (or specific project if you prefer) 5. **SAVE THE TOKEN** - you won't see it again! ### 2.3 Configure Authentication Create `~/.pypirc` file: ```ini [distutils] index-servers = pypi [pypi] username = __token__ password = pypi-YOUR_TOKEN_HERE ``` Replace `pypi-YOUR_TOKEN_HERE` with your actual token. ## Step 3: Install Build Tools ```bash uv add --dev build twine ``` ## Step 4: First Publication ### 4.1 Build the Package ```bash # Clean any previous builds rm -rf dist/ build/ *.egg-info/ # Build uv run python -m build ``` You should see files created in `dist/`: - `mcp_server_boilerplate-0.1.0.tar.gz` - `mcp_server_boilerplate-0.1.0-py3-none-any.whl` ### 4.2 Test on TestPyPI (Recommended) ```bash # Upload to test repository uv run twine upload --repository testpypi dist/* ``` When prompted: - Username: `__token__` - Password: Your PyPI token ### 4.3 Test Installation from TestPyPI ```bash # Install from test repository pip install --index-url https://test.pypi.org/simple/ mcp-server-boilerplate # Test it works mcp-server-boilerplate # Uninstall test version pip uninstall mcp-server-boilerplate ``` ### 4.4 Upload to Production PyPI If TestPyPI worked correctly: ```bash uv run twine upload dist/* ``` ## Step 5: Verify Publication 1. **Check PyPI page**: [https://pypi.org/project/mcp-server-boilerplate/](https://pypi.org/project/mcp-server-boilerplate/) 2. **Test installation**: ```bash pip install mcp-server-boilerplate mcp-server-boilerplate ``` 3. **Test in fresh environment**: ```bash # Create new virtual environment python -m venv test_env source test_env/bin/activate # On Windows: test_env\Scripts\activate pip install mcp-server-boilerplate mcp-server-boilerplate deactivate rm -rf test_env ``` ## Step 6: Announce Your Package Update your GitHub README to include the PyPI installation instructions (already done in your current README). ## Future Updates ### Updating the Package 1. **Update version numbers** in both: - `pyproject.toml` → `version = "0.1.1"` - `mcp_server_boilerplate/__init__.py` → `__version__ = "0.1.1"` 2. **Test changes locally**: ```bash uv sync uv run mcp-server-boilerplate ``` 3. **Clean and rebuild**: ```bash rm -rf dist/ build/ *.egg-info/ uv run python -m build ``` 4. **Upload to PyPI**: ```bash uv run twine upload dist/* ``` ### Version Numbering Follow [Semantic Versioning](https://semver.org/): - `0.1.0` → `0.1.1` (patch: bug fixes) - `0.1.1` → `0.2.0` (minor: new features, backward compatible) - `0.2.0` → `1.0.0` (major: breaking changes) ## Troubleshooting ### Common Publishing Errors **"Package already exists"** - You need to increment the version number - PyPI doesn't allow overwriting existing versions **"Invalid authentication"** - Check your token is correct in `~/.pypirc` - Username should be `__token__` - Password should be your full token starting with `pypi-` **"Build fails"** - Run `uv sync` to ensure dependencies are installed - Check that all files are in the right locations ### Testing Issues **"Command not found: mcp-server-boilerplate"** - After pip install, the command should be available globally - Try restarting your terminal - Check that the installation was successful **"Import errors"** - Verify the package structure is correct - Ensure `__init__.py` imports are working ## Quick Checklist Before publishing: - [ ] All tests pass locally - [ ] Version number updated - [ ] GitHub URLs updated in pyproject.toml - [ ] Clean build (`rm -rf dist/`) - [ ] Test on TestPyPI first - [ ] Verify installation works