# PyPI Publication Plan for TealFlowMCP

## Overview

This document outlines the steps required to prepare TealFlowMCP for publication on PyPI. The implementation focuses on essential changes to make the package installable and functional via `pip install tealflow-mcp`.

**Estimated Time**: 2-3 hours
**Difficulty**: Moderate
**Risk Level**: Low (no breaking changes to existing functionality)

---

## Phase 1: Restructure Knowledge Base (Critical)

### Objective
Move essential knowledge base files inside the package to ensure they're included in the PyPI distribution.

### Files to Move

**Create new directory:**
```bash
mkdir -p tealflow_mcp/knowledge_base
```

**Move essential files** (only mandatory files):
```bash
# From knowledge_base/ to tealflow_mcp/knowledge_base/
- agent.md (37 KB)
- teal_modules_clinical_dataset_requirements.json (13 KB)
- teal_modules_clinical_modules_requirements.json (72 KB)
- teal_modules_general_modules_requirements.json (45 KB)
- teal_modules_clinical_by_analysis_type.json (8.4 KB)
- teal_modules_general_by_analysis_type.json (5.8 KB)
- app.template.R (391 bytes)
```

**Total package size for essential files**: ~181 KB

**Files to EXCLUDE** (not needed at runtime):
- `*.Rds` files (sample data - 485 KB)
- `data.R` (example code)
- `claude.py` (utility script)
- `SAP_001.txt`, `hello.txt` (test files)
- `.claude/` directory (configuration)

### Create Package Marker

Create empty `__init__.py` to mark as Python package:
```bash
touch tealflow_mcp/knowledge_base/__init__.py
```

### Update Path Resolution

**File**: `tealflow_mcp/core/constants.py`

**Current code**:
```python
KNOWLEDGE_BASE_DIR = Path(__file__).parent.parent.parent / "knowledge_base"
```

**New code**:
```python
KNOWLEDGE_BASE_DIR = Path(__file__).parent.parent / "knowledge_base"
```

**Explanation**: Changes from 3 levels up (to project root) to 2 levels up (to package root), then into knowledge_base subdirectory.

### Verification
After moving files, verify imports still work:
```bash
uv run python -c "from tealflow_mcp.core.constants import KNOWLEDGE_BASE_DIR; print(KNOWLEDGE_BASE_DIR); print(KNOWLEDGE_BASE_DIR.exists())"
```

Expected output: Path should exist and point to `tealflow_mcp/knowledge_base/`

---

## Phase 2: Update Package Metadata

### Objective
Add required PyPI metadata to pyproject.toml

### File: `pyproject.toml`

**Changes Required**:

#### 1. Update Project Description
**Current**:
```toml
description = "Add your description here"
```

**New**:
```toml
description = "MCP server for discovering, understanding, and generating Teal R Shiny applications for clinical trial data analysis"
```

#### 2. Add Authors
**Add after description**:
```toml
authors = [
    { name = "Kuba [Your Last Name]", email = "your.email@example.com" }
]
maintainers = [
    { name = "Kuba [Your Last Name]", email = "your.email@example.com" }
]
```

**Note**: Replace with your actual name and email.

#### 3. Add License
**Add after maintainers**:
```toml
license = { text = "MIT" }
```

**Note**: Adjust license type if you prefer Apache-2.0, BSD, or other. MIT is most common.

#### 4. Add Build System
**Add at the top of file** (before `[project]`):
```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```

#### 5. Add Project URLs
**Add after license**:
```toml
[project.urls]
Homepage = "https://github.com/yourusername/TealFlowMCP"
Repository = "https://github.com/yourusername/TealFlowMCP"
Documentation = "https://github.com/yourusername/TealFlowMCP#readme"
"Bug Tracker" = "https://github.com/yourusername/TealFlowMCP/issues"
```

**Note**: Replace `yourusername` with your actual GitHub username.

#### 6. Add Console Script Entry Point
**Add after project.urls**:
```toml
[project.scripts]
tealflow-mcp = "tealflow_mcp:main"
```

**Note**: This requires adding a `main()` function (see Phase 3).

#### 7. Add Keywords and Classifiers
**Add after license**:
```toml
keywords = [
    "mcp",
    "model-context-protocol",
    "teal",
    "clinical-trials",
    "shiny",
    "r",
    "cdisc",
    "adam"
]

classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Software Development :: Libraries :: Python Modules",
    "Topic :: Scientific/Engineering",
]
```

---

## Phase 3: Add Entry Point Function

### Objective
Create a proper entry point for the console script

### File: `tealflow_mcp.py`

**Add at the end of file** (before `if __name__ == "__main__":`):

```python
def main() -> None:
    """Entry point for the tealflow-mcp console command."""
    mcp.run()


if __name__ == "__main__":
    # Run the MCP server
    main()
```

**Changes**:
- Extract `mcp.run()` into a `main()` function
- Update `if __name__ == "__main__":` to call `main()`

This allows the console script to work: `tealflow-mcp` will call `main()`

---

## Phase 4: Add Version Management

### Objective
Add version information to the package

### File: `tealflow_mcp/__init__.py`

**Add at the top** (after existing imports):
```python
__version__ = "0.1.0"
```

**Update the `__all__` list** to include version:
```python
__all__ = [
    "__version__",
    # ... existing exports ...
]
```

### Update pyproject.toml

**Option 1: Static version** (simpler, recommended):
Keep `version = "0.1.0"` in pyproject.toml as-is.

**Option 2: Dynamic version** (more advanced):
```toml
# In [project] section, remove static version line and add:
dynamic = ["version"]

# Add new section:
[tool.hatch.version]
path = "tealflow_mcp/__init__.py"
```

**Recommendation**: Use Option 1 (static) for simplicity. Update both places when bumping version.

---

## Phase 5: Create LICENSE File

### Objective
Add a license file (required by PyPI)

### File: `LICENSE`

**For MIT License** (recommended):
```
MIT License

Copyright (c) 2025 [Your Name]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

**Note**: Replace `[Your Name]` and year as appropriate.

---

## Phase 6: Update .gitignore

### Objective
Ensure build artifacts are ignored by git

### File: `.gitignore`

**Verify these patterns exist**:
```
# Distribution / packaging
dist/
build/
*.egg-info/
*.egg
wheels/

# PyPI
.pypirc
```

**Current status**: Already properly configured ✓

---

## Phase 7: Update README for PyPI

### Objective
Ensure README displays correctly on PyPI

### File: `README.md`

**Current status**: Comprehensive README already exists (528 lines) ✓

**Optional improvements**:
1. Add installation instructions at the top:
   ```markdown
   ## Installation

   ```bash
   pip install tealflow-mcp
   ```

   For development:
   ```bash
   git clone https://github.com/yourusername/TealFlowMCP.git
   cd TealFlowMCP
   uv sync
   ```
   ```

2. Add PyPI badge (after publishing):
   ```markdown
   [![PyPI version](https://badge.fury.io/py/tealflow-mcp.svg)](https://badge.fury.io/py/tealflow-mcp)
   ```

---

## Phase 8: Build and Test Locally

### Objective
Build the package locally and verify it works

### Commands

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

**2. Build the package**:
```bash
uv build
```

**Note**: `uv` has build tools built-in, no need to install separately.

**Expected output**:
```
dist/
├── tealflow_mcp-0.1.0-py3-none-any.whl
└── tealflow_mcp-0.1.0.tar.gz
```

**3. Verify package contents**:
```bash
# Check wheel contents
uv run python -m zipfile -l dist/tealflow_mcp-0.1.0-py3-none-any.whl

# Verify knowledge_base is included
uv run python -m zipfile -l dist/tealflow_mcp-0.1.0-py3-none-any.whl | grep knowledge_base
```

**Expected output should include**:
```
tealflow_mcp/knowledge_base/__init__.py
tealflow_mcp/knowledge_base/agent.md
tealflow_mcp/knowledge_base/app.template.R
tealflow_mcp/knowledge_base/teal_modules_clinical_by_analysis_type.json
tealflow_mcp/knowledge_base/teal_modules_clinical_dataset_requirements.json
tealflow_mcp/knowledge_base/teal_modules_clinical_modules_requirements.json
tealflow_mcp/knowledge_base/teal_modules_general_by_analysis_type.json
tealflow_mcp/knowledge_base/teal_modules_general_modules_requirements.json
```

**4. Check package metadata**:
```bash
uv run twine check dist/*
```

**Expected**: `PASSED` for all checks

**5. Test installation in a clean environment**:
```bash
# Create test virtualenv
python -m venv test_env
source test_env/bin/activate

# Install from local build
pip install dist/tealflow_mcp-0.1.0-py3-none-any.whl

# Test the entry point
tealflow-mcp --help

# Test importing
python -c "import tealflow_mcp; print(tealflow_mcp.__version__)"

# Test that knowledge base is accessible
python -c "from tealflow_mcp.core.constants import KNOWLEDGE_BASE_DIR; print(KNOWLEDGE_BASE_DIR.exists())"

# Deactivate and clean up
deactivate
rm -rf test_env
```

---

## Phase 9: Publish to Test PyPI

### Objective
Test the publication process using TestPyPI

### Prerequisites

**1. Create TestPyPI account**:
- Visit: https://test.pypi.org/account/register/
- Verify email

**2. Create API token**:
- Go to: https://test.pypi.org/manage/account/token/
- Create token with scope: "Entire account"
- **Save token securely** (you'll need to paste it during upload)

### Upload

**Upload to TestPyPI (Manual Token Entry - SECURE)**:
```bash
# Twine will prompt for credentials
twine upload --repository testpypi dist/*

# When prompted:
# Username: __token__
# Password: [paste your TestPyPI token here - it starts with "pypi-"]
```

**Note**: This approach is more secure than storing tokens in `.pypirc` as the token is never written to disk.

**2. Verify upload**:
- Visit: https://test.pypi.org/project/tealflow-mcp/

**3. Test installation from TestPyPI**:
```bash
# Create clean environment
python -m venv test_pypi_env
source test_pypi_env/bin/activate

# Install from TestPyPI (with dependencies from real PyPI)
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ tealflow-mcp

# Run tests
tealflow-mcp --help
python -c "import tealflow_mcp; print(tealflow_mcp.__version__)"

# Deactivate
deactivate
rm -rf test_pypi_env
```

---

## Phase 10: Publish to PyPI (Production)

### Objective
Publish to the real PyPI

### Prerequisites

**1. Create PyPI account**:
- Visit: https://pypi.org/account/register/
- Verify email

**2. Create API token**:
- Go to: https://pypi.org/manage/account/token/
- Create token with scope: "Entire account" (or project-specific after first upload)
- **Save token securely** (you'll need to paste it during upload)

### Upload

**1. Final verification**:
```bash
# Ensure tests pass
uv run python -m pytest tests/ -v

# Ensure CI checks pass
uv run ruff check tealflow_mcp/ tests/
uv run ruff format tealflow_mcp/ tests/ --check
uv run mypy tealflow_mcp/
```

**2. Upload to PyPI (Manual Token Entry - SECURE)**:
```bash
# Twine will prompt for credentials
twine upload dist/*

# When prompted:
# Username: __token__
# Password: [paste your PyPI token here - it starts with "pypi-"]
```

**Note**: This approach is more secure than storing tokens in `.pypirc` as the token is never written to disk.

**3. Verify**:
- Visit: https://pypi.org/project/tealflow-mcp/
- Check metadata displays correctly
- Check README renders properly

**4. Test installation**:
```bash
# In a clean environment
pip install tealflow-mcp

# Verify
tealflow-mcp --help
```

---

## Phase 11: Post-Publication Tasks

### Update README

Add installation badge and instructions:
```markdown
## Installation

```bash
pip install tealflow-mcp
```

[![PyPI version](https://badge.fury.io/py/tealflow-mcp.svg)](https://pypi.org/project/tealflow-mcp/)
[![Python Support](https://img.shields.io/pypi/pyversions/tealflow-mcp.svg)](https://pypi.org/project/tealflow-mcp/)
```

### Update Documentation

Add to MCP configuration examples showing pip installation:
```json
{
  "mcpServers": {
    "tealflow": {
      "command": "tealflow-mcp"
    }
  }
}
```

### Create GitHub Release

1. Tag the release:
   ```bash
   git tag -a v0.1.0 -m "Release v0.1.0"
   git push origin v0.1.0
   ```

2. Create GitHub release with changelog

---

## Phase 12: MCP Registry Publication (Optional but Recommended)

### Objective
Publish TealFlowMCP to the official MCP Registry for enhanced discoverability

### Prerequisites

**Completed Phase 10** (PyPI publication must be done first)

### Time Estimate
**~30 minutes**

### Step 1: Install mcp-publisher CLI

**macOS/Linux**:
```bash
# Option 1: Homebrew (recommended)
brew install mcp-publisher

# Option 2: Direct download
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m).tar.gz" | tar xz mcp-publisher
sudo mv mcp-publisher /usr/local/bin/
```

**Windows**:
```powershell
# Download from GitHub releases
# https://github.com/modelcontextprotocol/registry/releases/latest
```

**Verify installation**:
```bash
mcp-publisher --version
```

### Step 2: Create server.json

**Create file in repository root**:
```bash
# Initialize with interactive prompts
mcp-publisher init

# Or create manually:
touch server.json
```

**File: `server.json`**

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.yourusername/tealflow-mcp",
  "title": "TealFlow MCP",
  "description": "MCP server for discovering, understanding, and generating Teal R Shiny applications for clinical trial data analysis. Enables LLMs to work with teal.modules.clinical and teal.modules.general packages programmatically.",
  "repository": {
    "url": "https://github.com/yourusername/TealFlowMCP",
    "source": "github"
  },
  "version": "0.1.0",
  "packages": [
    {
      "registryType": "pypi",
      "identifier": "tealflow-mcp",
      "version": "0.1.0",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "capabilities": {
    "tools": true,
    "prompts": false,
    "resources": false
  }
}
```

**Important fields**:
- `name`: Must match format `io.github.username/project-name`
- `repository.url`: Your actual GitHub repository URL
- `packages.identifier`: Must match your PyPI package name exactly
- `version`: Must match your PyPI package version

### Step 3: Add MCP Registry Verification to README

**File: `README.md`**

**Add at the top of README** (after title, before description):
```markdown
<!-- mcp-name: io.github.yourusername/tealflow-mcp -->
```

**Complete example**:
```markdown
# TealFlowMCP

<!-- mcp-name: io.github.yourusername/tealflow-mcp -->

TealFlowMCP is an MCP (Model Context Protocol) server that enables LLMs to discover...
```

**Why this is needed**: This comment provides verification that you own the PyPI package. The MCP Registry will check that this comment exists in your PyPI package's README before accepting publication.

### Step 4: Authenticate with MCP Registry

**Authenticate using GitHub**:
```bash
mcp-publisher login github
```

**Steps**:
1. CLI will display a device code
2. Visit: https://github.com/login/device
3. Enter the device code
4. Authorize the application
5. CLI will confirm successful authentication

**Verify authentication**:
```bash
mcp-publisher whoami
```

### Step 5: Validate server.json

**Run validation before publishing**:
```bash
mcp-publisher validate
```

**Expected output**:
```
✓ server.json is valid
✓ Package verification found in README
✓ PyPI package exists: tealflow-mcp@0.1.0
```

**Fix any validation errors** before proceeding.

### Step 6: Publish to MCP Registry

**Publish the server metadata**:
```bash
mcp-publisher publish
```

**Expected output**:
```
Publishing server: io.github.yourusername/tealflow-mcp
✓ Validated server.json
✓ Verified package ownership
✓ Published to registry

Server URL: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.yourusername/tealflow-mcp
```

### Step 7: Verify Publication

**Check via API**:
```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.yourusername/tealflow-mcp" | jq
```

**Expected response**:
```json
{
  "name": "io.github.yourusername/tealflow-mcp",
  "title": "TealFlow MCP",
  "description": "MCP server for discovering, understanding...",
  "version": "0.1.0",
  "packages": [...],
  "repository": {...}
}
```

**Search the registry**:
```bash
curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=tealflow" | jq
```

### Step 8: Update Documentation

**Add MCP Registry badge to README**:
```markdown
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/servers/io.github.yourusername/tealflow-mcp)
```

**Update installation instructions**:
```markdown
## Installation

### Via pip (recommended)
```bash
pip install tealflow-mcp
```

### MCP Configuration

After installation, configure in your MCP client:

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "tealflow": {
      "command": "tealflow-mcp"
    }
  }
}
```

**VSCode** (when MCP support is available):
Registry URL: `https://registry.modelcontextprotocol.io/servers/io.github.yourusername/tealflow-mcp`
```

### Step 9: Update server.json for Future Versions

**When releasing new versions**:

1. Update version in `pyproject.toml` and `tealflow_mcp/__init__.py`
2. Build and publish to PyPI
3. Update `server.json`:
   ```json
   {
     "version": "0.2.0",
     "packages": [
       {
         "version": "0.2.0",
         ...
       }
     ]
   }
   ```
4. Re-publish to registry:
   ```bash
   mcp-publisher publish
   ```

### Troubleshooting

**Error: "Package verification not found"**
- Ensure `<!-- mcp-name: ... -->` comment is in README.md
- Republish to PyPI with updated README
- Wait 5-10 minutes for PyPI to index

**Error: "Package does not exist"**
- Verify PyPI package name matches exactly
- Check package is publicly visible on PyPI
- Try publishing to PyPI again

**Error: "Authentication failed"**
- Re-run `mcp-publisher login github`
- Check GitHub permissions for the app
- Try revoking and re-authorizing

**Error: "Version mismatch"**
- Ensure `server.json` version matches PyPI package version exactly
- Update both to the same version

### Benefits of MCP Registry Publication

1. **Discoverability**: Users can find your server via registry search
2. **Future-proof**: Ready for VSCode/IDE marketplace integration
3. **Centralized metadata**: Single source of truth for server info
4. **Verification**: Official verification of package ownership
5. **API access**: Clients can programmatically discover and install
6. **Community**: Listed alongside other MCP servers in ecosystem

### Registry API Endpoints

**Search for your server**:
```
GET https://registry.modelcontextprotocol.io/v0.1/servers?search=tealflow
```

**Get server details**:
```
GET https://registry.modelcontextprotocol.io/v0.1/servers/io.github.yourusername/tealflow-mcp
```

**List all servers**:
```
GET https://registry.modelcontextprotocol.io/v0.1/servers
```

### Post-Registry Publication Checklist

- [ ] Install mcp-publisher CLI
- [ ] Create server.json with correct metadata
- [ ] Add verification comment to README.md
- [ ] Republish to PyPI with updated README
- [ ] Authenticate with GitHub
- [ ] Validate server.json
- [ ] Publish to MCP Registry
- [ ] Verify via API
- [ ] Update README with registry badge
- [ ] Update documentation with registry URL
- [ ] Test discovery via registry API

---

## Phase 12 Success Criteria

1. ✅ `server.json` passes validation
2. ✅ Verification comment present in PyPI README
3. ✅ Successfully authenticated with GitHub
4. ✅ Published to MCP Registry without errors
5. ✅ Server appears in registry search results
6. ✅ API returns correct server metadata
7. ✅ Documentation updated with registry information

---

## Rollback Plan

If issues are discovered after publication:

**1. Yank the release** (doesn't delete, but marks as broken):
```bash
# Via PyPI web interface or:
twine upload --repository pypi --skip-existing dist/* --yank
```

**2. Fix issues and publish new version**:
```bash
# Update version to 0.1.1 in pyproject.toml and __init__.py
# Rebuild and republish
```

---

## Checklist

Use this checklist during implementation:

### Phase 1: Knowledge Base Restructure
- [ ] Create `tealflow_mcp/knowledge_base/` directory
- [ ] Move 7 essential files (agent.md, 6 JSONs, app.template.R)
- [ ] Create `tealflow_mcp/knowledge_base/__init__.py`
- [ ] Update `tealflow_mcp/core/constants.py` path
- [ ] Verify path resolution works
- [ ] Run tests: `uv run python -m pytest tests/ -v`

### Phase 2: Package Metadata
- [ ] Update description in pyproject.toml
- [ ] Add authors/maintainers
- [ ] Add license field
- [ ] Add build-system section
- [ ] Add project URLs
- [ ] Add console script entry point
- [ ] Add keywords and classifiers

### Phase 3: Entry Point
- [ ] Add `main()` function to tealflow_mcp.py
- [ ] Update `if __name__ == "__main__":` block

### Phase 4: Version Management
- [ ] Add `__version__` to `tealflow_mcp/__init__.py`
- [ ] Update `__all__` list

### Phase 5: License
- [ ] Create LICENSE file with chosen license

### Phase 6: .gitignore
- [ ] Verify build artifacts are ignored (already done ✓)

### Phase 7: README
- [ ] Add installation instructions
- [ ] Review for PyPI display

### Phase 8: Build and Test
- [ ] Install build tools
- [ ] Clean previous builds
- [ ] Build package
- [ ] Verify wheel contents include knowledge_base
- [ ] Run `twine check`
- [ ] Test installation in clean virtualenv
- [ ] Verify entry point works
- [ ] Verify knowledge_base is accessible

### Phase 9: TestPyPI
- [ ] Create TestPyPI account
- [ ] Create API token
- [ ] Configure ~/.pypirc
- [ ] Upload to TestPyPI
- [ ] Test installation from TestPyPI
- [ ] Verify functionality

### Phase 10: Production PyPI
- [ ] Create PyPI account
- [ ] Create API token
- [ ] Update ~/.pypirc
- [ ] Run all CI checks
- [ ] Upload to PyPI
- [ ] Verify project page
- [ ] Test installation from PyPI

### Phase 11: Post-Publication
- [ ] Update README with badges
- [ ] Update documentation
- [ ] Create GitHub release
- [ ] Tag version in git

### Phase 12: MCP Registry (Optional)
- [ ] Install mcp-publisher CLI
- [ ] Create server.json
- [ ] Add verification comment to README
- [ ] Republish to PyPI with updated README
- [ ] Authenticate with GitHub
- [ ] Validate server.json
- [ ] Publish to MCP Registry
- [ ] Verify publication via API
- [ ] Update documentation with registry info

---

## Estimated Timeline

| Phase | Task | Time |
|-------|------|------|
| 1 | Knowledge base restructure | 30 min |
| 2 | Update pyproject.toml | 20 min |
| 3 | Add entry point | 10 min |
| 4 | Version management | 10 min |
| 5 | Create LICENSE | 5 min |
| 6 | .gitignore check | 2 min |
| 7 | Update README | 15 min |
| 8 | Build and test locally | 30 min |
| 9 | TestPyPI publication | 20 min |
| 10 | Production PyPI | 15 min |
| 11 | Post-publication tasks | 20 min |
| 12 | MCP Registry (optional) | 30 min |
| **Total** | | **~3 hours** |

---

## Success Criteria

The implementation is successful when:

### Required (Phases 1-11)
1. ✅ Package builds without errors: `python -m build`
2. ✅ Package passes twine checks: `twine check dist/*`
3. ✅ Knowledge base files are included in wheel
4. ✅ All 153 tests pass after restructure
5. ✅ Entry point works: `tealflow-mcp --help`
6. ✅ Can install from TestPyPI successfully
7. ✅ Can install from PyPI successfully
8. ✅ MCP server functions correctly after pip install
9. ✅ All metadata displays correctly on PyPI project page
10. ✅ Documentation is clear and accurate

### Optional (Phase 12 - MCP Registry)
11. ✅ Server published to MCP Registry
12. ✅ Server discoverable via registry API
13. ✅ Package verification successful
14. ✅ Documentation includes registry information

---

## Notes

- **Package size**: ~181 KB (excluding optional .Rds sample files)
- **Breaking changes**: None - existing development workflows continue to work
- **Python versions**: Supports Python 3.10+
- **Dependencies**: All dependencies are already properly specified in pyproject.toml
- **Backwards compatibility**: Development mode (`uv sync`) continues to work as before
