mcp-python/UVX_USAGE.md

# ⚡ Using MCP Python Manager with uvx

This guide explains how to use the MCP Python Project Manager server with [`uv`](https://github.com/astral-sh/uv) and `uvx` for faster, simpler execution.

## Why uvx?

✅ **No virtual environment setup** - Run directly without `python -m venv`  
✅ **Instant startup** - uv's caching makes repeated runs lightning fast  
✅ **Dependency isolation** - Each run uses isolated dependencies  
✅ **Cross-platform** - Works the same on Windows, macOS, and Linux  
✅ **Automatic updates** - uvx fetches the latest version automatically  

## 🚀 Quick Start

### Install uv (one-time)

```cmd
# Via winget (Windows)
winget install astral-sh.uv

# Or via pip
pip install uv

# Verify installation
uv --version
uvx --version
```

### Run the MCP Server

```cmd
# Basic run (recommended for MCP clients)
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager

# With custom workspace
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --workspace "C:\MyProjects"

# With debug logging
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --debug

# Via SSE transport
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --transport sse --port 8000
```

### Run from Project Directory

If you're already in the project directory:

```cmd
cd C:\Users\dimir\proects\mcp-python
uvx --from . mcp-python-manager
```

## 🔌 Claude Desktop Configuration

Add to `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "python-manager": {
      "command": "uvx",
      "args": [
        "--from",
        "C:/Users/dimir/proects/mcp-python",
        "mcp-python-manager",
        "--transport",
        "stdio"
      ],
      "env": {
        "MCP_PYTHON_WORKSPACE": "C:/Users/dimir/projects",
        "UV_NO_CACHE": "0",
        "UV_LINK_MODE": "copy",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

### Environment Variables Explained

| Variable | Purpose | Recommended Value |
|----------|---------|------------------|
| `MCP_PYTHON_WORKSPACE` | Root directory for Python projects | `C:/Users/dimir/projects` |
| `UV_NO_CACHE` | Disable uv cache (0 = use cache) | `0` |
| `UV_LINK_MODE` | How uv links packages (`copy`, `symlink`, `hardlink`) | `copy` (safest on Windows) |
| `PYTHONUNBUFFERED` | Disable Python output buffering | `1` |

## 🔧 Cursor / VS Code Configuration

```json
{
  "mcp": {
    "servers": {
      "python-manager": {
        "type": "stdio",
        "command": "uvx",
        "args": [
          "--from",
          "C:/Users/dimir/proects/mcp-python",
          "mcp-python-manager",
          "--transport",
          "stdio"
        ],
        "env": {
          "MCP_PYTHON_WORKSPACE": "C:/Users/dimir/projects",
          "UV_LINK_MODE": "copy"
        }
      }
    }
  }
}
```

## 🛠️ Development with uvx

### Test Changes Locally

```cmd
# After editing server.py or tools.py, test immediately:
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --debug

# No need to reinstall - uvx picks up local changes!
```

### Install for Development

```cmd
# Install with dev dependencies
uv pip install -e ".[dev]" --system

# Run tests
uv run pytest tests/ -v

# Run linting
uv run ruff check .
uv run black --check .
```

### Build and Publish (Optional)

```cmd
# Build distribution
uv build

# Publish to PyPI (requires token)
uv publish --token $PYPI_TOKEN
```

## 🐛 Troubleshooting uvx

### "Command not found: uvx"

```cmd
# Install uv
winget install astral-sh.uv
# or
pip install uv

# Ensure it's in PATH
where uvx
```

### Permission errors on Windows

```cmd
# Use copy link mode (safer than symlinks on Windows)
set UV_LINK_MODE=copy
uvx --from . mcp-python-manager

# Or run as Administrator if needed
```

### Cache issues

```cmd
# Clear uv cache
uv cache clean

# Disable cache for one run
uvx --no-cache --from . mcp-python-manager
```

### Slow first run

The first `uvx` run downloads dependencies. Subsequent runs are instant due to caching.

```cmd
# Pre-warm cache (optional)
uvx --from . mcp-python-manager --help
```

### Debug uvx behavior

```cmd
# Enable uv debug output
set UV_VERBOSE=1
uvx --from . mcp-python-manager --debug

# See what uvx is doing
set RUST_LOG=uv=debug
uvx --from . mcp-python-manager
```

## 📊 Performance Comparison

| Method | First Run | Subsequent Runs | Setup Time |
|--------|-----------|----------------|------------|
| `python server.py` + venv | ~30s | ~1s | ~2 min (venv + pip) |
| `uvx --from .` | ~15s | **~0.5s** | **0s** |
| `pip install -e .` + run | ~45s | ~1s | ~3 min |

## 🔄 Updating the Server

With uvx, updates are automatic:

```cmd
# Just run again - uvx fetches latest code
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager

# Or force refresh
uv cache clean mcp-python-manager
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager
```

## 📁 Project Structure for uvx

```
mcp-python/
├── pyproject.toml    # [project.scripts] defines entry points
├── server.py         # Contains run_server() entry point
├── .uvrc             # uv-specific configuration (optional)
└── ...
```

### Key pyproject.toml Settings

```toml
[project.scripts]
# This creates the 'mcp-python-manager' command
mcp-python-manager = "server:run_server"

[tool.uv]
# uv-specific optimizations
dev-dependencies = ["dev"]
```

## 🎯 Best Practices

1. **Use `--from .` when in project directory** - Faster than full path
2. **Set `UV_LINK_MODE=copy` on Windows** - Avoids symlink permission issues
3. **Keep `MCP_PYTHON_WORKSPACE` in env** - Consistent project access
4. **Use `--debug` during development** - See detailed logs
5. **Cache warmup** - Run `--help` once to pre-download dependencies

## 🔄 Switching Back to Python

If you need to use traditional Python:

```cmd
# Traditional setup
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python server.py
```

Both methods work - choose what fits your workflow!

---

**uv Documentation**: https://docs.astral.sh/uv/  
**MCP Specification**: https://modelcontextprotocol.io