portainer-mcp/CLAUDE.md

# Portainer Core MCP Server

This MCP server provides authentication and core management functionality for Portainer Business Edition.

## Server Purpose

**Primary Functions:**
- User authentication and session management
- API token generation and validation
- User profile and settings management
- Basic system information retrieval

**Part of Portainer MCP Suite:**
- `portainer-core` - Authentication and user management (this server)
- `portainer-teams` - Teams and RBAC management
- `portainer-environments` - Environment and endpoint management
- `portainer-docker` - Docker container operations
- `portainer-kubernetes` - Kubernetes cluster management
- `portainer-stacks` - Stack deployment and management
- `portainer-edge` - Edge computing and device management

## Authentication Flow

**Required for all operations:**
1. Initialize admin user (first time setup)
2. Authenticate to get JWT token
3. Use token in `X-API-Key` header for all requests

**Token Management:**
- Tokens expire based on server configuration
- Generate new tokens before expiration
- Store tokens securely in environment variables

## Base Configuration

**Environment Variables:**
```bash
PORTAINER_URL=https://your-portainer-instance.com
PORTAINER_API_KEY=your-api-token
```

**API Base URLs:**
- Business Edition: `{PORTAINER_URL}/api`
- All endpoints require authentication except initial admin setup

## Common Response Patterns

**Success Response Structure:**
```json
{
  "Id": 1,
  "Username": "admin",
  "Role": 1,
  "CreationDate": 1631852794
}
```

**Error Response Structure:**
```json
{
  "message": "Invalid credentials",
  "details": "Authentication failed"
}
```

## Core Endpoint Categories

**Authentication Endpoints:**
- `POST /api/users/admin/init` - Initialize admin user
- `POST /api/auth` - Authenticate user
- `POST /api/users/{id}/tokens` - Generate API token
- `DELETE /api/auth` - Logout/invalidate session

**User Management:**
- `GET /api/users` - List users
- `POST /api/users` - Create user
- `GET /api/users/{id}` - Get user details
- `PUT /api/users/{id}` - Update user
- `DELETE /api/users/{id}` - Delete user

**Settings:**
- `GET /api/settings` - Get Portainer settings
- `PUT /api/settings` - Update settings
- `GET /api/settings/public` - Get public settings

## Error Handling

**Common HTTP Status Codes:**
- `200` - Success
- `201` - Created
- `400` - Bad Request (invalid parameters)
- `401` - Unauthorized (invalid/missing token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (resource already exists)
- `500` - Internal Server Error

**Retry Logic:**
- Implement exponential backoff for 5xx errors
- Refresh token on 401 responses
- Maximum 3 retry attempts

## Security Considerations

**Best Practices:**
- Always use HTTPS in production
- Rotate API tokens regularly
- Implement proper token storage
- Log authentication events
- Rate limit API calls

**RBAC Integration:**
- Check user permissions before operations
- Respect environment-level access controls
- Honor team-based restrictions

## Development Workflow

**Testing Authentication:**
```bash
# Test admin initialization
curl -X POST "${PORTAINER_URL}/api/users/admin/init" \
  -H "Content-Type: application/json" \
  -d '{"Username":"admin","Password":"yourpassword"}'

# Test login
curl -X POST "${PORTAINER_URL}/api/auth" \
  -H "Content-Type: application/json" \
  -d '{"Username":"admin","Password":"yourpassword"}'
```

**Local Development:**
- Use Docker Compose with Portainer for testing
- Mock authentication for unit tests
- Validate all endpoints with proper error handling

## Integration Notes

**With Other MCP Servers:**
- Share authentication state across Portainer MCP servers
- Use consistent error handling patterns
- Maintain session context for user operations

**Rate Limits:**
- Portainer has built-in rate limiting
- Implement client-side throttling
- Monitor for 429 responses

## Troubleshooting

**Common Issues:**
- **401 Unauthorized**: Check token validity and format
- **403 Forbidden**: Verify user permissions and RBAC settings
- **Connection Refused**: Confirm Portainer URL and network access
- **SSL Errors**: Validate certificate configuration

**Debug Commands:**
```bash
# Verify Portainer connectivity
curl -I "${PORTAINER_URL}/api/status"

# Check current user context
curl -H "X-API-Key: ${PORTAINER_API_KEY}" \
  "${PORTAINER_URL}/api/users/me"
```

**Logging:**
- Enable verbose logging for authentication flows
- Log all API calls with timestamps
- Mask sensitive data in logs (passwords, tokens)

## Version Compatibility

**Supported Versions:**
- Portainer Business Edition 2.30.x+
- API Version: 2.31.3

**Breaking Changes:**
- Monitor Portainer release notes for API changes
- Test against new versions before upgrading
- Maintain backward compatibility where possible