# Portainer Core MCP Server

A Model Context Protocol (MCP) server that provides authentication and user management functionality for Portainer Business Edition.

## Features

- **Authentication**: JWT token-based authentication with Portainer API
- **User Management**: Complete CRUD operations for users
- **Settings Management**: Portainer instance configuration
- **Health Monitoring**: Server and service health checks
- **Fault Tolerance**: Circuit breaker pattern with automatic recovery
- **Structured Logging**: JSON-formatted logs with correlation IDs

## Requirements

- Python 3.8+
- Portainer Business Edition instance
- Valid Portainer API key

## Installation

### Using pip

```bash
pip install -e .
```

### Using uv (recommended)

```bash
uv pip install -e .
```

### Using uvx (run without installing)

```bash
# No installation needed - runs directly
uvx --from . portainer-core-mcp
```

### Using npm/npx

```bash
npm install -g portainer-core-mcp
```

## Configuration

### Environment Variables

Create a `.env` file or set environment variables:

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

# Optional
HTTP_TIMEOUT=30
MAX_RETRIES=3
LOG_LEVEL=INFO
DEBUG=false
```

### Generate API Key

1. Log in to your Portainer instance
2. Go to **User Settings** > **API Tokens**
3. Click **Add API Token**
4. Copy the generated token

## Usage

### Start the Server

#### Using Python

```bash
python run_server.py
```

#### Using uv

```bash
uv run python run_server.py
```

#### Using uvx

```bash
uvx --from . portainer-core-mcp
```

#### Using npm/npx

```bash
npx portainer-core-mcp
```

### Environment Setup

```bash
# Copy example environment file
cp .env.example .env

# Edit configuration
nano .env

# Start server (choose your preferred method)
python run_server.py
# OR
uvx --from . portainer-core-mcp
```

## Available Tools

The MCP server provides the following tools:

### Authentication
- `authenticate` - Login with username/password
- `generate_token` - Generate API tokens
- `get_current_user` - Get current user info

### User Management
- `list_users` - List all users
- `create_user` - Create new user
- `update_user` - Update user details
- `delete_user` - Delete user

### Settings
- `get_settings` - Get Portainer settings
- `update_settings` - Update configuration

### Health
- `health_check` - Server health status

## Available Resources

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

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/portainer-core-mcp.git
cd portainer-core-mcp

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

### Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src/portainer_core --cov-report=html

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration
```

### Code Quality

```bash
# Format code
black src tests
isort src tests

# Lint code
flake8 src tests

# Type checking
mypy src
```

## Architecture

The server follows a layered architecture:

- **MCP Server Layer**: Handles MCP protocol communication
- **Service Layer**: Abstracts Portainer API interactions
- **Models Layer**: Defines data structures and validation
- **Utils Layer**: Provides utility functions and helpers

## Security

- All API communications use HTTPS
- JWT tokens are handled securely and never logged
- Input validation on all parameters
- Rate limiting to prevent abuse
- Circuit breaker pattern for fault tolerance

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

## License

MIT License - see LICENSE file for details.