# 📦 PyPI Setup Guide for Letta MCP Server

This guide explains how to set up PyPI distribution for the Letta MCP Server package, following 2025 best practices.

## 🏗️ Project Structure

The project uses modern Python packaging standards:

```
letta-mcp-server-enhanced/
├── pyproject.toml           # Modern configuration file (replaces setup.py)
├── src/                     # Source layout
│   └── letta_mcp/
│       ├── __init__.py
│       ├── _version.py      # Generated by setuptools-scm
│       └── ...
├── scripts/                 # Build and upload scripts
│   ├── build.py
│   ├── upload.py
│   └── test_install.py
├── .github/workflows/       # Automated CI/CD
│   ├── ci.yml
│   └── release.yml
└── tests/                   # Test suite
```

## 🔧 Configuration Details

### pyproject.toml

The `pyproject.toml` file contains all package configuration:

- **Build System**: Uses setuptools with setuptools-scm for dynamic versioning
- **Project Metadata**: Name, description, authors, license, dependencies
- **Entry Points**: CLI commands (`letta-mcp`, `letta-mcp-server`)
- **Tool Configuration**: Black, Ruff, mypy, pytest settings

### Dynamic Versioning

The project uses setuptools-scm for automatic version management:

- Version is determined from Git tags
- Format: `v1.0.0` → `1.0.0`
- Development versions: `1.0.0.dev123+g1234567`
- Generated `_version.py` file is imported by `__init__.py`

## 🚀 Release Process

### 1. Automated Release (Recommended)

The project includes GitHub Actions workflows for automated releases:

**On tag push** (e.g., `git tag v1.0.0 && git push --tags`):
1. Runs tests across Python 3.10-3.12
2. Builds wheel and source distribution
3. Uploads to PyPI via Trusted Publishing
4. Creates GitHub release

**Setup required**:
1. Enable Trusted Publishing on PyPI:
   - Go to https://pypi.org/manage/project/letta-mcp-server/settings/publishing/
   - Add GitHub repository as trusted publisher
2. Configure repository environments in GitHub:
   - `testpypi` environment for test releases
   - `pypi` environment for production releases

### 2. Manual Release

For manual releases, use the provided scripts:

```bash
# 1. Build the package
python scripts/build.py

# 2. Test the package
python scripts/test_install.py

# 3. Upload to TestPyPI first
python scripts/upload.py --test

# 4. Test TestPyPI installation
python scripts/test_install.py --testpypi

# 5. Upload to production PyPI
python scripts/upload.py --production
```

## 🔑 Authentication Setup

### Trusted Publishing (Recommended)

Trusted Publishing eliminates the need for API tokens:

1. **PyPI Setup**:
   - Go to your PyPI project settings
   - Add GitHub repository as trusted publisher
   - Specify repository owner, name, and workflow

2. **GitHub Setup**:
   - Configure environment protection rules
   - Add required reviewers for production releases

### API Tokens (Alternative)

If not using Trusted Publishing:

1. **Create API tokens**:
   - TestPyPI: https://test.pypi.org/manage/account/#api-tokens
   - PyPI: https://pypi.org/manage/account/#api-tokens

2. **Configure .pypirc**:
   ```ini
   [distutils]
   index-servers = testpypi pypi

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

   [pypi]
   repository = https://upload.pypi.org/legacy/
   username = __token__
   password = your-pypi-token-here  # Your PyPI token
   ```

## 🧪 Testing Strategy

### Local Testing

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run linting
ruff check src/ tests/
black --check src/ tests/

# Run type checking
mypy src/

# Run tests with coverage
pytest --cov=letta_mcp
```

### Package Testing

```bash
# Build and test package
python scripts/build.py
python scripts/test_install.py

# Test from TestPyPI
python scripts/test_install.py --testpypi
```

### CI/CD Testing

The GitHub Actions workflows test:
- Multiple Python versions (3.10, 3.11, 3.12)
- Multiple operating systems (Ubuntu, Windows, macOS)
- Package building and installation
- Security scanning with safety and bandit

## 📋 Pre-Release Checklist

Before releasing:

- [ ] Update version in Git tag (setuptools-scm handles the rest)
- [ ] Update RELEASE_NOTES_v*.md
- [ ] Run full test suite locally
- [ ] Test package building: `python scripts/build.py`
- [ ] Test package installation: `python scripts/test_install.py`
- [ ] Review GitHub Actions workflows are passing
- [ ] Check PyPI Trusted Publishing is configured

## 🔗 Package Information

- **PyPI**: https://pypi.org/project/letta-mcp-server/
- **TestPyPI**: https://test.pypi.org/project/letta-mcp-server/
- **Installation**: `pip install letta-mcp-server`
- **Documentation**: https://github.com/SNYCFIRE-CORE/letta-mcp-server/docs

## 🆘 Troubleshooting

### Common Issues

1. **setuptools-scm can't find version**:
   - Ensure you're in a Git repository
   - Check git tags exist: `git tag --list`
   - Try: `python -m setuptools_scm`

2. **Build fails**:
   - Check dependencies: `pip install -e ".[dev]"`
   - Verify Python version ≥ 3.10
   - Run: `python scripts/build.py` for detailed output

3. **Upload fails**:
   - Verify API token in .pypirc
   - Check package name isn't taken
   - Try TestPyPI first: `python scripts/upload.py --test`

4. **Import fails after installation**:
   - Check entry points in pyproject.toml
   - Verify package structure with: `python -c "import letta_mcp; print(letta_mcp.__file__)"`

### Getting Help

- Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- Open issue: https://github.com/SNYCFIRE-CORE/letta-mcp-server/issues
- Python Packaging User Guide: https://packaging.python.org/

## 📚 Additional Resources

- [Python Packaging User Guide](https://packaging.python.org/)
- [setuptools-scm Documentation](https://setuptools-scm.readthedocs.io/)
- [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
- [GitHub Actions for Python](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python)