system-setup

Original source / Raw SKILL.md

---
name: system-setup
description: Guides installation and verification of MCP runtime dependencies (Python, Node.js, uv) across Windows, Linux, and macOS. Use when users need to set up their environment for running MCP servers or troubleshoot missing dependencies.
license: Complete terms in LICENSE.txt
---

# System Setup for MCP Servers

Automated installation and verification of MCP runtime dependencies.

## When to Use

- User reports MCP server failures due to missing runtimes
- Setting up LibrAgent on a new machine
- Troubleshooting "command not found" or "python/node not installed" errors
- Verifying system readiness for MCP operations

## Quick Start

### Check Current Installation

Use platform detection and verification commands:

**Windows (PowerShell):**

```powershell
Get-Command python -ErrorAction SilentlyContinue
Get-Command node -ErrorAction SilentlyContinue
Get-Command uv -ErrorAction SilentlyContinue
```

**Linux/macOS (Bash):**

```bash
which python3 && python3 --version
which node && node --version
which uv && uv --version
```

### Installation Strategy

1. **Detect OS** - Use `run_in_terminal` to identify platform
2. **Check existing installations** - Verify versions and PATH configuration
3. **Install missing components** - Follow OS-specific installation guides
4. **Verify installation** - Confirm executables are accessible

## Installation Guides

### Python Installation

**Windows:**

- Use Microsoft Store: `winget install Python.Python.3.12`
- Or download from python.org (ensure "Add to PATH" is checked)
- Verify: `python --version`

**Linux:**

```bash
# Ubuntu/Debian
sudo apt update && sudo apt install python3 python3-pip python3-venv

# Fedora/RHEL
sudo dnf install python3 python3-pip

# Arch Linux
sudo pacman -S python python-pip
```

**macOS:**

```bash
# Using Homebrew (recommended)
brew install python3

# Or use system Python (macOS 12.3+)
python3 --version
```

### Node.js Installation

**Windows:**

```powershell
# Using winget
winget install OpenJS.NodeJS.LTS

# Or download from nodejs.org
```

**Linux:**

```bash
# Ubuntu/Debian (NodeSource)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Fedora/RHEL
sudo dnf install nodejs npm

# Arch Linux
sudo pacman -S nodejs npm
```

**macOS:**

```bash
# Using Homebrew
brew install node
```

### uv Installation

**All Platforms:**

```bash
# Using pip (after Python is installed)
pip install uv

# Or using pipx (recommended for isolated installation)
pip install pipx
pipx install uv
```

**Windows PowerShell (standalone):**

```powershell
irm https://astral.sh/uv/install.ps1 | iex
```

**Linux/macOS (standalone):**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## Verification

After installation, verify all components:

```bash
# Python
python --version  # or python3 --version
pip --version

# Node.js
node --version
npm --version

# uv
uv --version
```

Expected output format:

- Python: `Python 3.11+`
- Node: `v18.0.0+`
- uv: `0.1.0+`

## Common Issues

### PATH Not Updated

**Symptoms:** `command not found` after installation

**Solutions:**

- **Windows:** Restart terminal or reboot system
- **Linux/macOS:** Run `source ~/.bashrc` or `source ~/.zshrc`
- Manually add to PATH if needed (see [PATH_CONFIG.md](references/PATH_CONFIG.md))

### Python vs Python3

**Linux/macOS:** Use `python3` and `pip3` explicitly
**Windows:** Usually aliased to `python` and `pip`

### Permission Issues

**Linux/macOS:** Use `sudo` for system-wide installation or pipx/venv for user-local
**Windows:** Run terminal as Administrator if needed

### Multiple Python Versions

Use virtual environments to isolate dependencies:

```bash
python -m venv mcp_env
source mcp_env/bin/activate  # Linux/macOS
.\mcp_env\Scripts\activate   # Windows
```

## Advanced Topics

- **PATH Configuration:** [PATH_CONFIG.md](references/PATH_CONFIG.md)
- **Virtual Environments:** [VENV_GUIDE.md](references/VENV_GUIDE.md)
- **Offline Installation:** [OFFLINE_INSTALL.md](references/OFFLINE_INSTALL.md)

## Scripts

Automated installation scripts are available in `scripts/`:

- `install_python.ps1` / `install_python.sh` - Python installation
- `install_node.ps1` / `install_node.sh` - Node.js installation
- `install_uv.ps1` / `install_uv.sh` - uv installation
- `verify_setup.ps1` / `verify_setup.sh` - Comprehensive verification

Execute scripts based on user's platform and permission level.

## Integration with LibrAgent

LibrAgent MCP servers require:

- **Python 3.11+** for Python-based MCP servers
- **Node.js 18+** for TypeScript-based MCP servers
- **uv** for fast Python dependency management

Check `src-tauri/src/mcp/server_manager.rs` for runtime detection logic.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/PATH_CONFIG.md

```markdown
# PATH Configuration Guide

## Understanding PATH

The PATH environment variable tells the operating system where to find executable files. When you type a command like `python` or `node`, the system searches directories listed in PATH.

## Viewing Current PATH

**Windows PowerShell:**

```powershell
$env:PATH -split ';'
```

**Linux/macOS:**

```bash
echo $PATH | tr ':' '\n'
```

## Adding to PATH

### Windows

**Method 1: System Settings (Permanent)**

1. Search "Environment Variables" in Start menu
2. Click "Environment Variables"
3. Under "User variables" or "System variables", select "Path"
4. Click "Edit" → "New"
5. Add directory path (e.g., `C:\Python311\Scripts`)
6. Click OK and restart terminal

**Method 2: PowerShell (Current Session)**

```powershell
$env:PATH += ";C:\path\to\directory"
```

**Method 3: PowerShell Profile (Permanent)**

```powershell
# Edit profile
notepad $PROFILE

# Add this line:
$env:PATH += ";C:\path\to\directory"
```

### Linux/macOS

**Method 1: Shell RC File (Permanent)**

For Bash (`~/.bashrc` or `~/.bash_profile`):

```bash
export PATH="$HOME/.local/bin:$PATH"
```

For Zsh (`~/.zshrc`):

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Apply changes:

```bash
source ~/.bashrc  # or ~/.zshrc
```

**Method 2: Current Session Only**

```bash
export PATH="$HOME/.local/bin:$PATH"
```

## Common PATH Locations

### Python

**Windows:**

- `C:\Python311\`
- `C:\Python311\Scripts\`
- `%APPDATA%\Python\Python311\Scripts\`

**Linux:**

- `/usr/bin/`
- `/usr/local/bin/`
- `~/.local/bin/`

**macOS:**

- `/usr/local/bin/`
- `/opt/homebrew/bin/` (Apple Silicon)
- `~/Library/Python/3.11/bin/`

### Node.js

**Windows:**

- `C:\Program Files\nodejs\`
- `%APPDATA%\npm\`

**Linux:**

- `/usr/bin/`
- `/usr/local/bin/`
- `~/.npm-global/bin/`

**macOS:**

- `/usr/local/bin/`
- `/opt/homebrew/bin/`

### uv

**Windows:**

- `%USERPROFILE%\.cargo\bin\`

**Linux/macOS:**

- `~/.cargo/bin/`

## Troubleshooting

### PATH Not Updating

**Windows:**

- Close all terminal windows and reopen
- Log out and log back in
- Restart computer (system-wide changes)

**Linux/macOS:**

- Run `source ~/.bashrc` or `source ~/.zshrc`
- Close terminal and open new one
- Check shell type: `echo $SHELL`

### Duplicate Entries

**Windows:**

```powershell
# Remove duplicates
$paths = $env:PATH -split ';' | Select-Object -Unique
$env:PATH = $paths -join ';'
```

**Linux/macOS:**

```bash
# View duplicates
echo $PATH | tr ':' '\n' | sort | uniq -d
```

### Permission Denied

**Linux/macOS:**

- Ensure directories have execute permissions: `chmod +x /path/to/executable`
- Check file ownership: `ls -la /path/to/executable`

### Wrong Version Executed

Multiple versions installed? Check which one is found first:

```bash
# Windows
Get-Command python -All

# Linux/macOS
which -a python3
```

Order matters: The first match in PATH is executed.

## Security Considerations

- **Avoid adding current directory (`.`) to PATH** - Security risk
- **Use absolute paths** - Avoid relative paths in PATH
- **Limit write permissions** - Ensure PATH directories aren't world-writable
- **Order matters** - Place trusted directories first

## PATH Priority

Directories are searched in order:

1. **Windows:** Left to right (separated by `;`)
2. **Linux/macOS:** Left to right (separated by `:`)

To prioritize a specific installation, place it earlier in PATH.

```

### references/VENV_GUIDE.md

```markdown
# Virtual Environment Guide

## Why Virtual Environments?

Virtual environments isolate Python dependencies per project, preventing:

- Version conflicts between projects
- Global package pollution
- Permission issues with system Python
- "It works on my machine" problems

## Creating Virtual Environments

### Python venv (Built-in)

**All Platforms:**

```bash
# Create venv
python -m venv myenv

# Activate
source myenv/bin/activate  # Linux/macOS
.\myenv\Scripts\activate   # Windows PowerShell
myenv\Scripts\activate.bat # Windows CMD

# Deactivate
deactivate
```

### uv (Recommended for Speed)

**All Platforms:**

```bash
# Create venv with uv (much faster)
uv venv

# Activate
source .venv/bin/activate  # Linux/macOS
.\.venv\Scripts\activate   # Windows

# Install packages
uv pip install package-name

# Generate requirements
uv pip freeze > requirements.txt
```

## Virtual Environment Locations

**Standard locations:**

- Project root: `./venv` or `./.venv`
- Centralized: `~/.virtualenvs/project-name/`

**LibrAgent MCP servers:**

- Each MCP server may have its own venv
- Check `mcp-server-directory/.venv/`

## Managing Dependencies

### Installing Packages

```bash
# Activate venv first!
source .venv/bin/activate

# Using pip
pip install package-name

# Using uv (faster)
uv pip install package-name

# From requirements.txt
pip install -r requirements.txt
uv pip install -r requirements.txt
```

### Exporting Dependencies

```bash
# Generate requirements.txt
pip freeze > requirements.txt
uv pip freeze > requirements.txt

# With version hashes (more secure)
pip freeze --all > requirements.txt
```

## IDE Integration

### VS Code

Add to `.vscode/settings.json`:

```json
{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true
}
```

### PyCharm

1. File → Settings → Project → Python Interpreter
2. Click gear icon → Add
3. Select "Virtualenv Environment" → "Existing environment"
4. Choose `.venv/bin/python`

## Common Issues

### Activation Not Working

**Symptoms:** `(venv)` prefix doesn't appear

**Solutions:**

- Ensure correct activation script path
- Check script execution policy (Windows): `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`
- Try absolute path: `C:\path\to\venv\Scripts\activate`

### Wrong Python Version

**Symptoms:** Venv uses different Python than expected

**Solutions:**

```bash
# Specify Python version explicitly
python3.11 -m venv myenv
/usr/bin/python3.11 -m venv myenv
C:\Python311\python.exe -m venv myenv
```

### Packages Not Found After Activation

**Symptoms:** `ModuleNotFoundError` despite installing package

**Solutions:**

- Verify venv is activated: `which python` or `Get-Command python`
- Check pip installation: `pip list`
- Reinstall package in activated venv

### Venv Too Large

**Symptoms:** Venv directory consumes excessive disk space

**Solutions:**

- Don't commit venv to git (add to `.gitignore`)
- Use `--without-pip` and install pip later if needed
- Clean up unused packages: `pip uninstall package-name`

## Best Practices

### Project Structure

```
project/
├── .venv/           # Virtual environment (gitignored)
├── src/             # Source code
├── requirements.txt # Dependencies
└── README.md
```

### Gitignore

Add to `.gitignore`:

```
# Virtual environments
venv/
.venv/
env/
ENV/
```

### Requirements.txt Management

**Split requirements:**

- `requirements.txt` - Production dependencies
- `requirements-dev.txt` - Development tools (pytest, black, etc.)

Install both:

```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

### Reproducible Environments

```bash
# Pin versions
pip freeze > requirements.txt

# Or use pip-tools for deterministic builds
pip install pip-tools
pip-compile requirements.in
pip-sync requirements.txt
```

## MCP Server Contexts

LibrAgent MCP servers may use venvs:

**Check MCP server venv:**

```bash
# Look for .venv or venv directory
ls -la /path/to/mcp-server/

# Check which Python is used
cat /path/to/mcp-server/start.sh
```

**Activate MCP server venv manually:**

```bash
cd /path/to/mcp-server
source .venv/bin/activate
python server.py
```

## uv Virtual Environments

uv provides faster venv operations:

```bash
# Create venv
uv venv

# Install packages (parallel, cached)
uv pip install -r requirements.txt

# Sync exact dependencies
uv pip sync requirements.txt

# Compile requirements with hashes
uv pip compile requirements.in -o requirements.txt
```

**Benefits:**

- 10-100x faster than pip
- Parallel downloads
- Disk cache for offline installs
- Drop-in pip replacement

```

### references/OFFLINE_INSTALL.md

```markdown
# Offline Installation Guide

## Overview

Install Python, Node.js, and uv without internet connectivity.

## Preparation (Online Machine)

### Download Python

**Windows:**

1. Visit python.org/downloads
2. Download "Windows installer (64-bit)"
3. Save file: `python-3.11.x-amd64.exe`

**Linux:**

```bash
# Download source tarball
wget https://www.python.org/ftp/python/3.11.x/Python-3.11.x.tgz

# Or use your distro's package cache
apt-get download python3 python3-pip
dnf download python3 python3-pip
```

**macOS:**

```bash
# Download official installer
curl -O https://www.python.org/ftp/python/3.11.x/python-3.11.x-macos11.pkg
```

### Download Node.js

**Windows:**

1. Visit nodejs.org/download
2. Download "Windows Installer (.msi)" - 64-bit
3. Save file: `node-v20.x.x-x64.msi`

**Linux:**

```bash
# Download binary tarball
wget https://nodejs.org/dist/v20.x.x/node-v20.x.x-linux-x64.tar.xz
```

**macOS:**

```bash
# Download PKG installer
curl -O https://nodejs.org/dist/v20.x.x/node-v20.x.x.pkg
```

### Download uv

**All Platforms:**

```bash
# Download prebuilt binary
# Windows
curl -LO https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-pc-windows-msvc.zip

# Linux
curl -LO https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-gnu.tar.gz

# macOS (Intel)
curl -LO https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-apple-darwin.tar.gz

# macOS (Apple Silicon)
curl -LO https://github.com/astral-sh/uv/releases/latest/download/uv-aarch64-apple-darwin.tar.gz
```

### Download Python Packages

```bash
# Create requirements.txt with needed packages
cat > requirements.txt <<EOF
fastmcp
anthropic
openai
requests
EOF

# Download packages and dependencies
pip download -r requirements.txt -d ./packages/
```

## Installation (Offline Machine)

### Python Installation

**Windows:**

```powershell
# Run installer
.\python-3.11.x-amd64.exe /quiet InstallAllUsers=1 PrependPath=1
```

**Linux (from binary):**

```bash
# Extract and install
tar xzf Python-3.11.x.tgz
cd Python-3.11.x
./configure --prefix=/usr/local
make
sudo make install
```

**Linux (from .deb packages):**

```bash
sudo dpkg -i python3_*.deb python3-pip_*.deb
sudo apt-get install -f  # Fix dependencies if needed
```

**macOS:**

```bash
# Install PKG
sudo installer -pkg python-3.11.x-macos11.pkg -target /
```

### Node.js Installation

**Windows:**

```powershell
# Run MSI installer
msiexec /i node-v20.x.x-x64.msi /quiet
```

**Linux:**

```bash
# Extract binary
tar xJf node-v20.x.x-linux-x64.tar.xz
sudo mv node-v20.x.x-linux-x64 /opt/nodejs

# Add to PATH
echo 'export PATH="/opt/nodejs/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**macOS:**

```bash
# Install PKG
sudo installer -pkg node-v20.x.x.pkg -target /
```

### uv Installation

**Windows:**

```powershell
# Extract and move to PATH
Expand-Archive uv-x86_64-pc-windows-msvc.zip
Move-Item uv-x86_64-pc-windows-msvc\uv.exe $env:USERPROFILE\.cargo\bin\
```

**Linux/macOS:**

```bash
# Extract and install
tar xzf uv-*.tar.gz
sudo mv uv /usr/local/bin/
chmod +x /usr/local/bin/uv
```

### Python Packages Installation

```bash
# Install from downloaded packages
pip install --no-index --find-links=./packages/ -r requirements.txt
```

## Verification

```bash
# Check installations
python --version
pip --version
node --version
npm --version
uv --version

# Test package import
python -c "import fastmcp; print('fastmcp OK')"
```

## Creating Offline Package Cache

### For Python Projects

```bash
# Create wheel cache
pip wheel -r requirements.txt -w ./wheelhouse/

# Install from wheelhouse
pip install --no-index --find-links=./wheelhouse/ -r requirements.txt
```

### For Node.js Projects

```bash
# Create offline npm cache
npm install --cache ./npm-cache/ --prefer-offline

# Or use npm pack
npm pack package-name
```

### For uv

```bash
# uv caches packages automatically in ~/.cache/uv/
# Copy cache to offline machine:
tar czf uv-cache.tar.gz ~/.cache/uv/

# On offline machine:
tar xzf uv-cache.tar.gz -C ~/
```

## Portable Installation

### Python Portable (Windows)

1. Download "embeddable package" from python.org
2. Extract to `C:\Python311Portable\`
3. Add `python311._pth` file:
   ```
   python311.zip
   .
   ./Lib/site-packages
   ```
4. Install pip manually:
   ```powershell
   python get-pip.py --no-index
   ```

### Node.js Portable (Windows)

1. Download ZIP archive from nodejs.org
2. Extract to desired location
3. Add to PATH or use full path: `C:\node\node.exe`

## Corporate Environment

### Using Internal Mirrors

```bash
# Python (pip)
pip install --index-url http://internal-pypi/simple/ package-name

# Node.js (npm)
npm config set registry http://internal-npm/

# uv
export UV_INDEX_URL=http://internal-pypi/simple/
```

### Proxy Configuration

```bash
# System-wide proxy
export HTTP_PROXY=http://proxy:8080
export HTTPS_PROXY=http://proxy:8080

# pip proxy
pip install --proxy http://proxy:8080 package-name

# npm proxy
npm config set proxy http://proxy:8080
npm config set https-proxy http://proxy:8080
```

## Troubleshooting

### Missing System Libraries (Linux)

Python compilation may need:

```bash
# Debian/Ubuntu
sudo apt-get install build-essential libssl-dev libffi-dev python3-dev

# Fedora/RHEL
sudo dnf groupinstall "Development Tools"
sudo dnf install openssl-devel libffi-devel python3-devel
```

### Certificate Issues

```bash
# Disable SSL verification (testing only)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org package-name

# Or add custom CA certificate
export REQUESTS_CA_BUNDLE=/path/to/ca-bundle.crt
```

### Permission Errors

```bash
# Install to user directory (no sudo needed)
pip install --user package-name

# Or use virtual environment
python -m venv venv
source venv/bin/activate
pip install package-name
```

```