Dependency Audit: Critical UV Migration and Modernization Required

[Coldaine]

Dependency Audit Report

Executive Summary

This repository currently uses pip/venv for dependency management with dual configuration files (requirements.txt, requirements-dev.txt, and pyproject.toml). According to project standards defined in CLAUDE.md, UV should be the exclusive package manager (ALWAYS use UV - never pip, venv, or requirements.txt).

Status: ❌ NOT UV COMPLIANT

---

Critical Findings

1. ❌ Non-UV Package Management

Severity: HIGH
Impact: Violates project standards, slower installs, inconsistent environments

Current State:

• Using pip for dependency installation
• Using venv for virtual environment creation
• Dependency definitions in requirements.txt and requirements-dev.txt
• pyproject.toml exists but not configured for UV

Evidence:

• run-server.sh:969-976: Uses pip install -r requirements.txt
• code_quality_checks.sh:45: Uses pip install -r requirements-dev.txt
• run-server.sh:565-657: UV is optional fallback, not primary

Required Actions:

1. Migrate all dependency management to UV exclusively
2. Convert requirements.txt → pyproject.toml dependencies
3. Convert requirements-dev.txt → pyproject.toml dev dependencies
4. Update all scripts to use uv sync instead of pip install
5. Remove legacy requirements*.txt files after migration

---

2. ⚠️ Missing Dependency Lock File

Severity: MEDIUM
Impact: Unreproducible builds, potential version conflicts

Current State:

• No uv.lock file present
• Dependencies use minimum version constraints (>=)
• No guarantee of reproducible installations across environments

Dependencies with minimum constraints:

mcp>=1.0.0
google-genai>=1.19.0  
openai>=1.55.2
pydantic>=2.0.0
python-dotenv>=1.0.0

Required Actions:

1. Initialize UV: uv init
2. Generate lock file: uv lock
3. Commit uv.lock to version control
4. Update CI/CD to use uv sync --frozen for reproducible builds

---

3. ⚠️ Dual Configuration Maintenance Burden

Severity: MEDIUM
Impact: Configuration drift, maintenance overhead, potential inconsistencies

Current State:

• Dependencies defined in 3 places:
  1. requirements.txt (6 runtime deps)
  2. requirements-dev.txt (8 dev deps)
  3. pyproject.toml (5 deps, missing dev deps)

Inconsistencies Found:

• pyproject.toml missing importlib-resources (present in requirements.txt)
• Dev dependencies only in requirements-dev.txt, not in pyproject.toml

Required Actions:

1. Consolidate all dependencies into pyproject.toml
2. Use [project.dependencies] for runtime deps
3. Use [project.optional-dependencies] for dev deps
4. Remove requirements*.txt files
5. Update documentation to reference pyproject.toml only

---

4. ⚠️ Build System Configuration Issues

Severity: MEDIUM
Impact: Potential build failures, outdated build tools

Current State:

[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
build-backend = "setuptools.build_meta"

Issues:

• Using setuptools>=45 (released 2019) - current is 75+
• wheel should be implicit, not explicit
• setuptools_scm configured but no version source defined in [tool.setuptools_scm]

Required Actions:

1. Update to modern build system:

   [build-system]
   requires = ["setuptools>=75.0.0", "setuptools_scm>=8.0.0"]
   build-backend = "setuptools.build_meta"

2. Configure setuptools_scm properly or remove if unused
3. Consider migrating to hatchling for better UV integration

---

5. ✅ Positive Findings

What's Working Well:

• ✅ Pinned minimum versions for critical dependencies (openai>=1.55.2 for httpx compatibility)
• ✅ pyproject.toml structure is modern and well-organized
• ✅ Using Python 3.9+ (good minimum version)
• ✅ Dev tools properly separated (black, ruff, isort, pytest)
• ✅ run-server.sh has UV detection logic (lines 569-627)

---

Dependency Staleness Analysis

Runtime Dependencies

Package	Current Min	Latest Stable	Status
mcp	>=1.0.0	~1.x	✅ OK (using latest)
google-genai	>=1.19.0	2.0.0+	⚠️ May need update
openai	>=1.55.2	1.60+	⚠️ Consider updating
pydantic	>=2.0.0	2.10+	✅ OK (v2 modern)
python-dotenv	>=1.0.0	1.0.1	✅ OK

Dev Dependencies

Package	Current Min	Latest Stable	Status
pytest	>=7.4.0	8.3.4	⚠️ Update recommended
pytest-asyncio	>=0.21.0	0.24.0	⚠️ Update recommended
black	>=23.0.0	24.10.0	⚠️ Update recommended
ruff	>=0.1.0	0.8+	⚠️ Update recommended
isort	>=5.12.0	5.13.2	✅ OK

---

UV Migration Roadmap

Phase 1: Immediate (Week 1)

1. ✅ Install UV globally: curl -LsSf https://astral.sh/uv/install.sh | sh
2. ✅ Initialize UV in project: uv init
3. ✅ Migrate dependencies to pyproject.toml:

   uv add mcp google-genai "openai>=1.55.2" "pydantic>=2.0.0" python-dotenv
   uv add --dev pytest pytest-asyncio pytest-mock black ruff isort python-semantic-release build

4. ✅ Generate lock file: uv lock
5. ✅ Test installation: uv sync

Phase 2: Script Migration (Week 1-2)

1. Update run-server.sh:
   • Replace python -m venv → uv venv
   • Replace pip install -r requirements.txt → uv sync
   • Remove UV as optional, make it required
2. Update code_quality_checks.sh:
   • Replace pip install -r requirements-dev.txt → uv sync --all-extras
3. Update run_integration_tests.sh:
   • Use uv run pytest instead of direct pytest calls

Phase 3: Cleanup (Week 2)

1. Remove requirements.txt
2. Remove requirements-dev.txt
3. Update CLAUDE.md documentation to reflect UV-only workflow
4. Update CI/CD workflows to use UV
5. Add uv.lock to version control

Phase 4: Validation (Week 2-3)

1. Test clean installs on multiple platforms
2. Verify CI/CD pipelines work with UV
3. Update contributor documentation
4. Close this issue with verification report

---

Recommended pyproject.toml Structure

[project]
name = "zen-mcp-server"
version = "1.0.0"
description = "AI-powered MCP server with multiple model providers"
requires-python = ">=3.9"
dependencies = [
    "mcp>=1.0.0",
    "google-genai>=1.19.0",
    "openai>=1.55.2",
    "pydantic>=2.0.0",
    "python-dotenv>=1.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-asyncio>=0.21.0",
    "pytest-mock>=3.11.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "isort>=5.12.0",
]
release = [
    "python-semantic-release>=10.3.0",
    "build>=1.0.0",
]

[build-system]
requires = ["setuptools>=75.0.0", "setuptools_scm>=8.0.0"]
build-backend = "setuptools.build_meta"

# Keep existing tool configurations (black, isort, ruff, etc.)

---

Security Considerations

Dependency Scanning

Recommendation: Add uv pip audit to CI/CD pipeline to check for known vulnerabilities.

Current Risk: Without lock file, could accidentally install vulnerable versions.

Example CI/CD Integration

- name: Security Audit
  run: |
    uv pip audit
    uv sync --frozen  # Ensures exact versions from lock file

---

Migration Commands Quick Reference

# 1. Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Initialize and migrate
uv init
uv add mcp google-genai "openai>=1.55.2" pydantic python-dotenv
uv add --dev pytest pytest-asyncio pytest-mock black ruff isort python-semantic-release build

# 3. Generate lock file
uv lock

# 4. Install dependencies
uv sync

# 5. Run commands with UV
uv run python server.py
uv run pytest
uv run black .

# 6. Clean up legacy files
rm requirements.txt requirements-dev.txt
git add pyproject.toml uv.lock
git commit -m "Migrate to UV for dependency management"

---

References

• Project Standards: CLAUDE.md ("ALWAYS use UV - never pip, venv, or requirements.txt")
• UV Documentation: https://docs.astral.sh/uv/
• UV Migration Guide: https://docs.astral.sh/uv/guides/migration/
• Current Requirements: requirements.txt, requirements-dev.txt
• Script Analysis: run-server.sh, code_quality_checks.sh

---

Action Items

• Install UV globally on development machines
• Run uv init to initialize UV in project
• Migrate dependencies from requirements.txt → pyproject.toml
• Generate and commit uv.lock file
• Update run-server.sh to use UV exclusively
• Update code_quality_checks.sh to use UV
• Update run_integration_tests.sh to use UV
• Remove requirements.txt and requirements-dev.txt
• Update documentation to reflect UV-only workflow
• Test clean installation on fresh environment
• Update CI/CD pipelines to use UV
• Add uv pip audit to security checks

---

Priority: HIGH
Effort: Medium (2-3 weeks for full migration)
Risk: Low (UV is backward compatible, can run in parallel initially)

Next Steps: Assign to development team for sprint planning and begin Phase 1 migration.