134 lines
2.8 KiB
Markdown
134 lines
2.8 KiB
Markdown
# Portainer Core MCP Server
|
|
|
|
A Model Context Protocol (MCP) server for Portainer Business Edition authentication and user management.
|
|
|
|
## Features
|
|
|
|
- **Authentication & Session Management**: JWT token handling and user authentication
|
|
- **User Management**: Create, read, update, and delete users
|
|
- **Settings Management**: Retrieve and update Portainer settings
|
|
- **Secure Token Handling**: Automatic token refresh and secure storage
|
|
- **Error Handling**: Comprehensive error handling with retry logic
|
|
- **Circuit Breaker**: Fault tolerance for external API calls
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install portainer-core-mcp
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set the following environment variables:
|
|
|
|
```bash
|
|
PORTAINER_URL=https://your-portainer-instance.com
|
|
PORTAINER_API_KEY=your-api-token # Optional, for API key authentication
|
|
PORTAINER_USERNAME=admin # For username/password authentication
|
|
PORTAINER_PASSWORD=your-password # For username/password authentication
|
|
```
|
|
|
|
## Usage
|
|
|
|
### As MCP Server
|
|
|
|
```bash
|
|
portainer-core-mcp
|
|
```
|
|
|
|
### Programmatic Usage
|
|
|
|
```python
|
|
from portainer_core.server import PortainerCoreMCPServer
|
|
|
|
server = PortainerCoreMCPServer()
|
|
# Use server instance
|
|
```
|
|
|
|
## Available MCP Tools
|
|
|
|
- `authenticate` - Login with username/password
|
|
- `generate_token` - Generate API token
|
|
- `get_current_user` - Get authenticated 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 settings
|
|
|
|
## 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. |