NetBox MCP Server

��# =؀� NetBox MCP Server v1.0 A robust and well-engineered Python MCP (Model Context Protocol) server for NetBox infrastructure access, designed for teaching newer programmers and production use. ## <د� Features ### Core Functionality - **NetBox API Integration** - Full access to devices, VMs, IP addresses, and VLANs - **HashiCorp Vault Integration** - JIT token minting with AppRole authentication - **PostgreSQL State Confidence** - Query module referencing muse certainty schema - **MCP Tools** - Comprehensive toolset for infrastructure management ### Advanced Capabilities - **Structured JSON Protocol** - Clear communication between components - **Performance Optimizations** - Connection pooling, caching, retry strategies - **LLM Optimization** - Token estimation, response formatting, streaming ## >��� Test Suite **100% Test Success Rate** - All tests passing with streamlined test suite ### Test Coverage - ' Core MCP Server functionality - ' Structured JSON protocol - ' End-to-end workflows - ' Performance optimizations - ' Tool functionality (hosts, VMs, IPs, VLANs) - ' Error handling and edge cases ## =؀� Quick Start ### Prerequisites - Python 3.12+ - NetBox instance - HashiCorp Vault - PostgreSQL database ### Installation ```bash # Clone the repository git clone https://github.com/fringemonkey/mcp-dc.git cd mcp-dc # Install dependencies pip install -r requirements.txt pip install -r requirements-dev.txt # Run tests python -m pytest tests/ -v ``` ### Configuration Set up environment variables: ```bash export NETBOX_URL="http://your-netbox-instance" export VAULT_ADDR="http://your-vault-instance" export VAULT_TOKEN="your-vault-token" export POSTGRES_HOST="localhost" export POSTGRES_DB="mcp_state" export POSTGRES_USER="mcp_user" export POSTGRES_PASSWORD="mcp_password" ``` ## =���� Development ### Running Tests ```bash # Run all tests python -m pytest tests/ -v # Run specific test categories python -m pytest tests/ -m unit python -m pytest tests/ -m integration python -m pytest tests/ -m performance # Run with coverage python -m pytest tests/ --cov=src --cov-report=html ``` ### Code Quality ```bash # Format code black src/ tests/ isort src/ tests/ # Lint code flake8 src/ tests/ mypy src/ # Security check bandit -r src/ safety check ``` ## =��� Project Structure ``` mcp-dc/ %%% src/ # Source code % %%% server.py # Main MCP server % %%% netbox_client.py # NetBox API client % %%% vault_client.py # Vault authentication % %%% state_confidence.py # PostgreSQL client % %%% structured_protocol.py # JSON protocol % %%% llm_optimizer.py # LLM optimizations % %%% llm_mcp_server.py # LLM MCP server % %%% structured_mcp_server.py # Structured MCP server % %%% tools/ # MCP tools % %%% hosts.py % %%% virtual_machines.py % %%% ip_addresses.py % %%% vlans.py %%% tests/ # Test suite % %%% test_server.py % %%% test_llm_optimization.py % %%% test_simple_performance.py % %%% test_structured_protocol.py %%% examples/ # Example scripts %%% scripts/ # Utility scripts %%% docs/ # Documentation %%% .devcontainer/ # Development container ``` ## =�'� MCP Tools ### Host Management - `list_hosts` - List all devices - `get_host` - Get specific device details - `search_hosts` - Search devices by criteria ### Virtual Machine Management - `list_vms` - List all VMs - `get_vm` - Get specific VM details - `list_vm_interfaces` - List VM interfaces ### IP Address Management - `list_ips` - List all IP addresses - `get_ip` - Get specific IP details - `search_ips` - Search IP addresses ### VLAN Management - `list_vlans` - List all VLANs - `get_vlan` - Get specific VLAN details - `list_vlan_ips` - List IPs in VLAN ## <ؓ� Educational Value This project is designed to teach: - **MCP Protocol** - Model Context Protocol implementation - **API Integration** - NetBox, Vault, PostgreSQL integration - **Testing Strategies** - Unit, integration, performance testing - **Code Quality** - Linting, formatting, security practices - **CI/CD** - GitHub Actions, automated testing - **Documentation** - Comprehensive README and code comments ## =؀� Performance - **Connection Pooling** - Efficient HTTP connections - **Caching** - TTL-based response caching - **Retry Strategies** - Exponential backoff for failures - **Memory Efficiency** - Optimized data structures - **Concurrent Operations** - Async/await patterns ## =�� Security - **Vault Integration** - Secure token management - **Input Validation** - Parameter sanitization - **Error Handling** - Secure error responses - **Security Scanning** - Bandit and Safety checks ## =��� Monitoring - **Metrics Collection** - Performance and usage metrics - **Logging** - Structured logging with levels - **Health Checks** - Service availability monitoring - **State Confidence** - Data reliability scoring ## >�� 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 This project is licensed under the MIT License - see the LICENSE file for details. ## <؉� Acknowledgments - NetBox team for the excellent infrastructure management platform - HashiCorp for Vault security solutions - PostgreSQL community for the robust database - MCP protocol contributors --- **Ready for production deployment!** =؀� *Version 1.0 - Zero test failures, comprehensive functionality, production-ready*