Unimus MCP Server

Unimus MCP Server

A read-only Model Context Protocol server for Unimus network configuration management system. This server enables you to interact with your Unimus data directly via LLMs that support MCP.

Version

Current Version: 0.4.0 (Backup Content Search & Advanced Analysis)

See ROADMAP.md for planned features and future versions.

Features

Tools Available (v0.4.0)

New in v0.4.0 🚀

• Backup Content Search: Search through backup configurations with regex patterns using unimus_search_backup_content
• Advanced Pattern Matching: Full regex support with case-insensitive, multiline search capabilities
• Context-Aware Results: Get configurable lines of context around matches for better understanding
• Smart Filtering: Combine device filters, time ranges, and search limits for optimal performance
• Detailed Match Information: Line numbers, regex capture groups, and context highlighting

Previous Updates

• v0.3.0: Backup Diff Analysis, Change Tracking, Schedule Management
• Backup Diff Analysis: Compare any two backup configurations with unimus_get_backup_diff
• Change Tracking: Find devices with backup changes in time ranges with unimus_get_devices_with_changed_backups
• Schedule Management: Access backup schedules with unimus_get_schedules and unimus_get_schedule_by_id
• Enhanced Analytics: Build powerful network change analysis workflows

Previous Updates

• v0.2.5: Automatic Base64 Decoding, Performance Optimization, Smart Content Handling
• v0.2.0: Enhanced Device Search and Bulk Backup Operations
• v0.1.0: Core device and backup functionality

Key Improvements over Basic API Access

• Transparent Pagination: Automatically handles paginated responses
• Enhanced Error Handling: Clear error messages with appropriate exception types
• Type Safety: Full type annotations for better development experience
• Connection Validation: Automatic validation of Unimus connectivity at startup
• Comprehensive Documentation: Detailed docstrings for all functions

Requirements

• Python 3.10+
• Unimus 1.7.x or newer (API v.2 support)
• Valid Unimus API token with read permissions

Installation

1. Clone or download this repository
2. Install the package and its dependencies:
   pip install .
   Or using uv (recommended for development):
   uv sync
   For development with optional dependencies:
   pip install .[dev]

Installation

Option 1: Docker (Recommended) 🐳

Quick Start:

With Docker Compose:

📖 Complete Docker guide: DOCKER.md

🩺 Health Monitoring:

• Liveness: http://localhost:8080/healthz - Container alive check
• Readiness: http://localhost:8080/readyz - Service ready check
• Legacy: http://localhost:8080/health - Backward compatibility

Option 2: Python Installation

Already covered above in the initial setup section.

Configuration

Environment Variables

Set the following environment variables:

• UNIMUS_URL: Full URL to your Unimus instance (e.g., https://unimus.example.com)
• UNIMUS_TOKEN: API token from Unimus (Bearer token)

Creating a Unimus API Token

1. Log into your Unimus web interface
2. Navigate to User Management > API Tokens
3. Create a new token with appropriate read permissions
4. Copy the token for use in the UNIMUS_TOKEN environment variable

Usage

Testing the Server

Verify the server can connect to your Unimus instance:

Configuring with LLM Clients

Claude Desktop (macOS)

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

Using uv (recommended)

Windows

Use full, escaped paths:

Example Queries

Once configured, you can use natural language queries with your LLM:

Device Management

Backup Operations

Backup Analysis & Diff (v0.3.0)

Schedule Management (v0.3.0)

Backup Content Search (v0.4.0)

System Health

Advanced Filtering

API Coverage

This implementation covers the core Unimus API endpoints for devices and backups based on the official Unimus API v.2 specification.

📚 IMPORTANT: All development must follow the official Unimus v2 API documentation
This document defines the complete API specification, request/response formats, and available endpoints.

Implemented Endpoints

• GET /api/v2/health - System health check
• GET /api/v2/devices - List devices (with filtering)
• GET /api/v2/devices/{id} - Get device by ID
• GET /api/v2/devices/findByAddress/{address} - Find device by address
• GET /api/v2/devices/findByDescription/{description} - Find devices by description
• GET /api/v2/devices/findByChangedBackup - NEW: Find devices with backup changes in time range
• GET /api/v2/devices/{id}/backups - Get device backups
• GET /api/v2/devices/{id}/backups/latest - Get latest device backup
• GET /api/v2/devices/backups/latest - Get latest backups for multiple devices
• GET /api/v2/backups/diff - NEW: Compare two backup configurations
• GET /api/v2/schedules - NEW: List all backup schedules
• GET /api/v2/schedules/{id} - NEW: Get individual schedule details

Note: Backup content search (unimus_search_backup_content) is implemented client-side since the Unimus API v.2 does not provide native content search endpoints.

Breaking Changes in v0.2.5

Important: This version contains breaking changes for better performance:

• Backup Content Format: The bytes field in backup responses has been replaced with:
  • content: Decoded content (readable text for TEXT backups, base64 for BINARY)
  • content_type: Format indicator ("text" or "base64")

Migration: If you have code that accesses backup["bytes"], change it to backup["content"]

Benefit: Massive performance improvement - no more artifact execution needed for reading configurations!

Performance Considerations

For large device inventories, consider using these optimization strategies:

• Use limit parameters: When searching by description or retrieving devices, use the limit parameter to control result size
• Bulk operations: Use unimus_get_latest_backups() instead of multiple individual calls
• Specific filtering: Apply vendor, type, or zone filters to reduce dataset size
• Targeted queries: Use exact matching when you know the precise description
• Optimized backups: v0.2.5+ automatically decodes TEXT backups for instant readability

⚠️ Important: Device Search Performance

Exact Match Warning: The unimus_get_devices_by_description() function with exact_match=True has specific performance characteristics:

• How it works: Retrieves ALL devices that partially match the description from the API, then filters them in Python
• Why necessary: The Unimus API only supports partial matching, so exact matching requires post-processing
• Performance impact: Can be slow with large device inventories

Best Practices:

Automatic Warnings: The system logs performance warnings when exact_match=True is used without a limit parameter.

Available Filters for Devices

• managed: Boolean (true/false) - Filter by management status
• vendor: String - Filter by vendor name (e.g., "Cisco", "MikroTik")
• type: String - Filter by device type (e.g., "IOS", "RouterOS")
• model: String - Filter by device model
• site_id: Number - Filter by site ID
• zone_id: String - Filter by zone ID
• address: String - Filter by device address
• description: String - Filter by description content

Error Handling

The server provides clear error messages for common issues:

• Authentication Errors: Invalid or expired API tokens
• Not Found Errors: Devices or resources that don't exist
• Validation Errors: Invalid parameters or malformed requests
• Connection Errors: Network connectivity issues

Security Considerations

• Use HTTPS for your Unimus URL in production
• Store API tokens securely (environment variables, not in code)
• Consider using read-only API tokens to limit access scope
• Regularly rotate API tokens according to your security policy

Troubleshooting

Common Issues

1. Connection Failed
   Failed to connect to Unimus at https://unimus.example.com
   • Verify UNIMUS_URL is correct and accessible
   • Check UNIMUS_TOKEN is valid and not expired
   • Ensure network connectivity to Unimus instance
2. Authentication Failed
   Authentication failed: Invalid token
   • Regenerate API token in Unimus
   • Verify token has appropriate read permissions
3. SSL Certificate Issues
   SSL verification failed
   • For development/testing with self-signed certificates, you may need to modify the client to skip SSL verification (not recommended for production)
4. Permission Denied
   API error (403): Insufficient permissions
   • Ensure API token has read access to devices and backups
   • Check user permissions in Unimus

Debug Mode

For debugging, you can increase log verbosity by modifying the logging level in server.py:

Development

Project Structure

Code Quality

The project follows Python best practices:

• Type Hints: Full type annotations throughout
• Error Handling: Comprehensive exception handling with custom exception types
• Documentation: Detailed docstrings for all public methods
• Code Style: Black formatting and flake8 linting (see pyproject.toml)

Dependency Management

Dependencies are managed through pyproject.toml following modern Python packaging standards:

• Production dependencies: Defined in [project.dependencies]
• Development dependencies: Defined in [project.optional-dependencies.dev]
• Dependency pinning: uv.lock file ensures reproducible builds
• Installation: Use pip install . or uv sync for locked dependencies

Development Testing

For testing new features during development:

1. Test Environment Setup:
   # Create local test environment file (excluded from git) cp .env.test.example .env.test # Edit .env.test with your test Unimus credentials
2. Run Test Suite:
   # Load test environment and run comprehensive tests source .env.test python test_functionality.py
3. Manual Testing:
   # Test individual components source .env.test python -c "from unimus_client import UnimusRestClient; client = UnimusRestClient(...)"

Note: Test environment files are excluded from git commits for security.

Contributing

Contributions are welcome! Please:

1. Follow the existing code style and patterns
2. Add appropriate type hints and documentation
3. Test changes against a real Unimus instance using the test framework
4. Update documentation as needed

Roadmap

This is version 0.1.0 focusing on core device and backup functionality. See ROADMAP.md for planned features:

• v0.2.0: Extended device operations and search capabilities
• v0.3.0: Backup analysis and diff operations
• v0.4.0: Schedule management and advanced queries
• v0.5.0: Performance optimizations and advanced features

License

This project is licensed under the MIT License. See the LICENSE file for details.

Compatibility

• Unimus API: Version 2 (Unimus 1.7.x and newer)
• Python: 3.10+
• MCP Protocol: Compatible with MCP 1.3.0+

⚠️ Development Note: This implementation strictly follows the official Unimus API v.2 specification. All features are based on documented endpoints and behaviors in the API documentation.

Support

For issues related to:

• This MCP Server: Open an issue in the project repository
• Unimus API: Consult the official Unimus API documentation
• MCP Protocol: See the Model Context Protocol documentation

Note: This implementation is based on Unimus API v.2 documentation. Always verify compatibility with your specific Unimus version and consult the official API documentation for the most current information.