# Publishing Guide - PQC Analyzer MCP Server to PyPI

This guide will help you publish your MCP server to PyPI (Python Package Index) so others can install it easily.

## 📋 Prerequisites

Before publishing, ensure you have:
- [x] Python 3.10+ installed
- [x] A PyPI account (create at https://pypi.org/account/register/)
- [x] A GitHub repository (recommended for source code hosting)
- [ ] PyPI API token (for secure publishing)

## 🚀 Publishing Steps

### Step 1: Create PyPI Account

1. Go to https://pypi.org/account/register/
2. Create an account with your email
3. Verify your email address
4. Enable 2FA (Two-Factor Authentication) - **Required for publishing**

### Step 2: Generate API Token

1. Log in to PyPI
2. Go to Account Settings → API tokens
3. Click "Add API token"
4. Name: `pqc-analyzer-mcp`
5. Scope: "Entire account" (for first upload) or "Project: pqc-analyzer-mcp" (after first upload)
6. **Save the token securely** - you'll only see it once!

### Step 3: Configure PyPI Credentials

Create a `.pypirc` file in your home directory:

```bash
cat > ~/.pypirc << 'EOF'
[distutils]
index-servers =
    pypi

[pypi]
username = __token__
password = pypi-YOUR-API-TOKEN-HERE
EOF

chmod 600 ~/.pypirc
```

Replace `pypi-YOUR-API-TOKEN-HERE` with your actual token.

### Step 4: Update Package Metadata

Edit [`pyproject.toml`](pyproject.toml:1) and update:

```toml
[project]
name = "pqc-analyzer-mcp"
version = "1.0.0"  # Update version for each release
authors = [
    {name = "Your Name", email = "your.email@example.com"}  # Update this
]

[project.urls]
Homepage = "https://github.com/yourusername/pqc-analyzer-mcp"  # Update URLs
Repository = "https://github.com/yourusername/pqc-analyzer-mcp"
Issues = "https://github.com/yourusername/pqc-analyzer-mcp/issues"
```

### Step 5: Create GitHub Repository (Recommended)

1. Create a new repository on GitHub: `pqc-analyzer-mcp`
2. Initialize git in your project:

```bash
cd /Users/sucharitapaul/Documents/Cline/MCP/pqc-analyzer
git init
git add .
git commit -m "Initial commit: PQC Analyzer MCP Server v1.0.0"
git branch -M main
git remote add origin https://github.com/yourusername/pqc-analyzer-mcp.git
git push -u origin main
```

3. Update the URLs in `pyproject.toml` with your actual GitHub repository

### Step 6: Build the Package

Install build tools:

```bash
cd /Users/sucharitapaul/Documents/Cline/MCP/pqc-analyzer
source venv/bin/activate
pip install --upgrade build twine
```

Build the distribution packages:

```bash
python -m build
```

This creates:
- `dist/pqc_analyzer_mcp-1.0.0.tar.gz` (source distribution)
- `dist/pqc_analyzer_mcp-1.0.0-py3-none-any.whl` (wheel distribution)

### Step 7: Test on TestPyPI (Optional but Recommended)

Before publishing to the real PyPI, test on TestPyPI:

1. Create account at https://test.pypi.org/account/register/
2. Generate API token for TestPyPI
3. Upload to TestPyPI:

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

4. Test installation:

```bash
pip install --index-url https://test.pypi.org/simple/ pqc-analyzer-mcp
```

### Step 8: Publish to PyPI

Once you're confident everything works:

```bash
python -m twine upload dist/*
```

You'll be prompted for credentials (use `__token__` as username and your API token as password, or it will use your `.pypirc` file).

### Step 9: Verify Publication

1. Visit https://pypi.org/project/pqc-analyzer-mcp/
2. Check that all information is correct
3. Test installation:

```bash
pip install pqc-analyzer-mcp
```

## 📦 Installation Instructions for Users

Once published, users can install your MCP server with:

```bash
pip install pqc-analyzer-mcp
```

### Configuration for IBM Bob

Users add to their MCP settings:

```json
{
  "mcpServers": {
    "pqc-analyzer": {
      "command": "pqc-analyzer",
      "disabled": false
    }
  }
}
```

### Configuration for Claude Desktop

Users add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pqc-analyzer": {
      "command": "pqc-analyzer"
    }
  }
}
```

## 🔄 Updating Your Package

When you make changes and want to release a new version:

### 1. Update Version Number

Edit `pyproject.toml`:

```toml
version = "1.0.1"  # Increment version
```

Version numbering follows [Semantic Versioning](https://semver.org/):
- **MAJOR** (1.x.x): Breaking changes
- **MINOR** (x.1.x): New features, backward compatible
- **PATCH** (x.x.1): Bug fixes, backward compatible

### 2. Update CHANGELOG

Create/update `CHANGELOG.md`:

```markdown
# Changelog

## [1.0.1] - 2026-02-11

### Fixed
- Bug fix description

### Added
- New feature description

## [1.0.0] - 2026-02-11

### Added
- Initial release
```

### 3. Commit Changes

```bash
git add .
git commit -m "Release v1.0.1: Description of changes"
git tag v1.0.1
git push origin main --tags
```

### 4. Rebuild and Republish

```bash
# Clean old builds
rm -rf dist/ build/ *.egg-info

# Build new version
python -m build

# Upload to PyPI
python -m twine upload dist/*
```

## 📊 Package Statistics

After publishing, you can track:
- **Downloads**: https://pypistats.org/packages/pqc-analyzer-mcp
- **GitHub Stars**: Track on your repository
- **Issues**: Monitor GitHub issues for user feedback

## 🔒 Security Best Practices

1. **Never commit API tokens** to git
2. **Use API tokens** instead of passwords
3. **Enable 2FA** on PyPI account
4. **Review dependencies** regularly for vulnerabilities
5. **Sign releases** with GPG (optional but recommended)

## 📝 Package Metadata Checklist

Before publishing, verify:

- [ ] Package name is unique on PyPI
- [ ] Version number follows semantic versioning
- [ ] README.md is comprehensive and up-to-date
- [ ] LICENSE file is included (MIT)
- [ ] Author information is correct
- [ ] Repository URLs are correct
- [ ] Keywords are relevant for discoverability
- [ ] Classifiers are accurate
- [ ] Dependencies are specified correctly
- [ ] Package builds without errors
- [ ] Installation works in clean environment

## 🎯 Marketing Your Package

### 1. Update README.md

Ensure your README includes:
- Clear description and purpose
- Installation instructions
- Quick start guide
- Usage examples
- Screenshots/demos (if applicable)
- Badges (PyPI version, downloads, license)

### 2. Add Badges to README

```markdown
[![PyPI version](https://badge.fury.io/py/pqc-analyzer-mcp.svg)](https://badge.fury.io/py/pqc-analyzer-mcp)
[![Downloads](https://pepy.tech/badge/pqc-analyzer-mcp)](https://pepy.tech/project/pqc-analyzer-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
```

### 3. Announce Your Package

- Post on relevant forums (Reddit: r/Python, r/cryptography)
- Share on social media (Twitter, LinkedIn)
- Submit to awesome lists (awesome-python, awesome-mcp)
- Write a blog post about your package
- Present at local Python meetups

### 4. Documentation

Consider creating documentation with:
- **Read the Docs**: https://readthedocs.org/
- **GitHub Pages**: Host docs on your repository
- **MkDocs**: Generate beautiful documentation

## 🐛 Troubleshooting

### Error: "Package name already exists"

Choose a different name in `pyproject.toml`. Check availability:
```bash
pip search pqc-analyzer-mcp
```

### Error: "Invalid credentials"

- Verify API token is correct
- Check `.pypirc` file permissions (should be 600)
- Ensure 2FA is enabled on PyPI

### Error: "Build failed"

- Check `pyproject.toml` syntax
- Ensure all required files exist
- Verify Python version compatibility

### Error: "Import errors after installation"

- Check package structure matches `pyproject.toml`
- Verify `__init__.py` exists in package directory
- Test in clean virtual environment

## 📚 Additional Resources

- **PyPI Documentation**: https://packaging.python.org/
- **Twine Documentation**: https://twine.readthedocs.io/
- **Semantic Versioning**: https://semver.org/
- **Python Packaging Guide**: https://packaging.python.org/tutorials/packaging-projects/
- **MCP Documentation**: https://modelcontextprotocol.io/

## 🎉 Success!

Once published, your package will be available at:
- **PyPI**: https://pypi.org/project/pqc-analyzer-mcp/
- **Installation**: `pip install pqc-analyzer-mcp`
- **Documentation**: Your GitHub repository

Users worldwide can now easily install and use your PQC Analyzer MCP Server!

---

**Need help?** Open an issue on your GitHub repository or consult the PyPI documentation.