Changelog

[2.0.0] - 2026-11-02

A ground-up rewrite focused on correctness, security and being immediately useful to coding agents. Tool names now mirror the uv CLI. This is a breaking release: see the migration table below.

Highlights

Install with one command: uvx uv-mcp-server@latest. The distribution is now named uv-mcp-server (matching PyPI). The old uv-mcp console script remains as an alias.
Complete uv coverage: 51 tools across projects, Python versions, the pip interface, virtual environments, tools (uvx), packaging, cache, auth and uv itself. Every tool accepts extra_args, and uv_command runs any other uv subcommand. A coverage map plus a test against the installed uv’s --help guarantees every uv command is covered and flags new ones.
Every uv option: about 300 of uv’s ~1,060 command options are typed parameters (including a shared resolver object for resolution strategy, pre-releases, exclude-newer, indexes, platform, no-build, no-sources, offline). The rest go through extra_args, now validated against the installed uv’s own --help, so typos, missing values and invalid choices are rejected with suggestions. The new uv_help tool lists any command’s options, choices and env vars and says how to pass each one.
New tools: uv_help (option discovery), uv_check (type checking), uv_audit and uv_tool_audit (vulnerability audits), uv_workspace_list, uv_workspace_dir, uv_workspace_metadata, uv_pip_tree, uv_pip_check, uv_auth_login, uv_auth_logout, uv_project_info, uv_command.
Uniform results: every command returns success, exit_code (the real one), command, cwd, stdout, stderr, duration_seconds, timed_out, truncated and an actionable hint. Lists of packages, Python installations and tools are parsed into typed fields.
Diagnose and repair rewritten: uv_diagnose checks the interpreter, uv lock --check, .venv health, uv sync --check and uv pip check, with a suggested fix per finding. uv_repair plans and runs the fixes (with dry_run) and re-diagnoses.
Agent instructions: the server sends MCP instructions telling models which tool to use when.

Security

No shell anywhere; option-like values are rejected wherever a name, version or path is expected.
Tokens and passwords go to uv through environment variables or stdin, never argv, and are redacted from all output along with URL credentials, PyPI tokens and GitHub tokens. uv auth token is refused.
uv_publish is a dry run unless dry_run=false is passed.
Accurate MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
New --read-only mode, UV_MCP_ALLOWED_ROOTS path confinement, UV_MCP_TOOLSETS selection and --no-raw-command.
Commands time out (default 600 s, configurable) and the whole process group is killed; stdin is closed so uv can never hang on a prompt; mutating commands are serialised per project.

Fixed

uv pip tools acted on the server’s own virtual environment when it was launched with uv run or uvx (inherited VIRTUAL_ENV). It is now scrubbed.
Configurations using uv --directory /path/to/uv-mcp made every tool operate on the uv-mcp source tree. The documented commands no longer change directory, the workspace root honours UV_MCP_WORKSPACE_ROOT and CLAUDE_PROJECT_DIR, and the Gemini extension passes ${workspacePath}.
uv_tool_list counted executables as tools.
Exit codes were always reported as 0 or 1.
pytest was a runtime dependency, and fastmcp was unpinned (>=0.2.0); it is now >=4.1,<5.
The documentation’s installation instructions were wrong in several places (package name, Python version, codex trust, client config files). They have been rewritten and checked.

Migration

1.x tool	2.0 tool
`uv_check_installation`, `uv_install`, `uv_self_version`, `uv_cache_dir`, `uv_python_dir`	`uv_info`
`uv_diagnose_environment`	`uv_diagnose`
`uv_repair_environment`, `uv_self_heal_environment`	`uv_repair` (after `uv_diagnose`)
`uv_initialize_project`	`uv_init`
`uv_add_dependency` / `uv_remove_dependency`	`uv_add` / `uv_remove` (take a list of `packages`)
`uv_sync_environment`	`uv_sync`
`uv_lock_project`	`uv_lock`
`uv_export_requirements`	`uv_export`
`uv_run_script`	`uv_run`
`uv_run_ephemeral_tool`	`uv_tool_run`
`uv_list_dependencies`	`uv_pip_list` or `uv_tree`
`uv_analyze_dependency_tree`	`uv_tree`
`uv_show_package_info`	`uv_pip_show`
`uv_check_outdated_packages`	`uv_pip_list` with `outdated=true`, or `uv_tree` with `outdated=true`
`uv_get_workspace_manifest`	`uv_project_info`
`uv_create_venv`	`uv_venv`
`uv_project_version`	`uv_version` (`bump` is now a list)
`uv_format_code`	`uv_format`
`uv_build_project` / `uv_publish_project`	`uv_build` / `uv_publish`
`uv_pip_sync_requirements`	`uv_pip_sync`
`uv_list_python_versions`, `uv_find_python`	`uv_python_list`, `uv_python_find`
`uv_install_python_version`, `uv_upgrade_python_version`, `uv_uninstall_python_version`	`uv_python_install`, `uv_python_upgrade`, `uv_python_uninstall`
`uv_pin_python_version`	`uv_python_pin`
`uv_clear_cache`, `uv_prune_cache`	`uv_cache_clean`, `uv_cache_prune`

uv_pip_compile, uv_pip_install, uv_pip_uninstall, uv_pip_freeze, uv_tool_install, uv_tool_upgrade, uv_tool_list, uv_tool_uninstall, uv_cache_size and uv_self_update keep their names. Client configs should switch to uvx uv-mcp-server@latest; the example configs name the server uv, so Claude Code tool names become mcp__uv__uv_add and so on.

[1.0.0] - 2026-05-16

The Stop Shop Release

UV-MCP now covers the entire uv CLI surface area. Every command from uv --help is now available as a typed MCP tool.

Added (24 new tools)

Tool	uv Command	Purpose
`uv_create_venv`	`uv venv`	Create `.venv` with `--seed`, `--relocatable`, `--clear`, `--system-site-packages`
`uv_run_script`	`uv run`	Execute scripts/commands with optional `--with` temporary deps
`uv_project_version`	`uv version`	Read, set, or bump project version
`uv_format_code`	`uv format`	Format Python code via Ruff (`--check`, `--diff`)
`uv_pip_compile`	`uv pip compile`	Compile `requirements.in` → `requirements.txt`
`uv_pip_sync_requirements`	`uv pip sync`	Sync environment from `requirements.txt`
`uv_pip_freeze`	`uv pip freeze`	Freeze installed packages
`uv_pip_install`	`uv pip install`	Imperative package installation
`uv_pip_uninstall`	`uv pip uninstall`	Imperative package removal
`uv_tool_install`	`uv tool install`	Install global CLI tools
`uv_tool_upgrade`	`uv tool upgrade`	Upgrade installed tools
`uv_tool_list`	`uv tool list`	List installed tools
`uv_tool_uninstall`	`uv tool uninstall`	Remove installed tools
`uv_prune_cache`	`uv cache prune`	Prune unreachable cache objects
`uv_cache_dir`	`uv cache dir`	Show cache directory path
`uv_cache_size`	`uv cache size`	Show cache disk usage
`uv_find_python`	`uv python find`	Find Python installations
`uv_python_dir`	`uv python dir`	Show Python installation directory
`uv_upgrade_python_version`	`uv python upgrade`	Upgrade Python installations
`uv_uninstall_python_version`	`uv python uninstall`	Uninstall Python versions
`uv_publish_project`	`uv publish`	Publish distributions to PyPI
`uv_self_update`	`uv self update`	Update the uv binary
`uv_self_version`	`uv self version`	Display uv binary version

New Models

VenvResult, ScriptRunResult, VersionResult, FormatResult, PipCompileResult, PipSyncResult, PipFreezeResult, ToolListResult, CacheInfoResult, PublishResult, SelfUpdateResult

Total Tool Count: 45 MCP tools covering 100% of uv CLI functionality.

[0.8.0] - 2026-05-16

Added

Ephemeral Tool Runner (uvx proxy): uv_run_ephemeral_tool(package, command) executes ephemeral tools via uv tool run --from <pkg> with typed EphemeralToolResult.
Workspace Introspection Engine: uv_get_workspace_manifest() parses [tool.uv.workspace] members from pyproject.toml and returns a WorkspaceManifest with topological dependency graph.
Self-Healing Diagnostics Handler: uv_self_heal_environment() captures ModuleNotFoundError signatures via regex, triggers uv sync, and yields per-package uv add <pkg> recommendations in a SelfHealingDiagnostics payload.
ANSI-Free Subprocess Environment: All uv invocations now unconditionally inject UV_COLOR=never and TERM=dumb to guarantee clean, parseable streams.
Concurrency Lockfile Gate: asyncio.Lock() serializes mutating commands (add, remove, sync, lock) to prevent uv.lock deadlocks under concurrent MCP tool calls.
Absolute Path Resolution: Every project_path input is normalized with Path.resolve() before being passed to uv --directory.
New Pydantic Models: EphemeralToolResult, WorkspaceManifest, WorkspaceMember, SelfHealingDiagnostics, HealingAction.

Fixed

Docker Health Check updated to use uv_mcp.utils (previously referenced non-existent uv_mcp.uv_utils).
Docker image label bumped to 0.8.0.
Type safety: errors.py and server.py tightened for --strict compliance.

Changed

ProjectTools refactored from raw str returns to strictly typed Pydantic models (ProjectInitResult, SyncResult, ExportResult).

[0.7.2] - 2026-02-07

Added

Configuration Module: Centralized config.py for timeouts, limits, and retry policies.
Concurrency Limits: MAX_CONCURRENT_COMMANDS prevents resource exhaustion.
Core Utilities: Improved validate_project_path and check_uv_available (zombie process fix).
Output Limits: Truncation for large dependency trees and sync outputs to avoid MCP payload limits.
Docstrings: Added comprehensive docstrings with examples to all actions.
Tests: New test_error_paths.py covering edge cases and missing files.

Fixed

Resource Leaks: Fixed zombie processes in check_uv_available.
Timeouts: Fixed cascading timeouts in run_uv_command.
Bug Fixes:
- Fixed KeyError in show_package_info.
- Fixed list slicing in list_dependencies.
- Fixed logic in check_dependencies regarding return codes.
- Fixed validation in check_outdated_packages.
Safety: Added rigorous project path validation across all tools.

[0.6.4] - 2025-12-28

Major Release

This release adds powerful new build and cache management tools, comprehensive error handling, and extensive edge case testing.

New Features

Build & Distribution Tools

build_project: Build wheel and source distributions

result = await build_project(wheel=True, sdist=True)
# Creates dist/myapp-0.1.0.tar.gz and .whl files

lock_project: Update lockfile without syncing environment
```
await lock_project()  # Updates uv.lock only
```

clear_cache: Clear UV package cache

await clear_cache()  # Clear entire cache
await clear_cache(package="requests")  # Clear specific package

Enhanced Error Handling

7 Custom Exception Classes: Structured errors with error codes
- UVNotInstalledError - UV not found
- ProjectNotFoundError - Missing project directory
- PyProjectNotFoundError - No pyproject.toml
- DependencyConflictError - Version conflicts
- VirtualEnvMissingError - Missing .venv
- PackageNotFoundError - Package not in PyPI
- InvalidPythonVersionError - Python version issues

Smart Error Suggestions: Context-aware help messages

{
  "error": "uv is not installed",
  "error_code": "UV_NOT_FOUND",
  "suggestion": "Install uv using: curl -LsSf https://astral.sh/uv/install.sh | sh"
}

Error Suggestion Engine: Automatically parses stderr and provides actionable advice

Comprehensive Testing

56 New Edge Case Tests covering:
- Command execution boundaries (empty output, large data, special characters)
- Concurrent operations and race conditions
- Platform variations (Windows/Unix paths, Unicode)
- Error recovery scenarios
- Memory and performance (1000+ dependencies, 10MB+ output)
- Boundary conditions (name lengths, dependency sizes)

Bug Fixes

Fixed pytest async marker warnings in test suite
Fixed CacheOperationResult model default values
All 134 tests now pass cleanly (133 passed, 1 intentionally skipped)

Documentation

Added 6 comprehensive documentation files:

IMPROVEMENTS.md - Technical changelog
SUMMARY.md - Executive overview
QUICK_REFERENCE.md - Usage guide
TEST_REPORT.md - Test documentation
NAMING_CONVENTIONS.md - MCP naming compliance
FINAL_SUMMARY.md - Complete project report

Metrics

Total MCP Tools: 19 (↑ 3 new)
Total Tests: 134 (↑ 56 new)
Pass Rate: 99.3%
Test Execution: ~2.5 seconds
Code Coverage: 85%+ on critical modules
Breaking Changes: 0 (100% backward compatible)

[0.6.1] - 2025-12-16

Added

Dependency Inspection Suite: Deep dependency analysis tools
- list_dependencies: List all installed packages
- show_package_info: Detailed package metadata
- check_outdated_packages: Find packages with updates available
- analyze_dependency_tree: Visualize dependency relationships

Fixed

Environment Isolation: Fixed bug where uv pip inspected wrong environment
Test Isolation: Improved test suite isolation from host system

[0.5.3] - 2025-12-16

Fixed

GitHub Actions CI/CD workflow syntax error
Release asset upload process

[0.5.2] - 2025-12-16

Refactor

Modern Python: Updated to Python 3.10+ style with type hints
File Renaming: Standardized naming (uv_utils.py → utils.py)
Pydantic Integration: All inputs/outputs use Pydantic models
Error Handling: Custom exception hierarchy
Code Structure: Decomposed complex functions for readability

Changed

Default Python version: 3.12
Updated all imports for new file structure

[0.5.0] - 2025-12-15

Documentation

Comprehensive docs powered by Astro Starlight
Usage guide, installation guide, architecture overview
Tool reference documentation
Search functionality

Changed

Removed unicode emojis for better compatibility
Improved error handling in project tools
Fixed typos and improved documentation workflow

[0.4.0] - 2025-12-14

Added

remove_dependency tool
Auto-install Python in repair_environment
Comprehensive test coverage

Fixed

check_python_version detection
check_dependencies output parsing
Race conditions in test suite

[0.1.0] - 2025-12-13

Initial Release

Core tools: check, install, diagnose, repair, add
Gemini CLI extension support
Comprehensive test suite
Full documentation
Example configurations

Features

Automatic project root detection
Virtual environment management
Dependency conflict detection
Python version compatibility
Lockfile synchronization
JSON-formatted responses

Changelog

[2.0.0] - 2026-11-02

Highlights

Security

Fixed

Migration

[1.0.0] - 2026-05-16

The Stop Shop Release

Added (24 new tools)

New Models

Total Tool Count: 45 MCP tools covering 100% of uv CLI functionality.

[0.8.0] - 2026-05-16

Added

Fixed

Changed

[0.7.2] - 2026-02-07

Added

Fixed

[0.6.4] - 2025-12-28

Major Release

New Features

Build & Distribution Tools

Enhanced Error Handling

Comprehensive Testing

Bug Fixes

Documentation

Metrics

[0.6.1] - 2025-12-16

Added

Fixed

[0.5.3] - 2025-12-16

Fixed

[0.5.2] - 2025-12-16

Refactor

Changed

[0.5.0] - 2025-12-15

Documentation

Changed

[0.4.0] - 2025-12-14

Added

Fixed

[0.1.0] - 2025-12-13

Initial Release

Features

Version Comparison Links