# Portainer Core MCP Server Usage Guide

## Quick Start

### 1. Set Required Environment Variables

```bash
# Required configuration
export PORTAINER_URL=https://your-portainer-instance.com
export PORTAINER_API_KEY=your-api-key-here
```

### 2. Generate Portainer API Key

1. Log in to your Portainer instance
2. Navigate to **User Settings** > **API Tokens**
3. Click **Add API Token**
4. Give it a name (e.g., "MCP Server")
5. Copy the generated token

### 3. Start the Server

Choose your preferred method:

#### Option A: Using Python (Direct)
```bash
python run_server.py
```

#### Option B: Using uv (Recommended)
```bash
# Install uv if not installed
pip install uv

# Run with uv
uv run python run_server.py
```

#### Option C: Using uvx (Run without installing)
```bash
# Install uv if not installed
pip install uv

# Run directly without installation
uvx --from . portainer-core-mcp
```

#### Option D: Using npm/npx
```bash
# Install globally
npm install -g portainer-core-mcp

# Run with npx
npx portainer-core-mcp
```

#### Option E: Using the uv wrapper script
```bash
# Make executable (if not already)
chmod +x scripts/run-with-uv.py

# Run with uv wrapper
python scripts/run-with-uv.py
```

## Environment Configuration

### Using .env File

1. Copy the example file:
   ```bash
   cp .env.example .env
   ```

2. Edit the file:
   ```bash
   nano .env
   ```

3. Set your values:
   ```bash
   # Required
   PORTAINER_URL=https://your-portainer-instance.com
   PORTAINER_API_KEY=your-api-key-here
   
   # Optional (with defaults)
   HTTP_TIMEOUT=30
   MAX_RETRIES=3
   LOG_LEVEL=INFO
   DEBUG=false
   ```

### Using Environment Variables

```bash
# Export variables
export PORTAINER_URL=https://your-portainer-instance.com
export PORTAINER_API_KEY=your-api-key-here

# Start server
python run_server.py
```

## Installation Methods

### Development Installation

```bash
# Clone and install in development mode
git clone <repository-url>
cd portainer-mcp
pip install -e .

# Or with uv
uv pip install -e .
```

### Production Installation

```bash
# Install from PyPI (when published)
pip install portainer-core-mcp

# Or with uv
uv pip install portainer-core-mcp
```

### Run Without Installing (uvx)

```bash
# Run directly from source without installation
uvx --from . portainer-core-mcp

# Or from PyPI (when published)
uvx portainer-core-mcp
```

### NPM Installation

```bash
# Install globally
npm install -g portainer-core-mcp

# Or run without installing
npx portainer-core-mcp
```

## Available Commands

### MCP Tools

Once the server is running, the following tools are available:

- **`authenticate`** - Login with username/password
- **`generate_token`** - Generate API tokens
- **`get_current_user`** - Get current user info
- **`list_users`** - List all users
- **`create_user`** - Create new user
- **`update_user`** - Update user details
- **`delete_user`** - Delete user
- **`get_settings`** - Get Portainer settings
- **`update_settings`** - Update configuration
- **`health_check`** - Server health status

### MCP Resources

- **`portainer://users`** - User management data
- **`portainer://settings`** - Configuration settings
- **`portainer://health`** - Server health status

## Testing

### Run Tests

```bash
# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=src

# Run specific test file
python -m pytest tests/test_basic.py
```

### Test Configuration

```bash
# Test configuration loading
python -c "
import os
os.environ['PORTAINER_URL'] = 'https://test.com'
os.environ['PORTAINER_API_KEY'] = 'test-key'
from src.portainer_core.config import get_config
config = get_config()
print('✅ Configuration OK')
print(f'URL: {config.portainer_url}')
print(f'API Base: {config.api_base_url}')
"
```

## Troubleshooting

### Common Issues

1. **Missing API Key Error**
   ```
   ValueError: PORTAINER_API_KEY must be provided and cannot be empty
   ```
   **Solution**: Set the `PORTAINER_API_KEY` environment variable

2. **Invalid URL Error**
   ```
   ValueError: Invalid Portainer URL
   ```
   **Solution**: Ensure `PORTAINER_URL` includes the protocol (http/https)

3. **Python Not Found (npx)**
   ```
   Error: Python is not installed or not in PATH
   ```
   **Solution**: Install Python 3.8+ and ensure it's in your PATH

### Debug Mode

Enable debug logging for troubleshooting:

```bash
DEBUG=true LOG_LEVEL=DEBUG python run_server.py
```

### Health Check

Test if the server is working:

```bash
# Check server health
curl -X POST http://localhost:8000/health

# Or use the health_check tool through MCP
```

## Advanced Usage

### Custom Configuration

```python
from portainer_core.config import PortainerConfig

# Create custom config
config = PortainerConfig(
    portainer_url="https://custom.portainer.com",
    portainer_api_key="custom-key",
    http_timeout=60,
    log_level="DEBUG"
)
```

### Programmatic Usage

```python
from portainer_core.server import create_server
import asyncio

async def main():
    server = create_server()
    await server.run()

asyncio.run(main())
```

## Support

- **Documentation**: See README.md and code comments
- **Issues**: Report via GitHub Issues
- **Configuration**: Check .env.example for all options