UV MCP
What I Do
Describe how to steer the uv-mcp server so natural language requests become precise uv workflows. This skill focuses on diagnosing environments, managing dependencies, controlling Python runtimes, and building artifacts with uv while keeping the workspace healthy.
Core Workflows
Environment Health & Setup
| Intent |
Tool |
What Happens |
| Diagnose failures or missing environments |
diagnose_environment |
Confirms pyproject.toml, virtualenv presence, lock sync status, and reports remediation steps. |
| Repair broken setups |
repair_environment |
Creates .venv, installs Python, and syncs dependencies automatically. |
| Verify/install uv itself |
check_uv_installation, install_uv |
Checks uv availability and returns platform-specific install steps when missing. |
> "Diagnose the environment"
# Use output to confirm pyproject + venv state
> "Repair the environment"
# Follow-up diagnostics ensure issues are resolved
Dependency Management
| Scenario |
Tool |
Notes |
| Add/remove libraries |
add_dependency, remove_dependency |
Supports --dev, optional dependency groups, and updates both config + env. |
Keep env aligned with uv.lock |
sync_environment |
Syncs or upgrades locked versions; run after lockfile updates. |
| Inspect or refresh packages |
check_outdated_packages, show_package_info |
Surfaces available upgrades and in-depth metadata for any package. |
Project Inspection
list_dependencies: Lists installed packages; request tree mode for transitive view.analyze_dependency_tree: Visualizes dependency graph depth to spot heavy branches before refactors.
Runtime Management
| Action |
Tool |
Guidance |
| List installed interpreters |
list_python_versions |
Shows versions uv already manages. |
| Install new interpreter |
install_python_version |
Downloads and activates the requested Python release. |
| Pin project runtime |
pin_python_version |
Updates .python-version to keep CI/CD aligned. |
Project Lifecycle
init_project: Scaffold a fresh uv-enabled project, ideal for greenfield work.export_requirements: Emit requirements.txt for platforms that expect pip-compatible manifests.
Build & Distribution (uv ≥ 0.6.4)
| Need |
Tool |
Tips |
| Create wheels/sdists |
build_project |
Choose wheel-only or sdist-only, customize output dir, capture artifact paths. |
| Refresh lockfile without installing |
lock_project |
Useful after manual pyproject.toml edits or before committing dependency changes. |
| Clear uv cache |
clear_cache |
Fixes checksum mismatches or frees disk space; target entire cache or a single package. |
Diagnostic Workflow Template
diagnose_environment- Review reported issues.
repair_environmentdiagnose_environment again.- If still broken:
clear_cache → lock_project → sync_environment.
Error Handling & Troubleshooting
- uv-mcp returns structured errors (
error, error_code, suggestion). Echo them in summaries so humans know the auto-remediation path.
- Common scenarios:
- UV not installed → run
install_uv.
- Missing packages →
sync_environment.
- Version conflicts →
clear_cache then lock_project and sync_environment.
- Corrupted artifacts →
clear_cache for that package and re-sync.
When to Use Me
- Onboarding or repairing uv-based projects without manual shell work.
- Automating dependency chores (install, remove, upgrade) through MCP.
- Managing Python runtimes inside CI/CD or multi-OS fleets.
- Preparing releases: lockfiles, builds,
requirements.txt exports.
Best Practices
- Diagnose before repair: Always capture the initial state so changes are auditable.
- Sync after mutations: Any
add_dependency / lock_project call should be followed by sync_environment to keep .venv aligned.
- Pin intentionally: Use
pin_python_version once a runtime is validated by CI.
- Cache hygiene: Run
clear_cache when checksum or corruption errors show up, then re-sync immediately.
- Capture artifacts: After
build_project, record the returned artifact list (wheel + sdist paths) in release notes.
Integration Patterns
- With
python-guidelines: Apply linting/testing standards after uv-mcp modifies dependencies.
- With
python-cli: Use init_project + dependency adds to scaffold CLIs rapidly.
- With
mcp-servers: Document uv-mcp availability in .vscode/mcp.json and keep tool lists lean.
Use this skill whenever the uv-mcp server is the fastest path to maintaining healthy uv environments without leaving the IDE context.
1---2name: uv-mcp3description: UV command automation and project lifecycle management patterns powered by the uv-mcp server4license: MIT5---67# UV MCP89## What I Do1011Describe how to steer the uv-mcp server so natural language requests become precise `uv` workflows. This skill focuses on diagnosing environments, managing dependencies, controlling Python runtimes, and building artifacts with uv while keeping the workspace healthy.1213## Core Workflows1415### Environment Health & Setup1617| Intent | Tool | What Happens |18| --- | --- | --- |19| Diagnose failures or missing environments | `diagnose_environment` | Confirms `pyproject.toml`, virtualenv presence, lock sync status, and reports remediation steps. |20| Repair broken setups | `repair_environment` | Creates `.venv`, installs Python, and syncs dependencies automatically. |21| Verify/install uv itself | `check_uv_installation`, `install_uv` | Checks uv availability and returns platform-specific install steps when missing. |2223```text24> "Diagnose the environment"25# Use output to confirm pyproject + venv state26> "Repair the environment"27# Follow-up diagnostics ensure issues are resolved28```2930### Dependency Management3132| Scenario | Tool | Notes |33| --- | --- | --- |34| Add/remove libraries | `add_dependency`, `remove_dependency` | Supports `--dev`, optional dependency groups, and updates both config + env. |35| Keep env aligned with `uv.lock` | `sync_environment` | Syncs or upgrades locked versions; run after lockfile updates. |36| Inspect or refresh packages | `check_outdated_packages`, `show_package_info` | Surfaces available upgrades and in-depth metadata for any package. |3738### Project Inspection3940- `list_dependencies`: Lists installed packages; request `tree` mode for transitive view.41- `analyze_dependency_tree`: Visualizes dependency graph depth to spot heavy branches before refactors.4243### Runtime Management4445| Action | Tool | Guidance |46| --- | --- | --- |47| List installed interpreters | `list_python_versions` | Shows versions uv already manages. |48| Install new interpreter | `install_python_version` | Downloads and activates the requested Python release. |49| Pin project runtime | `pin_python_version` | Updates `.python-version` to keep CI/CD aligned. |5051### Project Lifecycle5253- `init_project`: Scaffold a fresh uv-enabled project, ideal for greenfield work.54- `export_requirements`: Emit `requirements.txt` for platforms that expect pip-compatible manifests.5556### Build & Distribution (uv ≥ 0.6.4)5758| Need | Tool | Tips |59| --- | --- | --- |60| Create wheels/sdists | `build_project` | Choose wheel-only or sdist-only, customize output dir, capture artifact paths. |61| Refresh lockfile without installing | `lock_project` | Useful after manual `pyproject.toml` edits or before committing dependency changes. |62| Clear uv cache | `clear_cache` | Fixes checksum mismatches or frees disk space; target entire cache or a single package. |6364### Diagnostic Workflow Template65661. `diagnose_environment`672. Review reported issues.683. `repair_environment`694. `diagnose_environment` again.705. If still broken: `clear_cache` → `lock_project` → `sync_environment`.7172## Error Handling & Troubleshooting7374- uv-mcp returns structured errors (`error`, `error_code`, `suggestion`). Echo them in summaries so humans know the auto-remediation path.75- Common scenarios:76 - **UV not installed** → run `install_uv`.77 - **Missing packages** → `sync_environment`.78 - **Version conflicts** → `clear_cache` then `lock_project` and `sync_environment`.79 - **Corrupted artifacts** → `clear_cache` for that package and re-sync.8081## When to Use Me8283- Onboarding or repairing uv-based projects without manual shell work.84- Automating dependency chores (install, remove, upgrade) through MCP.85- Managing Python runtimes inside CI/CD or multi-OS fleets.86- Preparing releases: lockfiles, builds, `requirements.txt` exports.8788## Best Practices89901. **Diagnose before repair**: Always capture the initial state so changes are auditable.912. **Sync after mutations**: Any `add_dependency` / `lock_project` call should be followed by `sync_environment` to keep `.venv` aligned.923. **Pin intentionally**: Use `pin_python_version` once a runtime is validated by CI.934. **Cache hygiene**: Run `clear_cache` when checksum or corruption errors show up, then re-sync immediately.945. **Capture artifacts**: After `build_project`, record the returned artifact list (wheel + sdist paths) in release notes.9596## Integration Patterns9798- **With `python-guidelines`**: Apply linting/testing standards after uv-mcp modifies dependencies.99- **With `python-cli`**: Use `init_project` + dependency adds to scaffold CLIs rapidly.100- **With `mcp-servers`**: Document uv-mcp availability in `.vscode/mcp.json` and keep tool lists lean.101102Use this skill whenever the uv-mcp server is the fastest path to maintaining healthy uv environments without leaving the IDE context.
jr2804