mcp-python/QUICKSTART.md

# 🚀 Quick Start Guide

## ⚡ First Time Setup with uv (Recommended)

```cmd
# 1. Install uv if not already installed
winget install astral-sh.uv
# or
pip install uv

# 2. Navigate to project directory
cd C:\Users\dimir\proects\mcp-python

# 3. Run directly with uvx - no setup needed!
uvx --from . mcp-python-manager
```

## 🐍 First Time Setup with pip (Traditional)

```cmd
# 1. Navigate to project directory
cd C:\Users\dimir\proects\mcp-python

# 2. Create virtual environment
python -m venv .venv

# 3. Activate virtual environment
.venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. (Optional) Install dev tools
pip install -e ".[dev]"
```

## Run the Server

### ⚡ With uvx (Recommended)

```cmd
# Basic run (stdio transport - for MCP clients)
uvx --from . mcp-python-manager

# With debug output
uvx --from . mcp-python-manager --debug

# With custom workspace
uvx --from . mcp-python-manager --workspace "C:\My\Projects"

# SSE transport (for HTTP clients)
uvx --from . mcp-python-manager --transport sse --port 8000
```

### 🐍 With Python (Traditional)

```cmd
# Basic run (stdio transport - for MCP clients)
python server.py

# With debug output
python server.py --debug

# With custom workspace
python server.py --workspace "C:\My\Projects"

# SSE transport (for HTTP clients)
python server.py --transport sse --port 8000
```

## Test the Server

```cmd
# Run built-in tests
python test_server.py

# Run with pytest (if installed)
pytest tests/ -v
```

## Connect from Claude Desktop

### ⚡ Using uvx (Recommended)

1. Edit your Claude Desktop config:
   - Location: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add this configuration:
```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"
      }
    }
  }
}
```

3. Restart Claude Desktop

### 🐍 Using Python (Traditional)

1. Edit your Claude Desktop config:
   - Location: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add this configuration:
```json
{
  "mcpServers": {
    "python-manager": {
      "command": "python",
      "args": ["C:/Users/dimir/proects/mcp-python/server.py"],
      "env": {
        "MCP_PYTHON_WORKSPACE": "C:/Users/dimir/projects",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

3. Restart Claude Desktop

## Example Prompts for Claude

Once connected, you can ask Claude to:

```
📁 Project Management:
- "Show me the structure of my project at C:\projects\myapp"
- "What Python files are in the src directory?"
- "Read the first 50 lines of main.py"

🔧 Code Execution:
- "Run the script at scripts/deploy.py with --dry-run argument"
- "Execute pytest on the tests folder with coverage"
- "Install the packages from requirements.txt"

🐛 Debugging:
- "What Python processes are currently running?"
- "Get debug info for main.py"
- "Show me the Python environment details"

✨ Code Quality:
- "Lint all Python files in src/ using flake8"
- "Format the code in utils.py using black"
- "Run pylint on the entire project"

📦 Dependencies:
- "List all installed packages in my venv"
- "Analyze dependencies in requirements.txt for issues"
- "Create a new virtual environment for my project"
```

## Common Commands Reference

### ⚡ With uvx

| Task | Command |
|------|---------|
| Start server | `uvx --from . mcp-python-manager` |
| Start with debug | `uvx --from . mcp-python-manager --debug` |
| Start with workspace | `uvx --from . mcp-python-manager --workspace "C:\Projects"` |
| Install uv | `winget install astral-sh.uv` |
| Update uv | `uv self update` |

### 🐍 With pip

| Task | Command |
|------|---------|
| Start server | `python server.py` |
| Test server | `python test_server.py` |
| Install deps | `pip install -r requirements.txt` |
| Install dev deps | `pip install -e ".[dev]"` |
| Run with debug | `python server.py --debug` |
| Check Python version | `python --version` |
| Activate venv | `.venv\Scripts\activate` |
| Deactivate venv | `deactivate` |

## Troubleshooting

### Server won't start
```cmd
# Check Python version
python --version  # Should be 3.10+

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Check for port conflicts (SSE mode)
netstat -ano | findstr :8000
```

### Tools not working
```cmd
# Enable debug logging
set MCP_PYTHON_DEBUG=true
python server.py

# Check allowed commands in config.py
# Add missing commands to config.allowed_commands
```

### Permission errors
```cmd
# Run terminal as Administrator
# Or adjust file/folder permissions
# Check antivirus software blocking execution
```

## Next Steps

1. ✅ Server installed and tested
2. ⬜ Configure Claude Desktop / Cursor / VS Code
3. ⬜ Customize `config.py` for your workflow
4. ⬜ Add custom tools in `tools.py`
5. ⬜ Set up CI/CD for your projects

## Need Help?

- Check `README.md` for full documentation
- Run `python test_server.py` for diagnostics
- Review logs in `server.log` (if configured)
- Check allowed commands in `config.py`

---
*Created for Windows 11 • Python 3.10+ • MCP Protocol*