Adolfo Delorenzo
be1e05c382
Major configuration and tooling updates: Authentication Changes: - Remove username/password authentication support - Require PORTAINER_URL and PORTAINER_API_KEY (both mandatory) - Simplify PortainerConfig class and validation logic - Update all documentation to reflect API key requirement Multiple Runtime Support: - Add uvx support for running without installation - Add uv support with dedicated wrapper script - Add npx support with Node.js wrapper script - Maintain backward compatibility with direct Python execution Documentation Updates: - Comprehensive README.md with all execution methods - Detailed USAGE.md with step-by-step instructions - Updated .env.example with clear required vs optional sections - Enhanced docstrings in server.py and config.py Tooling Support: - package.json for npm/npx support with cross-platform wrapper - scripts/run-with-uv.py for uv integration - bin/portainer-core-mcp Node.js wrapper for npx - test_uvx.py for uvx functionality testing Configuration Improvements: - Clear separation of required vs optional environment variables - Better validation error messages - Simplified authentication flow - Enhanced project metadata in pyproject.toml 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
217 lines
3.8 KiB
Markdown
217 lines
3.8 KiB
Markdown
# 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. |