# Story 1.5: Ensure MVP Package Build and PyPI Readiness

## Status: Done

## Story

As a Project Maintainer, I want the Fabric MCP Server to be correctly configured for building distributions (sdist and wheel) using `hatch` and ready for an initial MVP publication to PyPI (starting with TestPyPI) so that users can easily install and run the server.

## Acceptance Criteria (ACs)

1. `pyproject.toml` fully configured for `hatchling` build (metadata, Python version, dependencies, scripts).
2. `make build` (or `uv run hatch build`) successfully generates sdist and wheel in `dist/`.
3. Wheel can be installed in a clean virtual env via `pip` and `uv`.
4. Installed `fabric-mcp` script is executable and responds to `--version` / `--help`.
5. Package successfully uploaded to TestPyPI and installable from TestPyPI.
6. (Optional) Package successfully uploaded to official PyPI.
7. `README.md` includes PyPI installation instructions.

## Tasks / Subtasks

- [x] Task 1: Validate and finalize `pyproject.toml` configuration (AC: 1)
  - [x] Verify `hatchling>=1.27.0` as build backend
  - [x] Ensure dynamic version reads from `src/fabric_mcp/__about__.py`
  - [x] Validate all project metadata (name, description, authors, license, classifiers)
  - [x] Confirm `fabric-mcp` script entry point points to `fabric_mcp.cli:main`
  - [x] Verify dependencies list is complete and version-pinned appropriately
  - [x] Validate `tool.hatch.build.targets.wheel` and `tool.hatch.build.targets.sdist` configurations
  - [x] Ensure `tool.uv.index` includes both TestPyPI and PyPI with publish URLs

- [x] Task 2: Test local package building process (AC: 2)
  - [x] Clean previous build artifacts: `rm -rf dist/`
  - [x] Execute `uv run hatch build` and verify it completes without errors
  - [x] Confirm generation of both `.tar.gz` (sdist) and `.whl` (wheel) files in `dist/`
  - [x] Validate package contents using `tar -tf` for sdist and `unzip -l` for wheel
  - [x] Verify wheel contains correct package structure under `fabric_mcp/`

- [x] Task 3: Test local package installation and functionality (AC: 3, 4)
  - [x] Create clean virtual environment: `python -m venv test_env && source test_env/bin/activate`
  - [x] Install wheel using pip: `pip install dist/fabric_mcp-*.whl`
  - [x] Verify `fabric-mcp` command is available in PATH
  - [x] Test `fabric-mcp --version` returns expected version from `__about__.py`
  - [x] Test `fabric-mcp --help` displays proper CLI help with click-based interface
  - [x] Test installation via uv: `uv pip install dist/fabric_mcp-*.whl` in fresh environment
  - [x] Validate that installed package can import successfully: `python -c "import fabric_mcp; print('OK')"`

- [x] Task 4: Configure and test TestPyPI publication (AC: 5)
  - [x] Ensure TestPyPI credentials are configured (API token via environment or uv config)
  - [x] Upload to TestPyPI: `uv publish --index testpypi`
  - [x] Verify package appears on TestPyPI: <https://test.pypi.org/project/fabric-mcp/>
  - [x] Test installation from TestPyPI in clean environment
  - [x] Command: `uv pip install --index testpypi fabric-mcp`
  - [x] Verify installed version functionality matches local wheel test

- [x] Task 5: Update documentation with installation instructions (AC: 7)
  - [x] Add PyPI installation section to `README.md`
  - [x] Include both pip and uv installation commands
  - [x] Add version checking and basic usage examples
  - [x] Update any references to development installation vs. user installation
  - [x] Ensure installation instructions are consistent with project goals

- [x] Task 6: (Optional) Publish to official PyPI (AC: 6)
  - [x] Configure PyPI credentials (API token)
  - [x] Upload to PyPI: `uv publish --index pypi`
  - [x] Verify package appears on PyPI: <https://pypi.org/project/fabric-mcp/>
  - [x] Test installation from PyPI: `pip install fabric-mcp`
  - [x] Update README.md badge links to reflect PyPI availability

## Dev Technical Guidance

### Build System Configuration

The project uses **hatchling** as the build backend with **uv** as the package manager. Key configuration details:

- **Version Management**: Dynamic versioning via `tool.hatch.version.path = "src/fabric_mcp/__about__.py"`
- **Build Targets**: Configured for both wheel (`packages = ["src/fabric_mcp"]`) and sdist (`sources = ["src"]`)
- **Entry Points**: `fabric-mcp = "fabric_mcp.cli:main"` script defined in `project.scripts`

### Current Dependencies (per pyproject.toml)

**Runtime Dependencies:**

- `click>=8.2.1` (CLI framework)
- `httpx>=0.28.1` (HTTP client for Fabric API)
- `modelcontextprotocol>=0.1.0` (MCP protocol implementation)
- `fastmcp>=2.5.2` (MCP server framework)
- `rich>=14.0.0` (Enhanced terminal output)
- `httpx-retries>=0.4.0` (HTTP retry mechanisms)

### Package Structure Requirements

Ensure the built wheel includes:

- Main package: `src/fabric_mcp/` → installed as `fabric_mcp/`
- All `.py` files: `__init__.py`, `__about__.py`, `cli.py`, `core.py`, `api_client.py`, `utils.py`, `server_stdio.py`
- Entry point script accessible as `fabric-mcp` command

### Publishing Configuration

The project is configured with uv indexes for both TestPyPI and PyPI:

```toml
[tool.uv]
index = [
    { name = "testpypi", url = "https://test.pypi.org/simple/", publish-url = "https://test.pypi.org/legacy/", explicit = true },
    { name = "pypi", url = "https://pypi.org/simple/", publish-url = "https://upload.pypi.org/legacy/", explicit = true },
]
```

### Testing Recommendations

- Use isolated virtual environments for installation testing
- Test both pip and uv installation methods
- Verify the CLI works with `click` framework after installation
- Confirm package imports successfully in Python environments

### Project Structure Notes

The package follows standard Python src-layout:

- Source code in `src/fabric_mcp/`
- Tests in `tests/` (not included in distributions)
- Documentation in `docs/` (not included in distributions)
- Build artifacts generated in `dist/`

Reference `docs/architecture/project-structure.md` for complete project layout specifications.

## Story Progress Notes

### Agent Model Used: `GitHub Copilot (Fran - Scrum Master)`

### Completion Notes List

**✅ ALL TASKS COMPLETED (June 1, 2025):**

- **Task 1 COMPLETE**: `pyproject.toml` fully configured with proper hatchling setup, dynamic versioning, complete metadata, and correct publishing indexes
- **Task 2 COMPLETE**: Local build process verified working - `uv run hatch build` generates both sdist (1.6M) and wheel (12k) successfully
- **Task 3 COMPLETE**: Clean environment installation verified - `uv pip install fabric-mcp` installs 118 packages successfully, CLI functional
- **Task 4 COMPLETE**: TestPyPI publication working with automated CI/CD from develop branch - Installation verified: `uv pip install --index testpypi fabric-mcp` successful
- **Task 5 COMPLETE**: README.md already contains comprehensive PyPI installation instructions with both pip and uv commands
- **Task 6 COMPLETE**: Official PyPI publication working with automated CI/CD from main branch

**🎉 STORY FULLY ACCOMPLISHED:**

All Acceptance Criteria met:

1. ✅ `pyproject.toml` fully configured for hatchling build
2. ✅ `make build` successfully generates sdist and wheel
3. ✅ Wheel installable in clean virtual env via pip and uv
4. ✅ Installed `fabric-mcp` script executable and responds to `--version`/`--help`
5. ✅ Package successfully uploaded to TestPyPI and installable
6. ✅ Package successfully uploaded to official PyPI
7. ✅ `README.md` includes PyPI installation instructions

**📋 Final Build Status:**

- Version: 0.10.0 (from `__about__.py`)
- PyPI Package: Available at <https://pypi.org/project/fabric-mcp/>
- TestPyPI Package: Available at <https://test.pypi.org/project/fabric-mcp/>
- Installation verified: `uv pip install fabric-mcp` → 118 packages installed successfully
- TestPyPI installation also verified: `uv pip install --index testpypi fabric-mcp` → successful
- CLI functionality confirmed: `fabric-mcp --version` → "fabric-mcp, version 0.10.0"

### Change Log
