# PDFBlocks MCP - Deployment Guide

This guide covers deploying PDFBlocks MCP to PyPI and registering it in the MCP servers repository.

## Prerequisites

- Python 3.10+
- PyPI account (https://pypi.org/account/register/)
- Git repository access

## PyPI Deployment

### 1. Install Build Tools

```bash
pip install build twine
```

### 2. Build the Package

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

# Build distribution packages
python -m build
```

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

### 3. Validate the Build

```bash
# Check the distribution files
twine check dist/*
```

### 4. Test on TestPyPI (Optional but Recommended)

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

# Install from TestPyPI to test
pip install --index-url https://test.pypi.org/simple/ pdfblocks-mcp

# Test the installation
python -c "from src import server; print('Import successful')"
```

### 5. Upload to PyPI

```bash
# Upload to production PyPI
twine upload dist/*

# Enter your PyPI credentials when prompted
# Username: __token__
# Password: pypi-xxx... (your API token)
```

### 6. Verify Deployment

```bash
# Install from PyPI
pip install pdfblocks-mcp

# Verify installation
pip show pdfblocks-mcp
python -c "from src import server; print('Success!')"
```

## PyPI Configuration

### Using API Tokens (Recommended)

Create `.pypirc` in your home directory:

```ini
[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-testpypi-token-here
```

Set proper permissions:
```bash
chmod 600 ~/.pypirc
```

## Version Management

Update version in **both** files:
- `pyproject.toml` → `version = "x.y.z"`
- `setup.py` → `version="x.y.z"`

Version scheme: `MAJOR.MINOR.PATCH`
- MAJOR: Breaking changes
- MINOR: New features, backward compatible
- PATCH: Bug fixes

## MCP Servers Repository Registration

### 1. Fork the Repository

Visit https://github.com/modelcontextprotocol/servers and fork it.

### 2. Clone Your Fork

```bash
git clone https://github.com/YOUR_USERNAME/servers.git
cd servers
```

### 3. Create Server Directory

```bash
mkdir -p src/pdfblocks
cd src/pdfblocks
```

### 4. Add Required Files

Copy these files from PDFBlocks repository:
- `README.md` - Project documentation
- `index.json` - Server definition (based on server.json)

### 5. Create Pull Request

```bash
git checkout -b add-pdfblocks
git add src/pdfblocks/
git commit -m "Add PDFBlocks MCP Server"
git push origin add-pdfblocks
```

Then create PR on GitHub with description:
```markdown
## PDFBlocks MCP Server

Block-based PDF extraction optimized for LLM consumption.

### Features
- Automatic PDF corruption detection
- Structured block extraction (text, tables, images)
- Intelligent image filtering and optimization
- Context-aware pagination for large PDFs

### Links
- PyPI: https://pypi.org/project/pdfblocks-mcp/
- GitHub: https://github.com/PyJudge/pdfblocks-mcp
- License: MIT
```

## Troubleshooting

### Build Fails

```bash
# Check pyproject.toml and setup.py syntax
python -m build --verbose
```

### Upload Fails

```bash
# Verify credentials
twine check dist/*

# Check package name availability
# Visit: https://pypi.org/project/pdfblocks-mcp/
```

### Import Errors After Installation

```bash
# Check package structure
pip show -f pdfblocks-mcp

# Reinstall in editable mode for testing
pip install -e .
```

## Post-Deployment Checklist

- [ ] Package appears on PyPI: https://pypi.org/project/pdfblocks-mcp/
- [ ] README renders correctly on PyPI
- [ ] Installation works: `pip install pdfblocks-mcp`
- [ ] Import works: `python -c "from src import server"`
- [ ] GitHub release created with tag `v1.0.0`
- [ ] MCP servers PR submitted
- [ ] Documentation updated with installation instructions

## Security Notes

**NEVER commit**:
- `.pypirc` (contains API tokens)
- `config.json` (personal configuration)
- `sample_pdfs/` (test data)
- API tokens or credentials

These are protected by `.gitignore`.

## References

- PyPI Documentation: https://packaging.python.org/
- Twine Documentation: https://twine.readthedocs.io/
- MCP Servers: https://github.com/modelcontextprotocol/servers
